mirror of
https://github.com/grafana/grafana.git
synced 2024-11-22 08:56:43 -06:00
Add documentation for Exemplars (#30317)
* Add documentation for Exemplars * Update prometheus.md Add note + provisioning info * Update docs/sources/datasources/prometheus.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update prometheus.md * Update prometheus.md Add exemplars options to the settings table * Update docs/sources/datasources/prometheus.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update docs/sources/datasources/prometheus.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update prometheus.md Add more content to exemplars * Update whats-new-in-v7-4.md Add link to exemplars Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>
This commit is contained in:
Zoltán Bedi
GitHub
parent
15683319e0
commit
b76e02755c
@ -26,6 +26,9 @@ To access Prometheus settings, hover your mouse over the **Configuration** (gear
|
||||
| `Scrape interval` | Set this to the typical scrape and evaluation interval configured in Prometheus. Defaults to 15s. |
|
||||
| `Disable metrics lookup` | Checking this option will disable the metrics chooser and metric/label support in the query field's autocomplete. This helps if you have performance issues with bigger Prometheus instances. |
|
||||
| `Custom Query Parameters` | Add custom parameters to the Prometheus query URL. For example `timeout`, `partial_response`, `dedup`, or `max_source_resolution`. Multiple parameters should be concatenated together with an '&'. |
|
||||
| `Label name` | Add the name of the field in the label object. |
|
||||
| `URL` | If the link is external, then enter the full link URL. You can interpolate the value from the field with `${__value.raw }` macro. |
|
||||
| `Internal link` | Select if the link is internal or external. In the case of an internal link, a data source selector allows you to select the target data source. Supports tracing data sources only. |
|
||||
|
||||
## Prometheus query editor
|
||||
|
||||
@ -42,12 +45,13 @@ Open a graph in edit mode by clicking the title > Edit (or by pressing `e` key w
|
||||
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Query expression` | Prometheus query expression, check out the [Prometheus documentation](http://prometheus.io/docs/querying/basics/). |
|
||||
| `Legend format` | Controls the name of the time series, using name or pattern. For example `{{hostname}}` is replaced with the label value for the label `hostname`. |
|
||||
| `Min step` | An additional lower limit for the [`step` parameter of Prometheus range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) and for the `$__interval` and `$__rate_interval` variables. The limit is absolute and not modified by the _Resolution_ setting. |
|
||||
| `Min step` | An additional lower limit for the [`step` parameter of Prometheus range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) and for the `$__interval` and `$__rate_interval` variables. The limit is absolute, it cannot modified by the _Resolution_ setting. |
|
||||
| `Resolution` | `1/1` sets both the `$__interval` variable and the [`step` parameter of Prometheus range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) such that each pixel corresponds to one data point. For better performance, lower resolutions can be picked. `1/2` only retrieves a data point for every other pixel, and `1/10` retrieves one data point per 10 pixels. Note that both _Min time interval_ and _Min step_ limit the final value of `$__interval` and `step`. |
|
||||
| `Metric lookup` | Search for metric names in this input field. |
|
||||
| `Format as` | Switch between `Table`, `Time series`, or `Heatmap`. `Table` will only work in the Table panel. `Heatmap` is suitable for displaying metrics of the Histogram type on a Heatmap panel. Under the hood, it converts cumulative histograms to regular ones and sorts series by the bucket bound. |
|
||||
| `Format as` | Switch between `Table`, `Time series`, or `Heatmap`. `Table` will only work in the Table panel. `Heatmap` is suitable for displaying metrics of the Histogram type on a Heatmap panel. Under the hood, it converts cumulative histograms to regular ones and sorts series by the bucket bound. |
|
||||
| `Instant` | Perform an "instant" query, to return only the latest value that Prometheus has scraped for the requested time series. Instant queries return results much faster than normal range queries. Use them to look up label sets. |
|
||||
| `Min time interval` | This value multiplied by the denominator from the _Resolution_ setting sets a lower limit to both the `$__interval` variable and the [`step` parameter of Prometheus range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries). Defaults to _Scrape interval_ as set in the data source options. |
|
||||
| `Exemplars` | Run and show exemplars in the graph. |
|
||||
|
||||
> **Note:** Grafana modifies the request dates for queries to align them with the dynamically calculated step. This ensures consistent display of metrics data, but it can result in a small gap of data at the right edge of a graph.
|
||||
|
||||
@ -64,11 +68,12 @@ To show a horizontal line across the whole graph, add a series override and sele
|
||||
|
||||
### Query editor in Explore
|
||||
|
||||
| Name | Description |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Query expression` | Prometheus query expression, check out the [Prometheus documentation](http://prometheus.io/docs/querying/basics/). |
|
||||
| `Step` | [`Step` parameter of Prometheus range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries). Time units can be used here, for example: 5s, 1m, 3h, 1d, 1y. Default unit if no unit specified is `s` (seconds). |
|
||||
| Name | Description |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `Query expression` | Prometheus query expression, check out the [Prometheus documentation](http://prometheus.io/docs/querying/basics/). |
|
||||
| `Step` | [`Step` parameter of Prometheus range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries). Time units can be used here, for example: 5s, 1m, 3h, 1d, 1y. Default unit if no unit specified is `s` (seconds). |
|
||||
| `Query type` | `Range`, `Instant`, or `Both`. When running **Range query**, the result of the query is displayed in graph and table. Instant query returns only the latest value that Prometheus has scraped for the requested time series and it is displayed in the table. When **Both** is selected, both instant query and range query is run. Result of range query is displayed in graph and the result of instant query is displayed in the table. |
|
||||
| `Exemplars` | Run and show exemplars in the graph. |
|
||||
|
||||
## Templating
|
||||
|
||||
@ -84,13 +89,13 @@ types of template variables.
|
||||
Variable of the type _Query_ allows you to query Prometheus for a list of metrics, labels or label values. The Prometheus data source plugin
|
||||
provides the following functions you can use in the `Query` input field.
|
||||
|
||||
| Name | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `label_names()` | Returns a list of label names. |
|
||||
| `label_values(label)` | Returns a list of label values for the `label` in every metric. |
|
||||
| `label_values(metric, label)` | Returns a list of label values for the `label` in the specified metric. |
|
||||
| `metrics(metric)` | Returns a list of metrics matching the specified `metric` regex. |
|
||||
| `query_result(query)` | Returns a list of Prometheus query result for the `query`. |
|
||||
| Name | Description |
|
||||
| ----------------------------- | ----------------------------------------------------------------------- |
|
||||
| `label_names()` | Returns a list of label names. |
|
||||
| `label_values(label)` | Returns a list of label values for the `label` in every metric. |
|
||||
| `label_values(metric, label)` | Returns a list of label values for the `label` in the specified metric. |
|
||||
| `metrics(metric)` | Returns a list of metrics matching the specified `metric` regex. |
|
||||
| `query_result(query)` | Returns a list of Prometheus query result for the `query`. |
|
||||
|
||||
For details of what _metric names_, _label names_ and _label values_ are please refer to the [Prometheus documentation](http://prometheus.io/docs/concepts/data_model/#metric-names-and-labels).
|
||||
|
||||
@ -124,7 +129,7 @@ Regex:
|
||||
|
||||
> **Note:** Available in Grafana 7.2 and above
|
||||
|
||||
The `$__rate_interval` variable is meant to be used in the rate function. It is defined as max( `$__interval` + _Scrape interval_, 4 \* _Scrape interval_), where _Scrape interval_ is the Min step setting (AKA query_interval, a setting per PromQL query), if any is set, and otherwise the _Scrape interval_ as set in the Prometheus data source (but ignoring any Min interval setting in the panel, because the latter is modified by the resolution setting).
|
||||
The `$__rate_interval` variable is meant to be used in the rate function. It is defined as max( `$__interval` + _Scrape interval_, 4 \* _Scrape interval_), where _Scrape interval_ is the Min step setting (AKA query*interval, a setting per PromQL query), if any is set, and otherwise the \_Scrape interval* as set in the Prometheus data source (but ignoring any Min interval setting in the panel, because the latter is modified by the resolution setting).
|
||||
|
||||
### Using variables in queries
|
||||
|
||||
@ -161,7 +166,7 @@ The Prometheus data source works with other projects that implement the [Prometh
|
||||
- [Cortex](https://cortexmetrics.io/docs/)
|
||||
- [Thanos](https://thanos.io/v0.17/components/query.md/)
|
||||
|
||||
For more information on how to query other Prometheus-compatible projects from Grafana, refer to the specific project documentation.
|
||||
For more information on how to query other Prometheus-compatible projects from Grafana, refer to the specific project documentation.
|
||||
|
||||
## Provision the Prometheus data source
|
||||
|
||||
@ -178,14 +183,36 @@ datasources:
|
||||
# Access mode - proxy (server in the UI) or direct (browser in the UI).
|
||||
access: proxy
|
||||
url: http://localhost:9090
|
||||
jsonData:
|
||||
exemplarTraceIdDestinations:
|
||||
# Field with internal link pointing to data source in Grafana.
|
||||
# datasourceUid value can be anything, but it should be unique across all defined data source uids.
|
||||
- datasourceUid: my_jaeger_uid
|
||||
name: traceID
|
||||
|
||||
# Field with external link.
|
||||
- name: traceID
|
||||
url: 'http://localhost:3000/explore?orgId=1&left=%5B%22now-1h%22,%22now%22,%22Jaeger%22,%7B%22query%22:%22$${__value.raw}%22%7D%5D'
|
||||
```
|
||||
|
||||
## Amazon Managed Service for Prometheus
|
||||
|
||||
The Prometheus data source works with Amazon Managed Service for Prometheus. If you are using an AWS Identity and Access Management (IAM) policy to control access to your Amazon Managed Service for Prometheus domain, then you must use AWS Signature Version 4 (AWS SigV4) to sign all requests to that domain. For more details on AWS SigV4, refer to the [AWS documentation](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
|
||||
The Prometheus data source works with Amazon Managed Service for Prometheus. If you are using an AWS Identity and Access Management (IAM) policy to control access to your Amazon Managed Service for Prometheus domain, then you must use AWS Signature Version 4 (AWS SigV4) to sign all requests to that domain. For more details on AWS SigV4, refer to the [AWS documentation](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
|
||||
|
||||
> **Note:** Grafana version 7.3.5 or higher is required to use SigV4 authentication.
|
||||
|
||||
To connect the Prometheus data source to Amazon Managed Service for Prometheus using SigV4 authentication, refer to the AWS guide to [Set up Grafana open source or Grafana Enterprise for use with AMP](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-query-standalone-grafana.html).
|
||||
To connect the Prometheus data source to Amazon Managed Service for Prometheus using SigV4 authentication, refer to the AWS guide to [Set up Grafana open source or Grafana Enterprise for use with AMP](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-query-standalone-grafana.html).
|
||||
|
||||
If you are running Grafana in an Amazon EKS cluster, follow the AWS guide to [Query using Grafana running in an Amazon EKS cluster](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-query-grafana-7.3.html).
|
||||
|
||||
## Exemplars
|
||||
|
||||
> **Note:** This feature is available in Prometheus 2.25+ and Grafana 7.4+.
|
||||
|
||||
Grafana 7.4 and later versions have the capability to show exemplars data alongside a metric both in Explore and Dashboards.
|
||||
Exemplars are a way to associate higher cardinality metadata from a specific event with traditional timeseries data.
|
||||
{{< docs-imagebox img="/img/docs/v74/exemplars.png" class="docs-image--no-shadow" caption="Screenshot showing the detail window of an Exemplar" >}}
|
||||
|
||||
Configure Exemplars in the data source settings by adding external or internal links.
|
||||
{{< docs-imagebox img="/img/docs/v74/exemplars-settings.png" class="docs-image--no-shadow" caption="Screenshot of the Exemplars configuration" >}}
|
||||
|
||||
|
||||
@ -56,7 +56,7 @@ For more information, refer to [Filter data by value]({{< relref "../panels/tran
|
||||
|
||||
### Exemplar support
|
||||
|
||||
Grafana graphs now support Prometheus exemplars. They are displayed as diamonds in the graph visualization.
|
||||
Grafana graphs now support Prometheus [exemplars]({{< relref "../datasources/prometheus.md#exemplars" >}}). They are displayed as diamonds in the graph visualization.
|
||||
|
||||
> **Note:** Support for exemplars will be added in version Prometheus 2.25+,
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user