Skip to content

N
nexpie-grafana-theme
Commit e9bcee30 by Björn Rabenstein Committed by David
Options

Improve documentation for the Prometheus data source (#21415) 

Besides minor language corrections, this tries in particular to
provide some clarity about the `step` setting in the Prometheus range
query and the `$__interval` variable:

- First of all: They are both always the same.

- What's really confusing (and arguably really un-helpful) is that the
  _Min time interval_ is multiplied by the resolution
  factor. Therefore, I just state the fact here now but don't add
  anything like "This should be the scrape interval" because it is not
  true (if resolution is `1/10`, a meaningful _Min time interval_ is
  generally a tenth of the scrape interval).

- More helpful is the _Min step_ parameter, because it is not
  multiplied by the resolution factor (which I have now stated
  explicitly). Of course, the _Min time interval_ has to be set to
  something small so that the _Min step_ parameter can kick in.

It would be good if we could also override the _Min time interval_
tool tip because that is where most people will look, and the current,
very Graphite-centric tool tip is very confusing for the Prometheus
query editor, in particular because it doesn't have any hint about the
resolution factor being applied. See #21413.

Signed-off-by: beorn7 <beorn@grafana.com>
parent 7521d2bb
Showing with 9 additions and 8 deletions
docs/sources/features/datasources/prometheus.md
...@@ -26,15 +26,15 @@ Grafana includes built-in support for Prometheus. ...@@ -26,15 +26,15 @@ Grafana includes built-in support for Prometheus.
## Data source options ## Data source options
| Name | Description | | Name | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| _Name_ | The data source name. This is how you refer to the data source in panels and queries. | | _Name_ | The data source name. This is how you refer to the data source in panels and 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 Prometheus server (default port is usually 9090) | | _Url_ | The URL of your Prometheus server, e.g. `http://prometheus.example.org:9090`. |
| _Access_ | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. | | _Access_ | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. |
| _Basic Auth_ | Enable basic authentication to the Prometheus data source. | | _Basic Auth_ | Enable basic authentication to the Prometheus data source. |
| _User_ | Name of your Prometheus user | | _User_ | User name for basic authentication. |
| _Password_ | Database user's password | | _Password_ | Password for basic authentication. |
| _Scrape interval_ | This will be used as a lower limit for the Prometheus step query parameter. Default value is 15s. | | _Scrape interval_ | Set this to the typical scrape and evaluation interval configured in Prometheus. Defaults to 15s. |
| _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 '&amp;'. | | _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 '&amp;'. |
## Query editor ## Query editor
...@@ -48,11 +48,12 @@ Open a graph in edit mode by click the title > Edit (or by pressing `e` key whil ...@@ -48,11 +48,12 @@ Open a graph in edit mode by click the title > Edit (or by pressing `e` key whil
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _Query expression_ | Prometheus query expression, check out the [Prometheus documentation](http://prometheus.io/docs/querying/basics/). | | _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}}` will be replaced with label value for the label `hostname`. | | _Legend format_ | Controls the name of the time series, using name or pattern. For example `{{hostname}}` will be replaced with label value for the label `hostname`. |
| _Min step_ | Set a lower limit for the Prometheus step option. Step controls how big the jumps are when the Prometheus query engine performs range queries. Sadly there is no official prometheus documentation to link to for this very important option. | | _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` variable. The limit is absolute and not modified by the _Resolution_ setting. |
| _Resolution_ | Controls the step option. Small steps create high-resolution graphs but can be slow over larger time ranges, lowering the resolution can speed things up. `1/2` will try to set step option to generate 1 data point for every other pixel. A value of `1/10` will try to set step option so there is a data point every 10 pixels. | | _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. | | _Metric lookup_ | Search for metric names in this input field. |
| _Format as_ | Switch between Table, Time series or Heatmap. Table format will only work in the Table panel. Heatmap format is suitable for displaying metrics having histogram type on Heatmap panel. Under the hood, it converts cumulative histogram to regular 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. | | _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. |
> NOTE: Grafana slightly modifies the request dates for queries to align them with the dynamically calculated step. > NOTE: Grafana slightly modifies the request dates for queries to align them with the dynamically calculated step.
> This ensures consistent display of metrics data but can result in a small gap of data at the right edge of a graph. > This ensures consistent display of metrics data but can result in a small gap of data at the right edge of a graph.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment