mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
update prometheus query editor doc (#68595)
* initial updates to outdated info * minor edits prior to draft PR * commented out options no longer available * additional edits * removed tables, changed format to list * updated code mode section * finished edits to builder mode * added revisions per Brendan * removed commented out section * added note short codes
This commit is contained in:
lwandz13
GitHub
@@ -14,35 +14,46 @@ weight: 300
|
||||
|
||||
# Prometheus query editor
|
||||
|
||||
This topic explains querying specific to the Prometheus data source.
|
||||
Grafana provides a query editor for the Prometheus data source to create queries in PromQL. For more information about PromQL, see [Querying Prometheus](http://prometheus.io/docs/querying/basics/).
|
||||
|
||||
For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
|
||||
|
||||
For options and functions common to all query editors, see [Query editors]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
|
||||
|
||||
## Choose a query editing mode
|
||||
|
||||
You can switch the Prometheus query editor between two modes:
|
||||
The Prometheus query editor has two modes:
|
||||
|
||||
- [Code mode](#code-mode), which provides a feature-rich editor for writing queries
|
||||
- [Builder mode](#builder-mode), which provides a visual query designer
|
||||
- [Builder mode](#builder-mode)
|
||||
- [Code mode](#code-mode)
|
||||
|
||||
Each mode is explained in greater detail below.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/editing-mode.png" max-width="500px" class="docs-image--no-shadow" caption="Query editor mode" >}}
|
||||
|
||||
To switch between the editor modes, select the corresponding **Builder** and **Code** tabs.
|
||||
Both modes are synchronized, so you can switch between them. However, if there is an issue with the query while switching modes, a warning message will appear.
|
||||
|
||||
To run a query, select **Run query** in the upper right of the editor.
|
||||
## Toolbar elements
|
||||
|
||||
Each mode is synchronized with the other modes, so you can switch between them without losing your work, although there are some limitations.
|
||||
The query editor toolbar contains the following elements:
|
||||
|
||||
Builder mode doesn't yet support some complex queries.
|
||||
When you switch from Code mode to Builder mode with such a query, the editor displays a popup that explains how you might lose parts of the query if you continue.
|
||||
You can then decide whether you still want to switch to Builder mode.
|
||||
- **Kick start your query** - Click to see a list of operation patterns that help you quickly get started adding multiple operations to your query. These include:
|
||||
|
||||
You can also use the [Explain feature]({{< relref "#use-explain-mode-to-understand-queries" >}}) to help understand how a query works, and augment queries by using [template variables]({{< relref "./template-variables/" >}}).
|
||||
- Rate query starters
|
||||
- Histogram query starters
|
||||
- Binary query starters
|
||||
|
||||
For options and functions common to all query editors, refer to [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
|
||||
Click the arrow next to each to see available options to add to your query.
|
||||
|
||||
- **Explain** - Toggle to display a step-by-step explanation of all query components and operations.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/explain-results.png" max-width="500px" class="docs-image--no-shadow" caption="Explain results" >}}
|
||||
|
||||
- **Builder/Code** - Click the corresponding **Builder** or **Code** tab on the toolbar to select a editor mode.
|
||||
|
||||
## Configure common options
|
||||
|
||||
You can configure Prometheus-specific options in the query editor by setting several options regardless of its mode.
|
||||
You can configure Prometheus-specific options in the query editor by setting several options regardless of mode.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/options.png" max-width="500px" class="docs-image--no-shadow" caption="Options" >}}
|
||||
|
||||
@@ -50,11 +61,9 @@ You can configure Prometheus-specific options in the query editor by setting sev
|
||||
|
||||
The **Legend** setting defines the time series's name. You can use a predefined or custom format.
|
||||
|
||||
| Option | Description |
|
||||
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Auto** | Shows the value of a single label for each series with only one label, or displays all labels if a series has multiple labels. |
|
||||
| **Verbose** | Displays all label names. |
|
||||
| **Custom** | Uses templating to select which labels will be included.<br/>For example, `{{hostname}}` is replaced by the label value for the label `hostname`.<br/>Clear the input and click outside of it to select another mode. |
|
||||
- **Auto** - Displays unique labels. Also displays all overlapping labels if a series has multiple labels.
|
||||
- **Verbose** - Displays all label names.
|
||||
- **Custom** - Uses templating to select which labels will be included. For example, `{{hostname}}` is replaced by the label value for the label `hostname`. Clear the input and click outside of it to select another mode.
|
||||
|
||||
### Min step
|
||||
|
||||
@@ -64,101 +73,61 @@ This setting supports the `$__interval` and `$__rate_interval` macros.
|
||||
|
||||
### Format
|
||||
|
||||
You can switch between **Table**, **Time series**, and **Heatmap** options by configuring the query's **Format**.
|
||||
Switch between the following format options:
|
||||
|
||||
| Option | Description |
|
||||
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Table** | This works only in a [Table panel]({{< relref "../../../panels-visualizations/visualizations/table" >}}). |
|
||||
| **Time series** | Uses the default time series format. |
|
||||
| **Heatmap** | Displays metrics of the Histogram type on a [Heatmap panel]({{< relref "../../../panels-visualizations/visualizations/heatmap" >}}) by converting cumulative histograms to regular ones and sorting the series by the bucket bound. |
|
||||
- **Time series** - The default time series format. See [Time series kind formats](https://grafana.github.io/dataplane/timeseries/) for information on time series data frames and how time and value fields are structured.
|
||||
- **Table** - This works only in a [Table panel]({{< relref "../../../panels-visualizations/visualizations/table" >}}).
|
||||
- **Heatmap** - Displays metrics of the Histogram type on a [Heatmap panel]({{< relref "../../../panels-visualizations/visualizations/heatmap" >}}) by converting cumulative histograms to regular ones and sorting the series by the bucket bound.
|
||||
|
||||
### Type
|
||||
|
||||
The **Type** setting selects the query type.
|
||||
The **Type** setting sets the query type. These include:
|
||||
|
||||
- A **Range** query returns a Range vector, comprised of a set of time series containing a range of data points over time for each time series.
|
||||
- An **Instant** query returns only the latest value that Prometheus has scraped for the requested time series. Instant queries can return results much faster than normal range queries and are well suited to look up label sets.
|
||||
- **Both** - The default option. Returns results for both a **Range** query and an **Instant** query.
|
||||
- **Range** - Returns a range vector consisting of a set of time series data containing a range of data points over time for each time series. You can choose lines, bars, points, stacked lines or stacked bars
|
||||
- **Instant** - Returns one data point per query and only the most recent point in the time range provided. The results can be shown in table format or as raw data. To depict instant query results in the time series panel, first add a field override, next add a property to the override named `Transform`, and finally select `Constant` from the **Transform** dropdown.
|
||||
|
||||
Instant query results are comprised of only one data point per series and can be shown in the time series panel by adding a field override, adding a property to the override named `Transform`, and selecting `Constant` from the **Transform** dropdown.
|
||||
|
||||
For more information, refer to the [Time Series Transform option documentation]({{< relref "../../../panels-visualizations/visualizations/time-series#transform" >}}).
|
||||
|
||||
- An **Exemplars** query runs with the regular query and shows exemplars in the graph.
|
||||
For more information, refer to the [Time Series Transform option documentation]({{< relref "../../../panels-visualizations/visualizations/time-series#transform" >}}).
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Grafana modifies the request dates for queries to align them with the dynamically calculated step.
|
||||
This ensures a consistent display of metrics data, but it can result in a small gap of data at the right edge of a graph.
|
||||
{{% /admonition %}}
|
||||
|
||||
## Code mode
|
||||
### Exemplars
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/code-mode.png" max-width="500px" class="docs-image--no-shadow" caption="Code mode" >}}
|
||||
|
||||
In **Code mode**, you can write complex queries using a text editor with autocompletion features and syntax highlighting.
|
||||
It also contains a [Metrics browser]({{< relref "#metrics-browser" >}}) to further help you write queries.
|
||||
|
||||
For more information about Prometheus's query language (PromQL), see [Querying Prometheus](http://prometheus.io/docs/querying/basics/).
|
||||
|
||||
### Use autocompletion
|
||||
|
||||
Code mode's autocompletion feature works automatically while typing.
|
||||
|
||||
The query editor can autocomplete static functions, aggregations, keywords, and also dynamic items like metrics and labels.
|
||||
The autocompletion dropdown includes documentation for the suggested items where available.
|
||||
|
||||
To run a query in [Explore]({{< relref "../../../explore/" >}}), use the keyboard shortcut <key>Shift</key> + <key>Enter</key>.
|
||||
|
||||
### Metrics browser
|
||||
|
||||
The metrics browser locates metrics and selects relevant labels to help you build basic queries.
|
||||
When you open the browser, it displays all available metrics and labels.
|
||||
If supported by your Prometheus instance, each metric also displays its HELP and TYPE as a tooltip.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/metric-browser.png" max-width="500px" class="docs-image--no-shadow" caption="Metrics browser" >}}
|
||||
|
||||
When you select a metric, the browser narrows down the available labels to show only the ones applicable to the metric.
|
||||
You can then select one or more labels for which the available label values are shown in lists in the bottom section.
|
||||
Select one or more values for each label to tighten your query scope.
|
||||
Toggle **Exemplars** to run a query that includes exemplars in the graph. Exemplars are unique to Prometheus. For more information see [Introduction to exemplars](https://grafana.com/docs/grafana/latest/fundamentals/exemplars/).
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
If you do not remember a metric name to start with, you can also select a few labels to narrow down the list, then find relevant label values.
|
||||
There is no option to add exemplars with an **Instant** query type.
|
||||
{{% /admonition %}}
|
||||
|
||||
All lists in the metrics browser have a search field above them to quickly filter for metrics or labels that match a certain string.
|
||||
The values section has only one search field, and its filtering applies to all labels to help you find values across labels once selected.
|
||||
### Inspector
|
||||
|
||||
For example, among your labels `app`, `job`, `job_name` only one might with the value you are looking for.
|
||||
Click **Inspector** to get detailed statistics regarding your query. Inspector functions as a kind of debugging tool that "inspects" your query. It provides query statistics under **Stats**, request response time under **Query**, data frame details under **{} JSON**, and the shape of your data under **Data**.
|
||||
|
||||
Once you are satisfied with your query, click "Use query" to run the query. The button "Use as rate query" adds a `rate(...)[$__interval]` around your query to help write queries for counter metrics.
|
||||
The "Validate selector" button will check with Prometheus how many time series are available for that selector.
|
||||
{{< figure src="/static/img/docs/prometheus/insepctor-9-5.png" max-width="500px" class="docs-image--no-shadow" caption="Inspector" >}}
|
||||
|
||||
## Builder mode
|
||||
|
||||
In **Builder mode**, you can build queries using a visual interface.
|
||||
**Builder mode** helps you build queries using a visual interface. This option is best for users who have limited or no previous experience working with Prometheus and PromQL.
|
||||
|
||||
This video demonstrates how to use the visual Prometheus query builder available since Grafana v9.0:
|
||||
This video demonstrates how to use the visual Prometheus query builder available in Grafana v9.0:
|
||||
|
||||
{{< vimeo 720004179 >}}
|
||||
|
||||
</br>
|
||||
|
||||
### Toolbar
|
||||
|
||||
In addition to the **Run query** button and mode switcher, Builder mode includes additional elements:
|
||||
|
||||
| Name | Description |
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| **Kick start your query** | A list of operation patterns that help you quickly add multiple operations to your query. |
|
||||
| **Explain** | Displays a step-by-step explanation of all query parts and its operations. |
|
||||
|
||||
### Metric and labels
|
||||
### Metrics
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/metrics-and-labels.png" max-width="500px" class="docs-image--no-shadow" caption="Metric and label filters" >}}
|
||||
|
||||
Select a specific metric name from the dropdown list.
|
||||
When you are ready to create a query, you can choose the specific metric name from the dropdown list under **Metric**.
|
||||
The data source requests the list of available metrics from the Prometheus server based on the selected time rage.
|
||||
You can also enter text into the selector when the dropdown is open to search and filter the list.
|
||||
|
||||
### Label filters
|
||||
|
||||
Select desired labels and their values from the dropdown list.
|
||||
When a metric is selected, the data source requests available labels and their values from the server.
|
||||
Use the `+` button to add a label, and the `x` button to remove a label.
|
||||
@@ -167,53 +136,71 @@ Use the `+` button to add a label, and the `x` button to remove a label.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/operations.png" max-width="500px" class="docs-image--no-shadow" caption="Operations" >}}
|
||||
|
||||
Select the `+ Operations` button to add operations to your query.
|
||||
The query editor groups operations into related sections, and you can type while the operations dropdown is open to search and filter the list.
|
||||
Select the **+ Operations** button to add operations to your query.
|
||||
|
||||
The query editor displays a query's operations as boxes in the operations section.
|
||||
Each operation's header displays its name, and additional action buttons appear when you hover your cursor over the header:
|
||||
The query editor groups operations into the following sections:
|
||||
|
||||
| Button | Action |
|
||||
| ------ | ----------------------------------------------------------------- |
|
||||
| `v` | Replaces the operation with different operation of the same type. |
|
||||
| `info` | Opens the operation's description tooltip. |
|
||||
| `x` | Removes the operation. |
|
||||
- Aggregations - for additional information see [Aggregation operators](https://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators).
|
||||
- Range functions - for additional information see [Functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#functions).
|
||||
- Functions - for additional information see [Functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#functions).
|
||||
- Binary operations - for additional information see [Binary operators](https://prometheus.io/docs/prometheus/latest/querying/operators/#binary-operators).
|
||||
- Trigonometric - for additional information see [Trigonometric functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#trigonometric-functions).
|
||||
- Time functions - for additional information see [Functions](https://prometheus.io/docs/prometheus/latest/querying/functions/#functions).
|
||||
|
||||
Some operations have additional parameters under the operation header.
|
||||
For details about each operation, use the `info` button to view the operation's description, or refer to the Prometheus documentation on [query functions](https://prometheus.io/docs/prometheus/latest/querying/functions/).
|
||||
All operations have function parameters under the operation header. Click the `operator` to see a full list of supported functions. Some operations allow you to apply specific labels to functions.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/use-function-by-label-9-5.png" max-width="500px" class="docs-image--no-shadow" caption="Functions and labels" >}}
|
||||
|
||||
Some operations make sense only when used in a specific order.
|
||||
If adding an operation would result in nonsensical query, the query editor adds the operation to the correct place.
|
||||
To re-order operations manually, drag the operation box by its name and drop it into the desired place.
|
||||
|
||||
#### Hints
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/hint-example.png" max-width="500px" class="docs-image--no-shadow" caption="Hint" >}}
|
||||
|
||||
The query editor can detect which operations are most appropriate for some selected metrics.
|
||||
If it does, it displays a hint next to the `+ Operations` button.
|
||||
If it does, it displays a hint next to the **+ Operations** button.
|
||||
|
||||
To add the operation to your query, click the `hint`.
|
||||
To add the operation to your query, click the **Hint**.
|
||||
|
||||
## Use Explain mode to understand queries
|
||||
Once you are satisfied with your query, click **Run query**.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/explain-results.png" max-width="500px" class="docs-image--no-shadow" caption="Explain results" >}}
|
||||
## Code mode
|
||||
|
||||
Explain mode helps you understand a query by displaying a step-by-step explanation of all query components and operations.
|
||||
**Code mode** is for the experienced Prometheus user with prior expertise in PromQL, Prometheus' query language. The Code mode editor allows you to create queries just as you would in Prometheus. For more information about PromQL see [Querying Prometheus](http://prometheus.io/docs/querying/basics/).
|
||||
|
||||
### Additional options
|
||||
{{< figure src="/static/img/docs/prometheus/code-mode.png" max-width="500px" class="docs-image--no-shadow" caption="Code mode" >}}
|
||||
|
||||
In addition to these Builder mode-specific options, the query editor also displays the options it shares in common with Code mode.
|
||||
For details, refer to the [common options]({{< relref "#configure-common-options" >}}).
|
||||
The user interface (UI) also lets you select metrics, labels, filters and operations.
|
||||
|
||||
## Apply annotations
|
||||
You can write complex queries using the text editor with autocompletion features and syntax highlighting.
|
||||
It also contains a [Metrics browser]({{< relref "#metrics-browser" >}}) to further help you write queries.
|
||||
|
||||
[Annotations]({{< relref "../../../dashboards/build-dashboards/annotate-visualizations" >}}) overlay rich event information on top of graphs.
|
||||
You can add annotation queries in the Dashboard menu's Annotations view.
|
||||
### Use autocomplete
|
||||
|
||||
Prometheus supports two ways to query annotations.
|
||||
Code mode's autocomplete feature works automatically while typing. The query editor can autocomplete static functions, aggregations, keywords, and also dynamic items like metrics and labels.
|
||||
The autocompletion dropdown includes documentation for the suggested items where available.
|
||||
|
||||
- A regular metric query
|
||||
- A Prometheus query for pending and firing alerts (for details see [Inspecting alerts during runtime](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/#inspecting-alerts-during-runtime))
|
||||
### Metrics browser
|
||||
|
||||
The step option is useful to limit the number of events returned from your query.
|
||||
The metrics browser locates metrics and selects relevant labels to help you build basic queries.
|
||||
When you click **Metrics browser**, it displays all available metrics and labels.
|
||||
If supported by your Prometheus instance, each metric also displays its `HELP` and `TYPE` as a tooltip.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/metric-browser.png" max-width="500px" class="docs-image--no-shadow" caption="Metrics browser" >}}
|
||||
|
||||
When you select a metric under Step 1, the browser narrows down the available labels to show only the ones applicable to the metric.
|
||||
You can then select one or more labels shown in Step 2.
|
||||
Select one or more values in Step 3 for each label to tighten your query scope.
|
||||
In Step 4, you can select **Use query** to run the query, **Use as rate query** to add the rate operation to your query (`$__rate_interval`), **Validate selector** to verify the selector is valid and show the number of series found, or **Clear** to clear your selections and start over.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
If you do not remember a metric name, you can also select a few labels to narrow down the list, then find relevant label values.
|
||||
{{% /admonition %}}
|
||||
|
||||
All lists in the metrics browser have a search field above them to quickly filter for metrics or labels that match a certain string.
|
||||
The values section has only one search field, and its filtering applies to all labels to help you find values across labels once selected.
|
||||
|
||||
For example, among your labels `app`, `job`, `job_name` only one might have the value you are looking for.
|
||||
|
||||
Once you are satisfied with your query, click **Run query**.
|
||||
|
||||
Reference in New Issue
Block a user