grafana/docs/sources/features/datasources/elasticsearch.md

+++ title = "Using Elasticsearch in Grafana" description = "Guide for using Elasticsearch in Grafana" keywords = ["grafana", "elasticsearch", "guide"] type = "docs" aliases = ["/datasources/elasticsearch"] [menu.docs] name = "Elasticsearch" parent = "datasources" weight = 3 +++

Using Elasticsearch in Grafana

Grafana ships with advanced support for Elasticsearch. You can do many types of simple or complex elasticsearch queries to visualize logs or metrics stored in elasticsearch. You can also annotate your graphs with log events stored in elasticsearch.

Adding the data source

1. Open the side menu by clicking the the Grafana icon in the top header.
2. In the side menu under the Dashboards link you should find a link named Data Sources.
3. Click the + Add data source button in the top header.
4. Select Elasticsearch from the Type dropdown.

NOTE: If you're not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Name	Description
Name	The data source name. This is how you refer to the data source in panel metric queries.
Default	Default data source means that it will be pre-selected for new panels.
Url	The HTTP protocol, IP, and port of your graphite-web or graphite-api install.
Access	Proxy = access via Grafana backend, Direct = access directly from browser.

Proxy access means that the Grafana backend will proxy all requests from the browser, and send them on to the Data Source. This is useful because it can eliminate CORS (Cross Origin Site Resource) issues, as well as eliminate the need to disseminate authentication details to the Data Source to the browser.

Direct access

If you select direct access you must update your Elasticsearch configuration to allow other domains to access Elasticsearch from the browser. You do this by specifying these to options in your elasticsearch.yml config file.

http.cors.enabled: true
http.cors.allow-origin: "*"

Index settings

Here you can specify a default for the time field and specify the name of your elasticsearch index. You can use a time pattern for the index name or a wildcard.

Metric Query editor

The Elasticsearch query editor allows you to select multiple metrics and group by multiple terms or filters. Use the plus and minus icons to the right to add / remove metrics or group bys. Some metrics and group by have options, click the option text to expand the the row to view and edit metric or group by options.

Series naming & alias patterns

You can control the name for time series via the Alias input field.

Pattern	Description
{{term fieldname}}	replaced with value of a term group by
{{metric}}	replaced with metric name (ex. Average, Min, Max)
{{field}}	replaced with the metric field name

Pipeline metrics

If you have Elasticsearch 2.x and Grafana 2.6 or above then you can use pipeline metric aggregations like Moving Average and Derivative. Elasticsearch pipeline metrics require another metric to be based on. Use the eye icon next to the metric to hide metrics from appearing in the graph. This is useful for metrics you only have in the query to be used in a pipeline metric.

Templating

Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data being displayed in your dashboard.

Checkout the [Templating]({{< relref "reference/templating.md" >}}) documentation for an introduction to the templating feature and the different types of template variables.

Query variable

The Elasticsearch datasource supports two types of queries you can use in the Query field of Query variables.

The query is written using a custom json string.g

Query	Description
*{"find": "fields", "type": "keyword"}	Returns a list of field names with the index type keyword.
{"find": "terms", "field": "@hostname"}	Returns a list of values for a field using term aggregation. Query will user current dashboard time range as time range for query.
{"find": "terms", "field": "@hostname", "query": ''}	Returns a list of values for a field using term aggregation & and a specified lucene query filter. Query will use current dashboard time range as time range for query.

You can use other variables inside the query. Example query definition for variable named $host.

{"find": "terms", "field": "@hostname", "query": "@source:$source"}

In the above example we use another variable named $source inside the the query definition. When ever you change, via the dropdown, the current value of the $source variable, it will trigger an update of the $host variable so it now only contains hostnames filtered by in this case the @source document property.

Using variables in queries

There are two syntaxes:

• $<varname> Example: @hostname:$hostname
• [[varname]] Example: @hostname:hostname

Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of a word. When the Multi-value or Include all value options are enabled, Grafana converts the labels from plain text to a lucene compatible condition.

In the above example we have a lucene query that filters documents based on the @hostname property using a variable named $hostname. It is also using a variable in the Terms group by field input box. This allows you to use a variable to quickly change how the data is grouped.

Example dashboard: Elasticsearch Templated Dashboard

Annotations

[Annotations]({{< relref "reference/annotations.md" >}}) allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. Grafana can query any Elasticsearch index for annotation events.

Name	Description
Query	You can leave the search query blank or specify a lucene query
Time	The name of the time field, needs to be date field.
Title	The name of field to use for the event title.
Tags	Optional field name to use for event tags (can be array or csv string).
Text	Optional field name to use event text body.