Prepare dashboards, panels, and visualizations for Grafana Cloud mount (#73632)
* Update dashboards pages to use `docs/reference` shortcode Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update panels-visualizations pages to use `docs/reference` shortcode Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Use raw Markdown admonitions for contextual links See https://discourse.gohugo.io/t/markdown-reference-links-in-shortcodes/5770/3. Should be resolved by https://docs.google.com/document/d/19xd4CD3IrAqQqNR3xQeLfuIV-u2iNSQSBEvPZE9J4qU/edit#heading=h.5sybau7waq2q. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Prefer "Warning" over "Caution" Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Prettier Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix some links missing destinations Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix 'time range controls' link Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Add missing 'HTTP APIs' link Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix dashboard links missing destinations Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix links missing destinations in panels and visualizations documentation Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix dud link Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --------- Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>
This commit is contained in:
Jack Baldry
Isabel
@@ -23,7 +23,7 @@ weight: 85
|
||||
|
||||
Reporting enables you to automatically generate PDFs from any of your dashboards and have Grafana email them to interested parties on a schedule. This is available in Grafana Cloud and in Grafana Enterprise.
|
||||
|
||||
> If you have [Role-based access control]({{< relref "../../administration/roles-and-permissions/access-control/" >}}) enabled, for some actions you would need to have relevant permissions.
|
||||
> If you have [Role-based access control][] enabled, for some actions you would need to have relevant permissions.
|
||||
> Refer to specific guides to understand what permissions are required.
|
||||
|
||||
<!--
|
||||
@@ -36,16 +36,16 @@ For information about recent improvements to the reporting UI, refer to [Grafana
|
||||
|
||||
## Requirements
|
||||
|
||||
- SMTP must be configured for reports to be sent. Refer to [SMTP]({{< relref "../../setup-grafana/configure-grafana/#smtp" >}}) in [Configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}) for more information.
|
||||
- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering]({{< relref "../../setup-grafana/image-rendering/" >}}) for more information.
|
||||
- SMTP must be configured for reports to be sent. Refer to [SMTP][] in [Configuration][] for more information.
|
||||
- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering][] for more information.
|
||||
|
||||
## Access control
|
||||
|
||||
When [RBAC]({{< relref "../../administration/roles-and-permissions/access-control/" >}}) is enabled, you need to have the relevant [Permissions]({{< relref "../../administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/" >}}) to create and manage reports.
|
||||
When [RBAC][] is enabled, you need to have the relevant [Permissions][] to create and manage reports.
|
||||
|
||||
## Create or update a report
|
||||
|
||||
Only organization administrators can create reports by default. You can customize who can create reports with [Role-based access control]({{< relref "../../administration/roles-and-permissions/access-control/" >}}).
|
||||
Only organization administrators can create reports by default. You can customize who can create reports with [Role-based access control][].
|
||||
|
||||
1. Click **Dashboards > Reports** in the side navigation menu.
|
||||
|
||||
@@ -54,7 +54,7 @@ Only organization administrators can create reports by default. You can customiz
|
||||
1. Click **+ Create a new report**.
|
||||
1. Select report dashboard.
|
||||
- **Source dashboard:** Select the dashboard from which you want to generate the report.
|
||||
- **Time range:** (optional) Use custom time range for the report. For more information, refer to [Report time range]({{< relref "#report-time-range" >}}).
|
||||
- **Time range:** (optional) Use custom time range for the report. For more information, refer to [Report time range](#report-time-range).
|
||||
- **Add another dashboard:** Add more than one dashboard to the report.
|
||||
1. Format the report.
|
||||
- **Choose format options for the report:** Select at least one option. Attach report as PDF, embed dashboard as an image, or attach CSV file of table panel data.
|
||||
@@ -75,19 +75,15 @@ Only organization administrators can create reports by default. You can customiz
|
||||
|
||||
### Save as draft
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.1.0 and later and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 9.1.0 and later and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
You can save a report as a draft at any point during the report creation or update process. You can save a report as a draft even if it's missing required fields. Also, the report won't be sent according to its schedule while it's a draft.
|
||||
|
||||
### Choose template variables
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables]({{< relref "../variables/" >}}) section.
|
||||
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables][] section.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
The query variables saved with a report might become of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that occurs, the selected variables must be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report stays up-to-date as new values are added.
|
||||
@@ -95,11 +91,9 @@ The query variables saved with a report might become of date if the results of t
|
||||
|
||||
### Render a report with panels or rows set to repeat by a variable
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 8.0 and later, and [Grafana Cloud](/docs/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 [Repeat panels or rows]({{< relref "../../panels-visualizations/configure-panel-options/#configure-repeating-rows-or-panels" >}}).
|
||||
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 [Repeat panels or rows][].
|
||||
|
||||
#### Caveats
|
||||
|
||||
@@ -112,9 +106,7 @@ You can include dynamic dashboards with panels or rows, set to repeat by a varia
|
||||
|
||||
### Report time range
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
You can set custom report time ranges in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 7.2+ and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** You can set custom report time ranges in [Grafana Enterprise][] 7.2+ and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
By default, reports use the saved time range of the dashboard. You can change the time range of the report by:
|
||||
|
||||
@@ -123,7 +115,7 @@ By default, reports use the saved time range of the dashboard. You can change th
|
||||
|
||||
The page header of the report displays the time range for the dashboard's data queries. Dashboards set to use the browser's time zone use the time zone on the Grafana server.
|
||||
|
||||
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls]({{< relref "./manage-dashboards/#dashboard-time-settings" >}}).
|
||||
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls][].
|
||||
|
||||
### Layout and orientation
|
||||
|
||||
@@ -138,24 +130,20 @@ If the time zone is set differently between your Grafana server and its remote i
|
||||
|
||||
### CSV export
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 8+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] 8+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
You can attach a CSV file to the report email for each table panel on the selected dashboard, along with the PDF report. By default, CSVs larger than 10Mb are not sent which keeps email servers from rejecting the email. You can increase or decrease this limit in the [reporting configuration]({{< relref "#rendering-configuration" >}}).
|
||||
You can attach a CSV file to the report email for each table panel on the selected dashboard, along with the PDF report. By default, CSVs larger than 10Mb are not sent which keeps email servers from rejecting the email. You can increase or decrease this limit in the [reporting configuration](#rendering-configuration).
|
||||
|
||||
This feature relies on the same plugin that supports the [image rendering]({{< relref "../../setup-grafana/image-rendering/" >}}) features.
|
||||
This feature relies on the same plugin that supports the [image rendering][] features.
|
||||
|
||||
When the CSV file is generated, it is temporarily written to the `csv` folder in the Grafana `data` folder.
|
||||
|
||||
A background job runs every 10 minutes and removes temporary CSV files. You can configure how long a CSV file should be stored before being removed by configuring the [temp-data-lifetime]({{< relref "../../setup-grafana/configure-grafana/#temp-data-lifetime" >}}) setting. This setting also affects how long a renderer PNG file should be stored.
|
||||
A background job runs every 10 minutes and removes temporary CSV files. You can configure how long a CSV file should be stored before being removed by configuring the [temp-data-lifetime][] setting. This setting also affects how long a renderer PNG file should be stored.
|
||||
|
||||
### Scheduling
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
The scheduler was significantly changed in Grafana Enterprise version 8.1.
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
> The scheduler was significantly changed in Grafana Enterprise version 8.1.
|
||||
|
||||
Scheduled reports can be sent once, or repeated on an hourly, daily, weekly, or monthly basis, or sent at custom intervals. You can also disable scheduling by selecting **Never**, for example to send the report via the API.
|
||||
|
||||
@@ -175,9 +163,7 @@ When you schedule a report with a monthly frequency, and set the start date betw
|
||||
|
||||
#### Send a test email
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 7.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
1. In the report, click **Send test email**.
|
||||
1. In the **Email** field, enter the email address or addresses that you want to test, separated by a semicolon.
|
||||
@@ -188,25 +174,19 @@ The last saved version of the report will be sent to selected emails. You can us
|
||||
|
||||
### Pause a report
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 8.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
You can pause sending reports from the report list view by clicking the pause icon. The report will not be sent according to its schedule until it is resumed by clicking the resume button on the report row.
|
||||
|
||||
### Add multiple dashboards to a report
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
You can add more than one dashboard to a report. Additional dashboards will be rendered as new pages in the same PDF file, or additional images if you chose to embed images in your report email. You cannot add the same dashboard to a report multiple times.
|
||||
|
||||
### Embed a dashboard as an image into a report
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 9.0 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
You can send a report email with an image of the dashboard embedded in the email instead of attached as a PDF. In this case, the email recipients can see the dashboard at a glance instead of having to open the PDF.
|
||||
|
||||
@@ -214,9 +194,7 @@ You can send a report email with an image of the dashboard embedded in the email
|
||||
|
||||
You can generate and save PDF files of any dashboard.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 6.7 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
{{% /admonition %}}
|
||||
> **Note:** Available in [Grafana Enterprise][] version 6.7 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
1. In the dashboard that you want to export as PDF, click the **Share dashboard** icon.
|
||||
1. On the PDF tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
|
||||
@@ -226,7 +204,7 @@ Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterpr
|
||||
|
||||
## Send a report via the API
|
||||
|
||||
You can send reports programmatically with the [send report]({{< relref "../../developers/http_api/reporting/#send-report" >}}) endpoint in the [HTTP APIs]({{< relref "../../developers/http_api/" >}}).
|
||||
You can send reports programmatically with the [send report][] endpoint in the [HTTP APIs][].
|
||||
|
||||
## Rendering configuration
|
||||
|
||||
@@ -236,7 +214,7 @@ To make a panel more legible, you can set a scale factor for the rendered images
|
||||
|
||||
You can also specify custom fonts that support different Unicode scripts. The DejaVu font is the default used for PDF rendering.
|
||||
|
||||
These options are available in the [configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}) file.
|
||||
These options are available in the [configuration][] file.
|
||||
|
||||
```ini
|
||||
[reporting]
|
||||
@@ -263,7 +241,7 @@ font_italic = DejaVuSansCondensed-Oblique.ttf
|
||||
|
||||
## Report settings
|
||||
|
||||
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.2 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
> **Note:** Available in [Grafana Enterprise][] version 7.2 and later, and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
You can configure organization-wide report settings in the **Settings** under **Dashboards > Reporting**. Settings are applied to all the reports for current organization.
|
||||
|
||||
@@ -284,9 +262,53 @@ Currently, the API does not allow for the simultaneous upload of files with iden
|
||||
|
||||
## Troubleshoot reporting
|
||||
|
||||
To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration]({{< relref "../../setup-grafana/configure-grafana/#filters" >}}) for more information.
|
||||
To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration][] for more information.
|
||||
|
||||
```bash
|
||||
[log]
|
||||
filters = report:debug
|
||||
```
|
||||
|
||||
{{% docs/reference %}}
|
||||
[time range controls]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/manage-dashboards"
|
||||
[time range controls]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/manage-dashboards"
|
||||
|
||||
[image rendering]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/image-rendering"
|
||||
[image rendering]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/image-rendering"
|
||||
|
||||
[configuration]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana"
|
||||
[configuration]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana"
|
||||
|
||||
[Grafana Enterprise]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/introduction/grafana-enterprise"
|
||||
[Grafana Enterprise]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/introduction/grafana-enterprise"
|
||||
|
||||
[Image rendering]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/image-rendering"
|
||||
[Image rendering]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/image-rendering"
|
||||
|
||||
[send report]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>"
|
||||
[send report]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>"
|
||||
|
||||
[SMTP]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#smtp"
|
||||
[SMTP]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#smtp"
|
||||
|
||||
[Repeat panels or rows]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/configure-panel-options#configure-repeating-rows-or-panels"
|
||||
[Repeat panels or rows]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/configure-panel-options#configure-repeating-rows-or-panels"
|
||||
|
||||
[Templates and variables]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/variables"
|
||||
[Templates and variables]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/dashboards/variables"
|
||||
|
||||
[temp-data-lifetime]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#temp-data-lifetime"
|
||||
[temp-data-lifetime]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#temp-data-lifetime"
|
||||
|
||||
[RBAC]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/administration/roles-and-permissions/access-control"
|
||||
[RBAC]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/administration/roles-and-permissions/access-control"
|
||||
|
||||
[Role-based access control]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/administration/roles-and-permissions/access-control"
|
||||
[Role-based access control]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/administration/roles-and-permissions/access-control"
|
||||
|
||||
[Configuration]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#filters"
|
||||
[Configuration]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#filters"
|
||||
|
||||
[HTTP APIs]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/http_api"
|
||||
[HTTP APIs]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/http_api"
|
||||
{{% /docs/reference %}}
|
||||
|
||||
Reference in New Issue
Block a user