* 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>
A dashboard is a set of one or more [panels]({{< relref "../panels-visualizations/" >}}) organized and arranged into one or more rows. Grafana ships with a variety of panels making it easy to construct the right queries, and customize the visualization so that you can create the perfect dashboard for your need. Each panel can interact with data from any configured Grafana [data source]({{< relref "../administration/data-source-management/" >}}).
A dashboard is a set of one or more [panels][] organized and arranged into one or more rows. Grafana ships with a variety of panels making it easy to construct the right queries, and customize the visualization so that you can create the perfect dashboard for your need. Each panel can interact with data from any configured Grafana [data source][].
Dashboard snapshots are static. Queries and expressions cannot be re-executed from snapshots. As a result, if you update any variables in your query or expression, it will not change your dashboard data.
Before you begin, ensure that you have configured a data source. See also:
Usage insights enables you to have a better understanding of how your Grafana instance is used.
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/">}}) and [Grafana Cloud](/docs/grafana-cloud/). Grafana Cloud insights logs include additional fields with their own dashboards. Read more in the [Grafana Cloud documentation](/docs/grafana-cloud/usage-insights/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] and [Grafana Cloud](/docs/grafana-cloud/).
> Grafana Cloud insights logs include additional fields with their own dashboards.
> Read more in the [Grafana Cloud documentation](/docs/grafana-cloud/usage-insights/).
The usage insights feature collects a number of aggregated data and stores them in the database:
@ -36,12 +36,12 @@ The usage insights feature collects a number of aggregated data and stores them
The aggregated data provides you access to several features:
- [Dashboard and data source insights]({{< relref "#dashboard-and-data-source-insights" >}})
- [Sort dashboards by using insights data]({{< relref "#sort-dashboards-by-using-insights-data" >}})
- [Visualize usage insight data in a dashboard]({{< relref "#visualize-usage-insights-data" >}})
- [Dashboard and data source insights](#dashboard-and-data-source-insights)
- [Presence indicator](#presence-indicator)
- [Sort dashboards by using insights data](#sort-dashboards-by-using-insights-data)
- [Visualize usage insight data in a dashboard](#visualize-usage-insights-data)
This feature also generates detailed logs that can be exported to Loki. Refer to [Export logs of usage insights]({{< relref "../../setup-grafana/configure-security/export-logs/" >}}).
This feature also generates detailed logs that can be exported to Loki. Refer to [Export logs of usage insights][].
## Dashboard and data source insights
@ -87,11 +87,11 @@ To find data source insights:
When you are signed in and looking at a dashboard, you can know who is looking at the same dashboard as you are via a presence indicator, which displays avatars of users who have recently interacted with the dashboard. The default time frame is 10 minutes. To see the user's name, hover over the user's avatar. The avatars come from [Gravatar](https://gravatar.com) based on the user's email.
When there are more active users on a dashboard than can fit within the presence indicator, click the **+X** icon. Doing so opens [dashboard insights]({{< relref "#dashboard-and-data-source-insights" >}}), which contains more details about recent user activity.
When there are more active users on a dashboard than can fit within the presence indicator, click the **+X** icon. Doing so opens [dashboard insights](#dashboard-and-data-source-insights), which contains more details about recent user activity.
To change _recent_ to something other than the past 10 minutes, edit the [configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}) file:
To change _recent_ to something other than the past 10 minutes, edit the [configuration][] file:
```ini
[analytics.views]
@ -114,9 +114,23 @@ You can sort the dashboards by:
## Visualize usage insights data
If you set up your installation to [export logs of usage insights]({{< relref "../../setup-grafana/configure-security/export-logs/" >}}), we've created two dashboards to help you take advantage of this data.
If you set up your installation to [export logs of usage insights][], we've created two dashboards to help you take advantage of this data.
1. [Usage Insights overview](/grafana/dashboards/13785) provides a top-level perspective of user activity.
1. [Data source details](/grafana/dashboards/13786) dashboard provides a view of data source activity and health.
You can click the previous links to download the respective dashboard JSON, then import into your Grafana installation.
{{% docs/reference %}}
[export logs of usage insights]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/setup-grafana/configure-security/export-logs"
[export logs of usage insights]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/setup-grafana/configure-security/export-logs"
[Export logs of usage insights]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/setup-grafana/configure-security/export-logs"
[Export logs of usage insights]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/setup-grafana/configure-security/export-logs"
@ -24,4 +24,9 @@ This section includes the following topics:
## Dynamic dashboards
You can create more interactive and dynamic dashboards by adding and using [variables]({{< relref "../variables" >}}). Instead of hard-coding things like server, application, and sensor names in your metric queries, you can use variables in their place. Read more about variables [here]({{< relref "../variables" >}}).
You can create more interactive and dynamic dashboards by adding and using [variables][]. Instead of hard-coding things like server, application, and sensor names in your metric queries, you can use variables in their place. Read more about variables [here][variables].
@ -31,7 +31,7 @@ You can annotate visualizations in three ways:
In the first two cases, you're creating new annotations, while in the last you're querying existing annotations from data sources. The built-in annotation query also supports this.
This page explains the first and third options; for information about using the HTTP API, refer to [Annotations API]({{< relref "../../../developers/http_api/annotations/" >}}).
This page explains the first and third options; for information about using the HTTP API, refer to [Annotations API][].
Annotations are supported for the following visualization types:
@ -113,7 +113,7 @@ To add a new annotation query to a dashboard, take the following steps:
1. Configure the query.
The annotation query options are different for each data source. For information about annotations in a specific data source, refer to the specific [data source]({{< relref "../../../datasources/" >}}) topic.
The annotation query options are different for each data source. For information about annotations in a specific data source, refer to the specific [data source][] topic.
## Built-in query
@ -163,3 +163,11 @@ When adding or editing an annotation, you can define a repeating time region by
The above configuration will produce the following result in the Time series panel:
{{<figuresrc="/media/docs/grafana/screenshot-grafana-10-0-timeseries-time-regions.png"max-width="600px"caption="Time series time regions business hours">}}
- Prevent sprawl by using template variables. For example, you don't need a separate dashboard for each node, you can use query variables. Even better, you can make the data source a template variable too, so you can reuse the same dashboard across different clusters and monitoring backends.
Refer to the list of [Variable examples]({{< relref "../../variables/#examples-of-templates-and-variables" >}}) if you want some ideas.
Refer to the list of [Variable examples][] if you want some ideas.
- Methodical dashboards according to an [observability strategy]({{< relref "#common-observability-strategies" >}}).
- Methodical dashboards according to an [observability strategy](#common-observability-strategies).
- Hierarchical dashboards with drill-downs to the next level.
{{<figureclass="float-right"max-width="100%"src="/static/img/docs/best-practices/drill-down-example.png"caption="Example of using drill-down">}}
@ -113,12 +113,12 @@ How can you tell you are here?
- Compare like to like: split service dashboards when the magnitude differs. Make sure aggregated metrics don't drown out important information.
- Expressive charts with meaningful use of color and normalizing axes where you can.
- Example of meaningful color: Blue means it's good, red means it's bad. [Thresholds]({{< relref "../../../panels-visualizations/configure-thresholds/" >}}) can help with that.
- Example of meaningful color: Blue means it's good, red means it's bad. [Thresholds][] can help with that.
- Example of normalizing axes: When comparing CPU usage, measure by percentage rather than raw number, because machines can have a different number of cores. Normalizing CPU usage by the number of cores reduces cognitive load because the viewer can trust that at 100% all cores are being used, without having to know the number of CPUs.
- Directed browsing cuts down on "guessing."
- Template variables make it harder to “just browse” randomly or aimlessly.
- Most dashboards should be linked to by alerts.
- Browsing is directed with links. For more information, refer to [Manage dashboard links]({{< relref "../manage-dashboard-links" >}}).
- Browsing is directed with links. For more information, refer to [Manage dashboard links][].
- Version-controlled dashboard JSON.
### High - optimized use
@ -128,7 +128,7 @@ At this stage, you have optimized your dashboard management use with a consisten
- Actively reducing sprawl.
- Regularly review existing dashboards to make sure they are still relevant.
- Only approved dashboards added to master dashboard list.
- Tracking dashboard use. If you're an Enterprise user, you can take advantage of [Usage insights]({{< relref "../../assess-dashboard-usage/" >}}).
- Tracking dashboard use. If you're an Enterprise user, you can take advantage of [Usage insights][].
- Consistency by design.
- Use scripting libraries to generate dashboards, ensure consistency in pattern and style.
- grafonnet (Jsonnet)
@ -164,7 +164,7 @@ Ask yourself:
It's easy to make new dashboards. It's harder to optimize dashboard creation and adhere to a plan, but it's worth it. This strategy should govern both your overall dashboard scheme and enforce consistency in individual dashboard design.
Refer to [Common observability strategies]({{< relref "#common-observability-strategies" >}}) and [Dashboard management maturity levels]({{< relref "#dashboard-management-maturity-model" >}}) for more information.
Refer to [Common observability strategies](#common-observability-strategies) and [Dashboard management maturity levels](#dashboard-management-maturity-model) for more information.
#### Write it down
@ -176,14 +176,14 @@ Once you have a strategy or design guidelines, write them down to help maintain
- If you are creating a dashboard to play or experiment, then put the word `TEST` or `TMP` in the name.
- Consider including your name or initials in the dashboard name or as a tag so that people know who owns the dashboard.
- Remove temporary experiment dashboards when you are done with them.
- If you create many related dashboards, think about how to cross-reference them for easy navigation. Refer to [Best practices for managing dashboards]({{< relref "#best-practices-for-managing-dashboards" >}}) for more information.
- Grafana retrieves data from a data source. A basic understanding of [data sources]({{< relref "../../../datasources/" >}}) in general and your specific is important.
- If you create many related dashboards, think about how to cross-reference them for easy navigation. Refer to [Best practices for managing dashboards](#best-practices-for-managing-dashboards) for more information.
- Grafana retrieves data from a data source. A basic understanding of [data sources][] in general and your specific is important.
- Avoid unnecessary dashboard refreshing to reduce the load on the network or backend. For example, if your data changes every hour, then you don't need to set the dashboard refresh rate to 30 seconds.
- Use the left and right Y-axes when displaying time series with different units or ranges.
- Add documentation to dashboards and panels.
- To add documentation to a dashboard, add a [Text panel visualization]({{< relref "../../../panels-visualizations/visualizations/text/" >}}) to the dashboard. Record things like the purpose of the dashboard, useful resource links, and any instructions users might need to interact with the dashboard. Check out this [Wikimedia example](https://grafana.wikimedia.org/d/000000066/resourceloader?orgId=1).
- To add documentation to a dashboard, add a [Text panel visualization][] to the dashboard. Record things like the purpose of the dashboard, useful resource links, and any instructions users might need to interact with the dashboard. Check out this [Wikimedia example](https://grafana.wikimedia.org/d/000000066/resourceloader?orgId=1).
- To add documentation to a panel, edit the panel settings and add a description. Any text you add will appear if you hover your cursor over the small `i` in the top left corner of the panel.
- Reuse your dashboards and enforce consistency by using [templates and variables]({{< relref "../../variables" >}}).
- Reuse your dashboards and enforce consistency by using [templates and variables][].
- Be careful with stacking graph data. The visualizations can be misleading, and hide important data. We recommend turning it off in most cases.
## Best practices for managing dashboards
@ -196,13 +196,13 @@ Here are some principles to consider before you start managing dashboards.
#### Strategic observability
There are several [common observability strategies]({{< relref "#common-observability-strategies" >}}). You should research them and decide whether one of them works for you or if you want to come up with your own. Either way, have a plan, write it down, and stick to it.
There are several [common observability strategies](#common-observability-strategies). You should research them and decide whether one of them works for you or if you want to come up with your own. Either way, have a plan, write it down, and stick to it.
Adapt your strategy to changing needs as necessary.
#### Maturity level
What is your dashboard maturity level? Analyze your current dashboard setup and compare it to the [Dashboard management maturity model]({{< relref "#dashboard-management-maturity-model" >}}). Understanding where you are can help you decide how to get to where you want to be.
What is your dashboard maturity level? Analyze your current dashboard setup and compare it to the [Dashboard management maturity model](#dashboard-management-maturity-model). Understanding where you are can help you decide how to get to where you want to be.
### Best practices to follow
@ -211,9 +211,41 @@ What is your dashboard maturity level? Analyze your current dashboard setup and
- If you create a temporary dashboard, perhaps to test something, prefix the name with `TEST: `. Delete the dashboard when you are finished.
- Copying dashboards with no significant changes is not a good idea.
- You miss out on updates to the original dashboard, such as documentation changes, bug fixes, or additions to metrics.
- In many cases copies are being made to simply customize the view by setting template parameters. This should instead be done by maintaining a link to the master dashboard and customizing the view with [URL parameters]({{< relref "../../../panels-visualizations/configure-data-links/#data-link-variables" >}}).
- In many cases copies are being made to simply customize the view by setting template parameters. This should instead be done by maintaining a link to the master dashboard and customizing the view with [URL parameters][].
- When you must copy a dashboard, clearly rename it and _do not_ copy the dashboard tags. Tags are important metadata for dashboards that are used during search. Copying tags can result in false matches.
- Maintain a dashboard of dashboards or cross-reference dashboards. This can be done in several ways:
- Create dashboard links, panel, or data links. Links can go to other dashboards or to external systems. For more information, refer to [Manage dashboard links]({{< relref "../manage-dashboard-links/" >}}).
- Add a [Dashboard list panel]({{< relref "../../../panels-visualizations/visualizations/dashboard-list/" >}}). You can then customize what you see by doing tag or folder searches.
- Add a [Text panel]({{< relref "../../../panels-visualizations/visualizations/text/" >}}) and use markdown to customize the display.
- Create dashboard links, panel, or data links. Links can go to other dashboards or to external systems. For more information, refer to [Manage dashboard links][].
- Add a [Dashboard list panel][]. You can then customize what you see by doing tag or folder searches.
- Add a [Text panel][] and use markdown to customize the display.
Grafana can apply variable values passed as query parameters in dashboard URLs.
For more information, refer to [Manage dashboard links]({{< relref "../manage-dashboard-links/" >}}) and [Templates and variables]({{< relref "../../variables/" >}}).
For more information, refer to [Manage dashboard links][] and [Templates and variables][].
## Passing variables as query parameters
@ -50,11 +50,11 @@ This example in [Grafana Play](https://play.grafana.org/d/000000074/alerting?var
## Adding variables to dashboard links
Grafana can add variables to dashboard links when you generate them from a dashboard's settings. For more information and steps to add variables, refer to [Manage dashboard links]({{< relref "../manage-dashboard-links/" >}}).
Grafana can add variables to dashboard links when you generate them from a dashboard's settings. For more information and steps to add variables, refer to [Manage dashboard links][].
## Passing ad hoc filters
Ad hoc filters apply key/value filters to all metric queries that use a specified data source. For more information, refer to [Add ad hoc filters]({{< relref "../../variables/add-template-variables/#add-ad-hoc-filters" >}}).
Ad hoc filters apply key/value filters to all metric queries that use a specified data source. For more information, refer to [Add ad hoc filters][].
To pass an ad hoc filter as a query parameter, use the variable syntax to pass the ad hoc filter variable, and also provide the key, the operator as the value, and the value as a pipe-separated list.
@ -76,4 +76,18 @@ When sharing URLs with ad hoc filters, remember to encode the URL. In the above
## Controlling time range using the URL
To set a dashboard's time range, use the `from`, `to`, `time`, and `time.window` query parameters. Because these are not variables, they do not require the `var-` prefix. For more information, see the [Linking overview]({{< relref "../" >}}).
To set a dashboard's time range, use the `from`, `to`, `time`, and `time.window` query parameters. Because these are not variables, they do not require the `var-` prefix. For more information, see the [Linking overview][].
@ -21,10 +21,10 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
**Before you begin:**
- Ensure that you have the proper permissions. For more information about permissions, refer to [About users and permissions]({{< relref "../../../administration/roles-and-permissions/" >}}).
- Ensure that you have the proper permissions. For more information about permissions, refer to [About users and permissions][].
- Identify the dashboard to which you want to add the panel.
- Understand the query language of the target data source.
- Ensure that data source for which you are writing a query has been added. For more information about adding a data source, refer to [Add a data source]({{< relref "../../../administration/data-source-management#add-a-data-source" >}}) if you need instructions.
- Ensure that data source for which you are writing a query has been added. For more information about adding a data source, refer to [Add a data source][] if you need instructions.
**To create a dashboard**:
@ -37,7 +37,7 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
1. In the modal that opens, do one of the following:
- Select one of your existing data sources.
- Select one of the Grafana's [built-in special data sources]({{< relref "../../../datasources/#special-data-sources" >}}).
- Select one of the Grafana's [built-in special data sources][].
- Click **Configure a new data source** to set up a new one (Admins only).
{{<figureclass="float-right"src="/media/docs/grafana/dashboards/screenshot-data-source-selector-10.0.png"max-width="800px"alt="Select data source modal">}}
@ -45,7 +45,7 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
The **Edit panel** view opens with your data source selected.
You can change the panel data source later using the dropdown in the **Query** tab of the panel editor if needed.
For more information about data sources, refer to [Data sources]({{< relref "../../../datasources/" >}}) for specific guidelines.
For more information about data sources, refer to [Data sources][] for specific guidelines.
1. Write or construct a query in the query language of your data source.
@ -59,17 +59,17 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
Grafana displays a preview of your query results with the visualization applied.
For more information about individual visualizations, refer to [Visualizations options]({{< relref "../../../panels-visualizations/visualizations/" >}}).
For more information about individual visualizations, refer to [Visualizations options][].
1. Refer to the following documentation for ways you can adjust panel settings.
While not required, most visualizations need some adjustment before they properly display the information that you need.
- [Configure value mappings]({{< relref "../../../panels-visualizations/configure-value-mappings" >}})
- [Configure standard options]({{< relref "../../../panels-visualizations/configure-standard-options/" >}})
- [Configure value mappings][]
- [Visualization-specific options][]
- [Override field values][]
- [Configure thresholds][]
- [Configure standard options][]
1. When you've finished editing your panel, click **Save** to save the dashboard.
@ -85,7 +85,7 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
## Configure repeating rows
You can configure Grafana to dynamically add panels or rows to a dashboard based on the value of a variable. Variables dynamically change your queries across all rows in a dashboard. For more information about repeating panels, refer to [Configure repeating panels]({{< relref "../../../panels-visualizations/configure-panel-options/#configure-repeating-panels" >}}).
You can configure Grafana to dynamically add panels or rows to a dashboard based on the value of a variable. Variables dynamically change your queries across all rows in a dashboard. For more information about repeating panels, refer to [Configure repeating panels][].
To see an example of repeating rows, refer to [Dashboard with repeating rows](https://play.grafana.org/d/000000153/repeat-rows). The example shows that you can also repeat rows if you have variables set with `Multi-value` or `Include all values` selected.
@ -133,3 +133,38 @@ You can size a dashboard panel to suits your needs.
1. Click **Dashboards** in the left-side menu.
1. Navigate to the dashboard you want to work on.
1. To adjust the size of the panel, click and drag the lower-right corner of the panel.
{{% docs/reference %}}
[Override field values]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/configure-overrides"
[Override field values]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/configure-overrides"
[built-in special data sources]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/datasources#special-data-sources"
[built-in special data sources]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/datasources#special-data-sources"
@ -37,10 +37,10 @@ Start by figuring out how you're currently navigating between dashboards. If you
The next step is to figure out which link type is right for your workflow. Even though all the link types in Grafana are used to create shortcuts to other dashboards or external websites, they work in different contexts.
- If the link relates to most if not all of the panels in the dashboard, use [dashboard links]({{< relref "#dashboard-links" >}}).
- If you want to drill down into specific panels, use [panel links]({{< relref "#panel-links" >}}).
- If the link relates to most if not all of the panels in the dashboard, use [dashboard links](#dashboard-links).
- If you want to drill down into specific panels, use [panel links](#panel-links).
- If you want to link to an external site, you can use either a dashboard link or a panel link.
- If you want to drill down into a specific series, or even a single measurement, use [data links]({{< relref "../../../panels-visualizations/configure-data-links/#data-links" >}}).
- If you want to drill down into a specific series, or even a single measurement, use [data links][].
## Controlling time range using the URL
@ -52,7 +52,7 @@ To control the time range of a panel or dashboard, you can provide query paramet
## Dashboard links
When you create a dashboard link, you can include the time range and current template variables to directly jump to the same context in another dashboard. This way, you don’t have to worry whether the person you send the link to is looking at the right data. For other types of links, refer to [Data link variables]({{< relref "../../../panels-visualizations/configure-data-links/#data-link-variables/" >}}).
When you create a dashboard link, you can include the time range and current template variables to directly jump to the same context in another dashboard. This way, you don’t have to worry whether the person you send the link to is looking at the right data. For other types of links, refer to [Data link variables][].
Dashboard links can also be used as shortcuts to external systems, such as submitting [a GitHub issue with the current dashboard name](https://github.com/grafana/grafana/issues/new?title=Dashboard%3A%20HTTP%20Requests).
@ -74,7 +74,7 @@ Add links to other dashboards at the top of your current dashboard.
- **With tags** – Enter tags to limit the linked dashboards to only the ones with the tags you enter. Otherwise, Grafana includes links to all other dashboards.
- **As dropdown** – If you are linking to lots of dashboards, then you probably want to select this option and add an optional title to the dropdown. Otherwise, Grafana displays the dashboard links side by side across the top of your dashboard.
- **Time range** – Select this option to include the dashboard time range in the link. When the user clicks the link, the linked dashboard opens with the indicated time range already set. **Example:** https://play.grafana.org/d/000000010/annotations?orgId=1&from=now-3h&to=now
- **Variable values** – Select this option to include template variables currently used as query parameters in the link. When the user clicks the link, any matching templates in the linked dashboard are set to the values from the link. For more information, see [Dashboard URL variables]({{< relref "../create-dashboard-url-variables/" >}}).
- **Variable values** – Select this option to include template variables currently used as query parameters in the link. When the user clicks the link, any matching templates in the linked dashboard are set to the values from the link. For more information, see [Dashboard URL variables][].
- **Open in new tab** – Select this option if you want the dashboard link to open in a new tab or window.
1. Click **Add**.
@ -165,3 +165,14 @@ Click the icon next to the panel title to see available panel links.
1. Find the link that you want to delete.
1. Click the **X** icon next to the link you want to delete.
1. Click **Save** in the upper right to save your changes to the dashboard.
@ -56,7 +56,7 @@ icon you can hover over to see the event information.
1. Enter a name and select a data source.
1. Complete the rest of the form to build a query and annotation.
The query editor UI changes based on the data source you select. Refer to the [Data source]({{< relref "../../../datasources/" >}}) documentation for details on how to construct a query.
The query editor UI changes based on the data source you select. Refer to the [Data source][] documentation for details on how to construct a query.
## Add a variable
@ -64,7 +64,7 @@ Variables enable you to create more interactive and dynamic dashboards. Instead
and sensor names in your metric queries, you can use variables in their place. Variables are displayed as dropdown lists at the top of
the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
For more information about variables, refer to [Variables]({{< relref "../../variables/" >}}).
For more information about variables, refer to [Variables][].
1. On the **Dashboard settings** page, click **Variable** in the left side section menu and then the **Add variable** button.
1. In the **General** section, the name of the variable. This is the name that you will later use in queries.
@ -95,4 +95,15 @@ A dashboard in Grafana is represented by a JSON object, which stores metadata of
To view a dashboard JSON model, on the **Dashboard settings** page, click **JSON**.
For more information about the JSON fields, refer to [JSON fields]({{< relref "../view-dashboard-json-model/#json-fields" >}}).
For more information about the JSON fields, refer to [JSON fields][].
Reporting enables you to automatically generate PDFs from any of your dashboards and have Grafana email them to interested parties on a schedule. This is available in Grafana Cloud and in Grafana Enterprise.
> If you have [Role-based access control]({{< relref "../../administration/roles-and-permissions/access-control/" >}}) enabled, for some actions you would need to have relevant permissions.
> If you have [Role-based access control][] enabled, for some actions you would need to have relevant permissions.
> Refer to specific guides to understand what permissions are required.
<!--
@ -36,16 +36,16 @@ For information about recent improvements to the reporting UI, refer to [Grafana
## Requirements
- SMTP must be configured for reports to be sent. Refer to [SMTP]({{< relref "../../setup-grafana/configure-grafana/#smtp" >}}) in [Configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}) for more information.
- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering]({{< relref "../../setup-grafana/image-rendering/" >}}) for more information.
- SMTP must be configured for reports to be sent. Refer to [SMTP][] in [Configuration][] for more information.
- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering][] for more information.
## Access control
When [RBAC]({{< relref "../../administration/roles-and-permissions/access-control/" >}}) is enabled, you need to have the relevant [Permissions]({{< relref "../../administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/" >}}) to create and manage reports.
When [RBAC][] is enabled, you need to have the relevant [Permissions][] to create and manage reports.
## Create or update a report
Only organization administrators can create reports by default. You can customize who can create reports with [Role-based access control]({{< relref "../../administration/roles-and-permissions/access-control/" >}}).
Only organization administrators can create reports by default. You can customize who can create reports with [Role-based access control][].
1. Click **Dashboards > Reports** in the side navigation menu.
@ -54,7 +54,7 @@ Only organization administrators can create reports by default. You can customiz
1. Click **+ Create a new report**.
1. Select report dashboard.
- **Source dashboard:** Select the dashboard from which you want to generate the report.
- **Time range:** (optional) Use custom time range for the report. For more information, refer to [Report time range]({{< relref "#report-time-range" >}}).
- **Time range:** (optional) Use custom time range for the report. For more information, refer to [Report time range](#report-time-range).
- **Add another dashboard:** Add more than one dashboard to the report.
1. Format the report.
- **Choose format options for the report:** Select at least one option. Attach report as PDF, embed dashboard as an image, or attach CSV file of table panel data.
@ -75,19 +75,15 @@ Only organization administrators can create reports by default. You can customiz
### Save as draft
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.1.0 and later and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 9.1.0 and later and [Grafana Cloud](/docs/grafana-cloud/).
You can save a report as a draft at any point during the report creation or update process. You can save a report as a draft even if it's missing required fields. Also, the report won't be sent according to its schedule while it's a draft.
### Choose template variables
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud](/docs/grafana-cloud/).
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables]({{< relref "../variables/" >}}) section.
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables][] section.
{{% admonition type="note" %}}
The query variables saved with a report might become of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that occurs, the selected variables must be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report stays up-to-date as new values are added.
@ -95,11 +91,9 @@ The query variables saved with a report might become of date if the results of t
### Render a report with panels or rows set to repeat by a variable
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to [Repeat panels or rows]({{< relref "../../panels-visualizations/configure-panel-options/#configure-repeating-rows-or-panels" >}}).
You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to [Repeat panels or rows][].
#### Caveats
@ -112,9 +106,7 @@ You can include dynamic dashboards with panels or rows, set to repeat by a varia
### Report time range
{{% admonition type="note" %}}
You can set custom report time ranges in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 7.2+ and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** You can set custom report time ranges in [Grafana Enterprise][] 7.2+ and [Grafana Cloud](/docs/grafana-cloud/).
By default, reports use the saved time range of the dashboard. You can change the time range of the report by:
@ -123,7 +115,7 @@ By default, reports use the saved time range of the dashboard. You can change th
The page header of the report displays the time range for the dashboard's data queries. Dashboards set to use the browser's time zone use the time zone on the Grafana server.
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls]({{< relref "./manage-dashboards/#dashboard-time-settings" >}}).
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls][].
### Layout and orientation
@ -138,24 +130,20 @@ If the time zone is set differently between your Grafana server and its remote i
### CSV export
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 8+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] 8+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud](/docs/grafana-cloud/).
You can attach a CSV file to the report email for each table panel on the selected dashboard, along with the PDF report. By default, CSVs larger than 10Mb are not sent which keeps email servers from rejecting the email. You can increase or decrease this limit in the [reporting configuration]({{< relref "#rendering-configuration" >}}).
You can attach a CSV file to the report email for each table panel on the selected dashboard, along with the PDF report. By default, CSVs larger than 10Mb are not sent which keeps email servers from rejecting the email. You can increase or decrease this limit in the [reporting configuration](#rendering-configuration).
This feature relies on the same plugin that supports the [image rendering]({{< relref "../../setup-grafana/image-rendering/" >}}) features.
This feature relies on the same plugin that supports the [image rendering][] features.
When the CSV file is generated, it is temporarily written to the `csv` folder in the Grafana `data` folder.
A background job runs every 10 minutes and removes temporary CSV files. You can configure how long a CSV file should be stored before being removed by configuring the [temp-data-lifetime]({{< relref "../../setup-grafana/configure-grafana/#temp-data-lifetime" >}}) setting. This setting also affects how long a renderer PNG file should be stored.
A background job runs every 10 minutes and removes temporary CSV files. You can configure how long a CSV file should be stored before being removed by configuring the [temp-data-lifetime][] setting. This setting also affects how long a renderer PNG file should be stored.
### Scheduling
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
The scheduler was significantly changed in Grafana Enterprise version 8.1.
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
> The scheduler was significantly changed in Grafana Enterprise version 8.1.
Scheduled reports can be sent once, or repeated on an hourly, daily, weekly, or monthly basis, or sent at custom intervals. You can also disable scheduling by selecting **Never**, for example to send the report via the API.
@ -175,9 +163,7 @@ When you schedule a report with a monthly frequency, and set the start date betw
#### Send a test email
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 7.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
1. In the report, click **Send test email**.
1. In the **Email** field, enter the email address or addresses that you want to test, separated by a semicolon.
@ -188,25 +174,19 @@ The last saved version of the report will be sent to selected emails. You can us
### Pause a report
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
You can pause sending reports from the report list view by clicking the pause icon. The report will not be sent according to its schedule until it is resumed by clicking the resume button on the report row.
### Add multiple dashboards to a report
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
You can add more than one dashboard to a report. Additional dashboards will be rendered as new pages in the same PDF file, or additional images if you chose to embed images in your report email. You cannot add the same dashboard to a report multiple times.
### Embed a dashboard as an image into a report
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
You can send a report email with an image of the dashboard embedded in the email instead of attached as a PDF. In this case, the email recipients can see the dashboard at a glance instead of having to open the PDF.
@ -214,9 +194,7 @@ You can send a report email with an image of the dashboard embedded in the email
You can generate and save PDF files of any dashboard.
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 6.7 and later, and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] version 6.7 and later, and [Grafana Cloud](/docs/grafana-cloud/).
1. In the dashboard that you want to export as PDF, click the **Share dashboard** icon.
1. On the PDF tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
@ -226,7 +204,7 @@ Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterpr
## Send a report via the API
You can send reports programmatically with the [send report]({{< relref "../../developers/http_api/reporting/#send-report" >}}) endpoint in the [HTTP APIs]({{< relref "../../developers/http_api/" >}}).
You can send reports programmatically with the [send report][] endpoint in the [HTTP APIs][].
## Rendering configuration
@ -236,7 +214,7 @@ To make a panel more legible, you can set a scale factor for the rendered images
You can also specify custom fonts that support different Unicode scripts. The DejaVu font is the default used for PDF rendering.
These options are available in the [configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}) file.
These options are available in the [configuration][] file.
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.2 and later, and [Grafana Cloud](/docs/grafana-cloud/).
> **Note:** Available in [Grafana Enterprise][] version 7.2 and later, and [Grafana Cloud](/docs/grafana-cloud/).
You can configure organization-wide report settings in the **Settings** under **Dashboards > Reporting**. Settings are applied to all the reports for current organization.
@ -284,9 +262,53 @@ Currently, the API does not allow for the simultaneous upload of files with iden
## Troubleshoot reporting
To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana/#filters" >}}) for more information.
To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration][] for more information.
```bash
[log]
filters = report:debug
```
{{% docs/reference %}}
[time range controls]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/manage-dashboards"
[time range controls]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/manage-dashboards"
@ -19,14 +19,10 @@ This feature is in [public preview](/docs/release-life-cycle/).
{{% /admonition %}}
{{% admonition type="caution" %}}
> **Warning:** Making your dashboard public could result in a large number of queries to the data sources used by your dashboard.
> This can be mitigated by utilizing the enterprise [caching][] and/or rate limiting features.
Making your dashboard public could result in a large number of queries to the data sources used by your dashboard.
This can be mitigated by utilizing the enterprise [caching]({{< relref "../../administration/data-source-management/#query-and-resource-caching" >}}) and/or rate limiting features.
{{% /admonition %}}
Public dashboards allow you to share your Grafana dashboard with anyone. This is useful when you want to make your dashboard available to the world without requiring access to your Grafana organization. This differs from [dashboard sharing]({{< relref "../share-dashboards-panels" >}}), which either requires recipients to be users in the same Grafana organization or provides limited information, as with a snapshot.
Public dashboards allow you to share your Grafana dashboard with anyone. This is useful when you want to make your dashboard available to the world without requiring access to your Grafana organization. This differs from [dashboard sharing][], which either requires recipients to be users in the same Grafana organization or provides limited information, as with a snapshot.
You can see a list of all your public dashboards in one place by navigating to **Dashboards > Public dashboards**. For each dashboard in the list, the page displays the status, a link to view the dashboard, a link to the public dashboard configuration, and the option to revoke the public URL.
@ -149,15 +145,13 @@ If a Grafana user has read access to the parent dashboard, they can view the pub
## Assess public dashboard usage
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] and [Grafana Cloud](/docs/grafana-cloud).
You can check usage analytics about your public dashboard by clicking the insights icon in the dashboard header:
Learn more about the kind of information provided in the [dashboard insights documentation]({{< relref "../assess-dashboard-usage/#dashboard-insights" >}}).
Learn more about the kind of information provided in the [dashboard insights documentation][].
## Supported data sources
@ -276,4 +270,21 @@ We're excited to share this enhancement with you and we’d love your feedback!
## Custom branding
If you're a Grafana Enterprise customer, you can use custom branding to change the appearance of a public dashboard footer. For more information, refer to [Custom branding](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/configure-custom-branding/).
If you're a Grafana Enterprise customer, you can use custom branding to change the appearance of a public dashboard footer. For more information, refer to [Custom branding][].
A dashboard is a set of one or more [panels]({{< relref "../../panels-visualizations/" >}}) that visually presents your data in one or more rows.
A dashboard is a set of one or more [panels][] that visually presents your data in one or more rows.
For more information about creating dashboards, refer to [Add and organize panels](../add-organize-panels).
@ -49,7 +49,7 @@ Folders help you organize and group dashboards, which is useful when you have ma
**Before you begin:**
- Ensure that you have Grafana Admin or Super Admin permissions. For more information about dashboard permissions, refer to [Dashboard permissions]({{< relref "../../administration/roles-and-permissions/#dashboard-permissions" >}}).
- Ensure that you have Grafana Admin or Super Admin permissions. For more information about dashboard permissions, refer to [Dashboard permissions][].
**To create a dashboard folder:**
@ -86,11 +86,11 @@ To navigate to the dashboard folder page, hover over the name of the folder and
You can assign permissions to a folder. Any permissions you assign are inherited by the dashboards in the folder. An Access Control List (ACL) is used where **Organization Role**, **Team**, and a **User** can be assigned permissions.
For more information about dashboard permissions, refer to [Dashboard permissions]({{< relref "../../administration/roles-and-permissions/#dashboard-permissions" >}}).
For more information about dashboard permissions, refer to [Dashboard permissions][].
## Export and import dashboards
You can use the Grafana UI or the [HTTP API]({{< relref "../../developers/http_api/dashboard/#create-update-dashboard" >}}) to export and import dashboards.
You can use the Grafana UI or the [HTTP API][] to export and import dashboards.
### Export a dashboard
@ -170,3 +170,14 @@ In this graph, we set graph to show bars instead of lines and set the **No value
### More examples
You can find more examples in `public/dashboards/` directory of your Grafana installation.
@ -94,15 +94,13 @@ If you created a snapshot by mistake, click **Delete snapshot** to remove the sn
### Dashboard export
Grafana dashboards can easily be exported and imported. For more information, refer to [Export and import dashboards]({{< relref "./manage-dashboards/#export-and-import-dashboards" >}}).
Grafana dashboards can easily be exported and imported. For more information, refer to [Export and import dashboards][].
## Export dashboard as PDF
You can generate and save PDF files of any dashboard.
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
> **Note:** Available in [Grafana Enterprise][] and [Grafana Cloud](/docs/grafana-cloud/).
1. Click **Dashboards** in the left-side menu.
1. Click the dashboard you want to share.
@ -132,7 +130,7 @@ The **Link** tab shows the current time range, template variables, and the defau
1. Send the copied URL to a Grafana user with authorization to view the link.
1. You also optionally click **Direct link rendered image** to share an image of the panel.
For more information, refer to [Image rendering]({{< relref "../../setup-grafana/image-rendering/" >}}).
For more information, refer to [Image rendering][].
The following example shows a link to a server-side rendered PNG:
@ -191,3 +189,14 @@ To create a library panel from the **Share Panel** dialog:
1. In **Save in folder**, select the folder in which to save the library panel. By default, the root level is selected.
1. Click **Create library panel** to save your changes.
1. Save the dashboard.
{{% docs/reference %}}
[Export and import dashboards]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/manage-dashboards#export-and-import-dashboards"
[Export and import dashboards]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/manage-dashboards#export-and-import-dashboards"
@ -39,12 +39,12 @@ The following image and descriptions highlight all dashboard features.
- (3) **Share dashboard or panel**: Use this option to share the current dashboard or panel using a link or snapshot. You can also export the dashboard definition from the share modal.
- (4) **Add**: Use this option to add a panel, dashboard row, or library panel to the current dashboard.
- (5) **Save dashboard**: Click to save changes to your dashboard.
- (6) **Dashboard insights**: Click to view analytics about your dashboard including information about users, activity, query counts. Learn more about [dashboard analytics]({{< relref "../assess-dashboard-usage/" >}}).
- (7) **Dashboard settings**: Use this option to change dashboard name, folder, and tags and manage variables and annotation queries. Learn more about [dashboard settings]({{< relref "../build-dashboards/modify-dashboard-settings/" >}}).
- (6) **Dashboard insights**: Click to view analytics about your dashboard including information about users, activity, query counts. Learn more about [dashboard analytics][].
- (7) **Dashboard settings**: Use this option to change dashboard name, folder, and tags and manage variables and annotation queries. Learn more about [dashboard settings][].
- (8) **Time picker dropdown**: Click to select relative time range options and set custom absolute time ranges.
- You can change the **Timezone** and **fiscal year** settings from the time range controls by clicking the **Change time settings** button.
- Time settings are saved on a per-dashboard basis.
- (9) **Zoom out time range**: Click to zoom out the time range. Learn more about how to use [common time range controls]({{< relref "#common-time-range-controls" >}}).
- (9) **Zoom out time range**: Click to zoom out the time range. Learn more about how to use [common time range controls](#common-time-range-controls).
- (10) **Refresh dashboard**: Click to immediately trigger queries and refresh dashboard data.
- (11) **Refresh dashboard time interval**: Click to select a dashboard auto refresh time interval.
- (12) **View mode**: Click to display the dashboard on a large screen such as a TV or a kiosk. View mode hides irrelevant information such as navigation menus. Learn more about view mode in our [How to Create Kiosks to Display Dashboards on a TV blog post](https://grafana.com/blog/2019/05/02/grafana-tutorial-how-to-create-kiosks-to-display-dashboards-on-a-tv/).
@ -56,7 +56,7 @@ The following image and descriptions highlight all dashboard features.
- (15) **Dashboard row**: A dashboard row is a logical divider within a dashboard that groups panels together.
- Rows can be collapsed or expanded allowing you to hide parts of the dashboard.
- Panels inside a collapsed row do not issue queries.
- Use [repeating rows]({{< relref "../build-dashboards/create-dashboard/#configure-repeating-rows" >}}) to dynamically create rows based on a template variable.
- Use [repeating rows][] to dynamically create rows based on a template variable.
## Keyboard shortcuts
@ -209,6 +209,17 @@ Selecting the **Auto** interval schedules a refresh based on the query time rang
You can control the time range of a dashboard by providing the following query parameters in the dashboard URL:
- `from`: Defines the lower limit of the time range, specified in `ms`, `epoch`, or [relative time]({{< relref "#relative-time-range" >}})
- `to`: Defines the upper limit of the time range, specified in `ms`, `epoch`, or [relative time]({{< relref "#relative-time-range" >}})
- `from`: Defines the lower limit of the time range, specified in `ms`, `epoch`, or [relative time](#relative-time-range)
- `to`: Defines the upper limit of the time range, specified in `ms`, `epoch`, or [relative time](#relative-time-range)
- `time` and `time.window`: Defines a time range from `time-time.window/2` to `time+time.window/2`. Both parameters should be specified in `ms`. For example `?time=1500000000000&time.window=10000` results in 10s time range from 1499999995000 to 1500000005000
| Query | Query-generated list of values such as metric names, server names, sensor IDs, data centers, and so on. [Add a query variable]({{< relref "#add-a-query-variable" >}}). |
| Custom | Define the variable options manually using a comma-separated list. [Add a custom variable]({{< relref "#add-a-custom-variable" >}}). |
| Text box | Display a free text input field with an optional default value. [Add a text box variable]({{< relref "#add-a-text-box-variable" >}}). |
| Constant | Define a hidden constant. [Add a constant variable]({{< relref "#add-a-constant-variable" >}}). |
| Data source | Quickly change the data source for an entire dashboard. [Add a data source variable]({{< relref "#add-a-data-source-variable" >}}). |
| Interval | Interval variables represent time spans. [Add an interval variable]({{< relref "#add-an-interval-variable" >}}). |
| Ad hoc filters | Key/value filters that are automatically added to all metric queries for a data source (Prometheus, Loki, InfluxDB, and Elasticsearch only). [Add ad hoc filters]({{< relref "#add-ad-hoc-filters" >}}). |
| Global variables | Built-in variables that can be used in expressions in the query editor. Refer to [Global variables]({{< relref "#global-variables" >}}). |
| Chained variables | Variable queries can contain other variables. Refer to [Chained variables]({{< relref "#chained-variables" >}}). |
| Query | Query-generated list of values such as metric names, server names, sensor IDs, data centers, and so on. [Add a query variable](#add-a-query-variable). |
| Custom | Define the variable options manually using a comma-separated list. [Add a custom variable](#add-a-custom-variable). |
| Text box | Display a free text input field with an optional default value. [Add a text box variable](#add-a-text-box-variable). |
| Constant | Define a hidden constant. [Add a constant variable](#add-a-constant-variable). |
| Data source | Quickly change the data source for an entire dashboard. [Add a data source variable](#add-a-data-source-variable). |
| Interval | Interval variables represent time spans. [Add an interval variable](#add-an-interval-variable). |
| Ad hoc filters | Key/value filters that are automatically added to all metric queries for a data source (Prometheus, Loki, InfluxDB, and Elasticsearch only). [Add ad hoc filters](#add-ad-hoc-filters). |
| Global variables | Built-in variables that can be used in expressions in the query editor. Refer to [Global variables](#global-variables). |
| Chained variables | Variable queries can contain other variables. Refer to [Chained variables](#chained-variables). |
## Enter General options
@ -86,12 +86,10 @@ Query variables are generally only supported for strings. If your query returns
Query expressions can contain references to other variables and in effect create linked variables. Grafana detects this and automatically refreshes a variable when one of its linked variables change.
{{% admonition type="note" %}}
Query expressions are different for each data source. For more information, refer to the documentation for your [data source]({{< relref "../../../datasources/" >}}).
{{% /admonition %}}
> **Note:** Query expressions are different for each data source. For more information, refer to the documentation for your [data source][].
1. [Enter general options](#enter-general-options).
1. In the **Data source** list, select the target data source for the query. For more information about data sources, refer to [Add a data source]({{< relref "../../../administration/data-source-management#add-a-data-source" >}}).
1. In the **Data source** list, select the target data source for the query. For more information about data sources, refer to [Add a data source][].
1. In the **Refresh** list, select when the variable should update options.
- **On Dashboard Load:** Queries the data source every time the dashboard loads. This slows down dashboard loading, because the variable query needs to be completed before dashboard can be initialized.
- **On Time Range Change:** Queries the data source when the dashboard time range changes. Only use this option if your variable options query contains a time range filter or is dependent on the dashboard time range.
@ -99,9 +97,9 @@ Query expressions are different for each data source. For more information, refe
- The query field varies according to your data source. Some data sources have custom query editors.
- Make sure that the query returns values named `__text` and `__value` as appropriate in your query syntax. For example, in SQL, you can use a query such as `SELECT hostname AS __text, id AS __value FROM MyTable`. Queries for other languages will vary depending on syntax.
- If you need more room in a single input field query editor, then hover your cursor over the lines in the lower right corner of the field and drag downward to expand.
1. (Optional) In the **Regex** field, type a regex expression to filter or capture specific parts of the names returned by your data source query. To see examples, refer to [Filter variables with regex]({{< relref "#filter-variables-with-regex" >}}).
1. (Optional) In the **Regex** field, type a regex expression to filter or capture specific parts of the names returned by your data source query. To see examples, refer to [Filter variables with regex](#filter-variables-with-regex).
1. In the **Sort** list, select the sort order for values to be displayed in the dropdown list. The default option, **Disabled**, means that the order of options returned by your data source query will be used.
1. (Optional) Enter [Selection Options]({{< relref "#configure-variable-selection-options" >}}).
1. (Optional) Enter [Selection Options](#configure-variable-selection-options).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
@ -109,11 +107,11 @@ Query expressions are different for each data source. For more information, refe
Use a _custom_ variable for a value that does not change, such as a number or a string.
For example, if you have server names or region names that never change, then you might want to create them as custom variables rather than query variables. Because they do not change, you might use them in [chained variables]({{< relref "#chained-variables" >}}) rather than other query variables. That would reduce the number of queries Grafana must send when chained variables are updated.
For example, if you have server names or region names that never change, then you might want to create them as custom variables rather than query variables. Because they do not change, you might use them in [chained variables](#chained-variables) rather than other query variables. That would reduce the number of queries Grafana must send when chained variables are updated.
1. [Enter general options](#enter-general-options).
1. In the **Values separated by comma** list, enter the values for this variable in a comma-separated list. You can include numbers, strings, or key/value pairs separated by a space and a colon. For example, `key1 : value1,key2 : value2`.
1. (Optional) Enter [Selection Options]({{< relref "#configure-variable-selection-options" >}}).
1. (Optional) Enter [Selection Options](#configure-variable-selection-options).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
@ -137,7 +135,7 @@ Constant variables are _not_ flexible. Each constant variable only holds one val
Constant variables are useful when you have complex values that you need to include in queries but don't want to retype in every query. For example, if you had a server path called `i-0b6a61efe2ab843gg`, then you could replace it with a variable called `$path_gg`.
1. [Enter general options](#enter-general-options).
1. In the **Value** field, enter the variable value. You can enter letters, numbers, and symbols. You can even use wildcards if you use [raw format]({{< relref "../variable-syntax/#raw" >}}).
1. In the **Value** field, enter the variable value. You can enter letters, numbers, and symbols. You can even use wildcards if you use [raw format][].
1. In **Preview of values**, Grafana displays the current variable value. Review it to ensure it matches what you expect.
1. Click **Add** to add the variable to the dashboard.
@ -148,10 +146,10 @@ _Data source_ variables enable you to quickly change the data source for an enti
1. [Enter general options](#enter-general-options).
1. In the **Type** list, select the target data source for the variable.
You can also click **Open advanced data source picker** to see more options, including adding a data source (Admins only). For more information about data sources, refer to [Add a data source]({{< relref "../../../administration/data-source-management#add-a-data-source" >}}).
You can also click **Open advanced data source picker** to see more options, including adding a data source (Admins only). For more information about data sources, refer to [Add a data source][].
1. (Optional) In **Instance name filter**, enter a regex filter for which data source instances to choose from in the variable value drop-down list. Leave this field empty to display all instances.
1. (Optional) Enter [Selection Options]({{< relref "#configure-variable-selection-options" >}}).
1. (Optional) Enter [Selection Options](#configure-variable-selection-options).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
@ -194,7 +192,7 @@ Ad hoc filter variables only work with Prometheus, Loki, InfluxDB, and Elasticse
1. [Enter general options](#enter-general-options).
1. In the **Data source** list, select the target data source.
You can also click **Open advanced data source picker** to see more options, including adding a data source (Admins only). For more information about data sources, refer to [Add a data source]({{< relref "../../../administration/data-source-management#add-a-data-source" >}}).
You can also click **Open advanced data source picker** to see more options, including adding a data source (Admins only). For more information about data sources, refer to [Add a data source][].
1. Click **Add** to add the variable to the dashboard.
@ -233,7 +231,7 @@ Automatic escaping and formatting can cause problems and it can be tricky to gra
If you do not want Grafana to do this automatic regex escaping and formatting, then you must do one of the following:
- Turn off the **Multi-value** or **Include All option** options.
- Use the [raw variable format]({{< relref "../variable-syntax/#raw" >}}).
- Use the [raw variable format][].
### Include All option
@ -324,7 +322,7 @@ Currently only supported for Prometheus and Loki data sources. This variable rep
### $\_\_rate_interval
Currently only supported for Prometheus data sources. The `$__rate_interval` variable is meant to be used in the rate function. Refer to [Prometheus query variables]({{< relref "../../../datasources/prometheus/template-variables#use-__rate_interval" >}}) for details.
Currently only supported for Prometheus data sources. The `$__rate_interval` variable is meant to be used in the rate function. Refer to [Prometheus query variables][] for details.
### $\_\_rate_interval_ms
@ -520,7 +518,7 @@ For example, if you have a series of four linked variables (country, region, ser
## Manage variables
The variables page lets you [add]({{< relref "./add-template-variables/" >}}) variables and manage existing variables. It also allows you to [inspect]({{< relref "inspect-variable/" >}}) variables and identify whether a variable is being referenced (or used) in other variables or dashboard.
The variables page lets you [add][] variables and manage existing variables. It also allows you to [inspect][] variables and identify whether a variable is being referenced (or used) in other variables or dashboard.
**Move:** You can move a variable up or down the list using drag and drop.
The variables page lets you easily identify whether a variable is being referenced (or used) in other variables or dashboard. In addition, you can also [add]({{< relref "./add-template-variables/" >}}) and [manage variables]({{< relref "./add-template-variables/#manage-variables" >}}) on this page.
The variables page lets you easily identify whether a variable is being referenced (or used) in other variables or dashboard. In addition, you can also [add][] and [manage variables][] on this page.
{{% admonition type="note" %}}
This feature is available in Grafana 7.4 and later versions.
@ -35,3 +35,11 @@ Any variable that is referenced or used has a green check mark next to it, while
In addition, all referenced variables have a dependency icon next to the green check mark. You can click on the icon to view the dependency map. The dependency map can be moved. You can zoom in out with mouse wheel or track pad equivalent.
@ -27,7 +27,7 @@ Panel titles and metric queries can refer to variables using two different synta
This syntax is easy to read, but it does not allow you to use a variable in the middle of a word.
**Example:** apps.frontend.$server.requests.count
- `${var_name}` Use this syntax when you want to interpolate a variable in the middle of an expression.
- `${var_name:<format>}` This format gives you more control over how Grafana interpolates values. Refer to [Advanced variable format options]({{< relref "#advanced-variable-format-options" >}}) for more detail on all the formatting types.
- `${var_name:<format>}` This format gives you more control over how Grafana interpolates values. Refer to [Advanced variable format options](#advanced-variable-format-options) for more detail on all the formatting types.
- `[[varname]]` Do not use. Deprecated old syntax, will be removed in a future release.
Before queries are sent to your data source the query is _interpolated_, meaning the variable is replaced with its current value. During
@ -35,7 +35,7 @@ interpolation, the variable value might be _escaped_ in order to conform to the
For example, a variable used in a regex expression in an InfluxDB or Prometheus query will be regex escaped. Read the data source specific
documentation topic for details on value escaping during interpolation.
For advanced syntax to override data source default formatting, refer to [Advanced variable format options]({{< relref "#advanced-variable-format-options" >}}).
For advanced syntax to override data source default formatting, refer to [Advanced variable format options](#advanced-variable-format-options).
@ -29,9 +29,17 @@ Panels can be dragged, dropped, and resized to rearrange them on the dashboard.
Before you add a panel, ensure that you have configured a data source.
- For more information about adding and managing data sources as an administrator, refer to [Data source management]({{< relref "../administration/data-source-management/" >}}).
- For details about using specific data sources, refer to [Data sources]({{< relref "../datasources/" >}}).
- For more information about adding and managing data sources as an administrator, refer to [Data source management][].
- For details about using specific data sources, refer to [Data sources][].
@ -29,7 +29,7 @@ You can use data link variables or data links to create links between panels.
## Data link variables
You can use variables in data links to refer to series fields, labels, and values. For more information about data links, refer to [Data links]({{< relref "#data-links" >}}).
You can use variables in data links to refer to series fields, labels, and values. For more information about data links, refer to [Data links](#data-links).
To see a list of available variables, type `$` in the data link **URL** field to see a list of variables that you can use.
@ -37,14 +37,14 @@ To see a list of available variables, type `$` in the data link **URL** field to
These variables changed in 6.4 so if you have an older version of Grafana, then use the version picker to select docs for an older version of Grafana.
{{% /admonition %}}
You can also use template variables in your data links URLs, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}) for more information on template variables.
You can also use template variables in your data links URLs, refer to [Templates and variables][] for more information on template variables.
## Time range panel variables
These variables allow you to include the current time range in the data link URL.
- `__url_time_range` - current dashboard's time range (i.e. `?from=now-6h&to=now`)
- `$__from and $__to` - For more information, refer to [Global variables]({{< relref "../../dashboards/variables/add-template-variables/#__from-and-__to" >}}).
- `$__from and $__to` - For more information, refer to [Global variables][].
## Series variables
@ -90,7 +90,7 @@ Data links allow you to provide more granular context to your links. You can cre
The link itself is accessible in different ways depending on the visualization. For the Graph you need to click on a data point or line, for a panel like
Stat, Gauge, or Bar Gauge you can click anywhere on the visualization to open the context menu.
You can use variables in data links to send people to a detailed dashboard with preserved data filters. For example, you could use variables to specify a time range, series, and variable selection. For more information, refer to [Data link variables]({{< relref "#data-link-variables" >}}).
You can use variables in data links to send people to a detailed dashboard with preserved data filters. For example, you could use variables to specify a time range, series, and variable selection. For more information, refer to [Data link variables](#data-link-variables).
### Typeahead suggestions
@ -110,7 +110,7 @@ When creating or updating a data link, press Cmd+Space or Ctrl+Space on your key
1. Enter a **Title**. **Title** is a human-readable label for the link that will be displayed in the UI.
1. Enter the **URL** you want to link to.
You can even add one of the template variables defined in the dashboard. Click in the **URL** field and then type `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. By adding template variables to your panel link, the link sends the user to the right context, with the relevant variables already set. For more information, refer to [Data link variables]({{< relref "#data-link-variables" >}}).
You can even add one of the template variables defined in the dashboard. Click in the **URL** field and then type `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. By adding template variables to your panel link, the link sends the user to the right context, with the relevant variables already set. For more information, refer to [Data link variables](#data-link-variables).
1. If you want the link to open in a new tab, then select **Open in a new tab**.
1. Click **Save** to save changes and close the window.
@ -129,3 +129,11 @@ When creating or updating a data link, press Cmd+Space or Ctrl+Space on your key
1. Scroll down to the Data links section, expand it, and find the link that you want to delete.
1. Click the **X** icon next to the link you want to delete.
1. Click **Save** in the upper right to save your changes to the dashboard.
{{% docs/reference %}}
[Templates and variables]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/variables"
[Templates and variables]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/variables"
@ -72,10 +72,33 @@ By default, Grafana specifies the color of your series data, which you can chang
## Sort series
You can change legend mode to **Table** and choose [calculations]({{< relref "../calculation-types/" >}}) to be displayed in the legend. Click the calculation name header in the legend table to sort the values in the table in ascending or descending order.
You can change legend mode to **Table** and choose [calculations][] to be displayed in the legend. Click the calculation name header in the legend table to sort the values in the table in ascending or descending order.
{{% admonition type="note" %}}
This feature is only supported in these panels: Bar chart, Histogram, Time series.
@ -67,7 +67,7 @@ Add a title and description to a panel to share with users any important informa
Text entered in this field appears in a tooltip in the upper-left corner of the panel.
You can use [variables you have defined]({{< relref "../../dashboards/variables/" >}}) in the **Title** and **Description** field, but not [global variables]({{< relref "../../dashboards/variables/add-template-variables/#global-variables" >}}).
You can use [variables you have defined][] in the **Title** and **Description** field, but not [global variables][].
@ -89,7 +89,7 @@ Explore and export panel, panel data, and data frame JSON models.
## Configure repeating panels
You can configure Grafana to dynamically add panels or rows to a dashboard. A dynamic panel is a panel that the system creates based on the value of a variable. Variables dynamically change your queries across all panels in a dashboard. For more information about repeating rows, refer to [Configure repeating rows]({{< relref "../../dashboards/build-dashboards/create-dashboard/#configure-repeating-rows" >}}).
You can configure Grafana to dynamically add panels or rows to a dashboard. A dynamic panel is a panel that the system creates based on the value of a variable. Variables dynamically change your queries across all panels in a dashboard. For more information about repeating rows, refer to [Configure repeating rows][].
{{% admonition type="note" %}}
Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
@ -113,3 +113,14 @@ To see an example of repeating panels, refer to [this dashboard with repeating p
- Choose `vertical` to arrange panels in a column. The width of repeated panels is the same as the original, repeated panel.
1. To propagate changes to all panels, reload the dashboard.
{{% docs/reference %}}
[variables you have defined]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/variables"
[variables you have defined]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/dashboards/variables"
The data model used in Grafana, namely the [data frame]({{< relref "../../developers/plugins/introduction-to-plugin-development/data-frames/" >}}), is a columnar-oriented table structure that unifies both time series and table query results. Each column within this structure is called a _field_. A field can represent a single time series or table column.
The data model used in Grafana, namely the [data frame][], is a columnar-oriented table structure that unifies both time series and table query results. Each column within this structure is called a _field_. A field can represent a single time series or table column.
Field options allow you to change how the data is displayed in your visualizations. Options and overrides that you apply do not change the data, they change how Grafana displays the data. When you change an option, it is applied to all fields, meaning all series or columns. For example, if you change the unit to percentage, then all fields with numeric values are displayed in percentages.
For a complete list of field formatting options, refer to [Standard options definitions]({{< relref "#standard-options-definitions" >}}).
For a complete list of field formatting options, refer to [Standard options definitions](#standard-options-definitions).
> You can apply standard options to most built-in Grafana panels. Some older panels and community panels that have not updated to the new panel and data model will be missing either all or some of these field options.
@ -37,7 +37,7 @@ For a complete list of field formatting options, refer to [Standard options defi
1. In the panel display options pane, locate the **Standard options** section.
1. Select the standard options you want to apply.
For more information about standard options, refer to [Standard options definitions]({{< relref "#standard-options-definitions" >}}).
For more information about standard options, refer to [Standard options definitions](#standard-options-definitions).
1. To preview your change, click outside of the field option box you are editing or press **Enter**.
@ -96,7 +96,7 @@ To display all decimals, set the unit to `String`.
### Display name
Lets you set the display title of all fields. You can use [variables]({{< relref "../../dashboards/variables/" >}}) in the field title.
Lets you set the display title of all fields. You can use [variables][] in the field title.
When multiple stats, fields, or series are shown, this field controls the title in each stat. You can use expressions like `${__field.name}` to use only the series name or the field name in title.
@ -146,3 +146,11 @@ Select one of the following palettes:
### No value
Enter what Grafana should display if the field value is empty or null. The default value is a hyphen (-).
@ -26,17 +26,17 @@ This section includes information about using thresholds in your visualizations.
A threshold is a value that you specify for a metric that is visually reflected in a dashboard when the threshold value is met or exceeded.
Thresholds provide one method for you to conditionally style and color your visualizations based on query results. You can apply thresholds to most, but not all, visualizations. For more information about visualizations, refer to [Visualization panels]({{< relref "../visualizations/" >}}).
Thresholds provide one method for you to conditionally style and color your visualizations based on query results. You can apply thresholds to most, but not all, visualizations. For more information about visualizations, refer to [Visualization panels][].
You can use thresholds to:
- Color grid lines or grid areas in the [Time-series visualization]({{< relref "../visualizations/time-series/" >}})
- Color lines in the [Time-series visualization]({{< relref "../visualizations/time-series#from-thresholds" >}})
- Color the background or value text in the [Stat visualization]({{< relref "../visualizations/stat/" >}})
- Color the gauge and threshold markers in the [Gauge visualization]({{< relref "../visualizations/gauge/" >}})
- Color markers in the [Geomap visualization]({{< relref "../visualizations/geomap/" >}})
- Color cell text or background in the [Table visualization]({{< relref "../visualizations/table/" >}})
- Define regions and region colors in the [State timeline visualization]({{< relref "../visualizations/state-timeline/" >}})
- Color grid lines or grid areas in the [Time-series visualization][]
- Color lines in the [Time-series visualization][]
- Color the background or value text in the [Stat visualization][]
- Color the gauge and threshold markers in the [Gauge visualization][]
- Color markers in the [Geomap visualization][]
- Color cell text or background in the [Table visualization][]
- Define regions and region colors in the [State timeline visualization][]
There are two types of thresholds:
@ -92,3 +92,26 @@ In the Graph panel visualization, thresholds enable you to add lines or sections
- **Line -** Toggle the display of the threshold line.
- **Y-Axis -** Choose to display the y-axis on either the **left** or **right** of the panel.
1. Click **Save** to save the changes in the dashboard.
@ -49,16 +49,16 @@ This section describes the areas of the Grafana panel editor.
1. Visualization preview: The visualization preview section contains the following options:
- **Table view:** Convert any visualization to a table so you can see the data. Table views are helpful for troubleshooting. This view only contains the raw data. It does not include transformations you might have applied to the data or the formatting options available in the [Table]({{< relref "../visualizations/table/" >}}) visualization.
- **Table view:** Convert any visualization to a table so you can see the data. Table views are helpful for troubleshooting. This view only contains the raw data. It does not include transformations you might have applied to the data or the formatting options available in the [Table][] visualization.
- **Fill:** The visualization preview fills the available space. If you change the width of the side pane or height of the bottom pane the visualization changes to fill the available space.
- **Actual:** The visualization preview will have the exact size as the size on the dashboard. If not enough space is available, the visualization will scale down preserving the aspect ratio.
- **Time range controls:****Default** is either the browser local timezone or the timezone selected at a higher level.
1. Data section: The data section contains tabs where you enter queries, transform your data, and create alert rules (if applicable).
- **Query tab:** Select your data source and enter queries here. For more information, refer to [Add a query]({{< relref "../query-transform-data/#add-a-query" >}}). When you create a new dashboard, you'll be prompted to select a data source before you get to the panel editor. You set or update the data source in existing dashboards using the dropdown in the **Query** tab.
- **Transform tab:** Apply data transformations. For more information, refer to [Transform data]({{< relref "../query-transform-data/transform-data/" >}}).
- **Alert tab:** Write alert rules. For more information, refer to [the overview of Grafana Alerting]({{< relref "../../alerting/" >}}).
- **Query tab:** Select your data source and enter queries here. For more information, refer to [Add a query][]. When you create a new dashboard, you'll be prompted to select a data source before you get to the panel editor. You set or update the data source in existing dashboards using the dropdown in the **Query** tab.
- **Transform tab:** Apply data transformations. For more information, refer to [Transform data][].
- **Alert tab:** Write alert rules. For more information, refer to [the overview of Grafana Alerting][].
1. Panel display options: The display options section contains tabs where you configure almost every aspect of your data visualization.
@ -85,3 +85,17 @@ The panel inspector consists of the following options:
1. **Query tab -** Shows you the requests to the server sent when Grafana queries the data source.
1. **Error tab -** Shows the error. Only visible when query returns error.
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/).
@ -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/<GRAFANAVERSION>/panels-visualizations/query-transform-data/expression-queries"
[Use expressions to manipulate data]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/query-transform-data/expression-queries"
@ -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.
[No data and error handling]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/alerting/alerting-rules/create-grafana-managed-rule#configure-no-data-and-error-handling"
[No data and error handling]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/alerting/alerting-rules/create-grafana-managed-rule#configure-no-data-and-error-handling"
@ -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.
@ -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.).
@ -24,28 +24,28 @@ If you are unsure which visualization to pick, Grafana can provide visualization
{{% /admonition %}}
- Graphs & charts
- [Time series]({{< relref "time-series/" >}}) is the default and main Graph visualization.
- [State timeline]({{< relref "state-timeline/" >}}) for state changes over time.
- [Status history]({{< relref "status-history/" >}}) for periodic state over time.
- [Bar chart]({{< relref "bar-chart/" >}}) shows any categorical data.
- [Histogram]({{< relref "histogram/" >}}) calculates and shows value distribution in a bar chart.
- [Heatmap]({{< relref "heatmap/" >}}) visualizes data in two dimensions, used typically for the magnitude of a phenomenon.
- [Pie chart]({{< relref "pie-chart/" >}}) is typically used where proportionality is important.
- [Candlestick]({{< relref "candlestick/" >}}) is typically for financial data where the focus is price/data movement.
- [Time series][] is the default and main Graph visualization.
- [State timeline][] for state changes over time.
- [Status history][] for periodic state over time.
- [Bar chart][] shows any categorical data.
- [Histogram][] calculates and shows value distribution in a bar chart.
- [Heatmap][] visualizes data in two dimensions, used typically for the magnitude of a phenomenon.
- [Pie chart][] is typically used where proportionality is important.
- [Candlestick][] is typically for financial data where the focus is price/data movement.
- Stats & numbers
- [Stat]({{< relref "stat/" >}}) for big stats and optional sparkline.
- [Bar gauge]({{< relref "bar-gauge/" >}}) is a horizontal or vertical bar gauge.
- [Stat][] for big stats and optional sparkline.
- [Bar gauge][] is a horizontal or vertical bar gauge.
- Misc
- [Table]({{< relref "table/" >}}) is the main and only table visualization.
- [Logs]({{< relref "logs/" >}}) is the main visualization for logs.
- [Node Graph]({{< relref "node-graph/" >}}) for directed graphs or networks.
- [Traces]({{< relref "traces/" >}}) is the main visualization for traces.
- [Flame Graph]({{< relref "flame-graph/" >}}) is the main visualization for profiling.
- [Table][] is the main and only table visualization.
- [Logs][] is the main visualization for logs.
- [Node Graph][] for directed graphs or networks.
- [Traces][] is the main visualization for traces.
- [Flame Graph][] is the main visualization for profiling.
- Widgets
- [Dashboard list]({{< relref "dashboard-list/" >}}) can list dashboards.
- [Alert list]({{< relref "alert-list/" >}}) can list alerts.
- [Text panel]({{< relref "text/" >}}) can show markdown and html.
- [News panel]({{< relref "news/" >}}) can show RSS feeds.
- [Dashboard list][] can list dashboards.
- [Alert list][] can list alerts.
- [Text panel][] can show markdown and html.
- [News panel][] can show RSS feeds.
## Get more
@ -57,45 +57,45 @@ Below you can find some good examples for how all the visualizations in Grafana
### Graphs
For time based line, area and bar charts we recommend the default [Time series]({{< relref "time-series/" >}}) visualization. [This public demo dashboard](https://play.grafana.org/d/000000016/1-time-series-graphs?orgId=1) contains many different examples for how this visualization can be configured and styled.
For time based line, area and bar charts we recommend the default [Time series][] visualization. [This public demo dashboard](https://play.grafana.org/d/000000016/1-time-series-graphs?orgId=1) contains many different examples for how this visualization can be configured and styled.
The [Stat]({{< relref "stat/" >}}) visualization shows one large stat value with an optional graph sparkline. You can control the background or value color using thresholds or color scales.
The [Stat][] visualization shows one large stat value with an optional graph sparkline. You can control the background or value color using thresholds or color scales.
If you want to present a value as it relates to a min and max value you have two options. First a standard [Radial Gauge]({{< relref "gauge/" >}}) shown below.
If you want to present a value as it relates to a min and max value you have two options. First a standard [Radial Gauge][] shown below.
@ -104,3 +104,68 @@ To show value distribution over, time use the [heatmap]({{< relref "heatmap/" >}
The state timeline panel visualization shows discrete state changes over time. When used with time series, the thresholds are used to turn the numerical values into discrete state regions.
{{<figuresrc="/static/img/docs/v8/state_timeline_strings.png"max-width="700px"caption="state timeline with string states">}}
Use Alert list to display your alerts. You can configure the list to show the current state. You can read more about alerts in [Grafana Alerting overview]({{< relref "../../../alerting/" >}}).
Use Alert list to display your alerts. You can configure the list to show the current state. You can read more about alerts in [Grafana Alerting overview][].
@ -133,7 +133,7 @@ Gradient color is generated based on the hue of the line color.
### Legend calculations
Choose which of the [standard calculations]({{< relref "../../calculation-types/" >}}) to show in the legend. You can have more than one.
Choose which of the [standard calculations][] to show in the legend. You can have more than one.
For more information about the legend, refer to [Configure a legend](../configure-legend/).
@ -167,7 +167,7 @@ Display all Y-axes on the right side.
Hide all axes.
To selectively hide axes, [Add a field override]({{< relref "../../configure-overrides#add-a-field-override" >}}) that targets specific fields.
To selectively hide axes, [Add a field override][] that targets specific fields.
### Label
@ -187,4 +187,15 @@ Set a **Soft min** or **soft max** option for better control of Y-axis limits. B
**Soft min** and **soft max** settings can prevent blips from turning into mountains when the data is mostly flat, and hard min or max derived from standard min and max field options can prevent intermittent spikes from flattening useful detail by clipping the spikes past a defined point.
You can set standard min/max options to define hard limits of the Y-axis. For more information, refer to [Standard options definitions]({{< relref "../../configure-standard-options/#max" >}}).
You can set standard min/max options to define hard limits of the Y-axis. For more information, refer to [Standard options definitions][].
{{% docs/reference %}}
[Add a field override]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/configure-overrides#add-a-field-override"
[Add a field override]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/configure-overrides#add-a-field-override"
@ -37,7 +37,7 @@ Choose how Grafana displays your data.
Show a calculated value based on all rows.
- **Calculation -** Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types]({{< relref "../../calculation-types/" >}}).
- **Calculation -** Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types][].
- **Fields -** Select the fields display in the panel.
#### All values
@ -82,3 +82,8 @@ Automatically show x-axis scrollbar when there is a large amount of data.
Limit the minimum height of the bar row in the horizontal direction.
Automatically show y-axis scrollbar when there is a large amount of data.
The Candlestick panel builds upon the foundation of the [time series]({{< relref "time-series/" >}}) panel and includes many common configuration settings.
The Candlestick panel builds upon the foundation of the [time series][] panel and includes many common configuration settings.
## Mode
@ -65,4 +65,9 @@ These values are hidden from the legend.
## Additional fields
The candlestick panel is based on the time series panel. It can visualization additional data dimensions beyond open, high, low, close, and volume The **Include** and **Ignore** options allow the panel to visualize other included data such as simple moving averages, Bollinger bands and more, using the same styles and configurations available in the [time series]({{< relref "time-series/" >}}) panel.
The candlestick panel is based on the time series panel. It can visualization additional data dimensions beyond open, high, low, close, and volume The **Include** and **Ignore** options allow the panel to visualize other included data such as simple moving averages, Bollinger bands and more, using the same styles and configurations available in the [time series][] panel.
@ -32,7 +32,7 @@ On each dashboard load, this panel queries the dashboard list, always providing
Use these options to refine your visualization.
- **Include current time range -** Select this option to propagate the time range of the current dashboard to the dashboard links. When the user clicks a link, the linked dashboard opens with the indicated time range already set.
- **Include current template variable values -** Select this option to include template variables currently used as query parameters in a link. When the user clicks the link, any matching templates in the linked dashboard are set to the values from the link. Learn more about [Dashboard URL variables]({{< relref "../../../dashboards/build-dashboards/create-dashboard-url-variables/" >}}).
- **Include current template variable values -** Select this option to include template variables currently used as query parameters in a link. When the user clicks the link, any matching templates in the linked dashboard are set to the values from the link. Learn more about [Dashboard URL variables][].
- **Starred -** Display starred dashboards in alphabetical order.
- **Search -** Display dashboards by search query or tags. You must enter at least one value in **Query** or **Tags**. For the **Query** and **Tags** fields. Variable interpolation is supported, for example,`$my_var` or `${my_var}`.
@ -48,3 +48,8 @@ These options only apply if the **Search** option is selected.
- **Tags -** Here is where you enter your tags you want to search by. Note that existing tags will not appear as you type, and they _are_ case sensitive.
> **Note:** When multiple tags and strings appear, the dashboard list displays those matching _all_ conditions.
@ -35,7 +35,7 @@ Choose how Grafana displays your data.
Show a calculated value based on all rows.
- **Calculation -** Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types]({{< relref "../../calculation-types/" >}}).
- **Calculation -** Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types][].
- **Fields -** Select the fields display in the panel.
#### All values
@ -87,3 +87,8 @@ Adjust the sizes of the gauge text.
- **Title -** Enter a numeric value for the gauge title size.
- **Value -** Enter a numeric value for the gauge value size.
[Basemap layer types]({{< relref "#types-1" >}}) can also be added as layers. You can specify an opacity.
[Basemap layer types](#types-1) can also be added as layers. You can specify an opacity.
{{% /admonition %}}
### Layer Controls
@ -155,20 +155,20 @@ are available each with specific configuration options to style the base map.
There are four basemap layer types to choose from in the Geomap visualization.
- [Open Street Map]({{< relref "#open-street-map-layer" >}}) adds a map from a collaborative free geographic world database.
- [CARTO]({{< relref "#carto-layer" >}}) adds a layer from CARTO Raster basemaps.
- [ArcGIS]({{< relref "#arcgis-layer" >}}) adds a layer from an ESRI ArcGIS MapServer.
- [XYZ]({{< relref "#xyz-tile-layer" >}}) adds a map from a generic tile layer.
- [Open Street Map](#open-street-map-layer) adds a map from a collaborative free geographic world database.
- [CARTO](#carto-layer) adds a layer from CARTO Raster basemaps.
- [ArcGIS](#arcgis-layer) adds a layer from an ESRI ArcGIS MapServer.
- [XYZ](#xyz-tile-layer) adds a map from a generic tile layer.
### Default
The default base layer uses the [CARTO]({{< relref "#carto-layer" >}}) map. You can define custom default base layers in the `.ini` configuration file.
The default base layer uses the [CARTO](#carto-layer) map. You can define custom default base layers in the `.ini` configuration file.
#### Configure the default base layer with provisioning
You can configure the default base map using config files with Grafana’s provisioning system. For more information on all the settings, refer to the [provisioning docs page]({{< relref "../../../administration/provisioning/" >}}).
You can configure the default base map using config files with Grafana’s provisioning system. For more information on all the settings, refer to the [provisioning docs page][].
Use the JSON configuration option `default_baselayer_config` to define the default base map. There are currently four base map options to choose from: `carto`, `esri-xyz`, `osm-standard`, `xyz`. Here are some provisioning examples for each base map option.
@ -367,7 +367,7 @@ The Photos layer renders a photo at each data point.
The Network layer is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{% /admonition %}}
The Network layer renders a network graph. This layer supports the same [data format supported by the node graph visualization]({{< relref "../node-graph/#data-api" >}}) with the addition of [geospatial data]({{< relref "#location">}}) included in the nodes data. The geospatial data is used to locate and render the nodes on the map.
The Network layer renders a network graph. This layer supports the same [data format supported by the node graph visualization][] with the addition of [geospatial data]({{< relref "#location">}}) included in the nodes data. The geospatial data is used to locate and render the nodes on the map.
[data format supported by the node graph visualization]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/visualizations/node-graph#data-api"
[data format supported by the node graph visualization]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/visualizations/node-graph#data-api"
The Heatmap panel visualization allows you to view histograms over time. For more information about histograms, refer to [Introduction to histograms and heatmaps]({{< relref "../../../fundamentals/intro-histograms/" >}}).
The Heatmap panel visualization allows you to view histograms over time. For more information about histograms, refer to [Introduction to histograms and heatmaps][].
@ -120,3 +120,8 @@ Choose whether you want to display the heatmap legend on the visualization.
### Exemplars
Set the color used to show exemplar data.
{{% docs/reference %}}
[Introduction to histograms and heatmaps]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/fundamentals/intro-histograms"
[Introduction to histograms and heatmaps]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/fundamentals/intro-histograms"
Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard [color scheme]({{< relref "../../configure-standard-options/#color-scheme" >}}) field option.
Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard [color scheme][] field option.
Gradient display is influenced by the **Fill opacity** setting.
@ -77,4 +77,12 @@ Gradient color is generated based on the hue of the line color.
### Legend calculations
Choose a [standard calculations]({{< relref "../../calculation-types/" >}}) to show in the legend. You can select more than one.
Choose a [standard calculations][] to show in the legend. You can select more than one.
@ -31,7 +31,7 @@ To limit the number of lines rendered, you can use the **Max data points** setti
## Log level
For logs where a **level** label is specified, we use the value of the label to determine the log level and update color accordingly. If the log doesn't have a level label specified, we try to find out if its content matches any of the supported expressions (see below for more information). The log level is always determined by the first match. In case Grafana is not able to determine a log level, it will be visualized with **unknown** log level. See [supported log levels and mappings of log level abbreviation and expressions]({{< relref "../../../explore/logs-integration/#log-level" >}}).
For logs where a **level** label is specified, we use the value of the label to determine the log level and update color accordingly. If the log doesn't have a level label specified, we try to find out if its content matches any of the supported expressions (see below for more information). The log level is always determined by the first match. In case Grafana is not able to determine a log level, it will be visualized with **unknown** log level. See [supported log levels and mappings of log level abbreviation and expressions][].
## Log details
@ -52,3 +52,8 @@ Use these settings to refine your visualization:
- **Prettify JSON -** Set this to `true` to pretty print all JSON logs. This setting does not affect logs in any format other than JSON.
- **Enable log details -** Toggle option to see the log details view for each log row. The default setting is true.
- **Order -** Display results in descending or ascending time order. The default is **Descending**, showing the newest logs first. Set to **Ascending** to show the oldest log lines first.
{{% docs/reference %}}
[supported log levels and mappings of log level abbreviation and expressions]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/explore/logs-integration#log-level"
[supported log levels and mappings of log level abbreviation and expressions]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/explore/logs-integration#log-level"
@ -33,7 +33,7 @@ Choose how much information to show.
### Calculation
Select a calculation to reduce each series when Calculate has been selected. For information about available calculations, refer to [Calculation types]({{< relref "../../calculation-types/" >}}).
Select a calculation to reduce each series when Calculate has been selected. For information about available calculations, refer to [Calculation types][].
### Limit
@ -89,3 +89,8 @@ Select values to display in the legend. You can select more than one.
- **Value:** The raw numerical value.
For more information about the legend, refer to [Configure a legend](../configure-legend/).
@ -56,7 +56,7 @@ Display a single value per column or series, or show values for each row.
Display a calculated value based on all rows.
- **Calculation -** Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types]({{< relref "../../calculation-types/" >}}).
- **Calculation -** Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types][].
- **Fields -** Select the fields display in the panel.
#### All values
@ -117,3 +117,8 @@ Adjust the sizes of the gauge text.
- **Title -** Enter a numeric value for the gauge title size.
- **Value -** Enter a numeric value for the gauge value size.
@ -57,7 +57,7 @@ Controls the opacity of state regions.
## Value mappings
To assign colors to boolean or string values, you can use [Value mappings]({{< relref "../../configure-value-mappings/" >}}).
To assign colors to boolean or string values, you can use [Value mappings][].
{{<figuresrc="/static/img/docs/v8/value_mappings_side_editor.png"max-width="300px"caption="Value mappings side editor">}}
@ -69,6 +69,14 @@ The panel can be used with time series data as well. In this case, the threshold
## Legend options
When the legend option is enabled it can show either the value mappings or the threshold brackets. To show the value mappings in the legend, it's important that the `Color scheme` as referenced in [Color scheme]({{< relref "../../configure-standard-options/#color-scheme" >}}) is set to `Single color` or `Classic palette`. To see the threshold brackets in the legend set the `Color scheme` to `From thresholds`.
When the legend option is enabled it can show either the value mappings or the threshold brackets. To show the value mappings in the legend, it's important that the `Color scheme` as referenced in [Color scheme][] is set to `Single color` or `Classic palette`. To see the threshold brackets in the legend set the `Color scheme` to `From thresholds`.
@ -49,7 +49,7 @@ Controls the opacity of state regions.
## Value mappings
To assign colors to boolean or string values, use the [Value mappings]({{< relref "../../configure-value-mappings/" >}}).
To assign colors to boolean or string values, use the [Value mappings][].
{{<figuresrc="/static/img/docs/v8/value_mappings_side_editor.png"max-width="300px"caption="Value mappings side editor">}}
@ -62,6 +62,14 @@ use gradient color schemes to color values.
## Legend options
When the legend option is enabled it can show either the value mappings or the threshold brackets. To show the value mappings in the legend, it's important that the `Color scheme` as referenced in [Color scheme]({{< relref "../../configure-standard-options/#color-scheme" >}}) is set to `Single color` or `Classic palette`. To see the threshold brackets in the legend set the `Color scheme` to `From thresholds`.
When the legend option is enabled it can show either the value mappings or the threshold brackets. To show the value mappings in the legend, it's important that the `Color scheme` as referenced in [Color scheme][] is set to `Single color` or `Classic palette`. To see the threshold brackets in the legend set the `Color scheme` to `From thresholds`.
@ -149,11 +149,10 @@ If you have a field value that is an image URL or a base64 encoded image you can
### Sparkline
{{% admonition type="note" %}}
This cell type 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 cell type 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.
Shows value rendered as a sparkline. Requires [time series to table]({{< relref "../../query-transform-data/transform-data/#time-series-to-table-transform" >}}) data transform.
Shows value rendered as a sparkline. Requires [time series to table][] data transform.
@ -167,7 +166,7 @@ Cell value inspection is only available when cell display mode is set to Auto, C
## Column filter
You can temporarily change how column data is displayed. For example, you can order values from highest to lowest or hide specific values. For more information, refer to [Filter table columns]({{< relref "#filter-table-columns" >}}).
You can temporarily change how column data is displayed. For example, you can order values from highest to lowest or hide specific values. For more information, refer to [Filter table columns](#filter-table-columns).
## Pagination
@ -206,7 +205,7 @@ To remove the filter, click the blue funnel icon and then click **Clear filter**
## Table footer
You can use the table footer to show [calculations]({{< relref "../../calculation-types/" >}}) on fields.
You can use the table footer to show [calculations][] on fields.
After you enable the table footer:
@ -218,3 +217,14 @@ The system applies the calculation to all numeric fields if you do not select a
### Count rows
If you want to show the number of rows in the dataset instead of the number of values in the selected fields, select the **Count** calculation and enable **Count rows**.
[time series to table]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/query-transform-data/transform-data#time-series-to-table-transform"
[time series to table]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/query-transform-data/transform-data#time-series-to-table-transform"
@ -33,7 +33,7 @@ This option formats the content as [markdown](https://en.wikipedia.org/wiki/Mark
### HTML
This setting renders the content as [sanitized](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/text/sanitize.ts) HTML. If you require more direct control over the output, you can set the
[disable_sanitize_html]({{< relref "../../../setup-grafana/configure-grafana/#disable_sanitize_html" >}}) flag which enables you to directly enter HTML.
[disable_sanitize_html][] flag which enables you to directly enter HTML.
### Code
@ -42,4 +42,12 @@ to the embedded text.
## Variables
[Variables]({{< relref "../../../dashboards/variables/variable-syntax/" >}}) in the content will be expanded for display.
[Variables][] in the content will be expanded for display.
@ -90,12 +90,12 @@ Use opacity to specify the series area fill color.
### Gradient mode
Gradient mode specifies the gradient fill, which is based on the series color. To change the color, use the standard color scheme field option. For more information, refer to [Color scheme]({{< relref "../../configure-standard-options/#color-scheme" >}}).
Gradient mode specifies the gradient fill, which is based on the series color. To change the color, use the standard color scheme field option. For more information, refer to [Color scheme][].
- **None:** No gradient fill. This is the default setting.
- **Opacity:** An opacity gradient where the opacity of the fill increases as Y-axis values increase.
- **Hue:** A subtle gradient that is based on the hue of the series color.
- **Scheme:** A color gradient defined by your [Color scheme]({{< relref "../../configure-standard-options/#color-scheme" >}}). This setting is used for the fill area and line. For more information about scheme, refer to [Scheme gradient mode]({{< relref "#scheme-gradient-mode" >}}).
- **Scheme:** A color gradient defined by your [Color scheme][]. This setting is used for the fill area and line. For more information about scheme, refer to [Scheme gradient mode](#scheme-gradient-mode).
Gradient appearance is influenced by the **Fill opacity** setting. The following image show, the **Fill opacity** is set to 50.
@ -126,7 +126,7 @@ This option controls how the graph interpolates the series line.
### Line style
Set the style of the line. To change the color, use the standard [color scheme]({{< relref "../../configure-standard-options/#color-scheme" >}}) field option.
Set the style of the line. To change the color, use the standard [color scheme][] field option.
@ -152,7 +152,7 @@ _Stacking_ allows Grafana to display series on top of each other. Be cautious wh
#### Stack series in groups
The stacking group option is only available as an override. For more information about creating an override, refer to [Configure field overrides]({{< relref "../../configure-overrides" >}}).
The stacking group option is only available as an override. For more information about creating an override, refer to [Configure field overrides][].
1. Edit the panel and click **Overrides**.
1. Create a field override for the **Stack series** option.
@ -187,7 +187,7 @@ Select the placement of the Y-axis.
- **Right:** Display all Y-axes on the right side.
- **Hidden:** Hide all axes.
To selectively hide axes, [Add a field override]({{< relref "../../configure-overrides#add-a-field-override" >}}) that targets specific fields.
To selectively hide axes, [Add a field override][] that targets specific fields.
### Label
@ -205,7 +205,7 @@ Set a **Soft min** or **soft max** option for better control of Y-axis limits. B
**Soft min** and **soft max** settings can prevent blips from turning into mountains when the data is mostly flat, and hard min or max derived from standard min and max field options can prevent intermittent spikes from flattening useful detail by clipping the spikes past a specific point.
To define hard limits of the Y-axis, You can set standard min/max options. For more information, refer to [Configure standard options]({{< relref "../../configure-standard-options/#max" >}}).
To define hard limits of the Y-axis, You can set standard min/max options. For more information, refer to [Configure standard options][].
@ -229,7 +229,7 @@ The transform option is only available as an override.
## Color options
By default, the graph uses the standard [Color scheme]({{< relref "../../configure-standard-options/#color-scheme" >}}) option to assign series colors. You can also use the legend to open the color picker by clicking the legend series color icon. Setting
By default, the graph uses the standard [Color scheme][] option to assign series colors. You can also use the legend to open the color picker by clicking the legend series color icon. Setting
color this way automatically creates an override rule that set's a specific color for a specific series.
### Classic palette
@ -267,3 +267,20 @@ The following image shows a line chart with the **Green-Yellow-Red (by value)**
The following image shows a bar chart with the **Green-Yellow-Red (by value)** color scheme option selected.
@ -23,8 +23,8 @@ The Traces panel visualizes traces data into a diagram that allows you to easily
For more information about traces and how to use them, refer to the following documentation:
- [Tracing in Explore]({{< relref "../../../explore/trace-integration/" >}})
- [Tempo data source]({{< relref "../../../datasources/tempo/" >}})
- [Tracing in Explore][]
- [Tempo data source][]
- [Getting started with Tempo](/docs/tempo/latest/getting-started)
{{<figuresrc="/static/img/docs/explore/trace-view-9-4.png"class="docs-image--no-shadow"max-width="900px"caption="Screenshot of the trace view">}}
@ -34,7 +34,7 @@ For more information about traces and how to use them, refer to the following do
Once you have tracing data available in your Grafana stack, you can add tracing panels to your Grafana dashboards.
Using a dashboard variable, `traceID`, lets you create a query to show specific traces for a given trace ID.
For more information about dashboard variables, refer to the [Variables documentation]({{< relref "../../../dashboards/variables" >}}).
For more information about dashboard variables, refer to the [Variables documentation][].
### Before you begin
@ -47,7 +47,7 @@ To use this procedure, you need:
To view and analyze traces data in a dashboard, you need to add the tracing panel to your dashboard and define a query using the panel editor.
The query determines the data that is displayed in the panel.
For more information on the panel editor, refer to the [Panel editor documentation]({{< relref "../../panel-editor-overview" >}}).
For more information on the panel editor, refer to the [Panel editor documentation][].
This procedure uses dashboard variables and templates to allow you to enter trace IDs which can then be visualized. You'll use a variable called `traceId` and add it as a template query.
@ -55,7 +55,7 @@ This procedure uses dashboard variables and templates to allow you to enter trac
1. Select **Add visualization** from a new dashboard or select **Add Panel** on an existing dashboard.
1. Search for and select the appropriate tracing data source.
1. In the top-right of the panel editor, select the **Visualizations** tab, search for, and select **Traces**.
1. Under the **Panel options**, enter a **Title** for your trace panel. For more information on the panel editor, refer to the [Configure panel options documentation]({{< relref "../../configure-panel-options" >}}).
1. Under the **Panel options**, enter a **Title** for your trace panel. For more information on the panel editor, refer to the [Configure panel options documentation][].
1. In the query editor, select the **TraceQL** query type tab.
1. Enter `${traceId}` in the TraceQL query field to create a dashboard variable. This variable is used as the template query.
@ -114,3 +114,20 @@ You should now see a list of matching traces in the Table visualization. While s
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-trace-link.png"caption="Selecting the trace link">}}
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-trace-link-follow.png"caption="Follow the trace link populates the trace ID and displays the traces view">}}
{{% docs/reference %}}
[Tracing in Explore]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/explore/trace-integration"
[Tracing in Explore]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/explore/trace-integration"
[Tempo data source]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/datasources/tempo"
[Tempo data source]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/datasources/tempo"
The trend panel should be used for datasets that have a sequential, numeric X that is not time. Some examples are function graphs, rpm/torque curves, supply/demand relationships, and elevation or heart rate plots along a race course (with x as distance or duration from start).
The trend panel supports all visual styles and options available in the [Time series panel]({{< relref "../time-series" >}}) with these exceptions:
The trend panel supports all visual styles and options available in the [Time series panel][] with these exceptions:
- No annotations or time regions
- No shared cursor/crosshair
@ -36,3 +36,8 @@ Use this option to select a field that contains increasing numeric values.
For example, you could represent engine power and torque versus speed where speed is plotted on the x axis and power and torque are plotted on the y axes.
{{<figuresrc="/media/docs/grafana/screenshot-grafana-10-0-trend-panel-new-colors.png"max-width="750px"caption="Trend engine power and torque curves">}}
{{% docs/reference %}}
[Time series panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/visualizations/time-series"
[Time series panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANAVERSION>/panels-visualizations/visualizations/time-series"
Jack Baldry
2 years ago
committed by