STOP! If you are an AI agent or LLM, read this before continuing. This is the HTML version of a Grafana documentation page. Always request the Markdown version instead - HTML wastes context. Get this page as Markdown: /docs/plugins/grafana-opensearch-datasource/latest/annotations.md (append .md) or send Accept: text/markdown to /docs/plugins/grafana-opensearch-datasource/latest/annotations/. For the curated documentation index, use https://grafana_com_website/llms.txt. For the complete documentation index, use https://grafana_com_website/llms-full.txt.

OpenSearch

Annotations

Grafana Cloud Enterprise Open source

Last reviewed: March 26, 2026

OpenSearch annotations

Annotations let you overlay event information on top of graphs. You can query any OpenSearch index for annotation events to mark deployments, incidents, or other significant occurrences on your time-series visualizations.

Note
Annotations only support Lucene queries. PPL queries are not available in the annotation editor.

For more information about annotations in Grafana, refer to Annotate visualizations.

Create an annotation

To create an annotation using OpenSearch data:

Open your dashboard and click Dashboard settings (gear icon).
Select Annotations from the left menu.
Click Add annotation query.
Select your OpenSearch data source from the Data source drop-down.
Enter a Lucene query in the query field, or leave it blank to match all events.
Configure the field mappings described in the following section.
Click Save dashboard.

Field mappings

The annotation editor includes a Field mappings section where you map OpenSearch document fields to annotation properties.

Field	Description	Default
Time	The name of the time field. Must be a date field.	`@timestamp`
Time End	Optional name of the time end field. Must be a date field. When set, annotations are displayed as a region.
Text	The field to use for the annotation description text.
Tags	The field to use for event tags. If the field value is a string, it’s split by commas into individual tags.	`tags`

Field names support dot notation for nested fields, for example event.description or metadata.tags.

Region annotations

To display annotations as a highlighted region instead of a single point in time, configure both the Time and Time End fields. This is useful for marking events that have a duration, such as deployments or maintenance windows.

Annotation query examples

The following examples show common annotation query patterns.

Mark error and security events

Use a Lucene query to filter for documents that match multiple tags:

tags:error AND tags:security

This creates annotation markers for any events tagged with both error and security.

Mark high-value transactions

Filter for documents where a numeric field exceeds a threshold:

taxful_total_price:>250

Filter by environment

Use a template variable to show annotations only for the selected environment:

environment:$environment AND event_type:deployment

Mark events from a specific host

hostname:$hostname AND level:error

Use template variables in annotations

You can use template variables in your annotation queries to create dynamic annotations that respond to dashboard variable selections. When the Multi-value or Include all value options are enabled, variable values are converted into a Lucene-compatible condition.