From d9a0cedd89b439b1fbb431f092c2c04ab18d61f1 Mon Sep 17 00:00:00 2001 From: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com> Date: Mon, 15 Apr 2024 10:51:00 -0400 Subject: [PATCH] Docs: add panel overview (#86075) * Added panel overview page and updated panel editor page * Finalized panel overview intro text and added links * Added add panel section to overview and removed section from editor * Fixed version interpolation syntax and updated Cloud link Co-authored-by: Jack Baldry * Fixed version interpolation syntax Co-authored-by: Jack Baldry --------- Co-authored-by: Jack Baldry --- .../panel-editor-overview/index.md | 95 +++-------- .../panel-overview/index.md | 161 ++++++++++++++++++ 2 files changed, 183 insertions(+), 73 deletions(-) create mode 100644 docs/sources/panels-visualizations/panel-overview/index.md diff --git a/docs/sources/panels-visualizations/panel-editor-overview/index.md b/docs/sources/panels-visualizations/panel-editor-overview/index.md index 54ddeda2028..7c638b18ef8 100644 --- a/docs/sources/panels-visualizations/panel-editor-overview/index.md +++ b/docs/sources/panels-visualizations/panel-editor-overview/index.md @@ -15,99 +15,54 @@ keywords: - panel - dashboard - dynamic - - rows - add labels: products: - cloud - enterprise - oss -menuTitle: Panel editor overview -title: Panel editor overview +menuTitle: Panel editor +title: Panel editor description: Learn about the features of the panel editor weight: 20 --- -# Panel editor overview +# Panel editor In the panel editor, you can update all the elements of a visualization including the data source, queries, time range, and visualization display options. ![Panel editor](/media/docs/grafana/panels-visualizations/screenshot-panel-editor-view.png) -To add a panel in a new dashboard click **+ Add visualization** in the middle of the dashboard. To add a panel to an existing dashboard, click **Add** in the dashboard header and select **Visualization** in the drop-down: +This following sections describe the areas of the Grafana panel editor. -![Add dropdown](/media/docs/grafana/dashboards/screenshot-add-dropdown-10.0.png) +## Panel header -## Panel menu +The header section lists the dashboard in which the panel appears and the following controls: -To access the panel editor, hover over the top-right corner of any panel. Click the panel menu icon that appears and select **Edit**. The panel menu gives you access to the following actions: +- **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. -- **View**: View the panel in full screen. -- **Edit**: Open the panel editor to edit panel and visualization options. -- **Share**: Share the panel as a link, embed, or library panel. -- **Explore**: Open the panel in **Explore**, where you can focus on your query. -- **Inspect**: Open the **Inspect** drawer, where you can review the panel data, stats, metadata, JSON, and query. - - **Data**: Open the **Inspect** drawer in the **Data** tab. - - **Query**: Open the **Inspect** drawer in the **Query** tab. - - **Panel JSON**: Open the **Inspect** drawer in the **JSON** tab. -- **Extensions**: Access other actions provided by installed applications, such as declaring an incident. Note that this option doesn't appear unless you have app plugins installed which contribute an [extension](https://grafana.com/developers/plugin-tools/ui-extensions/) to the panel menu. -- **More**: Access other panel actions. - - **Duplicate**: Make a copy of the panel. Duplicated panels query data separately from the original panel. You can use the special `Dashboard` data source to [share the same query results across panels][] instead. - - **Copy**: Copy the panel to the clipboard. - - **Create library panel**: Create a panel that can be imported into other dashboards. - - **Create alert**: Open the alert rule configuration page in **Alerting**, where you can [create a Grafana-managed alert] based on the panel queries. - - **Hide legend**: Hide the panel legend. - - **Get help**: Send a snapshot or panel data to Grafana Labs Technical Support. -- **Remove**: Remove the panel from the dashboard. +## Visualization preview -## Panel editor +The visualization preview section contains the following options: -This section describes the areas of the Grafana panel editor. +- **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][] 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. -1. Panel header: The header section lists the dashboard in which the panel appears and the following controls: +## Data section - - **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. +The data section contains tabs where you enter queries, transform your data, and create alert rules (if applicable). -1. Visualization preview: The visualization preview section contains the following options: +- **Query tab:** Select your data source and enter queries here. For more information, refer to [Add a query][]. When you create a new dashboard, you'll be prompted to select a data source before you get to the panel editor. You set or update the data source in existing dashboards using the drop-down in the **Query** tab. +- **Transform tab:** Apply data transformations. For more information, refer to [Transform data][]. +- **Alert tab:** Write alert rules. For more information, refer to [the overview of Grafana Alerting][]. - - **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][] 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. +## Panel display options -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][]. 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][]. - - **Alert tab:** Write alert rules. For more information, refer to [the overview of Grafana Alerting][]. - -1. Panel display options: The display options section contains tabs where you configure almost every aspect of your data visualization. - -## Panel inspect drawer - -The inspect drawer helps you understand and troubleshoot your panels. You can view the raw data for any panel, export that data to a comma-separated values (CSV) file, view query requests, and export panel and data JSON. - -To access the panel inspect drawer from the edit view, hover over any part of the panel to display the actions menu on the top right corner. Click the menu and select **Inspect**. - -{{% admonition type="note" %}} -Not all panel types include all tabs. For example, dashboard list panels don't have raw data to inspect, so they don't display the Stats, Data, or Query tabs. -{{% /admonition %}} - -The panel inspector consists of the following options: - -1. The panel inspect drawer displays opens a drawer on the right side. Click the arrow in the upper right corner to expand or reduce the drawer pane. - -1. **Data tab -** Shows the raw data returned by the query with transformations applied. Field options such as overrides and value mappings aren't applied by default. - -1. **Stats tab -** Shows how long your query takes and how much it returns. - -1. **JSON tab -** Allows you to view and copy the panel JSON, panel data JSON, and data frame structure JSON. This is useful if you are provisioning or administering Grafana. - -1. **Query tab -** Shows you the requests to the server sent when Grafana queries the data source. - -1. **Error tab -** Shows the error. Only visible when query returns error. +The display options section contains tabs where you configure almost every aspect of your data visualization. {{% docs/reference %}} [Table]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/visualizations/table" @@ -121,10 +76,4 @@ The panel inspector consists of the following options: [the overview of Grafana Alerting]: "/docs/grafana/ -> /docs/grafana//alerting" [the overview of Grafana Alerting]: "/docs/grafana-cloud/ -> /docs/grafana//alerting" - -[share the same query results across panels]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/query-transform-data/share-query" -[share the same query results across panels]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/share-query" - -[create a Grafana-managed alert]: "/docs/grafana/ -> /docs/grafana//alerting/alerting-rules/create-grafana-managed-rule#create-alerts-from-panels" -[create a Grafana-managed alert]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-grafana-managed-rule#create-alerts-from-panels" {{% /docs/reference %}} diff --git a/docs/sources/panels-visualizations/panel-overview/index.md b/docs/sources/panels-visualizations/panel-overview/index.md new file mode 100644 index 00000000000..bcdbd4f2e02 --- /dev/null +++ b/docs/sources/panels-visualizations/panel-overview/index.md @@ -0,0 +1,161 @@ +--- +keywords: + - transform + - query + - panel + - dashboard + - rows + - dynamic + - add +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Panel overview +title: Panel overview +description: Learn about the features of the panel +weight: 15 +--- + +# Panel overview + +A Grafana panel is a visual representation of data composed of a [query][] and a [visualization][]. Within panels, you can apply [transformations][], which process the results of a query before they're passed on for visualization. You can also further customize a panel by formatting data and configuring visualization options. + +Each panel has a query editor specific to the data source selected in the panel. The query editor allows you to build a query that returns the data you want to visualize. + +Panels offer a wide variety of formatting and styling options, from applying colors based on field values to creating custom units. Each visualization also comes with options specific to it that give you further control over how your data is displayed. Panels can also be dragged, dropped, and resized to rearrange them on the dashboard. + +To get started adding panels, ensure that you have configured a data source: + +- For details about using data sources, refer to [Data sources][]. +- For more information about managing data sources as an administrator, refer to [Data source management][]. + + {{% admonition type="note" %}} + [Data source management](https://grafana.com/docs/grafana//administration/data-source-management/) is only available in [Grafana Enterprise](https://grafana.com/docs/grafana//introduction/grafana-enterprise/) and [Grafana Cloud](https://grafana.com/docs/grafana-cloud/). + {{% /admonition %}} + +## Panel feature overview + +The panel has the following features: + + + + + +- **Panel title** - You can create your own panel titles or have Grafana create them for you using [generative AI features][ai]. +- **Links** - Add [panel links][] to other dashboards, panels, or external sites. +- **Panel menu** - In the [panel menu](#panel-menu), access actions such as **View**, **Edit**, **Inspect**, and **Remove**. +- **Tooltips** - View [tooltips][] to get more information about data points. +- **Legend** - Change series colors, y-axis and series visibility directly from the [legend][]. + +## Panel menu + +To access the panel editor, hover over the top-right corner of any panel. Click the panel menu icon that appears and select **Edit**. The panel menu gives you access to the following actions: + +- **View**: View the panel in full screen. +- **Edit**: Open the panel editor to edit panel and visualization options. +- **Share**: Share the panel as a link, embed, or library panel. +- **Explore**: Open the panel in **Explore**, where you can focus on your query. +- **Inspect**: Open the **Inspect** drawer, where you can review the panel data, stats, metadata, JSON, and query. + - **Data**: Open the **Inspect** drawer in the **Data** tab. + - **Query**: Open the **Inspect** drawer in the **Query** tab. + - **Panel JSON**: Open the **Inspect** drawer in the **JSON** tab. +- **Extensions**: Access other actions provided by installed applications, such as declaring an incident. Note that this option doesn't appear unless you have app plugins installed which contribute an [extension](https://grafana.com/developers/plugin-tools/ui-extensions/) to the panel menu. +- **More**: Access other panel actions. + - **Duplicate**: Make a copy of the panel. Duplicated panels query data separately from the original panel. You can use the special `Dashboard` data source to [share the same query results across panels][share] instead. + - **Copy**: Copy the panel to the clipboard. + - **Create library panel**: Create a panel that can be imported into other dashboards. + - **Create alert**: Open the alert rule configuration page in **Alerting**, where you can [create a Grafana-managed alert][create] based on the panel queries. + - **Hide legend**: Hide the panel legend. + - **Get help**: Send a snapshot or panel data to Grafana Labs Technical Support. +- **Remove**: Remove the panel from the dashboard. + +## Keyboard shortcuts + +Grafana has a number of keyboard shortcuts available specifically for panels. Press `?` on your keyboard to display all keyboard shortcuts available in your version of Grafana. + +By hovering over a panel with the mouse you can use some shortcuts that will target that panel. + +- `e`: Toggle panel edit view +- `v`: Toggle panel fullscreen view +- `ps`: Open Panel Share Modal +- `pd`: Duplicate Panel +- `pr`: Remove Panel +- `pl`: Toggle panel legend + +## Add a panel + +To add a panel in a new dashboard click **+ Add visualization** in the middle of the dashboard: + +![Empty dashboard state](/media/docs/grafana/dashboards/empty-dashboard-10.2.png) + +To add a panel to an existing dashboard, click **Add** in the dashboard header and select **Visualization** in the drop-down: + +![Add dropdown](/media/docs/grafana/dashboards/screenshot-add-dropdown-10.0.png) + +## Panel configuration + +To configure panels, refer to the following subtopics: + +- [Configure panel options][] +- [Configure standard options][] +- [Configure a legend][legend] +- [Configure tooltips][tooltips] +- [Configure data links][] +- [Configure value mappings][] +- [Configure thresholds][] +- [Configure field overrides][] + +{{% docs/reference %}} +[query]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/query-transform-data" +[query]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data" + +[visualization]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/visualizations" +[visualization]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/visualizations" + +[transformations]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/query-transform-data/transform-data" +[transformations]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data" + +[Data source management]: "/docs/grafana/ -> /docs/grafana//administration/data-source-management" +[Data source management]: "/docs/grafana-cloud/ -> /docs/grafana//administration/data-source-management" + +[Data sources]: "/docs/grafana/ -> /docs/grafana//datasources" +[Data sources]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/connect-externally-hosted/data-sources" + +[ai]: "/docs/grafana/ -> /docs/grafana//dashboards/manage-dashboards#set-up-generative-ai-features-for-dashboards" +[ai]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/dashboards/manage-dashboards#set-up-generative-ai-features-for-dashboards" + +[panel links]: "/docs/grafana/ -> /docs/grafana//dashboards/build-dashboards/manage-dashboard-links#panel-links" +[panel links]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/dashboards/build-dashboards/manage-dashboard-links#panel-links" + +[tooltips]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-tooltips" +[tooltips]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-tooltips" + +[legend]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-legend" +[legend]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-legend" + +[share]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/query-transform-data/share-query" +[share]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/share-query" + +[create]: "/docs/grafana/ -> /docs/grafana//alerting/alerting-rules/create-grafana-managed-rule#create-alerts-from-panels" +[create]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-grafana-managed-rule#create-alerts-from-panels" + +[Configure panel options]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-panel-options" +[Configure panel options]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-panel-options" + +[Configure standard options]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-standard-options" +[Configure standard options]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-standard-options" + +[Configure data links]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-data-links" +[Configure data links]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-data-links" + +[Configure value mappings]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-value-mappings" +[Configure value mappings]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-value-mappings" + +[Configure thresholds]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-thresholds" +[Configure thresholds]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-thresholds" + +[Configure field overrides]: "/docs/grafana/ -> /docs/grafana//panels-visualizations/configure-overrides" +[Configure field overrides]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/visualizations/panels-visualizations/configure-overrides" +{{% /docs/reference %}}