Elasticsearch data source on Grafana Labs

Configure the Elasticsearch data source

Fri, 03 Apr 2026 19:43:06 +0000

Configure the Elasticsearch data source

Grafana ships with built-in support for Elasticsearch. You can create a variety of queries to visualize logs or metrics stored in Elasticsearch, and annotate graphs with log events stored in Elasticsearch.

For instructions on how to add a data source to Grafana, refer to the administration documentation. Administrators can also configure the data source via YAML with Grafana’s provisioning system.

Before you begin

To configure the Elasticsearch data source, you need:

Grafana administrator permissions: Only users with the organization administrator role can add data sources.
A supported Elasticsearch version: v7.17 or later, v8.x, v9.x or Elastic Cloud Serverless.
Elasticsearch server URL: The HTTP or HTTPS endpoint for your Elasticsearch instance, including the port (default: 9200).
Authentication credentials: Depending on your Elasticsearch security configuration, you need one of the following:
- Username and password for basic authentication
- API key
- No credentials (if Elasticsearch security is disabled)
Network access: Grafana must be able to reach your Elasticsearch server. For Grafana Cloud, consider using Private data source connect (PDC) if your Elasticsearch instance is in a private network.

Elasticsearch permissions

When Elasticsearch security features are enabled, you must configure the following cluster privileges for the user or API key that Grafana uses to connect:

monitor - Necessary to retrieve the version information of the connected Elasticsearch instance.
view_index_metadata - Required for accessing mapping definitions of indices.
read - Grants the ability to perform search and retrieval operations on indices. This is essential for querying and extracting data from the cluster.

Add the data source

To add the Elasticsearch data source, complete the following steps:

Click Connections in the left-side menu.
Under Connections, click Add new connection.
Enter Elasticsearch in the search bar.
Click Elasticsearch under the Data source section.
Click Add new data source in the upper right.

You will be taken to the Settings tab where you will set up your Elasticsearch configuration.

Configuration options

Configure the following basic settings for the Elasticsearch data source:

Name - The data source name. This is how you refer to the data source in panels and queries. Examples: elastic-1, elasticsearch_metrics.
Default - Toggle on to make this the default data source. New panels and Explore queries use the default data source.

Connection

URL - The URL of your Elasticsearch server, including the port. Examples: http://localhost:9200, http://elasticsearch.example.com:9200.

Authentication

Select an authentication method from the drop-down menu:

Basic authentication - Enter the username and password for your Elasticsearch user.
Forward OAuth identity - Forward the OAuth access token (and the OIDC ID token if available) of the user querying the data source.
No authentication - Connect without credentials. Only use this option if your Elasticsearch instance doesn’t require authentication.

API key authentication

To authenticate using an Elasticsearch API key, select No authentication and configure the API key using HTTP headers:

In the HTTP headers section, click + Add header.
Set Header to Authorization.
Set Value to ApiKey <your-api-key>, replacing <your-api-key> with your base64-encoded Elasticsearch API key.

For information about creating API keys, refer to the Elasticsearch API keys documentation.

Amazon Elasticsearch Service

If you use Amazon Elasticsearch Service, you can use Grafana’s Elasticsearch data source to visualize data from it.

If you use an AWS Identity and Access Management (IAM) policy to control access to your Amazon Elasticsearch Service domain, you must use AWS Signature Version 4 (AWS SigV4) to sign all requests to that domain.

For details on AWS SigV4, refer to the AWS documentation.

To sign requests to your Amazon Elasticsearch Service domain, you can enable SigV4 in Grafana’s configuration.

Once AWS SigV4 is enabled, you can configure it on the Elasticsearch data source configuration page. For more information about AWS authentication options, refer to AWS authentication.

TLS settings

Note
Use TLS (Transport Layer Security) for an additional layer of security when working with Elasticsearch. For information on setting up TLS encryption with Elasticsearch, refer to Configure TLS. You must add TLS settings to your Elasticsearch configuration file prior to setting these options in Grafana.

Add self-signed certificate - Check the box to authenticate with a CA certificate. Follow the instructions of the CA (Certificate Authority) to download the certificate file. Required for verifying self-signed TLS certificates.
TLS client authentication - Check the box to authenticate with the TLS client, where the server authenticates the client. Add the Server name, Client certificate and Client key. The ServerName is used to verify the hostname on the returned certificate. The Client certificate can be generated from a Certificate Authority (CA) or be self-signed. The Client key can also be generated from a Certificate Authority (CA) or be self-signed. The client key encrypts the data between client and server.
Skip TLS certificate validation - Check the box to bypass TLS certificate validation. Skipping TLS certificate validation is not recommended unless absolutely necessary or for testing purposes.

HTTP headers

Click + Add header to add one or more HTTP headers. HTTP headers pass additional context and metadata about the request/response.

