public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs/panel refactor (#43569)

Browse Source 
* new refactored panel docs

* fixed links

* removed xtra sharing link, added links to panel display option tasks

* fixed typo

* add aliases

* incorporate PM feedback

* intermediate commit to resolve merge conflict

* final changes to resolve merge conflicts
This commit is contained in:
Christopher Moyer
2022-01-18 15:06:27 -06:00
committed by GitHub
parent 959723050f
commit 449c608ef1
118 changed files with 2043 additions and 1668 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/panels/query-a-data-source/_index.md
+11
View File
@@ -0,0 +1,11 @@
+++
title = "Query a data source"
aliases = ["/docs/grafana/latest/panels/queries/", "/docs/grafana/latest/panels/expressions/", "/docs/grafana/latest/panels/inspect-panel/", "/docs/grafana/latest/panels/share-query-results/", "/docs/sources/panels/query-a-data-source/_index/"]
weight = 200
+++
# Query a data source
Data source queries return data that appear in visualizations. The query language in which you write depends on the data source you query. Grafana supports connections with many types of data sources.
{{< section >}}
docs/sources/panels/query-a-data-source/about-queries.md
+55
View File
@@ -0,0 +1,55 @@
+++
title = "About queries"
weight = 10
aliases = ["/docs/sources/panels/query-a-data-source/about-queries/"]
+++
# About queries
_Queries_ are how Grafana panels communicate with data sources to get data for the visualization. A query is a question written in the query language used by the data source. How often the query is sent to the data source and how many data points are collected can be adjusted in the panel data source options.
Use you a query editor to write a query. Each data source has its own query editor that we have customized to include the features and capabilities of the data source. Grafana supports up to 26 queries per panel.
> Important! You must be familiar with the query language of the data source. For more information about data sources, refer to [Data sources](../../../datasources/).
## Query editors
Depending on your data source, the query editor might provide auto-completion, metric names, or variable suggestions.
Because of the difference between query languages, data sources have query editors that look different. Here are two examples of query editors.
**InfluxDB query editor**
{{< figure src="/static/img/docs/queries/influxdb-query-editor-7-2.png" class="docs-image--no-shadow" max-width="1000px" >}}
**Prometheus (PromQL) query editor**
{{< figure src="/static/img/docs/queries/prometheus-query-editor-7-4.png" class="docs-image--no-shadow" max-width="1000px" >}}
## Query syntax
Data sources use different query languages to return data. Here are two query examples:
**PostgreSQL**
```
SELECT hostname FROM host WHERE region IN($region)
```
**PromQL**
```
query_result(max_over_time(<metric>[${__range_s}s]) != <state>)
```
## Data sources used in queries
In addition to the data sources that you have configured in Grafana, there are three special data sources available:
- **Grafana -** A built-in data source that generates random walk data, which can be useful for testing visualizations and running experiments.
- **Mixed -** Select this option to query multiple data sources in the same panel. When you select this data source, Grafana enables you to select a data source for every new query that you add.
- The first query uses the data source that was selected before you selected **Mixed**.
- You cannot change an existing query to use the Mixed Data Source.
- **Dashboard -** Select this option to use a result set from another panel in the same dashboard.
You can combine data from multiple data sources onto a single dashboard, but each panel is tied to a specific data source that belongs to a particular Organization.
docs/sources/panels/query-a-data-source/add-a-query.md
+30
View File
@@ -0,0 +1,30 @@
+++
title = "Add a query"
weight = 30
aliases = ["/docs/sources/panels/query-a-data-source/add-a-query/"]
+++
# Add a query
A query returns data that Grafana visualizes in dashboards. When you create a panel, Grafana automatically selects the default data source.
## Before you begin
- [Add a data source](../../../datasources/add-a-data-source).
- Ensure that you know the query language of the data source.
- [Add a panel]({{< relref "../working-with-panels/add-panel.md" >}}).
**To add a query**:
1. Edit the panel to which you are adding a query.
1. Click the **Query** tab.
1. Click the **Data source** drop-down menu and select a data source.
1. Click **Query options** to configure the maximum number of data points returned by the query and how frequently you want the query to request data from the data source.
For more information about query options, refer to [Reference: Query options]({{< relref "../reference-query-options.md" >}}).
1. Write the query.
1. Click **Apply**.
The system queries the data source and presents the data in the visualization.
docs/sources/panels/query-a-data-source/download-raw-query-results.md
+30
View File
@@ -0,0 +1,30 @@
+++
title = "Download raw query results"
weight = 70
aliases = ["/docs/sources/panels/query-a-data-source/download-raw-query-results/"]
+++
# Download raw query results
Grafana generates a CSV file that contains your data, including any transformations to that data. You can choose to view the data before or after the panel applies field options or field option overrides.
## Before you begin
- [Add a panel to a dashboard]({{< relref "../working-with-panels/add-panel.md" >}}).
- [Add a query]({{< relref "../query-a-data-source/add-a-query.md" >}}).
**To download raw query results**:
1. Edit the panel that contains the query data you want to download.
1. In the query editor, click **Query Inspector**.
1. Click **Data**.
If your panel contains multiple queries or queries multiple nodes, then you have additional options.
- **Select result**: Choose which result set data you want to view.
- **Transform data**
- **Join by time**: View raw data from all your queries at once, one result set per column. Click a column heading to reorder the data.
1. To see data before the system applies field overrides, click the **Formatted data** toggle.
1. To download a CSV file specifically formatted for Excel, click the **Download for Excel** toggle .
1. Click **Download CSV**.
docs/sources/panels/query-a-data-source/inspect-query-performance.md
+22
View File
@@ -0,0 +1,22 @@
+++
title = "Inspect query performance"
weight = 80
aliases = ["/docs/sources/panels/query-a-data-source/inspect-query-performance/"]
+++
# Inspect query performance
The **Stats** tab displays statistics that tell you how long your query takes, how many queries you send, and the number of rows returned. This information can help you troubleshoot your queries, especially if any of the numbers are unexpectedly high or low.
## Before you begin
- [Add a panel to a dashboard]({{< relref "../working-with-panels/add-panel.md" >}}).
- [Add a query]({{< relref "../query-a-data-source/add-a-query.md" >}}).
**To inspect query performance**:
1. Edit the panel that contains the query with performance you want to inspect.
1. In the query editor, click **Query Inspector**.
1. Click **Stats**.
Statistics are displayed in read-only format.
docs/sources/panels/query-a-data-source/inspect-request-and-response-data.md
+25
View File
@@ -0,0 +1,25 @@
+++
title = "Inspect query request and response data"
weight = 90
aliases = ["/docs/sources/panels/query-a-data-source/inspect-request-and-response-data/"]
+++
# Inspect query request and response data
Inspect query request and response data when you want to troubleshoot a query that returns unexpected results, or fails to return expected results.
## Before you begin
- [Add a panel to a dashboard]({{< relref "../working-with-panels/add-panel.md" >}}).
- [Add a query]({{< relref "../query-a-data-source/add-a-query.md" >}}).
**To inspect query request and response data**:
1. Edit the panel that contains the query you want to export.
1. In the query editor, click **Query Inspector**.
1. Click **Refresh**.
The panel populates with response data.
1. Make adjustments, as necessary and re-run the query.
1. To download the query request and response data, click the **Copy to clipboard** icon and paste the results into another application.
docs/sources/panels/query-a-data-source/manage-queries.md
+19
View File
@@ -0,0 +1,19 @@
+++
title = "Manage queries"
weight = 50
aliases = ["/docs/sources/panels/query-a-data-source/manage-queries/"]
+++
# Manage queries
Queries are organized in collapsible query rows. Each query row contains a query editor and is identified with a letter (A, B, C, and so on).
You can:
| Icon | Description |
| :-----------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| {{< figure src="/static/img/docs/queries/query-editor-help-7-4.png" class="docs-image--no-shadow" max-width="30px" max-height="30px" >}} | Toggle query editor help. If supported by the data source, click this icon to display information on how to use the query editor or provide quick access to common queries. |
| {{< figure src="/static/img/docs/queries/duplicate-query-icon-7-0.png" class="docs-image--no-shadow" max-width="30px" max-height="30px" >}} | Copy a query. Duplicating queries is useful when working with multiple complex queries that are similar and you want to either experiment with different variants or do minor alterations. |
| {{< figure src="/static/img/docs/queries/hide-query-icon-7-0.png" class="docs-image--no-shadow" max-width="30px" max-height="30px" >}} | Hide a query. Grafana does not send hidden queries to the data source. |
| {{< figure src="/static/img/docs/queries/remove-query-icon-7-0.png" class="docs-image--no-shadow" max-width="30px" max-height="30px" >}} | Remove a query. Removing a query permanently deletes it, but sometimes you can recover deleted queries by reverting to previously saved versions of the panel. |
| {{< figure src="/static/img/docs/queries/query-drag-icon-7-2.png" class="docs-image--no-shadow" max-width="30px" max-height="30px" >}} | Reorder queries. Change the order of queries by clicking and holding the drag icon, then drag queries where desired. The order of results reflects the order of the queries, so you can often adjust your visual results based on query order. |
docs/sources/panels/query-a-data-source/navigate-query-tab.md
+17
View File
@@ -0,0 +1,17 @@
+++
title = "Navigate the query tab"
weight = 20
aliases = ["/docs/sources/panels/query-a-data-source/navigate-query-tab/"]
+++
# Navigate the query tab
The Query tab consists of the following elements:
- Data source selector: Use the data source selector to select the source of the data you want to query. For more information about data sources, refer to [Data sources](../../../datasources/).
- Query options: Enables you to set maximum data retrieved parameters and query execution time intervals.
- Query inspector button: Open the query inspector panel where you can view and optimize your query.
- Query editor list: Lists the queries you have written.
- Expressions: Use the expression builder to create alert expressions. For more information about expressions, refer to [Use expressions to manipulate data](../use-expressions-to-manipulate-data/).
{{< figure src="/static/img/docs/queries/query-editor-7-2.png" class="docs-image--no-shadow" max-width="1000px" >}}
docs/sources/panels/query-a-data-source/share-query.md
+29
View File
@@ -0,0 +1,29 @@
+++
title = "Share query results with another panel"
weight = 60
aliases = ["/docs/sources/panels/query-a-data-source/share-query/"]
+++
# Share query results with another panel
Grafana let you use the query result from one panel for any other panel in the dashboard. Sharing query results across panels reduces the number of queries made to your data source, which can improve the performance of your dashboard.
The Dashboard data source lets you select a panel in your dashboard that contains the queries ‌you want to share the results for. Instead of sending a separate query for each panel, Grafana sends one query and other panels use the query results to construct visualizations.
This strategy can drastically reduce the number of queries being made when you for example have several panels visualizing the same data.
**To share data source queries with another panel**:
1. [Create a dashboard]({{< relref "../../getting-started/getting-started.md/#step-3-create-a-dashboard" >}}).
1. [Add a panel to a dashboard]({{< relref "../working-with-panels/add-panel.md" >}}).
1. Change the title to "Source panel". You'll use this panel as a source for the other panels.
1. Define the [query]({{< relref "../query-a-data-source/add-a-query.md" >}}) or queries that you want share.
If you don't have a data source available, use the **Grafana** data source, which returns a random time series that you can use for testing.
1. Add a second panel and select the **Dashboard** data source in the query editor.
1. In the **Use results from panel list**, select the first panel you created.
All queries defined in the source panel are now available to the new panel. Queries made in the source panel can be shared with multiple panels.
You can click on any of the queries to go to the panel where they are defined.
docs/sources/panels/query-a-data-source/use-expressions-to-manipulate-data/_index.md
+11
View File
@@ -0,0 +1,11 @@
+++
title = "Use expressions to manipulate data"
weight = 40
aliases = ["/docs/sources/panels/query-a-data-source/use-expressions-to-manipulate-data/"]
+++
# Use expressions to manipulate data
Server-side expressions enable you to manipulate data returned from queries with math and other operations. Expressions create new data and do not manipulate the data returned by data sources.
{{< section >}}
docs/sources/panels/query-a-data-source/use-expressions-to-manipulate-data/about-expressions.md
+172
View File
@@ -0,0 +1,172 @@
+++
title = "About expressions"
weight = 10
aliases = ["/docs/sources/panels/query-a-data-source/use-expressions-to-manipulate-data/about-expressions/"]
+++
# About expressions
> **Note:** This documentation is for a beta feature.
Server-side expressions allow you to manipulate data returned from queries with math and other operations. Expressions create new data and do not manipulate the data returned by data sources, aside from some minor data restructuring to make the data acceptable input for expressions.
## Using expressions
Expressions are primarily used by the new [Grafana 8 alerts]({{< relref "../../../alerting/unified-alerting/_index.md" >}}). The processing is done server-side, so expressions can operate without a browser session. However, expressions can also be used with backend data sources and visualization.
> **Note:** Expressions do not work with legacy dashboard alerts.
> **Note:** Expressions do not work with dashboard variables.
Expressions are meant to augment data sources by enabling queries from different data sources to be combined or by providing operations unavailable in a data source.
> **Note:** When possible, you should do data processing inside the data source. Copying data from storage to the Grafana server for processing is inefficient, so expressions are targeted at lightweight data processing.
Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data]({{< relref "../../../basics/timeseries-dimensions.md" >}}). For example, a query that returns multiple series, where each series is identified by labels or tags.
An individual expression takes one or more queries or other expressions as input and adds data to the result. Each individual expression or query is represented by a variable that is a named identifier known as its RefID (e.g., the default letter `A` or `B`).
To reference the output of an individual expression or a data source query in another expression, this identifier is used as a variable.
## Types of expressions
Expressions work with two types of data.
- A collection of time series.
- A collection of numbers, where each number is an item.
Each collection is returned from a single data source query or expression and represented by the RefID. Each collection is a set, where each item in the set is uniquely identified by its dimensions which are stored as [labels]({{< relref "../../../basics/timeseries-dimensions.md#labels" >}}) or key-value pairs.
## Data source queries
Server-side expressions only support data source queries for backend data sources. The data is generally assumed to be labeled time series data. In the future we intended to add an assertion of the query return type (number or time series) data so expressions can handle errors better.
Data source queries, when used with expressions, are executed by the expression engine. When it does this, it restructures data to be either one time series or one number per data frame. So for example if using a data source that returns multiple series on one frame in the table view, you might notice it looks different when executed with expressions.
Currently, the only non-time series format (number) is supported when using data frames are you have a table response that returns a data frame with no time, string columns, and one number column:
| Loc | Host | Avg_CPU |
| --- | ---- | ------- |
| MIA | A | 1 |
| NYC | B | 2 |
The example above will produce a number that works with expressions. The string columns become labels and the number column the corresponding value. For example `{"Loc": "MIA", "Host": "A"}` with a value of 1.
## Operations
You can use the following operations in expressions: math, reduce, and resample.
### Math
Math is for free-form math formulas on time series or number data. Math operations take numbers and time series as input and changes them to different numbers and time series.
Data from other queries or expressions are referenced with the RefID prefixed with a dollar sign, for example `$A`. If the variable has spaces in the name, then you can use a brace syntax like `${my variable}`.
Numeric constants may be in decimal (`2.24`), octal (with a leading zero like `072`), or hex (with a leading 0x like `0x2A`). Exponentials and signs are also supported (e.g., `-0.8e-2`).
#### Operators
The arithmetic (`+`, binary and unary `-`, `*`, `/`, `%`, exponent `**`), relational (`<`, `>`, `==`, `!=`, `>=`, `<=`), and logical (`&&`, `||`, and unary `!`) operators are supported.
How the operation behaves with data depends on if it is a number or time series data.
With binary operations, such as `$A + $B` or `$A || $B`, the operator is applied in the following ways depending on the type of data:
- If both `$A` and `$B` are a number, then the operation is performed between the two numbers.
- If one variable is a number, and the other variable is a time series, then the operation between the value of each point in the time series and the number is performed.
- If both `$A` and `$B` are time series data, then the operation between each value in the two series is performed for each time stamp that exists in both `$A` and `$B`. The Resample operation can be used to line up time stamps. (**Note:** in the future, we plan to add options to the Math operation for different behaviors).
Summary:
- Number OP number = number
- Number OP series = series
- Series OP series = series
Because expressions work with multiple series or numbers represented by a single variable, binary operations also perform a union (join) between the two variables. This is done based on the identifying labels associated with each individual series or number.
So if you have numbers with labels like `{host=web01}` in `$A` and another number in `$B` with the same labels then the operation is performed between those two items within each variable, and the result will share the same labels. The rules for the behavior of this union are as follows:
- An item with no labels will join to anything.
- If both `$A` and `$B` each contain only one item (one series, or one number), they will join.
- If labels are exact math they will join.
- If labels are a subset of the other, for example and item in `$A` is labeled `{host=A,dc=MIA}` and and item in `$B` is labeled `{host=A}` they will join.
- Currently, if within a variable such as `$A` there are different tag _keys_ for each item, the join behavior is undefined.
The relational and logical operators return 0 for false 1 for true.
#### Math Functions
While most functions exist in the own expression operations, the math operation does have some functions that similar to math operators or symbols. When functions can take either numbers or series, than the same type as the argument will be returned. When it is a series, the operation of performed for the value of each point in the series.
##### abs
abs returns the absolute value of its argument which can be a number or a series. For example `abs(-1)` or `abs($A)`.
##### is_inf
is_inf takes a number or a series and returns `1` for `Inf` values (negative or positive) and `0` for other values. For example `is_inf($A)`.
> **Note:** If you need to specifically check for negative infinity for example, you can do a comparison like `$A == infn()`.
##### is_nan
is_nan takes a number or a series and returns `1` for `NaN` values and `0` for other values. For example `is_nan($A)`. This function exists because `NaN` is not equal to `NaN`.
##### is_null
is_nan takes a number or a series and returns `1` for `null` values and `0` for other values. For example `is_null($A)`.
##### is_number
is_number takes a number or a series and returns `1` for all real number values and `0` for other values (which are `null`, `Inf+`, `Inf-`, and `NaN`). For example `is_number($A)`.
##### log
Log returns the natural logarithm of of its argument which can be a number or a series. If the value is less than 0, NaN is returned. For example `log(-1)` or `log($A)`.
##### inf, infn, nan, and null
The inf, infn, nan, and null functions all return a single value of the name. They primarily exist for testing. Example: `null()`.
### Reduce
Reduce takes one or more time series returned from a query or an expression and turns each series into a single number. The labels of the time series are kept as labels on each outputted reduced number.
**Fields:**
- **Function -** The reduction function to use
- **Input -** The variable (refID (such as `A`)) to resample
#### Reduction Functions
> **Note:** In the future we plan to add options to control empty, NaN, and null behavior for reduction functions.
##### Count
Count returns the number of points in each series.
##### Mean
Mean returns the total of all values in each series divided by the number of points in that series. If any values in the series are null or nan, or if the series is empty, NaN is returned.
##### Min and Max
Min and Max return the smallest or largest value in the series respectively. If any values in the series are null or nan, or if the series is empty, NaN is returned.
##### Sum
Sum returns the total of all values in the series. If series is of zero length, the sum will be 0. If there are any NaN or Null values in the series, NaN is returned.
### Resample
Resample changes the time stamps in each time series to have a consistent time interval. The main use case is so you can resample time series that do not share the same timestamps so math can be performed between them. This can be done by resample each of the two series, and then in a Math operation referencing the resampled variables.
**Fields:**
- **Input -** The variable of time series data (refID (such as `A`)) to resample
- **Resample to -** The duration of time to resample to, for example `10s`. Units may be `s` seconds, `m` for minutes, `h` for hours, `d` for days, `w` for weeks, and `y` of years.
- **Downsample -** The reduction function to use when there are more than one data point per window sample. See the reduction operation for behavior details.
- **Upsample -** The method to use to fill a window sample that has no data points.
- **pad** fills with the last know value
- **backfill** with next known value
- **fillna** to fill empty sample windows with NaNs
docs/sources/panels/query-a-data-source/use-expressions-to-manipulate-data/write-an-expression.md
+26
View File
@@ -0,0 +1,26 @@
+++
title = "Write an expression"
weight = 20
aliases = ["/docs/sources/panels/query-a-data-source/use-expressions-to-manipulate-data/write-an-expression/"]
+++
# Write an expression
If your data source supports them, then Grafana displays the **Expression** button and shows any existing expressions in the query editor list.
For more information about expressions, refer to [About expressions]({{< relref "./about-expressions.md" >}}).
## Before you begin
- [Add a panel]({{< relref "../../working-with-panels/add-panel.md" >}}).
**To write an expression**:
1. Open the panel.
1. Below the query, click **Expression**.
1. In the **Operation** field, select the type of expression you want to write.
For more information about expression operations, refer to [About expressions]({{< relref "./about-expressions.md" >}}).
1. Write the expression.
1. Click **Apply**.