From f96a72d3ec138970017cfc87290c25c322a04f40 Mon Sep 17 00:00:00 2001 From: Christopher Moyer <35463610+chri2547@users.noreply.github.com> Date: Wed, 10 Aug 2022 10:18:04 -0500 Subject: [PATCH] Docs/refactors configure panels (#53485) * updates prose * updates prose and relrefs * incorporates feedback * moves repeating rows to add and organize panels; fixes relrefs --- .../index.md} | 71 ++++++++---- docs/sources/dashboards/use-dashboards.md | 2 +- docs/sources/enterprise/reporting.md | 2 +- .../panels/add-panels-dynamically/_index.md | 18 ---- .../about-repeating-panels-rows.md | 18 ---- .../configure-repeating-panels.md | 30 ------ .../configure-repeating-rows.md | 28 ----- .../panels/configure-panel-options/index.md | 102 ++++++++++++++++++ .../add-title-and-description.md | 29 ----- .../working-with-panels/view-json-model.md | 21 ---- 10 files changed, 155 insertions(+), 166 deletions(-) rename docs/sources/dashboards/{add-organize-panels.md => add-organize-panels/index.md} (52%) delete mode 100644 docs/sources/panels/add-panels-dynamically/_index.md delete mode 100644 docs/sources/panels/add-panels-dynamically/about-repeating-panels-rows.md delete mode 100644 docs/sources/panels/add-panels-dynamically/configure-repeating-panels.md delete mode 100644 docs/sources/panels/add-panels-dynamically/configure-repeating-rows.md create mode 100644 docs/sources/panels/configure-panel-options/index.md delete mode 100644 docs/sources/panels/working-with-panels/add-title-and-description.md delete mode 100644 docs/sources/panels/working-with-panels/view-json-model.md diff --git a/docs/sources/dashboards/add-organize-panels.md b/docs/sources/dashboards/add-organize-panels/index.md similarity index 52% rename from docs/sources/dashboards/add-organize-panels.md rename to docs/sources/dashboards/add-organize-panels/index.md index b48598903fd..446e9d1eb15 100644 --- a/docs/sources/dashboards/add-organize-panels.md +++ b/docs/sources/dashboards/add-organize-panels/index.md @@ -6,9 +6,18 @@ aliases: - /docs/grafana/latest/features/dashboard/dashboards/ - /docs/grafana/latest/panels/working-with-panels/add-panel/ - /docs/grafana/latest/dashboards/add-organize-panels/ + - /docs/grafana/latest/panels/add-panels-dynamically/about-repeating-panels-rows/ + - /docs/grafana/latest/panels/add-panels-dynamically/configure-repeating-rows/ + - /docs/grafana/latest/panels/add-panels-dynamically/configure-repeating-panels/ title: Add and organize panels menuTitle: Add and organize panels weight: 2 +keywords: + - panel + - dashboard + - dynamic + - rows + - add --- # Add and organize panels @@ -17,23 +26,23 @@ This section describes the areas of the Grafana panel editor. 1. Panel header: The header section lists the dashboard in which the panel appears and the following controls: - - **Dashboard settings (gear) icon -** Click to access the dashboard settings. - - **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 will have to save the dashboard to persist the applied changes. + - **Dashboard settings (gear) icon:** Click to access the dashboard settings. + - **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 will have to save the dashboard to persist the applied changes. 1. Visualization preview: The visualization preview section contains the following options: - - **Table view -** Convert any visualization to a table so that you can see the data. Table views are useful for troubleshooting. - - **Fill -** The visualization preview fills the available space. If you change the width of the side pane or height of the bottom pane the visualization changes to fill the available space. - - **Actual -** The visualization preview will have the exact size as the size on the dashboard. If not enough space is available, the visualization will scale down preserving the aspect ratio. - - **Time range controls -** For more information, refer to [Time range controls]({{< relref "time-range-controls/" >}}). + - **Table view:** Convert any visualization to a table so that you can see the data. Table views are useful for troubleshooting. + - **Fill:** The visualization preview fills the available space. If you change the width of the side pane or height of the bottom pane the visualization changes to fill the available space. + - **Actual:** The visualization preview will have the exact size as the size on the dashboard. If not enough space is available, the visualization will scale down preserving the aspect ratio. + - **Time range controls:** For more information, refer to [Time range controls]({{< relref "time-range-controls/" >}}). 1. Data section: The data section contains tabs where you enter queries, transform your data, and create alert rules (if applicable). - - **Query tab -** Select your data source and enter queries here. For more information, refer to [Add a query]({{< relref "../panels/query-a-data-source/add-a-query/" >}}). - - **Transform tab -** Apply data transformations. For more information, refer to [Transform data]({{< relref "../panels/transform-data/" >}}). - - **Alert tab -** Write alert rules. For more information, refer to [Overview of Grafana 8 alerting]({{< relref "../alerting/" >}}). + - **Query tab:** Select your data source and enter queries here. For more information, refer to [Add a query]({{< relref "../../panels/query-a-data-source/add-a-query/" >}}). + - **Transform tab:** Apply data transformations. For more information, refer to [Transform data]({{< relref "../../panels/transform-data/" >}}). + - **Alert tab:** Write alert rules. For more information, refer to [Overview of Grafana 8 alerting]({{< relref "../../alerting/" >}}). 1. Panel display options: The display options section contains tabs where you configure almost every aspect of your data visualization. @@ -67,10 +76,10 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee **Before you begin:** -- Ensure that you have the proper permissions. For more information about permissions, refer to [About users and permissions]({{< relref "../administration/roles-and-permissions/" >}}). +- Ensure that you have the proper permissions. For more information about permissions, refer to [About users and permissions]({{< relref "../../administration/roles-and-permissions/" >}}). - Identify the dashboard to which you want to add the panel. - Understand the query language of the target data source. -- Ensure that data source for which you are writing a query has been added. For more information about adding a data source, refer to [Add a data source]({{< relref "../datasources/add-a-data-source/" >}}) if you need instructions. +- Ensure that data source for which you are writing a query has been added. For more information about adding a data source, refer to [Add a data source]({{< relref "../../datasources/add-a-data-source/" >}}) if you need instructions. **To create a dashboard and add a panel**: @@ -79,7 +88,7 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee 1. In the first line of the **Query** tab, click the drop-down list and select a data source. 1. Write or construct a query in the query language of your data source. - For more information about data sources, refer to [Data sources]({{< relref "../datasources/" >}}) for specific guidelines. + For more information about data sources, refer to [Data sources]({{< relref "../../datasources/" >}}) for specific guidelines. 1. In the Visualization list, select a visualization type. @@ -87,18 +96,40 @@ Dashboards and panels allow you to show your data in visual form. Each panel nee ![](/static/img/docs/panel-editor/select-visualization-8-0.png) - For more information about individual visualizations, refer to [Visualizations options]({{< relref "../visualizations/" >}}). + For more information about individual visualizations, refer to [Visualizations options]({{< relref "../../visualizations/" >}}). 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. - - [Format data using value mapping]({{< relref "../panels/format-data/about-value-mapping/" >}}) - - [Visualization-specific options]({{< relref "../visualizations/" >}}) - - [Override field values]({{< relref "../panels/override-field-values/about-field-overrides/" >}}) - - [Configure thresholds]({{< relref "../panels/configure-thresholds/" >}}) - - [Configure standard options]({{< relref "../panels/configure-standard-options/" >}}) + - [Format data using value mapping]({{< relref "../../panels/format-data/about-value-mapping/" >}}) + - [Visualization-specific options]({{< relref "../../visualizations/" >}}) + - [Override field values]({{< relref "../../panels/override-field-values/about-field-overrides/" >}}) + - [Configure thresholds]({{< relref "../../panels/configure-thresholds/" >}}) + - [Configure standard options]({{< relref "../../panels/configure-standard-options/" >}}) 1. Add a note to describe the visualization (or describe your changes) and then click **Save** in the upper-right corner of the page. Notes can be helpful if you need to revert the dashboard to a previous version. + +## 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](../../panels/configure-panel-options/#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. On the dashboard home page, click **Add panel**. + +1. On the **Add a panel** dialog box, click **Add a new row**. + +1. Hover over the row title and click the cog icon. + +1. On the **Row Options** dialog box, add a title and select the variable for which you want to add repeating rows. + +> **Note:** To provide context to dashboard users, add the variable to the row title. diff --git a/docs/sources/dashboards/use-dashboards.md b/docs/sources/dashboards/use-dashboards.md index 1af414cb36c..74a2e3bdd14 100644 --- a/docs/sources/dashboards/use-dashboards.md +++ b/docs/sources/dashboards/use-dashboards.md @@ -52,7 +52,7 @@ The main building block of dashboard is the panel. You add new panels via the `A A dashboard row is a logical divider within a dashboard. It is used to group panels together. Rows can be collapsed or expanded allowing you to hide parts of the dashboard. Panels inside a collapsed row will not issue any queries. -Use the [repeating rows]({{< relref "../panels/add-panels-dynamically/configure-repeating-rows" >}}) to dynamically create rows based on a template variable. +Use the [repeating rows]({{< relref "../panels/configure-panel-options/#configure-repeating-rows" >}}) to dynamically create rows based on a template variable. ## Keyboard shortcuts diff --git a/docs/sources/enterprise/reporting.md b/docs/sources/enterprise/reporting.md index 7510b9d2032..07c2ef5dede 100644 --- a/docs/sources/enterprise/reporting.md +++ b/docs/sources/enterprise/reporting.md @@ -75,7 +75,7 @@ You can configure report-specific template variables for the dashboard on the re > **Note:** Available in [Grafana Enterprise]({{< relref "../enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced]({{< ref "/grafana-cloud" >}}). -You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to the [Repeat panels or rows]({{< relref "../panels/add-panels-dynamically/" >}}) section. +You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to the [Repeat panels or rows]({{< relref "../panels/configure-panel-options/#configure-repeating-rows-or-panels" >}}) section. #### Caveats: diff --git a/docs/sources/panels/add-panels-dynamically/_index.md b/docs/sources/panels/add-panels-dynamically/_index.md deleted file mode 100644 index d7c20e7ce19..00000000000 --- a/docs/sources/panels/add-panels-dynamically/_index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/add-panels-dynamically/ - - /docs/grafana/latest/panels/repeat-panels-or-rows/ - - /docs/sources/panels/add-panels-dynamically/ -keywords: - - dynamic - - variable - - panel -title: Enable template variables to add panels dynamically -weight: 800 ---- - -# Enable template variables to add panels dynamically - -Harness the power of Grafana by configuring the system to automatically and dynamically add panels based on criteria that you define. - -{{< section >}} diff --git a/docs/sources/panels/add-panels-dynamically/about-repeating-panels-rows.md b/docs/sources/panels/add-panels-dynamically/about-repeating-panels-rows.md deleted file mode 100644 index c2f8ff94ca4..00000000000 --- a/docs/sources/panels/add-panels-dynamically/about-repeating-panels-rows.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/add-panels-dynamically/about-repeating-panels-rows/ - - /docs/sources/panels/add-panels-dynamically/about-repeating-panels-rows/ -title: About repeating panels or rows -weight: 10 ---- - -# About repeating panels and rows - -You can configure Grafana to dynamically add panels or rows to a dashboard. A dynamic panel (or row) 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. - -## Grafana Play examples - -You can see examples in the following dashboards: - -- [Prometheus repeat](https://play.grafana.org/d/000000036/prometheus-repeat) -- [Repeated Rows Dashboard](https://play.grafana.org/d/000000153/repeat-rows). diff --git a/docs/sources/panels/add-panels-dynamically/configure-repeating-panels.md b/docs/sources/panels/add-panels-dynamically/configure-repeating-panels.md deleted file mode 100644 index bf326fe56cc..00000000000 --- a/docs/sources/panels/add-panels-dynamically/configure-repeating-panels.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/add-panels-dynamically/configure-repeating-panels/ - - /docs/sources/panels/add-panels-dynamically/configure-repeating-panels/ -title: Configure repeating panels -weight: 20 ---- - -# Configure repeating panels - -For queries that return multiple values for a variable, you can configure Grafana to dynamically add panels based on those values. - -> **Note:** Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it. - -## Before you begin - -- Ensure that the query includes a multi-value variable. - -**To configure repeating panels**: - -1. Edit the panel you want to repeat. - -1. On the display options pane, expand **Panel options > Repeat options**. - -1. Select a `direction`. - - - Choose `horizontal` to arrange panels side-by-side. Grafana adjusts the width of a repeated panel. Currently, you cannot mix other panels on a row with a repeated panel. - - Choose `vertical` to arrange panels in a column. The width of repeated panels is the same as the original, repeated panel. - -1. To propagate changes to all panels, reload the dashboard. diff --git a/docs/sources/panels/add-panels-dynamically/configure-repeating-rows.md b/docs/sources/panels/add-panels-dynamically/configure-repeating-rows.md deleted file mode 100644 index 0032abb5942..00000000000 --- a/docs/sources/panels/add-panels-dynamically/configure-repeating-rows.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/add-panels-dynamically/configure-repeating-rows/ - - /docs/sources/panels/add-panels-dynamically/configure-repeating-rows/ -title: Configure repeating rows -weight: 30 ---- - -# Configure repeating rows - -As seen above with the panels you can also repeat rows if you have variables set with `Multi-value` or -`Include all value` selection option. - -## Before you begin - -- Ensure that the query includes a multi-value variable. - -**To configure repeating rows**: - -1. On the dashboard home page, click **Add panel**. - -1. On the **Add a panel** dialog box, click **Add a new row**. - -1. Hover over the row title and click the cog icon. - -1. On the `Row Options` configuration panel, select the variable for which you want to add repeating rows. - -> To help provide context to dashboard users, add the variable to the row title. diff --git a/docs/sources/panels/configure-panel-options/index.md b/docs/sources/panels/configure-panel-options/index.md new file mode 100644 index 00000000000..8bc56cfd2da --- /dev/null +++ b/docs/sources/panels/configure-panel-options/index.md @@ -0,0 +1,102 @@ +--- +aliases: + - /docs/grafana/latest/panels/add-panels-dynamically/ + - /docs/grafana/latest/panels/repeat-panels-or-rows/ + - /docs/grafana/latest/panels/working-with-panels/add-title-and-description/ + - /docs/grafana/latest/panels/working-with-panels/view-json-model/ + - /docs/grafana/latest/panels/configure-panel-options/ +title: Configure panel options +menuTitle: Configure panel options +weight: 150 +keywords: + - panel + - dynamic + - add + - title + - description + - JSON model +--- + +# Configure panel options + +A Grafana panel is the user interface you use to define a data source query, and transform and format data that appears in visualizations. + +A panel editor includes a query builder and a series of options that you can use to transform data and add information to your panels. + +This topic describes how to: + +- Open a panel for editing +- Add a panel title and description +- View a panel JSON model +- Add repeating rows and panels + +## Edit a panel + +After you add a panel to a dashboard, you can open it at any time to change change or update queries, add data transformation, and change visualization settings. + +1. Open the dashboard that contains the panel you want to edit. + +1. Click in the panel title and select **Edit**. To use a keyboard shortcut to open the panel, hover over the panel and press `e`. + + The panel opens in edit mode. + +## Add a title and description to a panel + +Add a title and description to a panel to share with users any important information about the visualization. For example, use the description to document the purpose of the visualization. + +1. [Edit a panel](#edit-a-panel). + +1. In the panel display options pane, locate the **Panel options** section. + +1. Enter a **Title**. + + Text entered in this field appears at the top of your panel in the panel editor and in the dashboard. + +1. Write a description of the panel and the data you are displaying. + + Text entered in this field appears in a tooltip in the upper-left corner of the panel. + + You can use [variables you have defined]({{< relref "../../variables/" >}}) in the **Title** and **Description** field, but not [global variables]({{< relref "../../variables/variable-types/global-variables/" >}}). + + ![](/static/img/docs/panels/panel-options-8-0.png) + +## View a panel JSON model + +Explore and export panel, panel data, and data frame JSON models. + +1. Open the dashboard that contains the panel. + +1. Click in the panel title and select **Inspect > Panel JSON**. + +1. In the **Select source** field, select one of the following options: + + - **Panel JSON:** Displays a JSON object representing the panel. + - **Panel data:** Displays a JSON object representing the data that was passed to the panel. + - **DataFrame structure:** Displays the raw result set with transformations, field configurations, and override configurations applied. + +1. To explore the JSON, click `>` to expand or collapse portions of the JSON model. + +## 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](../../dashboards/add-organize-panels/#configure-repeating-rows). + +> **Note:** Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it. + +To see an example of repeating panels, refer to [Prometheus dashboard with repeating panels](https://play.grafana.org/d/000000036/prometheus-repeat). + +**Before you begin:** + +- Ensure that the query includes a multi-value variable. + +**To configure repeating panels:** + +1. [Edit the panel](#edit-a-panel) you want to repeat. + +1. On the display options pane, click **Panel options > Repeat options**. + +1. Select a `direction`. + + - Choose `horizontal` to arrange panels side-by-side. Grafana adjusts the width of a repeated panel. Currently, you cannot mix other panels on a row with a repeated panel. + - Choose `vertical` to arrange panels in a column. The width of repeated panels is the same as the original, repeated panel. + +1. To propagate changes to all panels, reload the dashboard. diff --git a/docs/sources/panels/working-with-panels/add-title-and-description.md b/docs/sources/panels/working-with-panels/add-title-and-description.md deleted file mode 100644 index e08e2010362..00000000000 --- a/docs/sources/panels/working-with-panels/add-title-and-description.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/working-with-panels/add-title-and-description/ - - /docs/sources/panels/working-with-panels/add-title-and-description/ -title: Add a title and description to a panel -weight: 30 ---- - -# Add a title and description to a panel - -Add a title and description to a panel to share with users any important information about the visualization. For example, use the description to document the purpose of the visualization. - -1. Open a panel. - -1. In the panel display options pane, locate the **Panel options** section. - -1. Enter a **Title**. - - Text entered in this field is displayed at the top of your panel in the panel editor and in the dashboard. - - You can use [variables you have defined]({{< relref "../../variables/" >}}) in either field, but not [global variables]({{< relref "../../variables/variable-types/global-variables/" >}}). - -1. Write a description of the panel and the data you are displaying. - - Text entered in this field is displayed in a tooltip in the upper left corner of the panel. - - You can use [variables you have defined]({{< relref "../../variables/" >}}) in either field, but not [global variables]({{< relref "../../variables/variable-types/global-variables/" >}}). - - ![](/static/img/docs/panels/panel-options-8-0.png) diff --git a/docs/sources/panels/working-with-panels/view-json-model.md b/docs/sources/panels/working-with-panels/view-json-model.md deleted file mode 100644 index 9220c684720..00000000000 --- a/docs/sources/panels/working-with-panels/view-json-model.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/working-with-panels/view-json-model/ - - /docs/sources/panels/working-with-panels/view-json-model/ -title: View a panel JSON model -weight: 100 ---- - -# View a panel JSON model - -Explore and export panel, panel data, and data frame JSON models. - -1. Open the panel inspector and then click the **JSON** tab or in the panel menu click **Inspect > Panel JSON**. - -1. In Select source, choose one of the following options: - - - **Panel JSON -** Displays a JSON object representing the panel. - - **Panel data -** Displays a JSON object representing the data that was passed to the panel. - - **DataFrame structure -** Displays the raw result set with transformations, field configuration, and overrides configuration applied. - -1. You can expand or collapse portions of the JSON to explore it, or you can click **Copy to clipboard** and paste the JSON in another application.