1. Click on the trash icon in the annotation tooltip.
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
@ -109,10 +119,11 @@ Check out the video below for a quick tutorial.
### Add new annotation queries
To add a new annotation query to a dashboard, take the following steps:
To add a new annotation query to a dashboard, follow these steps:
1. Click the dashboard settings (gear) icon in the dashboard header to open the settings menu.
1. Select **Annotations**.
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.
@ -140,6 +151,9 @@ To add a new annotation query to a dashboard, take the following steps:
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 will still be visible. This is due to the built-in annotation query that exists on all dashboards. This annotation query will fetch 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.
@ -150,8 +164,9 @@ 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 the dashboard settings (gear) icon in the dashboard header to open the dashboard settings menu.
1. Click **Annotations**.
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.
@ -162,6 +177,8 @@ You can stop annotations from being fetched and drawn by taking the following st
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 will get a new dashboard id, so annotations created on the source dashboard will 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.
@ -95,7 +90,7 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
**To create a dashboard**:
1. Click **Dashboards** in the left-side menu.
1. Click **Dashboards** in the main menu.
1. Click **New** and select **New Dashboard**.
1. On the empty dashboard, click **+ Add visualization**.
@ -104,7 +99,7 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
1. In the dialog box that opens, do one of the following:
- Select one of your existing data sources.
- Select one of the Grafana's [built-in special data sources](ref:built-in-special-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).
{{<figureclass="float-right"src="/media/docs/grafana/dashboards/screenshot-data-source-selector-10.0.png"max-width="800px"alt="Select data source modal">}}
@ -115,14 +110,10 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee
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 the Refresh dashboard icon to query the data source.
- [Configure standard options](ref:configure-standard-options)
1. When you've finished editing your panel, click **Save** to save the dashboard.
1. When you've finished editing your panel, click **Save dashboard**.
Alternatively, click **Apply** if you want to see your changes applied to the dashboard first. Then click the save icon in the dashboard header.
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 **Add** in the dashboard header and select **Visualization** in the drop-down.
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.
When you add additional panels to the dashboard, you're taken straight to the **Edit panel** view.
## Copy an existing dashboard
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 an existing dashboard, follow these steps:
To copy a dashboard, follow these steps:
1. Click **Dashboards** in the primary menu.
1. Open the dashboard to be copied.
1. Click **Settings** (gear icon) in the top right of the dashboard.
1. Click **Save as** in the top-right corner of the dashboard.
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 located in the same folder.
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**.
@ -178,7 +174,7 @@ To see an example of repeating rows, refer to [Dashboard with repeating rows](ht
**To configure repeating rows:**
1. Click **Dashboards** in the left-side menu.
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.
@ -192,7 +188,7 @@ 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](ref:dashboard) data source—the data source that uses a result set from another panel in the same dashboard—then corresponding panels in repeated rows will reference the panel in the original row, not the ones in the repeated rows.
If a row includes panels using the special [Dashboard data source](ref:built-in-special-data-sources)—the data source that uses a result set from another panel in the same dashboard—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:
@ -205,14 +201,24 @@ For example, in a dashboard:
You can place a panel on a dashboard in any location.
1. Click **Dashboards** in the left-side menu.
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 left-side menu.
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.
@ -83,51 +83,64 @@ Once you've added a dashboard link, it appears in the upper right corner of your
Add links to other dashboards at the top of your current dashboard.
1. While viewing the dashboard you want to link, click the gear at the top of the screen to open **Dashboard settings**.
1. Click **Links** and then click **Add Dashboard Link** or **New**.
1. In **Type**, select **dashboards**.
1. Select link options:
- **With tags** – Enter tags to limit the linked dashboards to only the ones with the tags you enter. Otherwise, Grafana includes links to all other dashboards.
- **As dropdown** – If you are linking to lots of dashboards, then you probably want to select this option and add an optional title to the dropdown. Otherwise, Grafana displays the dashboard links side by side across the top of your dashboard.
- **Time range** – Select this option to include the dashboard time range in the link. When the user clicks the link, the linked dashboard opens with the indicated time range already set. **Example:** https://play.grafana.org/d/000000010/annotations?orgId=1&from=now-3h&to=now
- **Variable values** – Select this option to include template variables currently used as query parameters in the link. When the user clicks the link, any matching templates in the linked dashboard are set to the values from the link. For more information, see [Dashboard URL variables](ref:dashboard-url-variables).
- **Open in new tab** – Select this option if you want the dashboard link to open in a new tab or window.
1. Click **Add**.
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. While viewing the dashboard you want to link, click the gear at the top of the screen to open **Dashboard settings**.
1. Click **Links** and then click **Add Dashboard Link** or **New**.
1. In **Type**, select **link**.
1. Select link options:
- **Url** – Enter the URL you want to link to. Depending on the target, you might want to include field values. **Example:** https://github.com/grafana/grafana/issues/new?title=Dashboard%3A%20HTTP%20Requests
- **Title** – Enter the title you want the link to display.
- **Tooltip** – Enter the tooltip you want the link to display when the user hovers their mouse over it.
- **Icon** – Choose the icon you want displayed with the link.
- **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
- `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.
- **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. Here is the variable format: `https://${you-domain}/path/to/your/dashboard?var-${template-variable1}=value1&var-{template-variable2}=value2`**Example:** https://play.grafana.org/d/000000074/alerting?var-app=backend&var-server=backend_01&var-server=backend_03&var-interval=1h
- **Open in new tab** – Select this option if you want the dashboard link to open in a new tab or window.
1. Click **Add**.
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.
### Update a dashboard 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
To change or update an existing dashboard link, follow this procedure.
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:
1. In Dashboard Settings, on the Links tab, click the existing link that you want to edit.
1. Change the settings and then click **Update**.
- **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.
## Duplicate a dashboard link
1. Click **Save dashboard** in the top-right corner.
1. Click **Back to dashboard** and then **Exit edit**.
To duplicate an existing dashboard link, click the duplicate icon next to the existing link that you want to duplicate.
### Update a dashboard link
To edit, duplicate, or delete dashboard link, follow these steps:
### Delete a dashboard link
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:
To delete an existing dashboard link, click the trash icon next to the duplicate icon that you want to delete.
- **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
@ -144,7 +157,7 @@ Click the icon next to the panel title to see available panel links.
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. 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.
@ -152,9 +165,10 @@ Click the icon next to the panel title to see available panel links.
- `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 a new tab**.
1. Click **Save** to save changes and close the window.
1. Click **Save** in the upper right to save your changes to the dashboard.
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
@ -167,8 +181,9 @@ Click the icon next to the panel title to see available 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 window.
1. Click **Save** in the upper right to save your changes to the dashboard.
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
@ -180,4 +195,5 @@ Click the icon next to the panel title to see available panel links.
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** in the upper right to save your changes to the dashboard.
1. Click **Save dashboard** in the top-right corner.
1. Click **Back to dashboard** and then **Exit edit**.
@ -39,52 +39,75 @@ You can control permissions for library panels using [role-based access control
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.
1. Open a panel in edit mode.
1. In the panel display options, click the down arrow option to bring changes to the visualization.
{{<figuresrc="/media/docs/grafana/panels-visualizations/screenshot-create-lib-panel-from-edit-9-5.png"class="docs-image--no-shadow"max-width="800px"alt="Library panels tab of the panel editor pane">}}
1. Click **Library panels**, and then click **+ Create library panel** to open the create dialog.
1. Click **Edit** in the top-right corner of the dashboard.
1. On the panel you want to update, hover over any part of the panel to display the menu icon on the top-right corner.
1. Click the menu icon and select **More > Create library panel**.
1. In **Library panel name**, enter the name.
1. In **Save in folder**, select the folder to save the library panel.
1. Click **Create library panel** to save your changes.
1. Save the dashboard.
1. Click **Create library panel**.
1. Click **Save dashboard** and **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.
You can also create a library panel directly from the edit menu of any panel.
{{<figuresrc="/media/docs/grafana/panels-visualizations/screenshot-create-from-more-9-5.png"class="docs-image--no-shadow"max-width="900px"alt="Create library panel option in the panel menu">}}
## 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.
1. Click **Dashboards** in the left-side menu.
1. Click **Dashboards** in the main menu.
1. Click **New** and select **New Dashboard** in the dropdown.
1. On the empty dashboard, click **+ Import library panel**.
1. On the empty dashboard, click **+ Add library panel**.
You will see a list of your library panels.
You'll see a list of your library panels.
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.
1. Click **Dashboards** in the left-side menu.
1. Click **Dashboards** in the main menu.
1. Click **Library panels**.
1. Select a library panel that is being used in different dashboards.
1. Select the panel you want to unlink.
1. Hover over any part of the panel to display the actions menu on the top right corner.
1. Click the menu and select **Edit**.
1. Click **Unlink** on the top right corner of the page.
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 search for a library panel.
You can view a list of available library panels and see where those panels are being used.
1. Click **Dashboards** in the left-side menu.
1. Click **Dashboards** in the main menu.
1. Click **Library panels**.
You can see a list of previously defined library panels.
@ -94,10 +117,14 @@ You can view a list of available library panels and search for a library panel.
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
Delete a library panel when you no longer need it.
1. Click **Dashboards** in the left-side menu.
1. Click **Dashboards** in the main menu.
1. Click **Library panels**.
1. Click the delete icon next to the library panel name.
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. A list of these versions is available by entering the dashboard settings and then selecting "Versions" in the left side menu.
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:
The dashboard version history feature lets you compare and restore to previously saved dashboard versions.
## Comparing two dashboard versions
## Compare two dashboard versions
To compare two dashboard versions, select the two versions from the list that you wish to compare. Once selected, the "Compare versions" button will become clickable. Click the button to view the diff between the two 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**.
Upon clicking the button, you'll be brought to the diff view. By default, you'll see a textual summary of the changes, like in the image below.
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:
If you want to view the diff of the raw JSON that represents your dashboard, you can do that as well by clicking the expand icon for the View JSON Diff section at the bottom.
## Restore a previously dashboard version
## Restoring to a previously saved dashboard version
To restore to a previously saved dashboard version, follow these steps:
If you need to restore to a previously saved dashboard version, you can do so by either clicking the "Restore" button on the right of a row in the dashboard version list, or by clicking the **Restore to version \<x\>** button appearing in the diff view. Clicking the button will bring up the following popup prompting you to confirm the restoration.
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 restoring to a previous version, a new version will be created containing the same exact data as the previous version, only with a different version number. This is indicated in the "Notes column" for the row in the new dashboard version. This is done simply to ensure your previous dashboard versions are not affected by the change.
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.
@ -44,25 +49,29 @@ The dashboard settings page allows you to:
To access the dashboard setting page:
1. Open a dashboard in edit mode.
1. Click **Dashboard settings** (gear icon) located at the top of the 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 **Dashboard settings** page, click **General**.
1. Navigate to the **Time Options** section.
1. On the **Settings** page, scroll down to the **Time Options** section of the **General** tab.
1. Specify time settings as follows.
- **Timezone:** 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.
- **Timezone:** 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.
- **Local 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.
- **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.
- **Autorefresh:** 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**.
## Add tags
You can add metadata to your dashboards using tags. Tags also give you the ability to filter the list of dashboards.
@ -71,13 +80,16 @@ Tags can be up to 50 characters long, including spaces.
To add tags to a dashboard, follow these steps:
1. On the **Dashboard settings** page, scroll down to the **Tags** section.
1. On the **Settings** page, scroll down to the **Tags** section of the **General** tab.
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. Save the dashboard.
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.
@ -86,10 +98,14 @@ When you're on the **Dashboards** page, any tags you've entered show up under th
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 **Dashboard settings** page, click **Annotations**.
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.
@ -101,33 +117,43 @@ the dashboard. These dropdowns make it easy to change the data being displayed i
For more information about variables, refer to [Variables](ref:variables).
1. On the **Dashboard settings** page, click **Variable** in the left side section menu and then the **Add variable** button.
1. In the **General** section, the name of the variable. This is the name that you will later use in queries.
1. Select a variable **Type**.
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.
> **Note:** The variable type you select impacts which fields you populate on the page.
This is the name that you'll use later in queries.
1. Define the variable and click **Update**.
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 **Dashboard settings** page, click **Links** in the left side section menu and then the **Add link** button.
1. Enter title and in the **Type** field, select **Dashboard** or **Link**.
1. To add a dashboard link:
a. Add an optional tag. Tags are useful creating a dynamic dropdown of dashboards that all have a specific tag.
b. Select any of the dashboard link **Options**.
c. Click **Apply**.
1. To add a link:
a. Add a URL and tooltip text that appears when the user hovers over the link.
b. Select an icon that appears next to the link.
c. Select any of the dashboard link **Options**.
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 **Dashboard settings** page, click **JSON**.
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).
@ -32,34 +32,41 @@ You must have at least Editor role permissions to create and manage playlists.
## Access, share, and control a playlist
Use the information in this section to access existing playlists. Start and control the display of a playlist using one of the five available modes.
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 left-side menu.
1. Click **Playlists** to see a list of existing playlists.
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 five different view modes. View modes determine how the menus and navigation bar appear on the dashboards.
You can start a playlist in six different view modes. View modes determine how the menus and navigation bar appear on the dashboards as well as how panels are sized.
By default, each dashboard is displayed for the amount of time entered in the Interval field, which you set when you create or edit a playlist. After you start a playlist, you can control it with the navbar at the top of the page.
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 [six 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 **Dashboards** in the left-side menu.
1. Click **Playlists** to see a list of existing playlists.
1. Find the playlist you want to start, then click **Start playlist**.
1. In the modal that opens, select one of the five playlist modes available, based on the information in the table below.
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. Once a playlist starts, you can [control](#control-a-playlist) it using the navbar at the top of your screen.
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 [control](#control-a-playlist) it using the navbar at the top of your screen.
| Normal mode | <ul><li>The side menu remains visible.</li></ul><ul><li>The navbar, row, and panel controls appear at the top of the screen.</li></ul> |
| TV mode | <ul><li>The side menu and dashboard submenu (including variable drop-downs and dashboard links) are hidden or removed.</li></ul><ul><li>The navbar, row, and panel controls appear at the top of the screen.</li></ul><ul><li>Enabled automatically after one minute of user inactivity.</li></ul><ul><li>Enable it manually using the `d v` sequence shortcut, or by appending the parameter `?inactive` to the dashboard URL.</li></ul><ul><li>Disable it with any mouse movement or keyboard action.</li></ul> |
| TV mode (with auto fit panels) | <ul><li>The side menu and dashboard submenu (including variable drop-downs and dashboard links) are hidden or removed.</li></ul><ul><li>The navbar, row and panel controls appear at the top of the screen.</li></ul><ul><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul><ul> |
| Kiosk mode | <ul><li>The side menu, navbar, ro and panel controls are completely hidden/removed from view.</li></ul><ul><li>You can enable it manually using the `d v` sequence shortcut after the playlist has started.</li></ul><ul><li>You can disable it manually with the same shortcut.</li></ul> |
| Kiosk mode (with auto fit panels) | <ul><li>The side menu, navbar, row, and panel controls are completely hidden/removed from view.</li></ul><ul><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul> |
| Normal mode | <ul><li>The side menu remains visible.</li></ul><ul><li>The navbar and dashboard controls appear at the top of the screen.</li></ul> |
| Normal mode (with auto fit panels) | <ul><li>The side menu remains visible.</li></ul><ul><li>The navbar and dashboard controls appear at the top of the screen.</li></ul><ul><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul> |
| TV mode | <ul><li>The side menu is hidden or removed.</li></ul><ul><li>The navbar and dashboard controls appear at the top of the screen.</li></ul><ul><li>Enabled automatically after one minute of user inactivity.</li></ul><ul><li>Enable it manually using the `d v` sequence shortcut, or by appending the parameter `?inactive` to the dashboard URL.</li></ul><ul><li>Disable it with any mouse movement or keyboard action.</li></ul> |
| TV mode (with auto fit panels) | <ul><li>The side menu is hidden or removed.</li></ul><ul><li>The navbar and dashboard controls appear at the top of the screen.</li></ul><ul><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul><ul> |
| Kiosk mode | <ul><li>The side menu is hidden or removed.</li></ul><ul><li>The navbar and dashboard controls appear at the top of the screen.</li></ul><ul><li>You can disable or enable it manually using the `d v` sequence shortcut after the playlist has started.</li></ul> |
| Kiosk mode (with auto fit panels) | <ul><li>The side menu is hidden or removed.</li></ul><ul><li>The navbar and dashboard controls appear at the top of the screen.</li></ul><ul><li>You can disable or enable it manually using the `d v` sequence shortcut after the playlist has started.</li></ul><ul><li>Dashboard panels automatically adjust to optimize space on screen.</li></ul> |
### Control a playlist
@ -76,79 +83,50 @@ You can control a playlist in **Normal** or **TV** mode after it's started, usin
## Create a playlist
You can create a playlist to present dashboards in a sequence, with a set order and time interval between dashboards.
1. Click **Dashboards** in the left-side menu.
1. Click **Playlists** to see a list of existing playlists.
1. Click**Newplaylist**. The New playlist page opens.
1. Inthe**Name**text box, enter a descriptive name.
1. In the **Interval** text box, enter a time interval. Grafana displays a particular dashboard for the interval of time specified here before moving on to the next dashboard.
1. In Dashboards, add existing dashboards to the playlist using **Add by title** and **Add by tag** drop-down options. The dashboards you add are listed in a sequential order.
1. If needed:
- Search for a dashboard by its name, a regular expression, or a tag.
- Filter your results by starred status or tags.
1. If needed, rearrange the order of the dashboard you have added using the up and down arrow icon.
1. Optionally, remove a dashboard from the playlist by clicking the x icon beside dashboard.
1. Click **Save**.
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.
## Save a playlist
1. Click **Dashboards** in the main menu.
1. Click **Playlists**.
1. Click**Newplaylist**.
1. Inthe**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.
You can save a playlist and add it to your **Playlists** page, where you can start it. Be sure that all the dashboards you want to appear in your playlist are added when creating or editing the playlist before saving it.
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 **Dashboards** in the left-side menu.
1. Click **Playlists** to see a list of existing playlists.
1. Click on the playlist.
1. Edit the playlist.
1. Ensure that your playlist has a **Name**, **Interval**, and at least one **Dashboard** added to it.
1. Click **Save**.
## Edit or delete a playlist
You can edit a playlist by updating its name, interval time, and by adding, removing, and rearranging the order of dashboards. On the rare occasion when you no longer need a playlist, you can delete it.
## Edit a playlist
### Edit a playlist
You can edit a playlist including adding, removing, and rearranging the order of dashboards.
1. Click **Dashboards** in the left-side menu.
1. Click **Playlists** to see a list of existing playlists.
1. Find the playlist you want to update and click**Editplaylist**.
1. Update the name and time interval, then add or remove dashboards from the playlist using instructions in [Create a playlist](#create-a-playlist).
1. Click **Save** to save your changes.
### Delete a playlist
1. Click **Dashboards** in the left-side menu.
1. Click **Playlists** to see a list of existing playlists.
1. Find the playlist you want to remove.
1. Click **Delete playlist**.
1. Click **Dashboards** in the main menu.
1. Click **Playlists**.
1. Find the playlist you want to update and click**Editplaylist**. Do one or more of the following:
### Rearrange dashboard order
- 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 **Dashboards** in the left-side menu.
1. Click **Playlists** to see a list of existing playlists.
1. Find the playlist you want to update and click**Editplaylist**.
1. Click and drag the dashboards into your desired order.
1. Click **Save** to save your changes.
### Remove a dashboard
1. Click **Dashboards** in the left-side menu.
1. Click **Playlists** to see a list of existing playlists.
1. Find the playlist you want to update and click**Editplaylist**.
1. Click **\[x\]** on the name of the dashboard you want to remove from the playlist.
1. Click **Save** to save your changes.
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 left-side menu.
1. Click **Playlists** to see a list of existing playlists.
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. Click **Copy** next to the **Link URL** to copy it to your clipboard.
1. Paste the URL to your destination.
For example, the URL for the first playlist on the Grafana Play site in Kiosk mode will look like this:
@ -59,9 +59,9 @@ You must have an authorized viewer permission to see an image rendered by a dire
The same permission is also required to view embedded links unless you have anonymous access permission enabled for your Grafana instance.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
As of Grafana 8.0, anonymous access permission is not available in Grafana Cloud.
{{% /admonition %}}
{{</admonition>}}
When you share a panel or dashboard as a snapshot, a snapshot (which is a panel or dashboard at the moment you take the snapshot) is publicly available on the web. Anyone with a link to it can access it. Because snapshots do not require any authorization to view, Grafana removes information related to the account it came from, as well as any sensitive data from the snapshot.
@ -69,13 +69,13 @@ When you share a panel or dashboard as a snapshot, a snapshot (which is a panel
You can share a dashboard as a direct link or as a snapshot. You can also export a dashboard.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you change a dashboard, ensure that you save the changes before sharing.
{{% /admonition %}}
{{</admonition>}}
1. Click **Dashboards** in the left-side menu.
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** button at the top right of the screen.
1. Click **Share** in the top-right corner.
The share dialog opens and shows the Link tab.
@ -108,7 +108,7 @@ If you created a snapshot by mistake, click **Delete snapshot** in the dialog bo
To delete existing snapshots, follow these steps:
1. In the primary menu, click **Dashboards**.
1. Click **Dashboards** in the main menu.
1. Click **Snapshots** to go to the snapshots management page.
1. Click the red **x** next to the snapshot URL that you want to delete.
@ -120,7 +120,7 @@ The dashboard export action creates a Grafana JSON file that contains everything
1. Click **Dashboards** in the main menu.
1. Open the dashboard you want to export.
1. Click the **Share** icon in the top navigation bar.
1. Click **Share** in the top-right corner.
1. Click **Export**.
If you're exporting the dashboard to use in another instance, with different data source UIDs, enable the **Export for sharing externally** switch.
@ -139,12 +139,14 @@ A template variable of the type `Constant` is automatically hidden in the dashbo
You can generate and save PDF files of any dashboard.
> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud/).
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](ref:grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud/).
{{</admonition>}}
1. Click **Dashboards** in the left-side menu.
1. Click **Dashboards** in the main menu.
1. Click the dashboard you want to share.
1. Click the **Share** button at the top right of the screen.
1. On the PDF tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
1. Click **Share** in the top-right corner.
1. On the **PDF** tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
1. Click **Save as PDF** to render the dashboard as a PDF file.
Grafana opens the PDF file in a new window or browser tab.
@ -210,7 +212,7 @@ If you created a snapshot by mistake, click **Delete snapshot** in the dialog bo
To delete existing snapshots, follow these steps:
1. In the primary menu, click **Dashboards**.
1. Click **Dashboards** in the main menu.
1. Click **Snapshots** to go to the snapshots management page.
1. Click the red **x** next to the snapshot URL that you want to delete.
@ -220,7 +222,9 @@ The snapshot is immediately deleted. You may need to clear your browser cache or
You can embed a panel using an iframe on another web site. A viewer must be signed into Grafana to view the graph.
**> Note:** As of Grafana 8.0, anonymous access permission is no longer available for Grafana Cloud.
{{<admonitiontype="note">}}
As of Grafana 8.0, anonymous access permission is no longer available for Grafana Cloud.
{{</admonition>}}
Here is an example of the HTML code:
@ -243,4 +247,4 @@ To create a library panel from the **Share Panel** dialog:
1. In **Library panel name**, enter the name.
1. In **Save in folder**, select the folder in which to save the library panel. By default, the root level is selected.
1. Click **Create library panel** to save your changes.
@ -55,32 +80,30 @@ The dashboard user interface provides a number of features that you can use to c
The following image and descriptions highlight all dashboard features.
{{<figuresrc="/media/docs/grafana/dashboards/screenshot-dashboard-annotated-9-5-0.png"width="700px"alt="An annotated image of a dashboard">}}
- (1) **Grafana home**: Click **Home** in the breadcrumb to be redirected to the home page configured in the Grafana instance.
- (2) **Dashboard title**: When you click the dashboard title, you can search for dashboards contained in the current folder. You can create your own dashboard titles or have Grafana create them for you using [generative AI features](ref:generative-ai-features).
- (3) **Share dashboard or panel**: Use this option to share the current dashboard or panel using a link or snapshot. You can also export the dashboard definition from the share modal.
- (4) **Add**: Use this option to add a panel, dashboard row, or library panel to the current dashboard.
- (5) **Save dashboard**: Click to save changes to your dashboard.
- (6) **Dashboard insights**: Click to view analytics about your dashboard including information about users, activity, query counts. Learn more about [dashboard analytics](ref:dashboard-analytics).
- (7) **Dashboard settings**: Use this option to change dashboard name, folder, and tags and manage variables and annotation queries. Learn more about [dashboard settings](ref:dashboard-settings).
- (8) **Time picker dropdown**: Click to select relative time range options and set custom absolute time ranges.
- You can change the **Timezone** and **fiscal year** settings from the time range controls by clicking the **Change time settings** button.
1. **Grafana home** - Click **Home** in the breadcrumb to go to the home page configured in the Grafana instance.
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. **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. **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. **Share dashboard** - Access several [dashboard sharing](ref:sharing) options.
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. **Kiosk mode** - Click to display the dashboard on a large screen such as a TV or a kiosk. Kiosk mode hides elements such as navigation menus. 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 `Enter` to leave kiosk mode.
1. **Variables** - Use [variables](ref:variables) 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.
- (9) **Zoom out time range**: Click to zoom out the time range. Learn more about how to use [common time range controls](#common-time-range-controls).
- (10) **Refresh dashboard**: Click to immediately trigger queries and refresh dashboard data.
- (11) **Refresh dashboard time interval**: Click to select a dashboard auto refresh time interval.
- (12) **View mode**: Click to display the dashboard on a large screen such as a TV or a kiosk. View mode hides irrelevant information such as navigation menus. Learn more about view mode in our [How to Create Kiosks to Display Dashboards on a TV blog post](https://grafana.com/blog/2019/05/02/grafana-tutorial-how-to-create-kiosks-to-display-dashboards-on-a-tv/).
- (13) **Dashboard panel**: The primary building block of a dashboard is the panel. To add a new panel, dashboard row, or library panel, click **Add panel**.
- Library panels can be shared among many dashboards.
- To move a panel, drag the panel header to another location.
- To resize a panel, click and drag the lower right corner of the panel.
- Use [generative AI features](ref:generative-ai-features) to create panel titles and descriptions.
- (14) **Graph legend**: Change series colors, y-axis and series visibility directly from the legend.
- (15) **Dashboard row**: A dashboard row is a logical divider within a dashboard that groups panels together.
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
@ -147,7 +170,7 @@ Grafana Alerting does not support the following syntaxes at this time:
The dashboard and panel time controls have a common UI.
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`.
@ -102,18 +102,20 @@ The following table lists the types of variables shipped with Grafana.
You must enter general options for any type of variable that you create.
1. Navigate to the dashboard you want to make a variable for and click the **Dashboard settings** (gear) icon at the top of the page.
1. On the **Variables** tab, click **New variable**.
1. Click **Edit** in the top-right corner of the dashboard.
1. Click **Settings**.
1. Go to the **Variables** tab.
1. Click **Add variable**.
1. Enter a **Name** for the variable.
1. In the **Type** list, select **Query**.
1. In the **Select variable type** drop-down, choose**Query**.
1. (Optional) In **Label**, enter the display name of the variable dropdown.
If you don't enter a display name, then the dropdown label is the variable name.
1. Choose a **Hide** option:
- **No selection (blank):** The variable dropdown displays the variable **Name** or **Label** value. This is the default.
- **Label:** The variable dropdown only displays the selected variable value and a down arrow.
- **Variable:** No variable dropdown is displayed on the dashboard.
1. Choose a **Show on dashboard** option:
- **Label and value** - The variable drop-down displays the variable **Name** or **Label** value. This is the default.
- **Value:** The variable drop-down only displays the selected variable value and a down arrow.
- **Nothing:** No variable drop-down is displayed on the dashboard.
## Add a query variable
@ -123,7 +125,9 @@ Query variables are generally only supported for strings. If your query returns
Query expressions can contain references to other variables and in effect create linked variables. Grafana detects this and automatically refreshes a variable when one of its linked variables change.
> **Note:** Query expressions are different for each data source. For more information, refer to the documentation for your [data source](ref:data-source).
{{<admonitiontype="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. In the **Data source** list, select the target data source for the query. For more information about data sources, refer to [Add a data source](ref:add-a-data-source).
@ -141,7 +145,8 @@ Query expressions can contain references to other variables and in effect create
1. In the **Sort** list, select the sort order for values to be displayed in the dropdown list. The default option, **Disabled**, means that the order of options returned by your data source query will be used.
1. (Optional) Enter [Selection Options](#configure-variable-selection-options).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a custom variable
@ -153,7 +158,8 @@ For example, if you have server names or region names that never change, then yo
1. In the **Values separated by comma** list, enter the values for this variable in a comma-separated list. You can include numbers, strings, or key/value pairs separated by a space and a colon. For example, `key1 : value1,key2 : value2`.
1. (Optional) Enter [Selection Options](#configure-variable-selection-options).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a text box variable
@ -164,7 +170,8 @@ For more information about cardinality, refer to [What are cardinality spikes an
1. [Enter general options](#enter-general-options).
1. (Optional) In the **Default value** field, select 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. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a constant variable
@ -177,7 +184,8 @@ Constant variables are useful when you have complex values that you need to incl
1. [Enter general options](#enter-general-options).
1. In the **Value** field, enter the variable value. You can enter letters, numbers, and symbols. You can even use wildcards if you use [raw format](ref:raw-format).
1. In **Preview of values**, Grafana displays the current variable value. Review it to ensure it matches what you expect.
1. Click **Add** to add the variable to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add a data source variable
@ -191,7 +199,8 @@ _Data source_ variables enable you to quickly change the data source for an enti
1. (Optional) In **Instance name filter**, enter a regex filter for which data source instances to choose from in the variable value drop-down list. Leave this field empty to display all instances.
1. (Optional) Enter [Selection Options](#configure-variable-selection-options).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
## Add an interval variable
@ -205,7 +214,8 @@ You can use an interval variable as a parameter to group by time (for InfluxDB),
- **Step count -** Select the number of times the current time range will be 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 will 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 **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Add** to add the variable to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
### Interval variable examples
@ -234,7 +244,8 @@ Not all data sources support ad hoc filters. Examples of those that do include P
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. Click **Add** to add the variable to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
### Create ad hoc filters
@ -395,7 +406,8 @@ Extremely complex linked templated dashboards are possible, 5 or 10 levels deep.
### 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 **Dashboard settings** (gear icon) and then click **Variables**. Both examples are expanded in the following section.
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.
The variables page lets you [add](ref:add) variables and [manage](#manage-variables) existing variables. It also allows you to [inspect](#inspect-variables) variables and identify whether a variable is being referenced (or used) in other variables or dashboard.
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 on the variables page:
You can take the following actions in the **Variables** tab:
**Move:** You can move a variable up or down the list using drag and drop.
- **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.
**Clone:** To clone a variable, click the clone icon from 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_`.
## Inspect variables
**Delete:** To delete a variable, click the trash icon from the set of icons on the right.
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:
## Inspect variables
<!-- 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.
@ -54,6 +56,10 @@ Any variable that is referenced or used has a green check mark next to it, while
In addition, all referenced variables have a dependency icon next to the green check mark. You can click on the icon to view the dependency map. The dependency map can be moved. You can zoom in out with mouse wheel or track pad equivalent.
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.-->
This topic helps you get started with Grafana and build your first dashboard using the built-in `Grafana` data source. To learn more about Grafana, refer to [Introduction to Grafana]({{< relref "../introduction" >}}).
This topic helps you get started with Grafana and build your first dashboard using the built-in `Grafana` data source. To learn more about Grafana, refer to [Introduction to Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/).
{{% admonition type="note" %}}
Grafana also offers a [free account with Grafana Cloud](/signup/cloud/connect-account?pg=gsdocs) to help getting started even easier and faster. You can install Grafana to self-host or get a free Grafana Cloud account.
@ -22,7 +22,7 @@ Grafana also offers a [free account with Grafana Cloud](/signup/cloud/connect-ac
#### Install Grafana
Grafana can be installed on many different operating systems. For a list of the minimum hardware and software requirements, as well as instructions on installing Grafana, refer to [Install Grafana]({{< relref "../setup-grafana/installation" >}}).
Grafana can be installed on many different operating systems. For a list of the minimum hardware and software requirements, as well as instructions on installing Grafana, refer to [Install Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/installation/).
#### Sign in to Grafana
@ -39,18 +39,18 @@ To sign in to Grafana for the first time:
1. Click **OK** on the prompt and change your password.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
We strongly recommend that you change the default administrator password.
{{% /admonition %}}
{{</admonition>}}
#### Create a dashboard
If you've already set up a data source that you know how to query, refer to [Create a dashboard]({{< relref "../dashboards/build-dashboards/create-dashboard" >}}) instead.
If you've already set up a data source that you know how to query, refer to [Create a dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/) instead.
To create your first dashboard using the built-in `-- Grafana --` data source:
1. Click **Dashboards** in the left-side menu.
1. On the Dashboards page, click **New** and select **New Dashboard** from the drop-down menu.
1. Click **Dashboards** in the main menu.
1. On the **Dashboards** page, click **New** and select **New Dashboard** from the drop-down menu.
1. On the dashboard, click **+ Add visualization**.
@ -59,35 +59,33 @@ To create your first dashboard using the built-in `-- Grafana --` data source:
{{<figureclass="float-right"src="/media/docs/grafana/dashboards/screenshot-data-source-selector-10.0.png"max-width="800px"alt="Select data source dialog box">}}
This configures your [query]({{< relref "../panels-visualizations/query-transform-data#add-a-query" >}}) and generates the Random Walk dashboard.
1. Click the Refresh dashboard icon to query the data source.
This configures your [query](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/#add-a-query) and generates the Random Walk dashboard.
1. When you've finished editing your panel, click **Save** to save the dashboard.
1. Click **Refresh** to query the data source.
1. When you've finished editing your panel, click **Save dashboard**.
Alternatively, click **Apply** if you want to see your changes applied to the dashboard first. Then click the save icon in the dashboard header.
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. Add a descriptive title for the dashboard, or have Grafana create one using [generative AI features](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/manage-dashboards#set-up-generative-ai-features-for-dashboards), and then click **Save**.
1. Click **Back to dashboard** and then **Exit edit**.
Congratulations, you have created your first dashboard and it's displaying results.
#### Next steps
Continue to experiment with what you have built, try the [explore workflow]({{< relref "../explore" >}}) or another visualization feature. Refer to [Data sources]({{< relref "../datasources" >}}) for a list of supported data sources and instructions on how to [add a data source]({{< relref "../datasources#add-a-data-source" >}}). The following topics will be of interest to you:
Continue to experiment with what you have built, try the [explore workflow](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/explore/) or another visualization feature. Refer to [Data sources](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/) for a list of supported data sources and instructions on how to [add a data source](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/#add-a-data-source). The following topics will be of interest to you:
- [Panels and visualizations]({{< relref "../panels-visualizations" >}})
@ -249,5 +249,7 @@ If you want to add all of the current dashboard's variables to the URL, then use
1. If you want the link to open in a new tab, toggle the **Open in a new tab** switch.
1. Click **Save** to save changes and close the dialog box.
1. Click **Apply** to see your changes in the dashboard.
1. Click the **Save dashboard** icon to save your changes to the dashboard.
1. Click **Save dashboard**.
1. Click **Back to dashboard** and then **Exit edit**.
If you add multiple data links, you can control the order in which they appear in the visualization. To do this, click and drag the data link to the desired position.
@ -95,7 +95,8 @@ To configure repeating panels, follow these steps:
- **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**.
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.
@ -185,3 +185,6 @@ The following image shows a table visualization with value mappings. If you want
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**.
In the panel editor, you can update all the elements of a visualization including the data source, queries, time range, and visualization display options.
This following sections describe the areas of the Grafana panel editor.
@ -59,26 +59,25 @@ This following sections describe the areas of the Grafana panel editor.
The header section lists the dashboard in which the panel appears and the following controls:
- **Discard:** Discards changes you have made to the panel since you last saved the dashboard.
- **Save:** Saves changes you made to the panel.
- **Apply:** Applies changes you made and closes the panel editor, returning you to the dashboard. You'll have to save the dashboard to persist the applied changes.
- **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.
- **Fill:** The visualization preview fills the available space. If you change the width of the side pane or height of the bottom pane the visualization changes to fill the available space.
- **Actual:** The visualization preview has the exact size as the size on the dashboard. If not enough space is available, the visualization scales down preserving the aspect ratio.
- **Time range controls:****Default** is either the browser local timezone or the timezone selected at a higher level.
- **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).
- **Query tab:** Select your data source and enter queries here. For more information, refer to [Add a query](ref:add-a-query). When you create a new dashboard, you'll be prompted to select a data source before you get to the panel editor. You set or update the data source in existing dashboards using the drop-down in the **Query** tab.
- **Transform tab:** Apply data transformations. For more information, refer to [Transform data](ref:transform-data).
- **Alert tab:** Write alert rules. For more information, refer to [the overview of Grafana Alerting](ref:the-overview-of-grafana-alerting).
- **Queries** - Select your data source and enter queries here. For more information, refer to [Add a query](ref:add-a-query). When you create a new dashboard, you'll be prompted to select a data source before you get to the panel editor. You set or update the data source in existing dashboards using the drop-down in the **Queries** tab.
- **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).
@ -90,20 +86,30 @@ For more information on the panel editor, refer to the [Panel editor documentati
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. Select **Add visualization** from a new dashboard or select **Add Panel** on an existing dashboard.
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 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, select the **TraceQL** query type tab.
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.
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-template-query.png"caption="Add a template query">}}
1. Select **Apply** in the panel editor to add the panel to the dashboard.
1. Go to the dashboard **Settings** and add a new variable called `traceId`, of variable type **Custom**, giving it a label if required. Select **Apply** to add the variable to the dashboard.
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.
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-custom-variable.png"max-width="50%"caption="Add a Custom variable">}}
{{<figuresrc="/media/docs/grafana/dashboards/screenshot-traces-custom-variable-11.2.png"max-width="50%"caption="Add a Custom variable">}}
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.
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-traceid-panel.png"caption="Results of query in trace panel">}}
@ -113,15 +119,19 @@ This procedure uses dashboard variables and templates to allow you to enter trac
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, select **Add panel** to add a new visualization panel.
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 of the panel editor, select the **Visualizations** tab, search for, and select **Table**.
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.
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-dynamic-query.png"caption="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.
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-returned-query.png"caption="Results of a returned query in the panel table">}}
@ -132,7 +142,7 @@ The results in the traces visualization include links to the **Explore** page th
To create a set of data links in the panel, use the following steps:
1. In the right-side menu, under **Data links**, select**Add link**.
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.
@ -144,8 +154,8 @@ To create a set of data links in the panel, use the following steps:
{{<figuresrc="/static/img/docs/panels/traces/screenshot-traces-edit-link.png"caption="Edit link and add the Trace link">}}
1. Select **Save** to save the data link.
1. Select **Apply** from the panel editor to apply the panel to the dashboard.
1. Save the dashboard.
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.
Isabel Matwawana
8 months ago
committed by