Grafana ships with advanced support for Elasticsearch. You can do many types of
Grafana ships with advanced support for Elasticsearch. You can do many types of simple or complex elasticsearch queries to
simple or complex elasticsearch queries to visualize logs or metrics stored in elasticsearch. You can
visualize logs or metrics stored in elasticsearch. You can also annotate your graphs with log events stored in elasticsearch.
also annotate your graphs with log events stored in elasticsearch.
## Adding the data source
## Adding the data source
1. Open the side menu by clicking the the Grafana icon in the top header.
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`.
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 this link is missing in the side menu it means that your current user does not have the `Admin` role for the current organization.
> 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.
3. Click the `Add new` link in the top header.
4. Select `Elasticsearch` from the dropdown.
Name | Description
Name | Description
------------ | -------------
------------ | -------------
Name | The data source name, important that this is the same as in Grafana v1.x if you plan to import old dashboards.
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.
Default | Default data source means that it will be pre-selected for new panels.
Url | The http protocol, ip and port of you elasticsearch server.
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.
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.
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 is still supported because in some cases it may be useful to access a Data Source directly depending on the use case and topology of Grafana, the user, and the Data Source.
### Direct access
### Direct access
If you select direct access you must update your Elasticsearch configuration to allow other domains to 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.
Elasticsearch from the browser. You do this by specifying these to options in your **elasticsearch.yml** config file.
...
@@ -60,6 +55,16 @@ a time pattern for the index name or a wildcard.
...
@@ -60,6 +55,16 @@ a time pattern for the index name or a wildcard.
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
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.
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
## Pipeline metrics
If you have Elasticsearch 2.x and Grafana 2.6 or above then you can use pipeline metric aggregations like
If you have Elasticsearch 2.x and Grafana 2.6 or above then you can use pipeline metric aggregations like
...
@@ -71,25 +76,53 @@ in a pipeline metric.
...
@@ -71,25 +76,53 @@ in a pipeline metric.
## Templating
## Templating
The Elasticsearch datasource supports two types of queries you can use to fill template variables with values.
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.
### Possible values for a field
Checkout the [Templating]({{<relref"reference/templating.md">}}) documentation for an introduction to the templating feature and the different
types of template variables.
```json
### Query variable
{"find":"terms","field":"@hostname"}
```
### Fields filtered by type
The Elasticsearch datasource supports two types of queries you can use in the *Query* field of *Query* variables.
*{"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": '<lucene 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`.
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.
@@ -28,16 +28,13 @@ queries through the use of query references.
...
@@ -28,16 +28,13 @@ queries through the use of query references.
Name | Description
Name | Description
------------ | -------------
------------ | -------------
Name | The data source name, important that this is the same as in Grafana v1.x if you plan to import old dashboards.
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.
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.
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.
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.
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 is still supported because in some cases it may be useful to access a Data Source directly depending on the use case and topology of Grafana, the user, and the Data Source.
## Metric editor
## Metric editor
### Navigate metric segments
### Navigate metric segments
...
@@ -47,6 +44,7 @@ or keyboard arrow keys. You can select a wildcard and still continue.
...
@@ -47,6 +44,7 @@ or keyboard arrow keys. You can select a wildcard and still continue.
### Functions
### Functions
Click the plus icon to the right to add a function. You can search for the function or select it from the menu. Once
Click the plus icon to the right to add a function. You can search for the function or select it from the menu. Once
a function is selected it will be added and your focus will be in the text box of the first parameter. To later change
a function is selected it will be added and your focus will be in the text box of the first parameter. To later change
a parameter just click on it and it will turn into a text box. To delete a function click the function name followed
a parameter just click on it and it will turn into a text box. To delete a function click the function name followed
...
@@ -54,8 +52,8 @@ by the x icon.
...
@@ -54,8 +52,8 @@ by the x icon.
### Optional parameters
### Optional parameters
Some functions like aliasByNode support an optional second argument. To add this parameter specify for example 3,-2 as the first parameter and the function editor will adapt and move the -2 to a second parameter. To remove the second optional parameter just click on it and leave it blank and the editor will remove it.
Some functions like aliasByNode support an optional second argument. To add this parameter specify for example 3,-2 as the first parameter and the function editor will adapt and move the -2 to a second parameter. To remove the second optional parameter just click on it and leave it blank and the editor will remove it.