Header - Add a custom header. This allows custom headers to be passed based on the needs of your Elasticsearch instance.
Value - The value of the header.

Additional settings

Additional settings are optional settings that can be configured for more control over your data source.

Advanced HTTP settings

Allowed cookies - Specify cookies by name that should be forwarded to the data source. The Grafana proxy deletes all forwarded cookies by default.
Timeout - The HTTP request timeout. This must be in seconds. There is no default, so this setting is up to you.

Elasticsearch details

The following settings are specific to the Elasticsearch data source.

Index name - The name of your Elasticsearch index. You can use the following formats:
- Wildcard patterns - Use * to match multiple indices. Examples: logs-*, metrics-*, filebeat-*.
- Time patterns - Use date placeholders for time-based indices. Wrap the fixed portion in square brackets. Examples: [logstash-]YYYY.MM.DD, [metrics-]YYYY.MM.
- Specific index - Enter the exact index name. Example: application-logs.
Pattern - Select the matching pattern if you use a time pattern in your index name. Options include:
- no pattern
- hourly
- daily
- weekly
- monthly
- yearly

Only select a pattern option if you have specified a time pattern in the Index name field.

Time field name - Name of the time field. The default value is @timestamp. You can enter a different name.
Max concurrent shard requests - Sets the number of shards being queried at the same time. The default is 5. For more information on shards, refer to the Elasticsearch documentation.

Min time interval - Defines a lower limit for the auto group-by time interval. This value must be formatted as a number followed by a valid time identifier:

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

We recommend setting this value to match your Elasticsearch write frequency. For example, set this to 1m if Elasticsearch writes data every minute.

You can also override this setting in a dashboard panel under its data source options. The default is 10s.

X-Pack enabled - Toggle to enable X-Pack-specific features and options, which provide the query editor with additional aggregations, such as Rate and Top Metrics.
Include frozen indices - Toggle on when the X-Pack enabled setting is active. Includes frozen indices in searches. You can configure Grafana to include frozen indices when performing search requests.

Note
Frozen indices are deprecated in Elasticsearch since v7.14.

Logs

Configure which fields the data source uses for log messages and log levels.

Message field name - The field that contains the log message content.
Level field name - The field that contains log level or severity information. When specified, Grafana uses this field to determine the log level and color-code each log line. If the log doesn’t have a level field, Grafana tries to match the content against supported expressions. If Grafana can’t determine the log level, it displays as unknown.

Data links

Data links create a link from a specified field that can be accessed in Explore’s logs view. You can add multiple data links by clicking + Add.

Each data link configuration consists of:

Field - Sets the name of the field used by the data link.
URL/query - Sets the full link URL if the link is external. If the link is internal, this input serves as a query for the target data source.
In both cases, you can interpolate the value from the field with the ${__value.raw } macro.
URL Label (Optional) - Sets a custom display label for the link. The link label defaults to the full external URL or name of the linked internal data source and is overridden by this setting.
Internal link - Toggle on to set an internal link. For an internal link, you can select the target data source with a data source selector. This supports only tracing data sources.

Private data source connect (PDC) and Elasticsearch

Use private data source connect (PDC) to connect to and query data within a secure network without opening that network to inbound traffic from Grafana Cloud. Refer to Private data source connect for more information on how PDC works and Configure Grafana private data source connect (PDC) for steps on setting up a PDC connection.

If you use PDC with SigV4 (AWS Signature Version 4 Authentication), the PDC agent must allow internet egress to sts.<region>.amazonaws.com:443.

Private data source connect - Click in the box to set the default PDC connection from the drop-down menu or create a new connection.

Once you have configured your Elasticsearch data source options, click Save & test to test the connection. A successful connection displays the following message:

Elasticsearch data source is healthy.

Provision the data source

You can define and configure the data source in YAML files as part of Grafana’s provisioning system. For more information about provisioning, and for available configuration options, refer to Provisioning Grafana.

Note
The previously used database field has now been deprecated. Use the index field in jsonData to store the index name. Refer to the examples below.

Basic provisioning

apiVersion: 1

datasources:
  - name: Elastic
    type: elasticsearch
    access: proxy
    url: http://localhost:9200
    jsonData:
      index: '[metrics-]YYYY.MM.DD'
      interval: Daily
      timeField: '@timestamp'

Provision for logs

apiVersion: 1

datasources:
  - name: elasticsearch-v7-filebeat
    type: elasticsearch
    access: proxy
    url: http://localhost:9200
    jsonData:
      index: '[filebeat-]YYYY.MM.DD'
      interval: Daily
      timeField: '@timestamp'
      logMessageField: message
      logLevelField: fields.level
      dataLinks:
        - datasourceUid: my_jaeger_uid # Target UID needs to be known
          field: traceID
          url: '$${__value.raw}' # Careful about the double "$$" because of env var expansion

