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
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/_index.md
+48
View File
@@ -0,0 +1,48 @@
---
aliases:
- /docs/grafana-cloud/visualization/
- /docs/grafana-cloud/visualizations/
description: Learn how to build dashboards and visualizations.
menuTitle: Visualize data
title: Visualize your data in Grafana
hero:
title: Visualize data
level: 1
width: 100
height: 100
description: Easily collect, correlate, and visualize data with beautiful dashboards using Grafana&mdash;the solution that drives informed decisions, enhances system performance, and streamlines troubleshooting.
cards:
items:
- description: Allow you to query, transform, visualize, and understand your data no matter where it’s stored.
height: 24
href: /docs/grafana-cloud/visualizations/dashboards/
title: Dashboards
- description: Allow you to easily collect, correlate, and visualize data so you can make informed decisions in real time.
height: 24
href: /docs/grafana-cloud/visualizations/panels-visualizations/
title: Panels and visualizations
- description: Use the Drilldown apps to explore your telemetry data with a queryless experience.
height: 24
href: /docs/grafana-cloud/visualizations/simplified-exploration/
title: Drilldown apps
weight: 500
---
{{< docs/hero-simple key="hero" >}}
---
## Overview
A Grafana dashboard is a set of one or more panels that provide an at-a-glance view of related information. These panels are the basic building block in Grafana dashboards, and they're created using components that query and transform raw data from a data source into charts, graphs, and other visualizations.
A data source can be an SQL database, Grafana Loki, Grafana Mimir, or a JSON-based API. It can even be a basic CSV file. Queries allow you to reduce the entirety of your data to a specific dataset, providing a more manageable visualization. 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.
The growing suite of Grafana visualizations, ranging from time series graphs to heatmaps to cutting-edge 3D charts, provide you several different ways to present your data within a panel, depending on what best suits the data and your needs. If 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/_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"
```
docs/sources/visualizations/explore/_index.md
+64
View File
@@ -0,0 +1,64 @@
---
aliases:
- ../features/explore/ # /docs/grafana/next/features/explore/
- ../explore/ # /docs/grafana/next/explore/
- /docs/grafana-cloud/visualizations/explore/
keywords:
- explore
- loki
- logs
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Explore
title: Explore
weight: 90
hero:
title: Explore
level: 1
width: 110
height: 110
description: >-
Use Explore to query, collect, and analyze data for detailed real-time data analysis.
cards:
title_class: pt-0 lh-1
items:
- title: Get started with Explore
href: ./get-started-with-explore/
description: Get started using Explore to create queries and do real-time analysis on your data.
height: 24
- title: Query management
href: ./query-management/
description: Learn how to manage queries in Explore.
height: 24
- title: Query inspector in Explore
href: ./explore-inspector/
description: Learn how to use the Query inspector to troubleshoot issues with your queries.
height: 24
- title: Logs in Explore
href: ./logs-integration/
description: Learn about working with logs and log data in Explore.
height: 24
- title: Traces in Explore
href: ./trace-integration/
description: Learn about working with traces and tracing data in Explore.
height: 24
- title: Correlations editor in Explore
href: ./correlations-editor-in-explore/
description: Learn how to create and use Correlations.
height: 24
---
{{< docs/hero-simple key="hero" >}}
---
## Overview
Explore is your starting point for querying, analyzing, and aggregating data in Grafana. You can quickly begin creating queries to start analyzing data without having to create a dashboard or customize a visualization.
## Explore
{{< card-grid key="cards" type="simple" >}}
docs/sources/visualizations/explore/correlations-editor-in-explore.md
+139
View File
@@ -0,0 +1,139 @@
---
labels:
products:
- enterprise
- oss
- cloud
title: Correlations Editor in Explore
weight: 20
aliases:
- ../../explore/correlations-editor-in-explore/ # /docs/grafana/next/explore/correlations-editor-in-explore/
---
# Correlations Editor in Explore
{{< admonition type="note" >}}
The Explore editor is available in 10.1 and later versions. In the editor, transformations is available in Grafana 10.3 and later versions.
{{< /admonition >}}
Correlations allow users to build a link between any two data sources. For more information about correlations in general, please see the [correlations](/docs/grafana/<GRAFANA_VERSION>/administration/correlations/) topic in the administration page.
## Create a correlation
1. In Grafana, navigate to the Explore page.
1. Select a data source that you would like to be [the source data source](/docs/grafana/<GRAFANA_VERSION>/administration/correlations/correlation-configuration/#source-data-source-and-result-field) for a new correlation.
1. Run a query producing data in [a supported visualization](/docs/grafana/<GRAFANA_VERSION>/administration/correlations/#correlations).
1. Click **+ Add** in the top toolbar and select **Add correlation** (you can also select **Correlations Editor** from the [Command Palette](/docs/grafana/<GRAFANA_VERSION>/search/#command-palette)).
1. Explore is now in Correlations Editor mode indicated by a blue border and top bar. You can exit Correlations Editor by clicking **Exit** in the top bar.
1. You can now create the following new correlations for the visualization with links that are attached to the data that you can use to build a new query:
- Logs: links are displayed next to field values inside log details for each log row
- Table: every table cell is a link
1. Click on a link to add a new correlation.
Links are associated with a field that is used as a [result field of a correlation](/docs/grafana/<GRAFANA_VERSION>/administration/correlations/correlation-configuration/).
1. In the split view that opens, use the right pane to set up [the target query source of the correlation](/docs/grafana/<GRAFANA_VERSION>/administration/correlations/correlation-configuration/#target-query).
1. Build a target query using [variables syntax](/docs/grafana/<GRAFANA_VERSION>/dashboards/variables/variable-syntax/) with variables from the list provided at the top of the pane. The list contains sample values from the selected data row.
1. Provide a label and description (optional).
A label will be used as the name of the link inside the visualization and can contain variables.
1. Provide transformations (optional; see below for details).
1. Click **Save** in the top toolbar to save the correlation and exit Correlations Editor mode.
The link used to create the correlation is replaced with a data link in each row. When the link is clicked, the query you defined will run in another pane, with the variables replaced dynamically with the values from the selected row.
## Transformations
Transformations allow you to extract values that exist in a field with other data. For example, using a transformation, you can extract one portion of a log line to use in a correlation. For more details on transformations in correlations, see [Correlations](/docs/grafana/<GRAFANA_VERSION>/explore/correlations-editor-in-explore/#transformations).
After clicking one of the generated links in the editor mode, you can add transformations by clicking **Add transformation** in the Transformations dropdown menu.
You can use a transformation in your correlation with the following steps:
1. Select a field to apply the transformation to.
Select the portion of the field that you want to use for the transformation. For example, a log line.
Once selected, the value of this field will be used to assist you in building the transformation.
1. Select the type of the transformation.
See [correlations](/docs/grafana/<GRAFANA_VERSION>/explore/correlations-editor-in-explore/#transformations) for the options and relevant settings.
1. Based on your selection, you might see one or more variables populate, or you might need to provide more specifications in options that are displayed.
1. Select **Add transformation to correlation** to add the specified variables to the list of available variables.
### Notes for regular expressions
For regular expressions in this dialog box, the `mapValue` referred to in other documentation is called `Variable Name` here. Grafana highlights any text that matches the expression in the field value. Use regular expression capture groups to select what portion of the match should be extracted. When a valid regular expression is provided, the variable and the value of that variable appear below the `Variable Name` field.
## Correlations examples
The following examples show how to create correlations using the Correlations Editor in Explore. If you'd like to follow these examples, make sure to set up a [test data source](/docs/grafana/<GRAFANA_VERSION>/datasources/testdata/#testdata-data-source).
### Create a text to graph correlation
This example shows how to create a correlation using Correlations Editor in Explore.
Correlations allow you to use results of one query to run a new query in any data source. In this example, you will run a query that renders tabular data. The data will be used to run a different query that yields a graph result.
To follow this example, make sure you have set up [a test data source](/docs/grafana/<GRAFANA_VERSION>/datasources/testdata/#testdata-data-source).
1. In Grafana, navigate to **Explore**.
1. Select the **test data source** from the dropdown menu at the top left of the page.
1. Click **+ Add** in the dropdown menu to the right and select **Add correlation**.
1. Explore is now in Correlations Editor mode, indicated by a blue border.
1. Select the following scenario from the scenario dropdown menu: **CSV File**.
1. Select the file, **population_by_state.csv**.
Each cell is a link that you can click on to begin creating a new correlation.
{{< figure src="/static/img/docs/correlations/screenshot-correlations-editor-source-10.2.png" max-width="600px" caption="Selecting the source of a correlation" >}}
1. Click on any cell in the `State` column to create a new correlation that attaches a data link to that entry. For example, select "California".
1. In the split view, select the same data source you selected in the left pane.
The helper above the query editor contains all available variables you can use the target query. Variables contain all data fields (table columns) from the selected row.
1. In the **Scenario** menu, select **CSV Metric Values**.
The `String Input` field in the Query editor provides variables with population values for each year: `${1980},${2000},${2020}`. This will generate a graph using variable values.
1. In the Query Editor **Alias** field, enter "${State}".
{{< figure src="/static/img/docs/correlations/screenshot-correlations-editor-target-10.2.png" max-width="600px" caption="Setting up the target of a correlation" >}}
Run a query to see that it produces a graph using sample values from the variables.
1. Click **Save** to save the correlation and exit the Correlations Editor.
After the correlation is saved, Explore will rerun the query in the left pane. By clicking a state name, the query on the right is rerun with values from the row being inserted into the CSV, thus changing the graph. The query is rerun with updated values every time you click on a state name.
{{< figure src="/static/img/docs/correlations/screenshot-correlations-example-link-10.2.png" max-width="600px" caption="Result of clicking on a data link" >}}
You can apply the same steps to any data source. Correlations allow you to create links in visualizations to run dynamic queries based on selected data. In this example we used data returned by a query to build a new query generating different visualization using the same data source. However, you can create correlations between any data sources to create custom exploration flows.
### Create a logs to table correlation
In this example, you will create a correlation to demonstrate how to use transformations to extract values from the log line and another field.
To follow this example, make sure you have set up [a test data source](/docs/grafana/<GRAFANA_VERSION>/datasources/testdata/#testdata-data-source).
1. In Grafana, navigate to **Explore**.
1. Select the **test data source** from the dropdown menu at the top left of the page.
1. Click **+ Add** in the dropdown menu to the right and select **Add correlation**.
1. Explore is now in Correlations Editor mode, indicated by a blue border.
1. In the **Scenario** menu, select **Logs**.
1. Expand a log line to see the correlation links. Select `Correlate with hostname`.
1. Explore opens in split view. Select the same data source you selected in the left pane.
The helper above the query editor contains all available variables you can use the target query.
1. Expand the transformations section, and click **Add transformation**.
1. In the **Field** dropdown menu, select **message**.
The log line shows up as example data.
1. Under **Type**, select **Logfmt**.
This populates the list of variables.
1. Click **Add transformation to correlation**.
1. Click **Add transformation** again and under **Field**, select **hostname**.
1. Under **Type**, select **Regular expression**.
1. Under **Expression**, enter the following:
`-([0-9]\*)`
This selects any numbers to the right of the dash.
1. Under **Variable Name**, enter the following:
hostNumber
This populates the list of variables.
1. Click **Add transformation to correlation** to add it to the other variables.
1. In the data source editor, open the **Scenario** dropdown menu and select **CSV Content**.
1. In the text box below, provide the following and save the correlation:
```csv
time,msg,hostNumber,status
${time},${msg},${hostNumber},${status}
```
This closes the split view and reruns the left query. Expand any log line to see the correlation button. Clicking the correlation button opens the split view with the `time` (a field), `msg` (extracted with `logfmt` from the log line), host number (extracted with `regex` from the `hostname`) and the `status` (extracted with `logfmt` from the log line).
docs/sources/visualizations/explore/explore-inspector.md
+90
View File
@@ -0,0 +1,90 @@
---
description: Learn more about the Query inspector in Grafana Explore.
labels:
products:
- cloud
- enterprise
- oss
keywords:
- Explore
title: Query inspector in Explore
weight: 15
aliases:
- ../../explore/explore-inspector/ # /docs/grafana/next/explore/explore-inspector/
- /docs/grafana-cloud/visualizations/explore/explore-inspector/
---
# Query inspector in Explore
The Query inspector in Grafana Explore gives you detailed statistics regarding your query, which helps you understand and troubleshoot issues with your queries. Query inspector also lets you inspect raw data, export data to a comma-separated values (CSV) file, export log results in TXT format, and view query requests.
## Query inspector UI
To open Query inspector:
1. Go to the Explore page.
1. Run the query you would like to inspect.
1. Click **Query inspector**.
The Query inspector pane opens on the bottom of the Explore page, where you see the following tabs:
- **Stats tab -** Shows statistics regarding the query, including the amount of time it takes to run the query, data processing time and the amount of data returned.
- **Query tab -** Provides raw request and response data and time when Grafana queries the data source.
- **JSON tab -** Allows you to view and copy the JSON data and the JSON data frame structure.
- **Data tab -** Shows the raw data returned by the query. You can download the information to a CSV file.
- **Error tab -** Shows any errors. _Only visible if the query returns an error._
## Query inspector Stats tab
You can inspect query performance in the **Stats tab**, which displays statistics that tell you how long your query takes, how many queries you send, the number of rows returned and trace IDs. This information can help you troubleshoot your queries, especially if any of the numbers are unexpectedly high or low.
1. Open the inspector.
1. Click the **Stats tab**.
Statistics display in read-only format.
## Query inspector Query tab
View raw request and response in the Query tab.
1. Open the Query inspector and click the **Query tab**.
1. Click **Refresh**.
Grafana sends the query to the server and displays the result. You can drill down on specific portions of the query, expand or collapse all of it. Click **Copy to clipboard** to copy the data to use in other applications.
## Query inspector JSON tab
View data results as JSON and as data frame JSON models in the **JSON tab**.
1. Open the Query inspector and click the **JSON tab**.
1. Choose one of the following options from the **Select source** dropdown menu:
- **Panel data -** Displays a JSON object representing the data retrieved by the visualization from Explore.
- **DataFrame JSON (from query) -** Displays the raw data result set without transformations and field configuration applied.
## Query inspector Data tab
View, inspect and download raw query results in the **Data tab**.
1. Open the Query inspector and click the **Data** tab.
1. Click **Data options** to to view options under **Show data frame**.
1. Select a data results set from the dropdown menu.
1. For multiple queries or for queries multiple nodes, you can select **Series joined by time** from the dropdown to view the raw data from all of your queries at once, one result set per column. You can click any column heading to sort the data.
1. Toggle **Formatted data** to match the format in the panel.
1. Toggle **Download for Excel** to download a CSV file specifically formatted for Excel.
1. To download the results to a CSV file click **Download CSV** in the upper right of the Query inspector pane.
### Download log results as TXT
Based on the type of data source (Loki, for example), or when logs are present in the results set, Grafana generates a TXT file of log raw data results in your default browser download location. You can open it in the viewer of your choice.
1. Click **Query inspector**.
1. Click the **Data tab** to view log query results.
1. Click **Download logs**.
### Download trace results
Based on the data source type (Tempo, for example), Grafana generates a JSON file for trace results in one of these supported formats: Jaeger, Zipkin, or OTLP.
1. Click **Query inspector**.
1. Click the **Data tab** to view traces results.
1. Click **Download traces**.
docs/sources/visualizations/explore/get-started-with-explore.md
+224
View File
@@ -0,0 +1,224 @@
---
aliases:
- ../../explore/get-started-with-explore/ # /docs/grafana/next/explore/get-started-with-explore/
keywords:
- explore
- loki
- logs
labels:
products:
- cloud
- enterprise
- oss
title: Get started with Explore
refs:
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
weight: 5
---
# Get started with Explore
{{< shared id="explore-overview" >}}
Explore is your gateway for querying, analyzing, and aggregating data in Grafana. It allows you to visually explore and iterate until you develop a working query or set of queries for building visualizations and conducting data analysis. If your data source supports graph and table data, there's no need to create a dashboard, as Explore can display the results in both formats. This facilitates quick, detailed, real-time data analysis.
With Explore you can:
- Create visualizations to integrate into your dashboards.
- Create queries using mixed data sources.
- Create multiple queries within a single interface.
- Understand the shape of your data across various data sources.
- Perform real time data exploration and analysis.
Key features include:
- Query editor, based on specific data source, to create and iterate queries.
- [Query history](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/explore/query-management/) to track and maintain your queries.
- [Query inspector](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/explore/explore-inspector/) to help troubleshoot query performance.
{{< /shared >}}
Watch the following video to get started using Explore:
{{< youtube id="1q3YzX2DDM4" >}}
## Before you begin
In order to access Explore, you must have either the `editor` or `administrator` basic role or the `data sources explore` role. Refer to [Role and permissions](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/) for more information on what each role can access.
Refer to [Role-based access control (RBAC)](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/) in Grafana Enterprise to understand how you can manage Explore with role-based permissions.
## Explore elements
Explore consists of a toolbar, outline, query editor, the ability to add multiple queries, a query history and a query inspector.
- **Outline** - Keeps track of the queries and visualization panels created in Explore. Refer to [Content outline](#content-outline) for more detail.
- **Toolbar** - Provides quick access to frequently used tools and settings.
- **Data source picker** - Select a data source from the dropdown menu, or use absolute time.
- **Split** - Click to compare visualizations side by side. Refer to [Split and compare](#split-and-compare) for additional detail.
- **Add** - Click to add your exploration to a dashboard. You can also use this to declare an incident,create a forecast, detect outliers and to run an investigation.
- **Time picker** - Select a time range form the time picker. You can also enter an absolute time range. Refer to [Time picker](#time-picker) for more information.
- **Run query** - Click to run your query.
- **Query editor** - Interface where you construct the query for a specific data source. Query editor elements differ based on data source. In order to run queries across multiple data sources you need to select **Mixed** from the data source picker.
- **+ Add query** - Add additional queries.
- **+ Add from saved queries** - Add a 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. 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 >}}
- **Query history** - Query history contains the list of queries that you created in Explore. You can also add queries from the history to your saved queries. Refer to [Query history](/docs/grafana/<GRAFANA_VERSION>/explore/query-management/#query-history) for detailed information on working with your query history.
- **Query inspector** - Provides detailed statistics regarding your query. Inspector functions as a kind of debugging tool that "inspects" your query. It provides query statistics under **Stats**, request response time under **Query**, data frame details under **{} JSON**, and the shape of your data under **Data**. Refer to [Query inspector in Explore](/docs/grafana/latest/explore/explore-inspector/) for additional information.
## Access Explore
To access Explore:
1. Click on **Explore** in the left side menu.
To start with an existing query from a dashboard panel, select the Explore option from the Panel menu in the upper right. This opens an Explore page with the panel's query, enabling you to tweak or iterate the query outside your dashboard.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-panel-menu-10.1.png" class="docs-image--no-shadow" caption="Panel menu with Explore option" >}}
1. Select a data source from the drop-down in the upper left.
1. Using the query editor provided for the specific data source, begin writing your query. Each query editor differs based on each data source's unique elements.
Some query editors provide a **Kick start your query** option, which gives you a list of basic pre-written queries. Refer to [Use query editors](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/#use-query-editors) to see how to use various query editors. For general information on querying data sources in Grafana, refer to [Query and transform data](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/).
Based on specific data source, certain query editors allow you to select the label or labels to add to your query. Labels are fields that consist of key/value pairs representing information in the data. Some data sources allow for selecting fields.
1. Click **Run query** in the upper right to run your query.
## Content outline
The content outline is a side navigation bar that keeps track of the queries and visualizations you created in Explore. It allows you to navigate between them quickly.
The content outline works in a split view, with a separate outline generated for each pane.
To open the content outline:
1. Click the Outline button in the top left corner of the Explore screen.
You can then click on any panel icon in the content outline to navigate to that panel.
## Split and compare
The split view enables easy side-by-side comparison of visualizations or simultaneous viewing of related data on a single page.
To open the split view:
1. Click the split button to duplicate the current query and split the page into two side-by-side queries.
1. Run and re-run queries as often as needed.
You can select a different data source, or different metrics and label filters for the new query, allowing you to compare the same query across two different servers or compare the staging environment with the production environment.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-explore-split-10.1.png" max-width= "950px" caption="Screenshot of Explore screen split" >}}
You can also link the time pickers for both panels by clicking on one of the time-sync buttons attached to the time pickers. When linked, changing the time in one panel automatically updates the other, keeping the start and end times synchronized. This ensures that both split panels display data for the same time interval.
Click **Close** to quit split view.
## Time picker
Use the time picker to select a time range for your query. The default is **last hour**. You can select a different option from the dropdown or use an absolute time range. You can also change the timezone associated with the query, or use a fiscal year.
1. Click **Change time settings** to change the timezone or apply a fiscal year.
Refer to [Set dashboard time range](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/use-dashboards/#set-dashboard-time-range) for more information on absolute and relative time ranges. You can also [control the time range using a URL](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/use-dashboards/#control-the-time-range-using-a-url).
## Mixed data source
Select **Mixed** from the data source dropdown to run queries across multiple data sources in the same panel. When you select Mixed, you can select a different data source for each new query that you add.
## Share Explore URLs
When using Explore, the URL in the browser address bar updates as you make changes to the queries. You can share or bookmark this URL.
{{< admonition type="note" >}}
Explore may generate long URLs, which some tools, like messaging or videoconferencing applications, might truncate due to fixed message lengths. In such cases, Explore displays a warning and loads a default state.
If you encounter issues when sharing Explore links in these applications, you can generate shortened links. See [Share shortened link](#share-shortened-link) for more information.
{{< /admonition >}}
### Generate Explore URLs from external tools
Because Explore URLs have a defined structure, you can build a URL from external tools and open it in Grafana. The URL structure is:
```
http://<grafana_url>/explore?panes=<panes>&schemaVersion=<schema_version>&orgId=<org_id>
```
where:
- `org_id` is the organization ID
- `schema_version` is the schema version (should be set to the latest version which is `1`)
- `panes` is a URL-encoded JSON object of panes, where each key is the pane ID and each value is an object matching the following schema:
```
{
datasource: string; // the pane's root datasource UID, or `-- Mixed --` for mixed datasources
queries: {
refId: string; // an alphanumeric identifier for this query, must be unique within the pane, i.e. "A", "B", "C", etc.
datasource: {
uid: string; // the query's datasource UID ie: "AD7864H6422"
type: string; // the query's datasource type-id, i.e: "loki"
}
// ... any other datasource-specific query parameters
}[]; // array of queries for this pane
range: {
from: string; // the start time, in milliseconds since epoch
to: string; // the end time, in milliseconds since epoch
}
}
```
{{< admonition type="note" >}}
The `from` and `to` also accept relative ranges defined in [Time units and relative ranges](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/use-dashboards/#time-units-and-relative-ranges).
{{< /admonition >}}
## Share shortened link
{{< admonition type="note" >}}
Available in Grafana 7.3 and later versions.
{{< /admonition >}}
The Share shortened link capability allows you to create smaller and simpler URLs of the format `/goto/:uid` instead of using longer URLs with query parameters. To create a shortened link to the executed query, click the **Share** option in the Explore toolbar.
A shortened link that's not accessed automatically gets deleted after a [configurable period](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#short_links), which defaults to seven days. However, if the link is accessed at least once, it will not be deleted.
### Share shortened links with absolute time
{{< admonition type="note" >}}
Available in Grafana 10.3 and later versions.
{{< /admonition >}}
Shortened links have two options: relative time (e.g., from two hours ago to now) or absolute time (e.g., from 8am to 10am). By default, sharing a shortened link copies the selected time range, whether it's relative or absolute.
To create a short link with an absolute time:
1. Click the dropdown button next to the share shortened link button.
1. Select one of the options under **Time-Sync URL Links**.
This ensures that anyone receiving the link will see the same data you see, regardless of when they open it. Your selected time range will remain unaffected.
## Next steps
Now that you are familiar with Explore you can:
- [Build dashboards](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/)
- Create a wide variety of [visualizations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/)
- [Work with logs](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/explore/logs-integration/)
- [Work with traces](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/explore/trace-integration/)
- [Create and use correlations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/explore/correlations-editor-in-explore/)
docs/sources/visualizations/explore/logs-integration.md
+197
View File
@@ -0,0 +1,197 @@
---
description: Logs in Explore
keywords:
- explore
- logs
labels:
products:
- cloud
- enterprise
- oss
title: Logs in Explore
weight: 25
aliases:
- ../../explore/logs-integration/ # /docs/grafana/next/explore/logs-integration/
---
# Logs in Explore
Explore is a powerful tool for logging and log analysis. It allows you to investigate logs from different data sources including:
- [Loki](/docs/grafana/<GRAFANA_VERSION>/datasources/loki/)
- [Elasticsearch](/docs/grafana/<GRAFANA_VERSION>/datasources/elasticsearch/)
- [Cloudwatch](/docs/grafana/<GRAFANA_VERSION>/datasources/aws-cloudwatch/)
- [InfluxDB](/docs/grafana/<GRAFANA_VERSION>/datasources/influxdb/)
- [Azure Monitor](/docs/grafana/<GRAFANA_VERSION>/datasources/azure-monitor/)
- [ClickHouse](https://github.com/grafana/clickhouse-datasource)
With Explore, you can efficiently monitor, troubleshoot, and respond to incidents by analyzing your logs and identifying the root causes. It also helps you to correlate logs with other telemetry signals such as metrics, traces or profiles, by viewing them side-by-side.
The results of log queries display as individual log lines and as a graph showing the logs volume for the selected time period.
## Logs volume
When working with data sources that support a full range logs volume, Explore automatically displays a graph showing the log distribution for all submitted log queries. This feature is currently supported by the Elasticsearch and Loki data sources.
{{< admonition type="note" >}}
In Loki, generating the full range log volume via a metric query can be resource-intensive, depending on the time range queried. This is especially challenging for smaller Loki installations. To mitigate this, we recommend that you use a proxy like [nginx](https://www.nginx.com/) in front of Loki with a timeout like 10ss. Log volume histogram queries can be identified by looking for queries with the HTTP header `X-Query-Tags` with value `Source=logvolhist`; these headers are added by Grafana to all log volume histogram queries.
{{< /admonition >}}
If the data source doesn't support loading the full range logs volume, the logs model calculates a time series by counting log rows and organizing them into buckets based on an automatically calculated time interval. The timestamp of the first log row is used to anchor the start of the logs volume in the results. The end of the time series is anchored to the time picker's **To** range. This way, you can still analyze and visualize log data efficiently even when the data source doesn't offer full range support.
## Logs
The following sections provide detailed explanations on how to visualize and interact with individual logs in Explore.
### Logs navigation
Logs navigation, located at the right side of the log lines, can be used to easily request additional logs by clicking **Older logs** at the bottom of the navigation. This is especially useful when you reach the line limit and you want to see more logs. Each request run from the navigation displays in the navigation as separate page. Every page shows `from` and `to` timestamps of the incoming log lines. You can see previous results by clicking on each page. Explore caches the last five requests run from the logs navigation so you're not re-running the same queries when clicking on the pages, saving time and resources.
![Navigate logs in Explore](/static/img/docs/explore/navigate-logs-8-0.png)
### Visualization options
You have the option to customize the display of logs and choose which columns to show. Following is a list of available options.
| Option | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Time** | Shows or hides the time column. This is the timestamp associated with the log line as reported from the data source. |
| **Unique labels** | Shows or hides the unique labels column that includes only non-common labels. All common labels are displayed above. |
| **Wrap lines** | Set this to `true` if you want the display to use line wrapping. If set to `false`, it will result in horizontal scrolling. |
| **Prettify JSON** | Set this to `true` to pretty print all JSON logs. This setting does not affect logs in any format other than JSON. |
| **Deduplication** | Log data can be very repetitive. Explore hides duplicate log lines using a few different deduplication algorithms. **Exact** matches are done on the whole line except for date fields. **Numbers** matches are done on the line after stripping out numbers such as durations, IP addresses, and so on. **Signature** is the most aggressive deduplication as it strips all letters and numbers and matches on the remaining whitespace and punctuation. |
| **Display results order** | You can change the order of received logs from the default descending order (newest first) to ascending order (oldest first). |
### Download log lines
This feature lets you save log data for further analysis or to share it with others in a convenient and accessible format.
In Explore there are three export options:
- **TXT** - will export the data as visible on the screen, meaning it will take into account formatting, like `line_format`.
- **JSON** - will export the raw data, regardless of the formatting, like `line_format`.
- **CSV** - will export the raw data, regardless of the formatting, like `line_format`.
Click **Download** and select `TXT`, `JSON` or `CSV` to download log results.
### Log result meta information
The following meta information displays above the retrieved log lines:
- **Number of received logs -** Indicates the total count of logs received for the current query or time range.
- **Error -** Displays any errors in your log results.
- **Common labels -** Displays common labels.
- **Total bytes processed -** Represents the cumulative size of the log data processed in bytes.
{{< admonition type="note" >}}
The availability of certain metadata may vary depending on the data source, so you might only see details related to those specific data sources.
{{< /admonition >}}
### Escaping newlines
Explore automatically detects some incorrectly escaped sequences in log lines, such as newlines (`\n`, `\r`) or tabs (`\t`). When it detects such sequences, Explore provides an **Escape newlines** option.
To automatically fix incorrectly escaped sequences that Explore has detected:
1. Click **Escape newlines** to replace the sequences.
2. Review returned log lines.
Explore replaces these sequences, changing the option from **Escape newlines** to **Remove escaping**. Assess the changes, as the parsing may not be accurate based on the input. To revert the replacements, click **Remove escaping**.
### Log level
For logs where a `level` label is specified, the value of this label is used to determine the log level and update the color of each log line accordingly.
If the log doesn't have a specified level label, Grafana attempts to determine if its content matches any of the supported expressions.
Refer to the following table for more information. The log level is always determined by the first match. If Grafana isn't able to infer a log level field, it gets visualized as an unknown log level.
{{< admonition type="tip" >}}
When using the Loki data source, if `level` is part of your log line, you can use parsers such as `json`, `logfmt`, or `regex` to extract the level information into a level label. This label is used to determine the level value, allowing the histogram to display the various log levels as separate bars.
{{< /admonition >}}
**Log levels supported and mapping of log level abbreviation and expressions:**
| Log level | Color | Supported expressions |
| :-------- | :--------- | ---------------------------------------------- |
| critical | purple | emerg, fatal, alert, crit, critical, 0, 1, 2 |
| error | red | err, eror, error, 3 |
| warning | yellow | warn, warning, 4 |
| info | green | info, information, informational, notice, 5, 6 |
| debug | blue | dbug, debug, 7 |
| trace | light blue | trace |
| unknown | grey | \* |
### Highlight searched words
When your query includes specific words or expressions for keyword search, Explore highlights them in log lines to enhance visibility. This highlighting feature facilitates easier identification and focus on the relevant content within your logs.
{{< admonition type="note" >}}
The ability to highlight search words varies depending on data source. For some data sources, the highlighting of search words may not be available.
{{< /admonition >}}
### Log details view
In Explore, each log line has an expandable section called **Log details** that you open by clicking on the log line. The Log details view provides additional information and exploration options in the form of **Fields** and **Links** attached to the log lines, enabling a more robust interaction and analysis.
#### Fields
Within the **Log details** view, you have the ability to filter the displayed fields in two ways: a positive filter, which focuses on an specific field and a negative filter, which excludes certain fields.
These filters modify the corresponding query that generated the log line, incorporating equality and inequality expressions accordingly.
If the data source supports it, as is the case with Loki and Elasticsearch, log details will verify whether the field is already included in the current query, indicating an active state for positive filters. This enables you to toggle it off from the query or convert the filter expression from positive to negative as necessary.
Click the **eye icon** to select a subset of fields to visualize in the logs list instead of the complete log line.
Each field has a **stats icon**, which displays ad-hoc statistics in relation to all displayed logs.
#### Links
Grafana provides data links or correlations, allowing you to convert any part of a log message into an internal or external link. These links enable you to navigate to related data or external resources, offering a seamless and convenient way to explore additional information.
{{< figure src="/static/img/docs/explore/data-link-9-4.png" max-width="800px" caption="Data link in Explore" >}}
### Log context
Log context is a feature that displays additional lines of context surrounding a log entry that matches a specific search query. This helps in understanding the context of the log entry and is similar to the `-C` parameter in the `grep` command.
Toggle **Wrap lines** if you encounter long lines of text that make it difficult to read and analyze the context around log entries. By enabling this toggle, Grafana automatically wraps long lines of text to fit within the visible width of the viewer, making the log entries easier to read and understand.
Click **Open in split view** to execute the context query for a log entry in a split screen in the Explore view. Clicking this button opens a new Explore pane with the context query displayed alongside the log entry, making it easier to analyze and understand the surrounding context.
Use Command-click or Ctrl+click to open the log context query in a new browser to view the context model. All previously selected filters get applied.
### Copy log line
Click **Copy log line** to copy the content of a selected log line to the clipboard.
### Copy link to log line
Linking log lines in Grafana allows you to quickly navigate to specific log entries for detailed and precise analysis. Click **Copy shortlink** to generate and copy a [short URL](/docs/grafana/<GRAFANA_VERSION>/developers/http_api/short_url/) that provides direct access to the exact log entry within an absolute time range. When you open the link, Grafana automatically scrolls to the corresponding log line and highlights it in blue, making it easy to identify and focus on relevant information.
{{< admonition type="note" >}}
The short URL feature is currently only supported in Loki and other data sources that provide an `id` field.
{{< /admonition >}}
## Live tailing
Use the **Live tail** feature to view real-time logs from data sources.
1. Click **Live** in the Explore toolbar to switch to Live tail view.
1. In **Live tail view**, new logs appear at the bottom of the screen, and have a contrasting background, allowing you to easily track what's new.
1. Click **Pause** to pause live tailing and explore previous logs without interruptions. or simply scroll through the logs view.
1. Click **Clear logs** to remove all displayed logs. This action resets the log view and provides a clean slate to continue your log analysis
1. Click **Resume** to resume live tailing and continue viewing real-time logs.
1. Click **Stop** to exit live tailing and return to the standard Explore view.
The **Live tailing feature** allows you to monitor the latest logs in real-time, making it easier to track events as they occur and promptly detect issues.
{{< video-embed src="/static/img/docs/v95/explore_live_tailing.mp4" >}}
### Logs sample
If the selected data source supports log samples and both log and metric queries, you will automatically see log line samples that contribute to the visualized metrics for metric queries. **This feature is currently only supported by the Loki data source.**
### Switch from metrics to logs
If you are transitioning from a metrics data source that implements `DataSourceWithQueryExportSupport` (such as Prometheus) to a logging data source that supports `DataSourceWithQueryImportSupport` (such as Loki), Explore retains the labels from your query that exist in the logs and use them to query the log streams.
For example, after switching to the Loki data source, the Prometheus query `grafana_alerting_active_alerts{job="grafana"}` changes to `{job="grafana"}`. This will retrieve a set of logs within the specified time range, which can be searched using grep or text search.
docs/sources/visualizations/explore/query-management.md
+103
View File
@@ -0,0 +1,103 @@
---
keywords:
- explore
- loki
- logs
labels:
products:
- cloud
- enterprise
- oss
title: Query management in Explore
weight: 10
refs:
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
aliases:
- ../../explore/query-management/ # /docs/grafana/next/explore/query-management/
---
# Query management in Explore
Grafana Explore provides a variety of tools to help manage your queries.
{{< admonition type="note" >}}
For help with debugging queries, Explore allows you to investigate query requests and responses, as well as query statistics, via the Query inspector. Refer to [Query inspector in Explore](/docs/grafana/<GRAFANA_VERSION>/explore/explore-inspector/) for more information.
{{< /admonition >}}
## Query history
Query history contains the list of queries that you created in Explore. This history is stored in the Grafana database and isn't shared with other users. The retention period for a query history is **two weeks**. Queries older than two weeks are automatically deleted.
{{< admonition type="note" >}}
Starred queries aren't subject to the two-week retention period and aren't deleted.
{{< /admonition >}}
To view your query history:
1. Go to the Explore page.
1. Click **Query history**.
The Query history pane opens at the bottom of the page, and contains the following tabs:
- **Query history tab-** Contains a history of all your queries, with options for searching and managing them.
- **Starred tab -** Contains all of your starred queries.
- **Settings tab-** Provides customizable options for your query history.
### Query history tab
The Query history depicts a history of your queries for the past two weeks, unless the query is starred, which means it doesn't get deleted. For each individual query, you can:
- Run and re-run the query.
- Create and/or edit a comment.
- Copy a query to the clipboard.
- Copy a shortened link with the query to the clipboard.
- Delete a query.
- Star a query.
- Add a query from your history to your [saved queries](ref:saved-queries).
By default, query history shows you newest queries first. Click the sort box in the upper right to change to **Oldest first** to older queries first. You can search your queries using keywords.
### Query history Starred tab
All starred queries are displayed in the **Starred** tab. This gives quick access to key or favorite queries without having to rewrite them.
You also have the option to switch the data source and run a starred query.
#### Filter query history
Filter query history in both the **Query history** and **Starred** tabs by data source name:
1. Click the **Filter queries for specific data source(s)** field.
1. Select the data source in the dropdown by which you want to filter your history. You can select multiple data sources.
{{< admonition type="note" >}}
Queries with the **Mixed** data source appear only when filtering for "Mixed" and not when filtering by individual data source.
{{< /admonition >}}
You can also filter queries by date using the vertical slider:
- Drag the bottom circle to adjust the start date.
- Drag the top circle to adjust the end date.
#### Search in query history
Use **Search queries** in both the **Query history** and **Starred** tabs to search your query history and comments using keywords.
1. Click in the **Search queries** field.
1. Type the keyword(s) or term you are want to search for in search field.
### Query history Settings tab
You can customize your query history in the **Settings** tab.
Toggle **Change the default active tab from "Query history" to "Starred"** to make the **Starred tab** the default active tab.
{{< admonition type="note" >}}
Query history settings are global, and applied to both panels in split mode.
{{< /admonition >}}
<!-- All queries that have been starred in the Query history tab are displayed in the Starred tab. This allows you to access your favorite queries faster and to reuse these queries without typing them from scratch. -->
docs/sources/visualizations/explore/trace-integration.md
+192
View File
@@ -0,0 +1,192 @@
---
keywords:
- explore
- trace
labels:
products:
- cloud
- enterprise
- oss
title: Traces in Explore
weight: 40
aliases:
- ../../explore/trace-integration/ # /docs/grafana/next/explore/trace-integration/
---
# Traces in Explore
You can use Explore to query and visualize traces from tracing data sources. Supported data sources include:
- [Tempo](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/)
- [Jaeger](/docs/grafana/<GRAFANA_VERSION>/datasources/jaeger/)
- [Zipkin](/docs/grafana/<GRAFANA_VERSION>/datasources/zipkin/)
- [X-Ray](https://grafana.com/grafana/plugins/grafana-x-ray-datasource)
- [Azure Monitor](/docs/grafana/latest/datasources/azure-monitor/)
- [ClickHouse](https://github.com/grafana/clickhouse-datasource)
- [New Relic](/docs/plugins/grafana-newrelic-datasource/latest/)
- [Infinity](/docs/plugins/yesoreyeram-infinity-datasource/latest/)
Here are some references to learn more about traces and how you can use them:
- [Introduction to tracing](https://grafana.com/docs/tempo/<TEMPO_VERSION>/introduction/)
- [Trace structure](https://grafana.com/docs/tempo/<TEMPO_VERSION>/traceql/trace-structure/#trace-structure)
- [Traces and telemetry](https://grafana.com/docs/tempo/<TEMPO_VERSION>/introduction/telemetry/)
- [Using traces to find solutions to problems](https://grafana.com/docs/tempo/<TEMPO_VERSION>/introduction/solutions-with-traces/)
- [Best practices for tracing](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/tracing-best-practices/)
## Query editors
You can query and search tracing data using a data source's query editor. Note that data sources in Grafana have unique query editors.
For information on how to use the query editor to create queries for tracing data sources, refer to the documentation for each individual data source.
## Trace view
Grafana's trace view provides an overview of a request as it travels through your system. The following sections provide detail on various elements of the trace view.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view.png" class="docs-image--no-shadow" max-width= "900px" caption="Trace view" >}}
### Header
The trace view header includes the following:
- **Header title** - Shows the name of the root span and trace ID.
- **Search** - Highlights spans containing the searched text.
- **Metadata** - Various metadata about the trace.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-header.png" class="docs-image--no-shadow" max-width= "750px" caption="Trace view header" >}}
### Minimap
**Minimap** displays a condensed view of the trace timeline. Drag your mouse over the minimap to zoom into a smaller time range. This also updates the main timeline, making it easier to view shorter spans
When zoomed in, hovering over the minimap displays **Reset selection**, which resets the zoom.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-minimap.png" class="docs-image--no-shadow" max-width= "900px" caption="Trace view minimap example" >}}
### Timeline
Timeline shows list of spans within the trace. Each span row consists of the following components:
- **Expand children** - Expands or collapses all the children spans of the selected span.
- **Service name** - Name of the service logged the span.
- **Operation name** - Name of the operation that this span represents.
- **Span duration bar** - Visual representation of the operation duration within the trace.
Click anywhere on the span row to reveal span details.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-timeline.png" class="docs-image--no-shadow" max-width= "900px" caption="Trace view timeline" >}}
### Span details
Traces are composed of one or more spans.
A span is a unit of work within a trace that has a start time relative to the beginning of the trace, a duration and an operation name for the unit of work.
It usually has a reference to a parent span, unless it’s the first span, the root span, in a trace.
It frequently includes key/value attributes that are relevant to the span itself, for example the HTTP method used in the request, as well as other metadata such as the service name, sub-span events, or links to other spans.
You can expand any span in a trace and view the details, including the span and resource attributes.
For more information about spans and traces, refer to [Introduction to tracing](https://grafana.com/docs/tempo/latest/introduction/) in the Tempo documentation.
Span details include span attributes, resource attributes, events, and links.
#### Span and resource attributes
**Span attributes** are key-value pairs that provide metadata about a specific span. They give context to the operation being performed, such as information about the request, response, or any relevant operational details. For example, if the span deals with calling another service via HTTP, an attribute could include the HTTP URL (maybe as the span attribute key `http.url`) and the HTTP status code returned (as the span attribute `http.status_code`).
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-span-span-attributes.png" class="docs-image--no-shadow" max-width= "900px" caption="Trace view span attributes" >}}
**Resource attributes** are key-value pairs that describe the environment or entity that is producing the trace. They capture static information about the origin of traces, like the application name or the service version.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-span-resource-attributes.png" class="docs-image--no-shadow" max-width= "900px" caption="Trace view span resource attributes" >}}
Span attributes are specific to a particular operation, while resource attributes are associated with the whole trace or the entire service emitting the spans. Refer to [Span and resource attributes](/docs/tempo/<TEMPO_VERSION>/operations/best-practices/#span-and-resource-attributes) for more detail.
#### Events
Events are log-like records attached to a span that represent an occurrence during its execution. They record notable moments or occurrences within the span's lifecycle, such as errors, warnings, or checkpoints. If an error occurs during an operation, an event can be added to the span to indicate what went wrong and when. Events include a timestamp, name, and key-value pairs attributes that provide additional context or details about the event.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-span-events.png" class="docs-image--no-shadow" max-width= "900px" caption="Trace view span events" >}}
#### Links
Links show relationships between spans that are not in a direct parent-child relationship. They represent associations between spans that happen concurrently or across separate trace trees, linking traces that originated from separate sources but are logically connected, such as background job processing initiated from a web request. You might use links when a trace passes through an asynchronous queue or when correlating traces from different services.
### Span filters
Span filters allow you to refine the spans displayed in the trace timeline viewer.
The more filters you add, the more specific the filtered spans become.
Click on a trace to access Span filters.
![Screenshot of span filtering](/media/docs/tempo/screenshot-grafana-tempo-span-filters-v10-1.png)
You can add one or more of the following filters:
- **Service name** - Filter by selecting a service name from the dropdown.
- **Span name** - Filter by selecting a span name from the dropdown.
- **Duration** - Filter by duration. Accepted units include ns, us, ms, s, m, h.
- **Tags** - Filter by tags, process tags, or log fields in your span.
To only show the spans you have matched, toggle **Show matches only**.
Refer to [Span filters](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/span-filters/) for more in depth information.
Watch the following video to learn more about filtering trace spans in Grafana:
{{< youtube id="VP2XV3IIc80" >}}
### Trace to logs
You can navigate from a span in a trace view directly to logs relevant for that span.
This feature is available for the Tempo, Jaeger, and Zipkin data sources.
Refer to each individual data source's documentation for configuration instructions.
Click the document icon to open a split view in Explore with the configured data source and query relevant logs for the span.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-trace-to-logs.png" class="docs-image--no-shadow" max-width= "900px" caption="Trace to logs" >}}
### Trace to metrics
You can navigate from a span in a trace view directly to metrics relevant for that span.
This feature is available for the Tempo, Jaeger, and Zipkin data sources.
Refer to each individual data source's documentation for configuration instructions.
For Tempo, refer to [Trace to metrics configuration](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/configure-tempo-data-source/#trace-to-metrics).
### Trace to profiles
Using Trace to profiles, you can use Grafana’s ability to correlate different signals by adding the functionality to link between traces and profiles.
For Tempo refer to [Trace to profiles](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/configure-tempo-data-source#trace-to-profiles) for configuration instructions.
{{< figure src="/static/img/docs/tempo/profiles/tempo-trace-to-profile.png" max-width="900px" class="docs-image--no-shadow" alt="Selecting a link in the span queries the profile data source" >}}
### Trace correlations
You can use [correlations](/docs/grafana/<GRAFANA_VERSION>/administration/correlations/) to define custom links that appear in the trace view based on trace and span information.
For Tempo, refer to [Trace correlations](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/traces-in-grafana/trace-correlations/) for configuration instructions.
{{< figure src="/media/docs/tempo/screenshot-grafana-trace-view-correlations.png" max-width="900px" class="docs-image--no-shadow" alt="Using correlations for a trace" >}}
## Node graph
You can also expand the node graph for a displayed trace. If the data source supports it, this displays spans of the trace as nodes in the graph, or provides additional context, such as a service graph based on the current trace.
Refer to [Node graph](/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/node-graph/) for additional information.
{{< admonition type="note" >}}
The node graph requires data to be returned from the data source in a specific format to display correctly. Refer to [Data API](/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/node-graph/#data-api), [Nodes data frame structure](/docs/grafana/latest/panels-visualizations/visualizations/node-graph/#nodes-data-frame-structure) and [Node graph data requirements](/docs/grafana/latest/panels-visualizations/visualizations/node-graph/#data-requirements) for additional information and configuration instructions.
{{< /admonition >}}
{{< figure src="/media/docs/tempo/screenshot-grafana-node-graph.png" class="docs-image--no-shadow" max-width= "900px" caption="Node graph" >}}
## Service graph
A service graph visualizes rates, error rates, and durations (RED), along with service relationships.
After the requirements are configured, this pre-configured view is immediately available.
For additional information refer to the following documentation:
- [Service Graph and Service Graph view](/docs/grafana/<GRAFANA_VERSION>/datasources/tempo/service-graph/)
- [Service graph view](/docs/tempo/<TEMPO_VERSION>/metrics-generator/service-graph-view/) in Tempo documentation
{{< figure src="/static/img/docs/grafana-cloud/apm-overview.png" class="docs-image--no-shadow" max-width= "900px" caption="Service graph view" >}}
docs/sources/visualizations/panels-visualizations/_index.md
+73
View File
@@ -0,0 +1,73 @@
---
aliases:
- ../dashboards/configure-panels-visualizations/ # /docs/grafana/next/dashboards/configure-panels-visualizations/
- ../features/panels/panels/ # /docs/grafana/next/features/panels/panels/
- ../panels/ # /docs/grafana/next/panels/
- ../panels-visualizations/ # /docs/grafana/next/panels-visualizations/
keywords:
- grafana
- configure
- panels
- visualizations
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Panels and visualizations
title: Panels and visualizations
description: Learn about and configure panels and visualizations
weight: 80
hero:
title: Panels and visualizations
level: 1
width: 110
height: 110
description: >-
Easily collect, correlate, and visualize data so you can make informed decisions in real time.
cards:
title_class: pt-0 lh-1
items:
- title: Visualizations
href: ./visualizations/
description: Learn about all the visualizations available in Grafana, including which visualizations are ideal for different datasets and how to configure their options.
height: 24
- title: Panel overview
href: ./panel-overview/
description: Learn about the features of the panel.
height: 24
- title: Panel editor
href: ./panel-editor-overview/
description: Learn about the features of the panel editor and how to begin editing a panel.
height: 24
- title: Configure standard options
href: ./configure-standard-options/
description: Learn about configuring standard options like units, field display names, and colors.
height: 24
- title: Query and transform data
href: ./query-transform-data/
description: Learn about querying and transforming your data to refine your visualizations.
height: 24
refs:
query:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/
---
{{< docs/hero-simple key="hero" >}}
---
## Overview
Panels are the basic building block in Grafana dashboards, composed of a [query](ref:query) and a visualization, a graphical representation of query results.
Visualizations provide you several different ways to present your data within a panel, depending on what best suits the data and your needs. Grafana’s growing suite of visualizations, ranging from time series graphs to heatmaps to cutting-edge 3D charts, help you decode complex datasets.
Panels offer a wide variety of formatting and styling options from applying colors based on field values to custom units. Each visualization also comes with options specific to it that give you further control over how your data is displayed. With Grafana panels and visualizations, you can easily get the information you need from your data and optimize performance.
## Explore
{{< card-grid key="cards" type="simple" >}}
docs/sources/visualizations/panels-visualizations/configure-data-links/index.md
+355
View File
@@ -0,0 +1,355 @@
---
aliases:
- ../../linking/data-link-variables/ # /docs/grafana/next/linking/data-link-variables/
- ../../linking/data-links/ # /docs/grafana/next/linking/data-links/
- ../../panels/configure-data-links/ # /docs/grafana/next/panels/configure-data-links/
- ../../reference/datalinks/ # /docs/grafana/next/reference/datalinks/
- ../../variables/url-variables/ # /docs/grafana/next/variables/url-variables/
- ../../variables/variable-types/url-variables/ # /docs/grafana/next/variables/variable-types/url-variables/
- ../../panels-visualizations/configure-data-links/ # /docs/grafana/next/panels-visualizations/configure-data-links/
keywords:
- grafana
- url variables
- variables
- data link
- documentation
- playlist
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure data links and actions
title: Configure data links and actions
description: Configure data links to create links between dashboards and link to external resources
weight: 80
refs:
api-settings:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/#button-api-options
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/latest/panels-visualizations/visualizations/canvas/#button-api-options
global-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#__from-and-__to
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#__from-and-__to
heatmap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/heatmap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/heatmap/
templates-and-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
bar-gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-gauge/
canvas:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/canvas/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/gauge/
google-cloud-monitoring:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/google-cloud-monitoring/query-editor/#deep-link-from-grafana-panels-to-the-google-cloud-console-metrics-explorer
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/google-cloud-monitoring/query-editor/#deep-link-from-grafana-panels-to-the-google-cloud-console-metrics-explorer
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
xy-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/xy-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/xy-chart/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
geomap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/geomap/
stat:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/stat/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/stat/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
cloudwatch:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/aws-cloudwatch/query-editor/#deep-link-grafana-panels-to-the-cloudwatch-console-1
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/aws-cloudwatch/query-editor/#deep-link-grafana-panels-to-the-cloudwatch-console-1
table:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/table/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/table/
histogram:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
pie-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/pie-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/pie-chart/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
---
# Configure data links and actions
_Data links_ allow you to link to other panels, dashboards, and external resources and _actions_ let you trigger basic, unauthenticated, API calls.
In both cases, you can carry out these tasks while maintaining the context of the source panel.
## Data links
With data links, you can create links that include the series name or even the value under the cursor. For example, if your visualization shows four servers, you can add a data link to one or two of them.
The link itself is accessible in different ways depending on the visualization. For the time series visualization you need to click a data point or line:
![Time series visualization with a data link displayed](/media/docs/grafana/panels-visualizations/screenshot-time-series-data-link-v10.3.png)
For visualizations like stat, gauge, or bar gauge you can click anywhere on the visualization to open the context menu:
![Stat visualization with a data link displayed](/media/docs/grafana/panels-visualizations/screenshot-stat-data-link-v10.3.png)
If there's only one data link in the visualization, clicking anywhere on the visualization opens the link rather than the context menu.
### Supported visualizations
You can configure data links for the following visualizations:
{{< column-list >}}
- [Bar chart](ref:bar-chart)
- [Bar gauge](ref:bar-gauge)
- [Candlestick](ref:candlestick)
- [Canvas](ref:canvas)
- [Gauge](ref:gauge)
- [Geomap](ref:geomap)
- [Heatmap](ref:heatmap)
- [Histogram](ref:histogram)
- [Pie chart](ref:pie-chart)
- [Stat](ref:stat)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Table](ref:table)
- [Time series](ref:time-series)
- [Trend](ref:trend)
- [XY chart](ref:xy-chart)
{{< /column-list >}}
## Actions
Using actions, you can trigger processes like starting or shutting down a server, directly from a dashboard panel. [API settings](ref:api-settings) are configured in the **Add action** dialog box. You can also pass variables in the API editor.
### Supported visualizations
You can configure actions for the following visualizations:
{{< column-list >}}
- [Bar chart](ref:bar-chart)
- [Candlestick](ref:candlestick)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Table](ref:table)
- [Time series](ref:time-series)
- [Trend](ref:trend)
- [XY chart](ref:xy-chart)
{{< /column-list >}}
## Data link and action variables {#data-link-variables}
Variables in data links and actions let you send people to a detailed dashboard or trigger an API call with preserved data filters. For example, you could use variables to specify a label, time range, series, or variable selection.
To see a list of available variables, enter `$` in the data link or action **URL** field.
{{< admonition type="note" >}}
These variables changed in 6.4 so if you have an older version of Grafana, then use the version picker to select docs for an older version of Grafana.
{{< /admonition >}}
Azure Monitor, [CloudWatch](ref:cloudwatch), and [Google Cloud Monitoring](ref:google-cloud-monitoring) have pre-configured data links called _deep links_.
You can also use template variables in your data links or actions URLs. For more information, refer to [Templates and variables](ref:templates-and-variables).
### Time range panel variables
These variables allow you to include the current time range in the data link or action URL:
| Variable | Description |
| ------------------ | ------------------------------------------------------------------------ |
| `__url_time_range` | Current dashboard's time range (for example, `?from=now-6h&to=now`) |
| `__from` | For more information, refer to [Global variables](ref:global-variables). |
| `__to` | For more information, refer to [Global variables](ref:global-variables). |
When you create data links and actions using time range variables like `__url_time_range` in the URL, you have to form the query parameter syntax yourself; that is, you must format the URL by appending query parameters using the question mark (`?`) and ampersand (`&`) syntax. These characters aren't automatically generated.
### Series variables
Series-specific variables are available under `__series` namespace:
| Variable | Description |
| --------------- | ---------------------- |
| `__series.name` | Series name to the URL |
### Field variables
Field-specific variables are available under `__field` namespace:
| Variable | Description |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `__field.name` | The name of the field |
| `__field.labels.<LABEL>` | Label's value to the URL. If your label contains dots, then use `__field.labels["<LABEL>"]` syntax. |
### Value variables
Value-specific variables are available under `__value` namespace:
| Variable | Description |
| ----------------- | --------------------------------------------------------------------------------- |
| `__value.time` | Value's timestamp (Unix ms epoch) to the URL (for example, `?time=1560268814105`) |
| `__value.raw` | Raw value |
| `__value.numeric` | Numeric representation of a value |
| `__value.text` | Text representation of a value |
| `__value.calc` | Calculation name if the value is result of calculation |
Using value-specific variables in data links and actions can show different results depending on the set option of Tooltip mode.
When you create data links and actions using time range variables like `__value.time` in the URL, you have to form the query parameter syntax yourself; that is, you must add the question mark (`?`) and ampersand (`&`). These characters aren't automatically generated.
### Data variables
To access values and labels from other fields use:
| Variable | Description |
| --------------------------------- | ------------------------------------------ |
| `__data.fields[i]` | Value of field `i` (on the same row) |
| `__data.fields["NameOfField"]` | Value of field using name instead of index |
| `__data.fields[1].labels.cluster` | Access labels of another field |
### Template variables
When linking to another dashboard that uses template variables, select variable values for whoever clicks the link.
`${var-myvar:queryparam}` - where `var-myvar` is the name of the template variable that matches one in the current dashboard that you want to use.
| Variable state | Result in the created URL |
| ------------------------ | ----------------------------------- |
| selected one value | `var-myvar=value1` |
| selected multiple values | `var-myvar=value1&var-myvar=value2` |
| selected `All` | `var-myvar=All` |
If you want to add all of the current dashboard's variables to the URL, then use `${__all_variables}`.
When you link to another dashboard, ensure that:
- The target dashboard has the same variable name. If it doesn't (for example, `server` in the source dashboard and `host` in the target), you must align them or explicitly map values (for example, `&var-host=${server}`).
- You use the variable _name_, and not the label. Labels are only used as display text and aren't recognized in URLs.
For example, if you have a variable with the name `var-server` and the label `ChooseYourServer`, you must use `var-server` in the URL, as shown in the following table:
| Correct link | Incorrect link |
| ---------------------------------------------- | -------------------------------------------------------- |
| `/d/xxxx/dashboard-b?orgId=1&var-server=web02` | `/d/xxxx/dashboard-b?orgId=1&var-ChooseYourServer=web02` |
## Add data links or actions {#add-a-data-link}
The following tasks describe how to configure data links and actions.
{{< tabs >}}
{{< tab-content name="Add data links" >}}
To add a data link, follow these steps:
1. Navigate to the panel to which you want to add the data link.
1. Hover over any part of the panel to display the menu icon in the upper-right corner.
1. Click the menu icon and select **Edit** to open the panel editor.
1. Scroll down to the **Data links and actions** section and expand it.
1. Click **+ Add link**.
1. In the dialog box that opens, enter a **Title**.
This is a human-readable label for the link displayed in the UI. This is a required field.
1. Enter the **URL** to which you want to link.
1. (Optional) To add a data link variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables.
1. If you want the link to open in a new tab, toggle the **Open in a new tab** switch.
1. If you want the data link to open with a single click on the visualization, toggle the **One click** switch.
Only one data link can have **One click** enabled at a time. **One click** is only supported for some visualizations.
1. Click **Save** to save changes and close the dialog box.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
{{< /tab-content >}}
{{< tab-content name="Add actions" >}}
{{< admonition type="note">}}
Actions are not supported for all visualizations. For the list of supported visualizations, refer to [Supported visualizations](#supported-visualizations-1).
{{< /admonition >}}
To add an action, by follow these steps:
1. Navigate to the panel to which you want to add the action.
1. Hover over any part of the panel to display the menu icon in the upper-right corner.
1. Click the menu icon and select **Edit** to open the panel editor.
1. Scroll down to the **Data links and actions** section and expand it.
1. Click **+ Add action**.
1. In the dialog box that opens, define the API call settings:
| Option | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title | A human-readable label for the action that's displayed in the UI. |
| Confirmation message | A descriptive prompt to confirm or cancel the action. |
| Method | Select from **POST**, **PUT**, or **GET**. |
| URL | The request URL.</p><p>To add a variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. |
| Variables | **Key** and **Name** pairs with a type selection. Click the **+** icon to add as many variables as you need. To add a variable to the request, prefix the key with `$`. You can set the values for the variables when performing an action. |
| Query parameters | **Key** and **Value** pairs. Click the **+** icon to add as many key/value pairs as you need. |
| Headers | Comprised of **Key** and **Value** pairs and a **Content-Type**.</p><p>Click the **+** icon to add as many key/value pairs as you need. |
| Content-Type | Select from the following: **application/json**, **text/plain**, **application/XML**, and **application/x-www-form-urlencoded**. |
| Body | The body of the request. |
1. Click **Save** to save changes and close the dialog box.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
{{< /tab-content >}}
{{< /tabs >}}
If you add multiple data links or actions, you can control the order in which they appear in the visualization. To do this, click and drag the data link or action to the desired position.
docs/sources/visualizations/panels-visualizations/configure-legend/index.md
+181
View File
@@ -0,0 +1,181 @@
---
aliases:
- ../../panels/working-with-panels/configure-legend/ # /docs/grafana/next/panels/working-with-panels/configure-legend/
- ../../panels-visualizations/visualizations/configure-legend/ # /docs/grafana/next/panels-visualizations/visualizations/configure-legend/
- ../../panels-visualizations/configure-legend/ # /docs/grafana/next/panels-visualizations/configure-legend/
labels:
products:
- cloud
- enterprise
- oss
title: Configure a legend
description: Configure a legend for your panel visualization
weight: 70
refs:
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
geomaps:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/geomap/
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
xy-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/xy-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/xy-chart/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
calculations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/calculation-types/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/calculation-types/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
histogram:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
heatmaps:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/heatmap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/heatmap/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
pie-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/pie-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/pie-chart/
---
# Configure a legend
A panel includes a legend that you can use to identify and interpret data displayed in a visualization. Each legend option adds context and clarity to the data illustrated in a visualization.
## Supported visualizations
Legends are supported for the following visualizations:
- [Bar chart](ref:bar-chart)
- [Candlestick](ref:candlestick)
- [Histogram](ref:histogram)
- [Pie chart](ref:pie-chart)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Time series](ref:time-series)
- [Trend](ref:trend)
- [XY chart](ref:xy-chart)
[Geomaps](ref:geomaps) and [heatmaps](ref:heatmaps) also have legends, but they only provide the choice to display or not display a legend and don't support other legend options.
## Legend options
You can find the following options under the **Legend** section in the panel edit pane.
{{< admonition type="note" >}}
Not all of the options listed apply to all visualizations with legends.
{{< /admonition >}}
### Visibility
Set whether the legend is displayed or not. Use the switch to toggle a legend on or off.
### Mode
Set the format in which the legend is displayed. Choose from:
- **List**
- **Table**
When you format a legend as a table, other information about the legend, such as associated [values](#values) or where it's located in the visualization, might be displayed as well.
### Placement
Set where on the visualization a legend is displayed. Choose from:
- **Bottom**
- **Right**
### Width
If you set the legend placement to **Right**, the **Width** option becomes available. Leave the field empty to allow Grafana to automatically set the legend width or enter a value in the field.
### Values
You can add more context to a visualization by adding series data values or [calculations](ref:calculations) to a legend. You can add as many values as you'd like. After you apply your changes, you can scroll the legend to see all values.
![Legend showing values](/media/docs/grafana/panels-visualizations/screenshot-legend-values-10.3.png)
## Change a series color
By default, Grafana sets the colors of your series data, but you can change them through the panel legend. To change the series data color, follow these steps:
1. Navigate to the panel you want to update.
1. In the legend, click the color bar associated with the series.
1. Select a pre-set color in the **Colors** tab or set a custom color in the **Custom** tab, using the picker or RGB values.
1. Save the dashboard.
![Change legend series color](/static/img/docs/legend/legend-series-color-7-5.png)
## Isolate series data in a visualization
Visualizations can often be visually complex, and include many data series. You can simplify the view by removing series data from the visualization through the legend, which isolates the data you want to see. When you do this, Grafana automatically creates a new override in the **Override** section.
To isolate a series, follow these steps:
1. Navigate to the panel you want to update.
1. In the legend, click the label of the series you want to isolate.
The system removes all other series data from view.
1. To incrementally add series data back to an isolated series, press the **Ctrl** or **Command** key and click the label of the series you want to add.
1. To save your changes so that they appear to all viewers of the panel, save the dashboard.
To revert back to the default view that includes all data, click any series label twice.
## Sort series
When you format a legend as a table and add values to it, you can sort series in the table by those values. To do so, follow these steps:
1. Navigate to the panel you want to update.
1. Hover over any part of the panel you want to work on to display the menu on the top right corner.
1. Click the menu and select **Edit**.
1. Scroll to the **Legend** section of the panel edit pane.
1. Under **Mode**, select **Table**.
1. Under **Values**, select the value or calculation that you want to show.
The legend table now displays values.
1. Click the calculation name header in the legend table to sort the values in the table in ascending or descending order.
![Legend formatted as a table showing sorted values](/media/docs/grafana/panels-visualizations/screenshot-legend-sorted-10.3-v2.png)
{{< admonition type="note" >}}
This feature is only supported for the following visualizations: bar chart, histogram, time series.
{{< /admonition >}}
docs/sources/visualizations/panels-visualizations/configure-overrides/index.md
+279
View File
@@ -0,0 +1,279 @@
---
aliases:
- ../../panels/configure-overrides/ # /docs/grafana/next/panels/configure-overrides/
- ../../panels/field-overrides/ # /docs/grafana/next/panels/field-overrides/
- ../../panels/override-field-values/ # /docs/grafana/next/panels/override-field-values/
- ../../panels/override-field-values/about-field-overrides/ # /docs/grafana/next/panels/override-field-values/about-field-overrides/
- ../../panels/override-field-values/add-a-field-override/ # /docs/grafana/next/panels/override-field-values/add-a-field-override/
- ../../panels/override-field-values/delete-a-field-override/ # /docs/grafana/next/panels/override-field-values/delete-a-field-override/
- ../../panels/override-field-values/edit-field-override/ # /docs/grafana/next/panels/override-field-values/edit-field-override/
- ../../panels/override-field-values/view-field-override/ # /docs/grafana/next/panels/override-field-values/view-field-override/
- ../../panels-visualizations/configure-overrides/ # /docs/grafana/next/panels-visualizations/configure-overrides/
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure field overrides
title: Configure field overrides
description: Configure field overrides to customize visualization settings
weight: 110
refs:
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/gauge/
bar-gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-gauge/
canvas:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/canvas/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
heatmap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/heatmap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/heatmap/
rename-by-regex-transformation:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/#rename-by-regex
- pattern: /docs/grafana-cloud
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/#rename-by-regex
histogram:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
table:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/table/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/table/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
pie-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/pie-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/pie-chart/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
geomap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/geomap/
xy-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/xy-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/xy-chart/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
stat:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/stat/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/stat/
---
# Configure field overrides
Overrides allow you to customize visualization settings for specific fields or series. When you add an override rule, it targets a particular set of fields and lets you define multiple options for how that field is displayed.
For example, you can override the default unit measurement for all fields that include the text "bytes" by adding an override using the **Fields with name matching regex** matcher and then the **Standard options > Unit** setting to the override rule:
![Field with unit override](/media/docs/grafana/panels-visualizations/screenshot-unit-override-v10.3.png)
After you've set them, your overrides appear in both the **All** and **Overrides** tabs of the panel editor pane:
![All and Overrides tabs of panel editor pane](/media/docs/grafana/panels-visualizations/screenshot-all-overrides-tabs-v11.png)
## Supported visualizations
You can configure field overrides for the following visualizations:
{{< column-list >}}
- [Bar chart](ref:bar-chart)
- [Bar gauge](ref:bar-gauge)
- [Candlestick](ref:candlestick)
- [Canvas](ref:canvas)
- [Gauge](ref:gauge)
- [Geomap](ref:geomap)
- [Heatmap](ref:heatmap)
- [Histogram](ref:histogram)
- [Pie chart](ref:pie-chart)
- [Stat](ref:stat)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Table](ref:table)
- [Time series](ref:time-series)
- [Trend](ref:trend)
- [XY chart](ref:xy-chart)
{{< /column-list >}}
## Override rules
You can choose from five types of override rules, which are described in the following sections.
### Fields with name
Select a field from the list of all available fields. Properties you add to this type of rule are only applied to this single field.
### Fields with name matching regex
Specify fields to override with a regular expression. Properties you add to this type of rule are applied to all fields where the field name matches the regular expression. This override doesn't rename the field; to do this, use the [Rename by regex transformation](ref:rename-by-regex-transformation).
### Fields with type
Select fields by type, such as string, numeric, or time. Properties you add to this type of rule are applied to all fields that match the selected type.
### Fields returned by query
Select all fields returned by a specific query, such as A, B, or C. Properties you add to this type of rule are applied to all fields returned by the selected query.
### Fields with values
Select all fields returned by your defined reducer condition, such as **Min**, **Max**, **Count**, **Total**. Properties you add to this type of rule are applied to all fields returned by the selected condition.
## Examples
The following examples demonstrate how you can use override rules to alter the display of fields in visualizations.
### Example 1: Format temperature
The following result set is a data frame that consists of two fields: time and temperature.
| time | temperature |
| :-----------------: | :---------: |
| 2020-01-02 03:04:00 | 45.0 |
| 2020-01-02 03:05:00 | 47.0 |
| 2020-01-02 03:06:00 | 48.0 |
You can apply field options to each field (column) of this structure to alter the way its values are displayed. For example, you can set the following override rule:
- Rule: **Fields with type**
- Field: temperature
- Override property: **Standard options > Unit**
- Selection: **Temperature > Celsius**
This results in the following table:
| time | temperature |
| :-----------------: | :---------: |
| 2020-01-02 03:04:00 | 45.0 °C |
| 2020-01-02 03:05:00 | 47.0 °C |
| 2020-01-02 03:06:00 | 48.0 °C |
In addition, the decimal place isn't required, so you can remove it by adding another override property that changes the **Standard options > Decimals** setting from **auto** to `0`. That results in the following table:
| time | temperature |
| :-----------------: | :---------: |
| 2020-01-02 03:04:00 | 45 °C |
| 2020-01-02 03:05:00 | 47 °C |
| 2020-01-02 03:06:00 | 48 °C |
### Example 2: Format temperature and humidity
The following result set is a data frame that consists of four fields: time, high temp, low temp, and humidity.
| time | high temp | low temp | humidity |
| ------------------- | --------- | -------- | -------- |
| 2020-01-02 03:04:00 | 45.0 | 30.0 | 67 |
| 2020-01-02 03:05:00 | 47.0 | 34.0 | 68 |
| 2020-01-02 03:06:00 | 48.0 | 31.0 | 68 |
Use the following override rule and properties to add the **Celsius** unit option and remove the decimal place:
- Rule: **Fields with type**
- Field: temperature
- Override property: **Standard options > Unit**
- Selection: **Temperature > Celsius**
- Override property: **Standard options > Decimals**
-Change setting from **auto** to `0`
This results in the following table:
| time | high temp | low temp | humidity |
| ------------------- | --------- | -------- | -------- |
| 2020-01-02 03:04:00 | 45 °C | 30 °C | 67 °C |
| 2020-01-02 03:05:00 | 47 °C | 34 °C | 68 °C |
| 2020-01-02 03:06:00 | 48 °C | 31 °C | 68 °C |
The temperature fields are displaying correctly, but the humidity has incorrect units. You can fix this by applying a **Misc > Percent (0-100)** override to the humidity field. This results in the following table:
| time | high temp | low temp | humidity |
| ------------------- | --------- | -------- | -------- |
| 2020-01-02 03:04:00 | 45 °C | 30 °C | 67% |
| 2020-01-02 03:05:00 | 47 °C | 34 °C | 68% |
| 2020-01-02 03:06:00 | 48 °C | 31 °C | 68% |
## Add a field override
To add a field override, follow these steps:
1. Navigate to the panel to which you want to add the data link.
1. Hover over any part of the panel to display the menu icon in the upper-right corner.
1. Click the menu icon and select **Edit** to open the panel editor.
1. At the bottom of the panel editor pane, click **Add field override**.
1. Select the fields to which the override will be applied:
- **Fields with name**
- **Fields with name matching regex**
- **Fields with type**
- **Fields returned by query**
- **Fields with values**
1. Click **Add override property**.
1. Select the field option that you want to apply.
1. Continue to add overrides to this field by clicking **Add override property**.
1. Add as many overrides as you need.
1. When you're finished, click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
## Edit a field override
To edit a field override, follow these steps:
1. Navigate to the panel to which you want to add the data link.
1. Hover over any part of the panel to display the menu icon in the upper-right corner.
1. Click the menu icon and select **Edit** to open the panel editor.
1. In the panel editor pane, click the **Overrides** tab.
1. Locate the override you want to change.
1. Perform any of the following tasks:
- Edit settings on existing overrides or field selection parameters.
- Delete existing override properties by clicking the **X** next to the property.
- Delete an override entirely by clicking the trash icon at the top-right corner.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
The changes you make take effect immediately.
docs/sources/visualizations/panels-visualizations/configure-panel-options/index.md
+102
View File
@@ -0,0 +1,102 @@
---
aliases:
- ../../panels/add-panels-dynamically/ # /docs/grafana/next/panels/add-panels-dynamically/
- ../../panels/configure-panel-options/ # /docs/grafana/next/panels/configure-panel-options/
- ../../panels/repeat-panels-or-rows/ # /docs/grafana/next/panels/repeat-panels-or-rows/
- ../../panels/working-with-panels/add-title-and-description/ # /docs/grafana/next/panels/working-with-panels/add-title-and-description/
- ../../panels/working-with-panels/view-json-model/ # /docs/grafana/next/panels/working-with-panels/view-json-model/
- ../../panels-visualizations/configure-panel-options/ # /docs/grafana/next/panels-visualizations/configure-panel-options/
keywords:
- panel
- dynamic
- add
- title
- description
- JSON model
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure panel options
title: Configure panel options
description: Add titles, descriptions, repeating rows and panel links
weight: 50
refs:
global-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#global-variables
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#global-variables
links-to-the-panel:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/#panel-links
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/manage-dashboard-links/#panel-links
configure-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
set-up-generative-ai-features-for-dashboards:
- 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
variables-you-have-defined:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
grafana-llm-plugin:
- 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/
---
# Configure panel options
There are settings common to all visualizations, which you set in the **Panel options** section of the panel editor pane. The following sections describe these options as well as how to set them.
## Panel options
Set the following options to provide basic information about a panel and define basic display elements:
| Option | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title | Text entered in this field appears at the top of your panel in the panel editor and in the dashboard. You can use [variables you have defined](ref:variables-you-have-defined) in the **Title** field, but not [global variables](ref:global-variables). |
| Description | Text entered in this field appears in a tooltip in the upper-left corner of the panel. Add a description to a panel to share with users any important information about it, such as its purpose. You can use [variables you have defined](ref:variables-you-have-defined) in the **Description** field, but not [global variables](ref:global-variables). |
| Transparent background | Toggle this switch on and off to control whether or not the panel has the same background color as the dashboard. |
| Panel links | Add [links to the panel](ref:links-to-the-panel) to create shortcuts to other dashboards, panels, and external websites. Access panel links by clicking the icon next to the panel title. |
| Repeat options | Set whether to repeat the panel for each value in the selected variable. For more information, refer to [Configure repeating panels](#configure-repeating-panels). |
You can use generative AI to populate the **Title** and **Description** fields with the [Grafana LLM plugin](ref:grafana-llm-plugin), which is currently in public preview. To enable this, refer to [Set up generative AI features for dashboards](ref:set-up-generative-ai-features-for-dashboards).
## Configure repeating panels
You can configure Grafana to dynamically add panels or rows to a dashboard. A dynamic panel is a panel that the system creates based on the value of a variable. Variables dynamically change your queries across all panels in a dashboard. For more information about repeating rows, refer to [Configure repeating rows](ref:configure-repeating-rows).
To see an example of repeating panels, refer to [this dashboard with repeating panels](https://play.grafana.org/d/testdata-repeating/testdata-repeating-panels?orgId=1).
**Before you begin:**
- Ensure that the query includes a multi-value variable.
To configure repeating panels, follow these steps:
1. Navigate to the panel you want to update.
1. Hover over any part of the panel to display the menu on the top right corner.
1. Click the menu and select **Edit**.
1. Open the **Panel options** section of the panel editor pane.
1. Under **Repeat options**, select a variable in the **Repeat by variable** drop-down list.
1. 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.
1. If you selected **Horizontal** in the previous step, 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. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
1. To propagate changes to all panels, reload the dashboard.
You can stop a panel from repeating by selecting **Disable repeating** in the **Repeat by variable** drop-down list.
docs/sources/visualizations/panels-visualizations/configure-standard-options/index.md
+276
View File
@@ -0,0 +1,276 @@
---
aliases:
- ../../panels/apply-color-to-series/ # /docs/grafana/next/panels/apply-color-to-series/
- ../../panels/configure-standard-options/ # /docs/grafana/next/panels/configure-standard-options/
- ../../panels/field-options/ # /docs/grafana/next/panels/field-options/
- ../../panels/field-options/standard-field-options/ # /docs/grafana/next/panels/field-options/standard-field-options/
- ../../panels/reference-standard-field-definitions/ # /docs/grafana/next/panels/reference-standard-field-definitions/
- ../../panels/standard-field-definitions/ # /docs/grafana/next/panels/standard-field-definitions/
- ../../panels/working-with-panels/format-standard-fields/ # /docs/grafana/next/panels/working-with-panels/format-standard-fields/
- ../../panels/field-configuration-options/ # /docs/grafana/next/panels/field-configuration-options/
- ../../panels-visualizations/configure-standard-options/ # /docs/grafana/next/panels-visualizations/configure-standard-options/
keywords:
- panel
- dashboard
- standard
- option
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure standard options
title: Configure standard options
description: Configure standard options like units, min, max, and colors
weight: 60
refs:
bar-gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-gauge/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
canvas:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/canvas/
threshold:
- 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/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
stat:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/stat/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/stat/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
pie-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/pie-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/pie-chart/
variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/gauge/
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
xy-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/xy-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/xy-chart/
geomap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/geomap/
table:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/table/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/table/
histogram:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
configure-overrides:
- 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/
---
# Configure standard options
**Standard options** in the panel editor pane let you change how field data is displayed in your visualizations. Options that you apply don't change the data, they just change how Grafana _displays_ the data.
When you set a standard option, the change is applied to all fields or series. For example, if you set the **Unit** option to **Percentage**, all fields with numeric values are displayed as percentages.
For more granular control over the display of fields, refer to [Configure overrides](ref:configure-overrides).
## Supported visualizations
You can configure standard options for the following visualizations:
{{< column-list >}}
- [Bar chart](ref:bar-chart)
- [Bar gauge](ref:bar-gauge)
- [Candlestick](ref:candlestick)
- [Canvas](ref:canvas)
- [Gauge](ref:gauge)
- [Geomap](ref:geomap)
- [Histogram](ref:histogram)
- [Pie chart](ref:pie-chart)
- [Stat](ref:stat)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Table](ref:table)
- [Time series](ref:time-series)
- [Trend](ref:trend)
- [XY chart](ref:xy-chart)
{{< /column-list >}}
## Standard options
This section explains all available standard options.
To set these options, expand the **Standard options** section in the panel editor pane. Most field options won't affect the visualization until you click outside of the field option box you're editing or press Enter.
{{< admonition type="note" >}}
Not all of the options listed apply to all visualizations with standard options.
{{< /admonition >}}
### Unit
This option lets you choose which unit a field should use. Click in the **Unit** field, then drill down until you find the unit you want. The unit you select is applied to all fields except time.
#### Custom units
You can also use the **Unit** drop-down to specify custom units, custom prefixes or suffixes, and date time formats.
To set a custom unit, enter the unit you want to use and then select it in the drop-down. It'll be the last option listed. For example, if you enter a unit called "Hearts", the drop-down will then include the option **Custom unit: Hearts**.
You can further define a custom unit with specific syntax. For example, to set a custom currency unit called "Gems", enter `currency:Gems` in the field. The drop-down will include the option **Custom unit: currency:Gems**:
![A custom currency unit called Gems in the Unit drop-down](/media/docs/grafana/panels-visualizations/custom_unit_currency_v11.0.png)
The following table lists the special syntax options for custom units:
| Custom unit | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suffix:<suffix>` | Custom unit that should go after value. |
| `prefix:<prefix>` | Custom unit that should go before value. |
| `time:<format>` | Custom date time formats type, such as `time:YYYY-MM-DD`. Refer to [formats](https://momentjs.com/docs/#/displaying/) for the format syntax and options. |
| `si:<base scale><unit characters>` | Custom SI units, such as `si: mF`. You can specify both a unit and the source data scale. For example, if your source data is represented as milli-something, prefix the unit with the `m` SI scale character. |
| `count:<unit>` | Custom count unit. |
| `currency:<unit>` | Custom currency unit. |
| `currency:financial:<unit>` | Full format currency unit without abbreviations. Displays complete numeric values instead of scaled abbreviations (K: Thousand, M: Million, B: Billion, T: Trillion). For example, `currency:financial:$` displays `500,555` instead of `$501K`. Add `:suffix` to place the symbol after the number: `currency:financial:€:suffix` displays `500,555€`. |
You can also paste a native emoji in the **Unit** drop-down and select it as a custom unit:
![A thumbs up emoji as a custom unit](/media/docs/grafana/panels-visualizations/custom_unit_thumbsup_v11.0.png)
![A time series visualization using custom thumbs up emoji units](/media/docs/grafana/panels-visualizations/thumbsup_panel_v11.0.png)
##### Time format units
All **Date & time** format units in Grafana (such as **Datetime ISO** or **Datetime US**) expect input values to be in milliseconds since the Unix epoch (January 1, 1970). If your data source provides timestamps in seconds, these will be incorrectly interpreted as dates very close to January 1, 1970.
To display timestamps that are in seconds since epoch, multiply your timestamp values by 1000 using a transformation following these steps:
1. In the panel editor, click the **Transformations** tab.
1. Click **Add transformation**.
1. Select the **Add field from calculation** transformation.
1. Set the following options:
- **Mode** - **Binary operation**
- **Operation**
- Select your timestamp field
- Select the asterisk (`*`) for multiply by
- Enter 1000 in the **Field or Number** field
- Toggle the **Replace all fields** switch on if you want to see the calculated field.
#### Control unit scaling
By default, Grafana automatically scales the unit based on the magnitude of the value. For example, if you have values of 0.14kW and 3000kW, Grafana displays them as 140W and 3MW, respectively. You can use custom units to control this behavior by setting a prefix, suffix, or custom SI unit.
#### String units
Sometimes Grafana is too aggressive in interpreting strings and displaying them as numbers. To configure Grafana to show the original string value, select **Misc > String** in the **Unit** drop-down.
### Min
Set the minimum value used in percentage threshold calculations. Leave this field empty to automatically calculate the minimum.
### Max
Set the maximum value used in percentage threshold calculations. Leave this field empty to automatically calculate the maximum.
### Field min/max
By default, the calculated **Min** and **Max** are based on the minimum and maximum of all series and fields. When you enable **Field min/max**, Grafana calculates the min or max of each field individually, based on the minimum or maximum value of the field.
### Decimals
Specify the number of decimals Grafana includes in the rendered value. If you leave this field empty, Grafana automatically truncates the number of decimals based on the value. For example 1.1234 displays as 1.12 and 100.456 displays as 100.
To display all decimals, set the unit to **String**.
### Display name
Set the display title of all fields. You can use [variables](ref:variables) in the field title.
When multiple stats, fields, or series are displayed, this field controls the title in each stat. You can use expressions like `${__field.name}` to use only the series name or the field name in the title.
The following table shows examples of the different field names generated using various expressions. In this example, there's a field with a name of "Temp" and labels of {"Loc"="PBI", "Sensor"="3"}:
| Expression syntax | Example | Renders to | Explanation |
| ---------------------------- | ----------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `${__field.displayName}` | Same as syntax | `Temp {Loc="PBI", Sensor="3"}` | Displays the field name, and labels in `{}` if they are present. If there is only one label key in the response, then for the label portion, Grafana displays the value of the label without the enclosing braces. |
| `${__field.name}` | Same as syntax | `Temp` | Displays the name of the field (without labels). |
| `${__field.labels}` | Same as syntax | `Loc="PBI", Sensor="3"` | Displays the labels without the name. |
| `${__field.labels.X}` | `${__field.labels.Loc}` | `PBI` | Displays the value of the specified label key. |
| `${__field.labels.__values}` | Same as Syntax | `PBI, 3` | Displays the values of the labels separated by a comma (without label keys). |
If the value is an empty string after rendering the expression for a particular field, then the default display method is applied.
### Color scheme
The **Color scheme** options let you set single or multiple colors for your entire visualization.
The color options and their effect on a visualization depend on the visualization you're working with and some visualizations have different color options.
Select one of the following schemes:
| Color scheme | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Single color | Specifies a single color. |
| Shades of a color | Grafana selects shades of a single color. |
| From thresholds (by value) | The color is taken from the matching [threshold](ref:threshold). For some visualizations, you also need to choose if the color is set by the **Last**, **Min**, or **Max** value of the field or series. |
| Classic palette | Grafana automatically assigns a color for each field or series based on its order. If the order of a field changes in your query, the color also changes. Useful for graphs, pie charts, and other categorical data visualizations. |
| Classic palette (by series name) | Grafana automatically assigns colors based on the name of the series. Useful when the series names to be visualized can change based on the available data. |
| Multiple continuous colors (by value) | Grafana automatically assigns colors based on the percentage of a value relative to the min and the max of the field or series. For some visualizations, you also need to choose if the color is set by the **Last**, **Min**, or **Max** value of the field or series. Select from: **Green-Yellow-Red**, **Red-Yellow-Green**, **Blue-Yellow-Red**, **Yellow-Red**, **Blue-Purple**, and **Yellow-Blue**. |
| Single continuous color (by value) | Grafana automatically assigns shades of one color based on the percentage of a value relative to the min and the max of the field or series. For some visualizations, you also need to choose if the color is set by the **Last**, **Min**, or **Max** value of the field or series. Select from: **Blues**, **Reds**, **Greens**, and **Purples**. |
You can also use the legend to open the color picker by clicking the legend series color icon. Setting color this way automatically creates an override rule that set's a specific color for a specific series.
### No value
Enter what Grafana should display if the field value is empty or null. The default value is a hyphen (-).
docs/sources/visualizations/panels-visualizations/configure-thresholds/index.md
+191
View File
@@ -0,0 +1,191 @@
---
aliases:
- ../../panels/ # /docs/grafana/next/panels/
- ../../panels/configure-thresholds/ # /docs/grafana/next/panels/configure-thresholds/
- ../../panels/specify-thresholds/about-thresholds/ # /docs/grafana/next/panels/specify-thresholds/about-thresholds/
- ../../panels/specify-thresholds/add-a-threshold/ # /docs/grafana/next/panels/specify-thresholds/add-a-threshold/
- ../../panels/specify-thresholds/add-threshold-to-graph/ # /docs/grafana/next/panels/specify-thresholds/add-threshold-to-graph/
- ../../panels/specify-thresholds/delete-a-threshold/ # /docs/grafana/next/panels/specify-thresholds/delete-a-threshold/
- ../../panels/thresholds/ # /docs/grafana/next/panels/thresholds/
- ../../panels-visualizations/configure-thresholds/ # /docs/grafana/next/panels-visualizations/configure-thresholds/
description: Configure thresholds in your visualizations
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure thresholds
title: Configure thresholds
weight: 100
refs:
table:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/table/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/table/
histogram:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
geomap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/geomap/
stat:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/stat/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/stat/
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/gauge/
bar-gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-gauge/
canvas:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/canvas/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
---
# Configure thresholds
In dashboards, a threshold is a value or limit you set for a metric that's reflected visually when it's met or exceeded. Thresholds are one way you can conditionally style and color your visualizations based on query results.
Using thresholds, you can color grid lines and regions in a time series visualization:
![Time series visualization with green, blue, and purple threshold lines and regions](/media/docs/grafana/panels-visualizations/screenshot-thresholds-lines-regions-v10.4.png)
You can color the background or value text in a stat visualization:
![Stat visualization with three values in green and orange](/media/docs/grafana/panels-visualizations/screenshot-thresholds-value-v10.4.png)
You can define regions and region colors in a state timeline:
![State timeline with green, blue, and pink region thresholds](/media/docs/grafana/panels-visualizations/screenshot-thresholds-state-timeline-v10.4.png)
You can also use thresholds to:
- Color lines in a time series visualization
- Color the gauge and threshold markers in a gauge
- Color markers in a geomap
- Color cell text or background in a table
{{< docs/play title="Threshold example" url="https://play.grafana.org/d/000000167/" >}}
## Supported visualizations
You can set thresholds in the following visualizations:
{{< column-list >}}
- [Bar chart](ref:bar-chart)
- [Bar gauge](ref:bar-gauge)
- [Candlestick](ref:candlestick)
- [Canvas](ref:canvas)
- [Gauge](ref:gauge)
- [Geomap](ref:geomap)
- [Histogram](ref:histogram)
- [Stat](ref:stat)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Table](ref:table)
- [Time series](ref:time-series)
- [Trend](ref:trend)
{{< /column-list >}}
## Default thresholds
On visualizations that support thresholds, Grafana has the following default threshold settings:
- 80 = red
- Base = green
- Mode = Absolute
- Show thresholds = Off (for some visualizations); for more information, see the [Show thresholds](#show-thresholds) option.
## Thresholds options
You can set the following options to further define how thresholds look.
### Threshold value
This number is the value that triggers the threshold. You can also set the color associated with the threshold in this field.
The **Base** value represents minus infinity. By default, it's set to the color green, which is generally the “good” color.
### Thresholds mode
There are two threshold modes:
- **Absolute** thresholds are defined by a number. For example, 80 on a scale of 1 to 150.
- **Percentage** thresholds are defined relative to minimum or maximum. For example, 80 percent.
### Show thresholds
{{< admonition type="note" >}}
This option is supported for the bar chart, candlestick, time series, and trend visualizations.
{{< /admonition>}}
Set if and how thresholds are shown with the following options.
| Option | Example |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Off | |
| As lines | {{< figure max-width="500px" src="/media/docs/grafana/panels-visualizations/screenshot-thresholds-lines-v10.4.png" alt="Visualization with threshold as a line" >}} |
| As lines (dashed) | {{< figure max-width="500px" src="/media/docs/grafana/panels-visualizations/screenshot-thresholds-dashed-lines-v10.4.png" alt="Visualization with threshold as a dashed line" >}} |
| As filled regions | {{< figure max-width="500px" src="/media/docs/grafana/panels-visualizations/screenshot-thresholds-regions-v10.4.png" alt="Visualization with threshold as a region" >}} |
| As filled regions and lines | {{< figure max-width="500px" src="/media/docs/grafana/panels-visualizations/screenshot-thresholds-lines-regions-v10.4.png" alt="Visualization with threshold as a region and line" >}} |
| As filled regions and lines (dashed) | {{< figure max-width="500px" src="/media/docs/grafana/panels-visualizations/screenshot-thresholds-dashed-lines-regions-v10.4.png" alt="Visualization with threshold as a region and dashed line" >}} |
## Add a threshold
You can add as many thresholds to a visualization as you want. Grafana automatically sorts thresholds values from highest to lowest.
1. Navigate to the panel you want to update.
1. Hover over any part of the panel you want to work on to display the menu on the top right corner.
1. Click the menu and select **Edit**.
1. Scroll to the **Thresholds** section or enter `thresholds` in the search bar at the top of the panel edit pane.
1. Click **+ Add threshold**.
1. Enter a new threshold value or use the up and down arrows at the right side of the field to increase or decrease the value incrementally.
1. Click the colored circle to the left of the threshold value to open the color picker, where you can update the threshold color.
1. Under **Thresholds mode**, select either **Absolute** or **Percentage**.
1. Under **Show thresholds**, set how the threshold is displayed or turn it off.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
To delete a threshold, navigate to the panel that contains the threshold and click the trash icon next to the threshold you want to remove.
docs/sources/visualizations/panels-visualizations/configure-tooltips/index.md
+157
View File
@@ -0,0 +1,157 @@
---
aliases:
keywords:
- grafana
- tooltips
- documentation
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure tooltips
title: Configure tooltips
description: Configure tooltips for your visualizations
weight: 75
refs:
pie-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/pie-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/pie-chart/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
flame-graph:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/flame-graph/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/flame-graph/
xy-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/xy-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/xy-chart/
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
geomaps:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/#tooltip
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/geomap/#tooltip
field-override:
- 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/
heatmap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/heatmap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/heatmap/
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
---
# Configure tooltips
When you hover your cursor over a visualization, Grafana can display tooltips that contain more information about a data point, like the exact time of a result. You can customize tooltips to control how many series they include and the order of those values. You can also copy the content from tooltips to use elsewhere. Learn more about configuring tooltips in [Tooltip options](#tooltip-options).
## Supported visualizations
You can configure tooltips for the following visualizations:
{{< column-list >}}
- [Bar chart](ref:bar-chart)
- [Candlestick](ref:candlestick)
- [Heatmap](ref:heatmap)
- [Pie chart](ref:pie-chart)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Time series](ref:time-series)
- [Trend](ref:trend)
- [XY chart](ref:xy-chart)
{{< /column-list >}}
Some visualizations, for example [candlestick](ref:candlestick) and [flame graph](ref:flame-graph), have tooltips, but they aren't configurable. These visualizations don't have a **Tooltip** section in the panel editor pane. [Geomaps](ref:geomaps) provide you the option to have tooltips triggered upon click or hover under the **Map controls** options in the panel editor pane.
<!-- if we add documentation for treemap, some info will need to be added in the paragraph above -->
## Tooltip options
You can find the following options under the **Tooltip** section in the panel edit pane.
{{< admonition type="note" >}}
Not all of the options listed apply to all visualizations with tooltips.
{{< /admonition >}}
### Tooltip mode
Choose how tooltips behave with the following options:
- **Single** - The tooltip only the single series that you're hovering over in the visualization.
- **All** - The tooltip shows all series in the visualization. Grafana highlights the series that you are hovering over in bold in the series list in the tooltip.
- **Hidden** - Tooltips aren't displayed when you interact with the visualization.
You can use a [field override](ref:field-override) to hide individual series from the tooltip.
### Values sort order
When you set the **Tooltip mode** to **All**, the **Values sort order** option is displayed. This option controls the order in which values are listed in a tooltip. Choose from the following:
- **None** - Grafana automatically sorts the values displayed in a tooltip.
- **Ascending** - Values in the tooltip are listed from smallest to largest.
- **Descending** - Values in the tooltip are listed from largest to smallest.
### Hide zeros
When you set the **Tooltip mode** to **All**, the **Hide zeros** option is displayed. This option controls whether or not series with `0` values are shown in the list in the tooltip.
### Hover proximity
Set the hover proximity (in pixels) to control how close the cursor must be to a data point to trigger the tooltip to display.
![Adding a hover proximity limit for tooltips](/media/docs/grafana/gif-grafana-10-4-hover-proximity.gif)
### Max width
Set the maximum width of the tooltip box.
### Max height
Set the maximum height of the tooltip box. The default is 600 pixels.
### Show histogram (Y axis)
For the heatmap visualization only, when you set the **Tooltip mode** to **Single**, the **Show histogram (Y axis)** option is displayed. This option controls whether or not the tooltip includes a histogram representing the y-axis.
### Show color scale
For the heatmap visualization only, when you set the **Tooltip mode** to **Single**, the **Show color scale** option is displayed. This option controls whether or not the tooltip includes the color scale that's also represented in the legend. When the color scale is included in the tooltip, it shows the hovered value on the scale:
![Heatmap with a tooltip displayed showing the hovered value reflected in the color scale](/media/docs/grafana/panels-visualizations/screenshot-heatmap-tooltip-color-scale-v11.0.png)
docs/sources/visualizations/panels-visualizations/configure-value-mappings/index.md
+201
View File
@@ -0,0 +1,201 @@
---
aliases:
- ../../configure-value-mappings/ # /docs/grafana/next/panels/configure-value-mappings/
- ../../panels/format-data/ # /docs/grafana/next/panels/format-data/
- ../../panels/format-data/about-value-mapping/ # /docs/grafana/next/panels/format-data/about-value-mapping/
- ../../panels/format-data/edit-value-mapping/ # /docs/grafana/next/panels/format-data/edit-value-mapping/
- ../../panels/format-data/map-a-range/ # /docs/grafana/next/panels/format-data/map-a-range/
- ../../panels/format-data/map-a-regular-expression/ # /docs/grafana/next/panels/format-data/map-a-regular-expression/
- ../../panels/format-data/map-a-special-value/ # /docs/grafana/next/panels/format-data/map-a-special-value/
- ../../panels/format-data/map-a-value/ # /docs/grafana/next/panels/format-data/map-a-value/
- ../../panels/value-mappings/ # /docs/grafana/next/panels/value-mappings/
- ../../panels-visualizations/configure-value-mappings/ # /docs/grafana/next/panels-visualizations/configure-value-mappings/
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Configure value mappings
title: Configure value mappings
description: Configure value mappings to change how data appears in your visualizations
weight: 90
refs:
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
bar-gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-gauge/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
canvas:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/canvas/
gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/gauge/
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
geomap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/geomap/
stat:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/stat/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/stat/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
table:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/table/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/table/
histogram:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
pie-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/pie-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/pie-chart/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
---
# Configure value mappings
In addition to field overrides, value mapping is a technique you can use to change how data appears in a visualization.
For example, the mapping applied in the following image causes the visualization to display the text `Cold`, `Good`, and `Hot` in blue, green, and red for ranges of temperatures rather than actual temperature values. Using value mappings this way can make data faster and easier to understand and interpret.
![Value mappings applied to a gauge visualization](/media/docs/grafana/panels-visualizations/screenshot-value-mappings-v10.4.png)
Value mappings bypass unit formatting set in the **Standard options** section of panel editor, like color or number of decimal places displayed. When value mappings are present in a panel, Grafana displays a summary of them in the **Value mappings** section of the editor panel.
## Supported visualizations
You can configure value mappings for the following visualizations:
{{< column-list >}}
- [Bar chart](ref:bar-chart)
- [Bar gauge](ref:bar-gauge)
- [Candlestick](ref:candlestick)
- [Canvas](ref:canvas)
- [Gauge](ref:gauge)
- [Geomap](ref:geomap)
- [Histogram](ref:histogram)
- [Pie chart](ref:pie-chart)
- [Stat](ref:stat)
- [State timeline](ref:state-timeline)
- [Status history](ref:status-history)
- [Table](ref:table)
- [Time series](ref:time-series)
- [Trend](ref:trend)
{{< /column-list >}}
## Types of value mappings
Grafana supports the following value mapping types:
### Value
A **Value** mapping maps specific values to text and a color. For example, you can configure a mapping so that all instances of the value `10` appear as **Perfection!** rather than the number. Use **Value** mapping when you want to format a single value.
![The value 10 mapped to the text Perfection!](/media/docs/grafana/panels-visualizations/screenshot-map-value-v10.4.png)
### Range
A **Range** mapping maps numerical ranges to text and a color. For example, if a value is within a certain range, you can configure a range value mapping to display **Low** or **High** rather than the number. Use **Range** mapping when you want to format multiple, continuous values.
![Ranges of numbers mapped to the text Low and High with colors yellow and red](/media/docs/grafana/panels-visualizations/screenshot-map-range-v10.4.png)
### Regex
A **Regex** mapping maps regular expressions to text and a color. For example, if a value is `www.example.com`, you can configure a regular expression value mapping so that Grafana displays **www** and truncates the domain. Use the **Regex** mapping when you want to format the text and color of a regular expression value.
![A regular expression used to truncate full URLs to the text wwww](/media/docs/grafana/panels-visualizations/screenshot-map-regex-v10.4.png)
### Special
A **Special** mapping maps special values like `Null`, `NaN` (not a number), and boolean values like `true` and `false` to text and color. For example, you can configure a special value mapping so that `null` values appear as **N/A**. Use the **Special** mapping when you want to format uncommon, boolean, or empty values.
![The value null mapped to the text N/A](/media/docs/grafana/panels-visualizations/screenshot-map-special-v10.4.png)
## Examples
Refer to the following examples to learn more about value mapping.
### Time series example
The following image shows a time series visualization with value mappings. Value mapping colors aren't applied to this visualization, but the display text is shown on the axis.
![Value mappings time series example](/static/img/docs/value-mappings/value-mappings-summary-example-8-0.png)
### Stat example
The following image shows a stat visualization with value mappings and text colors applied. You can hide the sparkline so it doesn't interfere with the values.
![Value mappings stat example](/static/img/docs/value-mappings/value-mappings-stat-example-8-0.png)
### Bar gauge example
The following image shows a bar gauge visualization with value mappings. Note that the value mapping colors are applied to the text, but not to the gauges.
![Value mappings bar gauge example](/static/img/docs/value-mappings/value-mappings-bar-gauge-example-8-0.png)
### Table example
The following image shows a table visualization with value mappings. If you want value mapping colors displayed on the table, then set the cell display mode to **Color text** or **Color background**.
![Value mappings table example](/static/img/docs/value-mappings/value-mappings-table-example-8-0.png)
## Add a value mapping
1. Navigate to the panel you want to update.
1. Hover over any part of the panel you want to work on to display the menu on the top right corner.
1. Click the menu and select **Edit**.
1. Scroll to the **Value mappings** section and expand it.
1. Click **Add value mappings**.
1. Click **Add a new mapping** and then select one of the following:
- **Value** - Enter a single value to match.
- **Range** - Enter the beginning and ending values of a range to match.
- **Regex** - Enter a regular expression pattern to match.
- **Special** - Select a special value to match.
1. (Optional) Enter display text.
1. (Optional) Set the color.
1. (Optional) Set an icon (canvas visualizations only).
1. Click **Update** to save the value mapping.
After you've added a mapping, the **Edit value mappings** button replaces the **Add value mappings** button. Click the edit button to add or update mappings.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
docs/sources/visualizations/panels-visualizations/panel-editor-overview/index.md
+102
View File
@@ -0,0 +1,102 @@
---
aliases:
- ../../dashboards/add-organize-panels/ # /docs/grafana/next/dashboards/add-organize-panels/
- ../../dashboards/dashboard-create/ # /docs/grafana/next/dashboards/dashboard-create/
- ../../panels/add-panels-dynamically/about-repeating-panels-rows/ # /docs/grafana/next/panels/add-panels-dynamically/about-repeating-panels-rows/
- ../../panels/add-panels-dynamically/configure-repeating-panels/ # /docs/grafana/next/panels/add-panels-dynamically/configure-repeating-panels/
- ../../panels/add-panels-dynamically/configure-repeating-rows/ # /docs/grafana/next/panels/add-panels-dynamically/configure-repeating-rows/
- ../../panels/working-with-panels/ # /docs/grafana/next/panels/working-with-panels/
- ../../panels/working-with-panels/add-panel/ # /docs/grafana/next/panels/working-with-panels/add-panel/
- ../../panels/working-with-panels/navigate-inspector-panel/ # /docs/grafana/next/panels/working-with-panels/navigate-inspector-panel/
- ../../panels/working-with-panels/navigate-panel-editor/ # /docs/grafana/next/panels/working-with-panels/navigate-panel-editor/
- ../../panels-visualizations/add-organize-panels/ # /docs/grafana/next/panels-visualizations/add-organize-panels/
- ../../panels-visualizations/panel-editor-overview/ # /docs/grafana/next/panels-visualizations/panel-editor-overview/
keywords:
- panel
- dashboard
- dynamic
- add
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Panel editor
title: Panel editor
description: Learn about the features of the panel editor
weight: 20
refs:
transform-data:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/
the-overview-of-grafana-alerting:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/
table:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/table/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/table/
add-a-query:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/#add-a-query
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/#add-a-query
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
---
# Panel editor
In the panel editor, you can update all the elements of a visualization including the data source, queries, time range, and visualization display options.
![Panel editor](/media/docs/grafana/panels-visualizations/screenshot-panel-editor-v11.6.png)
This following sections describe the areas of the Grafana panel editor.
## Panel header
The header section lists the dashboard in which the panel appears and the following controls:
- **Back to dashboard** - Return to the dashboard with changes applied, but not yet saved.
- **Discard panel changes** - Discard changes you have made to the panel since you last saved the dashboard.
- **Save dashboard** - Save your changes to the dashboard.
## Visualization preview
The visualization preview section contains the following options:
- **Table view** - Convert any visualization to a table so you can see the data. Table views are helpful for troubleshooting. This view only contains the raw data. It doesn't include transformations you might have applied to the data or the formatting options available in the [Table](ref:table) visualization.
- **Time range controls** - **Default** is either the browser local timezone or the timezone selected at a higher level.
- **Refresh** - Query the data source.
## Data section
The data section contains tabs where you enter queries, transform your data, and create alert rules (if applicable).
- **Queries**
- Select your data source. You can also set or update the data source in existing dashboards using the drop-down menu in the **Queries** tab.
- [Add queries](ref:add-a-query). Write or construct a query in the query language of your data source or 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. 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 >}}
- **Transformations** - Apply data transformations. For more information, refer to [Transform data](ref:transform-data).
- **Alert** - Write alert rules. For more information, refer to [the overview of Grafana Alerting](ref:the-overview-of-grafana-alerting).
## Panel display options
The display options section contains tabs where you configure almost every aspect of your data visualization.
docs/sources/visualizations/panels-visualizations/panel-inspector/index.md
+76
View File
@@ -0,0 +1,76 @@
---
aliases:
- ../../panels/query-a-data-source/download-raw-query-results/ # /docs/grafana/next/panels/query-a-data-source/download-raw-query-results/
- ../../panels/query-a-data-source/inspect-query-performance/ # /docs/grafana/next/panels/query-a-data-source/inspect-query-performance/
- ../../panels/query-a-data-source/inspect-request-and-response-data/ # /docs/grafana/next/panels/query-a-data-source/inspect-request-and-response-data/
- ../../panels/working-with-panels/navigate-inspector-panel/ # /docs/grafana/next/panels/working-with-panels/navigate-inspector-panel/
- ../../panels-visualizations/panel-inspector/ # /docs/grafana/next/panels-visualizations/panel-inspector/
labels:
products:
- cloud
- enterprise
- oss
title: The panel inspect view
description: Inspect the raw data of your panels to understand and troubleshoot them
weight: 30
---
# The panel inspect view
The panel inspect view, which you can open via the panel menu, helps you understand and troubleshoot your panels. You can inspect the raw data for any Grafana panel, export that data to a comma-separated values (CSV) file, view query requests, and export panel and data JSON.
> **Note:** Not all panel types include all tabs. For example, dashboard list panels do not have raw data to inspect, so they do not display the Stats, Data, or Query tabs.
The panel inspector consists of the following options:
1. The panel inspector displays Inspect: <NameOfPanelBeingInspected> at the top of the pane. Click the arrow in the upper right corner to expand or reduce the pane.
2. **Data tab -** Shows the raw data returned by the query with transformations applied. Field options such as overrides and value mappings are not applied by default.
3. **Stats tab -** Shows how long your query takes and how much it returns.
4. **JSON tab -** Allows you to view and copy the panel JSON, panel data JSON, and data frame structure JSON. This is useful if you are provisioning or administering Grafana.
5. **Query tab -** Shows you the requests to the server sent when Grafana queries the data source.
6. **Error tab -** Shows the error. Only visible when query returns error.
## Download raw query results
Grafana generates a CSV file that contains your data, including any transformations to that data. You can choose to view the data before or after the panel applies field options or field option overrides.
1. Edit the panel that contains the query data you want to download.
1. In the query editor, click **Query Inspector**.
1. Click **Data**.
If your panel contains multiple queries or queries multiple nodes, then you have additional options.
- **Select result**: Choose which result set data you want to view.
- **Transform data**
- **Join by time**: View raw data from all your queries at once, one result set per column. Click a column heading to reorder the data.
1. To see data before the system applies field overrides, click the **Formatted data** toggle.
1. To download a CSV file specifically formatted for Excel, click the **Download for Excel** toggle .
1. Click **Download CSV**.
## Inspect query performance
The **Stats** tab displays statistics that tell you how long your query takes, how many queries you send, and the number of rows returned. This information can help you troubleshoot your queries, especially if any of the numbers are unexpectedly high or low.
1. Edit the panel that contains the query with performance you want to inspect.
1. In the query editor, click **Query Inspector**.
1. Click **Stats**.
Statistics are displayed in read-only format.
## Inspect query request and response data
Inspect query request and response data when you want to troubleshoot a query that returns unexpected results, or fails to return expected results.
1. Edit the panel that contains the query you want to export.
1. In the query editor, click **Query Inspector**.
1. Click **Refresh**.
The panel populates with response data.
1. Make adjustments, as necessary and re-run the query.
1. To download the query request and response data, click the **Copy to clipboard** icon and paste the results into another application.
docs/sources/visualizations/panels-visualizations/panel-overview/index.md
+202
View File
@@ -0,0 +1,202 @@
---
keywords:
- transform
- query
- panel
- dashboard
- rows
- dynamic
- add
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Panel overview
title: Panel overview
description: Learn about the features of the panel
weight: 15
refs:
configure-panel-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-panel-options/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-panel-options/
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/
data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/
configure-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/
visualization:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/
legend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-legend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-legend/
create:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/alerting-rules/create-grafana-managed-rule/#create-alerts-from-panels
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-grafana-managed-rule/#create-alerts-from-panels
share:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/share-query/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/share-query/
tooltips:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-tooltips/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-tooltips/
ai:
- 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-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/
configure-field-overrides:
- 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/
query:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/
panel-links:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/manage-dashboard-links/#panel-links
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/manage-dashboard-links/#panel-links
data-source-management:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/
transformations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/
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/
aliases:
- ../../panels-visualizations/panel-overview/ # /docs/grafana/next/panels-visualizations/panel-overview/
---
# Panel overview
A Grafana panel is a visual representation of data composed of a [query](ref:query) and a [visualization](ref:visualization). Within panels, you can apply [transformations](ref:transformations), which process the results of a query before they're passed on for visualization. You can also further customize a panel by formatting data and configuring visualization options.
Each panel has a query editor specific to the data source selected in the panel. The query editor allows you to build a query that returns the data you want to visualize.
Panels offer a wide variety of formatting and styling options, from applying colors based on field values to creating custom units. Each visualization also comes with options specific to it that give you further control over how your data is displayed. Panels can also be dragged, dropped, and resized to rearrange them on the dashboard.
To get started adding panels, ensure that you have configured a data source:
- For details about using data sources, refer to [Data sources](ref:data-sources).
- For more information about managing data sources as an administrator, refer to [Data source management](ref:data-source-management).
{{< admonition type="note" >}}
[Data source management](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/) is only available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](https://grafana.com/docs/grafana-cloud/).
{{< /admonition >}}
## Panel feature overview
The following image and descriptions highlight the panel features:
![Annotated panel with time series visualization](/media/docs/grafana/panels-visualizations/screenshot-panel-overview-ann-v11.0.png)
1. **Panel title** - You can create your own panel titles or have Grafana create them for you using [generative AI features](ref:ai).
1. **Panel description** - You can create your own panel descriptions or have Grafana create them for you using [generative AI features](ref:ai)
1. **Links** - Add [panel links](ref:panel-links) to other dashboards, panels, or external sites.
1. **Panel menu** - In the [panel menu](#panel-menu), access actions such as **View**, **Edit**, **Inspect**, and **Remove**.
1. **Legend** - Change series colors, y-axis, and series visibility directly from the [legend](ref:legend).
1. **Tooltips** - View [tooltips](ref:tooltips) to get more information about data points.
## Panel menu
To access the panel editor, hover over the top-right corner of any panel. Click the panel menu icon that appears and select **Edit**. The panel menu gives you access to the following actions:
- **View**: View the panel in full screen.
- **Edit**: Open the panel editor to edit panel and visualization options.
- **Share**: Share the panel as a link, embed, or snapshot.
- **Explore**: Open the panel in **Explore**, where you can focus on your query.
- **Inspect**: Open the **Inspect** drawer, where you can review the panel data, stats, metadata, JSON, and query.
- **Data**: Open the **Inspect** drawer in the **Data** tab.
- **Query**: Open the **Inspect** drawer in the **Query** tab.
- **Panel JSON**: Open the **Inspect** drawer in the **JSON** tab.
- **Extensions**: Access other actions provided by installed applications, such as declaring an incident. Note that this option doesn't appear unless you have app plugins installed which contribute an [extension](https://grafana.com/developers/plugin-tools/key-concepts/ui-extensions) to the panel menu.
- **More**: Access other panel actions.
- **Duplicate**: Make a copy of the panel. Duplicated panels query data separately from the original panel. You can use the special `Dashboard` data source to [share the same query results across panels](ref:share) instead.
- **Copy**: Copy the panel to the clipboard.
- **New library panel**: Create a panel that can be imported into other dashboards.
- **New alert rule**: Open the alert rule configuration page in **Alerting**, where you can [create a Grafana-managed alert](ref:create) based on the panel queries.
- **Hide legend**: Hide the panel legend.
- **Get help**: Send a snapshot or panel data to Grafana Labs Technical Support.
- **Remove**: Remove the panel from the dashboard.
## Keyboard shortcuts
Grafana has a number of keyboard shortcuts available specifically for panels. Press `?` on your keyboard to display all keyboard shortcuts available in your version of Grafana.
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 fullscreen view
- `pu`: Share link
- `pe`: Share embed
- `ps`: Share snapshot
- `px`: Open panel in **Explore**
- `pd`: Duplicate Panel
- `i`: Inspect
- `pl`: Hide or show legend
- `pr`: Remove Panel
## Add a panel
To add a panel in a new dashboard click **+ Add visualization** in the middle of the dashboard:
![Empty dashboard state](/media/docs/grafana/dashboards/empty-dashboard-10.2.png)
To add a panel to an existing dashboard, follow these steps:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click the **Add** drop-down and select **Visualization**:
![Add dropdown](/media/docs/grafana/panels-visualizations/screenshot-add-dropdown-11.2.png)
## Panel configuration
To configure panels, refer to the following subtopics:
- [Configure panel options](ref:configure-panel-options)
- [Configure standard options](ref:configure-standard-options)
- [Configure a legend](ref:legend)
- [Configure tooltips](ref:tooltips)
- [Configure data links](ref:configure-data-links)
- [Configure value mappings](ref:configure-value-mappings)
- [Configure thresholds](ref:configure-thresholds)
- [Configure field overrides](ref:configure-field-overrides)
docs/sources/visualizations/panels-visualizations/query-transform-data/_index.md
+335
View File
@@ -0,0 +1,335 @@
---
aliases:
- ../../panels-visualizations/manage-queries/ # /docs/grafana/next/panels-visualizations/manage-queries/
- ../../panels-visualizations/query-options/ # /docs/grafana/next/panels-visualizations/query-options/
- ../../panels-visualizations/query-transform-data/ # /docs/grafana/next/panels-visualizations/query-transform-data/
- ../../panels/expressions/ # /docs/grafana/next/panels/expressions/
- ../../panels/inspect-panel/ # /docs/grafana/next/panels/inspect-panel/
- ../../panels/queries/ # /docs/grafana/next/panels/queries/
- ../../panels/query-a-data-source/ # /docs/grafana/next/panels/query-a-data-source/
- ../../panels/query-a-data-source/about-queries/ # /docs/grafana/next/panels/query-a-data-source/about-queries/
- ../../panels/query-a-data-source/add-a-query/ # /docs/grafana/next/panels/query-a-data-source/add-a-query/
- ../../panels/query-a-data-source/manage-queries/ # /docs/grafana/next/panels/query-a-data-source/manage-queries/
- ../../panels/query-a-data-source/navigate-query-tab/ # /docs/grafana/next/panels/query-a-data-source/navigate-query-tab/
- ../../panels/query-options/ # /docs/grafana/next/panels/query-options/
- ../../panels/reference-query-options/ # /docs/grafana/next/panels/reference-query-options/
- ../../panels/share-query-results/ # /docs/grafana/next/panels/share-query-results/
labels:
products:
- cloud
- enterprise
- oss
title: Query and transform data
description: Query and transform your data
weight: 40
refs:
data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/
built-in-core-data-sources:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#built-in-core-data-sources
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/#built-in-core-data-sources
use-expressions-to-manipulate-data:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/expression-queries/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/expression-queries/
global-variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#global-variables
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#global-variables
plugin-management:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/plugin-management/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/plugin-management/
recorded-queries:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/recorded-queries/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/recorded-queries/
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
---
# Query and transform data
Grafana supports many types of [data sources](ref:data-sources).
Data source _queries_ return data that Grafana can _transform_ and visualize.
Each data source uses its own query language, and data source plugins each implement a query-building user interface called a query editor.
## About queries
Grafana panels communicate with data sources using queries, which retrieve data for the visualization.
A query is a question written in the query language used by the data source.
You can configure query frequency and data collection limits in the panel's data source options.
Grafana supports up to 26 queries per panel.
{{< admonition type="note" >}}
You **must** be familiar with a data source's query language.
For more information, refer to [Data sources](ref:data-sources).
{{< /admonition >}}
### Query editors
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-queries-tab-v11.6.png" max-width="750px" alt="The InfluxDB query editor" >}}
Each data source's query editor provides a customized user interface that helps you write queries that take advantage of its unique capabilities.
Because of the differences between query languages, each data source query editor looks and functions differently.
Depending on your data source, the query editor might provide auto-completion features, metric names, variable suggestions, or a visual query-building interface.
For example, this video demonstrates the visual Prometheus query builder:
{{< vimeo 720004179 >}}
For details on a specific data source's unique query editor features, refer to its documentation:
- For data sources included with Grafana, refer to [Built-in core data sources](ref:built-in-core-data-sources), which links to each core data source's documentation.
- For data sources installed as plugins, refer to the documentation for the plugin.
- Data source plugins in Grafana's [plugin catalog](/grafana/plugins/) link to or include their documentation in their catalog listings.
For details about the plugin catalog, refer to [Plugin management](ref:plugin-management).
- For links to Grafana Enterprise data source plugin documentation, refer to the [Enterprise plugins index](/docs/plugins/).
### Query syntax
Each data source uses a different query languages to request data.
For details on a specific data source's unique query language, refer to its documentation.
**PostgreSQL example:**
```
SELECT hostname FROM host WHERE region IN($region)
```
**PromQL example:**
```
query_result(max_over_time(<metric>[${__range_s}s]) != <state>)
```
### Saved queries
{{< admonition type="note" >}}
Saved queries is currently in [public preview](https://grafana.com/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
This feature is only available on Grafana Enterprise and Grafana Cloud. It will gradually roll out to all Grafana Cloud users with no action required. To try out this feature on Grafana Enterprise, enable the `queryLibrary` feature toggle.
{{< /admonition >}}
You can save queries that you've created so they can be reused by you and others in your organization.
This helps users across your organization create dashboards or find insights in Explore without having to create their own queries or know a query language.
It also helps you avoid having several users build the same queries for the same data sources multiple times.
You can see a list of these queries in the **Saved queries** drawer:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-saved-queries-v12.2png.png" max-width="550px" alt="List of saved queries and the edit query form" caption="The Saved queries drawer accessed from Dashboards" >}}
When you first open the drawer, the list of queries in the **All** tab is filtered by the data source of the panel.
However, you can clear that filter to display all saved queries.
The list in the **Favorites** tab is also filtered by data source, by default.
The **Recent** tab displays the last 20 queries across all data sources from your **Query history** in Explore.
From this tab, you can save queries for reuse as well.
In the **Saved queries** drawer, you can:
- Search for queries by data source name, query content, title, or description.
- Sort queries alphabetically or by creation date.
- Filter by data source name, author name, and tags (the tag filter uses the `OR` operator, while the others use the `AND` operator).
- Set queries as favorites.
- Duplicate, lock and unlock a query for editing, or delete a saved query.
- Edit a query title, description, tags, or the availability of the query to other users in your organization. By default, saved queries are locked for editing.
- When you access the **Saved queries** drawer from Explore, you can use the **Edit in Explore** option to edit the body of a query.
Access the duplicate, lock, unlock, and delete query options through the menu in the top-right corner of the query form next to the **Edit** button.
To access your saved queries, click **+ Add from saved queries** in the query editor:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-add-from-saved-2-v12.2.png" max-width="750px" alt="Add a saved query" >}}
If you've already entered a query, you also have the option to replace it with a saved one:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-replace-w-saved-v12.2.png" max-width="750px" alt="Replace a query with a saved one" >}}
#### Save a query
To save a query you've created:
1. From the query editor, click the **Save query** icon:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-save-query-v12.2.png" max-width="750px" alt="Save a query" >}}
1. In the **Saved queries** drawer, enter a title for the query that will make it easy to find later.
1. (Optional) Enter a description and relevant tags.
1. Clear the **Share query with all users** checkbox if you only want the saved query to be available to you.
1. Click **Save**.
#### Known limitations
- No validation is performed when you save a query, so it's possible to save an invalid query. You should confirm the query is working properly before you save it.
- Saved queries are currently accessible from the query editors in Dashboards and Explore.
- You can save a maximum of 1000 queries.
- Users with the Viewer role who have access to Explore can use saved queries, but can't write them.
- If you have multiple queries open in Explore and you edit one of them by way of the **Edit in Explore** function in the **Saved queries** drawer, the edited query replaces your open queries in Explore.
### Special data sources
Grafana also includes three special data sources: **Grafana**, **Mixed**, and **Dashboard**.
For details, refer to [Data sources](ref:data-sources)
## Navigate the Queries tab {#navigate-the-query-tab}
A panel's **Queries** tab consists of the following elements:
- **Data source selector** - Selects the data source to query.
For more information about data sources, refer to [Data sources](ref:data-sources).
- **Query options** - Sets maximum data retrieval parameters and query execution time intervals.
- **Query inspector button** - Opens the query inspector panel, where you can view and optimize your query.
- **Query editor list** - The list of queries you've written. Each query can be expanded or collapsed.
- **Expressions** - Uses the expression builder to create alert expressions.
For more information about expressions, refer to [Use expressions to manipulate data](ref:use-expressions-to-manipulate-data).
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-queries-tab2-v11.6.png" max-width="750px" alt="The Query tab of the panel editor" >}}
## Add a query
A query returns data that Grafana visualizes in dashboard panels.
When you create a panel, Grafana automatically selects the default data source.
To add a query, follow these steps:
1. Hover the cursor over any part of the panel to which you're adding a query to display the menu icon in the top-right corner.
1. Click the menu and select **Edit**.
1. In the panel editor, click the **Queries** tab.
1. Click the **Data source** drop-down menu and select a data source.
If you're creating a new dashboard, you'll be prompted to select a data source when you add the first panel.
1. Click **Query options** to configure the maximum number of data points you need.
For more information about query options, refer to [Query options](#query-options).
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 for reuse, click the **Save query** icon.
{{< admonition type="note" >}}
[Saved queries](#saved-queries) is currently in [public preview](https://grafana.com/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
This feature is only available on Grafana Enterprise and Grafana Cloud.
{{< /admonition >}}
1. Click **Run queries**.
Grafana queries the data source and visualizes the data.
## Manage queries
Grafana organizes queries in collapsible query rows.
Each query row contains a query editor and is identified with a letter (A, B, C, and so on).
You can:
<!-- prettier-ignore-start -->
| Icon | Description |
| ------- | -------------------------------------------- |
| {{< figure src="/static/img/docs/queries/query-editor-help-7-4.png" max-width="30px" max-height="30px" alt="Help icon" >}} | Toggles query editor help. If supported by the data source, click this icon to display information on how to use the query editor or provide quick access to common queries. |
| {{< figure src="/media/docs/grafana/panels-visualizations/create-recorded-query-icon.png" max-width="30px" max-height="30px" alt="Create recorded query icon" >}} | Create [recorded queries](ref:recorded-queries) so you can see trends over time by taking a snapshot of a data point on a set interval (Enterprise and Cloud only). |
| {{< figure src="/media/docs/grafana/panels-visualizations/save-to-query-icon.png" max-width="30px" max-height="30px" alt="Save query icon" >}} | Save query. Saves the query so it can be reused. Access saved queries by clicking **+ Add saved query**. For more information, refer to [Saved queries](#saved-queries) (Enterprise and Cloud only). |
| {{< figure src="/static/img/docs/queries/duplicate-query-icon-7-0.png" max-width="30px" max-height="30px" alt="Duplicate icon" >}} | Copies a query. Duplicating queries is useful when working with multiple complex queries that are similar and you want to either experiment with different variants or do minor alterations. |
| {{< figure src="/static/img/docs/queries/hide-query-icon-7-0.png" max-width="30px" max-height="30px" alt="Hide icon" >}} | Hides a query. Grafana does not send hidden queries to the data source. |
| {{< figure src="/static/img/docs/queries/remove-query-icon-7-0.png" max-width="30px" max-height="30px" alt="Remove icon">}} | Removes a query. Removing a query permanently deletes it, but sometimes you can recover deleted queries by reverting to previously saved versions of the panel. |
| {{< figure src="/static/img/docs/queries/query-drag-icon-7-2.png" max-width="30px" max-height="30px" alt="Drag icon" >}} | Reorders queries. Change the order of queries by clicking and holding the drag icon, then drag queries where desired. The order of results reflects the order of the queries, so you can often adjust your visual results based on query order. |
<!-- prettier-ignore-end -->
## Query options
Click **Query options** next to the data source selector to see settings for the selected data source.
Changes you make here affect only queries made in this panel.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-query-options-v11.6.png" max-width="750px" alt="Data source query options" >}}
Grafana sets defaults that are shown in dark gray text.
Changes are displayed in white text.
To return a field to the default setting, delete the white text from the field.
Panel data source query options include:
- **Max data points** - If the data source supports it, this sets the maximum number of data points for each series returned.
If the query returns more data points than the max data points setting, then the data source reduces the number of points returned by aggregating them together by average, max, or another function.
You can limit the number of points to improve query performance or smooth the visualized line.
The default value is the width (or number of pixels) of the graph, because you can only visualize as many data points as the graph panel has room to display.
With streaming data, Grafana uses the max data points value for the rolling buffer.
Streaming is a continuous flow of data, and buffering divides the stream into chunks.
For example, Loki streams data in its live tailing mode.
- **Min interval** - Sets a minimum limit for the automatically calculated interval, which is typically the minimum scrape interval.
If a data point is saved every 15 seconds, you don't benefit from having an interval lower than that.
You can also set this to a higher minimum than the scrape interval to retrieve queries that are more coarse-grained and well-functioning.
{{< admonition type="note" >}}
The **Min interval** corresponds to the min step in Prometheus. Changing the Prometheus interval can change the start and end of the query range because Prometheus aligns the range to the interval. Refer to [Min step](https://grafana.com/docs/grafana/latest/datasources/prometheus/query-editor/#min-step) for more details.
{{< /admonition >}}
- **Interval** - Sets a time span that you can use when aggregating or grouping data points by time.
Grafana automatically calculates an appropriate interval that you can use as a variable in templated queries.
The variable is measured in either seconds (`$__interval`) or milliseconds (`$__interval_ms`).
Intervals are typically used in aggregation functions like sum or average.
For example, this is a Prometheus query that uses the interval variable: `rate(http_requests_total[$__interval])`.
This automatic interval is calculated based on the width of the graph.
As the user zooms out on a visualization, the interval grows, resulting in a more coarse-grained aggregation.
Likewise, if the user zooms in, the interval decreases, resulting in a more fine-grained aggregation.
For more information, refer to [Global variables](ref:global-variables).
- **Relative time** - Overrides the relative time range for individual panels, which causes them to be different than what is selected in the dashboard time picker in the top-right corner of the dashboard.
You can use this to show metrics from different time periods or days on the same dashboard.
{{< admonition type="note">}}
Panel time overrides have no effect when the dashboard's time range is absolute.
{{< /admonition >}}
| Example | Relative time field |
| ---------------- | ------------------- |
| Last 5 minutes | `now-5m` |
| The day so far | `now/d` |
| Last 5 days | `now-5d/d` |
| This week so far | `now/w` |
| Last 2 years | `now-2y/y` |
{{< docs/play title="Time range override" url="https://play.grafana.org/d/000000041/" >}}
- **Time shift** - Overrides the time range for individual panels by shifting its start and end relative to the time picker.
For example, you can shift the time range for the panel to be two hours earlier than the dashboard time picker.
{{< admonition type="note">}}
Panel time overrides have no effect when the dashboard's time range is absolute.
{{< /admonition >}}
| Example | Time shift field |
| -------------------- | ---------------- |
| Last entire week | `1w/w` |
| Two entire weeks ago | `2w/w` |
| Last entire month | `1M/M` |
| This entire year | `1d/y` |
| Last entire year | `1y/y` |
- **Cache timeout** - _(Visible only if available in the data source)_ Overrides the default cache timeout if your time series store has a query cache.
Specify this value as a numeric value in seconds.
docs/sources/visualizations/panels-visualizations/query-transform-data/calculation-types/index.md
+48
View File
@@ -0,0 +1,48 @@
---
aliases:
- ../../../panels-visualizations/calculation-types/ # /docs/grafana/next/panels-visualizations/calculation-types/
- ../../../panels-visualizations/query-transform-data/calculation-types/ # /docs/grafana/next/panels-visualizations/query-transform-data/calculation-types/
- ../../../panels/calculation-types/ # /docs/grafana/<GRAFANA_VERSION>/panels/calculation-types/
- ../../../panels/calculations-list/ # /docs/grafana/<GRAFANA_VERSION>/panels/calculations-list/
- ../../../panels/reference-calculation-types/ # /docs/grafana/<GRAFANA_VERSION>/panels/reference-calculation-types/
labels:
products:
- cloud
- enterprise
- oss
title: Calculation types
description: Learn about the calculations you can apply to your data
weight: 1100
---
# Calculation types
The following table contains a list of calculations you can perform in Grafana. You can find these calculations in the **Transform** tab and in the bar gauge, gauge, stat, and table visualizations.
| Calculation | Description |
| :----------------- | :-------------------------------------------------------- |
| 1st % - 99th % | 1st - 99th percentile value. |
| All nulls | True when all values are null |
| All unique values | Array with all unique values |
| All values | Array with all values |
| All zeros | True when all values are 0 |
| Change count | Number of times the field's value changes |
| Count | Number of values in a field |
| Delta | Cumulative change in value, only counts increments |
| Difference | Difference between first and last value of a field |
| Difference percent | Percentage change between first and last value of a field |
| Distinct count | Number of unique values in a field |
| First | First value in a field |
| First\* (not null) | First, not null value in a field (also excludes NaNs) |
| Last | Last value in a field |
| Last\* (not null) | Last, not null value in a field (also excludes NaNs) |
| Max | Maximum value of a field |
| Median | Median value of all values in a field |
| Mean | Mean value of all values in a field |
| Min | Minimum value of a field |
| Min (above zero) | Minimum, positive value of a field |
| Range | Difference between maximum and minimum values of a field |
| StdDev | Standard deviation of all values in a field |
| Step | Minimal interval between values of a field |
| Total | Sum of all values in a field |
| Variance | Variance of all values in a field |
docs/sources/visualizations/panels-visualizations/query-transform-data/expression-queries/index.md
+263
View File
@@ -0,0 +1,263 @@
---
aliases:
- ../../../panels-visualizations/query-transform-data/ # /docs/grafana/next/panels-visualizations/query-transform-data/
- ../../../panels-visualizations/query-transform-data/expression-queries/ # /docs/grafana/next/panels-visualizations/query-transform-data/expression-queries/
- ../../../panels/query-a-data-source/use-expressions-to-manipulate-data/ # /docs/grafana/next/panels/query-a-data-source/use-expressions-to-manipulate-data/
- ../../../panels/query-a-data-source/use-expressions-to-manipulate-data/about-expressions/ # /docs/grafana/next/panels/query-a-data-source/use-expressions-to-manipulate-data/about-expressions/
- ../../../panels/query-a-data-source/use-expressions-to-manipulate-data/write-an-expression/ # /docs/grafana/next/panels/query-a-data-source/use-expressions-to-manipulate-data/write-an-expression/
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Write expression queries
title: Write expression queries
description: Write server-side expressions to manipulate data using math and other operations
weight: 40
refs:
no-data-and-error-handling:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/alerting-rules/create-grafana-managed-rule/#configure-no-data-and-error-handling
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/alerting-rules/create-grafana-managed-rule/#configure-no-data-and-error-handling
multiple-dimensional-data:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/fundamentals/timeseries-dimensions/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/fundamentals/timeseries-dimensions/
grafana-alerting:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/
labels:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/fundamentals/timeseries-dimensions/#labels
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/fundamentals/timeseries-dimensions/#labels
---
# Write expression queries
Server-side expressions enable you to manipulate data returned from queries with math and other operations. Expressions create new data and do not manipulate the data returned by data sources.
## About expressions
Server-side expressions allow you to manipulate data returned from queries with math and other operations. Expressions create new data and do not manipulate the data returned by data sources, aside from some minor data restructuring to make the data acceptable input for expressions.
### Using expressions
Expressions are most commonly used for [Grafana Alerting](ref:grafana-alerting). The processing is done server-side, so expressions can operate without a browser session. However, expressions can also be used with backend data sources and visualization.
{{< admonition type="note" >}}
Expressions do not work with legacy dashboard alerts.
{{< /admonition >}}
Expressions are meant to augment data sources by enabling queries from different data sources to be combined or by providing operations unavailable in a data source.
{{< admonition type="note" >}}
When possible, you should do data processing inside the data source. Copying data from storage to the Grafana server for processing is inefficient, so expressions are targeted at lightweight data processing.
{{< /admonition >}}
Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data](ref:multiple-dimensional-data). For example, a query that returns multiple series, where each series is identified by labels or tags.
An individual expression takes one or more queries or other expressions as input and adds data to the result. Each individual expression or query is represented by a variable that is a named identifier known as its RefID (e.g., the default letter `A` or `B`).
To reference the output of an individual expression or a data source query in another expression, this identifier is used as a variable.
### Types of expressions
Expressions work with two types of data.
- A collection of time series.
- A collection of numbers, where each number is an item.
Each collection is returned from a single data source query or expression and represented by the RefID. Each collection is a set, where each item in the set is uniquely identified by its dimensions which are stored as [labels](ref:labels) or key-value pairs.
### Data source queries
Server-side expressions only support data source queries for backend data sources. The data is generally assumed to be labeled time series data. In the future we intend to add an assertion of the query return type (number or time series) data so expressions can handle errors better.
Data source queries, when used with expressions, are executed by the expression engine. When it does this, it restructures data to be either one time series or one number per data frame. So for example if using a data source that returns multiple series on one frame in the table view, you might notice it looks different when executed with expressions.
Currently, the only non-time series format (number) is supported when you're using data frames and you have a table response that returns a data frame with no time, string columns, and one number column:
| Loc | Host | Avg_CPU |
| --- | ---- | ------- |
| MIA | A | 1 |
| NYC | B | 2 |
The example above will produce a number that works with expressions. The string columns become labels and the number column the corresponding value. For example `{"Loc": "MIA", "Host": "A"}` with a value of 1.
### Operations
You can use the following operations in expressions: math, reduce, and resample.
#### Math
Math is for free-form math formulas on time series or number data. Math operations take numbers and time series as input and change them to different numbers and time series.
Data from other queries or expressions are referenced with the RefID prefixed with a dollar sign, for example `$A`. If the variable has spaces in the name, then you can use a brace syntax like `${my variable}`.
Numeric constants may be in decimal (`2.24`), octal (with a leading zero like `072`), or hex (with a leading 0x like `0x2A`). Exponentials and signs are also supported (e.g., `-0.8e-2`).
##### Operators
The arithmetic (`+`, binary and unary `-`, `*`, `/`, `%`, exponent `**`), relational (`<`, `>`, `==`, `!=`, `>=`, `<=`), and logical (`&&`, `||`, and unary `!`) operators are supported.
How the operation behaves with data depends on if it is a number or time series data.
With binary operations, such as `$A + $B` or `$A || $B`, the operator is applied in the following ways depending on the type of data:
- If both `$A` and `$B` are a number, then the operation is performed between the two numbers.
- If one variable is a number, and the other variable is a time series, then the operation between the value of each point in the time series and the number is performed.
- If both `$A` and `$B` are time series data, then the operation between each value in the two series is performed for each time stamp that exists in both `$A` and `$B`. The Resample operation can be used to line up time stamps. (**Note:** in the future, we plan to add options to the Math operation for different behaviors).
Summary:
- Number OP number = number
- Number OP series = series
- Series OP series = series
Because expressions work with multiple series or numbers represented by a single variable, binary operations also perform a union (join) between the two variables. This is done based on the identifying labels associated with each individual series or number.
So if you have numbers with labels like `{host=web01}` in `$A` and another number in `$B` with the same labels then the operation is performed between those two items within each variable, and the result will share the same labels. The rules for the behavior of this union are as follows:
- An item with no labels will join to anything.
- If both `$A` and `$B` each contain only one item (one series, or one number), they will join.
- If labels are exact match they will join.
- If labels are a subset of the other, for example and item in `$A` is labeled `{host=A,dc=MIA}` and item in `$B` is labeled `{host=A}` they will join.
- Currently, if within a variable such as `$A` there are different tag _keys_ for each item, the join behavior is undefined.
The relational and logical operators return 0 for false 1 for true.
##### Math Functions
While most functions exist in the own expression operations, the math operation does have some functions similar to math operators or symbols. When functions can take either numbers or series, than the same type as the argument will be returned. When it is a series, the operation of performed for the value of each point in the series.
###### abs
abs returns the absolute value of its argument which can be a number or a series. For example `abs(-1)` or `abs($A)`.
###### is_inf
is_inf takes a number or a series and returns `1` for `Inf` values (negative or positive) and `0` for other values. For example `is_inf($A)`.
{{< admonition type="note" >}}
If you need to specifically check for negative infinity for example, you can do a comparison like `$A == infn()`.
{{< /admonition >}}
###### is_nan
is_nan takes a number or a series and returns `1` for `NaN` values and `0` for other values. For example `is_nan($A)`. This function exists because `NaN` is not equal to `NaN`.
###### is_null
is_null takes a number or a series and returns `1` for `null` values and `0` for other values. For example `is_null($A)`.
###### is_number
is_number takes a number or a series and returns `1` for all real number values and `0` for other values (which are `null`, `Inf+`, `Inf-`, and `NaN`). For example `is_number($A)`.
###### log
Log returns the natural logarithm of of its argument which can be a number or a series. If the value is less than 0, NaN is returned. For example `log(-1)` or `log($A)`.
###### inf, infn, nan, and null
The inf, infn, nan, and null functions all return a single value of the name. They primarily exist for testing. Example: `null()`.
###### round
Round returns a rounded integer value. For example, `round(3.123)` or `round($A)`. (This function should probably take an argument so it can add precision to the rounded value).
###### ceil
Ceil rounds the number up to the nearest integer value. For example, `ceil(3.123)` returns 4.
###### floor
Floor rounds the number down to the nearest integer value. For example, `floor(3.123)` returns 3.
#### Reduce
Reduce takes one or more time series returned from a query or an expression and turns each series into a single number. The labels of the time series are kept as labels on each outputted reduced number.
**Fields:**
- **Function -** The reduction function to use
- **Input -** The variable (refID (such as `A`)) to resample
- **Mode -** Allows control behavior of reduction function when a series contains non-numerical values (null, NaN, +\-Inf)
##### Reduction Functions
###### Count
Count returns the number of points in each series.
###### Mean
Mean returns the total of all values in each series divided by the number of points in that series. In `strict` mode if any values in the series are null or nan, or if the series is empty, NaN is returned.
###### Min and Max
Min and Max return the smallest or largest value in the series respectively. In `strict` mode if any values in the series are null or nan, or if the series is empty, NaN is returned.
###### Sum
Sum returns the total of all values in the series. If series is of zero length, the sum will be 0. In `strict` mode if there are any NaN or Null values in the series, NaN is returned.
##### Last
Last returns the last number in the series. If the series has no values then returns NaN.
##### Reduction Modes
###### Strict
In Strict mode the input series is processed as is. If any values in the series are non-numeric (null, NaN or +\-Inf), NaN is returned.
###### Drop Non-Numeric
In this mode all non-numeric values (null, NaN or +\-Inf) in the input series are filtered out before executing the reduction function.
###### Replace Non-Numeric
In this mode all non-numeric values are replaced by a pre-defined value.
#### Resample
Resample changes the time stamps in each time series to have a consistent time interval. The main use case is so you can resample time series that do not share the same timestamps so math can be performed between them. This can be done by resample each of the two series, and then in a Math operation referencing the resampled variables.
**Fields:**
- **Input -** The variable of time series data (refID (such as `A`)) to resample
- **Resample to -** The duration of time to resample to, for example `10s`. Units may be `s` seconds, `m` for minutes, `h` for hours, `d` for days, `w` for weeks, and `y` of years.
- **Downsample -** The reduction function to use when there are more than one data point per window sample. See the reduction operation for behavior details.
- **Upsample -** The method to use to fill a window sample that has no data points.
- **pad** fills with the last know value
- **backfill** with next known value
- **fillna** to fill empty sample windows with NaNs
## Write an expression
If your data source supports them, then Grafana displays the **Expression** button and shows any existing expressions in the query editor list.
For more information about expressions, refer to [About expressions](#about-expressions).
1. Open the panel.
1. Below the query, click **Expression**.
1. In the **Operation** field, select the type of expression you want to write.
For more information about expression operations, refer to [About expressions](#about-expressions).
1. Write the expression.
1. Click **Apply**.
## Special cases
When any queried data source returns no series or numbers, the expression engine returns `NoData`. For example, if a request contains two data source queries that are merged by an expression, if `NoData` is returned by at least one of the data source queries, then the returned result for the entire query is `NoData`.
For more information about how [Grafana Alerting](ref:grafana-alerting) processes `NoData` results, refer to [No data and error handling](ref:no-data-and-error-handling).
In the case of using an expression on multiple queries, the expression engine requires that all of the queries return an identical timestamp. For example, if using math to combine the results of multiple SQL queries which each use `SELECT NOW() AS "time"`, the expression will only work if all queries evaluate `NOW()` to an identical timestamp; which does not always happen. To resolve this, you can replace `NOW()` with an arbitrary time, such as `SELECT 1 AS "time"`, or any other valid UNIX timestamp.
docs/sources/visualizations/panels-visualizations/query-transform-data/share-query/index.md
+47
View File
@@ -0,0 +1,47 @@
---
aliases:
- ../../../panels/query-a-data-source/share-query/ # /docs/grafana/next/panels/query-a-data-source/share-query/
- ../../../panels-visualizations/query-transform-data/share-query/ # /docs/grafana/next/panels-visualizations/query-transform-data/share-query/
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Share query results
title: Share query results with another panel
description: Reduce the number of queries to your data source by sharing query results
weight: 60
refs:
query:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/#add-a-query
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/#add-a-query
create-a-dashboard:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/
---
# Share query results with another panel
Grafana lets you use the query result from one panel for any other panel in the dashboard. Sharing query results across panels reduces the number of queries made to your data source, which can improve the performance of your dashboard.
The Dashboard data source lets you select a panel in your dashboard that contains the queries ‌you want to share the results for. Instead of sending a separate query for each panel, Grafana sends one query and other panels use the query results to construct visualizations.
This strategy can drastically reduce the number of queries being made when you for example have several panels visualizing the same data.
1. [Create a dashboard](ref:create-a-dashboard).
1. Create a panel.
1. Change the panel title to "Source panel". You'll use this panel as a source for the other panels.
1. Define the [query](ref:query) or queries that you want share.
If you don't have a data source available, use the **Grafana** data source, which returns a random time series that you can use for testing.
1. Add a new panel and select the **Dashboard** data source in the query editor.
1. In the **Use results from panel list**, select the first panel you created.
All queries defined in the source panel are now available to the new panel. Queries defined in the source panel can be shared with multiple panels.
You can click on any of the queries to go to the panel where they are defined.
docs/sources/visualizations/panels-visualizations/query-transform-data/sql-expressions/index.md
+273
View File
@@ -0,0 +1,273 @@
---
aliases:
labels:
products:
- cloud
- enterprise
- oss
menuTitle: SQL expressions
title: SQL expressions
description: Manipulate and transform data in Grafana using SQL expressions.
weight: 45
refs:
expressions:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/expression-queries/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/expression-queries/
---
# SQL expressions
{{< docs/public-preview product="SQL expressions" >}}
SQL Expressions are server-side expressions that manipulate and transform the results of data source queries using MySQL-like syntax. They allow you to easily query and transform your data after it has been queried, using SQL, which provides a familiar and powerful syntax that can handle everything from simple filters to highly complex, multi-step transformations.
In Grafana, a server-side expression is a way to transform or calculate data after it has been retrieved from the data source, but before it is sent to the frontend for visualization. Grafana evaluates these expressions on the server, not in the browser or at the data source.
For general information on Grafana expressions, refer to [Write expression queries](ref:expressions).
![Example of a SQL expression](/media/docs/sql-expressions/sql-expressions-example-1.png)
## Before you begin
- Enable SQL expressions under the feature toggle `sqlExpressions`.
- If you self-host Grafana, you can find feature toggles in the configuration file `grafana.ini`.
```
[feature_toggles]
enable = sqlExpressions
```
- If you are using Grafana Cloud, contact [Support](https://grafana.com/help/) to enable this feature.
## Transform data with SQL expressions
SQL expressions allow you to:
- Shape, transform, and modify query results without changing the original query.
- JOIN data from multiple tables.
- Create alerts or recording rules based on transformed data.
- Perform final-stage modifications to datasets, including:
- Show, hide, or rename columns.
- Filter rows based on conditions.
- Aggregate data (for example: sum, average, count).
- Write subqueries and Common Table Expressions (CTEs) to support more complex logic:
- **Subqueries** are nested queries used for filtering, calculations, or transformations.
- **CTEs** are temporary named result sets that help make complex queries more readable and reusable.
A key capability of SQL expressions is the ability to JOIN data from multiple tables. This allows users to combine and transform data in a predictable, user-friendly way—even for complex use cases. You can JOIN data from an unlimited number of data source queries.
To work with SQL expressions, you must use data from a backend data source. In Grafana, a backend data source refers to a data source plugin or integration that communicates with a database, service, or API through the Grafana server, rather than directly from the browser (frontend).
## Known limitations
- Currently, only one SQL expression is supported per panel or alert.
- Grafana supports certain data sources. Refer to [compatible data sources](#compatible-data-sources) for a current list.
- Autocomplete is available, but column/field autocomplete is only available after enabling the `sqlExpressionsColumnAutoComplete` feature toggle, which is provided on an experimental basis.
## Compatible data sources
The following are compatible data sources:
**Full support:** Grafana supports all query types for each of these data sources.
- Elasticsearch
- MySQL
- Loki
- Graphite
- Google Sheets
- Amazon Athena
**Partial support:** The following data sources have limited or conditional support. Some support multiple query types depending on the service. For example, Azure Monitor can query multiple services, each with its own query format. In some cases, you can also switch the query type within a panel.
- InfluxDB
- Infinity
- Azure Monitor
- TestData
- Tempo
- Prometheus
- Cloudwatch
- GitHub
- BigQuery
## Create SQL expressions
To create a SQL expression, complete the following steps:
1. Navigate to **Dashboards** in the left-side menu.
1. Select a dashboard and open a dashboard panel.
1. Click the ellipsis in the upper right and select **Edit** .
1. Click **+ Expression**.
1. Select **SQL** from the drop-down.
After you have added a SQL expression, you can select from other data source queries by referencing the RefIDs of the queries in your SQL expression as if they were tables in a SQL database.
{{< admonition type="note" >}}
The **RefID** is a unique identifier assigned to each query within a Grafana panel that serves as a reference name for that query's data.
{{< /admonition >}}
![Using the RefID](/media/docs/sql-expressions/using-the-RefID.png)
## Workflow to build SQL expressions
Use the following workflow to create a SQL expression:
1. **Build your base queries.** Create the individual query and give it a meaningful name. Create the queries (A, B, etc.) that provide the data you want to combine or transform using SQL Expressions.
1. **Hide your base queries.** Click the **👁️ Eye icon** next to each base query to hide them from visualization. This keeps your panel clean while still making the data available to the SQL Expression.
1. **Switch to table view**. Set the panel visualization to **Table** to inspect and review the structure and output of your SQL expression as you build and refine it.
1. **Add a SQL Expression**. Add a new query and add select SQL Expression as its type.
**Inspect inputs**. Start with simple test queries to understand the shape of your input frames.
```sql
SELECT * FROM A LIMIT 10.
```
This lets you see the available columns and sample rows from `query A`. Repeat this for each input query you want to use (e.g., `SELECT * FROM B LIMIT 10`).
1. **Inspect your data**. Repeat this for each input query to understand the column structure and data types you're working with.
```sql
SELECT * FROM <B, C, D, etc> LIMIT 10
```
1. **Construct the SQL expression.** Once you understand your data, you can write your SQL expression to join, filter, or otherwise transform the data.
1. **Validate and iterate**. Click **Refresh** every time you update your SQL query to re-evaluate and see the updated result.
When selecting a visualization type, **ensure your SQL expression returns data in the required shape**. For example, time series panels require a column with a time field (e.g., timestamp) and a numeric value column (e.g., \_\_value\_\_). If the output is not shaped correctly, your visualization may appear empty or fail to render.
The SQL expression workflow in Grafana is designed with the following behaviors:
- **Unhidden queries are visualized automatically.** If an input query is not hidden, Grafana will attempt to render it alongside your SQL expression. This can clutter the output, especially in table visualizations.
- **SQL expression results may not be immediately visible.** You might need to use the data frame selector (dropdown at the bottom of the table panel) to switch between the raw query and the SQL expression result.
- **Non-tabular or incorrectly shaped data will not render in certain panels.** Visualizations such as graphs or gauges require properly structured data. Mismatched formats will result in rendering issues or missing data.
## SQL conversion rules
When you reference a RefID within a SQL statement (e.g., `SELECT * FROM A`), the system invokes a distinct SQL conversion process.
The SQL conversion path:
- The query result appears as a single data frame, without labels, and is mapped directly to a tabular format.
- If the frame type is present and is either numeric, wide time series, or multi-frame time series (for example: labeled formats), Grafana automatically converts the data into a table structure.
## Supported functions
Grafana maintains a complete list of supported SQL keywords, operators, and functions in the SQL expressions query validator implementation.
For the most up-to-date reference of all supported SQL functionality, refer to the `allowedNode` and `allowedFunction` definitions in the Grafana [codebase](https://github.com/grafana/grafana/blob/main/pkg/expr/sql/parser_allow.go).
## Alerting and recording rules
SQL expressions integrates alerting and recording rules, allowing you to define complex conditions and metrics using standard SQL queries. The system processes your query results and automatically creates alert instances or recorded metrics based on the returned data structure.
For SQL Expressions to work properly with alerting and recording rules, your query must return:
- One numeric column - **_required_**. This contains the value that triggers alerts or gets recorded.
- Unique string column combinations - **_required_**. Each row must have a unique combination of string column values.
- One or more string columns - _optional_. These become **labels** for the alert instances or metrics. Examples: `service`, `region`.
Consider the following query results:
```sql
error_count,service,region
25,auth-service,us-east
0,payment-service,us-west
15,user-service,eu-west
```
This query returns:
- the numeric column `error_count` (values: 25, 0, 15)
- the string columns `service` and `region`
For alert rules, this creates three alert instances:
- First instance with labels {service=auth-service, region=us-east} and value 25 (triggers alert - high error count)
- Second instance with labels {service=payment-service, region=us-west} and value 0 (no alert - zero errors)
- Third instance with labels {service=user-service, region=eu-west} and value 15 (triggers alert - elevated error count)
For recording rules, creates one metric with three series:
- First series: error_count_total{service=auth-service, region=us-east} 25
- Second series: error_count_total{service=payment-service, region=us-west} 0
- Third series: error_count_total{service=user-service, region=eu-west} 15
Following are some best practices for alerting and recording rules:
- Keep numeric values meaningful (for example: error counts, request duration).
- Use clear, descriptive column names - these become your labels.
- Keep string values short and consistent.
- Avoid too many unique label combinations, as this can result in high cardinality.
- Always use `GROUP BY` to avoid duplicate label errors.
- Aggregate numeric values logically (for example: `SUM(error_count)`).
## Supported data source formats
Grafana supports three types of data source response formats:
1. **Single Table-like Frame**:
This refers to data returned in a standard tabular structure, where all values are organized into rows and columns, similar to what you'd get from a SQL query.
- **Example**: Any query against a SQL data source (e.g., PostgreSQL, MySQL) with the format set to Table.
2. **Dataplane: Time Series Format**:
This format represents time series data with timestamps and associated values. It is typically returned from monitoring data sources.
- **Example**: Prometheus or Loki Range Queries (queries that return a set of values over time).
3. **Dataplane: Numeric Long Format**:
This format is used for point-in-time (instant) metric queries that return a single value (or a set of values) at a specific moment.
- **Example**: Prometheus or Loki Instant Queries (queries that return the current value of a metric).
For more information on Dataplane formats, refer to [Grafana Dataplane Documentation](https://grafana.com/developers/dataplane).
The following non-tabular formats are automatically converted to a tabular format (`FullLong`) when used in SQL expressions:
- **Time Series Wide**: Label keys become column names.
- **Time Series Multi**: Label values become the values in each row (or null if a label is missing).
- **Numeric Wide**: The `value` column contains the numeric metric value.
- **Numeric Multi**: If a display name exists, it will appear in the `display_name` column.
During conversion:
- Label keys become column names.
- Label values populate the corresponding rows (null if a label is missing).
- The `value` column contains the numeric metric.
- If available, the `display_name` column contains a human-readable name.
- The `metric_name` column stores the raw metric identifier.
- For time series data, Grafana includes a `time` column with timestamps
## SQL expressions examples
1. Create the following Prometheus query:
```promql
sum(
rate(go_cpu_classes_gc_total_cpu_seconds_total{namespace=~".*(namespace).*5."}[$__rate_interval])
) by (namespace)
```
The panel displays the CPU usage by Go garbage collection (GC) over time, broken down by namespace.
![Example using a Prometheus query](/media/docs/sql-expressions/sql-expressions-prom-query-example.png)
2. Add the SQL expression `SELECT * from A`. After you add a SQL expression that selects from RefID A, Grafana converts it to a table response:
![Add the SQL expression](/media/docs/sql-expressions/add-the-sql-expression.png)
## LLM integration
The Grafana LLM plugin seamlessly integrates AI-powered assistance into your SQL expressions workflow.
{{< admonition type="note" >}}
The Grafana LLM plugin is currently in public preview, meaning Grafana offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{< /admonition >}}
To use this integration, first [install and configure the LLM plugin](https://grafana.com/grafana/plugins/grafana-llm-app/). After installation, open your dashboard and select **Edit** to open the panel editor. Navigate to the **Queries** tab and scroll to the bottom where you'll find two new buttons positioned to the right of the **Run query** button in your SQL Expressions query.
{{< figure src="/media/docs/sql-expressions/sqlexpressions-LLM-integration-v12.2.png" caption="LLM integration" >}}
Click **Explain query** to open a drawer that displays a detailed explanation of your query, including its interpreted business meaning and performance statistics. Once the explanation is generated, the button changes to **View explanation**.
Click **Improve query** to open a suggestions drawer that contains performance and reliability enhancements, column naming best practices, and guidance on panel optimization. Click **Apply** to implement a suggestion. After you’ve interacted with the interface, you'll see a **Suggestions** button for quick access. Newer suggestions appear at the top, with older ones listed below, creating a history of improvements. If your SQL query has a parsing error, such as a syntax issue, the LLM will attempt to provide a corrected version. The LLM automatically identifies errors and helps you rewrite the query correctly.
docs/sources/visualizations/panels-visualizations/query-transform-data/transform-data/index.md
+1509
View File
File diff suppressed because it is too large Load Diff
docs/sources/visualizations/panels-visualizations/query-transform-data/troubleshoot-queries/index.md
+49
View File
@@ -0,0 +1,49 @@
---
aliases:
- ../../../troubleshooting/troubleshoot-queries/ # /docs/grafana/next/troubleshooting/troubleshoot-queries/
- ../../../panels-visualizations/query-transform-data/troubleshoot-queries/ # /docs/grafana/next/panels-visualizations/query-transform-data/troubleshoot-queries/
description: Troubleshoot Grafana queries
keywords:
- grafana
- troubleshooting
- documentation
- guide
- queries
labels:
products:
- cloud
- enterprise
- oss
title: Troubleshoot queries
weight: 200
refs:
inspect:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/panel-inspector/#inspect-query-request-and-response-data
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/panel-inspector/#inspect-query-request-and-response-data
---
# Troubleshoot queries
This page provides information to solve common dashboard problems.
## I get different results when I rearrange my functions
Function order is very important. Just like in math, the order that you place your functions can affect the result.
## Inspect your query request and response
The most common problems are related to the query and response from your data source. Even if it looks
like a bug or visualization issue in Grafana, it is almost always a problem with the data source query or
the data source response. Start by inspecting your panel query and response.
For more information, refer to [Inspect request and response data](ref:inspect).
## My query is slow
How many data points is your query returning? A query that returns lots of data points will be slow. Try this:
- In **Query options**, limit the **Max data points** returned.
- In **Query options**, increase the **Min interval** time.
- In your query, use a `group by` function.
docs/sources/visualizations/panels-visualizations/visualizations/_index.md
+256
View File
@@ -0,0 +1,256 @@
---
aliases:
- ../../features/panels/graph/ # /docs/grafana/next/features/panels/graph/
- ../../panels-visualizations/visualizations/ # /docs/grafana/next/panels-visualizations/visualizations/
- ../../panels/visualizations/ # /docs/grafana/next/panels/visualizations/
- ../../panels/visualizations/graph-panel/ # /docs/grafana/next/panels/visualizations/graph-panel/
- ../../reference/graph/ # /docs/grafana/next/reference/graph/
- ../../visualizations/ # /docs/grafana/next/visualizations/
- ../../visualizations/graph-panel/ # /docs/grafana/next/visualizations/graph-panel/
labels:
products:
- cloud
- enterprise
- oss
title: Visualizations
description: Apply visualizations to your data
weight: 10
refs:
news:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/news/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/news/
stat:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/stat/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/stat/
node-graph:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/node-graph/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/node-graph/
trend:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/trend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/trend/
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
pie-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/pie-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/pie-chart/
annotations-list:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/annotations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/annotations/
canvas:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/
candlestick:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/candlestick/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/candlestick/
bar-gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-gauge/
xy-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/xy-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/xy-chart/
geomap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/geomap/
flame-graph:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/flame-graph/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/flame-graph/
bar-chart:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/bar-chart/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
table:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/table/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/table/
histogram:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
heatmap:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/heatmap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/heatmap/
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/heatmap/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/heatmap/
datagrid:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/datagrid/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/datagrid/
status-history:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/status-history/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/status-history/
gauge:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/gauge/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/gauge/
logs:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/logs/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/logs/
dashboard-list:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/dashboard-list/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/dashboard-list/
alert-list:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/alert-list/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/alert-list/
traces:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/traces/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/traces/
text:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/text/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/text/
state-timeline:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/state-timeline/
---
# Visualizations
Grafana offers a variety of visualizations to support different use cases. This section of the documentation highlights the built-in visualizations, their options and typical usage.
{{< youtube id="JwF6FgeotaU" >}}
{{< admonition type="note" >}}
If you are unsure which visualization to pick, Grafana can provide visualization suggestions based on the panel query. When you select a visualization, Grafana will show a preview with that visualization applied.
{{< /admonition >}}
- Graphs & charts
- [Time series](ref:time-series) is the default and main graph visualization. Alerts are supported in this panel.
- [State timeline](ref:state-timeline) for state changes over time.
- [Status history](ref:status-history) for periodic state over time.
- [Bar chart](ref:bar-chart) shows any categorical data.
- [Histogram](ref:histogram) calculates and shows value distribution in a bar chart.
- [Heatmap](ref:heatmap) visualizes data in two dimensions, used typically for the magnitude of a phenomenon.
- [Pie chart](ref:pie-chart) is typically used where proportionality is important.
- [Candlestick](ref:candlestick) is typically for financial data where the focus is price/data movement.
- [Gauge](ref:gauge) is the traditional rounded visual showing how far a single metric is from a threshold.
- [Trend](ref:trend) for datasets that have a sequential, numeric x that is not time.
- [XY chart](ref:xy-chart) provides a way to visualize arbitrary x and y values in a graph.
- Stats & numbers
- [Stat](ref:stat) for big stats and optional sparkline.
- [Bar gauge](ref:bar-gauge) is a horizontal or vertical bar gauge.
- Misc
- [Table](ref:table) is the main and only table visualization.
- [Logs](ref:logs) is the main visualization for logs.
- [Node graph](ref:node-graph) for directed graphs or networks.
- [Traces](ref:traces) is the main visualization for traces.
- [Flame graph](ref:flame-graph) is the main visualization for profiling.
- [Canvas](ref:canvas) allows you to explicitly place elements within static and dynamic layouts.
- [Geomap](ref:geomap) helps you visualize geospatial data.
- [Datagrid](ref:datagrid) allows you to create and manipulate data, and act as data source for other panels.
- Widgets
- [Dashboard list](ref:dashboard-list) can list dashboards.
- [Alert list](ref:alert-list) can list alerts.
- [Annotations list](ref:annotations-list) can list available annotations.
- [Text](ref:text) can show markdown and html.
- [News](ref:news) can show RSS feeds.
The following video shows you how to create gauge, time series line graph, stats, logs, and node graph visualizations:
{{< youtube id="yNRnLyVntUw" >}}
## Get more
You can add more visualization types by installing [panel plugins](https://grafana.com/grafana/plugins/?type=panel).
## Examples
Below you can find some good examples for how all the visualizations in Grafana can be configured. You can also explore [play.grafana.org](https://play.grafana.org) which has a large set of demo dashboards that showcase all the different visualizations.
### Graphs
For time based line, area and bar charts we recommend the default [time series](ref:time-series) visualization. [This public demo dashboard](https://play.grafana.org/d/000000016/1-time-series-graphs?orgId=1) contains many different examples for how this visualization can be configured and styled.
{{< figure src="/static/img/docs/time-series-panel/time_series_small_example.png" max-width="700px" caption="Time series" >}}
For categorical data use a [bar chart](ref:bar-chart).
{{< figure src="/static/img/docs/bar-chart-panel/barchart_small_example.png" max-width="700px" caption="Bar chart" >}}
### Big numbers & stats
A [stat](ref:stat) shows one large stat value with an optional graph sparkline. You can control the background or value color using thresholds or color scales.
{{< figure src="/static/img/docs/v66/stat_panel_dark3.png" max-width="1025px" caption="Stat" >}}
### Gauge
If you want to present a value as it relates to a min and max value you have two options. First a standard radial [gauge](ref:gauge) shown below.
{{< figure src="/static/img/docs/v66/gauge_panel_cover.png" max-width="700px" alt="A gauge visualization" >}}
Secondly Grafana also has a horizontal or vertical [bar gauge](ref:bar-gauge) with three different distinct display modes.
{{< figure src="/static/img/docs/v66/bar_gauge_lcd.png" max-width="700px" alt="A bar gauge visualization" >}}
### Table
To show data in a table layout, use a [table](ref:table).
{{< figure src="/static/img/docs/tables/table_visualization.png" max-width="700px" lightbox="true" caption="Table visualization" >}}
### Pie chart
To display reduced series, or values in a series, from one or more queries, as they relate to each other, use a [pie chart](ref:pie-chart).
{{< figure src="/static/img/docs/pie-chart-panel/pie-chart-example.png" max-width="700px" lightbox="true" caption="Pie chart" >}}
### Heatmaps
To show value distribution over, time use a [heatmap](ref:heatmap).
{{< figure src="/static/img/docs/v43/heatmap_panel_cover.jpg" max-width="1000px" lightbox="true" caption="Heatmap" >}}
### State timeline
A state timeline shows discrete state changes over time. When used with time series, the thresholds are used to turn the numerical values into discrete state regions.
{{< figure src="/static/img/docs/v8/state_timeline_strings.png" max-width="700px" caption="State timeline with string states" >}}
docs/sources/visualizations/panels-visualizations/visualizations/alert-list/index.md
+125
View File
@@ -0,0 +1,125 @@
---
aliases:
- ../../../features/panels/alertlist/ # /docs/grafana/next/features/panels/alertlist/
- ../../../panels-visualizations/visualizations/alert-list/ # /docs/grafana/next/panels-visualizations/visualizations/alert-list/
- ../../../panels/visualizations/alert-list-panel/ # /docs/grafana/next/panels/visualizations/alert-list-panel/
- ../../../reference/alertlist/ # /docs/grafana/next/reference/alertlist/
- ../../../visualizations/alert-list-panel/ # /docs/grafana/next/visualizations/alert-list-panel/
keywords:
- grafana
- alert list
- documentation
- panel
- alertlist
labels:
products:
- cloud
- enterprise
- oss
title: Alert list
description: Configure options for Grafana's alert list visualization
weight: 100
refs:
grafana-alerting-overview:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/
create-dashboard:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/create-dashboard/
alert-label:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/fundamentals/alert-rules/annotation-label/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rules/annotation-label/
---
# Alert list
Alert lists allow you to display a list of important alerts that you want to track. You can configure the alert list to show the current state of your alert, such as firing, pending, or normal. Learn more about alerts in [Grafana Alerting overview](ref:grafana-alerting-overview).
![An alert list visualization](/media/docs/grafana/panels-visualizations/screenshot-alert-list-v11.3.png)
On each dashboard load, this visualization queries the alert list, always providing the most up-to-date results.
{{< docs/play title="Alert List" url="https://play.grafana.org/d/bdodlcyou483ke/" >}}
## Configure an alert list
Once you’ve [created a dashboard](ref:create-dashboard), the following video shows you how to configure an alert list visualization:
{{< youtube id="o4rK7_AXZ9Y" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Options
Use the following options to refine your alert list visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| View mode | Choose between **List** to display alerts in a detailed list format with comprehensive information, or **Stat** to show alerts as a summarized single-value statistic. |
| Group mode | Choose between **Default grouping** to show alert instances grouped by their alert rule, or **Custom grouping** to show alert instances grouped by a custom set of labels. |
| Max items | Sets the maximum number of alerts to list. By default, Grafana sets this value to 10. |
| [Sort order](#sort-order) | Select how to order the alerts displayed. |
| Alerts linked to this dashboard | Toggle the switch on to only show alerts from the dashboard the alert list is in. |
<!-- prettier-ignore-end -->
#### Sort order
Select how to order the alerts displayed. Choose from:
- **Alphabetical (asc)** - Alphabetical order.
- **Alphabetical (desc)** - Reverse alphabetical order.
- **Importance** - By importance according to the following values, with 1 being the highest:
- alerting: 1
- firing: 1
- no_data: 2
- pending: 3
- ok: 4
- paused: 5
- inactive: 5
- **Time (asc)** - Newest active alert instances first.
- **Time (desc)** - Oldest active alert instances first.
### Filter options
These options allow you to limit alerts shown to only those that match the query, folder, or tags you choose.
<!-- prettier-ignore-start -->
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| Alert name | Filter alerts by name. |
| Alert instance label | Filter alert instances using [label](ref:alert-label) querying. For example,`{severity="critical", instance=~"cluster-us-.+"}`. |
| Datasource | Filter alerts from the selected data source. |
| Folder | Filter alerts by the selected folder. Only alerts from dashboards in this folder are displayed. |
| Show alerts with 0 instances | Filter for alert rules with no instances. Alert rules with 0 (zero) instances are hidden by default. You can choose to show them by toggling this switch. Because these rules have no instances, they remain hidden if the **Alert instance label** filter is configured. |
### Alert state filter options
Choose which alert states to display in this visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| Alerting / Firing | Shows alerts that are currently active and triggering an alert condition. |
| Pending | Shows alerts that are in a transitional state, waiting for conditions to be met before triggering. |
| No Data | Shows alerts where the data source is not returning any data, which could indicate an issue with data collection. |
| Normal | Shows alerts that are in a normal or resolved state, where no alert condition is currently met. |
| Error | Shows alerts where an error has occurred, typically related to an issue in the alerting process. |
<!-- prettier-ignore-end -->
docs/sources/visualizations/panels-visualizations/visualizations/annotations/index.md
+93
View File
@@ -0,0 +1,93 @@
---
aliases:
- ../../../features/panels/annotations/ # /docs/grafana/next/features/panels/annotations/
- ../../../panels/visualizations/annotations/ # /docs/grafana/next/panels/visualizations/annotations/
- ../../annotations/ # /docs/grafana/next/visualizations/annotations/
- ../../../panels-visualizations/visualizations/annotations/ # /docs/grafana/next/panels-visualizations/visualizations/annotations/
description: Configure options for Grafana's annotations list visualization
keywords:
- grafana
- Annotations
- panel
- documentation
labels:
products:
- cloud
- enterprise
- oss
title: Annotations list
weight: 100
---
# Annotations list
The annotations list shows a list of available annotations you can use to view annotated data. Various options are available to filter the list based on tags and on the current dashboard.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-annotations-list-viz-v12.0.png" max-width="750px" alt="The annotations list visualization" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Annotation query options
The following options control the source query for the list of annotations:
<!-- prettier-ignore-start -->
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| [Query filter](#query-filter) | Specify which annotations are included in the list. |
| [Time Range](#time-range) | Specify whether the list should be limited to the current time range. |
| Tags | Filter the annotations by tags. You can add multiple tags to refine the list. Optionally, leave the tag list empty and filter in view mode by selecting tags that are listed as part of the results on the panel itself. |
| Limit | Limit the number of results returned. |
<!-- prettier-ignore-end -->
#### Query filter
Use the **Query filter** option to create a list of annotations from all dashboards in your organization or the current dashboard in which this panel is located.
Choose from:
- **All dashboards** - List annotations from all dashboards in the current organization.
- **This dashboard** - Limit the list to the annotations on the current dashboard.
#### Time Range
Specify whether the list should be limited to the current time range.
Choose from:
- **None** - No time range limit for the annotations query.
- **This dashboard** - Limit the list to the time range of the dashboard where the annotations list is available.
### Display options
These options control additional metadata included in the annotations list display:
<!-- prettier-ignore-start -->
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| Show user | Show or hide which user created the annotation. |
| Show time | Show or hide the time the annotation creation time. |
| Show tags | Show or hide the tags associated with an annotation. Note that you can use the tags to filter the annotations list. |
<!-- prettier-ignore-end -->
### Link behavior options
Use the following options to control the behavior of annotation links in the list:
<!-- prettier-ignore-start -->
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| Link target | Set how to view the annotated data. Choose from:<ul><li>**Panel** - The link takes you directly to a full-screen view of the panel with the corresponding annotation.</li><li>**Dashboard** - Focuses the annotation in the context of a complete dashboard.</li></ul> |
| Time before | Set the time range before the annotation. Use duration string values like `1h` for one hour and `10m` for 10 minutes. |
| Time after | Set the time range after the annotation. |
<!-- prettier-ignore-end -->
docs/sources/visualizations/panels-visualizations/visualizations/bar-chart/index.md
+222
View File
@@ -0,0 +1,222 @@
---
aliases:
- ../../../panels/visualizations/bar-chart/ # /docs/grafana/next/panels/visualizations/bar-chart/
- ../../bar-chart/ # /docs/grafana/next/visualizations/bar-chart/
- ../../../panels-visualizations/visualizations/bar-chart/ # /docs/grafana/next/panels-visualizations/visualizations/bar-chart/
description: Configure options for Grafana's bar chart visualization
keywords:
- grafana
- docs
- bar chart
- panel
- barchart
labels:
products:
- cloud
- enterprise
- oss
title: Bar chart
weight: 100
refs:
standard-options-definitions:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/#max
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/#max
add-a-field-override:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-overrides/#add-a-field-override
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-overrides/#add-a-field-override
time-series:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
---
# Bar chart
A bar chart is a visual representation that uses rectangular bars, where the length of each bar represents each value.
You can use the bar chart visualization when you want to compare values over different categories or time periods. The visualization can display the bars horizontally or vertically, and can be customized to group or stack bars for more complex data analysis.
![Bar chart visualizations](/media/docs/grafana/panels-visualizations/screenshot-bar-charts-v11.3.png)
You can use the bar chart visualization if you need to show:
- Population distribution by age or location
- CPU usage per application
- Sales per division
- Server cost distribution
## Configure a bar chart
The following video shows you how to create and configure a bar chart visualization:
{{< youtube id="qyKE9-71KkE" >}}
{{< docs/play title="Grafana Bar Charts and Pie Charts" url="https://play.grafana.org/d/ktMs4D6Mk/" >}}
## Supported data formats
To create a bar chart visualization, you need a dataset containing one string or time field (or column) and at least one numeric field, though preferably more than one to make best use of the visualization.
The text or time field is used to label the bars or values in each row of data and the numeric fields are represented by proportionally sized bars.
### Example 1
| Group | Value1 | Value2 | Value3 |
| ----- | ------ | ------ | ------ |
| uno | 5 | 3 | 2 |
![Bar chart single row example](/media/docs/grafana/panels-visualizations/screenshot-grafana-11.1-barchart-example1.png 'Bar chart single row example')
If you have more than one text or time field, by default, the visualization uses the first one, but you can change this in the x-axis option as described in the [Bar chart options](#bar-chart-options) section.
### Example 2
If your dataset contains multiple rows, the visualization displays multiple bar chart groups where each group contains multiple bars representing all the numeric values for a row.
| Group | Value1 | Value2 | Value3 |
| ----- | ------ | ------ | ------ |
| uno | 5 | 3 | 2 |
| dos | 10 | 6 | 4 |
| tres | 20 | 8 | 2 |
![Bar chart multiple row example](/media/docs/grafana/panels-visualizations/screenshot-grafana-11.1-barchart-example2.png 'Bar chart multiple row example')
While the first field can be time-based and you can use a bar chart to plot time-series data, for large amounts of time-series data, we recommend that you use the [time series visualization](ref:time-series) and configure it to be displayed as bars.
We recommend that you only use one dataset in a bar chart because using multiple datasets can result in unexpected behavior.
<!-- vale Grafana.WordList = NO -->
<!-- vale Grafana.Spelling = NO -->
## Apply ad hoc filters from the bar chart
In bar charts, you can apply ad hoc filters directly from the visualization.
To display the filter button, hover your cursor over the bar that has the value for which you want to filter and click the bar:
{{< 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">}}
For more information about applying ad hoc filters this way, refer to [Dashboard drilldown with ad hoc filters](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#dashboard-drilldown-with-ad-hoc-filters).
<!-- vale Grafana.Spelling = YES -->
<!-- vale Grafana.WordList = YES -->
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Bar chart options
Use these options to refine your visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| X Axis | Specify which field is used for the x-axis. |
| Orientation | Choose from: <ul><li>**Auto** - Grafana decides the bar orientation based on the panel dimensions.</li><li>**Horizontal** - Will make the X axis the category axis.</li><li>**Vertical** - Will make the Y axis the category axis.</li></ul> |
| Rotate x-axis tick labels | When the graph is vertically oriented, this setting rotates the labels under the bars. This setting is useful when bar chart labels are long and overlap. |
| X-axis tick label max length | Sets the maximum length of bar chart labels. Labels longer than the maximum length are truncated, and appended with `...`. |
| X-axis labels minimum spacing | Sets the minimum spacing between x-axis labels. Depending on your choice, you can select the **RTL** checkbox to require space from the right side. Choose from: <ul><li>**None** - All tick marks are shown.</li><li>**Small** - 100 px of space is required between labels.</li><li>**Medium** - 200 px of space is required between labels.</li><li>**Large** - 300 px of space is required between labels.</li></ul> |
| Show values | This controls whether values are shown. Values are shown on top or to the left of bars. Choose from: <ul><li>**Auto** Values will be shown if there is space.</li><li>**Always** Always show values.</li><li>**Never** Never show values.</li></ul> |
| Stacking | Controls bar chart stacking. Choose from: <ul><li>**Off**: Bars will not be stacked.</li><li>**Normal**: Bars will be stacked on each other.</li><li>**Percent**: Bars will be stacked on each other, and the height of each bar is the percentage of the total height of the stack.</li></ul> |
| Group width | Controls the width of groups. 1 = Max with, 0 = Min width. |
| Bar width | Controls the width of bars. 1 = Max width, 0 = Min width. |
| Bar radius | Controls the radius of the bars. Choose from: <ul><li>0 = Minimum radius</li><li>0.5 = Maximum radius</li></ul> |
| Highlight full area on cover | Controls if the entire surrounding area of the bar is highlighted when you hover over the bar. |
| Color by field | Use the color value for a sibling field to color each bar value. |
| Line width | Controls line width of the bars. |
| Fill opacity | Controls the fill opacity bars. |
| [Gradient mode](#gradient-mode) | Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard color scheme field option. Gradient appearance is influenced by the **Fill opacity** setting. |
<!-- prettier-ignore-end -->
#### Gradient mode
Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard color scheme field option. Gradient appearance is influenced by the **Fill opacity** setting. Choose from:
- **None** - No gradient fill. This is the default setting.
- **Opacity** - Transparency of the gradient is calculated based on the values on the y-axis. Opacity of the fill is increasing with the values on the Y-axis.
- **Hue** - Gradient color is generated based on the hue of the line color.
- **Scheme** - The bar receives a gradient color defined by the **Standard options > Color scheme** selection.
- **From thresholds** - If the **Color scheme** selection is **From thresholds (by value)**, then each bar is the color of the defined threshold.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-colors-by-thresholds-v11.3.png" alt="Color scheme From thresholds" caption="Color scheme: From thresholds" >}}
- **Gradient color schemes** - The following image shows a bar chart with the **Green-Yellow-Red (by value)** color scheme option selected.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-colors-by-value-v11.3.png" alt="Color scheme Green-Yellow-Red" caption="Color scheme: Green-Yellow-Red" >}}
### Tooltip options
{{< docs/shared lookup="visualizations/tooltip-options-1.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Legend options
{{< docs/shared lookup="visualizations/legend-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Text size
Enter a **Value** to change the size of the text on your bar chart.
### Axis
Use the following field settings to refine how your axes display.
For guidance on configuring more than one y-axis, refer to [Multiple y-axes](#multiple-y-axes).
Some field options will not affect the visualization until you click outside of the field option box you are editing or press Enter.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Placement | Select the placement of the Y-axis. Choose from: <ul><li>**Auto** - Grafana automatically assigns Y-axis to the series. When there are two or more series with different units, then Grafana assigns the left axis to the first unit and right to the following units.</li><li>**Left** - Display all Y-axes on the left side.</li><li>**Right** - Display all Y-axes on the right side.</li><li>**Hidden** - Hide all axes. To selectively hide axes, [add a field override](ref:add-a-field-override) that targets specific fields.</li></ul> |
| Label | Set a Y-axis text label. If you have more than one Y-axis, then you can assign different labels with an override. |
| Width | Set a fixed width of the axis. By default, Grafana dynamically calculates the width of an axis.<br></br>By setting the width of the axis, data whose axes types are different can share the same display proportions. This makes it easier to compare more than one graph’s worth of data because the axes are not shifted or stretched within visual proximity of each other. |
| Show grid lines | Set whether grid lines are displayed in the chart. Choose from: <ul><li>**Auto** - Grafana automatically determines whether grid lines are displayed.</li><li>**On** - Grid lines are always displayed.</li><li>**Off** - Grid lines are never displayed</li></ul> |
| Color | Choose whether the axis color is the **Text** or **Series** color. |
| Show border | Toggle the switch to hide or display the border. |
| Scale | Set how the y-axis is split. Choose from: <ul><li>**Linear**</li><li>**Logarithmic** - Choose between log base 2 or log base 10.</li><li>**Symlog** - Uses a symmetrical logarithmic scale. Choose between log base 2 or log base 10, allowing for negative values.</li></ul> |
| Centered zero | Set the y-axis so it's centered on zero. |
| [Soft min and soft max](#soft-min-and-soft-max) | Set a **Soft min** or **soft max** option for better control of Y-axis limits. By default, Grafana sets the range for the Y-axis automatically based on the dataset. |
<!-- prettier-ignore-end -->
#### Soft min and soft max
Set a **Soft min** or **soft max** option for better control of Y-axis limits. By default, Grafana sets the range for the Y-axis automatically based on the dataset.
**Soft min** and **soft max** settings can prevent blips from turning into mountains when the data is mostly flat, and hard min or max derived from standard min and max field options can prevent intermittent spikes from flattening useful detail by clipping the spikes past a defined point.
You can set standard min/max options to define hard limits of the Y-axis. For more information, refer to [Standard options definitions](ref:standard-options-definitions).
{{< docs/shared lookup="visualizations/multiple-y-axes.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+3" >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/bar-gauge/index.md
+173
View File
@@ -0,0 +1,173 @@
---
aliases:
- ../../../features/panels/bar_gauge/ # /docs/grafana/next/features/panels/bar_gauge/
- ../../../panels/visualizations/bar-gauge-panel/ # /docs/grafana/next/panels/visualizations/bar-gauge-panel/
- ../../bar-gauge-panel/ # /docs/grafana/next/visualizations/bar-gauge-panel/
- ../../../panels-visualizations/visualizations/bar-gauge/ # /docs/grafana/next/panels-visualizations/visualizations/bar-gauge/
description: Configure options for Grafana's bar gauge visualization
keywords:
- grafana
- bar
- bar gauge
labels:
products:
- cloud
- enterprise
- oss
title: Bar gauge
weight: 100
refs:
calculation-types:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/calculation-types/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/calculation-types/
---
# Bar gauge
Bar gauges simplify your data by reducing every field to a single value. You choose how Grafana calculates the reduction. This visualization can show one or more bar gauges depending on how many series, rows, or columns your query returns.
{{< figure src="/static/img/docs/v66/bar_gauge_cover.png" max-width="1025px" alt="Bar gauge panel" >}}
The bar gauge visualization displays values as bars with various lengths or fills proportional to the values they represent. They differ from traditional bar charts in that they act as gauges displaying metrics between ranges. One example is a thermometer displaying body temperature in a bar filling up.
You can use a bar gauge visualization when you need to show:
- Key performance indicators (KPIs)
- System health
- Savings goals
- Attendance
- Process completion rates
## Configure a bar gauge visualization
The following video shows you how to create and configure a bar gauge visualization:
{{< youtube id="7PhDysObEXA" >}}
{{< docs/play title="Bar Gauge" url="https://play.grafana.org/d/vmie2cmWz/" >}}
## Supported data formats
To create a bar gauge visualization, you need a dataset querying at least one numeric field. Every numeric field in the dataset is displayed as a bar gauge. Text or time fields aren't required but if they're present, they're used for labeling.
### Example 1
| Label | Value1 | Value2 | Value3 |
| ----- | ------ | ------ | ------ |
| Row1 | 5 | 3 | 2 |
![Bar gauge with single row of data](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-bargauge-example1.png)
The minimum and maximum range for the bar gauges is automatically pulled from the largest and smallest numeric values in the dataset. You can also manually define the minimum and maximum values as indicated in the [Standard options](#standard-options) section.
You can also define the minimum and maximum from the dataset provided.
### Example 2
| Label | Value | Max | Min |
| ----- | ----- | --- | --- |
| Row1 | 3 | 6 | 1 |
![Bar gauge with single row of data including maximum and minimum](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-bargauge-example2.png)
If you don’t want to show gauges for the min and max values, you can configure only one field to be displayed as described in the [Value options](#value-options) section.
![Bar gauge, single row of data with max and min displaying value](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-bargauge-example3.png)
Even if the min and max aren’t displayed, the visualization still pulls the range from the data set.
### Example 3
The bar gauge visualization also supports multiple records (rows) in the dataset.
| Label | Value1 | Value2 | Value3 |
| ----- | ------ | ------ | ------ |
| Row1 | 5 | 3 | 2 |
| Row2 | 10 | 6 | 4 |
| Row3 | 20 | 8 | 2 |
![Bar gauge with multiple rows of data displaying last row](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-bargauge-example4.png)
By default, the visualization is configured to [calculate](#value-options) a single value per column or series and to display only the last set of data. However, it derives the minimum and maximum from the full dataset even if those values aren’t visible. In this example, that means only the last row of data is displayed in the gauges and the minimum and maximum values are defined as 2 and 20, pulled from the whole dataset.
If you want to show one gauge per cell you can change the **Show** setting from **Calculate** to **All values** and each bar is labeled by concatenating the text column with each value's column name.
![Bar gauge with multiple rows of data displaying all the values](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-bargauge-example5.png)
For more information on these settings, refer to [Value options](#value-options).
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value options
Use the following options to refine how your visualization displays the value:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Show | Set how Grafana displays your data. Choose from:<ul><li>**Calculate** - Show a calculated value based on all rows.</li><li>**All values** - Show a separate value for every row. If you select this option, then you can also limit the number of rows to display.</li></ul> |
| Calculation | If you chose **Calculate** as your **Show** option, select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types](ref:calculation-types). |
| Limit | If you chose **All values** as your **Show** option, enter the maximum number of rows to display. The default is 5,000. |
| Fields | Select the fields display in the panel. |
<!-- prettier-ignore-end -->
### Bar gauge options
Adjust how the gauge is displayed.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Orientation | Choose a stacking direction:<ul><li>**Auto** - Grafana determines the best orientation.</li><li>**Horizontal** - Bars stretch horizontally, left to right.</li><li>**Vertical** - Bars stretch vertically, bottom to top.</li></ul> |
| Display mode | Choose a display mode:<ul><li>**Gradient** - Threshold levels define a gradient.</li><li>**Retro LCD** - The bar is split into sections that are lit or unlit.</li><li>**Basic** - Single color based on the matching threshold.</li></ul> |
| Value display | Choose a value display mode:<ul><li>**Value color** - Value color is determined by value.</li><li>**Text color** - Value color is default text color.</li><li>**Hidden** - Values are hidden.</li></ul> |
| Name placement | Set the name placement mode when the bar gauge orientation is **Auto** or **Horizontal**. Choose from:<ul><li>**Auto** - Grafana determines the best placement.</li><li>**Top** - Names are placed on top of each bar gauge.</li><li>**Left** - Names are placed to the left of each bar gauge.</li><li>**Hidden** - Names are hidden.</li></ul> <p>When the bar gauge is in the vertical orientation, choose from **Auto** (names are always placed at the bottom of each bar) or **Hidden**.</p>|
| Show unfilled area | Select if you want to render the unfilled region of the bars as dark gray. Not applicable to **Retro LCD** display mode. |
| Bar size | Choose a bar size mode:<ul><li>**Auto** - Grafana determines the best bar size.</li><li>**Manual** - Manually configure the bar size.</li></ul> |
| Min width | Limit the minimum width of the bar column when the gauge is oriented vertically or is in **Auto** mode. Automatically shows the x-axis scroll bar when there's a large amount of data.<p>This option only applies when the **Bar size** mode is set to **Manual**.</p> |
| Min height | Limit the minimum height of the bar row when the bar gauge is oriented horizontally or is in **Auto** mode. Automatically shows the y-axis scroll bar when there's a large amount of data. <p>This option only applies when the **Bar size** mode is set to **Manual**.</p> |
| Max height | Limit the maximum height of the bar row when the bar gauge is oriented horizontally or is in **Auto** mode. Automatically shows the y-axis scroll bar when there's a large amount of data. <p>This option only applies when the **Bar size** mode is set to **Manual**.</p> |
<!-- prettier-ignore-end -->
### Legend options
{{< docs/shared lookup="visualizations/legend-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Text size options
Set the sizes of the following text elements in pixels:
- **Title** - Bar name
- **Value** - Bar value
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/candlestick/index.md
+332
View File
@@ -0,0 +1,332 @@
---
aliases:
- ../../../features/panels/candlestick/ # /docs/grafana/next/features/panels/candlestick/
- ../../../panels/visualizations/candlestick/ # /docs/grafana/next/panels/visualizations/candlestick/
- ../../candlestick/ # /docs/grafana/next/visualizations/candlestick/
- ../../../panels-visualizations/visualizations/candlestick/ # /docs/grafana/next/panels-visualizations/visualizations/candlestick/
description: Configure options for Grafana's candlestick visualization
keywords:
- grafana
- Candlestick
- OHLC
- panel
- documentation
labels:
products:
- cloud
- enterprise
- oss
title: Candlestick
weight: 100
refs:
time-series-visualization:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
color-scheme:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/#color-scheme
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/#color-scheme
configure-field-overrides:
- 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/
add-a-field-override:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-overrides/#add-a-field-override
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-overrides/#add-a-field-override
---
# Candlestick
The candlestick visualization allows you to visualize data that includes a number of consistent dimensions focused on price movements, such as stock prices. The candlestick visualization includes an [Open-High-Low-Close (OHLC) mode](#open-high-low-close), as well as support for additional dimensions based on time series data.
Candlestick visualizations build upon the foundation of the [time series visualization](ref:time-series-visualization) and include many common configuration settings.
You can use a candlestick if you want to visualize, at a glance, how a price moved over time, whether it went up, down, or stayed the same, and how much it fluctuated:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candlestick-v11.6.png" max-width="750px" alt="A candlestick visualization" >}}
Each candlestick is represented as a rectangle, referred to as the _candlestick body_. The candlestick body displays the opening and closing prices during a time period. Green candlesticks represent when the price appreciated while the red candlesticks represent when the price depreciated. The lines sticking out the candlestick body are referred to as _wicks_ or _shadows_, which represent the highest and lowest prices during the time period.
Use a candlestick when you need to:
- Monitor and identify trends in price movements of specific assets such as stocks, currencies, or commodities.
- Analyze any volatility in the stock market.
- Provide data analysis to help with trading decisions.
## Configure a candlestick
Once you’ve created a [dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/), the following video shows you how to configure a candlestick visualization:
{{< youtube id="IOFKBgbf3aM" >}}
{{< docs/play title="Candlestick" url="https://play.grafana.org/d/candlestick/candlestick" >}}
## Supported data formats
The candlestick visualization works best with price movement data for an asset. The data must include:
- **Timestamps** - The time at which each price movement occurred.
- **Opening price** - The price of the asset at the beginning of the time period.
- **Closing price** - The price of the asset at the end of the time period.
- **Highest price** - The highest price the asset reached during the time period.
- **Lowest price** - The lowest price the asset reached during the time period.
### Example
| Timestamps | Open | High | Low | Close |
| ------------------- | ----- | ----- | ----- | ----- |
| 2024-03-13 10:05:00 | 0.200 | 0.205 | 0.201 | 0.203 |
| 2024-03-14 10:10:10 | 0.204 | 0.205 | 0.201 | 0.200 |
| 2024-03-15 10:15:10 | 0.204 | 0.205 | 0.201 | 0.200 |
| 2024-03-16 10:20:11 | 0.203 | 0.203 | 0.202 | 0.203 |
| 2024-03-17 10:25:11 | 0.203 | 0.203 | 0.202 | 0.203 |
| 2024-03-18 10:30:12 | 0.202 | 0.202 | 0.201 | 0.201 |
The data is converted as follows:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candles-volume-v11.6.png" max-width="750px" alt="A candlestick visualization showing the price movements of specific asset." >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Candlestick options
The following options let you control which data is displayed in the visualization and how it appears:
| Option | Description |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mode | Controls which dimensions are used for the visualization. Choose from:<ul><li>**Candles** - Uses the open, high, low, and close dimensions.</li><li>**Volume** - Uses only the volume dimension.</li><li>**Both** - The default behavior, which displays both candles and volume values.</li></ul> |
| Candle style | Controls the appearance of the candles. Choose from:<ul><li>**Candles** - The default display style, which creates candle-style markers between the open and close dimensions.</li><li>**OHLC Bars** - Displays values for the four core dimensions, open, high, low, and close.</li></ul> |
| [Color strategy](#color-strategy) | Controls how colors are applied to dimensions. Choose from:<ul><li>**Since Open** - This mode uses the **Up color** if the intra-period price movement is positive.</li><li>**Since Prior Close** - The color of the candle is based on the inter-period price movement or change in value.</li></ul> |
| Up color/Down color | These options control which colors are used when the price movement is up or down. Note that the **Color strategy** selection determines if intra-period or inter-period price movement is used to select the candle or OHLC bar color. |
| [Open, High, Low, Close, Volume](#open-high-low-close) | The candlestick visualization attempts to map fields from your data to these dimensions, as appropriate dimension. |
| [Additional fields](#additional-fields) | The **Include** and **Ignore** options allow the candlestick visualization to display other included data such as simple moving averages, Bollinger bands and more, using the same styles and configurations available in the [time series](ref:time-series-visualization) visualization. |
#### Color strategy
The **Color strategy** option controls how colors are applied to dimensions. Choose from:
- **Since Open** - The default behavior. This mode uses the **Up color** if the intra-period price movement is positive. In other words, if the value on close is greater or equal to the value on open, the **Up color** is used.
- **Since Prior Close** - An alternative display method where the color of the candle is based on the inter-period price movement or change in value. In other words, if the value on open is greater than the previous value on close, the **Up color** is used. If the value on open is lower than the previous value on close, the **Down color** is used.
This option also triggers the _hollow candlestick_ visualization mode. Hollow candlesticks indicate that the intra-period movement is positive (value is higher on close than on open), while filled candlesticks indicate the intra-period change is negative (value is lower on close than on open). To learn more, refer to the [explanation of the differences](https://thetradingbible.com/how-to-read-hollow-candlesticks).
#### Open, High, Low, Close, Volume {#open-high-low-close}
The candlestick visualization attempts to map fields from your data to the appropriate dimension:
- **Open** - Starting value of the given period.
- **High** - Highest value of the given period.
- **Low** - Lowest value of the given period.
- **Close** - Final (end) value of the given period.
- **Volume** - Sample count in the given period (for example, number of trades).
{{< admonition type="note" >}}
The candlestick visualization legend doesn't display these values.
{{< /admonition >}}
If your data can't be mapped to these dimensions for some reason (for example, because the column names aren't the same), you can map them manually using the **Open**, **High**, **Low**, and **Close** fields under the **Candlestick** options in the panel editor:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-olhc-options-v11.6.png" max-width="400px" alt="Open, High, Low, and Close fields in the panel editor" >}}
#### Additional fields
The candlestick visualization is based on the time series visualization, and it can visualize additional data dimensions beyond open, high, low, close, and volume.
The **Include** and **Ignore** options allow it to visualize other included data such as simple moving averages, Bollinger bands and more, using the same styles and configurations available in the [time series](ref:time-series-visualization) visualization.
### Tooltip options
Tooltip options control the information overlay that appears when you hover over data points in the visualization.
| Option | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [Tooltip mode](#tooltip-mode) | When you hover your cursor over the visualization, Grafana can display tooltips. Choose how tooltips behave. |
| [Values sort order](#values-sort-order) | This option controls the order in which values are listed in a tooltip. |
| [Hover proximity](#hover-proximity) | Set the hover proximity (in pixels) to control how close the cursor must be to a data point to trigger the tooltip to display. |
| Max width | Set the maximum width of the tooltip box. |
| Max height | Set the maximum height of the tooltip box. The default is 600 pixels. |
#### Tooltip mode
When you hover your cursor over the visualization, Grafana can display tooltips. Choose how tooltips behave.
- **Single -** The hover tooltip shows only a single series, the one that you are hovering over on the visualization.
- **All -** The hover tooltip shows all series in the visualization. Grafana highlights the series that you are hovering over in bold in the series list in the tooltip.
- **Hidden -** Do not display the tooltip when you interact with the visualization.
Use an override to hide individual series from the tooltip.
#### Values sort order
When you set the **Tooltip mode** to **All**, the **Values sort order** option is displayed. This option controls the order in which values are listed in a tooltip. Choose from the following:
- **None** - Grafana automatically sorts the values displayed in a tooltip.
- **Ascending** - Values in the tooltip are listed from smallest to largest.
- **Descending** - Values in the tooltip are listed from largest to smallest.
#### Hover proximity
Set the hover proximity (in pixels) to control how close the cursor must be to a data point to trigger the tooltip to display.
The following screen recording shows this option in a time series visualization:
![Adding a hover proximity limit for tooltips](/media/docs/grafana/gif-grafana-10-4-hover-proximity.gif)
### Legend options
{{< docs/shared lookup="visualizations/legend-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Graph styles options
The options under the **Graph styles** section let you control the general appearance of [additional fields](#additional-fields) in the visualization, excluding [color](#standard-options).
<!-- prettier-ignore-start -->
| Option | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Style](#style) | Choose whether to display your time-series data as **Lines**, **Bars**, or **Points**. |
| [Line interpolation](#line-interpolation) | Choose how the graph interpolates the series line. |
| Line width | Set the thickness of the series lines or the outline for bars using the **Line width** slider. |
| Fill opacity | Set the series area fill color using the **Fill opacity** slider. |
| [Gradient mode](#gradient-mode) | Choose a gradient mode to control the gradient fill, which is based on the series color. |
| [Line style](#line-style) | Choose a solid, dashed, or dotted line style. |
| [Connect null values](#connect-null-values) | Choose how null values, which are gaps in the data, appear on the graph. |
| [Disconnect values](#disconnect-values) | Choose whether to set a threshold above which values in the data should be disconnected. |
| [Show points](#show-points) | Set whether to show data points to lines or bars. |
| Point size | Set the size of the points, from 1 to 40 pixels in diameter. |
| [Stack series](#stack-series) | Set whether Grafana displays series on top of each other. |
| [Bar alignment](#bar-alignment) | Set the position of the bar relative to a data point. |
| Bar width factor | Set the width of the bar relative to minimum space between data points. A factor of 0.5 means that the bars take up half of the available space between data points. A factor of 1.0 means that the bars take up all available space. |
<!-- prettier-ignore-end -->
#### Style
Choose whether to display your time-series data as **Lines**, **Bars**, or **Points**.
You can use overrides to combine multiple styles in the same graph. Choose from the following:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candle-style-v12.0.png" max-width="750px" alt="Graph styles" >}}
#### Line interpolation
Choose how the graph interpolates the series line:
- **Linear** - Points are joined by straight lines.
- **Smooth** - Points are joined by curved lines that smooths transitions between points.
- **Step before** - The line is displayed as steps between points. Points are rendered at the end of the step.
- **Step after** - The line is displayed as steps between points. Points are rendered at the beginning of the step.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candle-interpolation-v12.0.png" max-width="750px" alt="Line interpolation styles" >}}
#### Gradient mode
Choose a gradient mode to control the gradient fill, which is based on the series color. To change the color, use the standard color scheme field option. For more information, refer to [Color scheme](ref:color-scheme).
- **None** - No gradient fill. This is the default setting.
- **Opacity** - An opacity gradient where the opacity of the fill increases as y-axis values increase.
- **Hue** - A subtle gradient that's based on the hue of the series color.
- **Scheme** - A color gradient defined by your [Color scheme](ref:color-scheme). This setting is used for the fill area and line. For more information about scheme, refer to [Scheme gradient mode](#scheme-gradient-mode).
Gradient appearance is influenced by the **Fill opacity** setting. The following image shows the **Fill opacity** set to 50.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candle-gradient-v12.0.png" max-width="750px" alt="Gradient modes" >}}
##### Scheme gradient mode
In **Scheme** gradient mode, the line or bar receives a gradient color defined from the selected **Color scheme** option in the visualization's **Standard** options.
The following image shows a line chart with the **Green-Yellow-Red (by value)** color scheme option selected:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candle-scheme-grad-1-v12.0.png" max-width="600px" alt="Gradient color scheme" >}}
If the **Color scheme** is set to **From thresholds (by value)** and **Gradient mode** is set to **Scheme**, then the line or bar color changes as it crosses the defined thresholds:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candle-scheme-grad-2-v12.0.png" max-width="600px" alt="Gradient color scheme with thresholds" >}}
#### Line style
Choose a solid, dashed, or dotted line style:
- **Solid** - Display a solid line. This is the default setting.
- **Dash** - Display a dashed line. When you choose this option, a list appears for you to select the length and gap (length, gap) for the line dashes. Dash spacing is 10, 10 by default.
- **Dots** - Display dotted lines. When you choose this option, a list appears for you to select the gap (length = 0, gap) for the dot spacing. Dot spacing is 0, 10 by default.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-candle-line-style-v12.0.png" max-width="750px" alt="Line styles" >}}
{{< docs/shared lookup="visualizations/connect-null-values.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
{{< docs/shared lookup="visualizations/disconnect-values.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
To change the color, use the standard [color scheme](ref:color-scheme) field option.
#### Show points
Set whether to show data points as lines or bars. Choose from the following:
- **Auto** - Grafana determines a point's visibility based on the density of the data. If the density is low, then points appear.
- **Always** - Show the points regardless of how dense the dataset is.
- **Never** - Don't show points.
#### Stack series
Set whether Grafana stacks or displays series on top of each other. Be cautious when using stacking because it can create misleading graphs. To read more about why stacking might not be the best approach, refer to [The issue with stacking](https://www.data-to-viz.com/caveat/stacking.html). Choose from the following:
- **Off** - Turns off series stacking. When **Off**, all series share the same space in the visualization.
- **Normal** - Stacks series on top of each other.
- **100%** - Stack by percentage where all series add up to 100%.
##### Stack series in groups
The stacking group option is only available as an override. For more information about creating an override, refer to [Configure field overrides](ref:configure-field-overrides).
1. Edit the panel and click **Overrides**.
1. Create a field override for the **Stack series** option.
1. In stacking mode, click **Normal**.
1. Name the stacking group in which you want the series to appear.
The stacking group name option is only available when you create an override.
#### Bar alignment
Set the position of the bar relative to a data point. In the examples below, **Show points** is set to **Always** which makes it easier to see the difference this setting makes. The points don't change, but the bars change in relationship to the points. Choose from the following:
- **Before** ![Bar alignment before icon](/static/img/docs/time-series-panel/bar-alignment-before.png)
The bar is drawn before the point. The point is placed on the trailing corner of the bar.
- **Center** ![Bar alignment center icon](/static/img/docs/time-series-panel/bar-alignment-center.png)
The bar is drawn around the point. The point is placed in the center of the bar. This is the default.
- **After** ![Bar alignment after icon](/static/img/docs/time-series-panel/bar-alignment-after.png)
The bar is drawn after the point. The point is placed on the leading corner of the bar.
### Axis options
{{< docs/shared lookup="visualizations/axis-options-2.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/canvas/index.md
+516
View File
@@ -0,0 +1,516 @@
---
aliases:
- ../../../features/panels/canvas/ # /docs/grafana/next/features/panels/canvas/
- ../../canvas/ # /docs/grafana/next/visualizations/canvas/
- ../../../panels-visualizations/visualizations/canvas/ # /docs/grafana/next/panels-visualizations/visualizations/canvas/
description: Configure options for Grafana's canvas visualization
keywords:
- grafana
- canvas
- panel
- documentation
labels:
products:
- cloud
- enterprise
- oss
title: Canvas
weight: 100
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/
---
# Canvas
Canvases combine the power of Grafana with the flexibility of custom elements.
They are extensible visualizations that allow you to add and arrange elements wherever you want within unstructured static and dynamic layouts.
This lets you design custom visualizations and overlay data in ways that aren't possible with standard Grafana visualizations, all within the Grafana UI.
{{< video-embed src="/static/img/docs/canvas-panel/canvas-beta-overview-9-2-0.mp4" max-width="750px" alt="Canvas beta overview" >}}
If you've used popular UI and web design tools, then designing canvases will feel very familiar.
With all of these dynamic elements, there's almost no limit to what a canvas can display.
{{< admonition type="note" >}}
We'd love your feedback on the canvas visualization. Please check out the [open Github issues](https://github.com/grafana/grafana/issues?page=1&q=is%3Aopen+is%3Aissue+label%3Aarea%2Fpanel%2Fcanvas) and [submit a new feature request](https://github.com/grafana/grafana/issues/new?assignees=&labels=type%2Ffeature-request,area%2Fpanel%2Fcanvas&title=Canvas:&projects=grafana-dataviz&template=1-feature_requests.md) as needed.
{{< /admonition >}}
## Configure a canvas visualization
The following video shows you how to create and configure a canvas visualization:
{{< youtube id="b7AYKoFcPpY" >}}
## Supported data formats
The canvas visualization is unique in that it doesn't have any specific data requirements. You can even start adding and configuring visual elements without providing any data. However, any data you plan to consume should be accessible through supported Grafana data sources and structured in a way that ensures smooth integration with your custom elements.
If your canvas is going to update in real time, your data should support refreshes at your desired intervals without degrading the user experience.
You can tie [Elements](#elements) and [Connections](#connections) to data through options like text, colors, and background pattern images, etc. available in the canvas visualization.
## Elements
Elements are the basic building blocks of a canvas and they help you visualize data with different shapes and options. You can rotate and move elements around the canvas. When you move elements, snapping and alignment guides help you create more precise layouts.
Add elements in the [Layer](#layer-options) section of canvas options.
{{< admonition type="note" >}}
Element snapping and alignment only works when the canvas is not zoomed in.
{{< /admonition >}}
### Element types
When you select an element that you've added to a canvas, you can access [configuration options](#selected-element-options) for it that are dependent on the element type.
The following sections describe the different elements available.
{{< column-list >}}
- [Metric value](#metric-value)
- [Text](#text)
- [Ellipse](#basic-shapes)
- [Rectangle](#basic-shapes)
- [Icon](#icon)
- [Server](#server)
- [Triangle](#basic-shapes)
- [Cloud](#basic-shapes)
- [Parallelogram](#basic-shapes)
- [Button](#button)
{{< /column-list >}}
#### Basic shapes
A basic shape element can display text (both fixed and field data) and its background color can be changed based on data thresholds. You can add the following basic shapes to a canvas:
- Cloud
- Ellipse
- Parallelogram
- Rectangle
- Triangle
#### Metric value
The metric value element lets you select the data you want to display on a canvas. This element has a unique “edit” mode that can be triggered either through the context menu “Edit” option or by double clicking. When in edit mode you can select which field data that you want to display.
#### Text
The text element lets you add text to the canvas. The element also supports an editing mode, triggered via either double clicking or the edit menu option in the context menu.
#### Icon
The icon element lets you add a supported icon to the canvas. Icons can have their color set based on thresholds or value mappings.
##### Add a custom icon
You can add a custom icon by referencing an SVG file. To add a custom icon, follow these steps:
1. Under **Icon > SVG Path**, if it's not already selected, select **Fixed** as your file source.
1. Click **Select a value** in the field below.
1. In the dialog box that opens, click the **URL** tab.
1. Enter the URL in the field below the **URL** tab.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="250px" alt="Add a custom image URL" >}}
1. Click **Select**.
1. (Optional) Add a background image to your icon with the **Background (icon)** option by following the steps to [add a custom image](#add-custom-images-to-elements).
If you don't have an SVG file, you can use a rectangle element instead of an icon and set its background image to an image file type. To add a custom image for another element type, follow the steps to [add a custom image](#add-custom-images-to-elements).
#### Server
The server element lets you easily represent a single server, a stack of servers, a database, or a terminal. Server elements support status color, bulb color, and a bulb blink rate all configurable by fixed or field values.
{{< figure src="/media/docs/grafana/canvas-server-element-9-4-0.png" max-width="650px" alt="Canvas server element" >}}
#### Button
The button element lets you add a basic button to the canvas. Button elements support triggering basic, unauthenticated API calls. [API settings](#button-api-options) are found in the button element editor. You can also pass template variables in the API editor.
{{< admonition type="note" >}}
A button click will only trigger an API call when [inline editing](#inline-editing) is disabled.
{{< /admonition >}}
{{< video-embed src="/media/docs/grafana/2023-20-10-Canvas-Button-Element-Enablement-Video.mp4" max-width="650px" alt="Canvas button element demo" >}}
{{< docs/play title="Canvas Visualization: Buttons" url="https://play.grafana.org/d/c9ea65f5-ed5a-45cf-8fb7-f82af7c3afdf/" >}}
##### Button API options
The following options let you configure basic, unauthenticated API calls:
<!-- prettier-ignore-start -->
| Option | Description |
| ------- | ------------ |
| Endpoint | Enter the endpoint URL. |
| Method | Choose from **GET**, **POST**, and **PUT**. |
| Content-Type | Select an option in the drop-down list. Choose from: JSON, Text, JavaScript, HTML, XML, and x-www-form-urlencoded. |
| Query parameters | Enter as many **Key**, **Value** pairs as you need. |
| Header parameters | Enter as many **Key**, **Value** pairs as you need. |
| Payload | Enter the body of the API call. |
<!-- prettier-ignore-end -->
### Add custom images to elements
You can add custom background images to all elements except **Button** by referencing an image URL.
The image must be hosted at a URL that allows requests from your Grafana instance.
To upload a custom image, follow these steps:
1. Under **Background (\<ELEMENT TYPE\>)**, if it's not already selected, select **Fixed** as your image source.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-src-v11.3.png" max-width="300px" alt="Custom image source selection" >}}
1. Click **Select a value** in the field below.
1. In the dialog box that opens, click the **URL** tab.
1. Enter the URL in the field below the **URL** tab.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="250px" alt="Add a custom image URL" >}}
1. Click **Select**.
## Connections
When building a canvas, you can connect elements together to create more complex visualizations. You can also create connections to the background of the canvas.
To create a connection, follow these steps:
1. In the panel edit pane, expand the **Canvas** options section.
1. Toggle on the **Inline editing** switch.
1. Hover the cursor over an element you want to connect to display the connection anchors:
![Element with connection anchors displayed](/media/docs/grafana/panels-visualizations/screenshot-connection-anchors-v11.3.png)
1. Drag the cursor from a connection anchor on that element to one on another element.
To remove a connection, click the connection and then press the `Delete` or `Backspace` key.
### Connection adjustments
You can adjust connections, adding angles to them, to fit the canvas you're working in. When you move connected elements, the connection resizes to fit the space.
- To adjust a connection, click it to display the midpoint controls and move those as needed.
- To make a connection a straight line again, move the midpoint back until the midpoint controls disappear.
If you move a connection so that it's almost a right angle or a straight line, the connection snaps into that angle or into a straight line.
### Connection styles
You can set the size, color, direction, and style of connections based on fixed or field values. To do so, enter into panel edit mode, select the connection, and modify the connection's properties in the panel editor. For more information on connection styles, refer to [Selected connection options](#selected-connection-options).
{{< youtube id="0iO2gqv0XNA" >}}
## Canvas editing
You can make changes to a canvas visualization while in the context of the dashboard, or in dashboard mode. The following sections describe the editing options available in dashboard mode.
### Inline editor
You can edit your canvas inline while in dashboard mode. The inline editor menu displays the options relevant to the part of the canvas that you've selected. You can also move the editor window around.
{{< video-embed src="/static/img/docs/canvas-panel/canvas-inline-editor-9-2-0.mp4" max-width="750px" alt="Inline editor demo" >}}
### Context menu
The context menu lets you perform common tasks quickly and efficiently. Supported functionality includes opening and closing the inline editor, duplicating an element, deleting an element, and more.
The context menu is triggered by a right click action over the panel or over a given canvas element. When right clicking the panel, you are able to set a background image and easily add elements to the canvas.
{{< figure src="/static/img/docs/canvas-panel/canvas-panel-context-menu-9-3-0.png" max-width="350px" alt="Canvas panel context menu" >}}
When right clicking an element, you are able to edit, delete, duplicate, and modify the element's layer positioning.
{{< figure src="/static/img/docs/canvas-panel/canvas-context-menu-9-2-0.png" max-width="250px" alt="Canvas element context menu" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Canvas options
#### Inline editing
The inline editing toggle lets you lock or unlock the canvas. When turned off the canvas becomes “locked”, freezing elements in place and preventing unintended modifications.
{{< video-embed src="/static/img/docs/canvas-panel/canvas-inline-editing-toggle-9-2-0.mp4" max-width="750px" alt="Inline editing toggle demo" >}}
#### Experimental Element types
Toggle the switch to include experimental element types in the available selections.
#### Pan and zoom
You can enable panning and zooming in a canvas. This allows you to both create and navigate more complex designs.
{{< docs/public-preview product="Canvas pan and zoom" featureFlag="`canvasPanelPanZoom`" >}}
Use the following pointer and keyboard strokes:
- **Zoom in** - Scroll up
- **Zoom out** - Scroll down
- **Pan** - Middle mouse/wheel + drag OR Control + right-click + drag
- **Reset** - Double-click
{{< video-embed src="/media/docs/grafana/2024-01-05-Canvas-Pan-&-Zoom-Enablement-Video.mp4" max-width="750px" alt="Canvas pan and zoom enablement video" >}}
##### Zoom to content
When you toggle on the **Zoom to content** switch, Grafana automatically adjusts the view to fit all visible elements in your canvas visualization into the viewport, adding a small margin around the edges. This makes it easy to reset your view, present content, or switch between devices without losing your framing. The content will re‑fit even if you resize the panel.
##### Infinite panning
You can enable infinite panning in a canvas when pan and zoom is enabled. This allows you to pan and zoom the canvas and uncover larger designs.
{{< admonition type="note" >}}
Infinite panning is an experimental feature that may not work as expected in all scenarios. For example, elements that are not top-left constrained may experience unexpected movement when panning.
{{< /admonition >}}
### Tooltip options
The **Tooltip mode** setting controls the display of tooltips when hovering over canvas elements that are connected to data, data links, or actions.
The options are:
- **Enabled** - Show a tooltip when the cursor hovers over an element.
- **Disabled** - Tooltips are not shown on hover.
The **Disable for one-click elements** setting allows hiding tooltips on elements that have one-click functionality enabled. This prevents tooltips from interfering with one-click interactions while still allowing tooltips on other elements.
### Layer options
The **Layer** options let you add elements to the canvas and control its appearance:
- [Elements](#elements-layer)
- [Background](#background-canvas)
- [Border](#border-canvas)
#### Elements (layer)
Use the **Add item** button to open the [element type](#element-types) drop-down list. Elements are listed in the reverse order that you add them to the canvas:
![Canvas elements added in the Layer options](/media/docs/grafana/panels-visualizations/screenshot-canvas-elements-v11.3.png)
By default, elements have numbered names, like "Element 1", and those numbers correspond to the order in which the elements were added, but you can [change the default names](#rename-an-element).
You can also take the following actions on elements:
- Change the order of elements by clicking and holding the row of the element while moving it up and down in the element list.
- Duplicate or remove elements by clicking the icons on the element row.
- Access the element editing options by clicking the element row. This displays the [Selected element](#selected-element-options) section of options. Click **Clear selection** to remove the element from focus and stop displaying that section of options.
##### Rename an element
To update the name of an element, follow these steps:
1. Hover the cursor over the element name so the **Edit layer name** (pencil) icon is displayed.
1. Click the **Edit layer name** icon.
1. Enter a new name.
1. Click outside of the name field.
#### Background (canvas)
Use the following options to control the background of the canvas:
| Option | Description |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| Color | Set the background color. |
| Image | Use one of the provided background images or [add your own custom image](#add-custom-images-to-elements). |
| Image size | Control the size of the image or set it as a tile. |
#### Border (canvas)
Use the following options to control the border of the canvas:
| Option | Description |
| ------ | ----------------------------------------------------------------------------------------------- |
| Width | Set the border width in pixels. |
| Color | Set the border color. This option is only displayed when the border width is greater than zero. |
| Radius | Add rounded corners to the border and control the degree of curve. |
### Selected element options
The following options allow you to control the appearance of the element you've selected. To access an element so that you can edit it, expand the **Layer** section and select the desired element.
| Option | Description |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [Element type](#element-type) | Change the selected element type. |
| [Element](#element) | Control the appearance of text on the element. This section is named based on the element type. |
| [Layout](#layout) | Control the placement of elements on the canvas. |
| [Background (element)](#background-element) | Set the background of the element. |
| [Border (element)](#border-element) | Set the border of the element. |
| [Data links and actions](#data-links-and-actions) | Configure data links and actions for elements. |
#### Element type
You can change element type by making a new selection in the drop-down list:
![Cursor on the element type selection drop-down](/media/docs/grafana/panels-visualizations/screenshot-element-type-select-v11.3.png)
#### Element
This section is named based on the element type. Control the appearance of text on the element with the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| -------------- | --------------------------------------------------------- |
| Style | Buttons only. Select an option in the **Variant** drop-down list to indicate what kind of action the button initiates. Choose from **primary**, **secondary**, **success**, and **destructive**. |
| Text | Select a **Source**. Choose from **Fixed** or **Field**. If you selected **Fixed**, enter text in the **Value** field. If you selected **Field**, choose the field. |
| Text color | Choose a text color. |
| Align text | Set the horizontal alignment of text within the element. Choose from **Left**, **Center**, and **Right**. |
| Vertical align | Set the vertical alignment of the text within the element. Choose from **Top**, **Middle**, and **Bottom**. |
| Text size | Set the text size. Leave the field empty to allow Grafana to automatically set the text size. |
| API | Buttons only. Configure API options. For more information, refer to [Button API options](#button-api-options). |
<!--prettier-ignore-end -->
<!-- prettier-ignore-start -->
Icons don't have text, so they have different options:
| Option | Description |
| -------------- | --------------------------------------------------------- |
| SVG Path | Choose whether the icon SVG file source is **Fixed** or **Field**. If you selected **Fixed**, choose a provided option or [add a custom icon](#add-a-custom-icon). If you selected **Field**, choose a field. |
| Fill color | Choose a fill color for the icon. |
<!--prettier-ignore-end -->
#### Layout
Control the placement of elements on the canvas with the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| --------------- | --------------- |
| Quick placement | Select an alignment option to automatically place the element. Choose from:<ul><li>Align left</li><li>Align horizontal centers</li><li>Align right</li><li>Align top</li><li>Align vertical centers</li><li>Align bottom</li></ul> |
| Constraints | Set element constraints. Choose from: **Left**, **Right**, **Left & Right**, **Center**, and **Scale**.<br></br>Use the **Scale** option to ensure that elements are automatically resized when the panel size changes. |
| Position | Use these settings to manually set the position of an element. Set any or all of the following options: **top**, **left**, **width**, **height**, and **rotation**. |
<!-- prettier-ignore-end -->
#### Background (element)
Use the following options to set the background of the element:
- **Color** - Set the background color.
- **Image** - Use one of the provided background images or [add your own custom image](#add-custom-images-to-elements).
This option doesn't apply to the button element.
#### Border (element)
Use the following options to set the border of the element:
- **Width** - Set the border width in pixels.
- **Color** - Set the border color. This option is only displayed when the border width is greater than zero.
- **Radius** - Add rounded corners to the element border and control the degree of curve.
#### Data links and actions
Canvases support [data links](ref:data-links) and actions for all elements.
If you add multiple data links or actions to an element, you can control the order in which they appear in the element tooltip.
To do this, click and drag the link or action to the desired position.
The following tasks describe how to configure data links and actions.
{{< tabs >}}
{{< tab-content name="Add data links" >}}
To add a data link, follow these steps:
1. Enable inline editing.
1. Click the element to which you want to add the data link.
1. In either the inline editor or panel editor, expand the **Selected element** editor.
1. Scroll down to the **Data links and actions** section and expand it.
1. Click **+ Add link**.
1. In the dialog box that opens, enter a **Title**.
This is a human-readable label for the link displayed in the UI. This is a required field.
1. Enter the **URL** or variable to which you want to link.
To add a data link variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. This is a required field.
1. If you want the link to open in a new tab, toggle the **Open in a new tab** switch.
1. If you want the data link to open with a single click on the element, toggle the **One click** switch.
Only one data link or action can have **One click** enabled at a time.
1. Click **Save** to save changes and close the dialog box.
1. Disable inline editing.
{{< /tab-content >}}
{{< tab-content name="Add actions" >}}
To add an action, by follow these steps:
1. Enable inline editing.
1. Click the element to which you want to add the data link.
1. In either the inline editor or panel editor, expand the **Selected element** editor.
1. Scroll down to the **Data links and actions** section and expand it.
1. Click **+ Add action**.
In the dialog box that opens, set the action options:
| Option | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title | A human-readable label for the action that's displayed in the UI. |
| Confirmation message | A descriptive prompt to confirm or cancel the action. |
| One click | If you want the action to be triggered by a single click on the element, toggle the switch.</p><p>Only one data link or action can have **One click** enabled at a time. |
| Method | Select from **POST**, **PUT**, or **GET**. |
| URL | The request URL or variable to which you want to link.</p><p>To add a variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. |
| Variables | **Key** and **Name** pairs with a type selection. Click the **+** icon to add as many variables as you need. To add a variable to the request, prefix the key with `$`. You can set the values for the variables when performing an action. |
| Query parameters | **Key** and **Value** pairs. Click the **+** icon to add as many key/value pairs as you need. |
| Headers | Comprised of **Key** and **Value** pairs and a **Content-Type**.</p><p>Click the **+** icon to add as many key/value pairs as you need. |
| Content-Type | Select from the following: **application/json**, **text/plain**, **application/XML**, and **application/x-www-form-urlencoded**. |
| Body | The body of the request. |
1. Click **Save** to save changes and close the dialog box.
1. Disable inline editing.
{{< /tab-content >}}
{{< /tabs >}}
### Selected connection options
You can style the selected connection using the following options:
- **Color** - Set the connection color.
- **Size** - Control the size of the connection by entering a number in the **Value** field.
- **Radius** - Add curve to the connection by entering a value to represent the degree.
- **Direction** - Control the appearance of the arrow head. Choose your source from **Fixed** or **Field**. The default value is **Forward** regardless of the source type.
If the direction source is **Fixed**, choose from:
- **Forward** - The arrow head points in the direction in which the connection was drawn.
- **Reverse** - The arrow head points in the opposite direction of which the connection was drawn.
- **Both** - Adds arrow heads to both ends of the connection.
- **None** - Removes the arrow head.
If the direction source is **Field**, select a field that contains numeric values:
- **Positive values** - Display forward arrows.
- **Negative values** - Display reverse arrows.
- **Zero** - Display no arrow heads.
- **Line style** - Choose from the following line styles: **Solid**, **Dashed**, and **Dotted**.
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/dashboard-list/index.md
+102
View File
@@ -0,0 +1,102 @@
---
aliases:
- ../../../features/panels/dashlist/ # /docs/grafana/next/features/panels/dashlist/
- ../../../panels/visualizations/dashboard-list-panel/ # /docs/grafana/next/panels/visualizations/dashboard-list-panel/
- ../../../reference/dashlist/ # /docs/grafana/next/reference/dashlist/
- ../../dashboard-list-panel/ # /docs/grafana/next/visualizations/dashboard-list-panel/
- ../../../panels-visualizations/visualizations/dashboard-list/ # /docs/grafana/next/panels-visualizations/visualizations/dashboard-list/
keywords:
- grafana
- dashboard list
- documentation
- panel
- dashlist
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's dashboard list visualization
title: Dashboard list
weight: 100
refs:
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/
dashboard:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/create-dashboard/
---
# Dashboard list
Dashboard lists allow you to display dynamic links to other dashboards. You can configure the list to use starred dashboards, recently viewed dashboards, a search query, and dashboard tags.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-dashboard-list-v11.6.png" max-width="750px" alt="A dashboard list visualization" >}}
On each dashboard load, this panel queries the dashboard list, always providing the most up-to-date results.
You can use a dashboard list visualization to display a list of important dashboards that you want to track.
## Configure a dashboard list visualization
Once you’ve created a [dashboard](ref:dashboard), the following video shows you how to configure a dashboard list visualization:
{{< youtube id="MserjWGWsh8" >}}
{{< docs/play title="Dashboard List Visualization" url="https://play.grafana.org/d/fdlojrg7daebka/" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Dashboard list options
Use the following options to refine your dashboard list visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Include current time range | Propagate the time range of the current dashboard to the dashboard list links. When you click a link, the linked dashboard opens with the indicated time range already set. |
| Include current template variable values | Include template variables that are being used as query parameters in the dashboard list link. When you click the link, any matching templates in the linked dashboard are set to the values from the link. Learn more in [Dashboard URL variables](ref:dashboard-url-variables). |
| Starred | Display starred dashboards in alphabetical order. |
| Recently viewed | Display recently viewed dashboards in alphabetical order. |
| Search | Display dashboards returned by search. You must enter at least one value in the search fields, **Query** or **Tags**. Variable interpolation is supported for both fields. For example, `$my_var` or `${my_var}`. |
| Show headings | Headings for enabled sections are displayed. Sections are:<ul><li>**Starred**</li><li>**Recently viewed**</li><li>**Search**</li> |
| Show folder names | Display the name of the folder where the dashboard is located. |
| Max items | Set the maximum number of items to list per section. If you enter "10" and enable **Starred** and **Recently viewed** dashboards, the panel displays up to 20 total dashboards, 10 in each section. |
| [Query](#query) | Search by dashboard name. This option is only applied when the **Search** switch is toggled on. |
| [Folder](#folder) | Only dashboards from the selected folder are displayed in the dashboard list. This option is only applied when the **Search** switch is toggled on. |
| [Tags](#tags) | Search by tags. This option is only applied when the **Search** switch is toggled on. |
<!-- prettier-ignore-end -->
#### Query
Use this field to search by dashboard name. Query terms are case-insensitive and partial values are accepted.
For example, if you have dashboards called "Indoor Temps" and "Outdoor temp", entering the word "temp" returns both results.
This option is only applied when the **Search** switch is toggled on.
#### Folder
Only dashboards from the selected folder are included in search results and displayed in the dashboard list.
To include all dashboards in search results, select the top-level **Dashboards** folder.
This option is only applied when the **Search** switch is toggled on.
#### Tags
Enter tags by which you want to search. Note that tags don't appear as you type, and they're case sensitive.
Tag search uses an `OR` condition, so if a dashboard has one of the defined tags, it's included in the list.
When multiple tags and strings appear, the dashboard list displays those matching _all_ conditions.
This option is only applied when the **Search** switch is toggled on.
docs/sources/visualizations/panels-visualizations/visualizations/datagrid/index.md
+135
View File
@@ -0,0 +1,135 @@
---
aliases:
- ../../../features/panels/datagrid_panel/ # /docs/grafana/next/features/panels/datagrid_panel/
- ../../../reference/datagrid/ # /docs/grafana/next/reference/datagrid/
- ../../datagrid/ # /docs/grafana/next/visualizations/datagrid/
- ../../../panels-visualizations/visualizations/datagrid/ # /docs/grafana/next/panels-visualizations/visualizations/datagrid/
description: Configure options for Grafana's datagrid visualization
keywords:
- grafana
- dashboard
- panels
- datagrid
- datagrid panel
- datagrid options
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Datagrid
title: Datagrid
weight: 100
refs:
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
---
# Datagrid
{{< docs/experimental product="The datagrid visualization" featureFlag="`enableDatagridEditing`" >}}
Datagrids offer you the ability to create, edit, and fine-tune data within Grafana. As such, this panel can act as a data source for other panels
inside a dashboard.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-datagrid-visualization-v12.0.png" max-width="750px" alt="The datagrid visualization" >}}
Through it, you can manipulate data queried from any data source, you can start from a blank slate, or you can pull data from a dragged and dropped file.
You can then use the panel as a simple tabular visualization, or you can modify the data—and even remove it altogether—to create a blank slate.
Editing the dataset changes the data source to use the inbuilt `-- Grafana --` data source, thus replacing the old data source settings and related queries, while also copying the current dataset into the dashboard model.
You can then use the panel as a data source for other panels, by using the inbuilt `-- Dashboard --` data source to pull the datagrid data.
This allows for an interactive dashboard experience, where you can modify the data and see the changes reflected in other panels.
Learn more about the inbuilt `-- Grafana --` and `-- Dashboard --` data sources in the [special data sources](ref:special-data-sources) documentation.
## Context menu
To provide a more streamlined experience, the datagrid has a context menu that can be accessed by right-clicking on a cell, column header, or row selector. Depending on the state of your datagrid, the context menu offers different options including:
- Delete or clear rows and columns.
- Remove all existing data (rendering your datagrid blank).
- Trigger search functionality, which allows you to find keywords within the dataset.
Deleting a row or column will remove the data from the datagrid, while clearing a row or column will only remove the data from the cells, leaving the row or column intact.
{{< figure src="/media/docs/datagrid/screenshot-grafana-datagrid-context-menu-2.png" alt="Datagrid context menu" max-width="400px" >}}
### Header menu
You can also access a header menu by clicking the dropdown icon next to the header title. From here, you can not only delete or clear a column, but also rename it, freeze it, or convert the field type of the column.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-datagrid-header-menu-v12.0.png" alt="Datagrid header menu" max-width="400px" >}}
## Use datagrids
Datagrids offer various ways of interacting with your data. You can add, edit, move, clear, and remove rows and columns; use the inbuilt search functionality to find specific data; and convert field types or freeze horizontal scroll on a specific column.
### Add data
You can add data to a datagrid by creating a new column or row.
To create a new column, follow these steps:
1. In an existing panel, click the **+** button in the table header after the last column.
1. When prompted, add a name for the new column.
1. Click anywhere outside the field or press the Enter key to save the column.
Now you can add data in each cell.
To add a new row, click a **+** button after the last row. The button is present in each cell after the last row, and clicking it triggers the creation of a new row while also activating the cell that you clicked.
### Edit data
To edit data, follow these steps:
1. Double-click on the cell that needs to be modified. This will activate the cell and allow you to edit the data.
1. After editing the data, click anywhere outside the cell or press the Enter key to finalize the edit.
To easily clear a cell of data, you can click on a cell to focus it and then press the Delete key.
### Move data
You can move columns and rows as needed.
To move a column, follow these steps:
1. Click and hold the header of the column that needs to be moved.
1. Drag the column to the desired location.
1. Release the mouse button to finalize the move.
To move a row, click and hold on the row selector from the number column situated on the far left side of the grid, and drag it to the desired location. Releasing the mouse button finalizes the move.
### Select multiple cells
You can select multiple cells by clicking on a single cell and dragging the mouse across others. This selection can be used to copy the data from the selected cells or to delete them using the Delete key.
### Delete/clear multiple rows or columns
To delete or clear multiple rows, follow these steps:
1. Hover over the number column (to the left of the first column in the grid) to display row checkbox.
1. Select the checkboxes for the rows you want to work with.
To select multiple consecutive rows, press and hold the Shift key while clicking on the first and last row. To select non-consecutive rows, press and hold the Ctrl (or Cmd) key while clicking the desired rows.
1. Right-click to access the context menu.
1. Select **Delete rows** or **Clear rows**.
The same rules apply to columns by clicking the column headers.
To delete all rows, use the select all checkbox at the top left corner of the datagrid. This selects all rows and allows you to delete them using the context menu.
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Datagrid options
If there are multiple series, you can choose the dataset the datagrid displays using the **Select series** option.
docs/sources/visualizations/panels-visualizations/visualizations/flame-graph/index.md
+202
View File
@@ -0,0 +1,202 @@
---
aliases:
- ../../flame-graph/ # /docs/grafana/next/visualizations/flame-graph/
- ../../../panels-visualizations/visualizations/flame-graph/ # /docs/grafana/next/panels-visualizations/visualizations/flame-graph/
keywords:
- grafana
- dashboard
- documentation
- panels
- flame graph
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's flame graph visualization
title: Flame graph
weight: 100
refs:
units:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/#unit
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/#unit
configure-field-overrides:
- 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/
---
# Flame graph
Flame graphs let you visualize [profiling](https://grafana.com/docs/pyroscope/latest/introduction/what-is-profiling/) data. Using this visualization, a [profile](https://grafana.com/docs/pyroscope/latest/view-and-analyze-profile-data/profiling-types/) can be represented as a [flame graph](#flame-graph-mode), [top table](#top-table-mode), or both.
For example, if you want to understand which parts of a program consume the most resources, such as CPU time, memory, or I/O operations, you can use a flame graph to visualize and analyze where potential performance issues are:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-dark-v12.0.png" max-width="750px" alt="A flame graph visualization for a system profile with both flame graph and top table mode." >}}
You can use a flame graph visualization if you need to:
- Identify any performance hotspots to find where code optimizations may be needed.
- Diagnose the root cause of any performance degradation.
- Analyze the behavior of complex systems, including distributed systems or microservices architectures.
To learn more about how Grafana Pyroscope visualizes flame graphs, refer to [Flame graphs: Visualizing performance data](https://grafana.com/docs/pyroscope/latest/view-and-analyze-profile-data/flamegraphs/).
## Configure a flame graph visualization
Once you’ve created a [dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/), the following video shows you how to configure a flame graph visualization:
{{< youtube id="VEvK0JkPlOY" >}}
{{< docs/play title="Flame Graphs" url="https://play.grafana.org/d/cdl34qv4zzg8wa/" >}}
## Supported data formats
To render a flame graph, you must format the data frame data using a _nested set model_.
A nested set model ensures each item of a flame graph is encoded by its nesting level as an integer value, its metadata, and by its order in the data frame. This means that the order of items is significant and needs to be correct. The ordering is a depth-first traversal of the items in the flame graph which recreates the graph without needing variable-length values in the data frame like in a children's array.
Required fields:
| Field name | Type | Description |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| level | number | The nesting level of the item. In other words how many items are between this item and the top item of the flame graph. |
| value | number | The absolute or cumulative value of the item. This translates to the width of the item in the graph. |
| label | string | Label to be shown for the particular item. |
| self | number | Self value, which is usually the cumulative value of the item minus the sum of cumulative values of its immediate children. |
### Example
The following table is an example of the type of data you need for a flame graph visualization and how it should be formatted:
| level | value | self | label |
| ----- | -------- | ------ | ----------------------------------------- |
| 0 | 16.5 Bil | 16.5 K | total |
| 1 | 4.10 Bil | 4.10 k | test/pkg/agent.(\*Target).start.func1 |
| 2 | 4.10 Bil | 4.10 K | test/pkg/agent.(\*Target).start.func1 |
| 3 | 3.67 Bil | 3.67 K | test/pkg/distributor.(\*Distributor).Push |
| 4 | 1.13 Bil | 1.13 K | compress/gzip.(\*Writer).Write |
| 5 | 1.06 Bil | 1.06 K | compress/flat.(\*compressor).write |
## Flame graph mode
A flame graph takes advantage of the hierarchical nature of profiling data. It condenses data into a format that allows you to easily see which code paths are consuming the most system resources, such as CPU time, allocated objects, or space when measuring memory. Each block in the flame graph represents a function call in a stack and its width represents its value.
Grayed-out sections are a set of functions that represent a relatively small value and they are collapsed together into one section for performance reasons.
{{< figure src="/static/img/docs/flame-graph-panel/flame-graph-mode-dark.png" max-width="700px" alt="A flame graph visualization for a system profile with flame graph mode." >}}
You can hover over a specific function to view a tooltip that shows you additional data about that function, like the function's value, percentage of total value, and the number of samples with that function.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-tooltip-v11.6.png" max-width="700px" alt="A flame graph visualization with a hover tooltip." >}}
### Menu actions
You can click a function to show a drop-down menu with additional actions:
- [Focus block](#focus-block)
- [Copy function name](#copy-function-name)
- [Sandwich view](#sandwich-view)
- [Grouping](#grouping)
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-menu-v12.0.png" max-width="700px" alt="A flame graph visualization with drop-down actions." >}}
#### Focus block
When you click **Focus block**, the block, or function, is set to 100% of the flame graph's width and all its child functions are shown with their widths updated relative to the width of the parent function. This makes it easier to drill down into smaller parts of the flame graph.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-focus-v11.6.png" max-width="700px" alt="A flame graph visualization with focus block action selected." >}}
#### Copy function name
When you click **Copy function name**, the full name of the function that the block represents is copied.
#### Sandwich view
The sandwich view allows you to show the context of the clicked function. It shows all the function's callers on the top and all the callees at the bottom. This shows the aggregated context of the function so if the function exists in multiple places in the flame graph, all the contexts are shown and aggregated in the sandwich view.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-sandwich-v11.6.png" max-width="700px" alt="A flame graph visualization with sandwich view selected.">}}
#### Grouping
Under the **Grouping** section of the menu, the following options let you expand and collapse groups of functions:
- **Expand group** - Expands the grouped function you've clicked. Displayed if you click a function that's been automatically grouped in the flame graph.
- **Expand all groups** - Expands all grouped functions in the flame graph. Always displayed when you click the graph.
- **Collapse group** - Collapses the expanded function you've clicked. Displayed if you click a function in the flame graph that's been manually expanded.
- **Collapse all groups** - Collapses all expanded functions in the flame graph. Displayed if there are any expanded functions when you click the graph.
### Status bar
The status bar shows metadata about the flame graph and currently applied modifications, like what part of the graph is in focus or what function is shown in sandwich view. Click the **X** in the status bar pill to remove that modification.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-status-v11.6.png" max-width="730px" alt="A flame graph visualization's status bar.">}}
## Top table mode
The top table shows the functions from the profile in table format. The table has three columns: symbols, self, and total. The table is sorted by self time by default, but can be reordered by total time or symbol name by clicking the column headers. Each row represents aggregated values for the given function if the function appears in multiple places in the profile.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-toptable-v12.0.png" max-width="700px" alt="Table view">}}
There are also action buttons on the left-most side of each row. The first button searches for the function name while second button shows the sandwich view of the function.
## Toolbar
The following table lists the features of the toolbar:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| [Search](#search) | Use the search field to find functions with a particular name. All the functions in the flame graph that match the search will remain colored while the rest of the functions appear in gray. |
| Reset | Reset the flame graph back to its original state from a focus block or sandwich view. The reset icon is only displayed when the flame graph is in one of those two states. |
| [Color schema picker](#color-schema-picker) | Switch between coloring functions by their value or by their package name to visually tie functions from the same package together. |
| Grouping | Expand or collapse all groups to show all instances of a function or show the function grouped. |
| Text align | Align text either to the left or to the right to show more important parts of the function name when it does not fit into the block. |
| Visualization picker | Choose to show only the flame graph, only table, or both at the same time. |
<!-- prettier-ignore-end -->
### Search
You can use the search field to find functions with a particular name. All the functions in the flame graph that match the search will remain colored while the rest of the functions are grayed-out.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-search-v12.0.png" max-width="700px" alt="Searching for a function name in a flame graph visualization.">}}
### Color schema picker
You can switch between coloring functions by their value or by their package name to visually tie functions from the same package together.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-flamegraph-color-v11.6.png" max-width="700px" alt="Different color scheme" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Standard options
**Standard options** in the panel editor pane let you change how field data is displayed in your visualizations.
When you set a standard option, the change is applied to all fields or series.
For more granular control over the display of fields, refer to [Configure field overrides](ref:configure-field-overrides).
You can customize the following standard options:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Unit | This option lets you choose which unit a field should use. For more information on unit options as well as creating custom units, refer to the [unit configuration documentation](ref:units). |
| Decimals | Specify the number of decimals Grafana includes in the rendered value. |
<!-- prettier-ignore-end -->
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/gauge/index.md
+189
View File
@@ -0,0 +1,189 @@
---
aliases:
- ../../../features/panels/gauge/ # /docs/grafana/next/features/panels/gauge/
- ../../../panels/visualizations/gauge-panel/ # /docs/grafana/next/panels/visualizations/gauge-panel/
- ../../gauge-panel/ # /docs/grafana/next/visualizations/gauge-panel/
- ../../../panels-visualizations/visualizations/gauge/ # /docs/grafana/next/panels-visualizations/visualizations/gauge/
description: Configure options for Grafana's gauge visualization
keywords:
- grafana
- gauge
- gauge panel
labels:
products:
- cloud
- enterprise
- oss
title: Gauge
weight: 100
refs:
calculation-types:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/calculation-types/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/calculation-types/
---
# Gauge
Gauges are single-value visualizations that allow you to quickly visualize where a value falls within a defined or calculated min and max range. With repeat options, you can display multiple gauges, each corresponding to a different series, column, or row.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-gauge-visualization-v11.4.png" alt="A gauge visualization">}}
You can use gauges if you need to track:
- Service level objectives (SLOs)
- How full a piece of equipment is
- How fast a vehicle is moving within a set of limits
- Network latency
- Equipment state with set point and alarm thresholds
- CPU consumption (0-100%)
- RAM availability
## Configure a gauge visualization
The following video provides beginner steps for creating gauge panels. You'll learn the data requirements and caveats, special customizations, and much more:
{{< youtube id="QwXj3y_YpnE" >}}
{{< docs/play title="Grafana Gauge Visualization" url="https://play.grafana.org/d/KIhkVD6Gk/" >}}
## Supported data formats
To create a gauge visualization you need a dataset containing at least one numeric field. These values are identified by the field name. Additional text fields aren’t required but can be used for identification and labeling.
### Example - One value
| GaugeName | GaugeValue |
| --------- | ---------- |
| MyGauge | 5 |
![Gauge with single numeric value](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example1.png)
This dataset generates a visualization with one empty gauge showing the numeric value. This is because the gauge visualization automatically defines the upper and lower range from the minimum and maximum values in the dataset. This dataset has only one value, so it’s set as both minimum and maximum.
If you only have one value, but you want to define a different minimum and maximum, you can set them manually in the [Standard options](#standard-options) settings to generate a more typical looking gauge.
![Gauge with single numeric value and hardcoded max and min](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example2.png)
### Example - One row, multiple values
The gauge visualization can support multiple fields in a dataset. <!-- In this case, multiple gauges are displayed. -->
| Identifier | value1 | value2 | value3 |
| ---------- | ------ | ------ | ------ |
| Gauges | 5 | 3 | 10 |
![Gauge visualization with multiple numeric values in a single row](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example3.png)
When there are multiple values in the dataset, the visualization displays multiple gauges and automatically defines the minimum and maximum. In this case, those are 3 and 10. Because the minimum and maximum values are defined, each gauge is shaded in to show that value in relation to the minimum and maximum.
### Example - Multiple rows and values
The gauge visualization can display datasets with multiple rows of data or even multiple datasets.
| Identifier | value1 | value2 | value3 |
| ---------- | ------ | ------ | ------ |
| Gauges | 5 | 3 | 10 |
| Indicators | 6 | 9 | 15 |
| Defaults | 1 | 4 | 8 |
![Gauge visualization with multiple rows and columns of numeric values showing the last row](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example6.png)
By default, the visualization is configured to [calculate](#value-options) a single value per column or series and to display only the last row of data. However, it derives the minimum and maximum from the full dataset, even if those values aren’t visible.
In this example, that means only the last row of data is displayed in the gauges and the minimum and maximum values are 1 and 10. The value 1 is displayed because it’s in the last row, while 10 is not.
If you want to show one gauge per table cell, you can change the **Show** setting from **Calculate** to **All values**, and each gauge is labeled by concatenating the text column with each value's column name.
![Gauge visualization with multiple rows and columns of numeric values showing all the values](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example7.png)
### Example - Defined min and max
You can also define minimum and maximum values as part of the dataset.
| Identifier | value | max | min |
| ---------- | ----- | --- | --- |
| Gauges | 5 | 10 | 2 |
![Gauge visualization with numeric values defining max and minimum](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example4.png)
If you don’t want to display gauges for the `min` and `max` values, you can configure only one field to be displayed as described in the [value options](#value-options) section.
![Gauge visualization with numeric values defining max and minimum but hidden](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example5.png)
Even when minimum and maximum values aren’t displayed, the visualization still pulls the range from them.
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value options
Use the following options to refine how your visualization displays the value:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Show | Set how Grafana displays your data. Choose from:<ul><li>**Calculate** - Show a calculated value based on all rows.</li><li>**All values** - Show a separate value for every row. If you select this option, then you can also limit the number of rows to display.</li></ul> |
| Calculation | If you chose **Calculate** as your **Show** option, select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types](ref:calculation-types). |
| Limit | If you chose **All values** as your **Show** option, enter the maximum number of rows to display. The default is 5,000. |
| Fields | Select the fields display in the panel. |
<!-- prettier-ignore-end -->
### Gauge options
Adjust how the gauge is displayed.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Orientation | Choose a stacking direction:<ul><li>**Auto** - Gauges display in rows and columns.</li><li>**Horizontal** - Gauges display top to bottom.</li><li>**Vertical** - Gauges display left to right.</li></ul> |
| Show threshold labels | Controls if threshold values are shown. |
| [Show threshold markers](#show-threshold-markers) | Controls if a threshold band is shown outside the inner gauge value band. |
| Gauge size | Choose a gauge size mode:<ul><li>**Auto** - Grafana determines the best gauge size.</li><li>**Manual** - Manually configure the gauge size.</li></ul>This option only applies when **Orientation** is set to **Horizontal** or **Vertical**. |
| Min width | Set the minimum width of vertically-oriented gauges. If you set a minimum width, the x-axis scrollbar is automatically displayed when there's a large amount of data. This option only applies when **Gauge size** is set to **Manual**. |
| Min height | Set the minimum height of horizontally-oriented gauges. If you set a minimum height, the y-axis scrollbar is automatically displayed when there's a large amount of data. This option only applies when **Gauge size** is set to **Manual**. |
| Neutral | Set the starting value from which every gauge will be filled. |
<!-- prettier-ignore-end -->
#### Show threshold markers
Controls if a threshold band is shown around the inner gauge value band.
![Gauge viz with multiple rows and columns of numeric values showing all the values and thresholds defined for 0-6-11](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.2-gauge-example8.png)
### Text size
Adjust the sizes of the gauge text.
- **Title** - Enter a numeric value for the gauge title size.
- **Value** - Enter a numeric value for the gauge value size.
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/geomap/index.md
+751
View File
@@ -0,0 +1,751 @@
---
aliases:
- ../../../features/panels/geomap/ # /docs/grafana/next/features/panels/geomap/
- ../../../features/panels/geomap/arcgis/ # /docs/grafana/next/features/panels/geomap/arcgis/
- ../../../features/panels/geomap/carto/ # /docs/grafana/next/features/panels/geomap/carto/
- ../../../features/panels/geomap/controls/ # /docs/grafana/next/features/panels/geomap/controls/
- ../../../features/panels/geomap/daynight/ # /docs/grafana/next/features/panels/geomap/daynight/
- ../../../features/panels/geomap/geojson/ # /docs/grafana/next/features/panels/geomap/geojson/
- ../../../features/panels/geomap/heatmap/ # /docs/grafana/next/features/panels/geomap/heatmap/
- ../../../features/panels/geomap/markers/ # /docs/grafana/next/features/panels/geomap/markers/
- ../../../features/panels/geomap/osm/ # /docs/grafana/next/features/panels/geomap/osm/
- ../../../features/panels/geomap/zyx/ # /docs/grafana/next/features/panels/geomap/zyx/
- ../../../panels/visualizations/geomap/ # /docs/grafana/next/panels/visualizations/geomap/
- ../../../panels/visualizations/geomap/arcgis/ # /docs/grafana/next/panels/visualizations/geomap/arcgis/
- ../../../panels/visualizations/geomap/carto/ # /docs/grafana/next/panels/visualizations/geomap/carto/
- ../../../panels/visualizations/geomap/controls/ # /docs/grafana/next/panels/visualizations/geomap/controls/
- ../../../panels/visualizations/geomap/daynight/ # /docs/grafana/next/panels/visualizations/geomap/daynight/
- ../../../panels/visualizations/geomap/geojson/ # /docs/grafana/next/panels/visualizations/geomap/geojson/
- ../../../panels/visualizations/geomap/heatmap/ # /docs/grafana/next/panels/visualizations/geomap/heatmap/
- ../../../panels/visualizations/geomap/markers/ # /docs/grafana/next/panels/visualizations/geomap/markers/
- ../../../panels/visualizations/geomap/osm/ # /docs/grafana/next/panels/visualizations/geomap/osm/
- ../../../panels/visualizations/geomap/zyx/ # /docs/grafana/next/panels/visualizations/geomap/zyx/
- ../../../visualizations/geomap/ # /docs/grafana/visualizations/geomap/
- ../../../panels-visualizations/visualizations/geomap/ # /docs/grafana/next/panels-visualizations/visualizations/geomap/
description: Configure options for Grafana's geomap visualization
keywords:
- grafana
- Geomap
- panel
- documentation
labels:
products:
- cloud
- enterprise
- oss
title: Geomap
weight: 100
refs:
data-format:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/node-graph/#data-api
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/node-graph/#data-api
provisioning-docs-page:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/provisioning/
---
# Geomap
Geomaps allow you to view and customize the world map using geospatial data. It's the ideal visualization if you have data that includes location information and you want to see it displayed in a map.
You can configure and overlay [map layers](#layer-type), like heatmaps and networks, and blend included basemaps or your own custom maps. This helps you to easily focus on the important location-based characteristics of the data.
{{< figure src="/static/img/docs/geomap-panel/geomap-example-8-1-0.png" max-width="750px" alt="Geomap visualization" >}}
When a geomap is in focus, in addition to typical mouse controls, you can pan around using the arrow keys or zoom in and out using the plus (`+`) and minus (`-`) keys or icons.
Geomaps are also useful when you have location data that’s changing in real time and you want to visualize where an element is moving, using auto-refresh.
You can use a geomap visualization if you need to:
- Track your fleet of vehicles and associated metrics
- Show the locations and statuses of data centers or other connected assets in a network
- Display geographic trends in a heatmap
- Visualize the relationship of your locations' HVAC consumption or solar production with the sun's location
{{< admonition type="note" >}}
We'd love your feedback on the geomap visualization. Please check out the [open Github issues](https://github.com/grafana/grafana/issues?page=1&q=is%3Aopen+is%3Aissue+label%3Aarea%2Fpanel%2Fgeomap) and [submit a new feature request](https://github.com/grafana/grafana/issues/new?assignees=&labels=type%2Ffeature-request,area%2Fpanel%2Fgeomap&title=Geomap:&projects=grafana-dataviz&template=1-feature_requests.md) as needed.
{{< /admonition >}}
## Configure a geomap visualization
The following video provides beginner steps for creating geomap visualizations. You'll learn the data requirements and caveats, special customizations, preconfigured displays and much more:
{{< youtube id="HwM8AFQ7EUs" >}}
{{< docs/play title="Geomap Examples" url="https://play.grafana.org/d/panel-geomap/" >}}
## Supported data formats
To create a geomap visualization, you need datasets containing fields with location information.
The supported location formats are:
- Latitude and longitude
- Geohash
- Lookup codes: country, US states, or airports
To learn more, refer to [Location mode](#location-mode).
Geomaps also support additional fields with various data types to define things like labels, numbers, heat sizes, and colors.
### Example - Latitude and longitude
If you plan to use latitude and longitude coordinates, the dataset must include at least two fields (or columns): one called `latitude` (you can also use`lat`), and one called `longitude` (also `lon` or `lng`). When you use this naming convention, the visualization automatically detects the fields and displays the elements. The order of the fields doesn't matter as long as there is one latitude and one longitude.
| Name | latitude | longitude | value |
| --------------- | --------- | --------- | ----- |
| Disneyland | 33.8121 | -117.9190 | 4 |
| DisneyWorld | 28.3772 | -81.5707 | 10 |
| EuroDisney | 48.867374 | 2.784018 | 3 |
| Tokyo Disney | 35.6329 | 139.8804 | 70 |
| Shanghai Disney | 31.1414 | 121.6682 | 1 |
If your latitude and longitude fields are named differently, you can specify them, as indicated in the [Location mode](#location-mode) section.
### Example - Geohash
If your location data is in geohash format, the visualization requires at least one field (or column) containing location data.
If the field is named `geohash`, the visualization automatically detects the location and displays the elements. The order of the fields doesn't matter and the data set can have multiple other numeric, text, and time fields.
| Name | geohash | trips |
| --------- | ------------ | ----- |
| Cancun | d5f21 | 8 |
| Honolulu | 87z9ps | 0 |
| Palm Cove | rhzxudynb014 | 1 |
| Mykonos | swdj02ey9gyx | 3 |
If your field containing geohash location data is not named as above, you can configure the visualization to use geohash and specify which field to use, as explained in the [Location mode](#location-mode) section.
### Example - Lookup codes
The geomap visualization can identify locations based on country, airport, or US state codes.
For this configuration, the dataset must contain at least one field (or column) containing the location code.
If the field is named `lookup`, the visualization automatically detects it and displays points based on country codes.
| Year | lookup | gdp |
| ---- | ------ | --------- |
| 2016 | MEX | 104171935 |
| 2016 | DEU | 94393454 |
| 2016 | FRA | 83654250 |
| 2016 | BRA | 80921527 |
| 2016 | CAN | 79699762 |
The other location types&mdash; airport codes or US state codes&mdash;aren't automatically detected.
If you want to use other codes or give the field a custom name, you can follow the steps in the [Location mode](#location-mode) section.
## Configuration options
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Map view options
The map view controls the initial view of the map when the dashboard loads.
#### Initial View
The initial view configures how the geomap renders when the panel is first loaded.
- **View** - Sets the center for the map when the panel first loads. Refer to the table following this list for view selections.
- **Zoom** - Sets the initial zoom level.
- **Use current map settings** - Use the settings of the current map to set the center.
<!-- prettier-ignore-start -->
| View selection | Description |
|---|---|
| Fit to data | fits the map view based on the data extents of Map layers and updates when data changes.<ul><li>**Data** - option allows selection of extent based on data from "All layers", a single "Layer", or the "Last value" from a selected layer.</li><li>**Layer** - can be selected if fitting data from a single "Layer" or the "Last value" of a layer.</li><li>**Padding** - sets padding in relative percent beyond data extent (not available when looking at "Last value" only).</li><li>**Max zoom** - sets the maximum zoom level when fitting data.</li> |
| (0°, 0°) | |
| Coordinates | sets the map view based on: **Latitude** and **Longitude**. |
<!-- prettier-ignore-end -->
Default Views are also available including:
<!-- prettier-ignore-start -->
| | | | | |
| ------------- | ------------- | ------ | ------ | --------- |
| North America | South America | Europe | Africa | West Asia |
| South Asia | South-East Asia | East Asia | Australia | Oceania |
<!-- prettier-ignore-end -->
#### Share view
The **Share view** option allows you to link the movement and zoom actions of multiple map visualizations within the same dashboard. The map visualizations that have this option enabled act in tandem when one of them is moved or zoomed, leaving the other ones independent.
{{< admonition type="note" >}}
You might need to reload the dashboard for this feature to work.
{{< /admonition >}}
#### No map repeating
The **No map repeating** option prevents the base map tiles from repeating horizontally when you pan across the world. This constrains the view to a single instance of the world map and avoids visual confusion when displaying global datasets. Enabling this option requires the map to reinitialize.
### Map layers options
Geomaps support showing multiple layers. Each layer determines how you visualize geospatial data on top of the base map.
There are three options that you need to set for all maps:
- [Layer type](#layer-type)
- [Data](#data)
- [Location mode](#location-mode)
Other options are dependent on your map layer type and are described within the layer type section.
The layer controls allow you to create layers, change their name, reorder and delete layers.
- **Add layer** creates an additional, configurable data layer for the geomap. When you add a layer, you are prompted to select a layer type. You can change the layer type at any point during panel configuration. See the **Layer Types** section above for details on each layer type.
- **Edit layer name (pencil icon)** renames the layer.
- **Trash Bin** deletes the layer.
- **Reorder (six dots/grab handle)** allows you to change the layer order. Data on higher layers will appear above data on lower layers. The visualization will update the layer order as you drag and drop to help simplify choosing a layer order.
You can add multiple layers of data to a single geomap in order to create rich, detailed visualizations.
#### Layer type
There are seven map layer types to choose from in a geomap.
- [Markers](#markers-layer) renders a marker at each data point.
- [Heatmap](#heatmap-layer) visualizes a heatmap of the data.
- [GeoJSON](#geojson-layer) renders static data from a GeoJSON file.
- [Night / Day](#night--day-layer) renders a night / day region.
- [Route (Beta)](#route-layer-beta) render data points as a route.
- [Photos (Beta)](#photos-layer-beta) renders a photo at each data point.
- [Network (Beta)](#network-layer-beta) visualizes a network graph from the data.
- [Open Street Map](#open-street-map-layer) adds a map from a collaborative free geographic world database.
- [CARTO basemap](#carto-basemap-layer) adds a layer from CARTO Raster basemaps.
- [ArcGIS MapServer](#arcgis-mapserver-layer) adds a layer from an ESRI ArcGIS MapServer.
- [XYZ Tile layer](#xyz-tile-layer) adds a map from a generic tile layer.
{{< admonition type="note" >}}
Beta is equivalent to the [public preview](/docs/release-life-cycle/) release stage.
{{< /admonition >}}
There are also two experimental (or alpha) layer types.
- **Icon at last point (alpha)** renders an icon at the last data point.
- **Dynamic GeoJSON (alpha)** styles a GeoJSON file based on query results.
To enable experimental layers. Set `enable_alpha` to `true` in your configuration file:
```
[panels]
enable_alpha = true
```
To enable the experimental layers using Docker, run the following command:
```
docker run -p 3000:3000 -e "GF_PANELS_ENABLE_ALPHA=true" grafana/grafana:<VERSION>
```
#### Data
Geomaps need a source of geographical data gathered from a data source query which can return multiple datasets. By default Grafana picks the first dataset, but this drop-down allows you to pick other datasets if the query returns more than one.
#### Location mode
There are four options to map the data returned by the selected query:
- **Auto** automatically searches for location data. Use this option when your query is based on one of the following names for data fields.
- geohash: “geohash”
- latitude: “latitude”, “lat”
- longitude: “longitude”, “lng”, “lon”
- lookup: “lookup”
- **Coords** specifies that your query holds coordinate data. You will get prompted to select numeric data fields for latitude and longitude from your database query.
- **Geohash** specifies that your query holds geohash data. You will be prompted to select a string data field for the geohash from your database query.
- **Lookup** specifies that your query holds location name data that needs to be mapped to a value. You will be prompted to select the lookup field from your database query and a gazetteer. The gazetteer is the directory that is used to map your queried data to a geographical point.
#### Markers layer
The markers layer allows you to display data points as different marker shapes such as circles, squares, triangles, stars, and more.
![Markers Layer](/static/img/docs/geomap-panel/geomap-markers-8-1-0.png)
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Data | Configure the data settings for the layer. For more information, refer to [Data](#data). |
| Location | Configure the data settings for the layer. For more information, refer to [Location mode](#location-mode). |
| Size | Configures the size of the markers. The default is `Fixed size`, which makes all marker sizes the same regardless of the data; however, there is also an option to size the markers based on data corresponding to a selected field. `Min` and `Max` marker sizes have to be set such that the markers can scale within this range. |
| Symbol | Allows you to choose the symbol, icon, or graphic to aid in providing additional visual context to your data. Choose from assets that are included with Grafana such as simple symbols or the Unicon library. You can also specify a URL containing an image asset. The image must be a scalable vector graphic (SVG). |
| Symbol Vertical Align | Configures the vertical alignment of the symbol relative to the data point. Note that the symbol's rotation angle is applied first around the data point, then the vertical alignment is applied relative to the rotation of the symbol. |
| Symbol Horizontal Align | Configures the horizontal alignment of the symbol relative to the data point. Note that the symbol's rotation angle is applied first around the data point, then the horizontal alignment is applied relative to the rotation of the symbol. |
| Color | Configures the color of the markers. The default `Fixed color` sets all markers to a specific color. There is also an option to have conditional colors depending on the selected field data point values and the color scheme set in the `Standard options` section. |
| Fill opacity | Configures the transparency of each marker. |
| Rotation angle | Configures the rotation angle of each marker in degrees. The default is `Fixed value`, which makes all markers rotate to the same angle regardless of the data; however, there is also an option to set the rotation of the markers based on data corresponding to a selected field. |
| Text label | Configures a text label for each marker. |
| Show legend | Allows you to toggle the legend for the layer. |
| Display tooltip | Allows you to toggle tooltips for the layer. |
<!-- prettier-ignore-end -->
#### Heatmap layer
The heatmap layer clusters various data points to visualize locations with different densities.
To add a heatmap layer:
Click on the drop-down menu under Data Layer and choose `Heatmap`.
Similar to `Markers`, you are prompted with various options to determine which data points to visualize and how you want to visualize them.
![Heatmap Layer](/static/img/docs/geomap-panel/geomap-heatmap-8-1-0.png)
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Data | Configure the data settings for the layer. For more information, refer to [Data](#data). |
| Location | Configure the data settings for the layer. For more information, refer to [Location mode](#location-mode). |
| Weight values | Configures the size of the markers. The default is `Fixed size`, which makes all marker sizes the same regardless of the data; however, there is also an option to size the markers based on data corresponding to a selected field. `Min` and `Max` marker sizes have to be set such that the markers can scale within this range. |
| Radius | Configures the size of the heatmap clusters. |
| Blur | Configures the amount of blur on each cluster. |
| Opacity | Configures the opacity of each cluster. |
| Display tooltip | Allows you to toggle tooltips for the layer. |
<!-- prettier-ignore-end -->
#### GeoJSON layer
The GeoJSON layer allows you to select and load a static GeoJSON file from the filesystem.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| GeoJSON URL | Provides a choice of GeoJSON files that are included with Grafana. You can also enter a URL manually, which supports variables. |
| Default Style | Controls which styles to apply when no rules above match.<ul><li>**Color** - configures the color of the default style</li><li>**Opacity** - configures the default opacity</li></ul> |
| Style Rules | Apply styles based on feature properties <ul><li>**Rule** - allows you to select a _feature_, _condition_, and _value_ from the GeoJSON file in order to define a rule. The trash bin icon can be used to delete the current rule.</li><li>**Color** - configures the color of the style for the current rule</li><li>**Opacity** - configures the transparency level for the current rule</li> |
| Display tooltip | Allows you to toggle tooltips for the layer. |
<!-- prettier-ignore-end -->
Styles can be set within the "properties" object of the GeoJSON with support for the following geometries:
**Polygon, MultiPolygon**
- **"fill"** - The color of the interior of the polygon(s)
- **"fill-opacity"** - The opacity of the interior of the polygon(s)
- **"stroke-width"** - The width of the line component of the polygon(s)
**Point, MultiPoint**
- **"marker-color"** - The color of the point(s)
- **"marker-size"** - The size of the point(s)
**LineString, MultiLineString**
- **"stroke"** - The color of the line(s)
- **"stroke-width"** - The width of the line(s)
#### Night / Day layer
The Night / Day layer displays night and day regions based on the current time range.
{{< figure src="/static/img/docs/geomap-panel/geomap-day-night-9-1-0.png" max-width="600px" alt="Geomap panel Night / Day" >}}
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Data | Configures the data set for the layer. For more information, refer to [Data](#data). |
| Show | Toggles the time source from panel time range. |
| Night region color | Picks the color for the night region. |
| Display sun | Toggles the sun icon. |
| Opacity | Set the opacity from `0` (transparent) to `1` (opaque). |
| Display tooltip | Allows you to toggle tooltips for the layer. |
<!-- prettier-ignore-end -->
[Extensions for OpenLayers - DayNight](https://viglino.github.io/ol-ext/examples/layer/map.daynight.html)
#### Route layer (Beta)
{{< admonition type="caution" >}}
The Route layer is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{< /admonition >}}
The Route layer renders data points as a route.
{{< figure src="/media/docs/grafana/geomap-route-layer-basic-9-4-0.png" max-width="600px" alt="Geomap panel Route" >}}
The layer can also render a route with arrows.
{{< figure src="/media/docs/grafana/geomap-route-layer-arrow-size-9-4-0.png" max-width="600px" alt="Geomap panel Route arrows with size" >}}
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Data | configure the data settings for the layer. For more information, refer to [Data](#data). |
| Location | configure the data settings for the layer. For more information, refer to [Location mode](#location-mode). |
| Size | sets the route thickness. Fixed value by default. When field data is selected you can set the Min and Max range in which field data can scale. |
| Color | sets the route color. Set to `Fixed color` by default. You can also tie the color to field data. |
| Fill opacity | configures the opacity of the route. |
| Text label | configures a text label for each route. |
| Arrow | sets the arrow styling to display along route, in order of data. Choose from: **None**, **Forward**, and **Reverse** |
| Display tooltip | allows you to toggle tooltips for the layer. |
<!-- prettier-ignore-end -->
[Extensions for OpenLayers - Flow Line Style](http://viglino.github.io/ol-ext/examples/style/map.style.gpxline.html)
#### Photos layer (Beta)
{{< admonition type="caution" >}}
The Photos layer is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{< /admonition >}}
The Photos layer renders a photo at each data point.
{{< figure src="/static/img/docs/geomap-panel/geomap-photos-9-3-0.png" max-width="600px" alt="Geomap panel Photos" >}}
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Data | Configure the data settings for the layer. For more information, refer to [Data](#data). |
| Location | Configure the data settings for the layer. For more information, refer to [Location mode](#location-mode). |
| Image Source field | Allows you to select a string field containing image data in either of the following formats:<ul><li>**Image URLs**</li><li>**Base64 encoded** - Image binary ("data:image/png;base64,...")</li></ul> |
| Kind | Sets the frame style around the images. Choose from: **Square**, **Circle**, **Anchored**, and **Folio**. |
| Crop | Toggles whether the images are cropped to fit. |
| Shadow | Toggles a box shadow behind the images. |
| Border | Sets the border size around images. |
| Border color | Sets the border color around images. |
| Radius | Sets the overall size of images in pixels. |
| Display tooltip | Allows you to toggle tooltips for the layer. |
<!-- prettier-ignore-end -->
[Extensions for OpenLayers - Image Photo Style](http://viglino.github.io/ol-ext/examples/style/map.style.photo.html)
#### Network layer (Beta)
{{< admonition type="caution" >}}
The Network layer is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{< /admonition >}}
The Network layer renders a network graph. This layer supports the same [data format supported by the node graph visualization](ref:data-format) with the addition of [geospatial data](#location-mode) included in the nodes data. The geospatial data is used to locate and render the nodes on the map.
{{< figure src="/media/docs/grafana/screenshot-grafana-10-1-geomap-network-layer-v2.png" max-width="750px" alt="Geomap network layer" >}}
You can convert node graph data to a network layer:
{{< video-embed src="/media/docs/grafana/screen-recording-10-1-geomap-network-layer-from-node-graph.mp4" max-width="750px" alt="Node graph to Geomap network layer" >}}
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Data | Configure the data settings for the layer. For more information, refer to [Data](#data). |
| Location | Configure the data settings for the layer. For more information, refer to [Location mode](#location-mode). |
| Arrow | Sets the arrow direction to display for each edge, with forward meaning source to target. Choose from: **None**, **Forward**, **Reverse** and **Both**. |
| Show legend | Allows you to toggle the legend for the layer. **Note:** The legend currently only supports node data. |
| Display tooltip | Allows you to toggle tooltips for the layer. |
<!-- prettier-ignore-end -->
##### Node styles options
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Size | Configures the size of the nodes. The default is `Fixed size`, which makes all node sizes the same regardless of the data; however, there is also an option to size the nodes based on data corresponding to a selected field. `Min` and `Max` node sizes have to be set such that the nodes can scale within this range. |
| Symbol | Allows you to choose the symbol, icon, or graphic to aid in providing additional visual context to your data. Choose from assets that are included with Grafana such as simple symbols or the Unicon library. You can also specify a URL containing an image asset. The image must be a scalable vector graphic (SVG). |
| Color | Configures the color of the nodes. The default `Fixed color` sets all nodes to a specific color. There is also an option to have conditional colors depending on the selected field data point values and the color scheme set in the `Standard options` section. |
| Fill opacity | Configures the transparency of each node. |
| Rotation angle | Configures the rotation angle of each node in degrees. The default is `Fixed value`, which makes all nodes rotate to the same angle regardless of the data; however, there is also an option to set the rotation of the nodes based on data corresponding to a selected field. |
| Text label | Configures a text label for each node. |
<!-- prettier-ignore-end -->
##### Edge styles options
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Size | Configures the line width of the edges. The default is `Fixed size`, which makes all edge line widths the same regardless of the data; however, there is also an option to size the edges based on data corresponding to a selected field. `Min` and `Max` eges sizes have to be set such that the edges can scale within this range. |
| Color | Configures the color of the edges. The default `Fixed color` sets all edges to a specific color. There is also an option to have conditional colors depending on the selected field data point values and the color scheme set in the `Standard options` section. |
| Fill opacity | Configures the transparency of each edge. |
| Text label | Configures a text label for each edge. |
<!-- prettier-ignore-end -->
#### Open Street Map layer
A map from a collaborative free geographic world database.
{{< figure src="/static/img/docs/geomap-panel/geomap-osm-9-1-0.png" max-width="600px" alt="Geomap panel Open Street Map" >}}
- **Opacity** from 0 (transparent) to 1 (opaque)
- **Display tooltip** - allows you to toggle tooltips for the layer.
[About Open Street Map](https://www.openstreetmap.org/about)
#### CARTO basemap layer
A CARTO layer is from CARTO Raster basemaps.
- **Theme**
- Auto
- Light
{{< figure src="/static/img/docs/geomap-panel/geomap-carto-light-9-1-0.png" max-width="600px" alt="Geomap panel CARTO light example" >}}
- Dark
{{< figure src="/static/img/docs/geomap-panel/geomap-carto-dark-9-1-0.png" max-width="600px" alt="Geomap panel CARTO dark example" >}}
- **Show labels** shows the Country details on top of the map.
- **Opacity** from 0 (transparent) to 1 (opaque)
- **Display tooltip** - allows you to toggle tooltips for the layer.
[About CARTO](https://carto.com/about-us/)
#### ArcGIS MapServer layer
An ArcGIS layer is a layer from an ESRI ArcGIS MapServer.
- **Server Instance** to select the map type.
- World Street Map
{{< figure src="/static/img/docs/geomap-panel/geomap-arcgis-wsm-9-1-0.png" max-width="600px" alt="Geomap panel ArcGIS World Street Map" >}}
- World Imagery
{{< figure src="/static/img/docs/geomap-panel/geomap-arcgis-wi-9-1-0.png" max-width="600px" alt="Geomap panel ArcGIS World Imagery" >}}
- World Physical
{{< figure src="/static/img/docs/geomap-panel/geomap-arcgis-wp-9-1-0.png" max-width="600px" alt="Geomap panel ArcGIS World Physical" >}}
- Topographic
{{< figure src="/static/img/docs/geomap-panel/geomap-arcgis-topographic-9-1-0.png" max-width="600px" alt="Geomap panel ArcGIS Topographic" >}}
- USA Topographic
{{< figure src="/static/img/docs/geomap-panel/geomap-arcgis-usa-topographic-9-1-0.png" max-width="600px" alt="Geomap panel ArcGIS USA Topographic" >}}
- World Ocean
{{< figure src="/static/img/docs/geomap-panel/geomap-arcgis-ocean-9-1-0.png" max-width="600px" alt="Geomap panel ArcGIS World Ocean" >}}
- Custom MapServer (see [XYZ](#xyz-tile-layer) for formatting)
- URL template
- Attribution
- **Opacity** from 0 (transparent) to 1 (opaque)
- **Display tooltip** - allows you to toggle tooltips for the layer.
##### More Information
- [ArcGIS Services](https://services.arcgisonline.com/arcgis/rest/services)
- [About ESRI](https://www.esri.com/en-us/about/about-esri/overview)
#### XYZ Tile layer
The XYZ Tile layer is a map from a generic tile layer.
{{< figure src="/static/img/docs/geomap-panel/geomap-xyz-9-1-0.png" max-width="600px" alt="Geomap panel xyz example" >}}
- **URL template** - Set a valid tile server url, with {z}/{x}/{y} for example: https://tile.openstreetmap.org/{z}/{x}/{y}.png
- **Attribution** sets the reference string for the layer if displayed in [map controls](#show-attribution)
- **Opacity** from 0 (transparent) to 1 (opaque)
##### More information
- [Tiled Web Map Wikipedia](https://en.wikipedia.org/wiki/Tiled_web_map)
- [List of Open Street Map Tile Servers](https://wiki.openstreetmap.org/wiki/Tile_servers)
### Basemap layer options
A basemap layer provides the visual foundation for a mapping application. It typically contains data with global coverage. Several base layer options
are available each with specific configuration options to style the base map.
Basemap layer types can also be added as layers. You can specify an opacity.
There are four basemap layer types to choose from in a geomap.
- [Open Street Map](#open-street-map-layer) adds a map from a collaborative free geographic world database.
- [CARTO basemap](#carto-basemap-layer) adds a layer from CARTO Raster basemaps.
- [ArcGIS MapServer](#arcgis-mapserver-layer) adds a layer from an ESRI ArcGIS MapServer.
- [XYZ Tile layer](#xyz-tile-layer) adds a map from a generic tile layer.
The default basemap layer uses the CARTO map. You can define custom default base layers in the `.ini` configuration file.
![Basemap layer options](/static/img/docs/geomap-panel/geomap-baselayer-8-1-0.png)
#### Configure the default base layer with provisioning
You can configure the default base map using config files with Grafana’s provisioning system. For more information on all the settings, refer to the [provisioning docs page](ref:provisioning-docs-page).
Use the JSON configuration option `default_baselayer_config` to define the default base map. There are currently four base map options to choose from: `carto`, `esri-xyz`, `osm-standard`, `xyz`. Here are some provisioning examples for each base map option.
- **carto** loads the CartoDB tile server. You can choose from `auto`, `dark`, and `light` theme for the base map and can be set as shown below. The `showLabels` tag determines whether or not Grafana shows the Country details on top of the map. Here is an example:
```ini
geomap_default_baselayer = `{
"type": "carto",
"config": {
"theme": "auto",
"showLabels": true
}
}`
```
- **esri-xyz** loads the ESRI tile server. There are already multiple server instances implemented to show the various map styles: `world-imagery`, `world-physical`, `topo`, `usa-topo`, and `ocean`. The `custom` server option allows you to configure your own ArcGIS map server. Here are some examples:
{{< tabs >}}
{{< tab-content name="World imagery" >}}
```ini
geomap_default_baselayer = `{
"type": "esri-xyz",
"config": {
"server": "world-imagery"
}
}`
```
{{< /tab-content >}}
{{< tab-content name="Custom" >}}
```ini
geomap_default_baselayer = `{
"type": "esri-xyz",
"config": {
"server": "custom",
"url": "[tile server url]",
"attribution": "[tile server attribution]"
}
}`
```
{{< /tab-content >}}
{{< /tabs >}}
- **osm-standard** loads the OpenStreetMap tile server. There are no additional configurations needed and the `config` fields can be left blank. Here is an example:
```ini
default_baselayer_config = `{
"type": "osm-standard",
"config": {}
}`
```
- **xyz** loads a custom tile server defined by the user. Set a valid tile server `url`, with {z}/{x}/{y} for this option in order to properly load a default base map. Here is an example:
```ini
default_baselayer_config = `{
"type": "xyz",
"config": {
"attribution": "Open street map",
"url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
}
}`
```
`enable_custom_baselayers` allows you to enable or disable custom open source base maps that are already implemented. The default is `true`.
### Map controls options
The map controls section contains various options for map information and tool overlays.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| [Show zoom control](#show-zoom-control) | Displays zoom controls in the upper left corner. |
| [Mouse wheel zoom](#mouse-wheel-zoom) | Enables the mouse wheel to be used for zooming in or out. |
| [Show attribution](#show-attribution) | Displays attribution for basemap layers. |
| [Show scale](#show-scale) | Displays scale information in the bottom left corner in meters (m) or kilometers (km). |
| [Show measure tools](#show-measure-tools) | Displays measure tools in the upper right corner. This includes the [Length](#length) and [Area](#area) options. |
| [Show debug](#show-debug) | Displays debug information in the upper right corner. |
| [Tooltip](#tooltip) | Controls display of tooltips. |
<!-- prettier-ignore-end -->
#### Show zoom control
Displays zoom controls in the upper left corner. This control can be useful when using systems that don't have a mouse.
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-zoom-9-1-0.png" max-width="300px" alt="Geomap panel zoom" >}}
#### Mouse wheel zoom
Enables the mouse wheel to be used for zooming in or out.
#### Show attribution
Displays attribution for basemap layers.
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-attribution-9-1-0.png" max-width="400px" alt="Geomap panel attribution" >}}
#### Show scale
Displays scale information in the bottom left corner in meters (m) or kilometers (km).
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-scale-9-1-0.png" max-width="400px" alt="Geomap panel scale" >}}
#### Show measure tools
Displays measure tools in the upper right corner. Measurements appear only when this control is open.
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-measure-9-1-0.png" max-width="400px" alt="Geomap panel measure" >}}
- **Click** to start measuring
- **Continue clicking** to continue measurement
- **Double-click** to end measurement
When you change measurement type or units, the previous measurement is removed from the map. If the control is closed and then re-opened, the most recent measurement is displayed. A measurement can be modified by clicking and dragging on it.
##### Length
Get the spherical length of a geometry. This length is the sum of the great circle distances between coordinates. For multi-part geometries, the length is the sum of the length of each part. Geometries are assumed to be in 'EPSG:3857'.
- **Metric (m/km)**
- **Feet (ft)**
- **Miles (mi)**
- **Nautical miles (nmi)**
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-measure-length-9-1-0.png" max-width="400px" alt="Geomap panel measure length" >}}
##### Area
Get the spherical area of a geometry. This area is calculated assuming that polygon edges are segments of great circles on a sphere. Geometries are assumed to be in 'EPSG:3857'.
- **Square Meters (m²)**
- **Square Kilometers (km²)**
- **Square Feet (ft²)**
- **Square Miles (mi²)**
- **Acres (acre)**
- **Hectare (ha)**
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-measure-area-9-1-0.png" max-width="550px" alt="Geomap panel measure area" >}}
#### Show debug
Displays debug information in the upper right corner. This can be useful for debugging or validating a data source.
- **Zoom** displays current zoom level of the map.
- **Center** displays the current **longitude**, **latitude** of the map center.
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-debug-9-1-0.png" max-width="400px" alt="Geomap panel debug" >}}
#### Tooltip
Tooltips are supported for the **Markers**, **Heatmap**, **Photos** (beta) layers.
For these layer types, choose from the following tooltip options:
- **None** displays tooltips only when a data point is clicked.
- **Details** displays tooltips when a mouse pointer hovers over a data point.
When a data point on the geomap represents one row&mdash;that is, only a single row of response data is relevant to that point&mdash;the tooltip displays a grid with the row's names and values:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-single-row-marker-v12.1.png" max-width="750px" alt="A data point with one row of associated data" >}}
When a data point represents more than one row&mdash;that is, different rows but with the same geographical information&mdash;then each row appears as a single entry:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-multiple-row-marker-v12.1.png" max-width="750px" alt="A data point with mulitple rows of associated data" >}}
The text displayed in each tooltip row is associated with the first field value in each data row.
Click it to expand and display the full details of the data row.
{{< admonition type="note" >}}
The data appearing in each detail row is determined by the underlying query and transformations applied to the query's results, and can't be directly controlled using tooltip options.
{{< /admonition >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/heatmap/index.md
+218
View File
@@ -0,0 +1,218 @@
---
aliases:
- ../../../features/panels/heatmap/ # /docs/grafana/next/features/panels/heatmap/
- ../../heatmap/ # /docs/grafana/next/visualizations/heatmap/
- ../../../panels-visualizations/visualizations/heatmap/ # /docs/grafana/next/panels-visualizations/visualizations/heatmap/
description: Configure options for Grafana's heatmap visualization
keywords:
- grafana
- heatmap
- panel
- documentation
labels:
products:
- cloud
- enterprise
- oss
title: Heatmap
weight: 100
refs:
intro-histograms-heatmaps:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/fundamentals/intro-histograms/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/fundamentals/intro-histograms/
histograms:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/histogram/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/histogram/
dashboards:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/create-dashboard/
---
# Heatmap
Heatmaps allow you to view [histograms](ref:histograms) over time. While histograms display the data distribution that falls in a specific value range, heatmaps allow you to identify patterns in the histogram data distribution over time. For more information about heatmaps, refer to [Introduction to histograms and heatmaps](ref:intro-histograms-heatmaps).
For example, if you want to understand the temperature changes for the past few years, you can use a heatmap visualization to identify trends in your data:
{{< figure src="/static/img/docs/heatmap-panel/temperature_heatmap.png" max-width="1025px" alt="A heatmap visualization showing the random walk distribution over time" >}}
{{< docs/play title="Grafana Heatmaps" url="https://play.grafana.org/d/heatmap-calculate-log/" >}}
You can use a heatmap visualization if you need to:
- Visualize a large density of your data distribution.
- Condense large amounts of data through various color schemes that are easier to interpret.
- Identify any outliers in your data distribution.
- Provide statistical analysis to see how values or trends change over time.
## Configure a heatmap visualization
Once you’ve created a [dashboard](ref:dashboards), the following video shows you how to configure a heatmap visualization:
{{< youtube id="SGWBzQ54koE" >}}
## Supported data formats
Heatmaps support time series data.
### Example
The table below is a simplified output of random walk distribution over time:
| Time | Walking (km) |
| ------------------- | ------------ |
| 2023-06-25 21:13:09 | 10 |
| 2023-08-25 21:13:10 | 8 |
| 2023-08-30 21:13:10 | 10 |
| 2023-10-08 21:13:11 | 12 |
| 2023-12-25 21:13:11 | 14 |
| 2024-01-05 21:13:12 | 13 |
| 2024-02-22 21:13:13 | 10 |
The data is converted as follows:
{{< figure src="/static/img/docs/heatmap-panel/heatmap.png" max-width="1025px" alt="A heatmap visualization showing the random walk distribution over time" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Heatmap options
The following options control how data in the heatmap is calculated and grouped.
<!-- prettier-ignore-start -->
| Options | Description |
| ------- | ----------- |
| Calculate from data | This setting determines if the data is already a calculated heatmap (from the data source/transformer), or one that should be calculated in the panel. |
| X Bucket | This setting determines how the x-axis is split into buckets. You can specify a time interval in the **Size** input. For example, a time range of `1h` makes the cells 1-hour wide on the x-axis. You can also set an interval based on **Count**. |
| Y Bucket | This setting determines how the y-axis is split into buckets. Choose from **Size** or **Count**. |
| Y Bucket scale | Select one of the following y-axis value scales:<ul><li>**Linear** - Linear scale.</li><li>**Logarithmic** - Choose a **Log base** of **2** or **10**.</li><li>**Symlog** - Symlog scale. Choose a **Log base** of **2** or **10** and enter a value for the **Linear threshold**.</li></ul> |
<!-- prettier-ignore-end -->
### Y-Axis options
The following options define the display of the y-axis.
<!-- prettier-ignore-start -->
| Options | Description |
| ------- | ----------- |
| Placement | Set where the y-axis is displayed. Choose from: **Left**, **Right**, or **Hidden**. |
| Unit | Unit configuration. |
| Decimals | This setting determines decimal configuration. |
| Min/Max value | These settings configure the axis range. |
| Axis width | This setting configures the width for the axis. |
| Axis label | This setting configures the axis value. |
| Tick alignment | Sets the alignment of the tick marks on the visualization. Choose from: **Auto**, **Top (LE)**, **Middle**, and **Bottom (GE)**. This option is only displayed when your **Calculate from data** setting is **No**. |
| Reverse| When selected, the axis appears in reverse order. |
<!-- prettier-ignore-end -->
{{< docs/shared lookup="visualizations/multiple-y-axes.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+3" >}}
### Colors options
The color spectrum controls the mapping between value count (in each bucket) and the color assigned to each bucket. The leftmost color on the spectrum represents the minimum count and the color on the right most side represents the maximum count. Some color schemes are automatically inverted when using the light theme.
You can also change the color mode to Opacity. In this case, the color will not change but the amount of opacity will change with the bucket count
#### Mode
Use the following options to define the heatmap colors.
- **Scheme** - Bucket value represented by cell color.
- **Scheme** - If the mode is **Scheme**, then select a color scheme.
- **Opacity** - Bucket value represented by cell opacity. Opaque cell means maximum value.
- **Color** - Cell base color.
- **Scale** - Scale for mapping bucket values to the opacity.
- **Exponential** - Power scale. Cell opacity calculated as `value ^ k`, where `k` is a configured **Exponent** value. If exponent is less than `1`, you will get a logarithmic scale. If exponent is greater than `1`, you will get an exponential scale. In case of `1`, scale will be the same as linear.
- **Exponent** - Value of the exponent, greater than `0`.
- **Linear** - Linear scale. Bucket value maps linearly to the opacity.
#### Steps
Set a value between `1` and `128`.
#### Reverse
Toggle the switch to reverse the color scheme. This option only applies the **Scheme** color mode.
#### Start/end color scale from value
By default, Grafana calculates cell colors based on minimum and maximum bucket values. With Min and Max you can overwrite those values. Consider a bucket value as a Z-axis and Min and Max as Z-Min and Z-Max, respectively.
- **Start** - Minimum value using for cell color calculation. If the bucket value is less than Min, then it is mapped to the "minimum" color. The series min value is the default value.
- **End** - Maximum value using for cell color calculation. If the bucket value is greater than Max, then it is mapped to the "maximum" color. The series max value is the default value.
### Cell display options
Use these settings to control the display of heatmap cells.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Unit | Unit configuration. |
| Decimals | This setting determines decimal configuration. |
| Cell gap | Set how much space there is between cells. |
| Hide cells with values <= | Enter a value. |
| Hide cells with values >= | Enter a value. |
<!-- prettier-ignore-end -->
### Tooltip options
Tooltip options control the information overlay that appears when you hover over data points in the visualization.
| Option | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Tooltip mode](#tooltip-mode) | When you hover your cursor over the visualization, Grafana can display tooltips. Choose how tooltips behave. |
| Show histogram (Y axis) | When you set the **Tooltip mode** to **Single**, this option is displayed. This option controls whether or not the tooltip includes a histogram representing the y-axis. |
| [Show color scale](#show-color-scale) | This option controls whether or not the tooltip includes the color scale that's also represented in the legend. |
| Max width | Set the maximum width of the tooltip box. |
| Max height | Set the maximum height of the tooltip box. The default is 600 pixels. |
#### Tooltip mode
When you hover your cursor over the visualization, Grafana can display tooltips. Choose how tooltips behave.
- **Single -** The hover tooltip shows only a single series, the one that you are hovering over on the visualization.
- **All -** The hover tooltip shows all series in the visualization. Grafana highlights the series that you are hovering over in bold in the series list in the tooltip.
- **Hidden -** Do not display the tooltip when you interact with the visualization.
Use an override to hide individual series from the tooltip.
#### Show color scale
When you set the **Tooltip mode** to **Single**, this option is displayed. This option controls whether or not the tooltip includes the color scale that's also represented in the legend. When the color scale is included in the tooltip, it shows the hovered value on the scale:
![Heatmap with a tooltip displayed showing the hovered value reflected in the color scale](/media/docs/grafana/panels-visualizations/screenshot-heatmap-tooltip-color-scale-v11.0.png)
### Legend options
Choose whether you want to display the heatmap legend on the visualization by toggling the **Show legend** switch.
### Exemplars
Set the color used to show exemplar data.
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/histogram/index.md
+165
View File
@@ -0,0 +1,165 @@
---
aliases:
- ../../../features/panels/histogram/ # /docs/grafana/next/features/panels/histogram/
- ../../../panels/visualizations/histogram/ # /docs/grafana/next/panels/visualizations/histogram/
- ../../../visualizations/histogram/ # /docs/grafana/next/visualizations/histogram/
- ../../../panels-visualizations/visualizations/histogram/ # /docs/grafana/next/panels-visualizations/visualizations/histogram/
description: Configure options for Grafana's histogram visualization
keywords:
- grafana
- docs
- bar chart
- panel
- barchart
labels:
products:
- cloud
- enterprise
- oss
title: Histogram
weight: 100
refs:
color-scheme:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/#color-scheme
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/#color-scheme
---
# Histogram
Histograms calculate the distribution of values and present them as a bar chart. Each bar represents a bucket; the y-axis and the height of each bar represent the count of values that fall into each bucket, and the x-axis represents the value range.
For example, if you want to understand the distribution of people's heights, you can use a histogram visualization to identify patterns or insights in the data distribution:
{{< figure src="/static/img/docs/histogram-panel/histogram-example-v8-0.png" max-width="1025px" alt="A histogram visualization showing the distribution of people's heights" >}}
You can use a histogram visualization if you need to:
- Visualize and analyze data distributions over a specific time range to see how frequently certain values occur.
- Identify any outliers in your data distribution.
- Provide statistical analysis to help with decision-making
## Configure a histogram visualization
After you've created a [dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/), the following video shows you how to configure a histogram visualization:
{{< youtube id="QfJ480j9-KM" >}}
{{< docs/play title="Histogram Examples" url="https://play.grafana.org/d/histogram_tests/" >}}
## Supported data formats
Histograms support time series and any table results with one or more numerical fields.
### Examples
The following tables are examples of the type of data you need for a histogram visualization and how it should be formatted.
#### Time-series table
| Time | Walking (km) |
| ------------------- | ------------ |
| 2024-03-25 21:13:09 | 37.2 |
| 2024-03-25 21:13:10 | 37.1 |
| 2024-03-25 21:13:10 | 37.0 |
| 2024-03-25 21:13:11 | 37.2 |
| 2024-03-25 21:13:11 | 36.9 |
| 2024-03-25 21:13:12 | 36.7 |
| 2024-03-25 21:13:13 | 36.3 |
The data is converted as follows:
{{< figure src="/static/img/docs/histogram-panel/histogram-example-time-series.png" max-width="1025px" alt="A histogram visualization showing the random walk distribution." >}}
#### Basic numerical table
| Gender | Height (in) | Weight (lbs) |
| ------ | ----------- | ------------ |
| Male | 73.8 | 242 |
| Male | 68.8 | 162 |
| Male | 74.1 | 213 |
| Male | 71.7 | 220 |
| Male | 69.9 | 206 |
| Male | 67.3 | 152 |
| Male | 68.8 | 184 |
The data is converted as follows:
{{< figure src="/static/img/docs/histogram-panel/histogram-example-height-weight.png" max-width="1025px" alt="A histogram visualization showing the male height and weight distribution" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Histogram options
Use the following options to refine your histogram visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Bucket count | Specifies the number of bins used to group your data in the histogram, affecting the granularity of the displayed distribution. Leave this empty for automatic bucket count of 30. |
| Bucket size | The size of the buckets. Leave this empty for automatic bucket sizing (~10% of the full range). |
| [Bucket offset](#bucket-offset) | If the first bucket should not start at zero. A non-zero offset has the effect of shifting the aggregation window. |
| Combine series | This will merge all series and fields into a combined histogram. |
| Stacking | Controls how multiple series are displayed in the histogram. Choose from the following:<ul><li>**Off** - Series are not stacked, but instead shown side by side.</li><li>**Normal** - Series are stacked on top of each other, showing cumulative values.</li><li>**100%** - Series are stacked to fill 100% of the chart, showing the relative proportion of each series.</li></ul> |
| Line width | Controls line width of the bars. |
| Fill opacity | Controls the fill opacity bars. |
| [Gradient mode](#gradient-mode) | Set the mode of the gradient fill. Fill gradient is based on the line color. |
<!-- prettier-ignore-end -->
#### Bucket offset
If the first bucket should not start at zero, a non-zero offset has the effect of shifting the aggregation window.
For example, 5-sized buckets that are 0-5, 5-10, 10-15 with a default 0 offset would become 2-7, 7-12, 12-17 with an offset of 2; offsets of 0, 5, or 10, in this case, would effectively do nothing.
Typically, this option would be used with an explicitly defined bucket size rather than automatic. For this setting to affect, the offset amount should be greater than 0 and less than the bucket size; values outside this range have the same effect as values within this range.
#### Gradient mode
Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard [color scheme](ref:color-scheme) field option.
Gradient display is influenced by the **Fill opacity** setting.
Choose from the following:
- **None** - No gradient fill. This is the default setting.
- **Opacity** - Transparency of the gradient is calculated based on the values on the Y-axis. The opacity of the fill is increasing with the values on the Y-axis.
- **Hue** - Gradient color is generated based on the hue of the line color.
- **Scheme** - The selected [color palette](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-standard-options/#color-scheme) is applied to the histogram bars.
### Tooltip options
{{< docs/shared lookup="visualizations/tooltip-options-3.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Legend options
{{< docs/shared lookup="visualizations/legend-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/logs/index.md
+99
View File
@@ -0,0 +1,99 @@
---
aliases:
- ../../../features/panels/logs/ # /docs/grafana/next/features/panels/logs/
- ../../../panels/visualizations/logs-panel/ # /docs/grafana/next/panels/visualizations/logs-panel/
- ../../../reference/logs/ # /docs/grafana/next/reference/logs/
- ../../logs-panel/ # /docs/grafana/next/visualizations/logs-panel/
- ../../../panels-visualizations/visualizations/logs/ # /docs/grafana/next/panels-visualizations/visualizations/logs/
keywords:
- grafana
- dashboard
- documentation
- panels
- logs panel
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's logs visualization
title: Logs
weight: 100
refs:
log-levels:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/explore/logs-integration/#log-level
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/explore/logs-integration/#log-level
---
# Logs
_Logs_ are structured records of events or messages generated by a system or application&mdash;that is, a series of text records with status updates from your system or app. They generally include timestamps, messages, and context information like the severity of the logged event.
The logs visualization displays these records from data sources that support logs, such as Elastic, Influx, and Loki. The logs visualization has colored indicators of log status, as well as collapsible log events that help you analyze the information generated.
![Logs visualization](/media/docs/grafana/panels-visualizations/screenshot-logs-v11.3.png)
{{< docs/play title="Logs Panel" url="https://play.grafana.org/d/6NmftOxZz/" >}}
Typically, you use logs with a graph visualization to display the log output of a related process. If you have an incident in your application or systems, such as a website disruption or code failure, you can use the logs visualization to help you figure out what went wrong, when, and even why.
## Configure a log visualization
The following video provides a walkthrough of creating a logs visualization. You'll also learn how to customize some settings and log visualization caveats:
{{< youtube id="jSSi_x-fD_8" >}}
## Supported data formats
The logs visualization works best with log-type datasets such as queries from data sources like Loki, Elastic, and InfluxDB.
You can also build log-formatted data from other data sources as long as the first field is a time type followed by string, number, and time fields. The leading time field is used to sort and timestamp the logs and if the data contains other time-type fields, they’re included as elements of the logged record.
The second field is used as the log record title regardless of whether it’s a time, numeric, or string field. Usually the second field is a text field containing multiple string elements, but if the message level (or `lvl`) is present, the visualization uses the values in it to add colors to the record, as described in [Log levels integration](ref:log-levels).
Subsequent fields are collapsed inside of each log record and you can open them by clicking the expand (`>`) icon.
To limit the number of log lines rendered in the visualization, you can use the **Max data points** setting in the panel **Query options**. If that option isn't set, then the data source typically enforces its own default limit.
### Example
| Time | TitleMessage | Element1 | Element2 | Element3 |
| ------------------- | -------------------- | -------- | -------- | ------------------- |
| 2023-02-01 12:00:00 | title=Log1 lvl=info | 1 | server2 | 2023-02-01 11:00:00 |
| 2023-02-01 11:30:00 | title=Log1 lvl=error | 1 | server2 | 2023-02-01 11:00:00 |
| 2023-02-01 11:00:00 | title=Log1 lvl=trace | 1 | server2 | 2023-02-01 11:00:00 |
![Logs Example](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-logs-example.png 'Logs Example')
## Log level
For logs where a **level** label is specified, we use the value of the label to determine the log level and update color accordingly. If the log doesn't have a level label specified, we try to find out if its content matches any of the supported expressions (see below for more information). The log level is always determined by the first match. In case Grafana is not able to determine a log level, it will be visualized with **unknown** log level. See [supported log levels and mappings of log level abbreviation and expressions](ref:log-levels).
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Logs options
Use these settings to refine your visualization:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Time | Show or hide the time column. This is the timestamp associated with the log line as reported from the data source. |
| Unique labels | Show or hide the unique labels column, which shows only non-common labels. |
| Common labels | Show or hide the common labels. |
| Wrap lines | Turn line wrapping on or off. |
| Prettify JSON | Toggle the switch on to pretty print all JSON logs. This setting does not affect logs in any format other than JSON. |
| Enable log details | Toggle the switch on to see an extendable area with log details including labels and detected fields. Each field or label has a stats icon to display ad-hoc statistics in relation to all displayed logs. The default setting is on. |
| Deduplication | Hide log messages that are duplicates of others shown, according to your selected criteria. Choose from: <ul><li>**Exact** - Ignoring ISO datetimes.</li><li>**Numerical** - Ignoring only those that differ by numbers such as IPs or latencies.</li><li>**Signatures** - Removing successive lines with identical punctuation and white space.</li></ul> |
| Order | Set whether to show results **Newest first** or **Oldest first**. |
<!-- prettier-ignore-end -->
docs/sources/visualizations/panels-visualizations/visualizations/news/index.md
+61
View File
@@ -0,0 +1,61 @@
---
aliases:
- ../../../panels/visualizations/news-graph/ # /docs/grafana/next/panels/visualizations/news-graph/
- ../../news-panel/ # /docs/grafana/next/visualizations/news-panel/
- ../../../panels-visualizations/visualizations/news/ # /docs/grafana/next/panels-visualizations/visualizations/news/
keywords:
- grafana
- news
- documentation
- panels
- news panel
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's news visualization
title: News
weight: 100
---
# News
The news visualization displays an RSS feed. By default, it displays articles from the Grafana Labs blog, but you can change this by entering a different RSS feed URL.
{{< figure src="/static/img/docs/news/news-visualization.png" max-width="1025px" alt="A news visualization showing the latest Grafana news feed" >}}
{{< admonition type="note" >}}
In version 8.5, we discontinued the "Use Proxy" option for Grafana news visualizations. As a result, RSS feeds that are not configured for request by Grafana's frontend (with the appropriate [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)) may not load.
{{< /admonition >}}
You can use the news visualization to provide regular news and updates to your users.
{{< docs/play title="News Panel" url="https://play.grafana.org/d/cdodkwspaaa68b/" >}}
## Configure a news visualization
After you’ve created a [dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/), enter the URL of an RSS in the **URL** field in the **News** section. This visualization type doesn't accept any other queries, and you shouldn't expect to be able to filter or query the RSS feed data in any way using this visualization.
If you're having trouble loading an RSS feed, you can try rehosting the feed on a different server or using a CORS proxy. A CORS proxy is a tool that allows you to bypass CORS restrictions by making requests to the RSS feed on your behalf. You can find more information about using CORS proxies online.
If you're unable to display an RSS feed using the news visualization, you can try using the community RSS/Atom data source plugin [RSS/Atom data source](https://grafana.com/grafana/plugins/volkovlabs-rss-datasource/) in combination with the Dynamic text community panel [Dynamic text](https://grafana.com/grafana/plugins/marcusolsson-dynamictext-panel/). This will allow you to display the RSS feed in a different way.
## Supported data formats
The news visualization supports RSS and Atom feeds.
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### News options
Use the following options to refine your news visualization:
- **URL** - The URL of the RSS or Atom feed.
- **Show image** - Controls if the news social image is displayed beside the text content.
docs/sources/visualizations/panels-visualizations/visualizations/node-graph/index.md
+244
View File
@@ -0,0 +1,244 @@
---
aliases:
- ../../../panels-visualizations/visualizations/node-graph/ # /docs/grafana/next/panels-visualizations/visualizations/node-graph/
- ../../../panels/visualizations/node-graph/ # /docs/grafana/next/panels/visualizations/node-graph/
- ../../../visualizations/node-graph/ # /docs/grafana/next/visualizations/node-graph/
keywords:
- grafana
- dashboard
- documentation
- panels
- node graph
- directed graph
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's node graph visualization
title: Node graph
weight: 100
---
# Node graph
Node graphs are useful when you need to visualize elements that are related to each other. This is done by displaying circles&mdash;or _nodes_&mdash;for each element you want to visualize, connected by lines&mdash;or _edges_. The visualization uses a directed force layout that positions the nodes into a network of connected circles.
Node graphs display useful information about each node, as well as the relationships between them, allowing you to visualize complex infrastructure maps, hierarchies, or execution diagrams.
![Node graph visualization](/media/docs/grafana/panels-visualizations/screenshot-node-graph-v11.3.png 'Node graph')
The appearance of nodes and edges can also be customized in several ways including color, borders, and line style.
You can use a node graph visualization if you need to show:
- Solution topologies
- Networks
- Infrastructure
- Organizational charts
- Critical path diagrams
- Family trees
- Mind maps
## Configure a node graph visualization
The following video provides beginner steps for creating node panel visualizations. You'll learn the data requirements and caveats, special customizations, and much more:
{{< youtube id="VrvsMkRwoKw" >}}
{{< docs/play title="Node graph panel" url="https://play.grafana.org/d/bdodfbi3d57uoe/" >}}
## Supported data formats
To create node graphs, you need two datasets: one containing the records for the displayed elements (nodes) and one dataset containing the records for the connections between those elements (edges).
### Nodes dataset
The nodes dataset must contain one alphanumeric ID field that gives each element a unique identifier. The visualization also accepts other options fields for titles, subtitles, main and secondary stats, arc information for how much of the circle border to paint, details, colors, icons, node size, and indicators for element highlighting. For more information and naming conventions for these fields, refer to the [Nodes data frame structure](#nodes-data-frame-structure) section.
#### Example
| id | title | subtitle | mainstat | secondarystat | color | icon | highlighted |
| ----- | ----- | -------- | -------- | ------------- | ----- | ---- | ----------- |
| node1 | PC | Windows | AMD | 16gbRAM | blue | | true |
| node2 | PC | Linux | Intel | 32gbRAM | green | eye | false |
| node3 | Mac | MacOS | M3 | 16gbRAM | gray | apps | false |
| node4 | Alone | SoLonely | JustHere | NotConnected | red | | false |
If the icon field contains a value, it’s displayed instead of the title and subtitle. For a list of of available icons, refer to [Icons Overview](https://developers.grafana.com/ui/latest/index.html?path=/story/docs-overview-icon--icons-overview).
### Edges dataset
Similar to the nodes dataset, the edges dataset needs one unique ID field for each relationship, followed by two fields containing the source and the target nodes of the edge; that is, the nodes the edge connects. Other optional fields are main and secondary stats, context menu elements, line thickness, highlight indications, line colors, and configurations to turn the connection into a dashed line. For more information and naming conventions for these fields, refer to the [Edges data frame structure](#edges-data-frame-structure) section.
#### Example
| id | source | target | mainstat | seconddarystat | thickness | highlighted | color |
| ----- | ------ | ------ | -------- | -------------- | --------- | ----------- | ------ |
| edge1 | node1 | node2 | TheMain | TheSub | 3 | true | cyan |
| edge2 | node3 | node2 | Main2 | Sub2 | 1 | false | orange |
If a node lacks edge connections, it’s displayed on its own outside of the network.
### Data requirements
A node graph requires a specific shape of the data to be able to display its nodes and edges. This means not every data source or query can be visualized with this graph. If you want to use this as a data source developer see the section about data API.
A node graph consists of _nodes_ and _edges_.
- A _node_ is displayed as a circle. A node might represent an application, a service, or anything else that is relevant from an application perspective.
- An _edge_ is displayed as a line that connects two nodes. The connection might be a request, an execution, or some other relationship between the two nodes.
Both nodes and edges can have associated metadata or statistics. The data source defines what information and values is shown, so different data sources can show different type of values or not show some values.
#### Nodes
{{< admonition type="note" >}}
Node graphs can show only 1,500 nodes. If this limit is crossed a warning will be visible in upper right corner, and some nodes will be hidden. You can expand hidden parts of the graph by clicking on the "Hidden nodes" markers in the graph.
{{< /admonition >}}
Usually, nodes show two statistical values inside the node and two identifiers just below the node, usually name and type. Nodes can also show another set of values as a color circle around the node, with sections of different color represents different values that should add up to 1.
For example, you can have the percentage of errors represented by a red portion of the circle.
Additional details can be displayed in a context menu which is displayed when you click on the node.
There also can be additional links in the context menu that can target either other parts of Grafana or any external link.
![Node context menu](/media/docs/grafana/panels-visualizations/screenshot-node-links-v11.3.png 'Node context menu')
#### Edges
Edges can also show statistics when you hover over the edge. Similar to nodes, you can open a context menu with additional details and links by clicking on the edge.
The first data source supporting this visualization is X-Ray data source for its Service map feature. For more information, refer to the [X-Ray plugin documentation](https://grafana.com/grafana/plugins/grafana-x-ray-datasource).
## Node graph navigation
You can use pan, zoom, and other functions to navigate a node graph.
### Pan
You can pan the view by clicking outside any node or edge and dragging your mouse.
### Zoom
Use the buttons in the lower right corner to zoom in or out. You can also use the mouse wheel or touchpad scroll, together with either Ctrl or Cmd key to do so.
### Hidden nodes
The number of nodes shown at a given time is limited to maintain a reasonable visualization performance. Nodes that are not currently visible are hidden behind clickable markers that show an approximate number of hidden nodes that are connected by a particular edge. You can click on the marker to expand the graph around that node.
![Node graph exploration](/media/docs/grafana/panels-visualizations/node-graph-exploration-8.0-2.png 'Node graph exploration')
### Grid view
You can switch to the grid view to have a better overview of the most interesting nodes in the graph. Grid view shows nodes in a grid without edges and can be sorted by stats shown inside the node or by stats represented by the a colored border of the nodes.
![Node graph grid](/media/docs/grafana/panels-visualizations/screenshot-node-graph-grid-v11.3.png 'Node graph grid')
To sort the nodes, click on the stats inside the legend. The marker next to the stat name shows which stat is currently used for sorting and sorting direction.
![Node graph legend](/media/docs/grafana/panels-visualizations/screenshot-node-graph-legend-v11.3.png 'Node graph legend')
Click on the node and select "Show in Graph layout" option to switch back to graph layout and focus on the selected node, to show it in context of the full graph.
![Node graph grid to default](/media/docs/grafana/panels-visualizations/screenshot-node-graph-view-v11.3.png 'Node graph grid to default')
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Node graph options
Use the following options to refine your node graph visualization.
- **Zoom mode** - Choose how the node graph should handle zoom and scroll events.
### Nodes options
The **Nodes** options section provides configurations for node behaviors.
- **Main stat unit** - Choose which unit the main stat displays in the graph's nodes.
- **Secondary stat unit** - Choose which unit the secondary stat displays in the graph's nodes.
- **Arc sections** - Configure which fields define the size of the colored circle around the node and select a color for each. You can add multiple fields.
{{< admonition type="note" >}}
Defining arc sections overrides the automatic detection of `arc__*` and `color` fields described in the **Optional fields** section of [Nodes data frame structure](#nodes-data-frame-structure).
{{< /admonition >}}
### Edges options
The **Edges** options section provides configurations for node edges behaviors.
- **Main stat unit** - Choose which unit the main stat displays in the graph's edges.
- **Secondary stat unit** - Choose which unit the secondary stat displays in the graph's edges.
### Data links
{{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
In node graphs, some data fields may have pre-configured data links. To add a different data link in those cases, use a [field override](#field-overrides).
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
## Data API
This visualization needs a specific shape of the data to be returned from the data source in order to correctly display it.
Node graphs, at minimum, require a data frame describing the edges of the graph. By default, node graphs will compute the nodes and any stats based on this data frame. Optionally a second data frame describing the nodes can be sent in case there is need to show more node specific metadata. You have to set `frame.meta.preferredVisualisationType = 'nodeGraph'` on both data frames or name them `nodes` and `edges` respectively for the node graph to render.
### Edges data frame structure
Required fields:
| Field name | Type | Description |
| ---------- | ------ | ------------------------------ |
| id | string | Unique identifier of the edge. |
| source | string | Id of the source node. |
| target | string | Id of the target. |
Optional fields:
| Field name | Type | Description |
| --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mainstat | string/number | First stat shown in the overlay when hovering over the edge. It can be a string showing the value as is or it can be a number. If it is a number, any unit associated with that field is also shown |
| secondarystat | string/number | Same as mainStat, but shown right under it. |
| detail\_\_\* | string/number | Any field prefixed with `detail__` will be shown in the header of context menu when clicked on the edge. Use `config.displayName` for more human readable label. |
| thickness | number | The thickness of the edge. Default: `1` |
| highlighted | boolean | Sets whether the edge should be highlighted. Useful, for example, to represent a specific path in the graph by highlighting several nodes and edges. Default: `false` |
| color | string | Sets the default color of the edge. It can be an acceptable HTML color string. Default: `#999` |
| strokeDasharray | string | Sets the pattern of dashes and gaps used to render the edge. If unset, a solid line is used as edge. For more information and examples, refer to the [`stroke-dasharray` MDN documentation](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray). |
{{< admonition type="caution" >}}
Starting with 10.5, `highlighted` is deprecated.
It will be removed in a future release.
Use `color` to indicate a highlighted edge state instead.
{{< /admonition >}}
### Nodes data frame structure
Required fields:
| Field name | Type | Description |
| ---------- | ------ | -------------------------------------------------------------------------------------------- |
| id | string | Unique identifier of the node. This ID is referenced by edge in its source and target field. |
Optional fields:
| Field name | Type | Description |
| ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| title | string | Name of the node visible in just under the node. |
| subtitle | string | Additional, name, type or other identifier shown under the title. |
| mainstat | string/number | First stat shown inside the node itself. It can either be a string showing the value as is or a number. If it is a number, any unit associated with that field is also shown. |
| secondarystat | string/number | Same as mainStat, but shown under it inside the node. |
| arc\_\_\* | number | Any field prefixed with `arc__` will be used to create the color circle around the node. All values in these fields should add up to 1. You can specify color using `config.color.fixedColor`. |
| detail\_\_\* | string/number | Any field prefixed with `detail__` will be shown in the header of context menu when clicked on the node. Use `config.displayName` for more human readable label. |
| color | string/number | Can be used to specify a single color instead of using the `arc__` fields to specify color sections. It can be either a string which should then be an acceptable HTML color string or it can be a number in which case the behavior depends on `field.config.color.mode` setting. This can be for example used to create gradient colors controlled by the field value. |
| icon | string | Name of the icon to show inside the node instead of the default stats. Only Grafana [built in icons](https://developers.grafana.com/ui/latest/index.html?path=/story/iconography-icon--icons-overview)) are allowed. |
| nodeRadius | number | Radius value in pixels. Used to manage node size. |
| highlighted | boolean | Sets whether the node should be highlighted. Useful for example to represent a specific path in the graph by highlighting several nodes and edges. Default: `false` |
docs/sources/visualizations/panels-visualizations/visualizations/pie-chart/index.md
+197
View File
@@ -0,0 +1,197 @@
---
aliases:
- ../../../panels/visualizations/pie-chart-pane/ # /docs/grafana/next/panels/visualizations/pie-chart-pane/
- ../../pie-chart-panel/ # /docs/grafana/next/visualizations/pie-chart-panel/
- ../../../panels-visualizations/visualizations/pie-chart/ # /docs/grafana/next/panels-visualizations/visualizations/pie-chart/
keywords:
- grafana
- pie chart
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's pie chart visualization
title: Pie chart
weight: 100
refs:
calculation-types:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/calculation-types/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/calculation-types/
configure-legends:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-legend/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-legend/
---
# Pie chart
A pie chart is a graph that displays data as segments of a circle proportional to the whole, making it look like a sliced pie. Each slice corresponds to a value or measurement.
![Pie chart visualizations](/media/docs/grafana/panels-visualizations/screenshot-pie-chart-v11.4.png)
The pie chart visualization is ideal when you have data that adds up to a total and you want to show the proportion of each value compared to other slices, as well as to the whole of the pie.
You can use a pie chart if you need to compare:
- Browser share distribution in the market
- Incident causes per category
- Network traffic sources
- User demographics
## Configure a pie chart visualization
The following video guides you through the creation steps and common customizations of pie chart visualizations and is great for beginners:
{{< youtube id="A_lDhM9w4_g" >}}
{{< docs/play title="Grafana Bar Charts and Pie Charts" url="https://play.grafana.org/d/ktMs4D6Mk/" >}}
## Supported data formats
The pie chart is different from other visualizations in that it will only display one pie, regardless of the number of datasets, fields, or records queried in it.
To create a pie chart visualization, you need a dataset containing a set of numeric values either in rows, columns, or both.
### Example - One row
The easiest way to provide data for a pie chart visualization is in a dataset with a single record (or row) containing the fields (or columns) that you want in the pie, as in the following example. The default settings of the pie chart visualization automatically display each column as a slice of the pie.
| Value1 | Value2 | Value3 | Optional |
| ------ | ------ | ------ | -------- |
| 5 | 3 | 2 | Sums10 |
![Pie chart visualization with multiple values in a single row](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-pie-example1.png)
### Example - Multiple rows
If you need to use numeric data that's in multiple rows, the default **Show** parameter of the visualization [Value options](#value-options) is set to **Calculate** and use data from the last row.
| Value | Label |
| ----- | ------ |
| 5 | Value1 |
| 3 | Value2 |
| 2 | Value3 |
![Pie chart visualization with multiple row values showing the last one](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-pie-example2.png)
By default, the visualization is configured to [calculate](#value-options) a single value per column or series and to display only the last row of data.
To allow values in multiple rows to be displayed, change the **Show** setting in the [Value options](#value-options) from **Calculate** to **All values**.
![Pie chart visualization with multiple row values showing all values](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-pie-example3.png)
### Example - Multiple rows and columns
If your dataset contains multiple rows and columns with numeric data, by default only the last row's values are summed.
| Value1 | Value2 | Value3 | Optional |
| ------ | ------ | ------ | -------- |
| 5 | 3 | 2 | Sums10 |
| 10 | 6 | 4 | Sums20 |
| 20 | 8 | 2 | Sums30 |
![Pie chart visualization with multiple rows and columns showing the last one](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-pie-example4.png)
If you want to display all the cells, change the **Show** setting in the [Value options](#value-options) from **Calculate** to **All values**. This also labels the elements by concatenating all the text fields (if you have any) with the column name.
![Pie chart visualization with multiple rows and columns showing the all values](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-pie-example5.png)
If you want to display only the values from a given field (or column), once the **Show** setting in the [Value options](#value-options) is set to **All values**, set the **Fields** option to the column you wish to sum in the display. The value labels are also concatenated as indicated before.
![Pie chart visualization with multiple rows and columns showing values from one column](/media/docs/grafana/panels-visualizations/screenshot-grafana-12.1-pie-example6.png)
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value options
Use the following options to refine the value in your visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Show | Set how much information to show. Choose from:<ul><li>**Calculate** - Reduces each value to a single value per series.</li><li>**All values** - Displays every value from a single series.</li></ul> |
| Calculation | If you chose **Calculate** as your **Show** option, select a calculation to reduce each series. For information about available calculations, refer to [Calculation types](ref:calculation-types). |
| Limit | If you chose **All values** as your **Show** option, enter a value to limit the number of values displayed. |
| Fields | Select which field or fields to display in the visualization. Each field name is available on the list, or you can select one of the following options:<ul><li>**Numeric fields** - All fields with numerical values.</li><li>**All fields** - All fields that are not removed by transformations.</li><li>**Time** - All fields with time values.</li></ul> |
<!-- prettier-ignore-end -->
### Pie chart options
Use these options to refine how your visualization looks.
#### Pie chart type
Select the pie chart display style. Choose from **Pie** or **Donut**.
![Pie chart types](/media/docs/grafana/panels-visualizations/screenshot-pie-chart-types.png)
#### Slice sorting
By default, the pie chart is sorted so that the slices decrease in size clockwise around the circle.
You can configure the sorting of the slices, and by extension the legend, with the following options:
- **Descending** - The slices decrease in size, clockwise (default).
- **Ascending** - The slices increase in size, clockwise.
- **None** - No sorting is applied. The original order of the data is maintained.
#### Labels
Select labels to display on the pie chart. You can select more than one.
- **Name** - The series or field name.
- **Percent** - The percentage of the whole.
- **Value** - The raw numerical value.
Labels are displayed in white over the body of the chart. You might need to select darker chart colors to make them more visible. Long names or numbers might be clipped.
The following example shows a pie chart with **Name** and **Percent** labels displayed:
{{< figure src="/static/img/docs/pie-chart-panel/pie-chart-labels-7-5.png" alt="Pie chart labels" max-width="350px" >}}
### Tooltip options
{{< docs/shared lookup="visualizations/tooltip-options-1.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Legend options
Use these settings to define how the legend appears in your visualization. For more information about the legend, refer to [Configure a legend](ref:configure-legends).
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Visibility | Toggle the switch to turn the legend on or off. |
| Mode | Use these settings to define how the legend appears in your visualization. Choose from:<ul><li>**List** - Displays the legend as a list. This is a default display mode of the legend.</li><li>**Table** - Displays the legend as a table.</li></ul> |
| Placement | Select where to display the legend. Choose **Bottom** or **Right**. |
| Width | Control how wide the legend is when placed on the right side of the visualization. This option is only displayed if you set the legend placement to **Right**. |
| Legend values | Select values to display in the legend. You can select more than one:<ul><li>**Percent** - The percentage of the whole.</li><li>**Value** - The raw numerical value.</li></ul> |
<!-- prettier-ignore-end -->
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/stat/index.md
+190
View File
@@ -0,0 +1,190 @@
---
aliases:
- ../../../features/panels/singlestat/ # /docs/grafana/next/features/panels/singlestat/
- ../../../features/panels/stat/ # /docs/grafana/next/features/panels/stat/
- ../../../panels/visualizations/stat-panel/ # /docs/grafana/next/panels/visualizations/stat-panel/
- ../../../reference/singlestat/ # /docs/grafana/next/reference/singlestat/
- ../../stat-panel/ # /docs/grafana/next/visualizations/stat-panel/
- ../../../panels-visualizations/visualizations/stat/ # /docs/grafana/next/panels-visualizations/visualizations/stat/
description: Configure options for Grafana's stat visualization
keywords:
- grafana
- docs
- stat panel
labels:
products:
- cloud
- enterprise
- oss
title: Stat
weight: 100
refs:
calculation-types:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/calculation-types/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/calculation-types/
create-dashboard:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/create-dashboard/
---
# Stat
{{< admonition type="note" >}}
This visualization replaces the Singlestat visualization, which was deprecated in Grafana 7.0 and removed in Grafana 8.0.
{{< /admonition >}}
A stat visualization displays your data in single values of interest&mdash;such as the latest or current value of a series&mdash;with an optional graph sparkline. A graph sparkline, which is only available in stat visualizations, is a small time-series graph shown in the background of each value in the visualization.
For example, if you're monitoring the utilization of various services, you can use a stat visualization to show their latest usage:
![A stat panel showing latest usage of various services](/media/docs/grafana/panels-visualizations/screenshot-stat-visualization-v11.3.png)
Use a stat visualization when you need to:
- Monitor key metrics at a glance, such as the latest health of your application, number of high priority bugs in your application, or total number of sales.
- Display aggregated data, such as the average response time of your services.
- Highlight values above your normal thresholds to quickly identify if any metrics are outside your expected range.
{{< docs/play title="Stat Visualizations in Grafana" url="https://play.grafana.org/d/Zb3f4veGk/" >}}
## Configure a stat visualization
Once you've [created a dashboard](ref:create-dashboard), the following video shows you how to configure a stat visualization:
{{< youtube id="yNRnLyVntUw" start="1048" >}}
Alternatively, refer to this blog post on [how to easily retrieve values from a range in Grafana using a stat visualization](https://grafana.com/blog/2023/10/18/how-to-easily-retrieve-values-from-a-range-in-grafana-using-a-stat-panel/).
## Supported data formats
The stat visualization supports a variety of formats for displaying data. Supported formats include:
- **Single values** - The most common format and can be numerical, strings, or boolean values.
- **Time-series data** - [Calculation types](ref:calculation-types) can be applied to your time-series data to display single values over a specified time range.
### Examples
The following tables are examples of the type of data you need for a stat visualization and how it should be formatted.
#### Single numerical values
| Number of high priority bugs |
| ---------------------------- |
| 80 |
| 52 |
| 59 |
| 40 |
The data is visualized as follows, with the last value displayed, along with a sparkline and [percentage change](#value-options):
![A stat panel showing the latest number of high priority bugs](/media/docs/grafana/panels-visualizations/screenshot-stat-single-value-v11.3.png)
#### Time-series data
| Time | Cellar | Living room | Porch | Bedroom | Guest room | Kitchen |
| ------------------- | ------ | ----------- | ----- | ------- | ---------- | ------- |
| 2024-03-20 06:34:40 | 12.3 | 18.3 | 18.8 | 15.9 | 9.29 | 9.61 |
| 2024-03-20 06:41:40 | 16.8 | 17.1 | 21.5 | 14.1 | 10.5 | 17.5 |
| 2024-03-20 06:48:40 | 16.7 | 18.0 | 21.0 | 9.51 | 13.6 | 20.1 |
| 2024-03-20 06:55:40 | 14.3 | 18.7 | 16.5 | 9.11 | 14.8 | 12.5 |
| 2024-03-20 07:02:40 | 12.8 | 15.2 | 21.1 | 15.6 | 7.98 | 13.0 |
The data is visualized as follows, with the mean value displayed for each room, along with the room name, sparkline, and unit of measurement:
![A stat panel showing some statistics for each room in square meters](/media/docs/grafana/panels-visualizations/screenshot-stat-multiple-values-v11.3.png)
By default, a stat displays one of the following:
- Just the value for a single series or field.
- Both the value and name for multiple series or fields.
You can use the [**Text mode**](#text-mode) to control how the text is displayed.
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value options
Use the following options to refine how your visualization displays its values:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Show | Display a single value per column or series, or show values for each row. Choose from: <ul><li>**Calculate** - Display a calculated value based on all rows.</li><li>**All values** - Show a separate stat for every row. If you select this option, then you can also limit the number of rows to display.</li> |
| Calculation | This option is displayed when you select **Calculate** as your **Show** option. Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [Calculation types](ref:calculation-types). |
| Limit | This option is displayed when you select **All values** as your **Show** option. Set the maximum number of rows to display. Default is 5,000. |
| Fields | Select the fields displayed in the visualization. |
<!-- prettier-ignore-end -->
### Stat styles
The stat visualization automatically adjusts the layout depending on available width and height in the dashboard, but you can also use the following options to further style the visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Orientation | Select a stacking direction. Choose from: <ul><li>**Auto** - Grafana selects the ideal orientation.</li><li>**Horizontal** - Bars stretch horizontally, left to right.</li><li>**Vertical** - Bars stretch vertically, top to bottom.</li></ul> |
| [Text mode](#text-mode) | You can use the **Text mode** option to control what text the visualization renders. If the value is not important, only the name and color is, then change the **Text mode** to **Name**. The value will still be used to determine color and is displayed in a tooltip. |
| [Wide layout](#wide-layout) | Set whether wide layout is enabled or not. Wide layout is enabled by default. This option is only applicable when **Text mode** is set to **Value and name**. |
| Color mode | Select a color mode. Choose from: <ul><li>**None** - No color applied to the value.</li><li>**Value** - Applies color to the value and graph area.</li><li>**Background Gradient** - Applies color to the value, graph area, and background, with a slight background gradient.</li><li>**Background Solid** - Applies color to the value, graph area, and background, with a solid background color.</li></ul> |
| Graph mode | Select a graph sparkline mode. Choose from: <ul><li>**None** - Hides the graph sparkline and only shows the value.</li><li>**Area** - Shows the graph sparkline below the value. This requires that your query returns a time column.</li></ul> The graph sparkline is automatically hidden if the panel becomes too small.|
| Text alignment | Select an alignment mode. Choose from: <ul><li>**Auto** - If only a single value is shown (no repeat), then the value is centered. If multiple series or rows are shown, then the value is left-aligned.</li><li>**Center** - Stat value is centered.</li></ul> |
| Show percent change | Set whether percent change is displayed or not. Disabled by default. This option is applicable when the **Show** setting, under **Value options**, is set to **Calculate**. |
| Percent change color mode | This option is only displayed when **Show percent change** is enabled. Choose from: <ul><li>**Standard** - Green if the percent change is positive, red if the percent change is negative.</li><li>**Inverted** - Red if the percent change is positive, green if the percent change is negative.</li><li>**Same as Value** - Use the same color as the value.</li></ul> |
<!-- prettier-ignore-end -->
#### Text mode
You can use the Text mode option to control what text the visualization renders. If the value is not important, only the name and color is, then change the **Text mode** to **Name**. The value will still be used to determine color and is displayed in a tooltip.
- **Auto** - If the data contains multiple series or fields, show both name and value.
- **Value** - Show only value, never name. Name is displayed in the hover tooltip instead.
- **Value and name** - Always show value and name.
- **Name** - Show name instead of value. Value is displayed in the hover tooltip.
- **None** - Show nothing (empty). Name and value are displayed in the hover tooltip.
#### Wide layout
Set whether wide layout is enabled or not. Wide layout is enabled by default.
- **On** - Wide layout is enabled.
- **Off** - Wide layout is disabled.
This option is only applicable when **Text mode** is set to **Value and name**. When wide layout is enabled, the value and name are displayed side-by-side with the value on the right, if the panel is wide enough. When wide layout is disabled, the value is always rendered underneath the name.
### Text size
Adjust the sizes of the gauge text.
- **Title** - Enter a numeric value for the gauge title size.
- **Value** - Enter a numeric value for the gauge value size.
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/state-timeline/index.md
+164
View File
@@ -0,0 +1,164 @@
---
aliases:
- ../../../panels/visualizations/state-timeline/ # /docs/grafana/next/panels/visualizations/state-timeline/
- ../../state-timeline/ # /docs/grafana/next/visualizations/state-timeline/
- ../../../panels-visualizations/visualizations/state-timeline/ # /docs/grafana/next/panels-visualizations/visualizations/state-timeline/
description: Configure options for Grafana's state timeline visualization
keywords:
- grafana
- docs
- state timeline
- panel
labels:
products:
- cloud
- enterprise
- oss
title: State timeline
weight: 100
---
# State timeline
A state timeline visualization displays data in a way that shows state changes over time. In a state timeline, the data is presented as a series of bars or bands called _state regions_. State regions can be rendered with or without values, and the region length indicates the duration or frequency of a state within a given time range.
For example, if you're monitoring the CPU usage of a server, you can use a state timeline to visualize the different states, such as “LOW,” “NORMAL,” “HIGH,” or “CRITICAL,” over time. Each state is represented by a different color and the lengths represent the duration of time that the server remained in that state:
![A state timeline visualization showing CPU usage](/media/docs/grafana/panels-visualizations/screenshot-state-timeline-v11.4.png)
The state timeline visualization is useful when you need to monitor and analyze changes in states or statuses of various entities over time. You can use one when you need to:
- Monitor the status of a server, application, or service to know when your infrastructure is experiencing issues over time.
- Identify operational trends over time.
- Spot any recurring issues with the health of your applications.
## Configure a state timeline
{{< youtube id="a9wZHM0mdxo" >}}
{{< docs/play title="Grafana State Timeline & Status History" url="https://play.grafana.org/d/qD-rVv6Mz/6-state-timeline-and-status-history?orgId=1s" >}}
## Supported data formats
The state timeline visualization works best if you have data capturing the various states of entities over time, formatted as a table. The data must include:
- **Timestamps** - Indicate when each state change occurred. This could also be the start time for the state change. You can also add an optional timestamp to indicate the end time for the state change.
- **Entity name/identifier** - Represents the name of the entity you're trying to monitor.
- **State value** - Represents the state value of the entity you're monitoring. These can be string, numerical, or boolean states.
Each state ends when the next state begins or when there is a `null` value.
### Example 1
The following example has a single time column and includes null values:
| Timestamps | Server A | Server B |
| ------------------- | -------- | -------- |
| 2024-02-29 8:00:00 | Up | Up |
| 2024-02-29 8:15:00 | null | Up |
| 2024-02-29 8:30:00 | Down | null |
| 2024-02-29 8:45:00 | | Up |
| 2024-02-29 9:00:00 | Up | |
| 2024-02-29 9:15:00 | Up | Down |
| 2024-02-29 9:30:00 | Up | Down |
| 2024-02-29 10:00:00 | Down | Down |
| 2024-02-29 10:30:00 | Warning | Down |
The data is converted as follows, with the [null and empty values visualized as gaps](#connect-null-values) in the state timeline:
{{< figure src="/static/img/docs/state-timeline-panel/state-timeline-with-null-values.png" max-width="1025px" alt="A state timeline visualization with null values showing the status of two servers" >}}
### Example 2
The following example has two time columns and doesn't include any null values:
| Start time | End time | Server A | Server B |
| ------------------- | ------------------- | -------- | -------- |
| 2024-02-29 8:00:00 | 2024-02-29 8:15:00 | Up | Up |
| 2024-02-29 8:15:00 | 2024-02-29 8:30:00 | Up | Up |
| 2024-02-29 8:45:00 | 2024-02-29 9:00:00 | Down | Up |
| 2024-02-29 9:00:00 | 2024-02-29 9:15:00 | Down | Up |
| 2024-02-29 9:30:00 | 2024-02-29 10:00:00 | Down | Down |
| 2024-02-29 10:00:00 | 2024-02-29 10:30:00 | Warning | Down |
The data is converted as follows:
{{< figure src="/static/img/docs/state-timeline-panel/state-timeline-with-two-timestamps.png" max-width="1025px" alt="A state timeline visualization with two time columns showing the status of two servers" >}}
If your query results aren't in a table format like the preceding examples, especially for time-series data, you can apply specific [transformations](https://stackoverflow.com/questions/68887416/grafana-state-timeline-panel-with-values-states-supplied-by-label) to achieve this.
### Time series data
You can also create a state timeline visualization using time series data. To do this, add [thresholds](#thresholds), which turn the time series into discrete colored state regions.
![State timeline with time series](/media/docs/grafana/panels-visualizations/screenshot-state-timeline-time-series-v11.4.png)
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### State timeline options
Use these options to refine the visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------------------------------------------------------------------------------------------- |
| Merge equal consecutive values | Controls whether Grafana merges identical values if they are next to each other. |
| Show values | Controls whether values are rendered inside the state regions. Choose from **Auto**, **Always**, and **Never**. **Auto** renders values if there is sufficient space. |
| Align values | Controls value alignment inside state regions. Choose from **Left**, **Center**, and **Right**. |
| Row height | Controls how much space between rows there are. 1 = no space = 0.5 = 50% space. |
| [Page size](#page-size-enable-pagination) | The **Page size** option lets you paginate the state timeline visualization to limit how many series are visible at once. |
| Line width | Controls line width of state regions. |
| Fill opacity | Controls value alignment inside state regions. |
| [Connect null values](#connect-null-values) | Choose how null values, which are gaps in the data, appear on the graph. |
| [Disconnect null values](#disconnect-values) | Choose whether to set a threshold above which values in the data should be disconnected. |
<!-- prettier-ignore-end -->
#### Page size (enable pagination)
The **Page size** option lets you paginate the state timeline visualization to limit how many series are visible at once. This is useful when you have many series. With paginated results, the visualization displays a subset of all series on each page:
{{< video-embed src="/media/docs/grafana/panels-visualizations/screen-recording-grafana-11-2-state-timeline-pagination-dark.mp4" >}}
{{< docs/shared lookup="visualizations/connect-null-values.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
{{< docs/shared lookup="visualizations/disconnect-values.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Legend options
{{< docs/shared lookup="visualizations/legend-options-2.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Tooltip options
{{< docs/shared lookup="visualizations/tooltip-options-3.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Axis options
{{< docs/shared lookup="visualizations/axis-options-3.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/status-history/index.md
+143
View File
@@ -0,0 +1,143 @@
---
aliases:
- ../../../panels/visualizations/status-history/ # /docs/grafana/next/panels/visualizations/status-history/
- ../../status-history/ # /docs/grafana/next/visualizations/status-history/
- ../../../panels-visualizations/visualizations/status-history/ # /docs/grafana/next/panels-visualizations/visualizations/status-history/
description: Configure options for Grafana's status history visualization
keywords:
- grafana
- docs
- status history
- panel
labels:
products:
- cloud
- enterprise
- oss
title: Status history
weight: 100
---
# Status history
A status history visualization displays data in a way that shows periodic states over time. In a status history, each field or series is rendered as a horizontal row, with multiple boxes showing the different statuses. This provides you with a centralized view for the status of a component or service.
For example, if you're monitoring the health status of different services, you can use a status history to visualize the different statuses, such as “True” or "False," over time. Each status is represented by a different color:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-status-history-v11.6.png" max-width="800px" alt="A status history panel showing the health status of different sensors" >}}
{{< admonition type="note" >}}
A status history is similar to a [state timeline](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/), but has different [configuration options](#status-history-options). Unlike state timelines, status histories don't merge consecutive values.
{{< /admonition >}}
Use a status history when you need to:
- Monitor the status of a server, application, or service to know when your infrastructure is experiencing issues over time.
- Identify operational trends over time.
- Spot any recurring issues with the health of your applications.
## Configure a status history
Once you've [created a dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/), you can use the following state timeline video as a reference for how to configure a status history:
{{< youtube id="a9wZHM0mdxo" >}}
{{< docs/play title="Grafana State Timeline & Status History" url="https://play.grafana.org/d/qD-rVv6Mz/6-state-timeline-and-status-history?orgId=1s" >}}
## Supported data formats
The status history visualization works best if you have data capturing the various status of entities over time, formatted as a table. The data must include:
- **Timestamps** - Indicate when each status change occurred. This could also be the start time for the status change. You can also add an optional timestamp to indicate the end time for the status change.
- **Entity name/identifier** - Represents the name of the entity you're trying to monitor.
- **Status value** - Represents the state value of the entity you're monitoring. These can be string, numerical, or boolean states.
### Examples
The following tables are examples of the type of data you need for a status history visualization and how it should be formatted.
#### Single time column with null values
| Timestamps | Backend_01 | Backend_02 |
| ------------------ | ---------- | ---------- |
| 2024-02-29 8:00:00 | OK | WARN |
| 2024-02-29 8:15:00 | WARN | |
| 2024-02-29 8:18:00 | | WARN |
| 2024-02-29 8:30:00 | BAD | |
| 2024-02-29 8:36:00 | | OK |
| 2024-02-29 8:45:00 | OK | |
The data is converted as follows, with the null and empty values visualized as gaps in the status history:
{{< figure src="/static/img/docs/status-history-panel/status_history_with_null.png" max-width="1025px" alt="A status history panel with null values showing the status of two servers" >}}
#### Two time columns without null values
| Start time | End time | Backend_01 | Backend_02 |
| ------------------ | ------------------ | ---------- | ---------- |
| 2024-02-29 8:00:00 | 2024-02-29 8:15:00 | OK | OK |
| 2024-02-29 8:15:00 | 2024-02-29 8:30:00 | OK | OK |
| 2024-02-29 8:30:00 | 2024-02-29 8:45:00 | OK | OK |
| 2024-02-29 8:45:00 | 2024-02-29 9:00:00 | BAD | WARN |
| 2024-02-29 9:00:00 | 2024-02-29 9:15:00 | OK | WARN |
The data is converted as follows:
{{< figure src="/static/img/docs/status-history-panel/status_history.png" max-width="1025px" alt="A status history panel with two time columns showing the status of two servers" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Status history options
Use these options to refine the visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------------------------------------------------------------------------------------------- |
| Show values | Controls whether values are rendered inside the state regions. Choose from **Auto**, **Always**, and **Never**. **Auto** renders values if there is sufficient space. |
| Row height | Controls the height of boxes. 1 = maximum space and 0 = minimum space. |
| Column width | Controls the width of boxes. 1 = maximum space and 0 = minimum space. |
| Page size (enable pagination) | The **Page size** option lets you paginate the status history visualization to limit how many series are visible at once. This is useful when you have many series. |
| Line width | Controls line width of state regions. |
| Fill opacity | Controls value alignment inside state regions. |
<!-- prettier-ignore-end -->
### Legend options
{{< docs/shared lookup="visualizations/legend-options-2.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Tooltip options
{{< docs/shared lookup="visualizations/tooltip-options-3.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Axis options
{{< docs/shared lookup="visualizations/axis-options-3.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/table/index.md
+567
View File
@@ -0,0 +1,567 @@
---
aliases:
- ../../../features/panels/table_panel/ # /docs/grafana/next/features/panels/table_panel/
- ../../../panels/visualizations/table/filter-table-columns/ # /docs/grafana/next/panels/visualizations/table/filter-table-columns/
- ../../../reference/table/ # /docs/grafana/next/reference/table/
- ../../table/ # /docs/grafana/next/visualizations/table/
- ../../table/filter-table-columns/ # /docs/grafana/next/visualizations/table/filter-table-columns/
- ../../../panels/visualizations/table/table-field-options/ # /docs/grafana/next/panels/visualizations/table/table-field-options/
- ../../../panels-visualizations/visualizations/table/ # /docs/grafana/next/panels-visualizations/visualizations/table/
description: Configure options for Grafana's table visualization
keywords:
- grafana
- dashboard
- panels
- table panel
- table options
- format tables
- table filter
- filter columns
labels:
products:
- cloud
- enterprise
- oss
title: Table
weight: 100
refs:
calculations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/calculation-types/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/calculation-types/
time-series-panel:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
time-series-to-table-transformation:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/#time-series-to-table-transform
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/#time-series-to-table-transform
color-scheme:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/#color-scheme
- pattern: /docs/grafana-cloud
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/#color-scheme
field-override:
- 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/
data-transformation:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/
build-query:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/
graph-styles:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/#graph-styles-options
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/#graph-styles-options
---
# Table
Tables are a highly flexible visualization designed to display data in columns and rows.
The table visualization can take multiple datasets and provide the option to switch between them.
With this versatility, it's the preferred visualization for viewing multiple data types, aiding in your data analysis needs.
![Basic table visualization](/media/docs/grafana/panels-visualizations/screenshot-basic-table-v11.3.png)
You can use a table visualization to show datasets such as:
- Common database queries like logs, traces, metrics
- Financial reports
- Customer lists
- Product catalogs
Any information you might want to put in a spreadsheet can often be best visualized in a table.
Tables also provide different styles to visualize data inside the table cells, such as colored text and cell backgrounds, gauges, sparklines, data links, JSON code, and images.
{{< admonition type="note" >}}
Annotations and alerts are not currently supported for tables.
{{< /admonition >}}
## Configure a table visualization
The following video provides a visual walkthrough of the options you can set in a table visualization.
If you want to see a configuration in action, check out the video:
{{< youtube id="PCY7O8EJeJY" >}}
{{< docs/play title="Table Visualizations in Grafana" url="https://play.grafana.org/d/OhR1ID6Mk/" >}}
## Supported data formats
The table visualization supports any data that has a column-row structure.
{{< admonition type="note" >}}
If you’re using a cell type such as sparkline or JSON, the data requirements may differ in a way that’s specific to that type. For more info refer to [Cell type](#cell-type).
{{< /admonition >}}
### Example
This example shows a basic dataset in which there's data for every table cell:
```csv
Column1, Column2, Column3
value1 , value2 , value3
value4 , value5 , value6
value7 , value8 , value9
```
If a cell is missing or the table column-row structure is not complete, as in the following example, the table visualization won’t display any of the data:
```csv
Column1, Column2, Column3
value1 , value2 , value3
gap1 , gap2
value4 , value5 , value6
```
If you need to hide columns, you can do so using [data transformations](ref:data-transformation), [field overrides](#field-overrides), or by [building a query](ref:build-query) that returns only the needed columns.
## Column filtering
You can temporarily change how column data is displayed using column filtering.
For example, you can show or hide specific values.
### Turn on column filtering
To turn on column filtering, follow these steps:
1. In Grafana, navigate to the dashboard with the table with the columns that you want to filter.
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**.
1. In the panel editor pane, expand the **Table** options section.
1. Toggle on the [**Column filter** switch](#table-options).
A filter icon (funnel) appears next to each column title.
{{< figure src="/static/img/docs/tables/column-filter-with-icon.png" max-width="350px" alt="Column filtering turned on" class="docs-image--no-shadow" >}}
### Filter column values
To filter column values, follow these steps:
1. Click the filter icon (funnel) next to a column title.
Grafana displays the filter options for that column.
{{< figure src="/media/docs/grafana/panels-visualizations/filter-column-values_12.2.png" max-width="300px" alt="Filter column values" >}}
1. Click the checkbox next to the values that you want to display or click **Select all**.
1. Enter text in the search field at the top to show those values in the display so that you can select them rather than scroll to find them.
1. Choose from several operators to display column values:
- **Contains** - Matches a regex pattern (operator by default).
- **Expression** - Evaluates a boolean expression. The character `$` represents the column value in the expression (for example, "$ >= 10 && $ <= 12").
- The typical comparison operators: `=`, `!=`, `<`, `<=`, `>`, `>=`.
1. Click the checkbox above the **Ok** and **Cancel** buttons to add or remove all displayed values to and from the filter.
### Clear column filters
Columns with filters applied have a blue filter displayed next to the title.
{{< figure src="/static/img/docs/tables/filtered-column.png" max-width="100px" alt="Filtered column" class="docs-image--no-shadow" >}}
To remove the filter, click the blue filter icon and then click **Clear filter**.
<!-- vale Grafana.WordList = NO -->
<!-- vale Grafana.Spelling = NO -->
### Apply ad hoc filters from the table
In tables, you can apply ad hoc filters directly from the visualization with one click.
To display the filter icons, hover your cursor over the cell that has the value for which you want to filter:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-table-adhoc-filter-v12.2.png" max-width="500px" alt="Table with ad hoc filter icon displayed on a cell" >}}
For more information about applying ad hoc filters this way, refer to [Dashboard drilldown with ad hoc filters](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#dashboard-drilldown-with-ad-hoc-filters).
<!-- vale Grafana.Spelling = YES -->
<!-- vale Grafana.WordList = YES -->
## Sort columns
Click a column title to change the sort order from default to descending to ascending.
Each time you click, the sort order changes to the next option in the cycle.
You can sort multiple columns by holding the `Cmd` or `Ctrl` key
and clicking the column name.
{{< figure src="/static/img/docs/tables/sort-descending.png" max-width="350px" alt="Sort descending" class="docs-image--no-shadow" >}}
## Dataset selector
If the data queried contains multiple datasets, a table displays a drop-down list at the bottom, so you can select the dataset you want to visualize.
This option is only available when you're editing the panel.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-table-multi-dataset-v11.3.png" max-width="650px" alt="Table visualization with multiple datasets" >}}
## Configuration options
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Table options
<!-- prettier-ignore-start -->
| Option | Description |
| -------------------- | --------------------------------------------------------- |
| Show table header | Show or hide column names imported from your data source. |
| Frozen columns | Freeze columns starting from the left side of the table. Enter a value to set how many columns are frozen. |
| Cell height | Set the height of the cell. Choose from **Small**, **Medium**, or **Large**. |
| Max row height | Define the maximum height for a row in the table. This can be useful when **Wrap text** is enabled for one or more columns. |
| Enable pagination | Toggle the switch to control how many table rows are visible at once. When switched on, the page size automatically adjusts to the height of the table. This option doesn't affect queries. |
| Minimum column width | Define the lower limit of the column width, in pixels. By default, the minimum width of the table column is 150 pixels. For small-screen devices, such as mobile phones or tablets, reduce the value to `50` to allow table-based panels to render correctly in dashboards. |
| Column width | Define a column width, in pixels, rather than allowing the width to be set automatically. By default, Grafana calculates the column width based on the table size and the minimum column width. |
| Column alignment | Set how Grafana should align cell contents. Choose from: **Auto** (default), **Left**, **Center**, or **Right**. |
| Column filter | Temporarily change how column data is displayed. For example, show or hide specific values. For more information, refer to [Column filtering](#column-filtering). |
| Wrap text | Enables text wrapping for cell content. |
| Wrap header text | Enables text wrapping for column headers. |
<!-- prettier-ignore-end -->
### Table footer options
The table footer displays the results of calculations (and reducer functions) on fields.
The footer is only displayed after you select an option in the **Calculation** drop-down list:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-table-footer-selector-v12.2.png" max-width="300px" alt="The footer calculation selector, open" >}}
There are several calculations you can choose from including minimum, maximum, first, last, and total.
For the full list of options, refer to [Calculations](ref:calculations).
In the table footer:
- You can apply multiple calculations at once.
- The calculations and reducer functions apply to all fields in the table, by default. To control which fields have a calculation or function applied, add the table footer in an override instead.
- If you enable a mathematical function for a non-numeric field, nothing for that function is displayed for that field.
In the following image, multiple calculations&mdash;**Mean**, **Max**, and **Last**&mdash;have been applied:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-tablefooter-v12.2.png" max-width="750px" alt="Table with footer displaying mean, max, and last" >}}
You can also see in the previous image that the mathematical functions, **Mean** and **Max**, haven't been applied to the text field in the table.
Only the **Last** function has been applied to that field.
{{< admonition type="note">}}
Calculations applied to cell types like **Markdown + HTML** might have unexpected results.
{{< /admonition>}}
### Cell options
Cell options allow you to control how data is displayed in a table.
The options are differ based on the cell type that you select and are outlined within the descriptions of each cell type.
The following table provides short descriptions for each cell type and links to a longer description and the cell type options.
#### Cell type
By default, Grafana automatically chooses display settings.
You can override these settings by choosing one of the following cell types to control the default display for all fields.
Additional configuration is available for some cell types.
If you want to apply a cell type to only some fields instead of all fields, you can do so using the **Cell options > Cell type** field override.
<!-- prettier-ignore-start -->
| Cell type | Description |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [Auto](#auto) | A basic text and number cell. |
| [Colored text](#colored-text) | If thresholds, value mappings, or color schemes are set, then the cell text is displayed in the appropriate color. |
| [Colored background](#colored-background) | If thresholds, value mappings, or color schemes are set, then the cell background is displayed in the appropriate color. |
| [Data links](#data-links) | The cell text reflects the titles of the configured data links.|
| [Gauge](#gauge) | Values are displayed as a horizontal bar gauge. You can set the [Gauge display mode](#gauge-display-mode) and the [Value display](#value-display) options. |
| [Sparkline](#sparkline) | Shows values rendered as a sparkline. |
| [JSON View](#json-view) | Shows values formatted as code. |
| [Pill](#pill) | Displays each item in a comma-separated string in a colored block. |
| [Markdown + HTML](#markdown--html) | Displays rich markdown or HTML content. |
| [Image](#image) | Displays an image when the value is a URL or a base64 encoded image. |
| [Actions](#actions) | The cell displays a button that triggers a basic, unauthenticated API call when clicked. |
<!-- prettier-ignore-end -->
#### Auto
This is a basic text and number cell.
It has the following cell options:
{{< docs/shared lookup="visualizations/cell-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
#### Colored text
If thresholds, value mappings, or color schemes are set, the cell text is displayed in the appropriate color.
![Table with colored text cell type](/media/docs/grafana/panels-visualizations/screenshot-table-colored-text-v11.3-2.png)
The colored text cell type has the following options:
{{< docs/shared lookup="visualizations/cell-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
#### Colored background
If thresholds, value mappings, or color schemes are set, the cell background is displayed in the appropriate color.
![Table with colored background cell type](/media/docs/grafana/panels-visualizations/screenshot-table-colored-bkgrnd-v11.3-2.png)
You can also set background cell color by row:
![Table with background cell color applied to row](/media/docs/grafana/panels-visualizations/screenshot-table-colored-row-v11.3.png)
The colored background cell type has the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Background display mode | Choose between **Basic** and **Gradient**. |
| Apply to entire row | Toggle the switch on to apply the background color that's configured for the cell to the whole row. |
| Cell value inspect | <p>Enables value inspection from table cells. When the switch is toggled on, clicking the inspect icon in a cell opens the **Inspect value** drawer which contains two tabs: **Plain text** and **Code editor**.</p><p>Grafana attempts to automatically detect the type of data in the cell and opens the drawer with the associated tab showing. However, you can switch back and forth between tabs.</p> |
| Tooltip from field | Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip. For more information, refer to the [Tooltip from field](#tooltip-from-field). |
<!-- prettier-ignore-end -->
<!-- The cell value inspect and tooltip from field descriptions above should be copied from docs/sources/shared/visualizations/cell-options.md -->
#### Data links
If you've configured data links, when the cell type is **Auto**, the cell text becomes clickable.
If you change the cell type to **Data links**, the cell text reflects the titles of the configured data links. To control the application of data link text more granularly, use a **Cell option > Cell type > Data links** field override.
#### Gauge
With this cell type, cells can be displayed as a graphical gauge, with several different presentation types.
The gauge cell type has the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| Gauge display mode | Controls the type of gauge used. For more information, refer to the [Gauge display mode](#gauge-display-mode). |
| Value display | Controls how the value is displayed. For more information, refer to the [Value display](#value-display). |
| Tooltip from field | Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip. For more information, refer to [Tooltip from field](#tooltip-from-field). |
<!-- prettier-ignore-end -->
{{< admonition type="note" >}}
The maximum and minimum values of the gauges are configured automatically from the smallest and largest values in your whole dataset.
If you don't want the max/min values to be pulled from the whole dataset, you can configure them for each column using [field overrides](#field-overrides).
{{< /admonition >}}
##### Gauge display mode
You can set three gauge display modes.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Basic | Shows a simple gauge with the threshold levels defining the color of gauge. {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-gauge-mode-basic-v11.3.png" alt="Table cell with basic gauge mode" >}} |
| Gradient | The threshold levels define a gradient. {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-gauge-mode-gradient-v11.3.png" alt="Table cell with gradient gauge mode" >}} |
| Retro LCD | The gauge is split up in small cells that are lit or unlit. {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-gauge-mode-retro-v11.3.png" alt="Table cell with retro LCD gauge mode" >}} |
<!-- prettier-ignore-end -->
##### Value display
Labels displayed alongside of the gauges can be set to be colored by value, match the theme text color, or be hidden.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Value color | Labels are colored by value. {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-labels-value-color-v11.3.png" alt="Table with labels in value color" >}} |
| Text color | Labels match the theme text color. {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-labels-text-color-v11.3.png" alt="Table with labels in theme color" >}} |
| Hidden | Labels are hidden. {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-labels-hidden-v11.3.png" alt="Table with labels hidden" >}} |
<!-- prettier-ignore-end -->
#### Sparkline
This cell type shows values rendered as a sparkline.
To show sparklines on data with multiple time series, use the [Time series to table transformation](ref:time-series-to-table-transformation) to process it into a format the table can show.
![Table using sparkline cell type](/media/docs/grafana/panels-visualizations/screenshot-table-as-sparkline-v11.3.png)
The sparkline cell type options are described in the following table.
For more detailed information about all of the sparkline styling options (except **Hide value**), refer to the [time series graph styles documentation](ref:graph-styles).
<!-- prettier-ignore-start -->
| Option | Description |
| ------------------- | --------------------------------------------------------------------------------------------- |
| Hide value | Toggle the switch on or off to display or hide the cell value on the sparkline. |
| Style | Choose whether to display your time-series data as **Lines**, **Bars**, or **Points**. You can use overrides to combine multiple styles in the same graph. |
| Line interpolation | How the graph interpolates the series line. Choose from:<ul><li>**Linear** - Points are joined by straight lines.</li><li>**Smooth** - Points are joined by curved lines that smooths transitions between points.</li><li>**Step before** - The line is displayed as steps between points. Points are rendered at the end of the step.</li><li>**Step after** - The line is displayed as steps between points. Points are rendered at the beginning of the step.</li></ul> |
| Line width | The thickness of the series lines or the outline for bars using the **Line width** slider. |
| Fill opacity | The series area fill color using the **Fill opacity** slider. |
| Gradient mode | Gradient mode controls the gradient fill, which is based on the series color. Gradient appearance is influenced by the **Fill opacity** setting. To change the color, use the standard color scheme field option. For more information, refer to [Color scheme](ref:color-scheme). Choose from:<ul><li>**None** - No gradient fill. This is the default setting.</li><li>**Opacity** - An opacity gradient where the opacity of the fill increases as y-axis values increase.</li><li>**Hue** - A subtle gradient that's based on the hue of the series color.</li></ul> |
| Line style | Choose from:<ul><li>**Solid**</li><li>**Dash** - Select the length and gap for the line dashes. Default dash spacing is 10, 10.</li><li>**Dots** - Select the gap for the dot spacing. Default dot spacing is 0, 10.</li></ul> |
| Connect null values | How null values, which are gaps in the data, appear on the graph. Null values can be connected to form a continuous line or set to a threshold above which gaps in the data are no longer connected. Choose from:<ul><li>**Never** - Time series data points with gaps in the data are never connected.</li><li>**Always** - Time series data points with gaps in the data are always connected.</li><li>**Threshold** - Specify a threshold above which gaps in the data are no longer connected. This can be useful when the connected gaps in the data are of a known size or within a known range, and gaps outside this range should no longer be connected.</li></ul> |
| Show points | Whether to show data points to lines or bars. Choose from: <ul><li>**Auto** - Grafana determines a point's visibility based on the density of the data. If the density is low, then points appear.</li><li>**Always** - Show the points regardless of how dense the dataset is.</li><li>**Never** - Don't show points.</li></ul> |
| Point size | Set the size of the points, from 1 to 40 pixels in diameter. |
| Bar alignment | Set the position of the bar relative to a data point. |
| Tooltip from field | Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip. For more information, refer to [Tooltip from field](#tooltip-from-field). |
<!-- prettier-ignore-end -->
#### JSON View
This cell type shows values formatted as code.
If a value is an object the JSON view allowing browsing the JSON object will appear on hover.
{{< figure src="/static/img/docs/tables/json-view.png" max-width="350px" alt="JSON view" class="docs-image--no-shadow" >}}
For the JSON view cell type, you can set enable **Cell value inspect**.
This enables value inspection from table cells.
When the switch is toggled on, clicking the inspect icon in a cell opens the **Inspect value** drawer which contains two tabs: **Plain text** and **Code editor**.
Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip.
For more information, refer to [Tooltip from field](#tooltip-from-field).
Grafana attempts to automatically detect the type of data in the cell and opens the drawer with the associated tab showing.
However, you can switch back and forth between tabs.
#### Pill
The **Pill** cell type displays each item in a comma-separated string in a colored block.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-table-pill-cells-v12.2.png" max-width="750px" alt="Table using the pill cell type" >}}
The colors applied to each piece of text are maintained throughout the table.
For example, if the word "test" is first displayed in a red pill, it will always be displayed in a red pill.
The following data formats are supported for the pill cell type:
- Comma-separated values (`cows,chickens,goats`)
- JSON arrays of uniform (`(["cows","chickens","goats"])`) or mixed (`[1,2,3,"foo",42,"bar"]`) types
Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip.
For more information, refer to [Tooltip from field](#tooltip-from-field).
#### Markdown + HTML
The **Markdown + HTML** cell type displays rich Markdown or HTML content, rendered using the
[GitHub-Flavored Markdown](https://github.github.com/gfm/) spec. This is useful if you need to display
customized, pre-formatted information alongside tabular data, such as formatted strings,
lists of links, or other dynamic cases.
For this cell type, you can toggle the **Dynamic height** switch, which allows the cell to resize
dynamically based on the cell content. If you use dynamic height, we strongly recommend that you
also toggle on **Pagination** to avoid performance issues in larger tables, since enabling
Dynamic height disables table {{< term "virtualization" >}}virtualization{{< /term >}}.
By default, the HTML rendered is sanitized, and un-sanitized HTML can only be rendered
in these cells if the [`disable_sanitize_html`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#disable_sanitize_html) option is set to true for your Grafana instance.
Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip.
For more information, refer to [Tooltip from field](#tooltip-from-field).
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-table-markdown-v12.2.png" max-width="600px" alt="Table using the pill cell type" >}}
#### Image
If you have a field value that is an image URL or a base64 encoded image, this cell type displays it as an image.
![Table with image cell type](/media/docs/grafana/panels-visualizations/screenshot-table-cell-image-v11.3.png)
It has the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Alt text | Set the alternative text of an image. The text will be available for screen readers and in cases when images can't be loaded. |
| Title text | Set the text that's displayed when the image is hovered over with a cursor. |
| Tooltip from field | Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip. For more information, refer to [Tooltip from field](#tooltip-from-field). |
<!-- prettier-ignore-end -->
#### Actions
The cell displays a button that triggers a basic, unauthenticated API call when clicked.
Configure the API call with the following options:
<!-- prettier-ignore-start -->
| Option | Description |
| ------------------ | ------------ |
| Endpoint | Enter the endpoint URL. |
| Method | Choose from **GET**, **POST**, and **PUT**. |
| Content-Type | Select an option in the drop-down list. Choose from: JSON, Text, JavaScript, HTML, XML, and x-www-form-urlencoded. |
| Query parameters | Enter as many **Key**, **Value** pairs as you need. |
| Header parameters | Enter as many **Key**, **Value** pairs as you need. |
| Payload | Enter the body of the API call. |
| Tooltip from field | Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip. For more information, refer to [Tooltip from field](#tooltip-from-field). |
<!-- prettier-ignore-end -->
#### Tooltip from field
Toggle on the **Tooltip from field** switch to use the values from another field (or column) in a tooltip.
When you toggle the switch on, you can select from a drop-down list any of the fields in the table to be used as the source of the tooltip content.
All table fields are included in the drop-down list, whether visible or hidden.
When a tooltip from a field has been added to a cell, a chip is displayed in the top-right or top-left corner of the cell:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-tooltip-chip-1-v12.2.png" max-width="500px" alt="Tooltip chip" >}}
Hover your mouse over the chip to display the tooltip.
When you toggle on the switch, the **Tooltip placement** option, which controls where the tooltip box opens upon hover, is also displayed.
Select one of the following options: **Auto**, **Top**, **Right**, **Bottom**, and **Left**.
The content of the tooltip is determined by the values of the source field and can't be directly edited.
However, you can affect the display of the value using overrides like value mappings, as shown in the [Example: Tooltip from field with value mappings](#example-tooltip-from-field-with-value-mappings) section.
While you can turn on this option under **Cell options**, and have it applied to all cells in the table, it's typically used as an override on a sub-set of cells instead.
This is demonstrated in the example in the following section.
##### Example: Tooltip from field using overrides
The following table has five visible fields (columns) as well as a hidden field called "Info":
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-tooltip-table-1-v12.2.png" max-width="750px" alt="Table that includes a hidden column" >}}
- The "Info" field is hidden using the **Table > Hide in table** override property.
- The following overrides have been applied to the "Short text" field:
- The values from the "Info" field are used as tooltip text for the "Short text" cells using the **Cell options > Tooltip from field** override property.
- The **Cell options > Tooltip placement** override property is set to control the placement of the tooltip.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-tooltip-override-2-v12.2.png" max-width="300px" alt="Override to use the Info field values as tooltips for the Short text column" >}}
Now, when you hover the cursor over the chip in the "Short text" column, the corresponding values from the "Info" column appear in the tooltip:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-tooltip-on-hover-v12.2.png" max-width="750px" alt="Info field value in the tooltip of the Short text cell upon hover" >}}
##### Example: Tooltip from field with value mappings
While the content of the tooltip is determined by the values of the source field and can't be directly edited, you can use field overrides on the source field to manipulate the display of that value.
For example, if the "Info" column is being used as the source field for the tooltip values, you could set up a value mapping.
In this case, the value "up" is mapped to the word "Good":
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-tooltip-value-map-v12.2.png" max-width="750px" alt="Info field value up being mapped to the value Good in an override" >}}
Now, when you hover the cursor over the chip in the "Short text" cell, the mapped value appears in the tooltip:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-tooltip-on-hover-2-v12.2.png" max-width="750px" alt="Info field mapped to a new value in the tooltip of the Short text cell upon hover" >}}
You can use all field overrides to affect the display of the tooltip.
For example, the **Table > Column width** or **Cell options > Cell type** overrides can change the cell width or visual display of the data.
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-3.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/text/index.md
+72
View File
@@ -0,0 +1,72 @@
---
aliases:
- ../../../features/panels/text/ # /docs/grafana/next/features/panels/text/
- ../../../panels-visualizations/visualizations/text/ # /docs/grafana/next/panels-visualizations/visualizations/text/
- ../../../panels/visualizations/text-panel/ # /docs/grafana/next/panels/visualizations/text-panel/
- ../../../reference/alertlist/ # /docs/grafana/next/reference/alertlist/
- ../../../visualizations/text-panel/ # /docs/grafana/next/visualizations/text-panel/
keywords:
- grafana
- text
- documentation
- panel
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's text visualization
title: Text
weight: 100
refs:
disable-sanitize-html:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#disable_sanitize_html
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#disable_sanitize_html
variables:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/variable-syntax/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/variable-syntax/
---
# Text
Text visualizations let you include text or HTML in your dashboards.
This can be used to add contextual information and descriptions or embed complex HTML.
For example, if you want to display important links on your dashboard, you can use a text visualization to add these links:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-text-visualization-v11.6.png" max-width="750px" alt="A text panel showing important links" >}}
{{< docs/play title="Text Panel" url="https://play.grafana.org/d/adl33bxy1ih34b/" >}}
Use a text visualization when you need to:
- Add important links or useful annotations.
- Provide instructions or guidance on how to interpret different panels, configure settings, or take specific actions based on the displayed data.
- Announce any scheduled maintenance or downtime that might impact your dashboards.
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Text options
Use the following options to refine your text visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Mode | Determines how embedded content appears. Choose from:<ul><li>**Markdown** - Formats the content as [markdown](https://en.wikipedia.org/wiki/Markdown).</li><li>**HTML** - Renders the content as [sanitized](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/text/sanitize.ts) HTML. If you require more direct control over the output, you can set the [disable_sanitize_html](ref:disable-sanitize-html) flag which enables you to directly enter HTML.</li><li>**Code** - Renders content inside a read-only code editor. [Variables](ref:variables) in the content are expanded for display.</li></ul><p>To allow embedding of iframes and other websites, you need set `allow_embedding = true` in your Grafana `config.ini` or environment variables (depending on your employment).</p> |
| Language | When you choose **Code** as your text mode, select an appropriate language to apply syntax highlighting to the embedded text. |
| Show line numbers | Displays line numbers in the panel preview when you choose **Code** as your text mode. |
| Show mini map | Displays a small outline of the embedded text in the panel preview when you choose **Code** as your text mode. |
<!-- prettier-ignore-end -->
docs/sources/visualizations/panels-visualizations/visualizations/time-series/index.md
+214
View File
@@ -0,0 +1,214 @@
---
aliases:
- ../../../features/panels/histogram/ # /docs/grafana/next/features/panels/histogram/
- ../../../panels/visualizations/time-series/ # /docs/grafana/next/panels/visualizations/time-series/
- ../../../panels/visualizations/time-series/annotate-time-series/ # /docs/grafana/next/panels/visualizations/time-series/annotate-time-series/
- ../../../panels/visualizations/time-series/change-axis-display/ # /docs/grafana/next/panels/visualizations/time-series/change-axis-display/
- ../../../panels/visualizations/time-series/graph-color-scheme/ # /docs/grafana/next/panels/visualizations/time-series/graph-color-scheme/
- ../../../panels/visualizations/time-series/graph-time-series-as-bars/ # /docs/grafana/next/panels/visualizations/time-series/graph-time-series-as-bars/
- ../../../panels/visualizations/time-series/graph-time-series-as-lines/ # /docs/grafana/next/panels/visualizations/time-series/graph-time-series-as-lines/
- ../../../panels/visualizations/time-series/graph-time-series-as-points/ # /docs/grafana/next/panels/visualizations/time-series/graph-time-series-as-points/
- ../../../panels/visualizations/time-series/graph-time-series-stacking/ # /docs/grafana/next/panels/visualizations/time-series/graph-time-series-stacking/
- ../../time-series/ # /docs/grafana/next/visualizations/time-series/
- ../../time-series/annotate-time-series/ # /docs/grafana/next/visualizations/time-series/annotate-time-series/
- ../../time-series/change-axis-display/ # /docs/grafana/next/visualizations/time-series/change-axis-display/
- ../../time-series/graph-color-scheme/ # /docs/grafana/next/visualizations/time-series/graph-color-scheme/
- ../../time-series/graph-time-series-as-bars/ # /docs/grafana/next/visualizations/time-series/graph-time-series-as-bars/
- ../../time-series/graph-time-series-as-lines/ # /docs/grafana/next/visualizations/time-series/graph-time-series-as-lines/
- ../../time-series/graph-time-series-as-points/ # /docs/grafana/next/visualizations/time-series/graph-time-series-as-points/
- ../../time-series/graph-time-series-stacking/ # /docs/grafana/next/visualizations/time-series/graph-time-series-stacking/
- ../../../panels-visualizations/visualizations/time-series/ # /docs/grafana/next/panels-visualizations/visualizations/time-series/
keywords:
- grafana
- graph panel
- time series panel
- documentation
- guide
- graph
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's time series visualization
title: Time series
menuTitle: Time series
weight: 10
refs:
link-alert:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/alerting-rules/create-grafana-managed-rule/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-grafana-managed-rule/
panel-data-section:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/panel-editor-overview/#data-section
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/panel-editor-overview/#data-section
---
# Time series
Time series visualizations are the default way to show the variations of a set of data values over time. Each data point is matched to a timestamp and this _time series_ is displayed as a graph. The visualization can render series as lines, points, or bars and it's versatile enough to display almost any type of [time-series data](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/fundamentals/timeseries/).
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-time-series-v12.0.png" max-width="750px" alt="Time series visualization" >}}
{{< admonition type="note" >}}
You can migrate from the legacy Graph visualization to the time series visualization. To migrate, open the panel and click the **Migrate** button in the side pane.
{{< /admonition >}}
A time series visualization displays an x-y graph with time progression on the x-axis and the magnitude of the values on the y-axis. This visualization is ideal for displaying large numbers of timed data points that would be hard to track in a table or list.
You can use the time series visualization if you need track:
- Temperature variations throughout the day
- The daily progress of your retirement account
- The distance you jog each day over the course of a year
## Configure a time series visualization
The following video guides you through the creation steps and common customizations of time series visualizations, and is great for beginners:
{{< youtube id="RKtW87cPxsw" >}}
{{< docs/play title="Time Series Visualizations in Grafana" url="https://play.grafana.org/d/000000016/" >}}
## Supported data formats
Time series visualizations require time-series data—a sequence of measurements, ordered in time, and formatted as a table—where every row in the table represents one individual measurement at a specific time. Learn more about [time-series data](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/fundamentals/timeseries/).
The dataset must contain at least one numeric field, and in the case of multiple numeric fields, each one is plotted as a new line, point, or bar labeled with the field name in the tooltip.
### Example 1
In the following example, there are three numeric fields represented by three lines in the chart:
| Time | value1 | value2 | value3 |
| ------------------- | ------ | ------ | ------ |
| 2022-11-01 10:00:00 | 1 | 2 | 3 |
| 2022-11-01 11:00:00 | 4 | 5 | 6 |
| 2022-11-01 12:00:00 | 7 | 8 | 9 |
| 2022-11-01 13:00:00 | 4 | 5 | 6 |
![Time series line chart with multiple numeric fields](/media/docs/grafana/panels-visualizations/screenshot-grafana-11.1-timeseries-example1v2.png 'Time series line chart with multiple numeric fields')
If the time field isn't automatically detected, you might need to convert the data to a time format using a [data transformation](ref:panel-data-section).
### Example 2
The time series visualization also supports multiple datasets. If all datasets are in the correct format, the visualization plots the numeric fields of all datasets and labels them using the column name of the field.
#### Query1
| Time | value1 | value2 | value3 |
| ------------------- | ------ | ------ | ------ |
| 2022-11-01 10:00:00 | 1 | 2 | 3 |
| 2022-11-01 11:00:00 | 4 | 5 | 6 |
| 2022-11-01 12:00:00 | 7 | 8 | 9 |
#### Query2
| timestamp | number1 | number2 | number3 |
| ------------------- | ------- | ------- | ------- |
| 2022-11-01 10:30:00 | 11 | 12 | 13 |
| 2022-11-01 11:30:00 | 14 | 15 | 16 |
| 2022-11-01 12:30:00 | 17 | 18 | 19 |
| 2022-11-01 13:30:00 | 14 | 15 | 16 |
![Time series line chart with two datasets](/media/docs/grafana/panels-visualizations/screenshot-grafana-11.1-timeseries-example2v2.png 'Time series line chart with two datasets')
### Example 3
If you want to more easily compare events between different, but overlapping, time frames, you can do this by using a time offset while querying the compared dataset:
#### Query1
| Time | value1 | value2 | value3 |
| ------------------- | ------ | ------ | ------ |
| 2022-11-01 10:00:00 | 1 | 2 | 3 |
| 2022-11-01 11:00:00 | 4 | 5 | 6 |
| 2022-11-01 12:00:00 | 7 | 8 | 9 |
#### Query2
| timestamp(-30min) | number1 | number2 | number3 |
| ------------------- | ------- | ------- | ------- |
| 2022-11-01 10:30:00 | 11 | 12 | 13 |
| 2022-11-01 11:30:00 | 14 | 15 | 16 |
| 2022-11-01 12:30:00 | 17 | 18 | 19 |
| 2022-11-01 13:30:00 | 14 | 15 | 16 |
![Time Series Example with second Data Set offset](/media/docs/grafana/panels-visualizations/screenshot-grafana-11.1-timeseries-example3v2.png 'Time Series Example with second Data Set offset')
When you add the offset, the resulting visualization makes the datasets appear to be occurring at the same time so that you can compare them more easily.
## Alert rules
You can [link alert rules](ref:link-alert) to time series visualizations in the form of annotations to observe when alerts fire and are resolved. In addition, you can create alert rules from the **Alert** tab within the [panel editor](ref:panel-data-section).
## Special overrides
The following overrides help you further refine a time series visualization.
### Transform override property
Use the **Graph styles > Transform** [override property](#field-overrides) to transform series values without affecting the values shown in the tooltip, context menu, or legend. Choose from the following transform options:
- **Constant** - Show the first value as a constant line.
- **Negative Y transform** - Flip the results to negative values on the y-axis.
### Fill below to override property
The **Graph styles > Fill below to** [override property](#field-overrides) fills the area between two series. When you configure the property, select the series for which you want the fill to stop.
The following example shows three series: Min, Max, and Value. The Min and Max series have **Line width** set to 0. Max has a **Fill below to** override set to Min, which fills the area between Max and Min with the Max line color.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-fill-below-to-v12.0.png" max-width="600px" alt="Fill below to example" >}}
{{< docs/shared lookup="visualizations/multiple-y-axes.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+2" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Tooltip options
{{< docs/shared lookup="visualizations/tooltip-options-2.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1">}}
### Legend options
{{< docs/shared lookup="visualizations/legend-options-1.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Axis options
{{< docs/shared lookup="visualizations/axis-options-1.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Graph styles options
The options under the **Graph styles** section let you control the general appearance of the graph, excluding [color](#standard-options).
{{< docs/shared lookup="visualizations/graph-styles-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/traces/index.md
+197
View File
@@ -0,0 +1,197 @@
---
aliases:
- ../../traces/ # /docs/grafana/next/visualizations/traces/
- ../../../panels-visualizations/visualizations/traces/ # /docs/grafana/next/panels-visualizations/visualizations/traces/
keywords:
- grafana
- dashboard
- documentation
- panels
- traces
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's traces visualization
title: Traces
weight: 100
refs:
variables-documentation:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/variables/
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
tracing-in-explore:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/explore/trace-integration/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/explore/trace-integration/
panel-editor-documentation:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/panel-editor-overview/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/panel-editor-overview/
tempo-data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/tempo/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/tempo/
configure-panel-options-documentation:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-panel-options/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-panel-options/
---
# Traces
{{< shared id="traces-viz" >}}
Traces visualizations let you follow a request as it traverses the services in your infrastructure.
The traces visualization displays traces data in a diagram that allows you to easily interpret it. Traces visualizations currently render one trace traversal based on the traceID used in TraceQL or using a variable.
{{< /shared >}}
For more information about traces and how to use them, refer to the following documentation:
- [Tracing in Explore](ref:tracing-in-explore)
- [Tempo data source](ref:tempo-data-source)
- [Getting started with Tempo](/docs/tempo/latest/getting-started)
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-traces-visualization-11.5.png" max-width= "700px" alt="Screenshot of the trace view" >}}
{{< docs/play title="Traces Panel" url="https://play.grafana.org/d/edodkfmj0tce8f/" >}}
## Add a panel with tracing visualizations
Once you have tracing data available in your Grafana stack, you can add tracing panels to your Grafana dashboards.
Using a dashboard variable, `traceID`, lets you create a query to show specific traces for a given trace ID.
For more information about dashboard variables, refer to the [Variables documentation](ref:variables-documentation).
### Before you begin
To use this procedure, you need:
- A Grafana instance
- A [Tempo data source](ref:tempo-data-source) connected to your Grafana instance
### Steps {#add-the-traces-panel-query}
To view and analyze traces data in a dashboard, you need to add the traces visualization to your dashboard and define a query using the panel editor.
The query determines the data that is displayed in the visualization.
For more information on the panel editor, refer to the [Panel editor documentation](ref:panel-editor-documentation).
This procedure uses dashboard variables and templates to allow you to enter trace IDs which can then be visualized. You'll use a variable called `traceId` and add it as a template query.
1. From your Grafana stack, create a new dashboard or go to an existing dashboard where you'd like to add traces visualizations.
1. Do one of the following:
- New dashboard - Click **+ Add visualization**.
- Existing dashboard - Click **Edit** in the top-right corner and then select **Visualization** in the **Add** drop-down.
1. Search for and select the appropriate tracing data source.
1. In the top-right corner of the panel editor, select the **Visualizations** tab, search for, and select **Traces**.
1. Under the **Panel options**, enter a **Title** for your trace panel or have Grafana create one using [generative AI features](ref:generative-ai-features).
For more information on the panel editor, refer to the [Configure panel options documentation](ref:configure-panel-options-documentation).
1. In the query editor, click the **TraceQL** query type tab.
1. Enter `${traceId}` in the TraceQL query field to create a dashboard variable. This variable is used as the template query.
{{< figure src="/static/img/docs/panels/traces/screenshot-traces-template-query.png" alt="Add a template query" >}}
1. Click **Back to dashboard**.
1. Click **Settings** and go to the **Variables** tab.
1. Add a new variable called `traceId`, of variable type **Custom**, giving it a label if required.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-traces-custom-variable-v11.5.png" max-width="400px" alt="Add a template query" >}}
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
1. Verify that the panel works by using a valid trace ID for the data source used for the trace panel and editing the ID in the dashboard variable.
{{< figure src="/static/img/docs/panels/traces/screenshot-traces-traceid-panel.png" alt="Results of query in trace panel" >}}
## Add TraceQL with table visualizations
While you can add a trace visualization to a dashboard, having to manually add trace IDs as a dashboard variable is cumbersome.
It’s more useful to instead be able to use TraceQL queries to search for specific types of traces and then select appropriate traces from matching results.
1. In the same dashboard where you added the trace visualization, click **Edit** in the top-right corner.
1. In the **Add** drop-down, select **Visualization**.
1. Select the same trace data source you used in the previous section.
1. In the top-right corner of the panel editor, select the **Visualizations** tab, search for, and select **Table**.
1. In the query editor, select the **TraceQL** tab.
1. Under the **Panel options**, enter a **Title** for your trace panel or have Grafana create one using [generative AI features](ref:generative-ai-features).
1. Add an appropriate TraceQL query to search for traces that you would like to visualize in the dashboard. This example uses a simple, static query. You can write the TraceQL query as a template query to take advantage of other dashboard variables, if they exist. This lets you create dynamic queries based on these variables.
{{< figure src="/static/img/docs/panels/traces/screenshot-traces-dynamic-query.png" alt="Create a dynamic query" >}}
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
When results are returned from a query, the results are rendered in the panel’s table.
{{< figure src="/static/img/docs/panels/traces/screenshot-traces-returned-query.png" alt="Results of a returned query in the panel table" >}}
### Use a variable to add other links to traces
The results in the traces visualization include links to the **Explore** page that renders the trace. You can add other links to traces in the table that fill in the `traceId` dashboard variable when selected, so that the trace is visualized in the same dashboard.
To create a set of data links in the panel, use the following steps:
1. In the panel editor menu, under **Data links**, click **Add link**.
1. Add a **Title** for the data link.
1. Find the UUID of the dashboard by looking in your browser’s address bar when the full dashboard is being rendered. Because this is a link to a dashboard in the same Grafana stack, only the path of the dashboard is required.
{{< figure src="/static/img/docs/panels/traces/screensnot-traces-uuid-url.png" alt="Unique identifier for the dashboard" >}}
1. In the **URL** field, make a self-reference to the dashboard that contains both of the panels. This self-reference uses the value of the selected trace in the table to fill in the dashboard variable. Use the path for the dashboard from the previous step and then fill in the value of `traceId` using the selected results from the TraceQL table.
The trace ID is exposed using the `traceID` data field in the returned results, so use that as the value for the dashboard variable.
{{< figure src="/static/img/docs/panels/traces/screenshot-traces-edit-link.png" alt="Edit link and add the Trace link" >}}
1. Select **Save** to save the data link.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
You should now see a list of matching traces in the table visualization. While selecting the **TraceID** or **SpanID** fields will give you the option to either open the **Explore** page to visualize the trace or following the data link, selecting any other field (such as **Start time**, **Name** or **Duration**) automatically follows the data link, filling in the `traceId` dashboard variable, and then shows the relevant trace in the trace panel.
{{< figure src="/static/img/docs/panels/traces/screenshot-traces-trace-link.png" alt="Selecting the trace link" >}}
{{< figure src="/static/img/docs/panels/traces/screenshot-traces-trace-link-follow.png" caption="Follow the trace link populates the trace ID and displays the traces view" >}}
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Span filters options
The **Span filters** options control the initial state of the span filters when the visualization loads, allowing you to customize your trace analysis view.
The following options support variable interpolation, where you can set the service name to a variable `$var` and the visualization will replace it with the value for the variable named `$var` in the span filters: **Service name**, **Span name**, **Min duration**, **Max duration**, and **Tags**.
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Find in trace | Set the initial value to focus on spans relevant to your query. |
| Show matches only | Toggle the switch on to display only spans that match the defined filter criteria. This helps simplify trace interpretation. |
| Show critical path only | Toggle the switch on to highlight only the spans in the critical path, which helps identify performance bottlenecks and their impact on overall latency. |
| Service name | Along with the **Service name operator**, define a specific service or pattern to narrow analysis to spans related to particular services. |
| Span name | Along with the **Span name operator**, filter spans by name or pattern to focus on specific span types or processes. |
| Min duration | Set the minimum duration threshold to exclude spans outside the desired time range. |
| Max duration | Set the maximum duration threshold to exclude spans outside the desired time range. |
| Tags | Add one or more tags to further refine the filtering criteria so only relevant spans are displayed. |
<!-- prettier-ignore-end -->
docs/sources/visualizations/panels-visualizations/visualizations/trend/index.md
+91
View File
@@ -0,0 +1,91 @@
---
keywords:
- grafana
- graph panel
- trend panel
- documentation
- guide
- graph
- line chart
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's trend visualization
title: Trend
weight: 100
refs:
time-series-visualization:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/time-series/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/time-series/
aliases:
- ../../../panels-visualizations/visualizations/trend/ # /docs/grafana/next/panels-visualizations/visualizations/trend/
---
# Trend
Trend visualizations should be used for datasets that have a sequential, numeric x-field that is not time. Some examples are function graphs, rpm/torque curves, supply/demand relationships, and elevation or heart rate plots along a race course (with x as distance or duration from start).
For example, you could represent engine power and torque versus speed where speed is plotted on the x-axis and power and torque are plotted on the y-axes:
{{< figure src="/media/docs/grafana/screenshot-trend-visualization-v12.0.png" max-width="750px" alt="Trend engine power and torque curves" >}}
Trend visualizations support all visual styles and options available in the [time series visualization](ref:time-series-visualization) with these exceptions:
- No annotations or time regions
- No shared cursor/crosshair
- No multi-timezone x-axis
- No ability to change the dashboard time range using drag-selection
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### X axis options
In the **X field** option, select a field that contains increasing numeric values.
### Tooltip options
{{< docs/shared lookup="visualizations/tooltip-options-2.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Legend options
{{< docs/shared lookup="visualizations/legend-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Graph styles options
The options under the **Graph styles** section let you control the general appearance of the graph, excluding [color](#standard-options).
{{< docs/shared lookup="visualizations/graph-styles-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Axis options
{{< docs/shared lookup="visualizations/axis-options-2.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+1" >}}
### Standard options
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/panels-visualizations/visualizations/xy-chart/index.md
+217
View File
@@ -0,0 +1,217 @@
---
canonical: https://grafana.com/docs/grafana/latest/panels-visualizations/visualizations/xy-chart/
keywords:
- grafana
- chart
- xy chart
- documentation
- guide
- graph
labels:
products:
- cloud
- enterprise
- oss
description: Configure options for Grafana's xy chart
title: XY chart
weight: 100
refs:
configure-standard-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/#max
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/#max
color-scheme:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/configure-standard-options/#color-scheme
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options/#color-scheme
configure-field-overrides:
- 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:
- ../../../panels-visualizations/visualizations/xy-chart/ # /docs/grafana/next/panels-visualizations/visualizations/xy-chart/
---
# XY chart
XY charts provide a way to visualize arbitrary x and y values in a graph so that you can easily show the relationship between two variables. XY charts are typically used to create scatter plots. You can also use them to create bubble charts where field values determine the size of each bubble:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-xy-charts-v11.6.png" max-width="750px" alt="An xy chart showing height weight distribution" >}}
## Supported data formats
You can use any type of tabular data with at least two numeric fields in an xy chart. The x field can be a time field. This type of visualization doesn't require time data, but it can be used.
## Configuration options
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### XY Chart options
The following options let you control how data is displayed in an xy chart:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| [Series mapping](#series-mapping) | Set how series data is mapped in the chart. Choose from: **Auto** and **Manual**. Depending on your series mapping selection, the **Frame**, **X-field**, and **Y-field** options differ. For information on setting these specific fields, refer to the [Series mapping section](#series-mapping). |
| Size field | Set which field's values control the size of the points in the chart. This value is relative to the min and max of all the values in the data frame. When you select this option, you can then set the **Min point size** and **Max point size** options. Required in **Manual** mode. |
| Color field | Set which field's values control the color of the points in the chart. To use the color value options under the **Standard** options, you must set this field. Typically, this field is used when you only have one series displayed in the chart. Required in **Manual** mode. |
| [Show](#show) | Set how values are represented in the visualization. Choose from: **Points**, **Lines**, or **Both**. |
| Point size | Set the size of all points in the chart, from one to one hundred pixels in diameter. The default size is five pixels. You can set an [override](ref:configure-field-overrides) to set the pixel size by series (y-field). |
| Min/Max point size | Use these options to control the minimum or maximum point size when you've set the **Size field** option. You can [override](ref:configure-field-overrides) these options for specific series. |
| Point shape | Set the shape of the points in the chart. Choose from:<ul><li>**Circle** - The default setting</li><li>**Square** </li></ul> |
| Point stroke width | The width of the point stroke in pixels. The default is one pixel. |
| Fill opacity | The opacity of the point fill. The default is 50. |
| [Line style](#line-style) | Set the style of the lines that connect points. Choose from: **Solid**, **Dash**, or **Dots**. |
| Line width | The width of the lines that connect points, in pixels. |
<!-- prettier-ignore-end -->
#### Series mapping
Set how series data is mapped in the chart. Choose from:
- **Auto** - Automatically generates series from all available data frames (or datasets). You can filter to select only one frame.
- **Manual** - Explicitly define the series by selecting from available data frames.
Depending on your series mapping selection, the **Frame**, **X-field**, and **Y-field** options differ.
These options are described in the tabs that follow:
{{< tabs >}}
{{< tab-content name="Auto series mapping options" >}}
When you select **Auto** as your series mapping mode, the following options are preconfigured, but you can also define them yourself:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Frame | By default, an xy chart displays all data frames. You can filter to select only one frame. |
| [X field](#x-field) | Select which field or fields x represents. By default, this is the first number or time field in each data frame. For an example of this in **Auto** mode, refer to the [X field section](#x-field). |
| [Y field](#y-field) | After the x-field is set, by default, all the remaining number fields in the data frame are designated as the y-fields. You can use this option to explicitly choose which fields to use for y. For more information on how to use this in **Auto** mode, refer to the [Y field section](#y-field). |
<!-- prettier-ignore-end -->
{{< /tab-content >}}
{{< tab-content name="Manual series mapping options" >}}
When you select **Manual** as your series mode, you can add, edit, and delete series.
To manage a series, click the **Series** field; to rename the series, click the series name.
In **Manual** mode, these fields are required:
<!-- prettier-ignore-start -->
| Option | Description |
| ------ | ----------- |
| Frame | Select your data frame or dataset. You can add as many frames as you want. |
| X field | Select which field x represents. |
| Y field | Select which field y represents. |
<!-- prettier-ignore-end -->
{{< /tab-content >}}
{{< /tabs >}}
#### X field
In **Auto** series mapping mode, select which field or fields x represents. By default, this is the first number or time field in each data frame. For example, you enter the following CSV content:
| a | b | c |
| --- | --- | --- |
| 0 | 0 | 0 |
| 1 | 1 | 9 |
| 2 | 2 | 4 |
In the resulting chart, the x-field is generated from the values in column "a" unless you define it differently.
#### Y field
In **Auto** series mapping mode, after the x-field is set, by default, all the remaining number fields in the data frame are designated as the y-fields.
You can use this option to explicitly choose which fields to use for y.
The series of the chart are generated from the y-fields.
To make changes to a series in an xy chart, make [overrides](ref:configure-field-overrides) to the y-field.
{{< admonition type=note >}}
Any field you use in the **Size field** or **Color field** doesn't generate a series.
{{< /admonition >}}
You can also use [overrides](ref:configure-field-overrides) to exclude y-fields individually.
To do so, add an override with the following properties for each y-field you want removed:
- Override type: **Fields with name**
- Override property: **Series > Hide in area**
- Area: **Viz**
#### Show
Set how values are represented in the visualization. Choose from:
- **Points** - Display values as points. When you select this option, the **Point size** option is also displayed.
- **Lines** - Add a line between values. When you select this option, the [Line style](#line-style) and **Line width** options are also displayed.
- **Both** - Display both points and lines.
#### Line style
Set the style of the lines that connect points. To change the color, use the standard [Color scheme](ref:color-scheme) field option.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-line-style-options-v11.6.png" max-width="400px" alt="Line style options" >}}
- **Solid** - Display a solid line. This is the default setting.
- **Dash** - Display a dashed line. When you choose this option, a drop-down list is displayed where you can select the length and gap setting for the line dashes. By default, the length and gap are set to `10, 10`.
- **Dots** - Display dotted lines. When you choose this option, a drop-down list is displayed where you can select dot spacing. By default, the dot spacing is set to `0, 10` (the first number represents dot length, which is always zero).
### Tooltip options
Tooltip options control the information overlay that appears when you hover over data points in the visualization.
<!-- prettier-ignore-start -->
| Option | Description |
| ------------ | ----------- |
| Tooltip mode | When you hover your cursor over the visualization, Grafana can display tooltips. Choose how they behave:<ul><li>**Single** - The hover tooltip shows only a single series, the one that you are hovering over on the visualization.</li><li>**Hidden** - Do not display the tooltip when you interact with the visualization.</li></ul> |
| Max width | Set the maximum width of the tooltip box. |
<!-- prettier-ignore-end -->
### Legend options
{{< docs/shared lookup="visualizations/legend-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Axis options
{{< docs/shared lookup="visualizations/axis-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Standard options
**Standard options** in the panel editor pane let you change how field data is displayed in your visualizations. When you set a standard option, the change is applied to all fields or series. For more granular control over the display of fields, refer to [Configure field overrides](ref:configure-field-overrides).
You can customize the following standard options:
- **Field min/max** - Enable **Field min/max** to have Grafana calculate the min or max of each field individually, based on the minimum or maximum value of the field.
- **Color scheme** - Set single or multiple colors for your entire visualization. To learn more about color schemes, refer to [Configure standard options](ref:configure-standard-options).
### Data links and actions
{{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Value mappings
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Thresholds
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
### Field overrides
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
docs/sources/visualizations/simplified-exploration/_index.md
+55
View File
@@ -0,0 +1,55 @@
---
description: Use your telemetry data to explore and determine the root cause of issues without performing queries.
keywords:
- Simplified exploration
- queryless
- Explore apps
- Drilldown apps
title: Drilldown
menuTitle: Drilldown
weight: 100
hero:
title: Simplified exploration with the Drilldown apps
level: 1
width: 100
height: 100
description: Use the Grafana Drilldown apps to investigate and identify issues using telemetry data.
cards:
title_class: pt-0 lh-1
items:
- title: Grafana Metrics Drilldown
href: ./metrics/
description: Quickly find related metrics with a few clicks, without needing to write PromQL queries to retrieve metrics.
height: 24
- title: Grafana Logs Drilldown
href: ./logs/
description: Visualize log volumes to easily detect anomalies or significant changes over time, without needing to compose LogQL queries.
height: 24
- title: Grafana Traces Drilldown
href: ./traces/
description: Use Rate, Errors, and Duration (RED) metrics derived from traces to investigate and understand errors and latency issues within complex distributed systems.
height: 24
- title: Grafana Profiles Drilldown
href: ./profiles/
description: View and analyze high-level service performance, identify problem processes for optimization, and diagnose issues to determine root causes.
height: 24
aliases:
- ../explore/simplified-exploration/ # /docs/grafana/next/explore/simplified-exploration/
---
# Drilldown
The Grafana Drilldown apps are designed for effortless data exploration through intuitive, queryless interactions.
Easily explore telemetry signals with these specialized tools, tailored specifically for the Grafana databases to provide quick and accurate insights.
{{< docs/shared source="grafana" lookup="plugins/rename-note.md" version="<GRAFANA_VERSION>" >}}
To learn more, read:
- [From multi-line queries to no-code investigations: meeting Grafana users where they are](https://grafana.com/blog/2024/10/22/from-multi-line-queries-to-no-code-investigations-meeting-grafana-users-where-they-are/)
- [A queryless experience for exploring metrics, logs, traces, and profiles: Introducing the Drilldown apps suite for Grafana](https://grafana.com/blog/2024/09/24/queryless-metrics-logs-traces-profiles/).
{{< youtube id="MSHeWWsHaIA" >}}
{{< card-grid key="cards" type="simple" >}}