[release-12.3.1] DOCS: Updates to Elasticsearch data source docs (#115187)
DOCS: Updates to Elasticsearch data source docs (#115021)
* created new configure folder, rewrote intro page
* updated configure doc
* updated query editor
* updates to template variables
* added troubleshooting doc, fixed heading issues
* fix linter issues
* added alerting doc
* corrected title
* final edits
* fixed linter issue
* added deprecation comment per feedback
* ran prettier
(cherry picked from commit 91a72f2572)
This commit is contained in:
Larissa Wandzura
@@ -17,16 +17,6 @@ menuTitle: Elasticsearch
|
||||
title: Elasticsearch data source
|
||||
weight: 325
|
||||
refs:
|
||||
configuration:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#sigv4_auth_enabled
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#sigv4_auth_enabled
|
||||
provisioning-grafana:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#data-sources
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#data-sources
|
||||
explore:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/explore/
|
||||
@@ -44,12 +34,36 @@ refs:
|
||||
Elasticsearch is a search and analytics engine used for a variety of use cases.
|
||||
You can create many types of queries to visualize logs or metrics stored in Elasticsearch, and annotate graphs with log events stored in Elasticsearch.
|
||||
|
||||
The following will help you get started working with Elasticsearch and Grafana:
|
||||
The following resources will help you get started with Elasticsearch and Grafana:
|
||||
|
||||
- [What is Elasticsearch?](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro.html)
|
||||
- [Configure the Elasticsearch data source](/docs/grafana/latest/datasources/elasticsearch/configure-elasticsearch-data-source/)
|
||||
- [Elasticsearch query editor](query-editor/)
|
||||
- [Elasticsearch template variables](template-variables/)
|
||||
- [Configure the Elasticsearch data source](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/configure/)
|
||||
- [Elasticsearch query editor](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/query-editor/)
|
||||
- [Elasticsearch template variables](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/template-variables/)
|
||||
- [Elasticsearch annotations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/annotations/)
|
||||
- [Elasticsearch alerting](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/alerting/)
|
||||
- [Troubleshooting issues with the Elasticsearch data source](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/troubleshooting/)
|
||||
|
||||
## Key capabilities
|
||||
|
||||
The Elasticsearch data source supports:
|
||||
|
||||
- **Metrics queries:** Aggregate and visualize numeric data using bucket and metric aggregations.
|
||||
- **Log queries:** Search, filter, and explore log data with Lucene query syntax.
|
||||
- **Annotations:** Overlay Elasticsearch events on your dashboard graphs.
|
||||
- **Alerting:** Create alerts based on Elasticsearch query results.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you configure the Elasticsearch data source, you need:
|
||||
|
||||
- An Elasticsearch instance (v7.17+, v8.x, or v9.x)
|
||||
- Network access from Grafana to your Elasticsearch server
|
||||
- Appropriate user credentials or API keys with read access
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
If you use Amazon OpenSearch Service (the successor to Amazon Elasticsearch Service), use the [OpenSearch data source](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/opensearch/) instead.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Supported Elasticsearch versions
|
||||
|
||||
@@ -63,86 +77,18 @@ This data source supports these versions of Elasticsearch:
|
||||
- v8.x
|
||||
- v9.x
|
||||
|
||||
Our maintenance policy for Elasticsearch data source is aligned with the [Elastic Product End of Life Dates](https://www.elastic.co/support/eol) and we ensure proper functionality for supported versions. If you are using an Elasticsearch with version that is past its end-of-life (EOL), you can still execute queries, but you will receive a notification in the query builder indicating that the version of Elasticsearch you are using is no longer supported. It's important to note that in such cases, we do not guarantee the correctness of the functionality, and we will not be addressing any related issues.
|
||||
The Grafana maintenance policy for the Elasticsearch data source aligns with [Elastic Product End of Life Dates](https://www.elastic.co/support/eol). Grafana ensures proper functionality for supported versions only. If you use an EOL version of Elasticsearch, you can still run queries, but the query builder displays a warning. Grafana doesn't guarantee functionality or provide fixes for EOL versions.
|
||||
|
||||
## Provision the data source
|
||||
## Additional resources
|
||||
|
||||
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](ref:provisioning-grafana).
|
||||
Once you have configured the Elasticsearch data source, you can:
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The previously used `database` field has now been [deprecated](https://github.com/grafana/grafana/pull/58647).
|
||||
You should now use the `index` field in `jsonData` to store the index name.
|
||||
Please see the examples below.
|
||||
{{< /admonition >}}
|
||||
- Use [Explore](ref:explore) to run ad-hoc queries against your Elasticsearch data.
|
||||
- Configure and use [template variables](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/template-variables/) for dynamic dashboards.
|
||||
- Add [Transformations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/) to process query results.
|
||||
- [Build dashboards](ref:build-dashboards) to visualize your Elasticsearch data.
|
||||
|
||||
### Provisioning examples
|
||||
## Related data sources
|
||||
|
||||
**Basic provisioning**
|
||||
|
||||
```yaml
|
||||
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**
|
||||
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
|
||||
## Configure 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](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
|
||||
|
||||
### AWS Signature Version 4 authentication
|
||||
|
||||
To sign requests to your Amazon Elasticsearch Service domain, you can enable SigV4 in Grafana's [configuration](ref: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](../aws-cloudwatch/aws-authentication/).
|
||||
|
||||
{{< figure src="/static/img/docs/v73/elasticsearch-sigv4-config-editor.png" max-width="500px" class="docs-image--no-shadow" caption="SigV4 configuration for AWS Elasticsearch Service" >}}
|
||||
|
||||
## Query the data source
|
||||
|
||||
You can select multiple metrics and group by multiple terms or filters when using the Elasticsearch query editor.
|
||||
|
||||
For details, see the [query editor documentation](query-editor/).
|
||||
|
||||
## Use 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 dropdown 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 details, see the [template variables documentation](template-variables/).
|
||||
- [OpenSearch](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/opensearch/) - For Amazon OpenSearch Service.
|
||||
- [Loki](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/loki/) - Grafana's log aggregation system.
|
||||
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../data-sources/elasticsearch/alerting/
|
||||
description: Using Grafana Alerting with the Elasticsearch data source
|
||||
keywords:
|
||||
- grafana
|
||||
- elasticsearch
|
||||
- alerting
|
||||
- alerts
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: Alerting
|
||||
title: Elasticsearch alerting
|
||||
weight: 550
|
||||
refs:
|
||||
alerting:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/alerting-and-irm/alerting/
|
||||
create-alert-rule:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/alerting-rules/create-grafana-managed-rule/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-grafana-managed-rule/
|
||||
---
|
||||
|
||||
# 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](ref: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:
|
||||
|
||||
1. Navigate to **Alerting** > **Alert rules**.
|
||||
1. Click **New alert rule**.
|
||||
1. Enter a name for the alert rule.
|
||||
1. Select your **Elasticsearch** data source.
|
||||
1. 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
|
||||
1. Configure the alert condition (for example, when the average is above a threshold).
|
||||
1. Set the evaluation interval and pending period.
|
||||
1. Configure notifications and labels.
|
||||
1. Click **Save rule**.
|
||||
|
||||
For detailed instructions, refer to [Create a Grafana-managed alert rule](ref:create-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:
|
||||
|
||||
1. **Query:** `level:error`
|
||||
1. **Metric:** Count
|
||||
1. **Group by:** Date histogram (interval: 1m)
|
||||
1. **Condition:** When count is above 100
|
||||
|
||||
### Alert on average response time
|
||||
|
||||
Monitor API response times:
|
||||
|
||||
1. **Query:** `type:api_request`
|
||||
1. **Metric:** Average on field `response_time`
|
||||
1. **Group by:** Date histogram (interval: 5m)
|
||||
1. **Condition:** When average is above 500 (milliseconds)
|
||||
|
||||
### Alert on unique user count drop
|
||||
|
||||
Detect drops in active users:
|
||||
|
||||
1. **Query:** `*` (all documents)
|
||||
1. **Metric:** Unique count on field `user_id`
|
||||
1. **Group by:** Date histogram (interval: 1h)
|
||||
1. **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.
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../data-sources/elasticsearch/annotations/
|
||||
description: Using annotations with Elasticsearch in Grafana
|
||||
keywords:
|
||||
- grafana
|
||||
- elasticsearch
|
||||
- annotations
|
||||
- events
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: Annotations
|
||||
title: Elasticsearch annotations
|
||||
weight: 500
|
||||
refs:
|
||||
annotate-visualizations:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
|
||||
---
|
||||
|
||||
# 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](ref: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:
|
||||
|
||||
1. Navigate to your dashboard and click **Dashboard settings** (gear icon).
|
||||
1. Select **Annotations** in the left menu.
|
||||
1. Click **Add annotation query**.
|
||||
1. Enter a **Name** for the annotation.
|
||||
1. Select your **Elasticsearch** data source from the **Data source** drop-down.
|
||||
1. Configure the annotation query and field mappings.
|
||||
1. Click **Save dashboard**.
|
||||
|
||||
## Query
|
||||
|
||||
Use the query field to filter which Elasticsearch documents appear as annotations. The query uses [Lucene query syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-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`.
|
||||
|
||||
### Tags
|
||||
|
||||
The **Tags** field specifies which field contains tags for the annotation. Tags help categorize and filter annotations.
|
||||
|
||||
- **Default:** Empty
|
||||
- **Format:** The field can contain either a comma-separated string or an array of strings.
|
||||
|
||||
## Example: Deployment annotations
|
||||
|
||||
To display deployment events as annotations:
|
||||
|
||||
1. 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:
|
||||
|
||||
1. 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.
|
||||
@@ -0,0 +1,377 @@
|
||||
---
|
||||
aliases:
|
||||
- ../configure-elasticsearch-data-source/
|
||||
description: Guide for configuring the Elasticsearch data source in Grafana
|
||||
keywords:
|
||||
- grafana
|
||||
- elasticsearch
|
||||
- guide
|
||||
- data source
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: Configure
|
||||
title: Configure the Elasticsearch data source
|
||||
weight: 200
|
||||
refs:
|
||||
administration-documentation:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
|
||||
supported-expressions:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/explore/logs-integration/#log-level
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/explore/logs-integration/#log-level
|
||||
query-and-transform-data:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/
|
||||
provisioning-data-source:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/configure/#provision-the-data-source
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/elasticsearch/configure/#provision-the-data-source
|
||||
configuration:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#sigv4_auth_enabled
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#sigv4_auth_enabled
|
||||
provisioning-grafana:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/
|
||||
---
|
||||
|
||||
# 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](ref:administration-documentation).
|
||||
Administrators can also [configure the data source via YAML](ref:provisioning-data-source) 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, or v9.x. Elastic Cloud Serverless isn't supported.
|
||||
- **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)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/) 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:
|
||||
|
||||
1. Click **Connections** in the left-side menu.
|
||||
1. Under **Connections**, click **Add new connection**.
|
||||
1. Enter `Elasticsearch` in the search bar.
|
||||
1. Click **Elasticsearch** under the **Data source** section.
|
||||
1. 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:
|
||||
|
||||
1. In the **HTTP headers** section, click **+ Add header**.
|
||||
1. Set **Header** to `Authorization`.
|
||||
1. 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](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html).
|
||||
|
||||
### 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](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
|
||||
|
||||
To sign requests to your Amazon Elasticsearch Service domain, you can enable SigV4 in Grafana's [configuration](ref: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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/aws-cloudwatch/aws-authentication/).
|
||||
|
||||
{{< figure src="/static/img/docs/v73/elasticsearch-sigv4-config-editor.png" max-width="500px" class="docs-image--no-shadow" caption="SigV4 configuration for AWS Elasticsearch Service" >}}
|
||||
|
||||
### TLS settings
|
||||
|
||||
{{< admonition type="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](https://www.elastic.co/guide/en/elasticsearch/reference/8.8/configuring-tls.html#configuring-tls). You must add TLS settings to your Elasticsearch configuration file **prior** to setting these options in Grafana.
|
||||
{{< /admonition >}}
|
||||
|
||||
- **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](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/scalability.html#scalability).
|
||||
|
||||
- **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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/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](https://www.elastic.co/guide/en/elasticsearch/reference/7.13/frozen-indices.html) when performing search requests.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Frozen indices are [deprecated in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/frozen-indices.html) since v7.14.
|
||||
{{< /admonition >}}
|
||||
|
||||
### 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](ref: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.<br/>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](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/) for more information on how PDC works and [Configure Grafana private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/configure-pdc/#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](ref:provisioning-grafana).
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The previously used `database` field has now been [deprecated](https://github.com/grafana/grafana/pull/58647).
|
||||
Use the `index` field in `jsonData` to store the index name.
|
||||
Refer to the examples below.
|
||||
{{< /admonition >}}
|
||||
|
||||
### Basic provisioning
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```yaml
|
||||
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](https://www.terraform.io/) with the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
|
||||
|
||||
For more information about provisioning resources with Terraform, refer to the [Grafana as code using Terraform](https://grafana.com/docs/grafana-cloud/developer-resources/infrastructure-as-code/terraform/) documentation.
|
||||
|
||||
### Basic Terraform example
|
||||
|
||||
The following example creates a basic Elasticsearch data source for metrics:
|
||||
|
||||
```hcl
|
||||
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:
|
||||
|
||||
```hcl
|
||||
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:
|
||||
|
||||
```hcl
|
||||
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](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source).
|
||||
@@ -30,7 +30,7 @@ refs:
|
||||
# Elasticsearch query editor
|
||||
|
||||
Grafana provides a query editor for Elasticsearch. Elasticsearch queries are in Lucene format.
|
||||
See [Lucene query syntax](https://www.elastic.co/guide/en/kibana/current/lucene-query.html) and [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/query-dsl-query-string-query.html#query-string-syntax) if you are new to working with Lucene queries in Elasticsearch.
|
||||
For more information about query syntax, refer to [Lucene query syntax](https://www.elastic.co/guide/en/kibana/current/lucene-query.html) and [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax).
|
||||
|
||||
{{< admonition type="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.
|
||||
@@ -38,17 +38,17 @@ When composing Lucene queries, ensure that you use uppercase boolean operators:
|
||||
|
||||
{{< figure src="/static/img/docs/elasticsearch/elastic-query-editor-10.1.png" max-width="800px" class="docs-image--no-shadow" caption="Elasticsearch query editor" >}}
|
||||
|
||||
For general documentation on querying data sources in Grafana, including options and functions common to all query editors, see [Query and transform data](ref:query-and-transform-data).
|
||||
For general documentation on querying data sources in Grafana, including options and functions common to all query editors, refer to [Query and transform data](ref: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. See [Bucket aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket.html) for additional information. Use bucket aggregations under `Group by` when creating a metrics query in the query builder.
|
||||
- **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](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket.html) 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. See [Metrics aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics.html) for additional information. Use metrics aggregations in the metrics query type 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](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics.html) for additional information. Use metrics aggregations in the metrics query type in the query builder.
|
||||
|
||||
- **Pipeline** - Elasticsearch pipeline aggregations work with inputs or metrics created from other aggregations (not documents or fields). There are parent and sibling and sibling pipeline aggregations. See [Pipeline aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-pipeline.html) for additional information.
|
||||
- **Pipeline** - Pipeline aggregations work on the output of other aggregations rather than on documents or fields. Refer to [Pipeline aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline.html) for additional information.
|
||||
|
||||
## Select a query type
|
||||
|
||||
@@ -56,44 +56,51 @@ There are three types of queries you can create with the Elasticsearch query bui
|
||||
|
||||
### Metrics query type
|
||||
|
||||
Metrics queries aggregate data and produce a variety of calculations such as count, min, max, etc. Click on the metric box to view a list of options in the dropdown menu. The default is `count`.
|
||||
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 - see [Value count aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-valuecount-aggregation.html)
|
||||
- average - see [Avg aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-rate-aggregation.html)
|
||||
- sum - see [Sum aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-sum-aggregation.html)
|
||||
- max - see [Max aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-max-aggregation.html)
|
||||
- min - see [Min aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-min-aggregation.html)
|
||||
- extended stats - see [Extended stats aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-extendedstats-aggregation.html)
|
||||
- percentiles - see [Percentiles aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-percentile-aggregation.html)
|
||||
- unique count - see [Cardinality aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-cardinality-aggregation.html)
|
||||
- top metrics - see [Top metrics aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-top-metrics.html)
|
||||
- rate - see [Rate aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/search-aggregations-metrics-rate-aggregation.html)
|
||||
- count - refer to [Value count aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-valuecount-aggregation.html)
|
||||
- average - refer to [Avg aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-avg-aggregation.html)
|
||||
- sum - refer to [Sum aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-sum-aggregation.html)
|
||||
- max - refer to [Max aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html)
|
||||
- min - refer to [Min aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-min-aggregation.html)
|
||||
- extended stats - refer to [Extended stats aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-extendedstats-aggregation.html)
|
||||
- percentiles - refer to [Percentiles aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-percentile-aggregation.html)
|
||||
- unique count - refer to [Cardinality aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-cardinality-aggregation.html)
|
||||
- top metrics - refer to [Top metrics aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-top-metrics.html)
|
||||
- rate - refer to [Rate aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-rate-aggregation.html)
|
||||
|
||||
- **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](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-movfn-aggregation.html).
|
||||
- derivative - Calculates the derivative of a metric. Refer to [Derivative aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-derivative-aggregation.html).
|
||||
- cumulative sum - Calculates the cumulative sum of a metric. Refer to [Cumulative sum aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-cumulative-sum-aggregation.html).
|
||||
- serial difference - Calculates the difference between values in a time series. Refer to [Serial differencing aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-serialdiff-aggregation.html).
|
||||
- bucket script - Executes a script on metric values from other aggregations. Refer to [Bucket script aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-script-aggregation.html).
|
||||
|
||||
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. Below is a list of options in the dropdown menu.
|
||||
- terms - see [Terms aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html).
|
||||
- filter - see [Filter aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filter-aggregation.html).
|
||||
- geo hash grid - see [Geohash grid aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-geohashgrid-aggregation.html).
|
||||
- date histogram - for time series queries. See [Date histogram aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html).
|
||||
- histogram - Depicts frequency distributions. See [Histogram aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-histogram-aggregation.html).
|
||||
- nested (experimental) - See [Nested aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-nested-aggregation.html).
|
||||
- **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](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html).
|
||||
- filter - refer to [Filter aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filter-aggregation.html).
|
||||
- geo hash grid - refer to [Geohash grid aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-geohashgrid-aggregation.html).
|
||||
- date histogram - for time series queries. Refer to [Date histogram aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html).
|
||||
- histogram - Depicts frequency distributions. Refer to [Histogram aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-histogram-aggregation.html).
|
||||
- nested (experimental) - Refer to [Nested aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-nested-aggregation.html).
|
||||
|
||||
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** - Depicts date data options. The default option can be specified when configuring the Elasticsearch data source in the **Time field name** under the [**Elasticsearch details**](/docs/grafana/latest/datasources/elasticsearch/configure-elasticsearch-data-source/#elasticsearch-details) section. Otherwise **@timestamp** field will be used as a default option.
|
||||
- **Interval** - Group by a type of interval. There are option to choose from the dropdown menu to select seconds, minutes, hours or day. You can also add a custom interval such as `30d` (30 days). `Auto` is the default option.
|
||||
- **Min doc count** - The minimum amount of data to include in your query. The default is `0`.
|
||||
- **Thin edges** - Select to trim edges on the time series data points. The default is `0`.
|
||||
- **Offset** - Changes the start value of each bucket by the specified positive(+) or negative (-) offset duration. Examples include `1h` for 1 hour, `5s` for 5 seconds or `1d` for 1 day.
|
||||
- **Timezone** - Select a timezone from the dropdown menu. The default is `Coordinated universal time`.
|
||||
- **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](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/configure/#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:
|
||||
|
||||
@@ -101,7 +108,7 @@ Configure the following options for the **terms** bucket aggregation option:
|
||||
- **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. See [Missing value](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html#_missing_value_5) in Elasticsearch's documentation for more information.
|
||||
- **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](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html#_missing_value_5) in the Elasticsearch documentation for more information.
|
||||
|
||||
Configure the following options for the **filters** bucket aggregation option:
|
||||
|
||||
@@ -114,8 +121,8 @@ Configure the following options for the **geo hash grid** bucket aggregation opt
|
||||
|
||||
Configure the following options for the **histogram** bucket aggregation option:
|
||||
|
||||
- **Interval** - Group by a type of interval. There are option to choose from the dropdown menu to select seconds, minutes, hours or day. You can also add a custom interval such as `30d` (30 days). `Auto` is the default option.
|
||||
- **Min doc count** - The minimum amount of data to include in your query. The default is `0`
|
||||
- **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.
|
||||
|
||||
@@ -141,7 +148,7 @@ The option to run a **raw document query** is deprecated as of Grafana v10.1.
|
||||
|
||||
## Use template variables
|
||||
|
||||
You can also augment queries by using [template variables](../template-variables/).
|
||||
You can also augment queries by using [template variables](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/template-variables/).
|
||||
|
||||
Queries of `terms` have a 500-result limit by default.
|
||||
To set a custom limit, set the `size` property in your query.
|
||||
|
||||
@@ -22,6 +22,11 @@ refs:
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
|
||||
add-template-variables-add-ad-hoc-filters:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
|
||||
add-template-variables-multi-value-variables:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#multi-value-variables
|
||||
@@ -37,11 +42,29 @@ refs:
|
||||
# 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 dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
|
||||
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](ref:variables) and [Add and manage variables](ref:add-template-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](ref:add-template-variables-add-ad-hoc-filters).
|
||||
|
||||
## Choose a variable syntax
|
||||
|
||||
The Elasticsearch data source supports two variable syntaxes for use in the **Query** field:
|
||||
@@ -50,34 +73,35 @@ The Elasticsearch data source supports two variable syntaxes for use in the **Qu
|
||||
- `[[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, see the [Multi-value variables](ref:add-template-variables-multi-value-variables) documentation.
|
||||
For details, refer to the [Multi-value variables](ref:add-template-variables-multi-value-variables) documentation.
|
||||
|
||||
## Use variables in queries
|
||||
|
||||
You can use other variables inside the query.
|
||||
This example is used to define a variable named `$host`:
|
||||
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:
|
||||
|
||||
```
|
||||
{"find": "terms", "field": "hostname", "query": "source:$source"}
|
||||
hostname:$hostname AND level:$level
|
||||
```
|
||||
|
||||
This uses another variable named `$source` inside the query definition.
|
||||
Whenever you change the value of the `$source` variable via the dropdown, Grafana triggers an update of the `$host` variable to contain only hostnames filtered by, in this case, the `source` document property.
|
||||
### Chain or nest variables
|
||||
|
||||
These queries by default return results in term order (which can then be sorted alphabetically or numerically as for any variable).
|
||||
To produce a list of terms sorted by doc count (a top-N values list), add an `orderBy` property of "doc_count".
|
||||
This automatically selects a descending sort.
|
||||
You can create nested variables, where one variable's values depend on another variable's selection.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
To use an ascending sort (`asc`) with doc_count (a bottom-N list), set `order: "asc"`. However, Elasticsearch [discourages this](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html#search-aggregations-bucket-terms-aggregation-order) because sorting by ascending doc count can return inaccurate results.
|
||||
{{< /admonition >}}
|
||||
|
||||
To keep terms in the doc count order, set the variable's Sort dropdown to **Disabled**.
|
||||
You can alternatively use other sorting criteria, such as **Alphabetical**, to re-sort them.
|
||||
This example defines a variable named `$host` that only shows hosts matching the selected `$environment`:
|
||||
|
||||
```json
|
||||
{ "find": "terms", "field": "hostname", "query": "environment:$environment" }
|
||||
```
|
||||
{"find": "terms", "field": "hostname", "orderBy": "doc_count"}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
@@ -92,11 +116,36 @@ Write the query using a custom JSON string, with the field mapped as a [keyword]
|
||||
|
||||
If the query is [multi-field](https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-fields.html) 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": "terms", "field": "hostname.keyword", "size": 1000}` | Returns a list of values for a keyword using term aggregation. Query will use current dashboard time range as time range query. |
|
||||
| `{"find": "terms", "field": "hostname", "query": '<Lucene query>'}` | Returns a list of values for a keyword field using term aggregation and a specified Lucene query filter. Query will use current dashboard time range as time range for 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.
|
||||
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:
|
||||
|
||||
```json
|
||||
{ "find": "terms", "field": "status", "orderBy": "doc_count" }
|
||||
```
|
||||
|
||||
You can also use the `order` property to explicitly set ascending or descending sort:
|
||||
|
||||
```json
|
||||
{ "find": "terms", "field": "hostname", "orderBy": "doc_count", "order": "asc" }
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Elasticsearch [discourages](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html#search-aggregations-bucket-terms-aggregation-order) sorting by ascending doc count because it can return inaccurate results.
|
||||
{{< /admonition >}}
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,266 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../data-sources/elasticsearch/troubleshooting/
|
||||
description: Troubleshooting the Elasticsearch data source in Grafana
|
||||
keywords:
|
||||
- grafana
|
||||
- elasticsearch
|
||||
- troubleshooting
|
||||
- errors
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
menuTitle: Troubleshooting
|
||||
title: Troubleshoot issues with the Elasticsearch data source
|
||||
weight: 600
|
||||
---
|
||||
|
||||
# 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:**
|
||||
|
||||
1. Verify that the Elasticsearch URL is correct in the data source configuration.
|
||||
1. Check that Elasticsearch is running and accessible from the Grafana server.
|
||||
1. Ensure there are no firewall rules blocking the connection.
|
||||
1. If using a proxy, verify the proxy settings are correct.
|
||||
1. For Grafana Cloud, ensure you have configured [Private data source connect](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/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:**
|
||||
|
||||
1. Check the network latency between Grafana and Elasticsearch.
|
||||
1. Verify that Elasticsearch is not overloaded or experiencing performance issues.
|
||||
1. Increase the timeout setting in the data source configuration if needed.
|
||||
1. 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:**
|
||||
|
||||
1. Verify the URL format is correct (for example, `http://localhost:9200` or `https://elasticsearch.example.com:9200`).
|
||||
1. Ensure the URL includes the protocol (`http://` or `https://`).
|
||||
1. 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:**
|
||||
|
||||
1. Verify that the username and password are correct.
|
||||
1. If using an API key, ensure the key is valid and has not expired.
|
||||
1. Check that the authentication method selected matches your Elasticsearch configuration.
|
||||
1. 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:**
|
||||
|
||||
1. Verify the user has read access to the specified index.
|
||||
1. Check Elasticsearch security settings and role mappings.
|
||||
1. Ensure the user has permission to access the `_cluster/health` endpoint.
|
||||
1. 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:**
|
||||
|
||||
1. Check the Elasticsearch cluster health using `GET /_cluster/health`.
|
||||
1. Review Elasticsearch logs for errors.
|
||||
1. Verify all nodes in the cluster are running and connected.
|
||||
1. Check for unassigned shards using `GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason`.
|
||||
1. 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:**
|
||||
|
||||
1. Check the health of any proxies or load balancers in the connection path.
|
||||
1. Verify Elasticsearch is running and accepting connections.
|
||||
1. Review proxy/load balancer logs for more details.
|
||||
1. 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:**
|
||||
|
||||
1. Verify the index name or pattern in the data source configuration.
|
||||
1. Check that the index exists using `GET /_cat/indices`.
|
||||
1. If using a time-based index pattern (for example, `[logs-]YYYY.MM.DD`), ensure indices exist for the selected time range.
|
||||
1. 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:**
|
||||
|
||||
1. Verify the time field name in the data source configuration matches the field in your index.
|
||||
1. Check the field mapping using `GET /<index>/_mapping`.
|
||||
1. Ensure the time field is mapped as a `date` type, not `text` or `keyword`.
|
||||
1. 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:**
|
||||
|
||||
1. Reduce the time range of your query.
|
||||
1. Increase the date histogram interval (for example, change from `10s` to `1m`).
|
||||
1. Add filters to reduce the number of documents being aggregated.
|
||||
1. 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:**
|
||||
|
||||
1. Select a field for the metric aggregation in the query editor.
|
||||
1. 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:**
|
||||
|
||||
1. Use a supported interval: `Hourly`, `Daily`, `Weekly`, `Monthly`, or `Yearly`.
|
||||
1. 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:**
|
||||
|
||||
1. Upgrade Elasticsearch to a supported version (7.17+, 8.x, or 9.x).
|
||||
1. Refer to [Elastic Product End of Life Dates](https://www.elastic.co/support/eol) for version support information.
|
||||
1. 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:**
|
||||
|
||||
1. Verify the time range includes data in your index.
|
||||
1. Check the Lucene query syntax for errors.
|
||||
1. Test the query directly in Elasticsearch using the `_search` API.
|
||||
1. Ensure the index contains documents matching your query filters.
|
||||
|
||||
### Slow query performance
|
||||
|
||||
**Cause:** Queries take a long time to execute.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Reduce the time range of your query.
|
||||
1. Add more specific filters to limit the data scanned.
|
||||
1. Increase the date histogram interval.
|
||||
1. Check Elasticsearch cluster performance and resource utilization.
|
||||
1. 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:**
|
||||
|
||||
1. Use Server (proxy) access mode instead of Browser access mode in the data source configuration.
|
||||
1. If Browser access is required, configure CORS settings in Elasticsearch:
|
||||
|
||||
```yaml
|
||||
http.cors.enabled: true
|
||||
http.cors.allow-origin: '<your-grafana-url>'
|
||||
http.cors.allow-headers: 'Authorization, Content-Type'
|
||||
http.cors.allow-credentials: true
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Server (proxy) access mode is recommended for security and reliability.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Get additional help
|
||||
|
||||
If you continue to experience issues after following this troubleshooting guide:
|
||||
|
||||
1. Check the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html) for API-specific guidance.
|
||||
1. Review the [Grafana community forums](https://community.grafana.com/) for similar issues.
|
||||
1. Contact Grafana Support if you have an Enterprise license.
|
||||
Reference in New Issue
Block a user