Provision the data source using Terraform

You can provision the Elasticsearch data source using Terraform with the Grafana Terraform provider.

For more information about provisioning resources with Terraform, refer to the Grafana as code using Terraform documentation.

Basic Terraform example

The following example creates a basic Elasticsearch data source for metrics:

resource "grafana_data_source" "elasticsearch" {
  name = "Elasticsearch"
  type = "elasticsearch"
  url  = "http://localhost:9200"

  json_data_encoded = jsonencode({
    index     = "[metrics-]YYYY.MM.DD"
    interval  = "Daily"
    timeField = "@timestamp"
  })
}

Terraform example for logs

The following example creates an Elasticsearch data source configured for logs with a data link to Jaeger:

resource "grafana_data_source" "elasticsearch_logs" {
  name = "Elasticsearch Logs"
  type = "elasticsearch"
  url  = "http://localhost:9200"

  json_data_encoded = jsonencode({
    index           = "[filebeat-]YYYY.MM.DD"
    interval        = "Daily"
    timeField       = "@timestamp"
    logMessageField = "message"
    logLevelField   = "fields.level"
    dataLinks = [
      {
        datasourceUid = grafana_data_source.jaeger.uid
        field         = "traceID"
        url           = "$${__value.raw}"
      }
    ]
  })
}

Terraform example with basic authentication

The following example includes basic authentication:

resource "grafana_data_source" "elasticsearch_auth" {
  name = "Elasticsearch"
  type = "elasticsearch"
  url  = "http://localhost:9200"

  basic_auth_enabled  = true
  basic_auth_username = "elastic_user"

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = var.elasticsearch_password
  })

  json_data_encoded = jsonencode({
    index     = "[metrics-]YYYY.MM.DD"
    interval  = "Daily"
    timeField = "@timestamp"
  })
}

For all available configuration options, refer to the Grafana provider data source resource documentation.

Elasticsearch query editor

Fri, 03 Apr 2026 19:43:06 +0000

Elasticsearch query editor

Grafana provides a query editor for Elasticsearch. Elasticsearch queries are in Lucene format. For more information about query syntax, refer to Lucene query syntax and Query string syntax.

Note
When composing Lucene queries, ensure that you use uppercase boolean operators: AND, OR, and NOT. Lowercase versions of these operators are not supported by the Lucene query syntax.

For general documentation on querying data sources in Grafana, including options and functions common to all query editors, refer to Query and transform data.

Aggregation types

Elasticsearch groups aggregations into three categories:

Bucket - Bucket aggregations don’t calculate metrics, they create buckets of documents based on field values, ranges and a variety of other criteria. Refer to Bucket aggregations for additional information. Use bucket aggregations under Group by when creating a metrics query in the query builder.
Metrics - Metrics aggregations perform calculations such as sum, average, min, etc. They can be single-value or multi-value. Refer to Metrics aggregations for additional information. Use metrics aggregations in the metrics query type in the query builder.
Pipeline - Pipeline aggregations work on the output of other aggregations rather than on documents or fields. Refer to Pipeline aggregations for additional information.

Select a query type

There are three types of queries you can create with the Elasticsearch query builder. Each type is explained in detail below.

Metrics query type

Metrics queries aggregate data and produce calculations such as count, min, max, and more. Click the metric box to view options in the drop-down menu. The default is count.

Alias - Aliasing only applies to time series queries, where the last group is date histogram. This is ignored for any other type of query.
Metric - Metrics aggregations include:
- count - refer to Value count aggregation
- average - refer to Avg aggregation
- sum - refer to Sum aggregation
- max - refer to Max aggregation
- min - refer to Min aggregation
- extended stats - refer to Extended stats aggregation
- percentiles - refer to Percentiles aggregation
- unique count - refer to Cardinality aggregation
- top metrics - refer to Top metrics aggregation
- rate - refer to Rate aggregation
Pipeline aggregations - Pipeline aggregations work on the output of other aggregations rather than on documents. The following pipeline aggregations are available:
- moving function - Calculates a value based on a sliding window of aggregated values. Refer to Moving function aggregation.
- derivative - Calculates the derivative of a metric. Refer to Derivative aggregation.
- cumulative sum - Calculates the cumulative sum of a metric. Refer to Cumulative sum aggregation.
- serial difference - Calculates the difference between values in a time series. Refer to Serial differencing aggregation.
- bucket script - Executes a script on metric values from other aggregations. Refer to Bucket script aggregation.

You can select multiple metrics and group by multiple terms or filters when using the Elasticsearch query editor.

Use the + sign to the right to add multiple metrics to your query. Click on the eye icon next to Metric to hide metrics, and the garbage can icon to remove metrics.

