Prepare dashboards, panels, and visualizations for Grafana Cloud mount (#73632)

* Update dashboards pages to use `docs/reference` shortcode

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update panels-visualizations pages to use `docs/reference` shortcode

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Use raw Markdown admonitions for contextual links

See https://discourse.gohugo.io/t/markdown-reference-links-in-shortcodes/5770/3.
Should be resolved by https://docs.google.com/document/d/19xd4CD3IrAqQqNR3xQeLfuIV-u2iNSQSBEvPZE9J4qU/edit#heading=h.5sybau7waq2q.

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Prefer "Warning" over "Caution"

Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>

* Prettier

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix some links missing destinations

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix 'time range controls' link

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Add missing 'HTTP APIs' link

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix dashboard links missing destinations

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix links missing destinations in panels and visualizations documentation

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix dud link

Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>

---------

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>
This commit is contained in:
Jack Baldry
2023-09-13 10:39:04 +01:00
committed by GitHub
parent 00c6b87210
commit 7ef7cedc11
50 changed files with 963 additions and 320 deletions

View File

@ -24,7 +24,7 @@ weight: 200
# Query and transform data
Grafana supports many types of [data sources]({{< relref "../../datasources/" >}}).
Grafana supports many types of [data sources][].
Data source **queries** return data that Grafana can **transform** and visualize.
Each data source uses its own query language, and data source plugins each implement a query-building user interface called a query editor.
@ -37,7 +37,7 @@ You can configure query frequency and data collection limits in the panel's data
Grafana supports up to 26 queries per panel.
> **Important:** You **must** be familiar with a data source's query language.
> For more information, refer to [Data sources]({{< relref "../../datasources/" >}}).
> For more information, refer to [Data sources][].
### Query editors
@ -54,10 +54,10 @@ For example, this video demonstrates the visual Prometheus query builder:
For details on a specific data source's unique query editor features, refer to its documentation:
- For data sources included with Grafana, refer to [Built-in core data sources]({{< relref "../../datasources/#data-source-plugins" >}}), which links to each core data source's documentation.
- For data sources included with Grafana, refer to [Built-in core data sources][], which links to each core data source's documentation.
- For data sources installed as plugins, refer to its own documentation.
- Data source plugins in Grafana's [plugin catalog](/grafana/plugins/) link to or include their documentation in their catalog listings.
For details about the plugin catalog, refer to [Plugin management]({{< relref "../../administration/plugin-management/" >}}).
For details about the plugin catalog, refer to [Plugin management][].
- For links to Grafana Enterprise data source plugin documentation, refer to the [Enterprise plugins index](/docs/plugins/).
### Query syntax
@ -80,19 +80,19 @@ query_result(max_over_time(<metric>[${__range_s}s]) != <state>)
### Special data sources
Grafana also includes three special data sources: **Grafana**, **Mixed**, and **Dashboard**.
For details, refer to [Data sources]({{< relref "../../datasources/#special-data-sources" >}})
For details, refer to [Data sources][]
## Navigate the Query tab
A panel's Query tab consists of the following elements:
- **Data source selector:** Selects the data source to query.
For more information about data sources, refer to [Data sources]({{< relref "../../datasources/" >}}).
For more information about data sources, refer to [Data sources][].
- **Query options:** Sets maximum data retrieval parameters and query execution time intervals.
- **Query inspector button:** Opens the query inspector panel, where you can view and optimize your query.
- **Query editor list:** Lists the queries you've written.
- **Expressions:** Uses the expression builder to create alert expressions.
For more information about expressions, refer to [Use expressions to manipulate data]({{< relref "expression-queries/" >}}).
For more information about expressions, refer to [Use expressions to manipulate data][].
{{< figure src="/static/img/docs/queries/query-editor-7-2.png" class="docs-image--no-shadow" max-width="1000px" >}}
@ -110,7 +110,7 @@ When you create a panel, Grafana automatically selects the default data source.
If you're creating a new dashboard, you'll be prompted to select a data source when you add the first panel.
1. Click **Query options** to configure the maximum number of data points you need.
For more information about query options, refer to [Query options]({{< relref "#query-options" >}}).
For more information about query options, refer to [Query options](#query-options).
1. Write the query using the query editor.
1. Click **Apply**.
@ -169,7 +169,7 @@ Panel data source query options include:
As the user zooms out on a visualization, the interval grows, resulting in a more coarse-grained aggregation.
Likewise, if the user zooms in, the interval decreases, resulting in a more fine-grained aggregation.
For more information, refer to [Global variables]({{< relref "../../dashboards/variables/add-template-variables/#global-variables" >}}).
For more information, refer to [Global variables][].
- **Relative time:** Overrides the relative time range for individual panels, which causes them to be different than what is selected in the dashboard time picker in the top-right corner of the dashboard.
You can use this to show metrics from different time periods or days on the same dashboard.
@ -199,3 +199,23 @@ Panel data source query options include:
- **Cache timeout:** _(Visible only if available in the data source)_ Overrides the default cache timeout if your time series store has a query cache.
Specify this value as a numeric value in seconds.
{{% docs/reference %}}
[Use expressions to manipulate data]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data/expression-queries"
[Use expressions to manipulate data]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data/expression-queries"
[Plugin management]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/administration/plugin-management"
[Plugin management]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/administration/plugin-management"
[Global variables]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/variables/add-template-variables#global-variables"
[Global variables]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/variables/add-template-variables#global-variables"
[Built-in core data sources]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/datasources#data-source-plugins"
[Built-in core data sources]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/datasources#data-source-plugins"
[data sources]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/datasources"
[data sources]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/datasources"
[Data sources]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/datasources"
[Data sources]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/datasources"
{{% /docs/reference %}}

View File

@ -24,7 +24,7 @@ Server-side expressions allow you to manipulate data returned from queries with
### Using expressions
Expressions are most commonly used for [Grafana Alerting]({{< relref "../../../alerting/" >}}). 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.
Expressions are most commonly used for [Grafana Alerting][]. 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.
{{% admonition type="note" %}}
Expressions do not work with legacy dashboard alerts.
@ -36,7 +36,7 @@ Expressions are meant to augment data sources by enabling queries from different
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.
{{% /admonition %}}
Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data]({{< relref "../../../fundamentals/timeseries-dimensions/" >}}). For example, a query that returns multiple series, where each series is identified by labels or tags.
Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data][]. 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`).
@ -49,7 +49,7 @@ 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 "../../../fundamentals/timeseries-dimensions/#labels" >}}) or key-value pairs.
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][] or key-value pairs.
### Data source queries
@ -220,13 +220,13 @@ Resample changes the time stamps in each time series to have a consistent time i
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" >}}).
For more information about expressions, refer to [About expressions](#about-expressions).
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" >}}).
For more information about expression operations, refer to [About expressions](#about-expressions).
1. Write the expression.
1. Click **Apply**.
@ -235,6 +235,20 @@ For more information about expressions, refer to [About expressions]({{< relref
When any queried data source returns no series or numbers, the expression engine returns `NoData`. For example, if a request contains two data source queries that are merged by an expression, if `NoData` is returned by at least one of the data source queries, then the returned result for the entire query is `NoData`.
For more information about how [Grafana Alerting]({{< relref "../../../alerting/" >}}) processes `NoData` results, refer to [No data and error handling]({{< relref "../../../alerting/alerting-rules/create-grafana-managed-rule/#no-data-and-error-handling" >}}).
For more information about how [Grafana Alerting][] processes `NoData` results, refer to [No data and error handling][].
In the case of using an expression on multiple queries, the expression engine requires that all of the queries return an identical timestamp. For example, if using math to combine the results of multiple SQL queries which each use `SELECT NOW() AS "time"`, the expression will only work if all queries evaluate `NOW()` to an identical timestamp; which does not always happen. To resolve this, you can replace `NOW()` with an arbitrary time, such as `SELECT 1 AS "time"`, or any other valid UNIX timestamp.
{{% docs/reference %}}
[multiple-dimensional data]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/fundamentals/timeseries-dimensions"
[multiple-dimensional data]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/fundamentals/timeseries-dimensions"
[Grafana Alerting]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/alerting"
[Grafana Alerting]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/alerting"
[labels]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/fundamentals/timeseries-dimensions#labels"
[labels]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/fundamentals/timeseries-dimensions#labels"
[No data and error handling]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/alerting/alerting-rules/create-grafana-managed-rule#configure-no-data-and-error-handling"
[No data and error handling]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/alerting/alerting-rules/create-grafana-managed-rule#configure-no-data-and-error-handling"
{{% /docs/reference %}}

View File

@ -19,9 +19,9 @@ The Dashboard data source lets you select a panel in your dashboard that contain
This strategy can drastically reduce the number of queries being made when you for example have several panels visualizing the same data.
1. [Create a dashboard]({{< relref "../../../dashboards/build-dashboards/create-dashboard/" >}}).
1. [Create a dashboard][].
1. Change the title to "Source panel". You'll use this panel as a source for the other panels.
1. Define the [query]({{< relref "../#add-a-query" >}}) or queries that you want share.
1. Define the [query][] 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.
@ -31,3 +31,11 @@ This strategy can drastically reduce the number of queries being made when you f
All queries defined in the source panel are now available to the new panel. Queries defined 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/reference %}}
[Create a dashboard]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/build-dashboards/create-dashboard"
[Create a dashboard]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/build-dashboards/create-dashboard"
[query]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data#add-a-query"
[query]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/query-transform-data#add-a-query"
{{% /docs/reference %}}

View File

@ -39,7 +39,7 @@ You can also use the output of one transformation as the input to another transf
## Transformation types
Grafana provides a number of ways that you can transform data. For a complete list of transformations, refer to [Transformation functions]({{< relref "#transformation-functions" >}}).
Grafana provides a number of ways that you can transform data. For a complete list of transformations, refer to [Transformation functions](#transformation-functions).
## Order of transformations
@ -49,15 +49,15 @@ The order in which Grafana applies transformations directly impacts the results.
## Add a transformation function to data
The following steps guide you in adding a transformation to data. This documentation does not include steps for each type of transformation. For a complete list of transformations, refer to [Transformation functions]({{< relref "#transformation-functions" >}}).
The following steps guide you in adding a transformation to data. This documentation does not include steps for each type of transformation. For a complete list of transformations, refer to [Transformation functions](#transformation-functions).
1. Navigate to the panel where you want to add one or more transformations.
1. Hover over any part of the panel to display the actions menu on the top right corner.
1. Click the menu and select **Edit**.
1. Click the **Transform** tab.
1. Click a transformation.
A transformation row appears where you configure the transformation options. For more information about how to configure a transformation, refer to [Transformation functions]({{< relref "#transformation-functions" >}}).
For information about available calculations, refer to [Calculation types]({{< relref "../../calculation-types" >}}).
A transformation row appears where you configure the transformation options. For more information about how to configure a transformation, refer to [Transformation functions](#transformation-functions).
For information about available calculations, refer to [Calculation types][].
1. To apply another transformation, click **Add transformation**.
This transformation acts on the result set returned by the previous transformation.
{{< figure src="/static/img/docs/transformations/transformations-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
@ -111,7 +111,7 @@ Use this transformation to add a new field calculated from two other fields. Eac
- **Binary option -** Apply basic math operation(sum, multiply, etc) on values in a single row from two selected fields.
- **Index -** Will insert a field with the row index.
- **Field name -** Select the names of fields you want to use in the calculation for the new field.
- **Calculation -** If you select **Reduce row** mode, then the **Calculation** field appears. Click in the field to see a list of calculation choices you can use to create the new field. For information about available calculations, refer to [Calculation types]({{< relref "../../calculation-types" >}}).
- **Calculation -** If you select **Reduce row** mode, then the **Calculation** field appears. Click in the field to see a list of calculation choices you can use to create the new field. For information about available calculations, refer to [Calculation types][].
- **Operation -** If you select **Binary option** mode, then the **Operation** fields appear. These fields allow you to do basic math operations on values in a single row from two selected fields. You can also use numerical values for binary operations.
- **Alias -** (Optional) Enter the name of your new field. If you leave this blank, then the field will be named to match the calculation.
- **Replace all fields -** (Optional) Select this option if you want to hide all other fields and display only your calculated field in the visualization.
@ -186,7 +186,7 @@ The result:
### Create heatmap
Use this transformation to prepare histogram data to be visualized over time. Similar to the [Heatmap panel]({{< relref "../../visualizations/heatmap" >}}), this transformation allows you to convert histogram metrics to buckets over time.
Use this transformation to prepare histogram data to be visualized over time. Similar to the [Heatmap panel][], this transformation allows you to convert histogram metrics to buckets over time.
#### X Bucket
@ -227,7 +227,7 @@ Consider the following data set:
| 1636678680000000000 | {"value": 5} |
| 1636678620000000000 | {"value": 12} |
You could prepare the data to be used by a [Time series panel]({{< relref "../../visualizations/time-series" >}}) with this configuration:
You could prepare the data to be used by a [Time series panel][] with this configuration:
- Source: json_data
- Format: JSON
@ -380,7 +380,7 @@ Conditions that are invalid or incompletely configured are ignored.
### Group by
This transformation groups the data by a specified field (column) value and processes calculations on each group. Click to see a list of calculation choices. For information about available calculations, refer to [Calculation types]({{< relref "../../calculation-types" >}}).
This transformation groups the data by a specified field (column) value and processes calculations on each group. Click to see a list of calculation choices. For information about available calculations, refer to [Calculation types][].
Here's an example of original data.
@ -688,7 +688,7 @@ After merge:
### Merge
Use this transformation to combine the result from multiple queries into one single result. This is helpful when using the table panel visualization. Values that can be merged are combined into the same row. Values are mergeable if the shared fields contain the same data. For information, refer to [Table panel]({{< relref "../../visualizations/table/" >}}).
Use this transformation to combine the result from multiple queries into one single result. This is helpful when using the table panel visualization. Values that can be merged are combined into the same row. Values are mergeable if the shared fields contain the same data. For information, refer to [Table panel][].
In the example below, we have two queries returning table data. It is visualized as two separate tables before applying the transformation.
@ -894,7 +894,7 @@ As you can see each row in the source data becomes a separate field. Each field
This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
{{% /admonition %}}
Prepare time series transformation is useful when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames]({{< relref "../../../developers/plugins/introduction-to-plugin-development/data-frames/" >}}).
Prepare time series transformation is useful when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames][].
This transformation helps you resolve this issue by converting the time series data from either the wide format to the long format or the other way around.
@ -970,11 +970,10 @@ Here is the result after adding a Limit transformation with a value of '3':
### Time series to table transform
{{% admonition type="note" %}}
This transformation is available in Grafana 9.5+ as an opt-in beta feature. Modify Grafana [configuration file]({{< relref "../../../setup-grafana/configure-grafana/#configuration-file-location" >}}) to enable the `timeSeriesTable` [feature toggle]({{< relref "../../../setup-grafana/configure-grafana/#feature_toggles" >}}) to use it.
{{% /admonition %}}
> **Note:** This transformation is available in Grafana 9.5+ as an opt-in beta feature.
> Modify Grafana [configuration file][] to enable the `timeSeriesTable` [feature toggle][] to use it.
Use this transformation to convert time series result into a table, converting time series data frame into a "Trend" field. "Trend" field can then be rendered using [sparkline cell type]({{< relref "../../visualizations/table/#sparkline" >}}), producing an inline sparkline for each table row. If there are multiple time series queries, each will result in a separate table data frame. These can be joined using join or merge transforms to produce a single table with multiple sparklines per row.
Use this transformation to convert time series result into a table, converting time series data frame into a "Trend" field. "Trend" field can then be rendered using [sparkline cell type][], producing an inline sparkline for each table row. If there are multiple time series queries, each will result in a separate table data frame. These can be joined using join or merge transforms to produce a single table with multiple sparklines per row.
### Format Time
@ -983,3 +982,29 @@ This transformation is available in Grafana 10.1+ as an alpha feature.
{{% /admonition %}}
Use this transformation to format the output of a time field. Output can be formatted using (Moment.js format strings)[https://momentjs.com/docs/#/displaying/]. For instance, if you would like to display only the year of a time field the format string `YYYY` can be used to show the calendar year (e.g. 1999, 2012, etc.).
{{% docs/reference %}}
[Table panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
[Table panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
[Data frames]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
[Data frames]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
[Calculation types]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
[Calculation types]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
[sparkline cell type]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table#sparkline"
[sparkline cell type]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table#sparkline"
[Heatmap panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/heatmap"
[Heatmap panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/heatmap"
[configuration file]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#configuration-file-location"
[configuration file]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#configuration-file-location"
[Time series panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/time-series"
[Time series panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/time-series"
[feature toggle]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#feature_toggles"
[feature toggle]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#feature_toggles"
{{% /docs/reference %}}

View File

@ -31,7 +31,7 @@ The most common problems are related to the query and response from your data so
like a bug or visualization issue in Grafana, it is almost always a problem with the data source query or
the data source response. Start by inspecting your panel query and response.
For more information, refer to [Inspect request and response data]({{< relref "../../panel-inspector/#inspect-query-request-and-response data/" >}}).
For more information, refer to [Inspect request and response data][inspect].
## My query is slow
@ -40,3 +40,8 @@ How many data points is your query returning? A query that returns lots of data
- In **Query options**, limit the **Max data points** returned.
- In **Query options**, increase the **Min interval** time.
- In your query, use a `group by` function.
{{% docs/reference %}}
[inspect]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/panel-inspector#inspect-query-request-and-response-data"
[inspect]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/panel-inspector#inspect-query-request-and-response-data"
{{% /docs/reference %}}