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

Consolidate Grafana visualization documentation (#112393)

Browse Source 
Co-authored-by: Jacob Valdez <jacob.valdez@grafana.com>
This commit is contained in:
Jack Baldry
2025-10-15 18:41:15 +01:00
committed by GitHub
co-authored by Jacob Valdez
parent 7bc97d5fa8
commit d8c6af2fa7
83 changed files with 462 additions and 317 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/visualizations/dashboards/_index.md
+78
View File
@@ -0,0 +1,78 @@
---
aliases:
- ../features/dashboard/dashboards/ # /docs/grafana/latest/features/dashboard/dashboards/
- ../dashboards/previews/ # /docs/grafana/latest/dashboards/previews/
- ../dashboards/ # /docs/grafana/next/dashboards/
labels:
products:
- cloud
- enterprise
- oss
title: Dashboards
weight: 70
description: Create and manage dashboards
hero:
title: Dashboards
level: 1
width: 110
height: 110
description: >-
Dashboards allow you to query, transform, visualize, and understand your data no matter where it's stored.
cards:
title_class: pt-0 lh-1
items:
- title: Build dashboards
href: ./build-dashboards/
description: Get step-by-step directions for how to create or import your first dashboard and modify dashboard settings. Learn about reusable library panels, dashboard links, annotations, and dashboard JSON.
height: 24
- title: Manage dashboards
href: ./manage-dashboards/
description: Learn about dashboard and folder management, as well as generative AI features for dashboards.
height: 24
- title: Variables
href: ./variables/
description: Add variables to metric queries and panel titles to create interactive and dynamic dashboards.
height: 24
- title: Reporting
href: ./create-reports/
description: Automatically generate and share PDF reports from your Grafana dashboards.
height: 24
- title: Sharing
href: ./share-dashboards-panels/
description: Share Grafana dashboards and panels using links, snapshots, embeds, and exports.
height: 24
- title: Shared dashboards
href: ./share-dashboards-panels/shared-dashboards/
description: Share your dashboards with anyone without requiring access to your Grafana organization.
height: 24
refs:
panels:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/panel-overview/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/panel-overview/
---
{{< docs/hero-simple key="hero" >}}
---
## Overview
{{< shared id="dashboard-overview" >}}
A Grafana dashboard is a set of one or more [panels](ref:panels), organized and arranged into one or more rows, that provide an at-a-glance view of related information. These panels are created using components that query and transform raw data from a data source into visualizations.
A data source can be an SQL database, Grafana Loki, Grafana Mimir, or an API endpoint. It can even be a basic CSV file. Data source plugins take a query you want answered, retrieve the data from the data source, and reconcile the differences between the data model of the data source and the data model of Grafana dashboards.
{{< /shared >}}
Queries allow you to reduce the entirety of your data to a specific dataset, providing a more manageable visualization. Since data sources have their own distinct query languages, Grafana dashboards provide you with a query editor to accommodate these differences.
A panel is the container that displays the visualization and provides you with various controls to manipulate it. Panel options let you customize many aspects of a visualization and the options differ based on which visualization you select. When the data format in a visualization doesn't meet your requirements, you can apply a transformation that manipulates the data returned by a query.
With 150+ data source plugins, you can unify all your data sources into a single dashboard to streamline data monitoring and troubleshooting. With Grafana, you can translate, transform, and visualize data in flexible and versatile dashboards.
## Explore
{{< card-grid key="cards" type="simple" >}}
docs/sources/visualizations/dashboards/assess-dashboard-usage/index.md
+160
View File
@@ -0,0 +1,160 @@
---
aliases:
- ../../enterprise/usage-insights/ # /docs/grafana/next/enterprise/usage-insights/
- ../../enterprise/usage-insights/dashboard-datasource-insights/ # /docs/grafana/next/enterprise/usage-insights/dashboard-datasource-insights/
- ../../enterprise/usage-insights/improved-search/ # /docs/grafana/next/enterprise/usage-insights/improved-search/
- ../../enterprise/usage-insights/presence-indicator/ # /docs/grafana/next/enterprise/usage-insights/presence-indicator/
- ../../dashboards/assess-dashboard-usage/ # /docs/grafana/next/dashboards/assess-dashboard-usage/
description: Understand how your Grafana instance is used
keywords:
- grafana
- usage-insights
- enterprise
- presence-indicator
- search
- sort
labels:
products:
- cloud
- enterprise
title: Assess dashboard usage
weight: 900
refs:
grafana-enterprise:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
configuration:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/
export-logs-of-usage-insights:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/export-logs/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/export-logs/
dashboard-sharing:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#public_dashboards
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#public_dashboards
export-logs-of-usage-insights:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/export-logs/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/export-logs/
---
# Assess dashboard usage
Usage insights enables you to have a better understanding of how your Grafana instance is used.
{{< admonition type="note" >}}
Available in [Grafana Enterprise](ref:grafana-enterprise) and [Grafana Cloud](https://grafana.com/docs/grafana-cloud/).
Grafana Cloud insights logs include additional fields with their own dashboards.
Read more in the [Grafana Cloud documentation](https://grafana.com/docs/grafana-cloud/account-management/usage-insights/).
{{< /admonition >}}
The usage insights feature collects a number of aggregated data and stores them in the database:
- Dashboard views (aggregated and per user)
- Data source errors
- Data source queries
The aggregated data provides you access to several features:
- [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](ref:export-logs-of-usage-insights).
## Dashboard and data source insights
For every dashboard and data source, you can access usage information.
### Dashboard insights
To see dashboard usage information, click the dashboard insights icon in the header.
![Dashboard insights icon](/media/docs/grafana/dashboards/screenshot-dashboard-insights-icon-11.2.png)
Dashboard insights show the following information:
- **Stats:** The number of daily queries and errors for the past 30 days.
- **Users & activity:** The daily view count for the last 30 days; last activities on the dashboard and recent users (with a limit of 20).
{{< figure src="/static/img/docs/enterprise/dashboard_insights_stats.png" max-width="400px" class="docs-image--no-shadow" alt="Stats tab" >}}{{< figure src="/static/img/docs/enterprise/dashboard_insights_users.png" max-width="400px" class="docs-image--no-shadow" alt="Users and activity tab" >}}
If [dashboard sharing](ref:dashboard-sharing) is enabled, you'll also see a **Shared dashboards** tab in your analytics.
### Data source insights
Data source insights provides information about how a data source has been used in the past 30 days, such as:
- Queries per day
- Errors per day
- Query load time per day (averaged in ms)
To find data source insights:
1. Click **Connections** in the main navigation.
1. Under Your connections, click **Data sources**.
1. Click a data source.
1. Click the **Insights** tab.
{{< figure src="/media/docs/grafana/dashboards/screenshot-data-source-insights-9.5.png" max-width="650px" class="docs-image--no-shadow" alt="Insights tab for a data source" >}}
## Presence indicator
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](#dashboard-and-data-source-insights), which contains more details about recent user activity.
{{< figure src="/static/img/docs/enterprise/presence_indicators.png" max-width="400px" class="docs-image--no-shadow" alt="Presence indicator icons" >}}
To change _recent_ to something other than the past 10 minutes, edit the [configuration](ref:configuration) file:
```ini
[analytics.views]
# Set age for recent active users to 10 minutes
recent_users_age = 10m
```
To disable the presence indicator, edit the [configuration](ref:configuration) file as follows:
```ini
[analytics.views]
# Disables the presence indicator
recent_users_age = 0
```
The dashboard won't show any avatars and thus no recent user activity.
## Sort dashboards by using insights data
In the search view, you can use insights data to help you find most-used, broken, and unused dashboards.
You can sort the dashboards by:
- Errors total
- Errors 30 days (most and least)
- Views total
- Views 30 days (most and least)
{{< figure src="/media/docs/grafana/dashboards/screenshot-dashboard-sort-9.5.png" max-width="650px" class="docs-image--no-shadow" alt="Open list of dashboard sort options" >}}
## Visualize usage insights data
If you set up your installation to [export logs of usage insights](ref:export-logs-of-usage-insights), there are 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/sources/visualizations/dashboards/build-dashboards/_index.md
+32
View File
@@ -0,0 +1,32 @@
---
keywords:
- grafana
- dashboard
- dashboard folders
- create
- build
- design
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Build dashboards
title: Build dashboards
description: Build dashboards including managing settings, links, and version history
weight: 200
refs:
variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
aliases:
- ../../dashboards/build-dashboards/ # /docs/grafana/next/dashboards/build-dashboards/
---
# Build dashboards
This section includes the following topics:
{{< section >}}
docs/sources/visualizations/dashboards/build-dashboards/annotate-visualizations/index.md
+214
View File
@@ -0,0 +1,214 @@
---
aliases:
- ../../../dashboards/annotations/ # /docs/grafana/next/annotations/
- ../../../dashboards/build-dashboards/annotate-visualizations/ # /docs/grafana/next/dashboards/build-dashboards/annotate-visualizations/
- ../../../panels/visualizations/annotations/ # /docs/grafana/next/panels/visualizations/annotations/
- ../../../reference/annotations/ # /docs/grafana/latest/reference/annotations/
keywords:
- grafana
- annotations
- documentation
- guide
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Annotate visualizations
title: Annotate visualizations
weight: 600
description: Annotate dashboard visualizations to mark points with rich events
refs:
data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/
annotations-api:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/developers/http_api/annotations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/annotations/
---
# Annotate visualizations
Annotations provide a way to mark points on a visualization with rich events. They are visualized as vertical lines and icons on all graph panels. When you hover over an annotation, you can get event description and event tags. The text field can include links to other systems with more detail.
{{< figure src="/static/img/docs/v46/annotations.png" max-width="800px" alt="Annotated visualization with annotation context menu open" >}}
You can annotate visualizations in three ways:
- Directly in the panel, using the [built-in annotations query](#built-in-query)
- Using the HTTP API
- Configuring annotation queries in the dashboard settings
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](ref:annotations-api).
Annotations are supported for the following visualization types:
- Time series
- State timeline
- Candlestick
## Create annotations in panels
Grafana comes with the ability to add annotation events directly from a panel using the [built-in annotation query](#built-in-query) that exists on all dashboards. Annotations that you create this way are stored in Grafana.
To add annotations directly in the panel:
- The dashboard must already be saved.
- The built-in query must be enabled. Learn more in [Built-in query](#built-in-query).
Watch the following video for a quick tutorial on creating annotations:
{{< youtube id="N5iOlyYyK6Q" >}}
### Add an annotation
To add an annotation, complete the following steps:
1. If you've just saved a dashboard, refresh the page.
1. Click **Edit** in the top-right corner of the dashboard.
1. Click the panel to which you're adding the annotation.
A context menu appears.
1. In the context menu, click **Add annotation**.
![Add annotation context menu](/static/img/docs/time-series-panel/time-series-annotations-context-menu.png)
1. Add an annotation description and tags (optional).
1. Click **Save dashboard**.
1. Click **Exit edit**.
Alternatively, to add an annotation, press Ctrl/Cmd and click the panel, and the **Add annotation** context menu appears.
### Add a region annotation
1. If you've just saved a dashboard, refresh the page.
1. Click **Edit** in the top-right corner of the dashboard.
1. Press Ctrl/Cmd and click and drag on the panel.
![Add annotation popover](/static/img/docs/time-series-panel/time-series-annotations-add-region-annotation.gif)
1. Add an annotation description and tags (optional).
1. Click **Save dashboard**.
1. Click **Exit edit**.
### Edit an annotation
1. Click **Edit** in the top-right corner of the dashboard.
1. Hover over the annotation indicator on the panel.
1. Click the pencil icon in the annotation tooltip.
1. Modify the description and tags.
1. Click **Save dashboard**.
1. Click **Exit edit**.
### Delete an annotation
1. Click **Edit** in the top-right corner of the dashboard.
1. Hover over the annotation indicator on the panel.
1. Click the trash icon in the annotation tooltip.
1. Click **Save dashboard**.
1. Click **Exit edit**.
## Fetch annotations through dashboard settings
In the dashboard settings, under **Annotations**, you can add new queries to fetch annotations using any data source, including the built-in data annotation data source. Annotation queries return events that can be visualized as event markers in graphs across the dashboard.
Check out the video below for a quick tutorial.
{{< youtube id="2istdJpPj2Y" >}}
### Add new annotation queries
To add a new annotation query to a dashboard, follow these steps:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
1. On the **Settings** page, go to the **Annotations** tab.
1. Click **Add annotation query**.
If you've added a query before, the **+ New query** button is displayed.
1. Enter a name for the annotation query.
This name is given to the toggle (checkbox) that allows you to enable/disable showing annotation events from this query.
1. Select the data source for the annotations.
You can also click **Open advanced data source picker** to see more options, including adding a data source (Admins only).
1. If you don't want to use the annotation query right away, clear the **Enabled** checkbox.
1. If you don't want the annotation query toggle to be displayed in the dashboard, select the **Hidden** checkbox.
1. Select a color for the event markers.
1. In the **Show in** drop-down, choose one of the following options:
- **All panels** - The annotations are displayed on all panels that support annotations.
- **Selected panels** - The annotations are displayed on all the panels you select.
- **All panels except** - The annotations are displayed on all panels except the ones you select.
{{< figure src="/media/docs/grafana/dashboards/screenshot-annotation-filtering-10-v2.png" max-width="600px" caption="Annotation filtering" >}}
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](ref:data-source) topic.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Built-in query
After you add an annotation, they are still visible. This is due to the built-in annotation query that exists on all dashboards. This annotation query fetches all annotation events that originate from the current dashboard, which are stored in Grafana, and show them on the panel where they were created. This includes alert state history annotations.
By default, the built-in annotation query uses the `-- Grafana --` special data source, and manual annotations are only supported using this data source. You can use another data source in the built-in annotation query, but you'll only be able to create automated annotations using the query editor for that data source.
To add annotations directly to the dashboard, this query must be enabled.
To confirm if the built-in query is enabled, take the following steps:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
1. On the **Settings** page, go to the **Annotations** tab.
1. Find the **Annotations & Alerts (Built-in)** query.
If it says **Disabled** before the name of the query, then you'll need to click the query name to open it and update the setting.
You can stop annotations from being fetched and drawn by taking the following steps:
1. Click the dashboard settings (gear) icon in the dashboard header to open the settings menu.
1. Click **Annotations**.
1. Find and click the **Annotations & Alerts (Built-in)** query to open it.
1. Click the **Enabled** toggle to turn it off.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
When you copy a dashboard using the **Save As** feature it gets a new dashboard id, so annotations created on the source dashboard is no longer be visible on the copy. You can still show them if you add a new **Annotation Query** and filter by tags. However, this only works if the annotations on the source dashboard had tags to filter by.
Following are some query options specific to the built-in annotation query.
### Filter queries by tag
You can create new queries to fetch annotations from the built-in annotation query using the `-- Grafana --` data source by setting _Filter by_ to `Tags`.
Grafana also supports typeahead of existing tags, provide at least one tag.
For example, create an annotation query name `outages` and specify a tag `outage`. This query shows all annotations (from any dashboard or via API) with the `outage` tag. If multiple tags are defined in an annotation query, then Grafana only shows annotations matching all the tags. To modify the behavior, enable `Match any`, and Grafana shows annotations that contain any one of the tags you provided.
{{< figure src="/media/docs/grafana/dashboards/screenshot-annotations-typeahead-support-10.0.png" max-width="600px" alt="Annotation query options" >}}
You can also use template variables in the tag query. This means if you have a dashboard showing stats for different services and a template variable that dictates which services to show, you can use the same template variable in your annotation query to only show annotations for those services.
{{< figure src="/media/docs/grafana/dashboards/screenshot-annotation-tag-filter-variable-10.0.png" max-width="600px" alt="Annotation query options with a template variable query tag" >}}
### Add time regions
When adding or editing an annotation, you can define a repeating time region by setting **Query type** to **Time regions**. Then, define the **From** and **To** sections with the preferred days of the week and time. You also have the option to change the timezone, which is set to the dashboard's timezone, by default.
{{< figure src="/media/docs/grafana/dashboards/screenshot-annotation-timeregions-10-v2.png" max-width="600px" alt="Time regions options set to business hours" >}}
The above configuration produces the following result in the Time series panel:
{{< figure src="/media/docs/grafana/screenshot-grafana-10-0-timeseries-time-regions.png" max-width="600px" alt="Time series visualization with time regions business hours" >}}
Toggle the **Advanced** switch and use [Cron syntax](https://en.wikipedia.org/wiki/Cron) to set more granular time region controls. The following example sets a time region of 9:00 AM, Monday to Friday:
{{< figure src="/media/docs/grafana/dashboards/screenshot-annotations-cron-option-v11.6.png" max-width="600px" alt="Time region query with cron syntax" >}}
docs/sources/visualizations/dashboards/build-dashboards/best-practices/index.md
+275
View File
@@ -0,0 +1,275 @@
---
aliases:
- ../../../best-practices/ # /docs/grafana/next/best-practices/
- ../../../best-practices/best-practices-for-creating-dashboards/ # /docs/grafana/next/best-practices/best-practices-for-creating-dashboards/
- ../../../best-practices/best-practices-for-managing-dashboards/ # /docs/grafana/next/best-practices/best-practices-for-managing-dashboards/
- ../../../best-practices/common-observability-strategies/ # /docs/grafana/next/best-practices/common-observability-strategies/
- ../../../best-practices/dashboard-management-maturity-levels/ # /docs/grafana/next/best-practices/dashboard-management-maturity-levels/
- ../../../getting-started/strategies/ # /docs/grafana/next/getting-started/strategies/
- ../../../dashboards/build-dashboards/best-practices/ # /docs/grafana/next/dashboards/build-dashboards/best-practices/
description: Learn best practices for building and maintaining Grafana dashboards
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Best practices
title: Grafana dashboard best practices
weight: 800
refs:
text-panel:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/text/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/text/
text-panel-visualization:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/text/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/text/
data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
url-parameters:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-data-links/#data-link-variables
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-data-links/#data-link-variables
variable-examples:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/#examples-of-templates-and-variables
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/#examples-of-templates-and-variables
dashboard-list-panel:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/dashboard-list/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/dashboard-list/
manage-dashboard-links:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/
usage-insights:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/assess-dashboard-usage/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/assess-dashboard-usage/
templates-and-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
thresholds:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-thresholds/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-thresholds/
---
# Grafana dashboard best practices
This section provides information about best practices for intermediate Grafana administrators and users about how to build and maintain Grafana dashboards.
For more information about the different kinds of dashboards you can create, refer to [Grafana dashboards: A complete guide to all the different types you can build](https://grafana.com/blog/2022/06/06/grafana-dashboards-a-complete-guide-to-all-the-different-types-you-can-build/?pg=webinar-getting-started-with-grafana-dashboard-design-amer&plcmt=related-content-1).
## Common observability strategies
When you have a lot to monitor, like a server farm, you need a strategy to decide what is important enough to monitor. This page describes several common methods for choosing what to monitor.
A logical strategy allows you to make uniform dashboards and scale your observability platform more easily.
### Guidelines for usage
- The USE method tells you how happy your machines are, the RED method tells you how happy your users are.
- USE reports on causes of issues.
- RED reports on user experience and is more likely to report symptoms of problems.
- The best practice of alerting is to alert on symptoms rather than causes, so alerting should be done on RED dashboards.
### USE method
USE stands for:
- **Utilization -** Percent time the resource is busy, such as node CPU usage
- **Saturation -** Amount of work a resource has to do, often queue length or node load
- **Errors -** Count of error events
This method is best for hardware resources in infrastructure, such as CPU, memory, and network devices. For more information, refer to [The USE Method](http://www.brendangregg.com/usemethod.html).
### RED method
RED stands for:
- **Rate -** Requests per second
- **Errors -** Number of requests that are failing
- **Duration -** Amount of time these requests take, distribution of latency measurements
This method is most applicable to services, especially a microservices environment. For each of your services, instrument the code to expose these metrics for each component. RED dashboards are good for alerting and SLAs. A well-designed RED dashboard is a proxy for user experience.
For more information, refer to Tom Wilkie's blog post [The RED method: How to instrument your services](https://grafana.com/blog/2018/08/02/the-red-method-how-to-instrument-your-services).
### The Four Golden Signals
According to the [Google SRE handbook](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals), if you can only measure four metrics of your user-facing system, focus on these four.
This method is similar to the RED method, but it includes saturation.
- **Latency -** Time taken to serve a request
- **Traffic -** How much demand is placed on your system
- **Errors -** Rate of requests that are failing
- **Saturation -** How "full" your system is
{{< docs/play title="The Four Golden Signals" url="https://play.grafana.org/d/000000109/" >}}
## Dashboard management maturity model
_Dashboard management maturity_ refers to how well-designed and efficient your dashboard ecosystem is. It's recommended that you periodically review your dashboard setup to gauge where you are and how you can improve.
Broadly speaking, dashboard maturity can be defined as low, medium, or high.
Much of the content for this topic was taken from the KubeCon 2019 talk [Fool-Proof Kubernetes Dashboards for Sleep-Deprived Oncalls](https://www.youtube.com/watch?v=YE2aQFiMGfY).
### Low - default state
At this stage, you have no coherent dashboard management strategy. Almost everyone starts here.
How can you tell you are here?
- Everyone can modify your dashboards.
- Lots of copied dashboards, little to no dashboard reuse.
- One-off dashboards that hang around forever.
- No version control (dashboard JSON in version control).
- Lots of browsing for dashboards, searching for the right dashboard. This means lots of wasted time trying to find the dashboard you need.
- Not having any alerts to direct you to the right dashboard.
### Medium - methodical dashboards
At this stage, you are starting to manage your dashboard use with methodical dashboards. You might have laid out a strategy, but there are some things you could improve.
How can you tell you are here?
- 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](ref:variable-examples) if you want some ideas.
- Methodical dashboards according to an [observability strategy](#common-observability-strategies).
- Hierarchical dashboards with drill-downs to the next level.
{{< figure class="float-right" max-width="100%" src="/static/img/docs/best-practices/drill-down-example.png" caption="Example of using drill-down" >}}
- Dashboard design reflects service hierarchies. The example shown below uses the RED method (request and error rate on the left, latency duration on the right) with one row per service. The row order reflects the data flow.
{{< figure class="float-right" max-width="100%" src="/static/img/docs/best-practices/service-hierarchy-example.png" caption="Example of a service hierarchy" >}}
- 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](ref: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](ref:manage-dashboard-links).
- Version-controlled dashboard JSON.
### High - optimized use
At this stage, you have optimized your dashboard management use with a consistent and thoughtful strategy. It requires maintenance, but the results are worth it.
- 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](ref:usage-insights).
- Consistency by design.
- Use scripting libraries to generate dashboards, ensure consistency in pattern and style.
- grafonnet (Jsonnet)
- grafanalib (Python)
- No editing in the browser. Dashboard viewers change views with variables.
- Browsing for dashboards is the exception, not the rule.
- Perform experimentation and testing in a separate Grafana instance dedicated to that purpose, not your production instance. When a dashboard in the test environment is proven useful, then add that dashboard to your main Grafana instance.
## Best practices for creating dashboards
This page outlines some best practices to follow when creating Grafana dashboards.
### Before you begin
Here are some principles to consider before you create a dashboard.
#### A dashboard should tell a story or answer a question
What story are you trying to tell with your dashboard? Try to create a logical progression of data, such as large to small or general to specific. What is the goal for this dashboard? (Hint: If the dashboard doesn't have a goal, then ask yourself if you really need the dashboard.)
Keep your graphs simple and focused on answering the question that you are asking. For example, if your question is "which servers are in trouble?", then maybe you don't need to show all the server data. Just show data for the ones in trouble.
#### Dashboards should reduce cognitive load, not add to it
<!-- vale Grafana.GoogleWill = NO -->
_Cognitive load_ is basically how hard you need to think about something in order to figure it out. Make your dashboard easy to interpret. Other users and future you (when you're trying to figure out what broke at 2 AM) will appreciate it.
Ask yourself:
- Can I tell what exactly each graph represents? Is it obvious, or do I have to think about it?
- If I show this to someone else, how long will it take them to figure it out? Will they get lost?
<!-- vale Grafana.GoogleWill = YES -->
#### Have a monitoring strategy
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](#common-observability-strategies) and [Dashboard management maturity levels](#dashboard-management-maturity-model) for more information.
#### Write it down
Once you have a strategy or design guidelines, write them down to help maintain consistency over time. Check out this [Wikimedia runbook example](https://wikitech.wikimedia.org/wiki/Performance/Runbook/Grafana_best_practices).
### Best practices to follow
- When creating a new dashboard, make sure it has a meaningful name.
- 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](#best-practices-for-managing-dashboards) for more information.
- Grafana retrieves data from a data source. A basic understanding of [data sources](ref: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](ref: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 appears 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](ref:templates-and-variables).
- Be careful with stacking graph data. The visualizations can be misleading, and hide important data. It's recommended that you turn it off in most cases.
## Best practices for managing dashboards
This page outlines some best practices to follow when managing Grafana dashboards.
### Before you begin
Here are some principles to consider before you start managing dashboards.
#### Strategic observability
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](#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
- Avoid dashboard sprawl, meaning the uncontrolled growth of dashboards. Dashboard sprawl negatively affects time to find the right dashboard. Duplicating dashboards and changing "one thing" (worse: keeping original tags) is the easiest kind of sprawl.
- Periodically review the dashboards and remove unnecessary ones.
- 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](ref: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](ref:manage-dashboard-links).
- Add a [Dashboard list panel](ref:dashboard-list-panel). You can then customize what you see by doing tag or folder searches.
- Add a [Text panel](ref:text-panel) and use markdown to customize the display.
docs/sources/visualizations/dashboards/build-dashboards/create-dashboard-url-variables/index.md
+116
View File
@@ -0,0 +1,116 @@
---
aliases:
- ../../../variables/url-variables/ # /docs/grafana/next/variables/url-variables/
- ../../../variables/variable-types/url-variables/ # /docs/grafana/next/variables/variable-types/url-variables/
- ../../../dashboards/build-dashboards/create-dashboard-url-variables/ # /docs/grafana/next/dashboards/build-dashboards/create-dashboard-url-variables/
keywords:
- grafana
- url variables
- documentation
- variables
- dashboards
labels:
products:
- cloud
- enterprise
- oss
title: Dashboard URL variables
description: Use variables in dashboard URLs to add more context to your links
weight: 250
refs:
ad-hoc-filters:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#add-ad-hoc-filters
manage-dashboard-links:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/manage-dashboard-links/
variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
---
# Dashboard URL variables
Dashboard URL [variables](ref:variables) allow you to provide more context when you share a dashboard URL.
For example, you could share a basic URL to your dashboard that looks like this:
```
https://${your-domain}/path/to/your/dashboard
```
This allows someone to navigate to the dashboard, but doesn't provide any helpful context that might be available.
Instead, you can add dashboard variables, passed as query parameters in the dashboard URL, to provide a URL like this:
```
https://${your-domain}/path/to/your/dashboard?var-example=value
```
This allows you to provide added context to the dashboard when someone navigates to it.
## Variables as query parameters
Grafana interprets query string parameters prefixed with `var-` as variables in the given dashboard.
For example:
```
https://${your-domain}/path/to/your/dashboard?var-example=value
```
In this URL, the query parameter `var-example=value` represents the dashboard variable `example` with a value of `value`.
### Multiple values for a variable
To pass multiple values, repeat the variable parameter once for each value:
```
https://${your-domain}/path/to/your/dashboard?var-example=value1&var-example=value2
```
Grafana interprets `var-example=value1&var-example=value2` as the dashboard variable `example` with two values: `value1` and `value2`.
### Example
[This dashboard in Grafana Play](https://play.grafana.org/d/000000074/alerting?var-app=backend&var-server=backend_01&var-server=backend_03&var-interval=1h) passes the variable `server` with multiple values, and the variables `app` and `interval` with a single value each.
## Ad hoc filters
Ad hoc filters apply key/value filters to all metric queries that use the specified data source. For more information, refer to [Add ad hoc filters](ref:ad-hoc-filters).
To pass an ad hoc filter as a query parameter, use the variable syntax to pass the ad hoc filter variable. Then provide the key, operator, and value as a pipe-separated list.
For example:
```
https://${your-domain}/path/to/your/dashboard?var-adhoc=example_key|=|example_value
```
In this URL, the query parameter `var-adhoc=key|=|value` applies the ad hoc filter configured as the `adhoc` dashboard variable using the `example_key` key, the `=` operator, and the `example_value` value.
{{< admonition type="note" >}}
When sharing URLs with ad hoc filters, remember to encode the URL. In the preceding example, replace the pipes (`|`) with `%7C` and the equality operator (`=`) with `%3D`.
{{< /admonition >}}
### Example
[This dashboard in Grafana Play](https://play.grafana.org/d/p-k6QtkGz/template-redux?var-interval=$__auto&orgId=1&from=now-5m&to=now&timezone=utc&var-query=$__all&var-query2=$__all&var-query3=$__all&var-Filters=job%7C%3D%7Cmetrictank%2Ftsdb-gw&var-textbox=foo&var-custom=lisa&var-datasource=grafanacloud-demoinfra-prom) passes the ad hoc filter variable `Filters` with the filter value `job = metrictank/tsdb-gw`.
## Time range control using the URL
{{< docs/shared lookup="dashboards/time-range-URLs.md" source="grafana" version="<GRAFANA_VERSION>" >}}
## Variables in dashboard links
When you create dashboard links the dashboard settings, you can have current dashboard variables included in the link by selecting that option:
{{< figure src="/media/docs/grafana/dashboards/screenshot-dashboard-link-variables-11.1.png" max-width="500px" alt="Dashboard link page with variables option selected" >}}
For steps to add variables to dashboard links, refer to [Manage dashboard links](ref:manage-dashboard-links).
docs/sources/visualizations/dashboards/build-dashboards/create-dashboard/index.md
+247
View File
@@ -0,0 +1,247 @@
---
aliases:
- ../../../dashboards/build-dashboards/add-organize-panels/ # /docs/grafana/next/dashboards/build-dashboards/add-organize-panels/
- ../../../dashboards/build-dashboards/create-dashboard/ # /docs/grafana/next/dashboards/build-dashboards/create-dashboard/
keywords:
- panel
- dashboard
- create
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Create a dashboard
title: Create a dashboard
description: Create and edit a dashboard
weight: 1
refs:
built-in-special-data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#special-data-sources
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/#special-data-sources
visualization-specific-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/
configure-standard-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/
configure-value-mappings:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-value-mappings/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-value-mappings/
generative-ai-features:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/manage-dashboards/#set-up-generative-ai-features-for-dashboards
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/manage-dashboards/#set-up-generative-ai-features-for-dashboards
configure-thresholds:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-thresholds/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-thresholds/
data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/
add-a-data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#add-a-data-source
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#add-a-data-source
about-users-and-permissions:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
visualizations-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
configure-repeating-panels:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-panel-options/#configure-repeating-panels
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-panel-options/#configure-repeating-panels
override-field-values:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-overrides/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-overrides/
saved-queries:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/#saved-queries
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/#saved-queries
save-query:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/#save-a-query
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/#save-a-query
---
## Create a dashboard
Dashboards and panels allow you to show your data in visual form. Each panel needs at least one query to display a visualization.
**Before you begin:**
- Ensure that you have the proper permissions. For more information about permissions, refer to [About users and permissions](ref: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](ref:add-a-data-source) if you need instructions.
**To create a dashboard**:
{{< shared id="create-dashboard" >}}
1. Click **Dashboards** in the main menu.
1. Click **New** and select **New Dashboard**.
1. On the empty dashboard, click **+ Add visualization**.
![Empty dashboard state](/media/docs/grafana/dashboards/empty-dashboard-10.2.png)
{{< /shared >}}
1. In the dialog box that opens, do one of the following:
- Select one of your existing data sources.
- Select one of the Grafana [built-in special data sources](ref:built-in-special-data-sources).
- Click **Configure a new data source** to set up a new one (Admins only).
{{< figure class="float-right" src="/media/docs/grafana/dashboards/screenshot-data-source-selector-10.0.png" max-width="800px" alt="Select data source modal" >}}
The **Edit panel** view opens with your data source selected.
You can change the panel data source later using the drop-down in the **Queries** tab of the panel editor if needed.
For more information about data sources, refer to [Data sources](ref:data-sources) for specific guidelines.
1. To add a query, do one of the following:
- Write or construct a query in the query language of your data source.
- Click **+ Add from saved queries** to add a previously saved query.
- If you've already written a query, you can click the **Replace with saved query** icon to use a previously saved query instead.
1. (Optional) To [save the query](ref:save-query) for reuse, click the **Save query** icon.
{{< admonition type="note" >}}
[Saved queries](ref:saved-queries) is in [public preview](https://grafana.com/docs/release-life-cycle/) in Grafana Enterprise and Cloud only.
{{< /admonition >}}
1. Click **Refresh** to query the data source.
1. In the visualization list, select a visualization type.
![Visualization selector](/media/docs/grafana/dashboards/screenshot-select-visualization-11-2.png)
Grafana displays a preview of your query results with the visualization applied.
For more information about individual visualizations, refer to [Visualizations options](ref:visualizations-options).
1. Under **Panel options**, enter a title and description for your panel or have Grafana create them using [generative AI features](ref:generative-ai-features).
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](ref:configure-value-mappings)
- [Visualization-specific options](ref:visualization-specific-options)
- [Override field values](ref:override-field-values)
- [Configure thresholds](ref:configure-thresholds)
- [Configure standard options](ref:configure-standard-options)
1. When you've finished editing your panel, click **Save dashboard**.
Alternatively, click **Back to dashboard** if you want to see your changes applied to the dashboard first. Then click **Save dashboard** when you're ready.
1. Enter a title and description for your dashboard or have Grafana create them using [generative AI features](ref:generative-ai-features).
1. Select a folder, if applicable.
1. Click **Save**.
1. To add more panels to the dashboard, click **Back to dashboard**.
Then click **Add** in the dashboard header and select **Visualization** in the drop-down.
![Add drop-down](/media/docs/grafana/dashboards/screenshot-add-dropdown-11.2.png)
When you add additional panels to the dashboard, you're taken straight to the **Edit panel** view.
1. When you've saved all the changes you want to make to the dashboard, click **Exit edit**.
Now, when you want to make more changes to the saved dashboard, click **Edit** in the top-right corner.
## Copy a dashboard
To copy a dashboard, follow these steps:
1. Click **Dashboards** in the main menu.
1. Open the dashboard you want to copy.
1. Click **Edit** in top-right corner.
1. Click the **Save dashboard** drop-down and select **Save as copy**.
1. (Optional) Specify the name, folder, description, and whether or not to copy the original dashboard tags for the copied dashboard.
By default, the copied dashboard has the same name as the original dashboard with the word "Copy" appended and is in the same folder.
1. Click **Save**.
## 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](ref: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.
**Before you begin:**
- Ensure that the query includes a multi-value variable.
**To configure repeating rows:**
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to work on.
1. At the top of the dashboard, click **Add** and select **Row** in the drop-down.
If the dashboard is empty, you can click the **+ Add row** button in the middle of the dashboard.
1. Hover over the row title and click the cog icon.
1. In the **Row Options** dialog box, add a title and select the variable for which you want to add repeating rows.
1. Click **Update**.
To provide context to dashboard users, add the variable to the row title.
### Repeating rows and the Dashboard special data source
If a row includes panels using the special [Dashboard data source](ref:built-in-special-data-sources)&mdash;the data source that uses a result set from another panel in the same dashboard&mdash;then corresponding panels in repeated rows will reference the panel in the original row, not the ones in the repeated rows.
For example, in a dashboard:
- `Row 1` includes `Panel 1A` and `Panel 1B`
- `Panel 1B` uses the results from `Panel 1A` by way of the `-- Dashboard --` data source
- Repeating row, `Row 2`, includes `Panel 2A` and `Panel 2B`
- `Panel 2B` references `Panel 1A`, not `Panel 2A`
## Move a panel
You can place a panel on a dashboard in any location.
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to work on.
1. Click **Edit** in the top-right corner.
1. Click the panel title and drag the panel to the new location.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
## Resize a panel
You can size a dashboard panel to suits your needs.
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to work on.
1. Click **Edit** in the top-right corner.
1. To adjust the size of the panel, click and drag the lower-right corner of the panel.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
docs/sources/visualizations/dashboards/build-dashboards/create-dynamic-dashboard/index.md
+415
View File
@@ -0,0 +1,415 @@
---
labels:
products:
- cloud
- oss
stage:
- experimental
_build:
list: false
noindex: true
title: Create a dynamic dashboard
description: Create and edit a dynamic dashboard
weight: 900
refs:
built-in-special-data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#special-data-sources
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/#special-data-sources
visualization-specific-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/
configure-standard-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/
configure-value-mappings:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-value-mappings/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-value-mappings/
generative-ai-features:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/manage-dashboards/#set-up-generative-ai-features-for-dashboards
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/manage-dashboards/#set-up-generative-ai-features-for-dashboards
configure-thresholds:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-thresholds/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-thresholds/
data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/
add-a-data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#add-a-data-source
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#add-a-data-source
about-users-and-permissions:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
visualizations-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
configure-repeating-panels:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-panel-options/#configure-repeating-panels
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-panel-options/#configure-repeating-panels
override-field-values:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-overrides/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-overrides/
aliases:
- ../../../dashboards/build-dashboards/create-dynamic-dashboard/ # /docs/grafana/next/dashboards/build-dashboards/create-dynamic-dashboard/
---
# Create and edit dynamic dashboards
{{< admonition type="caution" >}}
Dynamic dashboards is an [experimental](https://grafana.com/docs/release-life-cycle/) feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
**Do not enable this feature in production environments as it may result in the irreversible loss of data.**
{{< /admonition >}}
Dashboards and panels allow you to show your data in visual form. Each panel needs at least one query to display a visualization.
## Before you begin
- Ensure that you have the proper permissions. For more information about permissions, refer to [About users and permissions](ref: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](ref:add-a-data-source) if you need instructions.
## Create a dashboard
To create a dashboard, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click **New** and select **New Dashboard**.
1. In the edit pane, enter the dashboard title and description.
{{< figure src="/media/docs/grafana/dashboards/screenshot-new-dashboard-v12.png" max-width="750px" alt="New dashboard" >}}
1. Under **Panel layout**, choose one of the following options:
- **Custom** - Position and size panels manually. The default selection.
- **Auto grid** - Panels are automatically resized to create a uniform grid based on the column and row settings.
1. Click **+ Add visualization**.
1. In the dialog box that opens, do one of the following:
- Select one of your existing data sources.
- Select one of the Grafana [built-in special data sources](ref:built-in-special-data-sources).
- Click **Configure a new data source** to set up a new one (Admins only).
{{< figure class="float-right" src="/media/docs/grafana/dashboards/screenshot-data-source-selector-10.0.png" max-width="800px" alt="Select data source modal" >}}
The **Edit panel** view opens with your data source selected.
You can change the panel data source later using the drop-down in the **Query** tab of the panel editor if needed.
For more information about data sources, refer to [Data sources](ref:data-sources) for specific guidelines.
1. Write or construct a query in the query language of your data source.
1. Click **Refresh** to query the data source.
1. In the visualization list, select a visualization type.
{{< figure src="/media/docs/grafana/dashboards/screenshot-select-visualization-v12.png" max-width="350px" alt="Visualization selector" >}}
Grafana displays a preview of your query results with the visualization applied.
For more information about configuring individual visualizations, refer to [Visualizations options](ref:visualizations-options).
1. Under **Panel options**, enter a title and description for your panel or have Grafana create them using [generative AI features](ref:generative-ai-features).
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](ref:configure-value-mappings)
- [Visualization-specific options](ref:visualization-specific-options)
- [Override field values](ref:override-field-values)
- [Configure thresholds](ref:configure-thresholds)
- [Configure standard options](ref:configure-standard-options)
1. When you've finished editing your panel, click **Save**.
Alternatively, click **Back to dashboard** if you want to see your changes applied to the dashboard first. Then click **Save** when you're ready.
1. Enter a title and description for your dashboard if you haven't already or have Grafana create them using [generative AI features](ref:generative-ai-features).
1. Select a folder, if applicable.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. To add more panels to the dashboard, click **Back to dashboard** and at the bottom-left corner of the dashboard, click **+ Add panel**.
{{< figure src="/media/docs/grafana/dashboards/screenshot-add-panel-v12.png" max-width="500px" alt="Add panel button" >}}
1. (Optional) In the edit pane, enter a title and description for the panel and set the panel transparency and repeat options, if applicable.
1. Click **Configure** in either the edit pane or on the panel to the configuration process.
1. When you've saved all the changes you want to make to the dashboard, click **Back to dashboard**.
1. Toggle off the edit mode switch.
{{< admonition type="caution" >}}
Dynamic dashboards is an [experimental](https://grafana.com/docs/release-life-cycle/) feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
**Do not enable this feature in production environments as it may result in the irreversible loss of data.**
{{< /admonition >}}
## Group panels
To help create meaningful sections in your dashboard, you can group panels into rows or tabs.
Rows and tabs let you break up big dashboards or make one dashboard out of several smaller ones.
You can nest tabs and rows within each other or themselves.
Also, tabs are included in the dashboard URL.
The following sections describe the configuration options for adding tabs and rows.
While grouping is meant for multiple panels, you can start a grouping with just one panel.
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to update.
1. Toggle on the edit mode switch.
1. At the bottom-left corner of the dashboard, click **Group panels**.
1. Select **Group into row** or **Group into tab**.
A dotted line surrounds the panels and the **Row** or **Tab** edit pane is displayed on the right side of the dashboard.
1. Set the [grouping configuration options](#grouping-configuration-options).
1. When you're finished, click **Save** at the top-right corner of the dashboard.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
### Grouping configuration options
The following table describes the options you can set for a row.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Title | Title of the row or tab. |
| Fill screen | Toggle the switch on to make the row fill the screen. Only applies to rows. |
| Hide row header | Toggle the switch on to hide the header. In edit mode, the row header is visible, but crossed out with the hidden icon next to it. Only applies to rows. |
| Group layout | Select the grouping option, between **Rows** and **Tabs**. Only available when there's a nested grouping and applies to the nested grouping. |
| Panel layout | Select whether panels are sized and positioned manually, **Custom**, or automatically, **Auto grid**. Only available when a grouping contains panels. |
| Repeat options > [Repeat by variable](#configure-repeat-options) | Configure the dashboard to dynamically add rows or tabs based on the value of a variable. |
| Show / hide rules > [Row/Tab visibility](#configure-showhide-rules) | Control whether or not rows or tabs are displayed based on variables or a time range. |
<!-- prettier-ignore-end -->
## Configure repeat options
<!-- previous heading "Configure repeating rows" -->
You can configure Grafana to dynamically add panels, rows, or tabs to a dashboard based on the value of that variable.
Variables dynamically change your queries across all rows in a dashboard.
This only applies to queries that include a multi-value variable.
<!-- 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.
Might be good to update this Play example -->
To configure repeats, follow these steps:
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to update.
1. Toggle on the edit mode switch.
The **Dashboard** edit pane opens on the right side of the dashboard.
1. Click in the panel, row, or tab you want to work with to bring it into focus and display the associated options in the edit pane.
1. Expand the **Repeat options** section.
1. Select the **Repeat by variable**.
1. For panels only, set the following options:
- Under **Repeat direction**, choose one of the following:
- **Horizontal** - Arrange panels side-by-side. Grafana adjusts the width of a repeated panel. You can’t mix other panels on a row with a repeated panel.
- **Vertical** - Arrange panels in a column. The width of repeated panels is the same as the original, repeated panel.
- If you selected **Horizontal**, select a value in the **Max per row** drop-down list to control the maximum number of panels that can be in a row.
1. (Optional) To provide context to dashboard users, add the variable name to the panel, row, or tab title.
1. When you've finished setting the repeat option, click **Save**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Toggle off the edit mode switch.
### Repeating rows and the Dashboard special data source
<!-- is this next section still true? -->
If a row includes panels using the special [Dashboard data source](ref:built-in-special-data-sources)&mdash;the data source that uses a result set from another panel in the same dashboard&mdash;then corresponding panels in repeated rows will reference the panel in the original row, not the ones in the repeated rows.
For example, in a dashboard:
- `Row 1` includes `Panel 1A` and `Panel 1B`
- `Panel 1B` uses the results from `Panel 1A` by way of the `-- Dashboard --` data source
- Repeating row, `Row 2`, includes `Panel 2A` and `Panel 2B`
- `Panel 2B` references `Panel 1A`, not `Panel 2A`
## Configure show/hide rules
You can configure panels, rows, and tabs to be shown or hidden based on rules.
For example, you might want to set a panel to be hidden if there's no data returned by a query or a tab to only be shown based on a variable being present.
{{< admonition type="note" >}}
You can only configure show/hide rules for panels when the dashboard is using the **Auto grid** panel layout.
{{< /admonition >}}
To configure show/hide rules, follow these steps:
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to update.
1. Toggle on the edit mode switch.
The **Dashboard** edit pane opens on the right side of the dashboard.
1. Click in the panel, row, or tab you want to work with to bring it into focus and display the associated options in the edit pane.
1. Expand the **Show / hide rules** section.
1. Select **Show** or **Hide** to set whether the panel, row, or tab is shown or hidden based on the rules outcome.
1. Click **+ Add rule**.
1. Select a rule type:
- **Query result** - Show or hide a panel based on query results. Choose from **Has data** and **No data**. For panels only.
- **Template variable** - Show or hide the panel, row, or tab dynamically based on the variable value. Select a variable and operator and enter a value.
- **Time range less than** - Show or hide the panel, row, or tab if the dashboard time range is shorter than the selected time frame. Select or enter a time range.
1. Configure the rule.
1. Under **Match rules**, select one of the following:
- **Match all** - The panel, row, or tab is shown or hidden only if _all_ the rules are matched.
- **Match any** - The panel, row, or tab is shown or hidden if _any_ of the rules are matched.
This option is only displayed if you add multiple rules.
1. When you've finished setting rules, click **Save**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Toggle off the edit mode switch.
{{< admonition type="caution" >}}
Dynamic dashboards is an [experimental](https://grafana.com/docs/release-life-cycle/) feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
**Do not enable this feature in production environments as it may result in the irreversible loss of data.**
{{< /admonition >}}
## Edit dashboards
When the dashboard is in edit mode, the edit pane that opens displays options associated with the part of the dashboard that it's in focus.
For example, if you click in the area of a panel, row, or tab, that area comes into focus and the edit pane shows the options for that area:
{{< figure src="/media/docs/grafana/dashboards/screenshot-edit-pane-focus-v12.png" max-width="750px" alt="Dashboard with a panel in focus" >}}
- For rows and tabs, all of the available options are in the edit pane.
- For panels, high-level options are in the edit pane and further configuration options are in the **Edit panel** view.
- For dashboards, high-level options are in the edit pane and further configuration options are in the **Settings** page.
To edit dashboards, follow these steps:
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to update.
1. Toggle on the edit mode switch.
The **Dashboard** edit pane opens on the right side of the dashboard.
1. Click in the area you want to work with to bring it into focus and display the associated options in the edit pane.
1. Do one of the following:
- For rows or tabs, make the required changes using the edit pane.
- For panels, update the panel title, description, repeat options or show/hide rules in the edit pane. For more changes, click **Configure** and continue in **Edit panel** view.
- For dashboards, update the dashboard title, description, grouping or panel layout. For more changes, click the settings (gear) icon in the top-right corner.
1. When you've finished making changes, click **Save**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Toggle off the edit mode switch.
### Undo and redo
When a dashboard is in edit mode, you can undo and redo changes you've made using the buttons on the toolbar:
{{< figure src="/media/docs/grafana/dashboards/screenshot-undo-redo-icons-v12.0.png" max-width="500px" alt="Undo and redo buttons" >}}
When you've made a change and hover the cursor over the buttons, the tooltip displays the change you're about to undo or redo.
Also, you can continue undoing or redoing as many changes as you need:
{{< video-embed src="/media/docs/grafana/dashboards/screen-record-undo-redo-v12.0.mp4" >}}
The undo and redo buttons are only available at the dashboard level and only apply to changes made there, such as dashboard layout and grouping and high-level dashboard or panel updates.
They aren't visible and don't apply when you're configuring a panel or making changes in the dashboard settings.
{{< admonition type="note" >}}
Not all dashboard edit actions can be undone or redone yet.
{{< /admonition >}}
## Move or resize a panel
<!-- previous headings Move a panel & Resize a panel -->
When you're dashboard has a **Custom** layout, you can resize or move a panel to any location on the dashboard.
To move or resize, follow these steps:
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to update.
1. Toggle on the edit mode switch.
1. Do one of the following:
- Click the panel title and drag the panel to the new location.
- Click and drag the lower-right corner of the panel to change the size of the panel.
1. Click **Save**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Toggle off the edit mode switch.
## Navigate using the dashboard outline
The dashboard **Outline** provides a tree-like structure that shows you all of the parts of your dashboard and their relationships to each other including panels, rows, tabs, and variables.
The outline also lets you quickly navigate the dashboard so that you don't have to spend time finding a particular element to work with it.
By default, the outline is collapsed except for the part that's currently in focus.
{{< figure src="/media/docs/grafana/dashboards/screenshot-dashboard-outline-v12.png" max-width="750px" alt="Dashboard with outline open showing panel in focus" >}}
To navigate the dashboard using the outline, follow these steps:
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to update.
1. Toggle on the edit mode switch.
The **Dashboard** edit pane opens on the right side of the dashboard.
1. In the edit pane, expand the **Outline** section.
1. Expand the outline to find the dashboard part to which you want to navigate.
1. Click the tree item to navigate that part of the dashboard.
## Copy a dashboard
To make a copy of a dashboard, follow these steps:
1. Click **Dashboards** in the main menu.
1. Navigate to the dashboard you want to update.
1. Toggle on the edit mode switch.
1. Click the **Save** drop-down and select **Save as copy**.
1. (Optional) Specify the name, folder, description, and whether or not to copy the original dashboard tags for the copied dashboard.
By default, the copied dashboard has the same name as the original dashboard with the word "Copy" appended and is in the same folder.
1. Click **Save**.
{{< admonition type="caution" >}}
Dynamic dashboards is an [experimental](https://grafana.com/docs/release-life-cycle/) feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
**Do not enable this feature in production environments as it may result in the irreversible loss of data.**
{{< /admonition >}}
docs/sources/visualizations/dashboards/build-dashboards/import-dashboards/index.md
+62
View File
@@ -0,0 +1,62 @@
---
aliases:
- ../../../reference/export_import/ # /docs/grafana/next/reference/export_import/
- ../../../dashboards/export-import/ # /docs/grafana/next/dashboards/export-import/
- ../../../dashboards/build-dashboards/import-dashboards/ # /docs/grafana/next/dashboards/build-dashboards/import-dashboards/
canonical: https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/
keywords:
- grafana
- dashboard
- import
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Import dashboards
title: Import dashboards
description: Learn how to import dashboards and about Grafana's preconfigured dashboards
weight: 5
refs:
share-dashboards-and-panels:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/share-dashboards-panels/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/share-dashboards-panels/
http-api:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/developers/http_api/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/
---
# Import dashboards
You can import preconfigured dashboards into your Grafana instance or Cloud stack using the UI or the [HTTP API](ref:http-api).
## Import a dashboard
To import a dashboard, follow these steps:
1. Click **Dashboards** in the primary menu.
1. Click **New** and select **Import** in the drop-down menu.
1. Perform one of the following steps:
- Upload a dashboard JSON file.
- Paste a [Grafana.com dashboard](#discover-dashboards-on-grafanacom) URL or ID into the field provided.
- Paste dashboard JSON text directly into the text area.
1. (Optional) Change the dashboard name, folder, or UID, and specify metric prefixes, if the dashboard uses any.
1. Select a data source, if required.
1. Click **Import**.
## Discover dashboards on grafana.com
The [Dashboards page](https://grafana.com/grafana/dashboards/) on grafana.com provides you with dashboards for common server applications. Browse our library of official and community-built dashboards and import them to quickly get up and running.
{{< figure src="/media/docs/grafana/dashboards/screenshot-gcom-dashboards.png" alt="Preconfigured dashboards on grafana.com">}}
You can also add to this library by exporting one of your own dashboards. For more information, refer to [Share dashboards and panels](ref:share-dashboards-and-panels).
## More examples
Your Grafana Cloud stack comes with several default dashboards in the **Grafana Cloud** folder in **Dashboards**. If you're running your own installation of Grafana, you can find more example dashboards in the `public/dashboards/` directory.
docs/sources/visualizations/dashboards/build-dashboards/manage-dashboard-links/index.md
+197
View File
@@ -0,0 +1,197 @@
---
aliases:
- ../../../dashboards/build-dashboards/manage-dashboard-links/ # /docs/grafana/next/dashboards/build-dashboards/manage-dashboard-links/
- ../../../features/navigation-links/ # /docs/grafana/next/features/navigation-links/
- ../../../linking/ # /docs/grafana/next/linking/
- ../../../linking/dashboard-links/ # /docs/grafana/next/linking/dashboard-links/
- ../../../linking/linking-overview/ # /docs/grafana/next/linking/linking-overview/
- ../../../panels/working-with-panels/add-link-to-panel/ # /docs/grafana/next/panels/working-with-panels/add-link-to-panel
- ../../../dashboards/manage-dashboard-links/ # /docs/grafana/next/dashboards/manage-dashboard-links/
description: Add links to your Grafana dashboards to connect to other dashboards, panels, and websites
keywords:
- link
- dashboard
- grafana
- linking
- create links
- link dashboards
- navigate
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Manage dashboard links
title: Manage dashboard links
weight: 200
refs:
data-links:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-data-links/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-data-links/
data-link-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-data-links/#data-link-variables
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-data-links/#data-link-variables
dashboard-url-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard-url-variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/create-dashboard-url-variables/
---
# Manage dashboard links
You can use links to navigate between commonly-used dashboards or to connect others to your visualizations. Links let you create shortcuts to other dashboards, panels, and even external websites.
Grafana supports dashboard links, panel links, and data links. Dashboard links are displayed at the top of the dashboard. Panel links are accessible by clicking the icon next to the panel title.
## Which link should you use?
Start by figuring out how you're currently navigating between dashboards. If you're often jumping between a set of dashboards and struggling to find the same context in each, links can help optimize your workflow.
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](#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](ref:data-links).
## Controlling time range using the URL
To control the time range of a panel or dashboard, you can provide query parameters in the dashboard URL:
- `from` - defines lower limit of the time range, specified in ms epoch
- `to` - defines upper limit of the time range, specified in ms epoch
- `time` and `time.window` - defines a time range from `time-time.window/2` to `time+time.window/2`. Both params should be specified in ms. For example `?time=1500000000000&time.window=10000` will result in 10s time range from 1499999995000 to 1500000005000
## 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](ref: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).
To see an example of dashboard links in action, check out:
- [Dashboard links with variables](https://play.grafana.org/d/rUpVRdamz/dashboard-links-with-variables?orgId=1)
- [Prometheus repeat](https://play.grafana.org/d/000000036/prometheus-repeat?orgId=1)
Once you've added a dashboard link, it appears in the upper right corner of your dashboard.
### Add links to dashboards
Add links to other dashboards at the top of your current dashboard.
1. In the dashboard you want to link, click **Edit**.
1. Click **Settings**.
1. Go to the **Links** tab and then click **Add dashboard link**.
The default link type is **Dashboards**.
1. In the **With tags** drop-down, enter tags to limit the linked dashboards to only the ones with the tags you enter.
If you don't add any tags, Grafana includes links to all other dashboards.
1. Set link options:
- **Show 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.
- **Include current 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
- **Include current template 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](ref:dashboard-url-variables).
- **Open link in new tab** – Select this option if you want the dashboard link to open in a new tab or window.
1. Click **Save dashboard** in the top-right corner.
1. Click **Back to dashboard** and then **Exit edit**.
### Add a URL link to a dashboard
Add a link to a URL at the top of your current dashboard. You can link to any available URL, including dashboards, panels, or external sites. You can even control the time range to ensure the user is zoomed in on the right data in Grafana.
1. In the dashboard you want to link, click **Edit**.
1. Click **Settings**.
1. Go to the **Links** tab and then click **Add dashboard link**.
1. In the **Type** drop-down, select **Link**.
1. In the **URL** field, enter the URL to which you want to link.
Depending on the target, you might want to include field values. **Example:** https://github.com/grafana/grafana/issues/new?title=Dashboard%3A%20HTTP%20Requests
1. In the **Tooltip** field, enter the tooltip you want the link to display when the user hovers their mouse over it.
1. In the **Icon** drop-down, choose the icon you want displayed with the link.
1. Set link options; by default, these options are enabled for URL links:
- **Include current 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
- **Include current template 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.
- **Open link in new tab** – Select this option if you want the dashboard link to open in a new tab or window.
1. Click **Save dashboard** in the top-right corner.
1. Click **Back to dashboard** and then **Exit edit**.
### Update a dashboard link
To edit, duplicate, or delete dashboard link, follow these steps:
1. In the dashboard you want to link, click **Edit**.
1. Click **Settings**.
1. Go to the **Links** tab.
1. Do one of the following:
- **Edit** - Click the name of the link and update the link settings.
- **Duplicate** - Click the copy link icon next to the link that you want to duplicate.
- **Delete** - Click the red **X** next to the link that you want to delete, and then **Delete**.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
## Panel links
Each panel can have its own set of links that are shown in the upper left of the panel after the panel title. You can link to any available URL, including dashboards, panels, or external sites. You can even control the time range to ensure the user is zoomed in on the right data in Grafana.
Click the icon next to the panel title to see available panel links.
{{< figure src="/media/docs/grafana/dashboards/screenshot-panel-links-v11.3.png" max-width="550px" alt="List of panel links displayed" >}}
### Add a panel link
1. Hover over any part of the panel to which you want to add the link to display the actions menu on the top right corner.
1. Click the menu and select **Edit**.
To use a keyboard shortcut to open the panel, hover over the panel and press `e`.
1. Expand the **Panel options** section, scroll down to **Panel links**.
1. Click **Add link**.
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. Press Ctrl+Space or Cmd+Space and click in the **URL** field to see the 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. You can also use time variables:
- `from` - Defines the lower limit of the time range, specified in ms epoch.
- `to` - Defines the upper limit of the time range, specified in ms epoch.
- `time` and `time.window` - Define a time range from `time-time.window/2` to `time+time.window/2`. Both params should be specified in ms. For example `?time=1500000000000&time.window=10000` will result in 10s time range from 1499999995000 to 1500000005000.
1. If you want the link to open in a new tab, then select **Open in new tab**.
1. Click **Save** to save changes and close the dialog box.
1. Click **Save dashboard** in the top-right corner.
1. Click **Back to dashboard** and then **Exit edit**.
### Update a panel link
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**.
To use a keyboard shortcut to open the panel, hover over the panel and press `e`.
1. Expand the **Panel options** section, scroll down to Panel links.
1. Find the link that you want to make changes to.
1. Click the Edit (pencil) icon to open the Edit link window.
1. Make any necessary changes.
1. Click **Save** to save changes and close the dialog box.
1. Click **Save dashboard** in the top-right corner.
1. Click **Back to dashboard** and then **Exit edit**.
### Delete a panel link
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**.
To use a keyboard shortcut to open the panel, hover over the panel and press `e`.
1. Expand the **Panel options** section, scroll down to 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 dashboard** in the top-right corner.
1. Click **Back to dashboard** and then **Exit edit**.
docs/sources/visualizations/dashboards/build-dashboards/manage-library-panels/index.md
+141
View File
@@ -0,0 +1,141 @@
---
aliases:
- ../../../dashboards/build-dashboards/manage-library-panels/ # /docs/grafana/next/dashboards/build-dashboards/manage-library-panels/
- ../../../panels/library-panels/ # /docs/grafana/next/panels/library-panels
- ../../../panels/library-panels/add-library-panel/ # /docs/grafana/next/panels/library-panels/add-library-panel
- ../../../panels/library-panels/create-library-panel/ # /docs/grafana/next/panels/library-panels/create-library-panel
- ../../../panels/library-panels/delete-library-panel/ # /docs/grafana/next/panels/library-panels/delete-library-panel
- ../../../panels/library-panels/manage-library-panel/ # /docs/grafana/next/panels/library-panels/manage-library-panel
- ../../../panels/library-panels/unlink-library-panel/ # /docs/grafana/next/panels/library-panels/unlink-library-panel
- ../../../panels/panel-library/ # /docs/grafana/next/panels/panels-library/
- ../manage-library-panels/ # /docs/grafana/next/visualizations/dashboards/manage-library-panels/
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Manage library panels
title: Manage library panels
description: Create reusable library panels that you can use in any dashboard
weight: 300
refs:
rbac:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/
---
# Manage library panels
A library panel is a reusable panel that you can use in any dashboard. When you make a change to a library panel, that change propagates to all instances of where the panel is used. Library panels streamline reuse of panels across multiple dashboards.
You can save a library panel in a folder alongside saved dashboards.
## Role-based access control
You can control permissions for library panels using [role-based access control (RBAC)](ref:rbac). RBAC provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as dashboards, reports, and administrative settings.
## Create a library panel
Library panels can be reused in different dashboards throughout Grafana. When you create a library panel, the panel on the source dashboard is converted to a library panel as well. You need to save the original dashboard once a panel is converted.
To create a library panel, follow these steps:
1. In the top-right corner of the dashboard, click **Edit**.
1. Hover over any part of the panel you want to share to display the actions menu on the top right corner.
1. Click **More > New library panel**.
1. In the **Library panel name** field, enter the name.
1. In the **Save in folder** drop-down list, 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. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
Once created, you can modify the library panel using any dashboard on which it appears. After you save the changes, all instances of the library panel reflect these modifications.
## Add a library panel to a dashboard
Add a Grafana library panel to a dashboard when you want to provide visualizations to other dashboard users.
To add a library panel, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click **New** and select **New Dashboard** in the drop-down list.
1. On the empty dashboard, click **+ Add library panel**.
The **Add panel from panel library** drawer opens.
1. Filter the list or search to find the panel you want to add.
1. Click a panel to add it to the dashboard.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
## Unlink a library panel
Unlink a library panel when you want to make a change to the panel and not affect other instances of the library panel.
To unlink a library panel, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click **Library panels**.
1. Select a library panel that is being used in dashboards.
1. Click the panel you want to unlink.
1. In the dialog box, select the dashboard from which you want to unlink the panel.
1. Click **View panel in \<dashboard name\>**.
1. Click **Edit** in the top-right corner of the dashboard.
1. Hover over any part of the panel you want to unlink to display the menu icon on the top-right corner.
1. Click the menu icon and select **More > Unlink library panel**.
1. Click **Yes, unlink**.
1. Click **Save dashboard** and **Exit edit**.
Alternatively, if you know where the library panel is being used, you can go directly to that dashboard and start at step 7.
## Replace a library panel
To replace a library panel with a different one, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click **Library panels**.
1. Select a library panel that is being used in different dashboards.
1. Click the panel you want to unlink.
1. In the dialog box, select the dashboard from which you want to unlink the panel.
1. Click **View panel in \<dashboard name\>**.
1. Click **Edit** in the top-right corner of the dashboard.
1. Hover over any part of the panel you want to unlink to display the menu icon on the top-right corner.
1. Click the menu icon and select **More > Replace library panel**.
1. Select the replacement library panel.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save** and **Exit edit**.
Alternatively, if you know where the library panel that you want to replace is being used, you can go directly to that dashboard and start at step 7.
## View a list of library panels
You can view a list of available library panels and see where those panels are being used.
To view and manage library panels, follow these steps:
1. Click **Dashboards > Library panels** in the main menu.
You can see a list of previously defined library panels.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-library-panel-list-9-5.png" class="docs-image--no-shadow" max-width= "900px" alt="Library panels page with list of library panels" >}}
1. Search for a specific library panel if you know its name.
You can also filter the panels by folder or type.
1. Click the panel to see if it's being used in any dashboards.
1. (Optional) If the library panel is in use, select one of the dashboards using it.
1. (Optional) Click **View panel in \<dashboard name\>** to see the panel in context.
## Delete a library panel
To delete a library panel that you no longer need, follow these steps:
1. Click **Dashboards > Library panels** in the main menu.
1. Click the delete icon next to the library panel name.
1. Click **Delete**.
docs/sources/visualizations/dashboards/build-dashboards/manage-version-history/index.md
+59
View File
@@ -0,0 +1,59 @@
---
aliases:
- ../../../reference/dashboard_history/ # /docs/grafana/next/reference/dashboard_history/
- ../../../dashboards/dashboard-history/ # /docs/grafana/next/dashboards/dashboard-history/
- ../../../dashboards/build-dashboards/manage-version-history/ # /docs/grafana/next/dashboards/build-dashboards/manage-version-history/
keywords:
- grafana
- dashboard
- documentation
- version
- history
labels:
products:
- cloud
- enterprise
- oss
menutitle: Manage version history
title: Manage dashboard version history
description: View and compare previous versions of your dashboard
weight: 400
---
# Manage dashboard version history
Whenever you save a version of your dashboard, a copy of that version is saved so that previous versions of your dashboard are never lost. You can see a list of dashboard versions in the **Versions** tab of the dashboard settings:
![Dashboards versions list](/media/docs/grafana/dashboards/screenshot-dashboard-version-list-11.2.png)
The dashboard version history feature lets you compare and restore to previously saved dashboard versions.
## Compare two dashboard versions
To compare two dashboard versions, follow these steps:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
1. Go to the **Versions** tab.
1. Select the two dashboard versions that you want to compare.
1. Click **Compare versions** to view the diff between the two versions.
1. Review the text descriptions of the differences between the versions.
1. (Optional) Expand the **View JSON Diff** section of the page to see the diff of the raw JSON that represents your dashboard.
1. When you've finished comparing versions, click **Back to dashboard** and **Exit edit**.
When you're comparing versions, if one of the versions you've selected is the latest version, a button to restore the previous version is also displayed, so you can restore a version from the compare view:
![Dashboards versions diff](/media/docs/grafana/dashboards/screenshot-dashboard-compare-versions-restore-11.2.png)
## Restore a previously dashboard version
To restore to a previously saved dashboard version, follow these steps:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
1. Go to the **Versions** tab.
1. Click the **Restore** button next to the version.
When you restore a version, the dashboard is immediately saved and you're no longer in edit mode.
After you restore a previous version, a new version of the dashboard is created containing the same exact data as the previous version, but with a different version number. This is indicated in the **Notes column** in the **Versions** tab of the dashboard settings. This is done simply to ensure your previous dashboard versions are not affected by the change.
docs/sources/visualizations/dashboards/build-dashboards/modify-dashboard-settings/index.md
+174
View File
@@ -0,0 +1,174 @@
---
keywords:
- time settings
- variables
- links
- dashboard
- settings
labels:
products:
- cloud
- enterprise
- oss
title: Modify dashboard settings
description: Manage and edit your dashboard settings
weight: 8
refs:
variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
json-fields:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/view-dashboard-json-model/#json-fields
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/view-dashboard-json-model/#json-fields
data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/
dashboard-links:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/#dashboard-links
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/manage-dashboard-links/#dashboard-links
aliases:
- ../../../dashboards/build-dashboards/modify-dashboard-settings/ # /docs/grafana/next/dashboards/build-dashboards/modify-dashboard-settings/
---
# Modify dashboard settings
The dashboard settings page allows you to:
- Edit general dashboard properties, including time settings
- Add annotation queries
- Add dashboard variables
- Add links
- View the dashboard JSON model
To access the dashboard setting page:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
## Modify dashboard time settings
Adjust dashboard time settings when you want to change the dashboard timezone, the local browser time, and specify auto-refresh time intervals.
1. On the the **General** tab of the **Settings** page, scroll down to the **Time options** section.
1. Specify time settings as follows.
- **Time zone:** Specify the local time zone of the service or system that you are monitoring. This can be helpful when monitoring a system or service that operates across several time zones.
- **Default:** Grafana uses the default selected time zone for the user profile, team, or organization. If no time zone is specified for the user profile, a team the user is a member of, or the organization, then Grafana uses the local browser time.
- **Browser time:** The time zone configured for the viewing user browser is used. This is usually the same time zone as set on the computer.
- Standard [ISO 8601 time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), including UTC.
- **Auto refresh:** Customize the options displayed for relative time and the auto-refresh options Entries are comma separated and accept any valid time unit.
- **Now delay:** Override the `now` time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values.
- **Hide time picker:** Select this option if you do not want Grafana to display the time picker.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
## Modify graph tooltip behavior
Use this option to control tooltip and hover highlight behavior across graph panels (for example, time series).
1. On the the **General** tab of the **Settings** page, scroll down to the **Panel options** section.
1. Choose from the following options to control the tooltip and hover highlight behavior across graph panels:
- **Default** - Tooltip and hover highlight behavior isn't shared across panels.
- **Shared crosshair** - When you hover the cursor over one graph panel in the dashboard, the crosshair is also displayed on all other graph panels in the dashboard.
- **Shared tooltip** - When you hover the cursor over one graph panel in the dashboard, the crosshair and tooltips are also displayed on all other graph panels in the dashboard.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
## Add tags
You can add metadata to your dashboards using tags. Tags also give you the ability to filter the list of dashboards.
Tags can be up to 50 characters long, including spaces.
To add tags to a dashboard, follow these steps:
1. On the the **General** tab of the **Settings** page, scroll down to the **Tags** section.
1. In the field, enter a new or existing tag.
If you're entering an existing tag, make sure that you spell it the same way or a new tag is created.
1. Click **Add** or press the Enter key.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
When you're on the **Dashboards** page, any tags you've entered show up under the **Tags** column.
## Add an annotation query
An annotation query is a query that queries for events. These events can be visualized in graphs across the dashboard as vertical lines along with a small
icon you can hover over to see the event information.
1. On the **Settings** page, go to the **Annotations** tab.
1. Click **Add annotation query**.
1. Enter a name and select a data source.
1. Complete the rest of the form to build a query and annotation.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
The query editor UI changes based on the data source you select. Refer to the [Data source](ref:data-source) documentation for details on how to construct a query.
## Add a variable
Variables enable you to create more interactive and dynamic dashboards. Instead of hard-coding things like server, application,
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](ref:variables).
1. On the **Settings** page, go to the **Variables** tab.
1. Click **+ New variable**.
1. In the **Select variable type** drop-down, choose an option.
The variable type you select impacts which fields you populate on the page.
1. In the **General** section, enter the name of the variable.
This is the name that you'll use later in queries.
1. Set the rest of the variable options.
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
## Add a link
Dashboard links enable you to place links to other dashboards and web sites directly below the dashboard header. Links provide for easy navigation to other, related dashboards and content.
1. On the **Settings** page, click the **Links** tab.
1. Click **+ New link**.
1. Enter title for the link.
1. In the **Type** drop-down, select **Dashboards** or **Link**.
1. Set the rest of the link options.
For more detailed directions on creating links, refer to [Dashboard links](ref:dashboard-links)
1. Click **Save dashboard**.
1. (Optional) Enter a description of the changes you've made.
1. Click **Save**.
1. Click **Exit edit**.
## View dashboard JSON model
A dashboard in Grafana is represented by a JSON object, which stores metadata of its dashboard. Dashboard metadata includes dashboard properties, metadata from panels, template variables, panel queries, and so on.
To view a dashboard JSON model, on the **Settings** page, click the **JSON Model** tab.
For more information about the JSON fields, refer to [JSON fields](ref:json-fields).
docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md
+272
View File
@@ -0,0 +1,272 @@
---
aliases:
- ../../../reference/dashboard/ # /docs/grafana/next/reference/dashboard/
- ../../../dashboards/json-model/ # /docs/grafana/next/dashboards/json-model/
- ../../../dashboards/build-dashboards/view-dashboard-json-model/ # /docs/grafana/next/dashboards/build-dashboards/view-dashboard-json-model/
keywords:
- grafana
- dashboard
- documentation
- json
- model
labels:
products:
- cloud
- enterprise
- oss
title: JSON model
description: View your Grafana dashboard JSON object
weight: 700
refs:
annotations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/annotate-visualizations/
---
# Dashboard JSON model
A dashboard in Grafana is represented by a JSON object, which stores metadata of its dashboard. Dashboard metadata includes dashboard properties, metadata from panels, template variables, panel queries, etc.
To view the JSON of a dashboard:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
1. Go to the **JSON Model** tab.
1. When you've finished viewing the JSON, click **Back to dashboard** and **Exit edit**.
## JSON fields
When a user creates a new dashboard, a new dashboard JSON object is initialized with the following fields:
{{< admonition type="note" >}}
In the following JSON, id is shown as null which is the default value assigned to it until a dashboard is saved. Once a dashboard is saved, an integer value is assigned to the `id` field.
{{< /admonition >}}
```json
{
"id": null,
"uid": "cLV5GDCkz",
"title": "New dashboard",
"tags": [],
"timezone": "browser",
"editable": true,
"graphTooltip": 1,
"panels": [],
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {
"refresh_intervals": []
},
"templating": {
"list": []
},
"annotations": {
"list": []
},
"refresh": "5s",
"schemaVersion": 17,
"version": 0,
"links": []
}
```
Each field in the dashboard JSON is explained below with its usage:
| Name | Usage |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| **id** | unique numeric identifier for the dashboard. (generated by the db) |
| **uid** | unique dashboard identifier that can be generated by anyone. string (8-40) |
| **title** | current title of dashboard |
| **tags** | tags associated with dashboard, an array of strings |
| **style** | theme of dashboard, i.e. `dark` or `light` |
| **timezone** | timezone of dashboard, i.e. `utc` or `browser` |
| **editable** | whether a dashboard is editable or not |
| **graphTooltip** | 0 for no shared crosshair or tooltip (default), 1 for shared crosshair, 2 for shared crosshair AND shared tooltip |
| **time** | time range for dashboard, i.e. last 6 hours, last 7 days, etc |
| **timepicker** | timepicker metadata, see [timepicker section](#timepicker) for details |
| **templating** | templating metadata, see [templating section](#templating) for details |
| **annotations** | annotations metadata, see [annotations](ref:annotations) for how to add them |
| **refresh** | auto-refresh interval |
| **schemaVersion** | version of the JSON schema (integer), incremented each time a Grafana update brings changes to said schema |
| **version** | version of the dashboard (integer), incremented each time the dashboard is updated |
| **panels** | panels array, see below for detail. |
## Panels
Panels are the building blocks of a dashboard. It consists of data source queries, type of graphs, aliases, etc. Panel JSON consists of an array of JSON objects, each representing a different panel. Most of the fields are common for all panels but some fields depend on the panel type. Following is an example of panel JSON of a text panel.
```json
"panels": [
{
"type": "text",
"title": "Panel Title",
"gridPos": {
"x": 0,
"y": 0,
"w": 12,
"h": 9
},
"id": 4,
"mode": "markdown",
"content": "# title"
}
```
### Panel size and position
The gridPos property describes the panel size and position in grid coordinates.
- `w` 1-24 (the width of the dashboard is divided into 24 columns)
- `h` In grid height units, each represents 30 pixels.
- `x` The x position, in same unit as `w`.
- `y` The y position, in same unit as `h`.
The grid has a negative gravity that moves panels up if there is empty space above a panel.
### timepicker
```json
"timepicker": {
"collapse": false,
"enable": true,
"notice": false,
"now": true,
"hidden": false,
"nowDelay": "",
"quick_ranges": [
{
"display": "Last 6 hours",
"from": "now-6h",
"to": "now"
},
{
"display": "Last 7 days",
"from": "now-7d",
"to": "now"
}
],
"refresh_intervals": [
"5s",
"10s",
"30s",
"1m",
"5m",
"15m",
"30m",
"1h",
"2h",
"1d"
],
"status": "Stable",
"type": "timepicker"
}
```
Usage of the fields is explained below:
| Name | Usage |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **collapse** | whether timepicker is collapsed or not |
| **enable** | whether timepicker is enabled or not |
| **notice** | |
| **now** | |
| **hidden** | whether timepicker is hidden or not |
| **nowDelay** | override the now time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values. |
| **quick_ranges** | custom quick ranges |
| **refresh_intervals** | interval options available in the refresh picker dropdown |
| **status** | |
| **type** | |
### templating
The `templating` field contains an array of template variables with their saved values along with some other metadata, for example:
```json
"templating": {
"enable": true,
"list": [
{
"allFormat": "wildcard",
"current": {
"tags": [],
"text": "prod",
"value": "prod"
},
"datasource": null,
"includeAll": true,
"name": "env",
"options": [
{
"selected": false,
"text": "All",
"value": "*"
},
{
"selected": false,
"text": "stage",
"value": "stage"
},
{
"selected": false,
"text": "test",
"value": "test"
}
],
"query": "tag_values(cpu.utilization.average,env)",
"refresh": false,
"type": "query"
},
{
"allFormat": "wildcard",
"current": {
"text": "apache",
"value": "apache"
},
"datasource": null,
"includeAll": false,
"multi": false,
"multiFormat": "glob",
"name": "app",
"options": [
{
"selected": true,
"text": "tomcat",
"value": "tomcat"
},
{
"selected": false,
"text": "cassandra",
"value": "cassandra"
}
],
"query": "tag_values(cpu.utilization.average,app)",
"refresh": false,
"regex": "",
"type": "query"
}
]
}
```
Usage of the above mentioned fields in the templating section is explained below:
| Name | Usage |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| **enable** | whether templating is enabled or not |
| **list** | an array of objects each representing one template variable |
| **allFormat** | format to use while fetching all values from data source, eg: `wildcard`, `glob`, `regex`, `pipe`, etc. |
| **current** | shows current selected variable text/value on the dashboard |
| **data source** | shows data source for the variables |
| **includeAll** | whether all value option is available or not |
| **multi** | whether multiple values can be selected or not from variable value list |
| **multiFormat** | format to use while fetching timeseries from data source |
| **name** | name of variable |
| **options** | array of variable text/value pairs available for selection on dashboard |
| **query** | data source query used to fetch values for a variable |
| **refresh** | configures when to refresh a variable |
| **regex** | extracts part of a series name or metric node segment |
| **type** | type of variable, i.e. `custom`, `query` or `interval` |
docs/sources/visualizations/dashboards/create-manage-playlists/index.md
+128
View File
@@ -0,0 +1,128 @@
---
aliases:
- ../../reference/playlist/ # /docs/grafana/next/reference/playlist/
- ../../dashboards/playlist/ # /docs/grafana/next/dashboards/playlist/
- ../../dashboards/create-manage-playlists/ # /docs/grafana/next/dashboards/create-manage-playlists/
keywords:
- grafana
- dashboard
- documentation
- playlist
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Manage playlists
title: Manage playlists
description: Create and manage dashboard playlists
weight: 500
---
# Manage playlists
A _playlist_ is a list of dashboards that are displayed in a sequence. You might use a playlist to build situational awareness or to present your metrics to your team or visitors.
Grafana automatically scales dashboards to any resolution, which makes them perfect for big screens.
You can access the **Playlist** feature from Grafana's side menu, in the Dashboards submenu.
{{< admonition type="note" >}}
You must have at least Editor role permissions to create and manage playlists.
{{< /admonition >}}
## Access, share, and control a playlist
Use the information in this section to access playlists. Start and control the display of a playlist using one of the six available modes.
### Access a playlist
1. Click **Dashboards** in the main menu.
1. Click **Playlists** to see a list of playlists.
### Start a playlist
You can start a playlist in four different view modes. View modes determine how the menus and navigation bar appear on the dashboards as well as how panels are sized.
1. Click **Dashboards** in the main menu.
1. Click **Playlists**.
1. Find the desired playlist and click **Start playlist**.
1. In the dialog box that opens, select one of the [four playlist modes](#playlist-modes) available.
1. Disable any dashboard controls that you don't want displayed while the list plays; these controls are enabled and visible by default. Select from:
- **Time and refresh**
- **Variables**
- **Dashboard links**
1. Click **Start \<playlist name\>**.
The playlist displays each dashboard for the time specified in the **Interval** field, set when creating or editing a playlist. After a playlist starts, you can [start or stop it](#control-a-playlist) it using the controls at the top of your screen.
### Playlist modes
<!-- prettier-ignore-start -->
| Mode | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| Normal mode | <ul><li>The main menu and navbar remain visible.</li><li>Dashboard controls are hidden.</li><li>Playlist controls are displayed at the top of the screen.<li><ul> |
| Normal mode (with auto fit panels) | <ul><li>The main menu and navbar remain visible.</li><li>Dashboard controls are hidden.</li><li>Playlist controls are displayed at the top of the screen.</li><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul> |
| Kiosk mode | <ul><li>The main menu, navbar, and dashboard controls are hidden.</li><li>You can disable the playlist manually by pressing the `Esc` key after the playlist has started. Doing so causes the playlist controls to be displayed at the top of the screen briefly.</li></ul> |
| Kiosk mode (with auto fit panels) | <ul><<li>The main menu, navbar, and dashboard controls are hidden.</li><li>You can disable the playlist manually by pressing the `Esc` key after the playlist has started. Doing so causes the playlist controls to be displayed at the top of the screen briefly.</li><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul> |
<!-- prettier-ignore-end -->
### Playlist controls
You can control a playlist in **Normal** mode after it's started, using the buttons at the top of your screen. Press the `Esc` key to stop the playlist.
- **Next (double-right arrow)** - Advances to the next dashboard.
- **Back (doublt-left arrow)** - Returns to the previous dashboard.
- **Stop playlist** - Ends the playlist, and exits to the current dashboard.
## Create a playlist
You can create a playlist to present dashboards in a sequence, with a set order and time interval between dashboards. Be sure that all the dashboards you want to appear in your playlist are added before you create the playlist.
1. Click **Dashboards** in the main menu.
1. Click **Playlists**.
1. Click **New playlist**.
1. In the **Name** field, enter a descriptive name.
1. In the **Interval** field, enter the time interval each dashboard is displayed before moving on to the next dashboard.
1. In the **Add dashboards** section, add dashboards to the playlist using the **Add by title** and **Add by tag** drop-down options.
Added dashboards are displayed in a list in the **Dashboards** section of the page, in the order you added them. This is also the play order of the dashboards.
1. Click **Save**.
## Edit a playlist
You can edit a playlist including adding, removing, and rearranging the order of dashboards.
1. Click **Dashboards** in the main menu.
1. Click **Playlists**.
1. Find the playlist you want to update and click **Edit playlist**. Do one or more of the following:
- Edit - Update the name and time interval.
- Add dashboards - Search for dashboards by title or tag to add them to the playlist.
- Rearrange dashboards - Click and drag the dashboards into your desired order.
- Remove dashboards - Click the **X** next to the name of the dashboard you want to remove from the playlist.
1. Click **Save**.
## Share a playlist in a view mode
You can share a playlist by copying the link address on the view mode you prefer, and pasting the URL to your destination.
1. Click **Dashboards** in the main menu.
1. Click **Playlists**.
1. Click the share icon of the playlist you want to share.
1. Select the view mode you prefer.
1. Click **Copy** next to the **Link URL** to copy it to your clipboard.
1. Paste the URL to your destination.
## Delete a playlist
When you no longer need a playlist, follow these steps to delete it:
1. Click **Dashboards** in the main menu.
1. Click **Playlists**.
1. Find the playlist you want to remove.
1. Click **Delete playlist**.
docs/sources/visualizations/dashboards/create-reports/_index.md
+406
View File
@@ -0,0 +1,406 @@
---
aliases:
- ../../administration/reports/ # /docs/grafana/next/administration/reports/
- ../../enterprise/export-pdf/ # /docs/grafana/next/enterprise/export-pdf/
- ../../enterprise/reporting/ # /docs/grafana/next/enterprise/reporting/
- ../../panels/create-reports/ # /docs/grafana/next/panels/create-reports/
- ../../dashboards/reporting/ # /docs/grafana/next/dashboards/reporting/
- ../../dashboards/create-reports/ # /docs/grafana/next/dashboards/create-reports/
keywords:
- grafana
- reporting
- export
- pdf
labels:
products:
- cloud
- enterprise
menuTitle: Reporting
title: Create and manage reports
description: Generate and share PDF reports from your Grafana dashboards
weight: 600
refs:
grafana-enterprise:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
image-rendering:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/
max-size-configuration:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#max_attachment_size_mb
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#max_attachment_size_mb
log-filters:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#filters
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#filters
permission:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
rbac:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/
send-report:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/developers/http_api/reporting/#send-a-report
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/reporting/#send-a-report
smtp:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#smtp
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#smtp
temp-data-lifetime:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#temp_data_lifetime
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#temp_data_lifetime
templates-and-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
time-range-controls:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/use-dashboards/#set-dashboard-time-range
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/use-dashboards/#set-dashboard-time-range
---
# Create and manage reports
{{< admonition type="note" >}}
The redesigned reporting feature is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. To use this feature, enable the `newShareReportDrawer` feature toggle in your Grafana configuration file or, for Grafana Cloud, contact Support.
{{< /admonition >}}
**Reporting** allows you to send automated and scheduled emails from any of your dashboards.
You can configure several elements of these reports and generate PDFs and CSV files.
Any changes you make to a dashboard used in a report are reflected the next time the report is sent.
{{< figure src="/media/docs/grafana/dashboards/screenshot-report-config-v12.0.png" max-width="600px" alt="The report configuration screen" >}}
## Requirements
For Grafana Enterprise, the Reporting feature has the following requirements:
- SMTP must be configured for reports to be sent. Refer to [SMTP configuration documentation](ref:smtp) for more information.
- The [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) (v3.10+) must be installed or the remote rendering service must be set up. Refer to [Image rendering](ref:image-rendering) for more information.
### Rendering configuration
By default, attachments (PDFs, CSV files, and embedded images) larger than 10 MB are not sent, which keeps email servers from rejecting the email.
You can increase or decrease this limit in the [reporting configuration](ref:max-size-configuration).
When a report file is generated, it's temporarily written to the corresponding folder (`csv`, `pdf`, `png`) in the Grafana `data` folder.
A background job runs every 10 minutes and removes temporary files.
You can set how long a file should be stored before being removed by configuring the [`temp_data_lifetime`](ref:temp-data-lifetime) setting in your `ini` file.
## Access control
Only organization administrators can create reports by default.
You can customize who can create reports with [role-based access control (RBAC)](ref:rbac).
When [RBAC](ref:rbac) is enabled, you need to have the relevant [permissions](ref:permission) to create and manage reports.
Refer to specific guides to understand what permissions are required.
## Create a report
The report creation process is multi-step, but you don't need to complete these steps in order.
You can also save the report as a draft at any point during the initial creation process.
You can create directly from a dashboard or from the **Reporting** page.
Select one of the following tabs for directions on each option.
To create a report, follow these steps:
{{< tabs >}}
{{< tab-content name="Create a report directly from a dashboard" >}}
1. In the main menu, click **Dashboards**.
1. Navigate to the dashboard from which you want to create a report.
1. Click the **Share** drop-down list in the top-right corner of the dashboard.
1. Click **Schedule report**.
The **Schedule report** drawer opens. Any other reports using this dashboard are listed in the drawer. You can also click **See all reports** to navigate to **Reporting** for a full list of reports generated from all dashboards.
1. Click **+ Create a new report**.
1. Update the name of the report, if needed.
By default, the report name is the name of the dashboard.
1. Expand and complete each section of the report, as needed:
- [Dashboards](#1-dashboards)
- [Schedule](#2-schedule)
- [Email settings](#3-email-settings)
- [Recipients](#4-recipients)
- [Attachments](#5-attachments)
1. Click one of the following buttons at the bottom of the **Schedule report** drawer:
- The menu icon to access the following options:
- **Download CSV**
- **Preview PDF**
- **Report settings** - Takes you to **Reporting** in a new browser tab and opens the **Report template settings** drawer, where you can configure organization-level report settings.
- **Send preview** - Send a preview of the report to your desired recipient. You can choose to use the report recipients:
{{< figure src="/media/docs/grafana/dashboards/screenshot-send-preview-v12.0.png" max-width="350px" alt="The Send preview modal" >}}
- **Schedule report** - The report is sent according the schedule you've set.
- **Save draft** - You can save a draft at any point during the initial report creation process, even if it's missing required fields. The report won't be sent according to its schedule while it's a draft.
If you click the **x** at the top of the drawer without scheduling or saving the report as a draft, the report is discarded. This action can't be reversed.
1. When you finish configuring the report, click the **x** at the top of the **Schedule report** drawer to close it.
{{< /tab-content >}}
{{< tab-content name="Create a report from Reporting" >}}
1. In the main menu, click **Dashboards > Reporting**.
1. Click **+ Create a new report**.
The **Schedule report** drawer opens.
1. Enter a name for the report.
1. Expand and complete each section of the report, as needed:
- [Dashboards](#1-dashboards)
- [Schedule](#2-schedule)
- [Email settings](#3-email-settings)
- [Recipients](#4-recipients)
- [Attachments](#5-attachments)
1. Click one of the following buttons at the bottom of the **Schedule report** drawer:
- The menu icon to access the following options:
- **Download CSV**
- **Preview PDF**
- **Report settings** - Opens the **Report template settings** drawer, where you can configure organization-level report settings.
- **Send preview** - Send a preview of the report to your desired recipient. You can choose to use the report recipients:
{{< figure src="/media/docs/grafana/dashboards/screenshot-send-preview-v12.0.png" max-width="350px" alt="The Send preview modal" >}}
- **Schedule report** - The report is sent according the schedule you've set.
- **Save draft** - Save a draft at any point during the initial report creation process, even if it's missing required fields. The report won't be sent according to its schedule while it's a draft.
If you click the **x** at the top of the drawer without scheduling or saving the report as a draft, the report is discarded. This action can't be reversed.
1. When you finish configuring the report, click the **x** at the top of the **Schedule report** drawer to close it.
{{< /tab-content >}}
{{< /tabs >}}
### 1. Dashboards
At this step, select the dashboard or dashboards on which the report is based, as well as the variables and time ranges for those dashboards.
The options are:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Source dashboard (required) | Select or update the dashboard from which you want to generate the report. If you've created your report directly from a dashboard, this field is already filled in with the name of the current dashboard. |
| [Time range](#time-range) | Update the report time range. If you've created the report directly from a dashboard, the default time range is that of the dashboard. Otherwise, the default time range is **Last 6 hours**. |
| [Customize template variables](#customize-template-variables) | Select and customize the variable values for the selected dashboard. This section is only displayed if the dashboard has variables. |
| + Add dashboard | Add more dashboards to the report. |
<!-- prettier-ignore-end -->
#### Time range
If you leave the **Time range** field empty, reports use the saved time range of the dashboard.
Optionally, you can change the time range of the report by setting it in the **Time range** field.
If specified, the custom time range overrides the time range from the report's dashboard.
#### Customize template variables
Configure report-specific template variables for the dashboard.
The variables that you select override the variables from the dashboard.
For detailed information about using template variables, refer to [Variables](ref:templates-and-variables).
The query variables saved with a report might become out 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 won't 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.
This option is only displayed if the dashboard has variables.
### 2. Schedule
At this step, set scheduling information.
Options vary depending on the frequency you select.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Schedule | Choose one of the following:<ul><li>**Send now** sends the report immediately after you save it. To stop sending the report at some point in the future, add an end date.</li><li>**Send later** schedules a report for a later date. When you select this option, the required **Start date**, **Start time**, and **Time zone** options are displayed.</li></ul> |
| Frequency | You can schedule reports to be sent once, repeated on an hourly, daily, weekly, or monthly basis, or sent at custom intervals. |
| Start date | Set the date when the report should start being sent. |
| Start time | Set the time when the report should start being sent. |
| [Time zone](#time-zone) | Set the time zone of the report. |
| End date | Set the date when the report should stop being sent. If you leave this field empty, the report is sent out indefinitely. |
| Send only from Monday to Friday | For reports that have an hourly or daily frequency, you can choose to send them only from Monday to Friday. |
| Send on the last day of the month | When you schedule a report with a monthly frequency, and set the start date between the 29th and the 31st of the month, the report is only sent during the months that have those dates. If you want the report to be sent every month, select the **Send on the last day of the month** option. This way, the report is sent on the last day of every month regardless of how many days there are in the month. |
<!-- prettier-ignore-end -->
#### Time zone
Reports use the time zone of the dashboard from which they're generated.
You can control the time zone for your reports by setting the dashboard to a specific time zone.
Note that this affects the display of the dashboard for all users.
If a dashboard has the **Browser Time** setting, the reports generated from that dashboard use the time zone of the Grafana server.
As a result, this time zone might not match the time zone of users creating or receiving the report.
If you want to use a specific time zone, save the dashboard with a fixed time zone instead of **Browser Time**
Each dashboard's time zone setting is visible in the [time range controls](ref:time-range-controls).
### 3. Email settings
At this step, configure the report email:
<!-- vale Grafana.GoogleLyHyphens = NO -->
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Email subject | If you leave this field empty, the report name is used as the email subject line. |
| Message | The body of the message in the report email. |
| Reply-to-email address | The address that appears in the **Reply to** field of the email. |
| Include a dashboard link | Include links to the dashboards in the report email. |
| Embed dashboard image | The report email is sent with an images of the dashboards embedded in it so recipients see them at a glance. |
<!-- prettier-ignore-end -->
<!-- vale Grafana.GoogleLyHyphens = YES -->
### 4. Recipients
Enter the email addresses of the people or teams that you want to receive the report, separated by commas or semicolons.
### 5. Attachments
At this step, select one or more report attachment options.
You can select multiple options, but you must select _at least one_:
- **Attach the report as a PDF** - Attach the report as one PDF file.
- **[Attach a separate PDF of table data](#table-data-in-pdf)** - Attach a separate PDF file to the report email for each table panel on the selected dashboard. Public preview only.
- **Attach a CSV file of table panel data** - Attach a CSV file to the report email for each table panel on the selected dashboard.
#### PDF format
If you selected a PDF attachment, configure the following formatting options:
<!-- prettier-ignore-start -->
| Option | Description |
|---------------------------------|-------------------------------------------------------------------------------------------------|
| Orientation | Set the report orientation in **Portrait** or **Landscape**. Refer to the [Layout and orientation table](#layout-and-orientation) to see examples. |
| Layout | Select one of the following:<ul><li>**Simple** - Renders each panel as full-width across the PDF.</li><li>**Grid** - Renders the PDF with the same panel arrangement and width as the source dashboard.</li></ul>Refer to the [Layout and orientation table](#layout-and-orientation) to see examples. |
| Zoom | Zoom in to enlarge text in your PDF or zoom out to see more data (like table columns) per panel. |
| Combine all dashboard PDFs in one file | Click the checkbox if you want to generate one PDF file for all the dashboards included in the report. This option is only displayed if there are multiple dashboards in the report. |
| Show template variables | Click the checkbox to show dashboard variables. This option is only displayed if the report contains variables. |
| [Include table data as PDF appendix](#table-data-in-pdf) | Add an appendix of the dashboard table data to the report PDF. This is useful when there's more data in your table visualization than can be shown in the dashboard PDF. _Public preview only._ |
<!-- prettier-ignore-end -->
##### Layout and orientation
<!-- prettier-ignore-start -->
| Layout | Orientation | Description | Preview |
| ------ | ----------- | --------------------------------------------------------------------------------------------------------- | ------------ |
| Simple | Portrait | Generates an A4 page in portrait mode with three panels per page. | {{< figure src="/static/img/docs/enterprise/reports_portrait_preview.png" max-width="500px" alt="Simple layout in portrait" >}} |
| Simple | Landscape | Generates an A4 page in landscape mode with a single panel per page. | {{< figure src="/static/img/docs/enterprise/reports_landscape_preview.png" max-width="500px" alt="Simple layout in landscape" >}} |
| Grid | Portrait | Generates an A4 page in portrait mode with panels arranged in the same way as at the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_portrait_preview.png" max-width="500px" alt="Grid layout in portrait" >}} |
| Grid | Landscape | Generates an A4 page in landscape mode with panels arranged in the same way as in the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_landscape_preview.png" max-width="500px" alt="Grid layout in landscape" >}} |
<!-- prettier-ignore-end -->
#### Table data in PDF
{{< admonition type="note" >}}
Available in public preview (`pdfTables` feature toggle) in [Grafana Enterprise](ref:grafana-enterprise) v10.3+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, as well as in [Grafana Cloud](/docs/grafana-cloud/).
{{< /admonition >}}
When there's more data in your table visualizations than can be shown in the dashboard PDF, you can select one of these two options to access all table visualization data as PDF in your reports:
- **Include table data as PDF appendix** - Adds an appendix to the dashboard PDF.
- **Attach a separate PDF of table data** - Generates a separate PDF file.
## Send a report using the API
You can send reports programmatically with the [send report](ref:send-report) endpoint using the HTTP API.
## Manage reports
You can view and manage all your reports, and create new ones, on the **Reporting** page:
{{< figure src="/media/docs/grafana/dashboards/screenshot-reporting-page-v12.0.png" max-width="750px" alt="The Reporting page" >}}
Alternatively, from any dashboard you can view and manage any reports generated from that dashboard, as well as create a new report
You can also navigate to the list of all reports from the dashboard-specific list:
{{< figure src="/media/docs/grafana/dashboards/screenshot-report-drawer-v12.0.png" max-width="750px" alt="The open Report schedule drawer with an existing report" >}}
### Edit reports
To edit a report, follow these steps:
1. Do one of the following:
- In the main menu, click **Dashboards > Reporting**.
- Navigate to the dashboard from which the report was generated and click **Share > Schedule report**.
1. Click the row of the report you want to update.
1. Make the necessary changes.
1. Click **Update report**.
1. Click the **x** at the top of the drawer to close it.
### Pause or resume reports
You can pause and resume sending reports from the report list view.
To do this, follow these steps:
1. Do one of the following:
- In the main menu, click **Dashboards > Reporting**.
- Navigate to the dashboard from which the report was generated and click **Share > Schedule report**.
1. On the row of the report you want to update, do one of the following:
- Click the pause icon - The report won't be sent according to its schedule until it's resumed.
- Click the resume icon - The report resumes on its previous schedule.
You can also pause or resume a report from **Update report** drawer.
### Delete reports
To delete a report, follow these steps:
1. Do one of the following:
- In the main menu, click **Dashboards > Reporting**.
- Navigate to the dashboard from which the report was generated and click **Share > Schedule report**.
1. On the row of the report you want to update, click the trash can icon.
1. Click **Delete** to confirm.
You can also delete a report from **Update report** drawer.
Deleting a report is irreversible.
## Troubleshoot Reporting
To troubleshoot and get more log information, enable debug logging in the configuration file.
Refer to the [log filters configuration documentation](ref:log-filters) for more information.
```bash
[log]
filters = rendering:debug,report.api:debug,report.render:debug,report.scheduler:debug,report.sender:debug,report.service:debug
```
docs/sources/visualizations/dashboards/create-reports/report-settings/index.md
+75
View File
@@ -0,0 +1,75 @@
---
keywords:
- grafana
- reporting
- settings
labels:
products:
- cloud
- enterprise
menuTitle: Settings
title: Reporting settings
description: Manage organizational Reporting settings
weight: 700
refs:
change-ui-theme:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/organization-preferences/#change-grafana-ui-theme
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/organization-preferences/#change-grafana-ui-theme
aliases:
- ../../../dashboards/create-reports/report-settings/ # /docs/grafana/next/dashboards/create-reports/report-settings/
---
# Reporting settings
You can configure organization-wide report settings and branding options in **Dashboards > Reporting**.
These settings are applied to all the reports for the current organization.
To access the settings, go to **Dashboards > Reporting** and click the **Report settings** button.
This opens the **Report template settings** drawer, where you can make changes.
{{< admonition type="note" >}}
The redesigned reporting feature, including the report settings drawer, is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. To use this feature, enable the `newShareReportDrawer` feature toggle in your Grafana configuration file or, for Grafana Cloud, contact Support.
{{< /admonition >}}
You can also navigate these settings from the **Schedule report** drawer that opens when you create a report directly from a dashboard.
## Attachment settings
The options in this section control the branding and theming of the report attachments.
### PDF
- **Company logo** - Company logo displayed in the report PDF.
Configure it by specifying a URL or uploading a file.
The maximum file size is 16 MB.
Defaults to the Grafana logo.
- **Theme** - Theme of the PDF attached to the report.
The selected theme is also applied to the PDFs generated when you click **Preview PDF** during report creation or select the **Export as PDF** option on a dashboard.
If **Current** is selected, the PDF in the report is in the instance theme of the report creator, but the preview and exported PDFs are in the user's instance theme.
Defaults to **Light**.
### Embedded Image
- **Theme** - Theme of the dashboard image embedded in the email.
If **Current** is selected, the image in the report is in the instance theme of the report creator. If the report creator doesn't have a theme set, then the team, organization, or server theme is used. For more information refer to [Change Grafana UI theme](ref:change-ui-theme).
Defaults to **Dark**.
<!-- vale Grafana.WordList = NO -->
## Email branding
<!-- vale Grafana.WordList = YES -->
- **Company logo** - Company logo displayed in the report email. Configure it by specifying a URL or uploading a file. The maximum file size is 16 MB. Defaults to the Grafana logo.
- **Email footer** - Toggle to enable the report email footer. Select **Sent by** or **None**.
- **Footer link text** - Text of the link in the report email footer. Defaults to `Grafana`.
- **Footer link URL** - Link of the report email footer.
Currently, the API does not allow for the simultaneous upload of files with identical names for both the email logo and report logo.
You can still upload the same file for each logo separately in two distinct steps.
docs/sources/visualizations/dashboards/manage-dashboards/index.md
+127
View File
@@ -0,0 +1,127 @@
---
aliases:
- ../../panels/working-with-panels/organize-dashboard/ # /docs/grafana/next/panels/working-with-panels/organize-dashboard/
- ../../reference/dashboard_folders/ # /docs/grafana/next/reference/dashboard_folders/
- ../../dashboards/dashboard-folders/ # /docs/grafana/next/dashboards/dashboard-folders/
- ../../dashboards/dashboard-manage/ # /docs/grafana/next/dashboards/dashboard-manage/
- ../../dashboards/manage-dashboards/ # /docs/grafana/next/dashboards/manage-dashboards/
canonical: https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/
keywords:
- grafana
- dashboard
- dashboard folders
- folder
- folders
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Manage dashboards
title: Manage dashboards
description: Learn about dashboard management and generative AI features for dashboards
weight: 300
refs:
build-dashboards:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/
dashboard-permissions:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/#dashboard-permissions
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/#dashboard-permissions
grafana-llm-plugin-documentation:
- pattern: /docs/grafana/
destination: /docs/grafana-cloud/alerting-and-irm/machine-learning/configure/llm-plugin/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/machine-learning/configure/llm-plugin/
---
# Manage dashboards
On the **Dashboards** page, you can perform dashboard management tasks such as:
- [Browsing](#browse-dashboards) and [creating](#create-a-dashboard-folder) dashboard folders
- [Managing folder permissions](#folder-permissions)
- [Adding generative AI features to dashboards](#set-up-generative-ai-features-for-dashboards)
For more information about creating dashboards, refer to [Build dashboards](ref:build-dashboards).
## Browse dashboards
On the **Dashboards** page, you can browse and manage folders and dashboards. This includes the options to:
- Create folders and dashboards.
- Move dashboards between folders.
- Delete multiple dashboards and folders.
- Navigate to a folder.
- Manage folder permissions. For more information, refer to [Dashboard permissions](ref:dashboard-permissions).
The page lists all the dashboards to which you have access, grouped into folders. Dashboards without a folder are displayed at the top level alongside folders.
### Shared with me
The **Shared with me** section displays folders and dashboards that are directly shared with you. These folders and dashboards aren't shown in the main list because you don't have access to one or more of their parent folders.
If you have permission to view all folders, you won't see a **Shared with me**.
## Create a dashboard folder
Folders help you organize and group dashboards, which is useful when you have many dashboards or multiple teams using the same Grafana instance.
> **Before you begin:** Ensure you have organization Editor permissions or greater to create root level folders or Edit or Admin access to a parent folder to create subfolders. For more information about dashboard permissions, refer to [Dashboard permissions](ref:dashboard-permissions).
**To create a dashboard folder:**
1. Click **Dashboards** in the primary menu.
1. Do one of the following:
- On the **Dashboards** page, click **New** and select **New folder** in the drop-down.
- Click an existing folder and on the folder’s page, click **New** and select **New folder** in the drop-down.
1. Enter a unique name.
Folder names can't include underscores (\_) or percentage signs (%), as it interferes with the search functionality.
Also, alerts can't be placed in folders with slashes (\ /) in the name. If you want to place alerts in the folder, don't use slashes in the folder name.
1. Click **Create**
When you nest folders, you can do so up to four levels deep.
When you save a dashboard, you can optionally select a folder to save the dashboard in.
**To edit the name of a folder:**
1. Click **Dashboards** in the primary menu.
1. Navigate to the folder by selecting it in the list, or searching for it.
1. Click the **Edit title** icon (pencil) in the header and update the name of the folder.
The new folder name is automatically saved.
### Folder permissions
You can assign permissions to a folder. Dashboards in the folder inherit any permissions that you've assigned to the folder. You can assign permissions to organization roles, teams, and users.
**To modify permissions for a folder:**
1. Click **Dashboards** in the primary menu.
1. Navigate to the folder by selecting it in the list, or searching for it.
1. On the folder's page, click **Folder actions** and select **Manage permissions** in the drop-down.
1. Update the permissions as desired.
Changes are saved automatically.
For more information about dashboard permissions, refer to [Dashboard permissions](ref:dashboard-permissions).
## Set up generative AI features for dashboards
You can use generative AI to help you with the following tasks:
- **Generate panel and dashboard titles and descriptions**: Generate a title and description based on the data you’ve added for your panel or dashboard. This is useful when you want to visualize your data quickly and don’t want to spend time coming up with a title or description.
- **Generate dashboard save changes summary**: Generate a summary of the changes you’ve made to a dashboard when you save it. This is great for easily tracking the history of a dashboard.
To access these features, install and configure Grafana’s Large Language Model (LLM) app plugin. For more information, refer to the [Grafana LLM plugin documentation](ref:grafana-llm-plugin-documentation).
When enabled, the **✨ Auto generate** option displays next to the **Title** and **Description** fields in your panels and dashboards, or when you press the **Save** button.
docs/sources/visualizations/dashboards/search-dashboards/index.md
+127
View File
@@ -0,0 +1,127 @@
---
description: Learn how to search for Grafana dashboards and folders
keywords:
- search
- dashboard
- folder
labels:
products:
- cloud
- enterprise
- oss
menutitle: Search dashboards
title: Search dashboards and folders
weight: 400
refs:
service-accounts:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/account-management/authentication-and-permissions/service-accounts/
config-file:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#configuration-file-location
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#configuration-file-location
feature-toggles:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#feature_toggles
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#feature_toggles
aliases:
- ../../dashboards/search-dashboards/ # /docs/grafana/next/dashboards/search-dashboards/
---
# Search dashboards and folders
You can search for dashboards and dashboard folders by name.
When you search for dashboards, you can also do it by panel title. Whether you search by name or panel title, the system returns all dashboards available within the Grafana instance, even if you do not have permission to view the contents of the dashboard.
## Search by name
Begin typing any part of the dashboard or folder name in the search bar. The search returns results for any partial string match in real-time, as you type.
The search is:
- Real-time
- _Not_ case sensitive
- Functional across stored _and_ file based dashboards and folders.
{{< admonition type="note" >}}
You can use your keyboard arrow keys to navigate the results and press `Enter` to open the selected dashboard or folder.
{{< /admonition >}}
The following images show:
Searching by dashboard name from the **Dashboards** page.
{{< figure src="/media/docs/grafana/dashboards/search-for-dashboard.png" width="700px" >}}
Searching by folder name from the **Dashboards** page.
{{< figure src="/media/docs/grafana/dashboards/search-folder.png" width="700px" >}}
Searching by dashboard name inside a folder.
{{< figure src="/media/docs/grafana/dashboards/search-in-folder.png" width="700px" >}}
{{< admonition type="note" >}}
When you search within a folder, its subfolders are not part of the results returned. You need to be on the **Dashboards** page (or the root level) to search for subfolders by name.
{{< /admonition >}}
## Search dashboards using panel title
You can search for a dashboard by the title of a panel that appears in a dashboard.
If a panel's title matches your search query, the dashboard appears in the search results.
This feature is available by default in Grafana Cloud and in Grafana OSS v9.1 and higher, you access this feature by enabling the `panelTitleSearch` feature toggle.
For more information about enabling panel title search, refer to [Enable the panelTitleSearch feature toggle.](#enable-the-paneltitlesearch-feature-toggle)
The following image shows the search results when you search using panel title.
{{< figure src="/static/img/docs/v91/dashboard-features/search-by-panel-title.png" width="700px" >}}
### Enable the panelTitleSearch feature toggle
Complete the following steps to enable the `panelTitleSearch` feature toggle.
**Before you begin:**
- If you are running Grafana Enterprise with RBAC, enable [service accounts](ref:service-accounts).
**To enable the panelTitleSearch feature toggle:**
1. Open the Grafana [configuration file](ref:config-file).
1. Locate the [feature_toggles](ref:feature-toggles) section.
1. Add the following parameter to the `feature_toggles` section:
```
[feature_toggles]
# enable features, separated by spaces
enable = panelTitleSearch
```
1. Save your changes and restart the Grafana server.
## Filter dashboard search results by tag(s)
Tags are a great way to organize your dashboards, especially as the number of dashboards grow. You can add and manage tags in dashboard `Settings`.
When you select multiple tags, Grafana shows dashboards that include all selected tags.
To filter dashboard search result by a tag, complete one of the following steps:
- To filter dashboard search results by tag, click a tag that appears in the right column of the search results.
You can continue filtering by clicking additional tags.
- To see a list of all available tags, click the **Filter by tags** dropdown menu and select a tag.
All tags will be shown, and when you select a tag, the dashboard search will be instantly filtered.
{{< admonition type="note" >}}
When using only a keyboard, press the `tab` key and navigate to the **Filter by tag** drop-down menu, press the down arrow key `▼` to activate the menu and locate a tag, and press `Enter` to select the tag.
{{< /admonition >}}
docs/sources/visualizations/dashboards/share-dashboards-panels/_index.md
+369
View File
@@ -0,0 +1,369 @@
---
aliases:
- ../../reference/share_dashboard/ # /docs/grafana/next/reference/share_dashboard/
- ../../reference/share_panel/ # /docs/grafana/next/reference/share_panel/
- ../../share-dashboards-panels/ # /docs/grafana/next/share-dashboards-panels/
- ../../sharing/ # /docs/grafana/next/sharing/
- ../../sharing/playlists/ # /docs/grafana/next/sharing/playlists/
- ../../sharing/share-dashboard/ # /docs/grafana/next/sharing/share-dashboard/
- ../../sharing/share-panel/ # /docs/grafana/next/sharing/share-panel/
- ../../dashboards/share-dashboard/ # /docs/grafana/next/dashboards/share-dashboard/
- ../../dashboards/share-dashboards-panels/ # /docs/grafana/next/dashboards/share-dashboards-panels/
keywords:
- grafana
- dashboard
- documentation
- share
- panel
- reporting
- export
- pdf
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Sharing
title: Share dashboards and panels
description: Share Grafana dashboards and panels within your organization and publicly
weight: 650
refs:
image-rendering:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/
grafana-enterprise:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
shared-dashboards:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/share-dashboards-panels/shared-dashboards/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/share-dashboards-panels/shared-dashboards/
configure-report:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/create-reports/#create-a-report
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/create-reports/#create-a-report
image-rendering-config:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#configuration
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#configuration
max-width:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#viewport-maximum-width
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#viewport-maximum-width
max-height:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#viewport-maximum-height
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#viewport-maximum-height
max-scale:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#maximum-device-scale-factor
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/image-rendering/#maximum-device-scale-factor
---
# Share dashboards and panels
Grafana enables you to share dashboards and panels with other users within your organization and in certain situations, publicly on the web. You can share using:
- Direct links with users in and outside of your organization
- Snapshots
- Embeds
- PDFs
- JSON files
- Reports
- Library panels
You must have an authorized viewer permission to see an image rendered by a direct link. The same permission is also required to view embedded links unless you have anonymous access permission enabled for your Grafana instance.
{{< admonition type="note" >}}
Anonymous access permission is not available in Grafana Cloud. This feature is only supported for Grafana Enterprise and Grafana Open Source.
{{< /admonition >}}
## Share dashboards {#share-a-dashboard}
You can share dashboards in the following ways:
- [Internally with a link](#share-an-internal-link)
- [Externally with anyone or specific people](#share-an-external-link)
- [As a report](#schedule-a-report)
- [As a snapshot](#share-a-snapshot)
- [As a PDF export](#export-a-dashboard-as-pdf)
- [As a JSON file export](#export-a-dashboard-as-json)
When you share a dashboard externally as a link or by email, those dashboards are included in a list of your shared dashboards. To view the list and manage these dashboards, navigate to **Dashboards > Shared dashboards**.
{{< admonition type="note" >}}
If you change a dashboard, ensure that you save the changes before sharing.
{{< /admonition >}}
### Share an internal link
To share a customized, direct link to your dashboard within your organization, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Share internally**.
1. (Optional) In the **Share internally** drawer that opens, set the following options:
- **Lock time range** - Change the current relative time range to an absolute time range. This option is enabled by default.
- **Shorten link** - Shorten the dashboard link. This option is enabled by default.
1. Select the theme for the dashboard. Choose from **Current**, **Dark**, or **Light**.
1. Click **Copy link**.
1. Send the copied link to a Grafana user with authorization to view the link.
1. Click the **X** at the top-right corner to close the share drawer.
#### Quick-share an internal link
Once you've customized an internal link, you can share it quickly by following these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** button, not the drop-down list icon, to copy a shortened link.
This link has any customizations, like time range locking or theme, that you've previously set. These are stored in the browser scope.
### Share an external link
Externally shared 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.
Learn how to configure and manage externally shared dashboards in [Externally shared dashboards](ref:shared-dashboards).
### Schedule a report
{{< admonition type="note" >}}
This feature is only available on Grafana Enterprise.
{{< /admonition >}}
To share your dashboard as a report, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Schedule a report**.
1. [Configure the report](ref:configure-report).
1. Depending on your schedule settings, you'll have different options at this step. Click either **Schedule send** or **Send now**.
You can also save the report as a draft.
To manage your reports, navigate to **Dashboards > Reporting > Reports**.
### Share a snapshot
A dashboard snapshot publicly shares a dashboard while removing sensitive data such as queries and panel links, leaving only visible metrics and series names. Anyone with the link can access the snapshot.
You can publish snapshots to your local instance or to [snapshots.raintank.io](http://snapshots.raintank.io). The latter is a free service provided by Grafana Labs that enables you to publish dashboard snapshots to an external Grafana instance. Anyone with the link can view it. You can set an expiration time if you want the snapshot removed after a certain time period.
{{< admonition type=note >}}
The snapshots.raintank.io option is disabled by default in Grafana Cloud. You can update [your config file](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#external_enabled) to enable this functionality.
{{< /admonition >}}
To see the other snapshots shared from your organization, navigate to **Dashboards > Snapshots** in the main menu.
To share your dashboard with anyone as a snapshot, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Share snapshot**.
1. In the **Share snapshot** drawer that opens, enter a descriptive title for the snapshot in the **Snapshot name** field.
1. Select one of the following expiration options for the snapshot:
- **1 Hour**
- **1 Day**
- **1 Week**
- **Never**
1. Click **Publish snapshot** or **Publish to snapshots.raintank.io**.
Grafana generates the link of the snapshot. Note that you can't publish dashboard snapshots containing custom panels to snapshot.raintank.io.
1. Click **Copy link**, and share it either within your organization or publicly on the web.
1. Click the **X** at the top-right corner to close the share drawer.
#### Delete a snapshot
To delete existing snapshots, follow these steps:
1. Navigate to **Dashboards > Snapshots** in the main menu.
1. To confirm which snapshot you're about to delete, click **View** on the snapshot row.
The URLs for panel and dashboard snapshots from the same dashboard look similar and viewing them first can help you distinguish them.
1. Click the red **x** next to the snapshot that you want to delete.
The snapshot is immediately deleted. You might need to clear your browser cache or use a private or incognito browser to confirm this.
## Export dashboards
In addition to sharing dashboards as links, reports, and snapshots, you can export them as PDFs or JSON files.
### Export a dashboard as PDF
{{< admonition type="note" >}}
This feature is only available on Grafana Enterprise.
{{< /admonition >}}
To export a dashboard in its current state as a PDF, follow these steps:
1. Click **Dashboards** in the main menu.
1. Open the dashboard you want to export.
1. Click the **Export** drop-down in the top-right corner and select **Export as PDF**.
1. In the **Export dashboard PDF** drawer that opens, select either **Landscape** or **Portrait** for the PDF orientation.
1. Select either **Grid** or **Simple** for the PDF layout.
1. Set the **Zoom** level; zoom in to enlarge text, or zoom out to see more data (like table columns) per panel.
1. Click **Generate PDF**.
The PDF opens in another tab where you can download it.
1. Click the **X** at the top-right corner to close the share drawer.
### Export a dashboard as JSON
Export a Grafana JSON file that contains everything you need, including layout, variables, styles, data sources, queries, and so on, so that you can later import the dashboard. To export a JSON file, follow these steps:
1. Click **Dashboards** in the main menu.
1. Open the dashboard you want to export.
1. Click the **Export** drop-down list in the top-right corner and select **Export as JSON**.
The **Export dashboard JSON** drawer opens.
1. Toggle the **Export the dashboard to use in another instance** switch to generate the JSON with a different data source UID.
1. Click **Download file** or **Copy to clipboard**.
1. Click the **X** at the top-right corner to close the share drawer.
## Share panels {#share-a-panel}
You can share a panels in the following ways:
- [Internally with a link](#share-an-internal-link)
- [As an embed](#share-an-embed)
- [As a snapshot](#panel-snapshot)
{{< admonition type="note" >}}
If you change a panel, ensure that you save the changes before sharing.
{{< /admonition >}}
### Share an internal link
To share a personalized, direct link to your panel within your organization, follow these steps:
1. Hover over any part of the panel you want to share to display the actions menu on the top right corner.
1. Click the menu and select **Share link**.
1. (Optional) In the **Link settings** drawer that opens, set the following options:
- **Lock time range** - Change the current relative time range to an absolute time range. This option is enabled by default.
- **Shorten link** - Shorten the panel link. This option is disabled by default.
1. Select the theme for the dashboard. Choose from **Current**, **Dark**, or **Light**.
1. Click **Copy link**.
1. Send the copied link to a Grafana user with authorization to view it.
1. (Optional) To [generate an image of the panel as a PNG file](ref:image-rendering), customize the image settings:
- **Width** - In pixels. The default is 1000.
- **Height** - In pixels. The default is 500.
- **Scale factor** - The default is 1.
There are maximums for [width](ref:max-width), [height](ref:max-height), and [scale factor](ref:max-scale) in the image renderer configuration that you can customize if needed.
1. (Optional) Click **Generate image** to see a preview of the panel image.
1. (Optional) Click **Download image**.
1. Send the copied image to a Grafana user with authorization to view it.
1. Click the **X** at the top-right corner to close the share drawer.
#### Query string parameters for server-side rendered images
When you click **Generate image** in the panel link settings, Grafana generates a PNG image of the panel with the following default parameters:
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| width | Width in pixels. Default is 1000. |
| height | Height in pixels. Default is 500. |
| tz | Timezone in the format `UTC%2BHH%3AMM` where HH and MM are offset in hours and minutes after UTC. |
| timeout | Number of seconds. The timeout can be increased if the query for the panel needs more than the default 30 seconds. |
| scale | Numeric value to configure device scale factor. Default is 1. Use a higher value to produce more detailed images (higher DPI). |
You can also update these parameters in the [image rendering configuration](ref:image-rendering-config).
The following example shows a link to a server-side rendered PNG:
```bash
https://play.grafana.org/render/d-solo/ktMs4D6Mk?from=2024-09-03T11:55:44.442Z&to=2024-09-03T17:55:44.442Z&panelId=panel-13&__feature.dashboardSceneSolo&width=1000&height=500&tz=UTC
```
### Share an embed
You can share a panel by embedding it on another website using an iframe. Users must be signed into Grafana to view the panel unless you have anonymous access permission enabled for your Grafana instance.
{{< admonition type="note" >}}
Panel embedding and anonymous access permissions are not available in Grafana Cloud, even for panels in [externally shared dashboards](ref:shared-dashboards). These capabilities are only supported in Grafana Enterprise and Grafana Open Source.
{{< /admonition >}}
To create a panel that can be embedded, follow these steps:
1. Hover over any part of the panel you want to share to display the actions menu on the top-right corner.
1. Click the menu and select **Share embed**.
The **Share embed** drawer opens.
1. (Optional) Toggle the **Lock time range** switch to set whether the panel uses the current relative time range or an absolute time range. This option is enabled by default.
1. Select the theme for the dashboard. Choose from **Current**, **Dark**, or **Light**.
1. (Optional) Make any changes to the HTML that you need.
1. Click **Copy to clipboard**.
1. Paste the HTML code into your website code.
1. Click the **X** at the top-right corner to close the share drawer.
Here's an example of what the HTML code might look like:
```html
<iframe
src="https://snapshots.raintank.io/dashboard-solo/snapshot/y7zwi2bZ7FcoTlB93WN7yWO4aMiz3pZb?from=1493369923321&to=1493377123321&panelId=4"
width="650"
height="300"
frameborder="0"
></iframe>
```
The result is an interactive Grafana visualization embedded in an iframe.
### Share a snapshot {#panel-snapshot}
A panel snapshot shares an interactive panel publicly while removing sensitive data such as queries and panel links, leaving only visible metrics and series names. Anyone with the link can access the snapshot.
You can publish snapshots to your local instance or to [snapshots.raintank.io](http://snapshots.raintank.io). The latter is a free service provided by Grafana Labs that enables you to publish dashboard snapshots to an external Grafana instance. Anyone with the link can view it. You can set an expiration time if you want the snapshot removed after a certain time period.
{{< admonition type=note >}}
The snapshots.raintank.io option is disabled by default in Grafana Cloud. You can update [your config file](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#external_enabled) to enable this functionality.
{{< /admonition >}}
To see the other snapshots shared from your organization, navigate to **Dashboards > Snapshots** in the main menu.
To share your panel with anyone as a snapshot, follow these steps:
1. Hover over any part of the panel you want to share to display the actions menu on the top-right corner.
1. Click the menu and select **Share snapshot**.
1. In the **Share snapshot** drawer that opens, enter a descriptive title for the snapshot in the **Snapshot name** field.
1. Select one of the following expiration options for the snapshot:
- **1 Hour**
- **1 Day**
- **1 Week**
- **Never**
1. Click **Publish snapshot** or **Publish to snapshots.raintank.io**.
Grafana generates the link of the snapshot. Note that you can't publish snapshots that include custom panels to snapshot.raintank.io.
1. Click **Copy link**, and share it either within your organization or publicly on the web.
1. Click the **X** at the top-right corner to close the share drawer.
#### Delete a snapshot
To delete existing snapshots, follow these steps:
1. Navigate to **Dashboards > Snapshots** in the main menu.
1. To confirm which snapshot you're about to delete, click **View** on the snapshot row.
The URLs for panel and dashboard snapshots from the same dashboard look similar and viewing them first can help you distinguish them.
1. Click the red **x** next to the snapshot URL that you want to delete.
The snapshot is immediately deleted. You may need to clear your browser cache or use a private or incognito browser to confirm this.
docs/sources/visualizations/dashboards/share-dashboards-panels/shared-dashboards/index.md
+314
View File
@@ -0,0 +1,314 @@
---
aliases:
- ../../../dashboards/dashboard-public/ # /docs/grafana/next/dashboards/dashboard-public/
- ../../../dashboards/share-dashboards-panels/shared-dashboards/ # /docs/grafana/next/dashboards/share-dashboards-panels/shared-dashboards/
labels:
products:
- cloud
- enterprise
- oss
title: Externally shared dashboards
menuTitle: Shared dashboards
description: Make your Grafana dashboards externally shared and share them with anyone
weight: 8
refs:
dashboard-sharing:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/share-dashboards-panels/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/share-dashboards-panels/
custom-branding:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/configure-custom-branding/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/configure-custom-branding/
dashboard-insights-documentation:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/assess-dashboard-usage/#dashboard-insights
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/assess-dashboard-usage/
caching:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/#query-and-resource-caching
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/#query-and-resource-caching
grafana-enterprise:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/
---
# Externally shared dashboards
{{< admonition type="note" >}}
This feature was previously called **Public dashboards**.
{{< /admonition >}}
Externally shared 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.
If you change a dashboard, ensure that you save the changes before sharing.
{{< admonition type="warning" >}}
Sharing your dashboard externally could result in a large number of queries to the data sources used by your dashboard.
This can be mitigated by using the Enterprise [caching](ref:caching) and/or rate limiting features.
{{< /admonition >}}
## Shared dashboards list
You can see a list of all your externally shared dashboards in one place by navigating to **Dashboards > Shared dashboards**. For each dashboard in the list, the page displays:
- Link to view the externally shared version of the dashboard
- Link to the shared dashboard configuration
- Options to pause or revoke access to the external dashboard
You can also click the name of the dashboard to navigate to the dashboard internally.
## Important notes about sharing your dashboard externally
- Anyone with the URL can access the dashboard.
- Externally shared dashboards are read-only.
- Arbitrary queries **cannot** be run against your data sources through externally shared dashboards. Externally shared dashboards can only execute the queries stored on the original dashboard.
## Share externally with specific people
{{< admonition type="note">}}
This feature was previously called **email sharing**.
Available in [Grafana Enterprise](ref:grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud).
{{< /admonition >}}
<!-- {{< docs/private-preview product="Sharing externally with specific people" >}}-->
{{< admonition type="note" >}}
Sharing externally with specific people is currently in [private preview](https://grafana.com/docs/release-life-cycle/#private-preview). Please contact support to have this feature enabled.
This feature will incur a cost once it is promoted to general availability.
{{< /admonition >}}
To share a dashboard with specific external users, you can send them a link by email. Use this option when you only want to share your dashboard with specific people. When you share dashboards by email, recipients receive a one-time use link that's valid for **one hour**. Once the link is used, the viewer has access to the shared dashboard for **30 days**.
<!--When you share a dashboard with an email link, your organization is billed per user, regardless of how many dashboards are shared. Grafana bills monthly per user until access is revoked.-->
To share a dashboard with specific people, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Share externally**.
The **Share externally** drawer opens.
1. In the **Link access** drop-down list, select **Only specific people**.
1. Click the checkbox confirming that you understand payment is required to add users.
1. Click **Accept**.
1. In the **Invite** field, enter the email address of the person you want to invite and click **Invite** and repeat this process for all the people you want to invite.
You can only invite one person at a time.
1. (Optional) Set the following options:
- **Enable time range** - Allow people accessing the link to change the time range. This configuration screen shows the default time range of the dashboard.
- **Display annotations** - Allow people accessing the link to view the dashboard annotations.
1. (Optional) Click **Copy external link** and send the copied URL to any external user.
1. Click the **X** at the top-right corner to close the share drawer.
Once you've shared a dashboard externally, a **Public** label is displayed in the header of the dashboard.
### Viewers requesting access
If a viewer without access tries to navigate to the shared dashboard, they'll be asked to request access by providing their email. They'll receive an email with a new one-time use link if the email they provided has already been invited to view the shared dashboard and hasn't been revoked.
### Revoke access for a viewer
You can revoke access to the entire dashboard using the steps in [Update access to an external dashboard link](#update-access-to-an-external-dashboard-link), but you can also revoke access to the dashboard for specific people.
To revoke access for a viewer, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Share externally**.
1. In the **Share externally** drawer that opens, click the menu icon (three dots) next to the email address of the viewer for whom you'd like to revoke access.
1. Click **Revoke access**.
1. Click the **X** at the top-right corner to close the share drawer.
The viewer immediately no longer has access to the dashboard, nor can they use any existing one-time use links they may have.
### Re-invite a viewer
To re-invite a viewer, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Share externally**.
1. In the **Share externally** drawer that opens, click the menu icon (three dots) next to the email address of the viewer you'd like to invite again.
1. Click **Resend invite**.
1. Click the **X** at the top-right corner to close the share drawer.
The viewer receives an email with a new one-time use link. This invalidates all previously issued links for that viewer.
### View shared dashboard users
To see a list of users who have accessed your externally shared dashboard by way of an emailed link, follow these steps:
1. Click **Administration** in in the main menu.
1. Select **Users and access** > **Users**.
1. On the **Users** page, click the **Shared dashboard users** tab.
On this screen, you can see:
- The earliest time a user has been active in a dashboard
- When they last accessed a shared dashboard
- The dashboards they have access to
- Their role
You can also revoke a user's access to all shared dashboards on from this tab.
### Access limitations
One-time use links use browser cookies, so when a viewer is granted access through one of these links, they'll only have access on the browser they used to claim the link.
A single viewer can't generate multiple valid one-time use links for a dashboard. When a new one-time use link is issued for a viewer, all previous ones are invalidated.
If a Grafana user has read access to the parent dashboard, they can view the externally shared dashboard without needing to have access granted.
## Share externally to anyone with a link
To share your dashboard so that anyone with the link can access it, follow these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Share externally**.
The **Share externally** drawer opens.
1. In the **Link access** drop-down list, select **Anyone with the link**.
1. Click the checkbox confirming that you understand the entire dashboard will be public.
1. Click **Accept**.
1. (Optional) Set the following options:
- **Enable time range** - Allow people accessing the link to change the time range. This configuration screen shows the default time range of the dashboard.
- **Display annotations** - Allow people accessing the link to view the dashboard annotations.
1. Click the **X** at the top-right corner to close the share drawer.
Now anyone with the link can access the dashboard until you pause or revoke access to it.
Once you've shared a dashboard externally, a **Public** label is displayed in the header of the dashboard.
### Update access to an external dashboard link
You can update the access to externally shared dashboard links by following these steps:
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** drop-down list in the top-right corner and select **Share externally**.
1. In the **Share externally** drawer that opens, do one of the following:
- Click **Pause access** so that people can't access the dashboard, but the link is maintained.
- Click **Resume access** so that people can access the dashboard again.
- Click **Revoke access** so that people can't access the dashboard unless a new external link is generated. Confirm that you want to revoke the link.
1. Click the **X** at the top-right corner to close the share drawer.
## Assess shared dashboard usage
{{< admonition type="note" >}}
Available in [Grafana Enterprise](ref:grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud).
{{< /admonition >}}
You can check usage analytics about your externally shared dashboard by clicking the insights icon in the dashboard header:
![Dashboard insights icon](/media/docs/grafana/dashboards/screenshot-dashboard-insights-icon-11.2.png)
Learn more about the kind of information provided in the [dashboard insights documentation](ref:dashboard-insights-documentation).
## Supported data sources
Externally shared dashboards _should_ work with any data source that has the properties `backend` and `alerting` both set to true in its `plugin.json`. However, this can't always be
guaranteed because plugin developers can override this functionality. The following lists include data sources confirmed to work with externally shared dashboards and data sources that should work, but have not been confirmed as compatible.
### Confirmed
{{< column-list >}}
- ClickHouse
- CloudWatch
- Elasticsearch
- Infinity
- InfluxDB
- Loki
- Microsoft SQL Server
- MongoDB
- MySQL
- Oracle Database
- PostgreSQL
- Prometheus
- Redis
- SQLite
{{< /column-list >}}
### Unsupported
- DynamoDB
- Dynatrace
- Graphite
- Google Sheets
### Unconfirmed
{{< column-list >}}
- Altinity plugin for ClickHouse
- Amazon Athena
- Amazon Redshift
- Amazon Timestream
- Apache Cassandra
- AppDynamics
- Azure Data Explorer Datasource
- Azure Monitor
- CSV
- DB2 Datasource
- Databricks
- Datadog
- Dataset
- Druid
- GitHub
- Google BigQuery
- Grafana for YNAB
- Honeycomb
- Jira
- Mock
- Neo4j Datasource
- New Relic
- OPC UA (Unified Architecture)
- Open Distro for Elasticsearch
- OpenSearch
- OpenTSDB
- Orbit
- SAP HANA®
- Salesforce
- Sentry
- ServiceNow
- Snowflake
- Splunk
- Splunk Infrastructure Monitoring
- Sqlyze data source
- TDengine
- Vertica
- Wavefront
- X-Ray
- kdb+
- simple grpc data source
{{< /column-list >}}
## Limitations
- Panels that use frontend data sources will fail to fetch data.
- Variables and queries including variables are not supported.
- Exemplars will be omitted from the panel.
- Only annotations that query the `-- Grafana --` data source and use the query type `Annotations & Alerts` are supported.
- Organization annotations are not supported.
- Grafana Live and real-time event streams are not supported.
- Library panels are not supported.
- Data sources using Reverse Proxy functionality are not supported.
## Custom branding
If you're a Grafana Enterprise customer, you can use custom branding to change the appearance of an externally shared dashboard footer. For more information, refer to [Custom branding](ref:custom-branding).
docs/sources/visualizations/dashboards/troubleshoot-dashboards/index.md
+59
View File
@@ -0,0 +1,59 @@
---
aliases:
- ../../troubleshooting/troubleshoot-dashboards/ # /docs/grafana/next/troubleshooting/troubleshoot-dashboards/
- ../../reference/timerange/ # /docs/grafana/next/reference/timerange/
- ../../dashboards/troubleshoot-dashboards/ # /docs/grafana/next/dashboards/troubleshoot-dashboards/
canonical: https://grafana.com/docs/grafana/latest/dashboards/troubleshoot-dashboards/
keywords:
- grafana
- dashboard
- troubleshoot
- time range
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Troubleshoot dashboards
title: Troubleshoot dashboards
description: Learn how to troubleshoot common dashboard issues
weight: 1000
---
# Troubleshoot dashboards
Use the following strategies to help you troubleshoot common dashboard problems.
## Dashboard is slow
- Are you trying to render dozens (or hundreds or thousands) of time series on a graph? This can cause the browser to lag. Try using functions like `highestMax` (in Graphite) to reduce the number of returned series.
- Sometimes series names can be very large. This causes larger response sizes. Try using `alias` to reduce the size of the returned series names.
- Are you querying many time series or a long time range? Both of these conditions can cause Grafana or your data source to pull in a lot of data, which may slow the dashboard down. Try reducing one or both of these.
- There could be high load on your network infrastructure. If the slowness isn't consistent, this may be the problem.
## Dashboard refresh rate issues
By default, Grafana queries your data source every 30 seconds. However, setting a low refresh rate on your dashboards puts unnecessary stress on the backend. In many cases, querying this frequently isn't necessary because the data source isn't sending data often enough for there to be changes every 30 seconds.
We recommend the following:
- Only enable auto-refreshing on dashboards, panels, or variables if necessary. Users can refresh their browser manually.
- If you require auto-refreshing, then set the refresh rate to a longer time period that makes sense, such as once a minute, every 10 minutes, or every hour.
- Check the time range of your dashboard. If your dashboard has a longer time range, such as a week, then you really don't need automated refreshing and you should disable it.
## Handling or rendering null data is wrong or confusing
Some applications publish data intermittently; for example, they only post a metric when an event occurs. By default, Grafana graphs connect lines between the data points, but this can be deceptive.
The graph in the following image has:
- Points and 3-point radius enabled to highlight where data points are actually present.
- **Connect null values** set to **Always**.
{{< figure src="/static/img/docs/troubleshooting/grafana_null_connected.png" max-width="1200px" alt="Graph with null values connected" >}}
The graph in this next image shows bars instead of lines and has the **No value** option under **Standard options** set to **0**.
{{< figure src="/static/img/docs/troubleshooting/grafana_null_zero.png" max-width="1200px" alt="Graph with null values not connected" >}}
As you can see, there's a significant difference in the visualizations.
docs/sources/visualizations/dashboards/use-dashboards/index.md
+313
View File
@@ -0,0 +1,313 @@
---
aliases:
- ../../reference/search/ # /docs/grafana/next/reference/search/
- ../../dashboards/dashboard-ui/ # /docs/grafana/next/dashboards/dashboard-ui/
- ../../dashboards/dashboard-ui/dashboard-header/ # /docs/grafana/next/dashboards/dashboard-ui/dashboard-header/
- ../../dashboards/dashboard-ui/dashboard-row/ # /docs/grafana/next/dashboards/dashboard-ui/dashboard-row/
- ../../dashboards/search/ # /docs/grafana/next/dashboards/search/
- ../../dashboards/shortcuts/ # /docs/grafana/next/dashboards/shortcuts/
- ../../dashboards/time-range-controls/ # /docs/grafana/next/dashboards/time-range-controls/
- ../../dashboards/use-dashboards/ # /docs/grafana/next/dashboards/use-dashboards/
keywords:
- dashboard
- search
- shortcuts
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Use dashboards
title: Use dashboards
description: Learn about the features of a Grafana dashboard
weight: 100
refs:
dashboard-analytics:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/assess-dashboard-usage/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/assess-dashboard-usage/
generative-ai-features:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/manage-dashboards/#set-up-generative-ai-features-for-dashboards
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/manage-dashboards/#set-up-generative-ai-features-for-dashboards
dashboard-settings:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/modify-dashboard-settings/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/modify-dashboard-settings/
repeating-rows:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/#configure-repeating-rows
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/create-dashboard/#configure-repeating-rows
variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
dashboard-folders:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/manage-dashboards/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/manage-dashboards/
sharing:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/share-dashboards-panels/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/share-dashboards-panels/
dashboard-links:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/manage-dashboard-links/
panel-overview:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/panel-overview/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/panel-overview/
export-dashboards:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/share-dashboards-panels/#export-dashboards
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/share-dashboards-panels/#export-dashboards
add-ad-hoc-filters:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#add-ad-hoc-filters
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#add-ad-hoc-filters
shared-dashboards:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/share-dashboards-panels/shared-dashboards/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/share-dashboards-panels/shared-dashboards/
---
# Use dashboards
This topic provides an overview of dashboard features and shortcuts, and describes how to use dashboard search.
{{< youtube id="vTiIkdDwT-0" >}}
## Dashboard feature overview
The dashboard user interface provides a number of features that you can use to customize the presentation of your data.
The following image and descriptions highlight all dashboard features.
![An annotated image of a dashboard](/media/docs/grafana/dashboards/screenshot-dashboard-annotated-v11.3-2.png)
1. **Dashboard folder** - When you click the dashboard folder name, you can search for other dashboards contained in the folder and perform other [folder management tasks](ref:dashboard-folders).
1. **Dashboard title** - You can create your own dashboard titles or have Grafana create them for you using [generative AI features](ref:generative-ai-features).
1. **Kiosk mode** - Click to display the dashboard on a large screen such as a TV or a kiosk. Kiosk mode hides the main menu, navbar, and dashboard controls. Learn more about kiosk 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/). Press `Esc` to leave kiosk mode.
1. **Mark as favorite** - Mark the dashboard as one of your favorites so it's included in your list of **Starred** dashboards in the main menu.
1. **Public label** - When you [share a dashboard externally](ref:shared-dashboards), it's marked with the **Public** label.
1. **Dashboard insights** - Click to view analytics about your dashboard including information about users, activity, query counts. Learn more about [dashboard analytics](ref:dashboard-analytics).
1. **Edit** - Click to leave view-only mode and enter edit mode, where you can make changes directly to the dashboard and access dashboard settings, as well as several panel editing functions.
1. **Export** - Access [dashboard exporting](ref:export-dashboards) options.
1. **Share dashboard** - Access several [dashboard sharing](ref:sharing) options.
1. **Variables** - Use [variables](ref:variables), including ad hoc filters, to create more interactive and dynamic dashboards.
1. **Dashboard links** - Link to other dashboards, panels, and external websites. Learn more about [dashboard links](ref:dashboard-links).
1. **Current dashboard time range and time picker** - Click to select [relative time range](#relative-time-range) options and set custom [absolute time ranges](#absolute-time-range).
- 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.
1. **Time range zoom out** - Click to zoom out the time range. Learn more about how to use [common time range controls](#common-time-range-controls).
1. **Refresh dashboard** - Click to immediately trigger queries and refresh dashboard data.
1. **Auto refresh control** - Click to select a dashboard auto refresh time interval.
1. **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](ref:repeating-rows) to dynamically create rows based on a template variable.
1. **Dashboard panel** - The [panel](ref:panel-overview) is the primary building block of a dashboard.
1. **Panel legend** - Change series colors as well as y-axis and series visibility directly from the legend.
## Keyboard shortcuts
Grafana has a number of keyboard shortcuts available. Press `?` on your keyboard to display all keyboard shortcuts available in your version of Grafana.
- `Ctrl+S`: Saves the current dashboard.
- `f`: Opens the dashboard finder / search.
- `d+k`: Toggle kiosk mode (hides the menu).
- `d+e`: Expand all rows.
- `d+s`: Dashboard settings.
- `Ctrl+K`: Opens the command palette.
- `Esc`: Exits panel when in full screen view or edit mode. Also returns you to the dashboard from dashboard settings.
**Focused panel**
By hovering over a panel with the mouse you can use some shortcuts that will target that panel.
- `e`: Toggle panel edit view
- `v`: Toggle panel full screen view
- `pu`: Open share panel link configuration
- `pe`: Open share panel embed configuration
- `ps`: Open share panel snapshot configuration
- `pd`: Duplicate panel
- `pr`: Remove panel
## Set dashboard time range
Grafana provides several ways to manage the time ranges of the data being visualized, for dashboard, panels and also for alerting.
This section describes supported time units and relative ranges, the common time controls, dashboard-wide time settings, and panel-specific time settings.
### Time units and relative ranges
Grafana supports the following time units: `s (seconds)`, `m (minutes)`, `h (hours)`, `d (days)`, `w (weeks)`, `M (months)`, `Q (quarters)` and `y (years)`.
The minus operator enables you to step back in time, relative to the current date and time, or `now`. If you want to display the full period of the unit (day, week, month, etc...), append `/<time unit>` to the end. To view fiscal periods, use `fQ (fiscal quarter)` and `fy (fiscal year)` time units.
The plus operator enables you to step forward in time, relative to now. For example, you can use this feature to look at predicted data in the future.
The following table provides example relative ranges:
| Example relative range | From: | To: |
| ---------------------- | ----------- | ----------- |
| Last 5 minutes | `now-5m` | `now` |
| The day so far | `now/d` | `now` |
| This week | `now/w` | `now/w` |
| This week so far | `now/w` | `now` |
| This month | `now/M` | `now/M` |
| This month so far | `now/M` | `now` |
| Previous Month | `now-1M/M` | `now-1M/M` |
| This year so far | `now/Y` | `now` |
| This Year | `now/Y` | `now/Y` |
| Previous fiscal year | `now-1y/fy` | `now-1y/fy` |
{{< admonition type="note" >}}
Grafana Alerting does not support the following syntaxes at this time:
- now+n for future timestamps.
- now-1n/n for "start of n until end of n" because this is an absolute timestamp.
{{< /admonition >}}
### Common time range controls
The dashboard and panel time controls have a common UI.
![Common time controls](/media/docs/grafana/dashboards/screenshot-common-time-controls-11.2.png)
The following sections define common time range controls.
#### Current time range
The current time range, also called the _time picker_, shows the time range currently displayed in the dashboard or panel you are viewing.
Hover your cursor over the field to see the exact time stamps in the range and their source (such as the local browser).
![Time picker](/media/docs/grafana/dashboards/screenshot-time-picker-11.2.png)
Click the current time range to change it. You can change the current time using a _relative time range_, such as the last 15 minutes, or an _absolute time range_, such as `2020-05-14 00:00:00 to 2020-05-15 23:59:59`.
![Current time range](/media/docs/grafana/dashboards/screenshot-current-time-range-11.2.png)
#### Relative time range
Select the relative time range from the **Relative time ranges** list. You can filter the list using the input field at the top. Some examples of time ranges include:
- Last 30 minutes
- Last 12 hours
- Last 7 days
- Last 2 years
- Yesterday
- Day before yesterday
- This day last week
- Today so far
- This week so far
- This month so far
#### Absolute time range
You can set an absolute time range in the following ways:
- Type values into the **From** and **To** fields. You can type exact time values or relative values, such as `now-24h`, and then click **Apply time range**.
- Click in the **From** or **To** field. Grafana displays a calendar. Click the day or days you want to use as the current time range and then click **Apply time range**.
This section also displays recently used absolute ranges.
#### Semi-relative time range
{{< admonition type="note" >}}
Grafana Alerting does not support semi-relative time ranges.
{{< /admonition >}}
You can also use the absolute time range settings to set a semi-relative time range. Semi-relative time range dashboards are useful when you need to monitor the progress of something over time, but you also want to see the entire history from a starting point.
Set a semi-relative time range by setting the start time to an absolute timestamp and the end time to a “now” that is relative to the current time. For example:
**Start time:** `2023-05-01 00:00:00`
**End time:** `now`
If you wanted to track the progress of something during business hours, you could set a time range that covers the current day, but starting at 8am, like so:
**Start time:** `now/d+8h`
**End time:** `now`
This is equivalent to the **Today so far** time range preset, but it starts at 8:00am instead of 12:00am by appending +8h to the periodic start time.
Using a semi-relative time range, as time progresses, your dashboard will automatically and progressively zoom out to show more history and fewer details. At the same rate, as high data resolution decreases, historical trends over the entire time period will become more clear.
#### Copy and paste time range
You can copy and paste the time range from a dashboard to **Explore** and vice versa, or from one dashboard to another.
Click the **Copy time range to clipboard** icon to copy the current time range to the clipboard. Then paste the time range into **Explore** or another dashboard.
<img class="no-shadow" src="/media/docs/grafana/dashboards/screenshot-copy-paste-time-range.png" max-width="900">
You can also copy and paste a time range using the keyboard shortcuts `t+c` and `t+v` respectively.
#### Zoom out (Cmd+Z or Ctrl+Z)
Click the **Zoom out** icon to view a larger time range in the dashboard or panel visualization.
#### Zoom in (only applicable to graph visualizations)
Click and drag to select the time range in the visualization that you want to view.
#### Refresh dashboard
Click the **Refresh dashboard** icon to immediately run every query on the dashboard and refresh the visualizations. Grafana cancels any pending requests when you trigger a refresh.
By default, Grafana does not automatically refresh the dashboard. Queries run on their own schedule according to the panel settings. However, if you want to regularly refresh the dashboard, click the down arrow next to the **Refresh dashboard** icon, and then select a refresh interval.
Selecting the **Auto** interval schedules a refresh based on the query time range and browser window width. Short time ranges update frequently, while longer ones update infrequently. There is no need to refresh more often then the pixels available to draw any updates.
### Control the time range using a URL
{{< docs/shared lookup="dashboards/time-range-URLs.md" source="grafana" version="<GRAFANA_VERSION>" >}}
## Filter dashboard data
Once you've [added an ad hoc filter](ref:add-ad-hoc-filters) in the dashboard settings, you can create label/value filter pairs on the dashboard.
These filters are applied to all metric queries that use the specified data source and to all panels on the dashboard.
To filter dashboard data, follow these steps:
1. On the dashboard, click in the filter field.
1. Select a label, operator, and value.
To add multiple values for one label, choose one of the multi-select operators, **One of** (`=|`) or **Not one of** (`!=|`). These operators only appear if the filter data source supports it.
1. Repeat this process as needed until you have all the filters you need.
![Ad hoc filters](/media/docs/grafana/dashboards/screenshot-adhoc-filters-v11.3.png)
### Edit or delete filters
To edit or delete filters, follow these steps:
1. On the dashboard, click anywhere on the filter you want to change.
1. Do one of the following:
- To edit the operator or value of a filter, click anywhere on the filter and update it.
![Editing an ad hoc filter](/media/docs/grafana/dashboards/screenshot-edit-filters-v11.3.png)
- To change the filter label, you must delete the filter and create a new one.
- To delete a filter, click the **X** next to it.
docs/sources/visualizations/dashboards/variables/_index.md
+96
View File
@@ -0,0 +1,96 @@
---
aliases:
- ../../variables/ # /docs/grafana/next/variables/
- ../../variables/templates-and-variables/ # /docs/grafana/next/variables/templates-and-variables/
- ../../variables/variable-examples/ # /docs/grafana/next/variables/variable-examples/
- ../../dashboards/variables/ # /docs/grafana/next/dashboards/variables/
labels:
products:
- cloud
- enterprise
- oss
title: Variables
description: Add variables to metric queries and panel titles to create interactive and dynamic dashboards
weight: 800
---
# Variables
A variable is a placeholder for a value.
When you change the value, the element using the variable will change to reflect the new value.
Variables are displayed as drop-down lists (or in some cases text fields) at the top of the dashboard.
These drop-down lists make it easy to update the variable value and thus change the data being displayed in your dashboard.
For example, if you needed to monitor several servers, you _could_ make a dashboard for each server.
Or you could create one dashboard and use panels with variables like this one, where you can change the server using the variable selector:
{{< figure src="/media/docs/grafana/dashboards/screenshot-selected-variables-v12.png" max-width="750px" alt="Variable drop-down open and two values selected" >}}
Variables allow you to create more interactive dashboards.
Instead of hard-coding things like server, application, and sensor names in your metric queries, you can use variables in their place.
They're useful for administrators who want to allow Grafana viewers to adjust visualizations without giving them full editing permissions.
Using variables also allows you to single-source dashboards.
If you have multiple identical data sources or servers, you can make one dashboard and use variables to change what you are viewing.
This simplifies maintenance and upkeep enormously.
{{< youtube id="mMUJ3iwIYwc" >}}
You can use variables in:
- Data source queries
- [Panel repeating options](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-panel-options/#configure-repeating-panels)
- [Dashboard and panel links](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/)
- Titles
- Descriptions
- [Transformations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/)
To see variable settings, navigate to **Dashboard Settings > Variables**.
Click a variable in the list to see its settings.
{{< docs/play title="Templating - Interactive dashboard" url="https://play.grafana.org/goto/B9Xog68Hg?orgId=1" >}}
## Template variables {#templates}
A _template_ is any query that contains a variable.
Queries with text that starts with `$` are templates.
{{< admonition type="note">}}
In our documentation and in the application, we typically simply refer to a _template query_ as a _query_, but we often use the terms _variable_ and _template variable_ interchangeably.
{{< /admonition >}}
For example, if you were administering a dashboard to monitor several servers, it could have panels that use template queries like this one:
```text
groupByNode(movingAverage(apps.$app.$server.counters.requests.count, 10), 2, 'sum')
```
The following image shows a panel in edit mode using the query:
{{< figure src="/media/docs/grafana/dashboards/screenshot-template-query-v12.1.png" max-width="750px" alt="A panel using a template query" >}}
### Variables in URLs
Variable values are always synced to the URL using [query parameter syntax](https://grafana.com/docs/grafana/latest/dashboards/variables/variable-syntax/#query-parameters), `var-<varname>=value`.
For example:
```text
https://play.grafana.org/d/HYaGDGIMk/templating-global-variables-and-interpolation?orgId=1&from=now-6h&to=now&timezone=utc&var-Server=CCC&var-MyCustomDashboardVariable=Hello%20World%21
```
In the preceding example, the variables and values are `var-Server=CCC` and `var-MyCustomDashboardVariable=Hello%20World%21`.
## Additional examples
The following dashboards in Grafana Play provide examples of template variables:
- [Templating - Repeated panels](https://play.grafana.org/goto/yfZOReUNR?orgId=1) - Using query variables to control how many panels appear in a dashboard.
- [Templating - Nested Variables Drilldown](https://play.grafana.org/d/testdata-nested-variables-drilldown/) - Demonstrates how changing one variable value can change the values available in a nested variable.
- [Templating - Global variables and interpolation](https://play.grafana.org/d/HYaGDGIMk/) - Shows you how the syntax for Grafana variables works.
## Next steps
The following topics describe how to add and manage variables in your dashboards:
{{< section >}}
docs/sources/visualizations/dashboards/variables/add-template-variables/index.md
+823
View File
@@ -0,0 +1,823 @@
---
aliases:
- ../../../reference/templating/ # /docs/grafana/next/reference/templating/
- ../../../variables/add-ad-hoc-filters/ # /docs/grafana/next/variables/add-ad-hoc-filters/
- ../../../variables/add-constant-variable/ # /docs/grafana/next/variables/add-constant-variable/
- ../../../variables/add-custom-variable/ # /docs/grafana/next/variables/add-custom-variable/
- ../../../variables/add-data-source-variable/ # /docs/grafana/next/variables/add-data-source-variable/
- ../../../variables/add-interval-variable/ # /docs/grafana/next/variables/add-interval-variable/
- ../../../variables/add-query-variable/ # /docs/grafana/next/variables/add-query-variable/
- ../../../variables/add-template-variables/ # /docs/grafana/next/variables/add-template-variables/
- ../../../variables/add-text-box-variable/ # /docs/grafana/next/variables/add-text-box-variable/
- ../../../variables/chained-variables/ # /docs/grafana/next/variables/chained-variables/
- ../../../variables/filter-variables-with-regex/ # /docs/grafana/next/variables/filter-variables-with-regex/
- ../../../variables/formatting-multi-value-variables/ # /docs/grafana/next/variables/formatting-multi-value-variables/
- ../../../variables/global-variables/ # /docs/grafana/next/variables/global-variables/
- ../../../variables/manage-variable/ # /docs/grafana/next/variables/manage-variable/
- ../../../variables/variable-selection-options/ # /docs/grafana/next/variables/variable-selection-options/
- ../../../variables/variable-types/ # /docs/grafana/next/variables/variable-types/
- ../../../variables/variable-types/add-ad-hoc-filters/ # /docs/grafana/next/variables/variable-types/add-ad-hoc-filters/
- ../../../variables/variable-types/add-constant-variable/ # /docs/grafana/next/variables/variable-types/add-constant-variable/
- ../../../variables/variable-types/add-custom-variable/ # /docs/grafana/next/variables/variable-types/add-custom-variable/
- ../../../variables/variable-types/add-data-source-variable/ # /docs/grafana/next/variables/variable-types/add-data-source-variable/
- ../../../variables/variable-types/add-interval-variable/ # /docs/grafana/next/variables/variable-types/add-interval-variable/
- ../../../variables/variable-types/add-query-variable/ # /docs/grafana/next/variables/variable-types/add-query-variable/
- ../../../variables/variable-types/add-text-box-variable/ # /docs/grafana/next/variables/variable-types/add-text-box-variable/
- ../../../variables/variable-types/chained-variables/ # /docs/grafana/next/variables/variable-types/chained-variables/
- ../../../variables/variable-types/global-variables/ # /docs/grafana/next/variables/variable-types/global-variables/
- ../../../dashboards/variables/add-template-variables/ # /docs/grafana/next/dashboards/variables/add-template-variables/
keywords:
- grafana
- documentation
- guide
- variable
- global
- standard
- nested
- chained
- linked
- best practices
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Add variables
title: Add variables
description: Learn about the types of variables you can add to dashboards and how
weight: 100
refs:
add:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/
inspect:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/inspect-variable/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/inspect-variable/
prometheus-query-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/prometheus/template-variables/#use-**rate_interval
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/prometheus/template-variables/#use-**rate_interval
raw-variable-format:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/variable-syntax/#raw
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/variable-syntax/#raw
data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/
raw-format:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/variable-syntax/#raw
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/variable-syntax/#raw
add-a-data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#add-a-data-source
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/#add-a-data-source
filter-dashboard:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/use-dashboards/#filter-dashboard-data
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/use-dashboards/#filter-dashboard-data
---
# Add variables
<!-- vale Grafana.Spelling = NO -->
The following table lists the types of variables shipped with Grafana.
| Variable type | Description |
| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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
You must enter general options for any type of variable that you create.
To create a variable, follow these steps:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
1. Go to the **Variables** tab.
1. Click **Add variable**, or if there are already existing variables, **+ New variable**.
1. Choose an option in the **Select variable type** drop-down list.
1. Enter a **Name** for the variable.
1. (Optional) In the **Label** field, enter the display name for the variable drop-down list.
If you don't enter a display name, then the drop-down list label is the variable name.
1. Choose a **Show on dashboard** option:
- **Label and value** - The variable drop-down list displays the variable **Name** or **Label** value. This is the default.
- **Value:** The variable drop-down list only displays the selected variable value and a down arrow.
- **Nothing:** No variable drop-down list is displayed on the dashboard.
1. Click one of the following links to complete the steps for adding your selected variable type:
- [Query](#add-a-query-variable)
- [Custom](#add-a-custom-variable)
- [Textbox](#add-a-text-box-variable)
- [Constant](#add-a-constant-variable)
- [Data source](#add-a-data-source-variable)
- [Interval](#add-an-interval-variable)
- [Ad hoc filters](#add-ad-hoc-filters)
<!-- vale Grafana.Spelling = YES -->
### Variable best practices
- Variable drop-down lists are displayed in the order in which they're listed in the **Variables** in dashboard settings, so put the variables that you will change often at the top, so they will be shown first (far left on the dashboard).
- By default, variables don't have a default value. This means that the topmost value in the drop-down list is always preselected. If you want to pre-populate a variable with an empty value, you can use the following workaround in the variable settings:
1. Select the **Include All Option** checkbox.
2. In the **Custom all value** field, enter a value like `+`.
## Add a query variable
Query variables enable you to write a data source query that can return a list of metric names, tag values, or keys. For example, a query variable might return a list of server names, sensor IDs, or data centers. The variable values change as they dynamically fetch options with a data source query.
Query variables are generally only supported for strings. If your query returns numbers or any other data type, you might need to convert them to strings to use them as variables. For the Azure data source, for example, you can use the [`tostring`](https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/tostringfunction) function for this purpose.
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](ref:data-source).
{{< /admonition >}}
1. [Enter general options](#enter-general-options).
1. Under the **Query options** section of the page, select a target data source in the **Data source** drop-down list.
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](ref:add-a-data-source).
1. In the **Query type** drop-down list, select one of the following options:
- **Label names**
- **Label values**
- **Metrics**
- **Query result**
- **Series query**
- **Classic query**
1. In the **Query** field, enter a query.
- The query field varies according to your data source. Some data sources have custom query editors.
- Each data source defines how the variable values are extracted. The typical implementation uses every string value returned from the data source response as a variable value. Make sure to double-check the documentation for the data source.
- Some data sources let you provide custom "display names" for the values. For instance, the PostgreSQL, MySQL, and Microsoft SQL Server plugins handle this by looking for fields named `__text` and `__value` in the result. Other data sources may look for `text` and `value` or use a different approach. Always remember to double-check the documentation for the data source.
- 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 regular expression to filter or capture specific parts of the names returned by your data source query. To see examples, refer to [Filter variables with a regular expression](#filter-variables-with-regex).
1. In the **Sort** drop-down 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 is used.
1. Under **Refresh**, 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 every time the dashboard loads and when the dashboard time range changes. Use this option if your variable options query contains a time range filter or is dependent on the dashboard time range.
1. (Optional) Configure the settings in the [Selection Options](#configure-variable-selection-options) section:
- **Multi-value** - Enables multiple values to be selected at the same time.
- **Include All option** - Enables an option to include all variables.
1. In the **Preview of values** section, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a custom variable
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](#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. Under the **Custom options** section of the page, in the **Values separated by comma** field, 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) Configure the settings in the [Selection Options](#configure-variable-selection-options) section:
- **Multi-value** - Enables multiple values to be selected at the same time.
- **Include All option** - Enables an option to include all variables.
1. In the **Preview of values** section, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a text box variable
_Text box_ variables display a free text input field with an optional default value. This is the most flexible variable, because you can enter any value. Use this type of variable if you have metrics with high cardinality or if you want to update multiple panels in a dashboard at the same time.
For more information about cardinality, refer to [What are cardinality spikes and why do they matter?](https://grafana.com/blog/2022/02/15/what-are-cardinality-spikes-and-why-do-they-matter/)
1. [Enter general options](#enter-general-options).
1. (Optional) Under the **Text options** section of the page, in the **Default value** field, enter the default value for the variable.
If you do not enter anything in this field, then Grafana displays an empty text box for users to type text into.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a constant variable
_Constant_ variables enable you to define a hidden constant. This is useful for metric path prefixes for dashboards you want to share. When you export a dashboard, constant variables are converted to import options.
Constant variables are _not_ flexible. Each constant variable only holds one value, and it cannot be updated unless you update the variable settings.
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. Under the **Constant options** section of the page, 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](ref:raw-format).
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a data source variable
_Data source_ variables enable you to quickly change the data source for an entire dashboard. They are useful if you have multiple instances of a data source, perhaps in different environments.
1. [Enter general options](#enter-general-options).
1. Under the **Data source options** section of the page, in the **Type** drop-down list, select the target data source for the variable.
1. (Optional) In **Instance name filter**, enter a regular expression 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) Configure the settings in the [Selection Options](#configure-variable-selection-options) section:
- **Multi-value** - Enables multiple values to be selected at the same time.
- **Include All option** - Enables an option to include all variables.
1. In the **Preview of values** section, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add an interval variable
Use an _interval_ variable to represents time spans such as `1m`,`1h`, `1d`. You can think of them as a dashboard-wide "group by time" command. Interval variables change how the data is grouped in the visualization. You can also use the Auto Option to return a set number of data points per time span.
You can use an interval variable as a parameter to group by time (for InfluxDB), date histogram interval (for Elasticsearch), or as a summarize function parameter (for Graphite).
1. [Enter general options](#enter-general-options).
1. Under the **Interval options** section, in the **Values** field, enter the time range intervals that you want to appear in the variable drop-down list.
The following time units are supported: `s (seconds)`, `m (minutes)`, `h (hours)`, `d (days)`, `w (weeks)`, `M (months)`, and `y (years)`. You can also accept or edit the default values: `1m,10m,30m,1h,6h,12h,1d,7d,14d,30d`.
1. (Optional) Select on the **Auto option** checkbox if you want to add the `auto` option to the list.
This option allows you to specify how many times the current time range should be divided to calculate the current `auto` time span. If you turn it on, then two more options appear:
- **Step count** - Select the number of times the current time range is divided to calculate the value, similar to the **Max data points** query option. For example, if the current visible time range is 30 minutes, then the `auto` interval groups the data into 30 one-minute increments. The default value is 30 steps.
- **Min interval** - The minimum threshold below which the step count intervals does not divide the time. To continue the 30 minute example, if the minimum interval is set to 2m, then Grafana would group the data into 15 two-minute increments.
1. In the **Preview of values** section, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
### Interval variable examples
The following example shows a template variable `myinterval` in a Graphite function:
```
summarize($myinterval, sum, false)
```
The following example shows a more complex Graphite example, from the [Graphite Template Nested Requests panel](https://play.grafana.org/d/000000056/graphite-templated-nested?editPanel=2&orgId=1):
```
groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum')
```
<!-- vale Grafana.WordList = NO -->
<!-- vale Grafana.Spelling = NO -->
## Add ad hoc filters
_Ad hoc filters_ are one of the most complex and flexible variable options available.
Instead of creating a variable for each dimension by which you want to filter, ad hoc filters automatically create variables (key/value pairs) for all the dimensions returned by your data source query.
This allows you to apply filters dashboard-wide.
Ad hoc filters let you add label/value filters that are automatically added to all metric queries that use the specified data source.
Unlike other variables, you don't use ad hoc filters in queries.
Instead, you use ad hoc filters to write filters for existing queries.
The following data sources support ad hoc filters:
- Dashboard - Use this special data source to [apply ad hoc filters to data from unsupported data sources](#filter-any-data-using-the-dashboard-data-source).
- Prometheus
- Loki
- InfluxDB
- Elasticsearch
- OpenSearch
To create an ad hoc filter, follow these steps:
1. [Enter general options](#enter-general-options).
1. Under the **Ad-hoc options** section of the page, select a target data source in the **Data source** drop-down list.
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](ref:add-a-data-source).
1. (Optional) To provide the filter dimensions as comma-separated values (CSV), toggle the **Use static key dimensions** switch on, and then enter the values in the space provided.
1. Click **Save dashboard**.
1. Enter an optional description of your dashboard changes, and then click **Save**.
1. Click **Back to dashboard** and **Exit edit**.
Now you can [filter data on the dashboard](ref:filter-dashboard).
### Filter any data using the Dashboard data source
In cases where a data source doesn't support the use of ad hoc filters, you can use the Dashboard data source to reference that data, and then filter it in a new panel.
This allows you to bypass the limitations of the data source in the source panel.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-adhoc-filter-dashboard-ds-v12.2.png" max-width="750px" alt="The query section of a panel with the Dashboard data source configured" >}}
To use ad hoc filters on data from an unsupported data source, follow these steps:
1. Navigate to the dashboard with the panel with the data you want to filter.
1. Click **Edit** in top-right corner of the dashboard.
1. At the top of the dashboard, click **Add** and select **Visualization** in the drop-down list.
1. In the **Queries** tab of the edit panel view, enter `Dashboard` in the **Data source** field and select **-- Dashboard --**.
1. In the query configuration section, make the following selections:
- **Source panel** - Choose the panel with the source data.
- **Data** - Select **All Data** to use the data of the panel, and not just the annotations. This is the default selection.
- **AdHoc Filters** - Toggle on the switch to make the data from the referenced panel filterable.
{{< admonition type="note">}}
If you're referencing multiple panels in a dashboard with the Dashboard data source, you can only use one of those source panels at a time for ad hoc filtering.
{{< /admonition >}}
1. Configure any other needed options for the panel.
1. Click **Save dashboard**.
Now you can filter the data from the source panel by way of the Dashboard data source.
Add as many panels as you need.
### Dashboard drilldown with ad hoc filters
In table and bar chart visualizations, you can apply ad hoc filters directly from the visualization.
To quickly apply ad hoc filter variables, follow these steps:
1. To display the filter icons, hover your cursor over the table cell with the value for which you want to filter. In this example, the cell value is `ConfigMap Updated`, which is in the `alertname` column:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-adhoc-filter-icon-v12.2.png" max-width="550px" alt="Table and bar chart with ad hoc filter icon displayed on a table cell" >}}
In bar chart visualizations, hover and click the bar to display the filter button:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-adhoc-filter-icon-bar-v12.2.png" max-width="300px" alt="The ad hoc filter button in a bar chart tooltip">}}
1. Click the add filter icon.
The variable pair `alertname = ConfigMap Updated` is added to the ad hoc filter and all panels using the same data source that include that variable value are filtered by that value:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-adhoc-filter-applied-v12.2.png" max-width="550px" alt="Table and bar chart, filtered" >}}
If one of the panels in the dashboard using that data source doesn't include that variable value, the panel won't return any data. In this example, the variable pair `_name_ = ALERTS` has been added to the ad hoc filter so the bar chart doesn't return any results:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-adhoc-filter-no-data-v12.2.png" max-width="650px" alt="Table, filtered and bar chart returning no results" >}}
In cases where the data source you're using doesn't support ad hoc filtering, consider using the special Dashboard data source.
For more information, refer to [Filter any data using the Dashboard data source](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#filter-any-data-using-the-dashboard-data-source).
<!-- vale Grafana.Spelling = YES -->
<!-- vale Grafana.WordList = YES -->
## Configure variable selection options
**Selection Options** are a feature you can use to manage variable option selections. All selection options are optional, and they are off by default.
### Multi-value variables
Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values into a string that is valid in the given context where the variable is used. Grafana tries to solve this by allowing each data source plugin to inform the templating interpolation engine what format to use for multiple values.
{{< admonition type="note" >}}
The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If it is left blank, then Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value is something like `*` or `all`.
{{< /admonition >}}
#### Multi-value variables with a Graphite data source
Graphite uses glob expressions. A variable with multiple values would, in this case, be interpolated as `{host1,host2,host3}` if the current variable value was _host1_, _host2_, and _host3_.
#### Multi-value variables with a Prometheus or InfluxDB data source
InfluxDB and Prometheus use regular expressions, so the same variable would be interpolated as `(host1|host2|host3)`. Every value would also be regular expression escaped. If not, a value with a regular expression control character would break the regular expression.
#### Multi-value variables with an Elastic data source
Elasticsearch uses Lucene query syntax, so the same variable would be formatted as `("host1" OR "host2" OR "host3")`. In this case, every value must be escaped so that the value only contains Lucene control words and quotation marks.
#### Variable indexing
If you have a multi-value variable that's formatted as an array, you can use array positions to reference the values rather than the actual values.
You can use this functionality in dashboard panels to filter data, and when you do so, the array is maintained.
To reference variable values this way, use the following syntax:
```text
${query0.0}
```
The preceding syntax references the first, or `0`, position in the array.
In the following example, there's an array of three values, `1t`, `2t`, and `3t`, and rather than referencing those values, the panel query references the second value in the array using the syntax `${query0.1}`:
{{< figure src="/media/docs/grafana/dashboards/screenshot-indexed-variables-v12.1.png" max-width="750px" alt="Panel query using variable indexing to reference a value" >}}
#### Troubleshoot multi-value variables
Automatic escaping and formatting can cause problems and it can be tricky to grasp the logic behind it. Especially for InfluxDB and Prometheus where the use of regular expression syntax requires that the variable is used in regular expression operator context.
If you do not want Grafana to do this automatic regular expression 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](ref:raw-variable-format).
### Include All option
Grafana adds an `All` option to the variable dropdown list. If a user selects this option, then all variable options are selected.
### Custom all value
This option is only visible if the **Include All option** is selected.
Enter regular expressions, globs, or Lucene syntax in the **Custom all value** field to define the value of the `All` option.
By default the `All` value includes all options in combined expression. This can become very long and can have performance problems. Sometimes it can be better to specify a custom all value, like a wildcard regular expression.
In order to have custom regular expression, globs, or Lucene syntax in the **Custom all value** option, it is never escaped so you have to think about what is a valid value for your data source.
## Global variables
Grafana has global built-in variables that can be used in expressions in the query editor. This topic lists them in alphabetical order and defines them. These variables are useful in queries, dashboard links, panel links, and data links.
### `$__dashboard`
This variable is the name of the current dashboard.
### `$__from` and `$__to`
Grafana has two built-in time range variables: `$__from` and `$__to`. They are currently always interpolated as epoch milliseconds by default, but you can control date formatting.
| Syntax | Example result | Description |
| ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `${__from}` | 1594671549254 | Unix millisecond epoch |
| `${__from:date}` | 2020-07-13T20:19:09.254Z | No arguments, defaults to ISO 8601/RFC 3339 |
| `${__from:date:iso}` | 2020-07-13T20:19:09.254Z | ISO 8601/RFC 3339 |
| `${__from:date:seconds}` | 1594671549 | Unix seconds epoch |
| `${__from:date:YYYY-MM}` | 2020-07 | Any custom [date format](https://momentjs.com/docs/#/displaying/) that does not include the `:` character. Uses browser time. Use `:date` or `:date:iso` for UTC |
The syntax above also works with `${__to}`.
You can use this variable in URLs, as well. For example, you can send a user to a dashboard that shows a time range from six hours ago until now: https://play.grafana.org/d/000000012/grafana-play-home?viewPanel=2&orgId=1?from=now-6h&to=now
### `$__interval`
You can use the `$__interval` variable as a parameter to group by time (for InfluxDB, MySQL, Postgres, MSSQL), Date histogram interval (for Elasticsearch), or as a _summarize_ function parameter (for Graphite).
Grafana automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph, then queries can be made more efficient by grouping by a larger interval. It is more efficient to group by 1 day than by 10s when looking at 3 months of data. The graph looks the same and the query is faster. The `$__interval` is calculated using the time range and the width of the graph (the number of pixels).
Approximate Calculation: `(to - from) / resolution`
For example, when the time range is 1 hour and the graph is full screen, then the interval might be calculated to `2m` - points are grouped in 2 minute intervals. If the time range is 6 months and the graph is full screen, then the interval might be `1d` (1 day) - points are grouped by day.
In the InfluxDB data source, the legacy variable `$interval` is the same variable. `$__interval` should be used instead.
The InfluxDB and Elasticsearch data sources have `Group by time interval` fields that are used to hard code the interval or to set the minimum limit for the `$__interval` variable (by using the `>` syntax -> `>10m`).
### `$__interval_ms`
This variable is the `$__interval` variable in milliseconds, not a time interval formatted string. For example, if the `$__interval` is `20m` then the `$__interval_ms` is `1200000`.
### `$__name`
This variable is only available in the **Singlestat** panel and can be used in the prefix or suffix fields on the Options tab. The variable is replaced with the series name or alias.
{{< admonition type="note" >}}
The **Singlestat** panel is no longer available from Grafana 8.0.
{{< /admonition >}}
### `$__org`
This variable is the ID of the current organization.
`${__org.name}` is the name of the current organization.
### `$__user`
`${__user.id}` is the ID of the current user.
`${__user.login}` is the login handle of the current user.
`${__user.email}` is the email for the current user.
### `$__range`
Currently only supported for Prometheus and Loki data sources. This variable represents the range for the current dashboard. It is calculated by `to - from`. It has a millisecond and a second representation called `$__range_ms` and `$__range_s`.
### `$__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](ref:prometheus-query-variables) for details.
### `$__rate_interval_ms`
This variable is the `$__rate_interval` variable in milliseconds, not a time-interval-formatted string. For example, if the `$__rate_interval` is `20m` then the `$__rate_interval_ms` is `1200000`.
### `$timeFilter` or `$__timeFilter`
The `$timeFilter` variable returns the currently selected time range as an expression. For example, the time range interval `Last 7 days` expression is `time > now() - 7d`.
This is used in several places, including:
- The WHERE clause for the InfluxDB data source. Grafana adds it automatically to InfluxDB queries when in Query Editor mode. You can add it manually in Text Editor mode: `WHERE $timeFilter`.
- Log Analytics queries in the Azure Monitor data source.
- SQL queries in MySQL, Postgres, and MSSQL.
- The `$__timeFilter` variable is used in the MySQL data source.
### `$__timezone`
The `$__timezone` variable returns the currently selected time zone, either `utc` or an entry of the IANA time zone database (for example, `America/New_York`).
If the currently selected time zone is _Browser Time_, Grafana tries to determine your browser time zone.
## Chained variables
_Chained variables_, also called _linked variables_ or _nested variables_, are query variables with one or more other variables in their variable query. This section explains how chained variables work and provides links to example dashboards that use chained variables.
Chained variable queries are different for every data source, but the premise is the same for all. You can use chained variable queries in any data source that allows them.
Extremely complex linked templated dashboards are possible, 5 or 10 levels deep. Technically, there is no limit to how deep or complex you can go, but the more links you have, the greater the query load.
### Grafana Play dashboard examples
The following Grafana Play dashboards contain fairly simple chained variables, only two layers deep. To view the variables and their settings, click **Edit**
and then **Settings**; then go to the **Variables** tab. Both examples are expanded in the following section.
- [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1&var-app=country&var-server=All&var-interval=1h)
- [InfluxDB Templated](https://play.grafana.org/d/e7bad3ef-db0c-4bbd-8245-b85c0b2ca2b9/influx-2-73a-hourly-electric-grid-monitor-for-us?orgId=1&refresh=1m)
### Examples explained
Variables are useful to reuse dashboards and dynamically change what is shown in dashboards. Chained variables are especially useful to filter what you see.
Create parent/child relationship in a variable, sort of a tree structure where you can select different levels of filters.
The following sections explain the linked examples in the dashboards above in depth and builds on them. While the examples are data source-specific, the concepts can be applied broadly.
#### Graphite example
In this example, there are several applications. Each application has a different subset of servers. It is based on the [Graphite Templated Nested](https://play.grafana.org/d/000000056/graphite-templated-nested?orgId=1&var-app=country&var-server=All&var-interval=1h).
Now, you could make separate variables for each metric source, but then you have to know which server goes with which app. A better solution is to use one variable to filter another. In this example, when the user changes the value of the `app` variable, it changes the dropdown options returned by the `server` variable. Both variables use the **Multi-value** option and **Include all option**, enabling users to select some or all options presented at any time.
##### `app` variable
The query for this variable basically says, "Find all the applications that exist."
```
apps.*
```
The values returned are `backend`, `country`, `fakesite`, and `All`.
##### `server` variable
The query for this variable basically says, "Find all servers for the currently chosen application."
```
apps.$app.*
```
If the user selects `backend`, then the query changes to:
```
apps.backend.*
```
The query returns all servers associated with `backend`, including `backend_01`, `backend_02`, and so on.
If the user selects `fakesite`, then the query changes to:
```
apps.fakesite.*
```
The query returns all servers associated with `fakesite`, including `web_server_01`, `web_server_02`, and so on.
##### More variables
{{< admonition type="note" >}}
This example is theoretical. The Graphite server used in the example does not contain CPU metrics.
{{< /admonition >}}
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected servers, you could copy the `server` variable and extend the query so that it reads:
```
apps.$app.$server.cpu.*
```
This query basically says, "Find the CPU metrics for the selected server."
Depending on what variable options the user selects, you could get queries like:
```
apps.backend.backend_01.cpu.*
apps.{backend.backend_02,backend_03}.cpu.*
apps.fakesite.web_server_01.cpu.*
```
#### InfluxDB example
In this example, you have several data centers. Each data center has a different subset of hosts. It is based on the [InfluxDB Templated](https://play.grafana.org/d/e7bad3ef-db0c-4bbd-8245-b85c0b2ca2b9/influx-2-73a-hourly-electric-grid-monitor-for-us?orgId=1&refresh=1m) dashboard.
In this example, when the user changes the value of the `datacenter` variable, it changes the dropdown options returned by the `host` variable. The `host` variable uses the **Multi-value** option and **Include all option**, allowing users to select some or all options presented at any time. The `datacenter` does not use either option, so you can only select one data center at a time.
##### `datacenter` variable
The query for this variable basically says, "Find all the data centers that exist."
```
SHOW TAG VALUES WITH KEY = "datacenter"
```
The values returned are `America`, `Africa`, `Asia`, and `Europe`.
##### `host` variable
The query for this variable basically says, "Find all hosts for the currently chosen data center."
```
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^$datacenter$/
```
If the user selects `America`, then the query changes to:
```
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^America/
```
The query returns all servers associated with `America`, including `server1`, `server2`, and so on.
If the user selects `Europe`, then the query changes to:
```
SHOW TAG VALUES WITH KEY = "hostname" WHERE "datacenter" =~ /^Europe/
```
The query returns all servers associated with `Europe`, including `server3`, `server4`, and so on.
##### More variables
{{< admonition type="note" >}}
This example is theoretical. The InfluxDB server used in the example does not contain CPU metrics.
{{< /admonition >}}
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected hosts, you could copy the `host` variable and extend the query so that it reads:
```
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^$datacenter$/ AND "host" =~ /^$host$/
```
This query basically says, "Find the CPU metrics for the selected host."
Depending on what variable options the user selects, you could get queries like:
```bash
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^America/ AND "host" =~ /^server2/
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Africa/ AND "host" =~ /^server/7/
SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Europe/ AND "host" =~ /^server3+server4/
```
### Best practices and tips
The following practices make your dashboards and variables easier to use.
#### New linked variables creation
- Chaining variables create parent/child dependencies. You can envision them as a ladder or a tree.
- The easiest way to create a new chained variable is to copy the variable that you want to base the new one on. In the variable list, click the **Duplicate variable** icon to the right of the variable entry to create a copy. You can then add on to the query for the parent variable.
- New variables created this way appear at the bottom of the list. You might need to drag it to a different position in the list to get it into a logical order.
#### Variable order
You can change the orders of variables in the dashboard variable list by clicking the up and down arrows on the right side of each entry. Grafana lists variable dropdowns left to right according to this list, with the variable at the top on the far left.
- List variables that do not have dependencies at the top, before their child variables.
- Each variable should follow the one it is dependent on.
- Remember there is no indication in the UI of which variables have dependency relationships. List the variables in a logical order to make it easy on other users (and yourself).
#### Complexity consideration
The more layers of dependency you have in variables, the longer it takes to update dashboards after you change variables.
For example, if you have a series of four linked variables (country, region, server, metric) and you change a root variable value (country), then Grafana must run queries for all the dependent variables before it updates the visualizations in the dashboard.
<!-- vale Grafana.WordList = NO -->
## Filter variables with regular expressions {#filter-variables-with-regex}
<!-- vale Grafana.WordList = NO -->
Using the **Regex** query option, you filter the list of options returned by the variable query or modify the options returned.
This page shows how to use a regular expression to filter/modify values in the variable dropdown.
Using the **Regex** query option, you filter the list of options returned by the Variable query or modify the options returned. For more information, refer to the Mozilla guide on [Regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions).
Examples of filtering on the following list of options:
```text
backend_01
backend_02
backend_03
backend_04
```
### Filter so that only the options that end with `01` or `02` are returned:
**Regex**:
```regex
/(01|02)$/
```
Result:
```text
backend_01
backend_02
```
### Filter and modify the options using a regular expression to capture group to return part of the text:
**Regex**:
```regex
/.*(01|02)/
```
Result:
```text
01
02
```
### Filter and modify - Prometheus Example
List of options:
```text
up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000
up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000
up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000
```
**Regex**:
```regex
/.*instance="([^"]*).*/
```
Result:
```text
demo.robustperception.io:9090
demo.robustperception.io:9093
demo.robustperception.io:9100
```
### Filter and modify using named text and value capture groups
Using named capture groups, you can capture separate 'text' and 'value' parts from the options returned by the variable query. This allows the variable drop-down list to contain a friendly name for each value that can be selected.
For example, when querying the `node_hwmon_chip_names` Prometheus metric, the `chip_name` is a lot friendlier than the `chip` value. So the following variable query result:
```text
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1
```
Passed through the following regular expression:
```regex
/chip_name="(?<text>[^"]+)|chip="(?<value>[^"]+)/g
```
Would produce the following drop-down list:
```text
Display Name Value
------------ -------------------------
enp216s0f0np0 0000:d7:00_0_0000:d8:00_0
enp216s0f0np1 0000:d7:00_0_0000:d8:00_1
enp216s0f0np2 0000:d7:00_0_0000:d8:00_2
enp216s0f0np3 0000:d7:00_0_0000:d8:00_3
```
{{< admonition type="note" >}}
Only `text` and `value` capture group names are supported.
{{< /admonition >}}
docs/sources/visualizations/dashboards/variables/inspect-variable/index.md
+58
View File
@@ -0,0 +1,58 @@
---
aliases:
- ../../../reference/templating/ # /docs/grafana/next/reference/templating/
- ../../../variables/inspect-variable/ # /docs/grafana/next/variables/inspect-variable/
- ../../../dashboards/variables/inspect-variable/ # /docs/grafana/next/dashboards/variables/inspect-variable/
keywords:
- grafana
- templating
- documentation
- guide
- template
- variable
labels:
products:
- cloud
- enterprise
- oss
title: Manage and inspect variables
menuTitle: Inspect variables
description: Review and manage your dashboard variables
refs:
add:
- pattern: /docs/grafana/
destination: https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/
- pattern: /docs/grafana-cloud/
destination: https://grafana.com/docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/
weight: 200
---
# Manage and inspect variables
In the **Variables** tab, you can [add](ref:add) variables and [manage](#manage-variables) existing variables. You can also [inspect](#inspect-variables) variables to identify any dependencies between them. <!--whether a variable is being referenced (or used) in other variables or dashboard.-->
## Manage variables
You can take the following actions in the **Variables** tab:
- **Move** - Move a variable up or down the list using drag and drop.
- **Clone** - Clone a variable by clicking the clone icon in the set of icons on the right. This creates a copy of the variable with the name of the original variable prefixed with `copy_of_`.
- **Delete** - Delete a variable by clicking the trash icon in the set of icons on the right.
## Inspect variables
In addition to [managing variables](#manage-variables), the **Variables** tab lets you easily identify whether variables have any dependencies. To check, click **Show dependencies** at the bottom of the list, which opens the dependencies diagram:
<!-- Update and comment this back in when the reference functionality is working again
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](ref:add) and [manage variables](#manage-variables) on this page.
![Variables list](/static/img/docs/variables-templates/variables-list-7-4.png)
Any variable that is referenced or used has a green check mark next to it, while unreferenced variables have a orange caution icon next to them.
![Variables list](/static/img/docs/variables-templates/variable-not-referenced-7-4.png)
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.-->
![Variables list](/static/img/docs/variables-templates/dependancy-map-7-4.png)
docs/sources/visualizations/dashboards/variables/variable-syntax/index.md
+225
View File
@@ -0,0 +1,225 @@
---
aliases:
- ../../../reference/templating/ # /docs/grafana/next/reference/templating/
- ../../../variables/advanced-variable-format-options/ # /docs/grafana/next/variables/advanced-variable-format-options/
- ../../../variables/syntax/ # /docs/grafana/next/variables/syntax/
- ../../../dashboards/variables/variable-syntax/ # /docs/grafana/next/dashboards/variables/variable-syntax/
keywords:
- grafana
- templating
- documentation
- guide
- template
- variable
labels:
products:
- cloud
- enterprise
- oss
title: Variable syntax
description: Learn about different types of variable syntax
weight: 300
---
# Variable syntax
Panel titles and metric queries can refer to variables using two different syntaxes:
- `$varname`
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](#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
interpolation, the variable value might be _escaped_ in order to conform to the syntax of the query language and where it is used.
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](#advanced-variable-format-options).
## Advanced variable format options
The formatting of the variable interpolation depends on the data source, but there are some situations where you might want to change the default formatting.
For example, the default for the MySql data source is to join multiple values as comma-separated with quotes: `'server01','server02'`. In some cases, you might want to have a comma-separated string without quotes: `server01,server02`. You can make that happen with advanced variable formatting options listed below.
### General syntax
Syntax: `${var_name:option}`
Test the formatting options on the [Grafana Play site](https://play.grafana.org/d/cJtIfcWiz/template-variable-formatting-options?orgId=1).
If any invalid formatting option is specified, then `glob` is the default/fallback option.
An alternative syntax (that might be deprecated in the future) is `[[var_name:option]]`.
### CSV
Formats variables with multiple values as a comma-separated string.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:csv}'
Interpolation result: 'test1,test2'
```
### Distributed - OpenTSDB
Formats variables with multiple values in custom format for OpenTSDB.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:distributed}'
Interpolation result: 'test1,servers=test2'
```
### Doublequote
Formats single- and multi-valued variables into a comma-separated string, escapes `"` in each value by `\"` and quotes each value with `"`.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:doublequote}'
Interpolation result: '"test1","test2"'
```
### Glob - Graphite
Formats variables with multiple values into a glob (for Graphite queries).
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:glob}'
Interpolation result: '{test1,test2}'
```
### Join
Formats multi-valued variables with a custom delimiter. If no delimiter argument is supplied, they will be combined with `,`.
```bash
servers = ["test1", "test2"]
String to interpolate: '${servers:join:&}'
Interpolation result: "test1&test2"
```
### JSON
Formats variables with multiple values as a comma-separated string.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:json}'
Interpolation result: '["test1", "test2"]'
```
### Lucene - Elasticsearch
Formats variables with multiple values in Lucene format for Elasticsearch.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:lucene}'
Interpolation result: '("test1" OR "test2")'
```
### Percentencode
Formats single and multi valued variables for use in URL parameters.
```bash
servers = ['foo()bar BAZ', 'test2']
String to interpolate: '${servers:percentencode}'
Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2'
```
### Pipe
Formats variables with multiple values into a pipe-separated string.
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers:pipe}'
Interpolation result: 'test1.|test2'
```
### Query parameters
Formats single- and multi-valued variables into their query parameter representation. Example: `var-foo=value1&var-foo=value2`
```bash
servers = ["test1", "test2"]
String to interpolate: '${servers:queryparam}'
Interpolation result: "var-servers=test1&var-servers=test2"
```
Use the `customqueryparam` formatter to customize how the query parameters are formatted. It accepts two optional arguments to specify the parameter name, and a value prefix.
```bash
servers = ["test1", "test2"]
String to interpolate: '${servers:customqueryparam:v-servers:x-}'
Interpolation result: "v-servers=x-test1&v-servers=x-test2"
```
### Raw
Doesn't apply any data source-specific formatting to the variable.
For example, in this case, there's a dashboard with a Prometheus data source and a multi-value variable.
Grafana typically converts the variable values as follows to accommodate Prometheus:
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers}'
Interpolation result: '(test1 | test2)'
```
Using the raw format, the values are returned without that formatting:
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers:raw}'
Interpolation result: 'test1,test2'
```
### Regex
Formats variables with multiple values into a regex string.
```bash
servers = ['test1.', 'test2']
String to interpolate: '${servers:regex}'
Interpolation result: '(test1\.|test2)'
```
### Singlequote
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `\'` and quotes each value with `'`.
```bash
servers = ['test1', 'test2']
String to interpolate: '${servers:singlequote}'
Interpolation result: "'test1','test2'"
```
### Sqlstring
Formats single- and multi-valued variables into a comma-separated string, escapes `'` in each value by `''` and quotes each value with `'`.
```bash
servers = ["test'1", "test2"]
String to interpolate: '${servers:sqlstring}'
Interpolation result: "'test''1','test2'"
```
### Text
Formats single- and multi-valued variables into their text representation. For a single variable it will just return the text representation. For multi-valued variables it will return the text representation combined with `+`.
```bash
servers = ["test1", "test2"]
String to interpolate: '${servers:text}'
Interpolation result: "test1 + test2"
```