Group by options - Create multiple group by options when constructing your Elasticsearch query. Date histogram is the default option. The following options are available in the drop-down menu:
- terms - refer to Terms aggregation.
- filter - refer to Filter aggregation.
- geo hash grid - refer to Geohash grid aggregation.
- date histogram - for time series queries. Refer to Date histogram aggregation.
- histogram - Depicts frequency distributions. Refer to Histogram aggregation.
- nested (experimental) - Refer to Nested aggregation.

Each group by option will have a different subset of options to further narrow your query.

The following options are specific to the date histogram bucket aggregation option.

Time field - The field used for time-based queries. The default can be set when configuring the data source in the Time field name setting under Elasticsearch details. The default is @timestamp.
Interval - The time interval for grouping data. Select from the drop-down menu or enter a custom interval such as 30d (30 days). The default is Auto.
Min doc count - The minimum number of documents required to include a bucket. The default is 0.
Trim edges - Removes partial buckets at the edges of the time range. The default is 0.
Offset - Shifts the start of each bucket by the specified duration. Use positive (+) or negative (-) values. Examples: 1h, 5s, 1d.
Timezone - The timezone for date calculations. The default is Coordinated Universal Time.

Configure the following options for the terms bucket aggregation option:

Order - Sets the order of data. Options are top or bottom.
Size - Limits the number of documents, or size of the data set. You can set a custom number or no limit.
Min doc count - The minimum amount of data to include in your query. The default is 0.
Order by - Order terms by term value, doc count or count.
Missing - Defines how documents missing a value should be treated. Missing values are ignored by default, but they can be treated as if they had a value. Refer to Missing value in the Elasticsearch documentation for more information.

Configure the following options for the filters bucket aggregation option:

Query - Specify the query to create a bucket of documents (data). Examples are hostname:"hostname1", product:"widget5". Use the * wildcard to match any number of characters.
Label - Add a label or name to the bucket.

Configure the following options for the geo hash grid bucket aggregation option:

Precision - Specifies the number of characters of the geo hash.

Configure the following options for the histogram bucket aggregation option:

Interval - The numeric interval for grouping values into buckets.
Min doc count - The minimum number of documents required to include a bucket. The default is 0.

The nested group by option is currently experimental, you can select a field and then settings specific to that field.

Click the + sign to add multiple group by options. The data will grouped in order (first by, then by).

Logs query type

Logs queries analyze Elasticsearch log data. You can configure the following options:

Logs Options/Limit - Limits the number of logs to analyze. The default is 500.

Raw data query type

Run a raw data query to retrieve a table of all fields that are associated with each log line.

Raw data size - Number of raw data documents. You can specify a different amount. The default is 500.

Note
The option to run a raw document query is deprecated as of Grafana v10.1.

Raw query editor

Note
The raw query editor is an experimental feature that must be enabled using the elasticsearchRawDSLQuery feature toggle.

The raw query editor allows you to write Elasticsearch queries using the native Elasticsearch Query DSL.

Switch between Builder and Code modes

To access the raw query editor, click the Code toggle in the top-right corner of the query editor. You can switch between Builder and Code modes:

Builder - Visual query builder with dropdown menus and forms
Code - JSON editor for writing raw Elasticsearch DSL queries

Write raw DSL queries

When in Code mode, you can write complete Elasticsearch query DSL in JSON format. The editor provides:

Syntax highlighting for JSON
Auto-formatting - Click the Format button or press Shift+Alt+F to format your query
Keyboard shortcuts - Press Ctrl+Enter (or Cmd+Enter on Mac) to run the query
Real-time validation - Invalid JSON will be highlighted with error messages

Time range handling

If you want to filter by time range in a dashboard, you need to use the $__from and $__to macros in your raw DSL.

An example query applying dashboard time range using the @timestamp field:

{
  "query": {
    "bool": {
      "must": [
        {
          "range": {
            "@timestamp": {
              "gte": "$__from",
              "lte": "$__to",
              "format": "epoch_millis"
            }
          }
        }
      ]
    }
  }
}

Supported query types

The raw query editor supports all query types:

Metrics queries are used to query time series data with aggregations. The query parser will automatically extract bucket and metric aggregations from your DSL and use them for response processing.
Logs queries are used to query log data.
Raw data queries are used for document-level data retrieval.

Use template variables

You can also augment queries by using template variables.

Queries of terms have a 500-result limit by default. To set a custom limit, set the size property in your query.

Elasticsearch template variables

Fri, 03 Apr 2026 19:43:06 +0000

Elasticsearch template variables

Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana lists these variables in drop-down select boxes at the top of the dashboard to help you change the data displayed in your dashboard. Grafana refers to such variables as template variables.

For an introduction to templating and template variables, refer to the Templating and Add and manage variables documentation.

Use ad hoc filters

Elasticsearch supports the Ad hoc filters variable type. You can use this variable type to specify any number of key/value filters, and Grafana applies them automatically to all of your Elasticsearch queries.

Ad hoc filters support the following operators:

Operator	Description
`=`	Equals. Adds `AND field:"value"` to the query.
`!=`	Not equals. Adds `AND -field:"value"` to the query.
`=~`	Matches regex. Adds `AND field:/value/` to the query.
`!~`	Does not match regex. Adds `AND -field:/value/` to the query.
`>`	Greater than. Adds `AND field:>value` to the query.
`<`	Less than. Adds `AND field:<value` to the query.

For more information, refer to Add ad hoc filters.

Choose a variable syntax

The Elasticsearch data source supports two variable syntaxes for use in the Query field:

$varname, such as hostname:$hostname, which is easy to read and write but doesn’t let you use a variable in the middle of a word.
[[varname]], such as hostname:[[hostname]]

When the Multi-value or Include all value options are enabled, Grafana converts the labels from plain text to a Lucene-compatible condition. For details, refer to the Multi-value variables documentation.

Use variables in queries

You can use variables in the Lucene query field, metric aggregation fields, bucket aggregation fields, and the alias field.

Variables in Lucene queries

Use variables to filter your Elasticsearch queries dynamically:

hostname:$hostname AND level:$level

Chain or nest variables

You can create nested variables, where one variable’s values depend on another variable’s selection.

This example defines a variable named $host that only shows hosts matching the selected $environment:

{ "find": "terms", "field": "hostname", "query": "environment:$environment" }

Whenever you change the value of the $environment variable via the drop-down, Grafana triggers an update of the $host variable to contain only hostnames filtered by the selected environment.

Variables in aggregations

You can use variables in bucket aggregation fields to dynamically change how data is grouped. For example, use a variable in the Terms group by field to let users switch between grouping by hostname, service, or datacenter.

Template variable examples

In the above example, a Lucene query filters documents based on the hostname property using a variable named $hostname. The example also uses a variable in the Terms group by field input box, which you can use to quickly change how data is grouped.

Create a query

Write the query using a custom JSON string, with the field mapped as a keyword in the Elasticsearch index mapping.

If the query is multi-field with both a text and keyword type, use "field":"fieldname.keyword" (sometimes fieldname.raw) to specify the keyword field in your query.

Query	Description
`{"find": "fields", "type": "keyword"}`	Returns a list of field names with the index type `keyword`.
`{"find": "fields", "type": "number"}`	Returns a list of numeric field names (includes `float`, `double`, `integer`, `long`, `scaled_float`).
`{"find": "fields", "type": "date"}`	Returns a list of date field names.
`{"find": "terms", "field": "hostname.keyword", "size": 1000}`	Returns a list of values for a keyword field. Uses the current dashboard time range.
`{"find": "terms", "field": "hostname", "query": "<Lucene query>"}`	Returns a list of values filtered by a Lucene query. Uses the current dashboard time range.
`{"find": "terms", "field": "status", "orderBy": "doc_count"}`	Returns values sorted by document count (descending by default).
`{"find": "terms", "field": "status", "orderBy": "doc_count", "order": "asc"}`	Returns values sorted by document count in ascending order.

Queries of terms have a 500-result limit by default. To set a custom limit, set the size property in your query.

Sort query results

By default, queries return results in term order (which can then be sorted alphabetically or numerically using the variable’s Sort setting).

To produce a list of terms sorted by document count (a top-N values list), add an orderBy property of doc_count. This automatically selects a descending sort:

{ "find": "terms", "field": "status", "orderBy": "doc_count" }

You can also use the order property to explicitly set ascending or descending sort:

{ "find": "terms", "field": "hostname", "orderBy": "doc_count", "order": "asc" }

Note
Elasticsearch discourages sorting by ascending doc count because it can return inaccurate results.

To keep terms in the document count order, set the variable’s Sort drop-down to Disabled. You can alternatively use other sorting criteria, such as Alphabetical, to re-sort them.

Elasticsearch annotations

Fri, 03 Apr 2026 19:43:06 +0000

Elasticsearch annotations

Annotations overlay event data on your dashboard graphs, helping you correlate log events with metrics. You can use Elasticsearch as a data source for annotations to display events such as deployments, alerts, or other significant occurrences on your visualizations.

For general information about annotations, refer to Annotate visualizations.

Before you begin

Before creating Elasticsearch annotations, ensure you have:

An Elasticsearch data source configured in Grafana
Documents in Elasticsearch containing event data with timestamp fields
Read access to the Elasticsearch index containing your events

Create an annotation query

To add an Elasticsearch annotation to your dashboard:

Navigate to your dashboard and click Dashboard settings (gear icon).
Select Annotations in the left menu.
Click Add annotation query.
Enter a Name for the annotation.
Select your Elasticsearch data source from the Data source drop-down.
Configure the annotation query and field mappings.
Click Save dashboard.

Query

Use the query field to filter which Elasticsearch documents appear as annotations. The query uses Lucene query syntax.

Examples:

Query	Description
`*`	Matches all documents.
`type:deployment`	Shows only deployment events.
`level:error OR level:critical`	Shows error and critical events.
`service:api AND environment:production`	Shows events for a specific service and environment.
`tags:release`	Shows events tagged as releases.

You can use template variables in your annotation queries. For example, service:$service filters annotations based on the selected service variable.

Field mappings

Field mappings tell Grafana which Elasticsearch fields contain the annotation data.

Time

The Time field specifies which field contains the annotation timestamp.

Default: @timestamp
Format: The field must contain a date value that Elasticsearch recognizes.

Time End

The Time End field specifies a field containing the end time for range annotations. Range annotations display as a shaded region on the graph instead of a single vertical line.

Default: Empty (single-point annotations)
Use case: Display maintenance windows, incidents, or any event with a duration.

Text

The Text field specifies which field contains the annotation description displayed when you hover over the annotation.

Default: tags
Tip: Use a descriptive field like message, description, or summary.

Example: Deployment annotations

To display deployment events as annotations:

Create an annotation query with the following settings:
- Query: type:deployment
- Time: @timestamp
- Text: message
- Tags: environment

This configuration displays deployment events with their messages as the annotation text and environments as tags.

Example: Range annotations for incidents

To display incidents with duration:

Create an annotation query with the following settings:
- Query: type:incident
- Time: start_time
- Time End: end_time
- Text: description
- Tags: severity

This configuration displays incidents as shaded regions from their start time to end time.

Elasticsearch alerting

Fri, 03 Apr 2026 19:43:06 +0000

Elasticsearch alerting

You can use Grafana Alerting with Elasticsearch to create alerts based on your Elasticsearch data. This allows you to monitor metrics, detect anomalies, and receive notifications when specific conditions are met.

For general information about Grafana Alerting, refer to Grafana Alerting.

Before you begin

Before creating alerts with Elasticsearch, ensure you have:

An Elasticsearch data source configured in Grafana
Appropriate permissions to create alert rules
Understanding of the metrics you want to monitor

Supported query types

Elasticsearch alerting works best with metrics queries that return time series data. To create a valid alert query:

Use a Date histogram as the last bucket aggregation (under Group by)
Select appropriate metric aggregations (Count, Average, Sum, Min, Max, etc.)

Queries that return time series data allow Grafana to evaluate values over time and trigger alerts when thresholds are crossed.

Query types and alerting compatibility

Query type	Alerting support	Notes
Metrics with Date histogram	✅ Full support	Recommended for alerting
Metrics without Date histogram	⚠️ Limited	May not evaluate correctly over time
Logs	❌ Not supported	Use metrics queries instead
Raw data	❌ Not supported	Use metrics queries instead
Raw document (deprecated)	❌ Not supported	Deprecated since Grafana v10.1. Use metrics queries instead

Create an alert rule

To create an alert rule using Elasticsearch:

Navigate to Alerting > Alert rules.
Click New alert rule.
Enter a name for the alert rule.
Select your Elasticsearch data source.
Build your query using the query editor:
- Add metric aggregations (for example, Average, Count, Sum)
- Add a Date histogram under Group by
- Optionally add filters using Lucene query syntax
Configure the alert condition (for example, when the average is above a threshold).
Set the evaluation interval and pending period.
Configure notifications and labels.
Click Save rule.

For detailed instructions, refer to Create a Grafana-managed alert rule.

Example alert queries

The following examples show common alerting scenarios with Elasticsearch.

Alert on high error count

Monitor the number of error-level log entries:

Query: level:error
Metric: Count
Group by: Date histogram (interval: 1m)
Condition: When count is above 100

Alert on average response time

Monitor API response times:

Query: type:api_request
Metric: Average on field response_time
Group by: Date histogram (interval: 5m)
Condition: When average is above 500 (milliseconds)

Alert on unique user count drop

Detect drops in active users:

Query: * (all documents)
Metric: Unique count on field user_id
Group by: Date histogram (interval: 1h)
Condition: When unique count is below 100

Limitations

When using Elasticsearch with Grafana Alerting, be aware of the following limitations:

Template variables not supported

Alert queries cannot contain template variables. Grafana evaluates alert rules on the backend without dashboard context, so variables like $hostname or $environment won’t be resolved.

If your dashboard query uses template variables, create a separate query for alerting with hard coded values.

Logs queries not supported

Queries using the Logs metric type cannot be used for alerting. Convert your query to use metric aggregations with a Date histogram instead.

Query complexity

Complex queries with many nested aggregations may timeout or fail to evaluate. Simplify queries for alerting by:

Reducing the number of bucket aggregations
Using appropriate time intervals
Adding filters to limit the data scanned

Best practices

Follow these best practices when creating Elasticsearch alerts:

Use specific filters: Add Lucene query filters to focus on relevant data and improve query performance.
Choose appropriate intervals: Match the Date histogram interval to your evaluation frequency.
Test queries first: Verify your query returns expected results in Explore before creating an alert.
Set realistic thresholds: Base alert thresholds on historical data patterns.
Use meaningful names: Give alert rules descriptive names that indicate what they monitor.

Troubleshoot issues with the Elasticsearch data source

Fri, 03 Apr 2026 19:43:06 +0000

Troubleshoot issues with the Elasticsearch data source

This document provides troubleshooting information for common errors you may encounter when using the Elasticsearch data source in Grafana.

Connection errors

The following errors occur when Grafana cannot establish or maintain a connection to Elasticsearch.

Failed to connect to Elasticsearch

Error message: “Health check failed: Failed to connect to Elasticsearch”

Cause: Grafana cannot establish a network connection to the Elasticsearch server.

Solution:

Verify that the Elasticsearch URL is correct in the data source configuration.
Check that Elasticsearch is running and accessible from the Grafana server.
Ensure there are no firewall rules blocking the connection.
If using a proxy, verify the proxy settings are correct.
For Grafana Cloud, ensure you have configured Private data source connect if your Elasticsearch instance is not publicly accessible.

Request timed out

Error message: “Health check failed: Elasticsearch data source is not healthy. Request timed out”

Cause: The connection to Elasticsearch timed out before receiving a response.

Solution:

Check the network latency between Grafana and Elasticsearch.
Verify that Elasticsearch is not overloaded or experiencing performance issues.
Increase the timeout setting in the data source configuration if needed.
Check if any network devices (load balancers, proxies) are timing out the connection.

Failed to parse data source URL

Error message: “Failed to parse data source URL”

Cause: The URL entered in the data source configuration is not valid.

Solution:

Verify the URL format is correct (for example, http://localhost:9200 or https://elasticsearch.example.com:9200).
Ensure the URL includes the protocol (http:// or https://).
Remove any trailing slashes or invalid characters from the URL.

Authentication errors

The following errors occur when there are issues with authentication credentials or permissions.

Unauthorized (401)

Error message: “Health check failed: Elasticsearch data source is not healthy. Status: 401 Unauthorized”

Cause: The authentication credentials are invalid or missing.

Solution:

Verify that the username and password are correct.
If using an API key, ensure the key is valid and has not expired.
Check that the authentication method selected matches your Elasticsearch configuration.
Verify the user has the required permissions to access the Elasticsearch cluster.

Forbidden (403)

Error message: “Health check failed: Elasticsearch data source is not healthy. Status: 403 Forbidden”

Cause: The authenticated user does not have permission to access the requested resource.

Solution:

Verify the user has read access to the specified index.
Check Elasticsearch security settings and role mappings.
Ensure the user has permission to access the _cluster/health endpoint.
If using AWS Elasticsearch Service with SigV4 authentication, verify the IAM policy grants the required permissions.

Cluster health errors

The following errors occur when the Elasticsearch cluster is unhealthy or unavailable.

Cluster status is red

Error message: “Health check failed: Elasticsearch data source is not healthy”

Cause: The Elasticsearch cluster health status is red, indicating one or more primary shards are not allocated.

Solution:

Check the Elasticsearch cluster health using GET /_cluster/health.
Review Elasticsearch logs for errors.
Verify all nodes in the cluster are running and connected.
Check for unassigned shards using GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason.
Consider increasing the cluster’s resources or reducing the number of shards.

Bad Gateway (502)

Error message: “Health check failed: Elasticsearch data source is not healthy. Status: 502 Bad Gateway”

Cause: A proxy or load balancer between Grafana and Elasticsearch returned an error.

Solution:

Check the health of any proxies or load balancers in the connection path.
Verify Elasticsearch is running and accepting connections.
Review proxy/load balancer logs for more details.
Ensure the proxy timeout is configured appropriately for Elasticsearch requests.

Index errors

The following errors occur when there are issues with the configured index or index pattern.

Index not found

Error message: “Error validating index: index_not_found”

Cause: The specified index or index pattern does not match any existing indices.

Solution:

Verify the index name or pattern in the data source configuration.
Check that the index exists using GET /_cat/indices.
If using a time-based index pattern (for example, [logs-]YYYY.MM.DD), ensure indices exist for the selected time range.
Verify the user has permission to access the index.

Time field not found

Error message: “Could not find time field ‘@timestamp’ with type date in index”

Cause: The specified time field does not exist in the index or is not of type date.

Solution:

Verify the time field name in the data source configuration matches the field in your index.
Check the field mapping using GET /<index>/_mapping.
Ensure the time field is mapped as a date type, not text or keyword.
If the field name is different (for example, timestamp instead of @timestamp), update the data source configuration.

Query errors

The following errors occur when there are issues with query syntax or configuration.

Too many buckets

Error message: “Trying to create too many buckets. Must be less than or equal to: [65536].”

Cause: The query is generating more aggregation buckets than Elasticsearch allows.

Solution:

Reduce the time range of your query.
Increase the date histogram interval (for example, change from 10s to 1m).
Add filters to reduce the number of documents being aggregated.
Increase the search.max_buckets setting in Elasticsearch (requires cluster admin access).

Required field missing

Error message: “Required one of fields [field, script], but none were specified.”

Cause: A metric aggregation (such as Average, Sum, or Min) was added without specifying a field.

Solution:

Select a field for the metric aggregation in the query editor.
Ensure the selected field exists in your index and contains numeric data.

Unsupported interval

Error message: “unsupported interval ‘<interval>’”

Cause: The interval specified for the index pattern is not valid.

Solution:

Use a supported interval: Hourly, Daily, Weekly, Monthly, or Yearly.
If you don’t need a time-based index pattern, use No pattern and specify the exact index name.

Version errors

The following errors occur when there are Elasticsearch version compatibility issues.

Unsupported Elasticsearch version

Error message: “Support for Elasticsearch versions after their end-of-life (currently versions < 7.16) was removed. Using unsupported version of Elasticsearch may lead to unexpected and incorrect results.”

Cause: The Elasticsearch version is no longer supported by the Grafana data source.

Solution:

Upgrade Elasticsearch to a supported version (7.17+, 8.x, or 9.x).
Refer to Elastic Product End of Life Dates for version support information.
Note that queries may still work, but Grafana does not guarantee functionality for unsupported versions.

Other common issues

The following issues don’t produce specific error messages but are commonly encountered.

Empty query results

Cause: The query returns no data.

Solution:

Verify the time range includes data in your index.
Check the Lucene query syntax for errors.
Test the query directly in Elasticsearch using the _search API.
Ensure the index contains documents matching your query filters.

Slow query performance

Cause: Queries take a long time to execute.

Solution:

Reduce the time range of your query.
Add more specific filters to limit the data scanned.
Increase the date histogram interval.
Check Elasticsearch cluster performance and resource utilization.
Consider using index aliases or data streams for better query routing.

CORS errors in browser console

Cause: Cross-Origin Resource Sharing (CORS) is blocking requests from the browser to Elasticsearch.

Solution:

Use Server (proxy) access mode instead of Browser access mode in the data source configuration.
If Browser access is required, configure CORS settings in Elasticsearch:

http.cors.enabled: true
http.cors.allow-origin: '<your-grafana-url>'
http.cors.allow-headers: 'Authorization, Content-Type'
http.cors.allow-credentials: true

Note
Server (proxy) access mode is recommended for security and reliability.

Get additional help

If you continue to experience issues after following this troubleshooting guide:

Check the Elasticsearch documentation for API-specific guidance.
Review the Grafana community forums for similar issues.
Contact Grafana Support if you have an Enterprise license.

Elasticsearch data source on Grafana Labs

Configure the Elasticsearch data source

Configure the Elasticsearch data source

Before you begin

Elasticsearch permissions

Add the data source

Configuration options

Connection

Authentication

API key authentication

Amazon Elasticsearch Service

TLS settings

HTTP headers

Additional settings

Advanced HTTP settings

Elasticsearch details

Logs

Data links

Private data source connect (PDC) and Elasticsearch

Provision the data source

Basic provisioning

Provision for logs

Provision the data source using Terraform

Basic Terraform example

Terraform example for logs

Terraform example with basic authentication

Elasticsearch query editor

Elasticsearch query editor

Aggregation types

Select a query type

Metrics query type

Logs query type

Raw data query type

Raw query editor

Switch between Builder and Code modes

Write raw DSL queries

Time range handling

Supported query types

Use template variables

Elasticsearch template variables

Elasticsearch template variables

Use ad hoc filters

Choose a variable syntax

Use variables in queries

Variables in Lucene queries

Chain or nest variables

Variables in aggregations

Template variable examples

Create a query

Sort query results

Elasticsearch annotations

Elasticsearch annotations

Before you begin

Create an annotation query

Query

Field mappings

Time

Time End

Text

Tags

Example: Deployment annotations

Example: Range annotations for incidents

Elasticsearch alerting

Elasticsearch alerting

Before you begin

Supported query types

Query types and alerting compatibility

Create an alert rule

Example alert queries

Alert on high error count

Alert on average response time

Alert on unique user count drop

Limitations

Template variables not supported

Logs queries not supported

Query complexity

Best practices

Troubleshoot issues with the Elasticsearch data source

Troubleshoot issues with the Elasticsearch data source

Connection errors