Grafana Enterprise on Grafana Labs

Usage insights

Fri, 07 Mar 2025 11:34:44 +0100

Usage insights

Usage insights allow you to have a better understanding of how your Grafana instance is used.

Note: Available in Grafana Enterprise and Grafana Cloud Pro and Advanced.

The usage insights feature collects a number of aggregated data and stores them in the database:

Dashboard views (aggregated and per user)
Data source errors
Data source queries

These aggregated data give you access to several features:

This feature also generates detailed logs that can be exported to Loki. Refer to Export logs of usage insights.

Query caching

Fri, 07 Mar 2025 11:34:44 +0100

Query caching

When query caching is enabled, Grafana temporarily stores the results of data source queries. When you or another user submit the exact same query again, the results will come back from the cache instead of from the data source (like Splunk or ServiceNow) itself.

Query caching works for all backend data sources. You can enable the cache globally and configure the cache duration (also called Time to Live, or TTL).

Note: Available in Grafana Enterprise and Grafana Cloud Pro and Advanced.

The following cache backends are available: in-memory, Redis, and Memcached.

Note: Storing cached queries in-memory can increase Grafana’s memory footprint. In production environments, a Redis or Memcached backend is highly recommended.

When a panel queries a cached data source, the time until this query fetches fresh data is determined by the panel’s interval. This means that wider panels and dashboards with shorter time ranges fetch new data more frequently than narrower panels and dashboards with longer time ranges.

Interval is visible in a panel’s query options. It is calculated like this: (max data points) / time range. Max data points are calculated based on the width of the panel. For example, a full-width panel on a dashboard with a time range of last 7 days will retrieve fresh data every 10 minutes. In this example, cached data for this panel will be served for up to 10 minutes before Grafana queries the data source again and returns new data.

You can make a panel retrieve fresh data more frequently by increasing the Max data points setting in the panel’s query options.

Query caching benefits

Faster dashboard load times, especially for popular dashboards.
Reduced API costs.
Reduced likelihood that APIs will rate-limit or throttle requests.

Data sources that work with query caching

Query caching works for all Enterprise data sources as well as the following built-in data sources:

CloudWatch Metrics
Google Cloud Monitoring
InfluxDB
Microsoft SQL Server
MySQL
Postgres
Tempo

Some data sources, such as Elasticsearch, Prometheus, and Loki, cache queries themselves, so Grafana query caching does not improve performance.

Query caching also works for all data sources that include a backend. More specifically, caching works with data sources that extend the DataSourceWithBackend class in the plugins SDK.

To tell if a data source works with query caching, follow the instructions below to Enable and Configure query caching. If caching is enabled in Grafana but the Caching tab is not visible for the given data source, then query caching is not available for that data source.

Enable and configure query caching

You must be an Org admin or Grafana admin to enable query caching for a data source. For more information on Grafana roles and permissions, refer to About users and permissions.

By default, data source queries are not cached. To enable query caching for a single data source:

On the side menu, click Configuration > Data Sources.
In the data source list, click the data source that you want to turn on caching for.
Open the Cache tab.
Press the Enable button.
(Optional) Choose custom TTLs for the data source’s queries and resources caching. If you skip this step, then Grafana uses the default TTL.

Note: If query caching is enabled and the Cache tab is not visible in a data source’s settings, then query caching is not available for that data source.

To configure global settings for query caching, refer to the Query caching section of Enterprise Configuration.

Disable query caching

To disable query caching for a single data source:

On the side menu, click Configuration > Data Sources.
In the data source list, click the data source that you want to turn off caching for.
In the Cache tab, click Disable.

To disable query caching for an entire Grafana instance, set the enabled flag to false in the Query caching section of Enterprise Configuration. You will no longer see the Cache tab on any data sources, and no data source queries will be cached.

Clear cache

If you experience performance issues or repeated queries become slower to execute, consider clearing your cache.

Note: This action impacts all cache-enabled data sources. If you are using Memcached, the system clears all data from the Memcached instance.

To clear the cache:

Sign in to Grafana and click Settings > Data Sources.
Select a data source.
Click the Cache tab.
Click Clear cache.

Sending a request without cache

If a data source query request contains an X-Cache-Skip header, then Grafana skips the caching middleware, and does not search the cache for a response. This can be particularly useful when debugging data source queries using cURL.

Recorded queries

Fri, 07 Mar 2025 11:34:44 +0100

Recorded queries

Recorded queries allow you to see trends over time by taking a snapshot of a data point on a set interval. This can give you insight into historic trends.

For our plugins that do not return time series, it might be useful to plot historical data. For example, you might want to query ServiceNow to see a history of request response times but it can only return current point-in-time metrics.

Note: Available in Grafana Enterprise.

How recorded queries work

Note: An administrator must configure a Prometheus data source and associate it with a Remote write target before recorded queries can be used.

Recorded queries only work with backend data source plugins. Refer to Backend data source plugin for more information about backend data source plugins. You can recorded three types of queries:

single row and column - A query that returns a single row and column.
row count - A query that returns meaningful rows to be counted.
expression - Any expression. To learn more about creating and using expressions, see Expressions.

After a recorded query is created or enabled, it immediately creates a snapshot and continues to create snapshots at the set interval. The recorded query stops taking snapshots when it is disabled, deleted, or when Grafana is not running. Data points are gathered in the backend by running the recorded query and forwarding each result to a remote-write enabled Prometheus instance.

Using a recorded query

To use a recorded query, create one and add it to a dashboard. After that, it can be managed in Preferences from the Recorded queries tab.

Create a recorded query

Find/create a query you want to record on a dashboard in an edit panel. The query must only return one row and column. If it returns more, you can still record the number of results returned using the “count” option.
- The query’s data source must be a backend data source.
- Expressions can be used to aggregate data from a time series query. Refer to Expressions to learn more about creating and using expressions.
Click the record query button located in the top right of the query editor.
Enter recorded query information. All fields are required unless otherwise indicated.
- Name - Name of the recorded query.
- Description - (optional) Describe the recorded query as you want it to appear in the recorded query list.
- Interval - The interval on which the snapshot will be taken. The interval starts when you create the recorded query and will stop if you pause or delete the recorded query. Refer to Managing recorded queries for more information on pausing and deleting recorded queries.
- Range - The relative time range of the query. If you select a range of 30m and an interval of 1h the query will take a snapshot every hour of the past 30 minutes.
- Count query results - If you want to count the rows returned from your query toggle this option on. If this option is off, your query must return one row with one value.
Test your recorded query by clicking the test recorded query button.
Click Start recording query to start recording your query.

Add a recorded query

You can add existing recorded queries to panels in a dashboard. For each recorded query that you add, a Prometheus query is created: generated_recorded_query_name{id="generated_id", name="recorded query name"}. The created query from Prometheus returns all the recorded query’s gathered snapshots.

Navigate to a panel in a dashboard where you wish to add a recorded query.
Click the + Recorded query button located below the queries.
If you want to filter recorded queries by data source, select a data source from the filter by data source drop down menu.
Click the Add button on your recorded query to add it to the panel.

After adding your recorded query to the panel, the panel data source will become -- Mixed --. Your recorded query is represented by a Prometheus query with a name label matching your recorded query name. Refer to Prometheus to learn more about the Prometheus data source.

If after adding a recorded query, a query with a -- Mixed -- data source instead of Prometheus data source appears, this could mean that a Prometheus remote write target was not set up for recorded queries. Refer to Remote write target to set up a remote write point.

Manage recorded queries

Recorded queries can be paused/activated and deleted from the Recorded queries tab in Preferences. Deleting a recorded query will remove it from Grafana, but the information that was gathered in Prometheus will still be there. Pausing a recorded query will no longer gather new data points until it is resumed.

Remote write target

The remote write target is the Prometheus data source that recorded query data points are written to. You will need a Prometheus with remote write enabled and you will need to create a data source for this Prometheus.

The remote write target can be edited by clicking Edit Remote Write Target in the upper right on the Recorded Queries tab in Preferences. Select the Prometheus data source that has remote write enabled and enter the remote write path.

Settings updates at runtime

Fri, 07 Mar 2025 11:34:44 +0100

Settings updates at runtime

Note: Available in Grafana Enterprise version 8.0 and later.

By updating settings at runtime, you can update Grafana settings without needing to restart the Grafana server.

Updates that happen at runtime are stored in the database and override settings from the other sources (arguments, environment variables, settings file, etc). Therefore, every time a specific setting key is removed at runtime, the value used for that key is the inherited one from the other sources in the reverse order of precedence (arguments > environment variables > settings file), being the application default the value used when no one provided through one of these, at least.

Currently, it only supports updates on the auth.saml section.

Update settings via the API

You can update settings through the Admin API.

When you submit a settings update via API, Grafana verifies if the given settings updates are allowed and valid. If they are, then Grafana stores the settings in the database and reloads Grafana services with no need to restart the instance.

So, the payload of a PUT request to the update settings endpoint (/api/admin/settings) should contain (either one or both):

An updates map with a key, and a value per section you want to set.
A removals list with keys per section you want to unset.

For example, if you provide the following updates:

{
  "updates": {
    "auth.saml": {
      "enabled": "true",
      "single_logout": "false"
    }
  }
}

it would enable SAML and disable single logouts. And, if you provide the following removals:

{
  "auth.saml": ["allow_idp_initiated"]
}

it would remove the key/value setting identified by allow_idp_initiated within the auth.saml. So, the SAML service would be reloaded and that value would be inherited for either (settings .ini file, environment variable, command line arguments or any other accepted mechanism to provide configuration).

Therefore, the complete HTTP payload would looks like:

{
  "updates": {
    "auth.saml": {
      "enabled": "true",
      "single_logout": "false"
    }
  },
  "removals": {
    "auth.saml": ["allow_idp_initiated"]
  }
}

In case any of these settings cannot be overridden nor valid, it would return an error and these settings won’t be persisted into the database.

Background job (high availability set-ups)

Grafana Enterprise has a built-in scheduled background job that looks into the database every minute for settings updates. If there are updates, it reloads the Grafana services affected by the detected changes.

The background job synchronizes settings between instances in high availability set-ups. So, after you perform some changes through the HTTP API, then the other instances are synchronized through the database and the background job.

Control access with role-based access control

If you have role-based access control enabled, you can control who can read or update settings. Refer to the Admin API for more information.

Reporting

Fri, 07 Mar 2025 11:34:44 +0100

Reporting

Reporting allows 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 Pro and Advanced and in Grafana Enterprise.

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.

Any changes you make to a dashboard used in a report are reflected the next time the report is sent. For example, if you change the time range in the dashboard, then the time range in the report changes as well.

Requirements

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 is enabled, you need to have the relevant Permissions to create and manage reports.

Create or update a report

Only organization admins can create reports by default. You can customize who can create reports with Role-based access control.

Click on the Reports icon in the side navigation menu. The Reports tab allows you to view, create, and update your reports. The report form has a multi-step layout. The steps do not need to be completed in succession and can be skipped over by clicking a step name.
Select report dashboard.
- Source dashboard - Select the dashboard to generate the report from.
- Time range - (optional) Use custom time range for the report. For more information, refer to Report time range.
- Add another dashboard - Add more than one dashboard to the report.
Format 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.
- If you selected the PDF format option:
  - Select an orientation for the report: Portrait or Landscape.
  - Select a layout for the generated report: Simple or Grid. The simple layout renders each panel as full-width across the PDF. The grid layout renders the PDF with the same panel arrangement and width as the source dashboard.
  - Click Preview PDF to view a rendered PDF with the options you selected.
Schedule report.
- Enter scheduling information. Options vary depending on the frequency selected.
Enter report information. All fields are required unless otherwise indicated.
- Report name - Name of the report as you want it to appear in the Reports list. It’s also used as the email subject.
- Recipients - Enter the emails of the people or teams that you want to receive the report, separated by commas or semicolons.
- Reply to - (optional) The address that will appear in the Reply to field of the email.
- Message - (optional) Message body in the email with the report.
- Include a dashboard link - Include a link to the dashboard from within the report email.
- Send test email to verify that the whole configuration is working as expected. You can choose to send this email to the recipients configured for the report, or to a different set of email addresses only used for testing.
Preview and save the report.

Choose template variables

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 Pro and Advanced.

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.

Note: The query variables saved with a report might go out of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that happens, the selected variables will need to 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 will stay up-to-date as new values are added.

Render a report with panels or rows set to repeat by a variable

Note: Available in Grafana Enterprise version 8.0 and later, and Grafana Cloud Pro and Advanced.

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 section.

Caveats:

Rendering repeating panels for dynamic variable types (e.g. query variables) with selected All value is currently not supported. As a workaround, it is possible to individually select all the values instead.
If you select different template variables in a report for a dashboard with repeating rows, you might see empty space or missing values at the bottom of the report. This is because the dimensions of the panels from the dashboard are used to generate the report. To avoid this issue, use the dashboard’s original template variables for the report, or make a copy of the dashboard, select the new set of template variables, and generate a report based on the copied dashboard.
Rendering of the repeating panels inside collapsed rows in reports is not supported.

Report time range

Note: You can set custom report time ranges in Grafana Enterprise 7.2+ and Grafana Cloud Pro and Advanced.

By default, reports use the saved time range of the dashboard. Changing the time range of the report can be done by:

Saving a modified time range to the dashboard.
Setting a time range via Time range field in the report form. If specified, then this custom time range overrides the one from the report’s dashboard.

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 will 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.

Layout and orientation

We’re actively developing new report layout options. Contact us to get involved in the design process.

Layout	Orientation	Support	Description
Simple	Portrait	v6.4+	Generates an A4 page in portrait mode with three panels per page.
Simple	Landscape	v6.7+	Generates an A4 page in landscape mode with a single panel per page.
Grid	Portrait	v7.2+	Generates an A4 page in portrait mode with panels arranged in the same way as at the original dashboard.
Grid	Landscape	v7.2+	Generates an A4 page in landscape mode with panels arranged in the same way as at the original dashboard.

CSV export

Note: Available in Grafana Enterprise 8+ with the Grafana image renderer plugin v3.0+, and Grafana Cloud Pro and Advanced.

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 won’t be sent to avoid email servers to reject the email. You can increase or decrease this limit in the reporting configuration.

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 setting. This setting also affects how long a renderer PNG file should be stored.

Scheduling

Note: Available in Grafana Enterprise version 8.0 and later, and Grafana Cloud Pro and Advanced. 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.

Send now or schedule for later

Send now sends the report immediately after you save it. To stop sending the report at some point in the future, add an end date. If you leave the end date empty, the report is sent out indefinitely.
Send later schedules a report for a later date. Thus, the start date and time are required fields. If you leave the end date empty, the report is sent out indefinitely.

Send only from Monday to Friday

For reports that have an hourly or daily frequency, you can choose to send them only from Monday to Friday.

Send on the last day of the month

When you schedule a report with a monthly frequency, and set the start date between the 29th and the 31st of the month, the report is only sent during the months that have those dates. If you want the report to be sent every month, select the Send on the last day of the month option instead. This way, the report is sent on the last day of every month regardless of how many days there are in any given month.

Send a test email

Note: Available in Grafana Enterprise version 7.0 and later, and Grafana Cloud Pro and Advanced.

In the report, click Send test email.
In the Email field, enter the email address or addresses that you want to test, separated by semicolon. If you want to use email addresses from the report, then select the Use emails from report check box.
Click Send.

The last saved version of the report will be sent to selected emails. You can use this to verify emails are working and to make sure the report is generated and displayed as you expect.

Pause a report

Note: Available in Grafana Enterprise version 8.0 and later, and Grafana Cloud Pro and Advanced.

You can pause sending of 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

Note: Available in Grafana Enterprise version 9.0 and later, and Grafana Cloud Pro and Advanced.

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. Note: you cannot add the same dashboard to a report twice.

Embed a dashboard as an image into a report

Note: Available in Grafana Enterprise version 9.0 and later, and Grafana Cloud Pro and Advanced.

You can send a report email with an image of the dashboard embedded in the email itself, 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.

Send a report via the API

You can send reports programmatically with the send report endpoint in the HTTP APIs.

Rendering configuration

When generating reports, each panel renders separately before being collected in a PDF. The per-panel rendering timeout and number of concurrently rendered panels can be configured.

To make a panel more legible, you can set a scale factor for the rendered images. However, a higher scale factor increases the file size of the generated PDF.

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 file.

[reporting]
# Set timeout for each panel rendering request
rendering_timeout = 10s
# Set maximum number of concurrent calls to the rendering service
concurrent_render_limit = 4
# Set the scale factor for rendering images. 2 is enough for monitor resolutions
# 4 would be better for printed material. Setting a higher value affects performance and memory
image_scale_factor = 2
# Set the maximum file size in megabytes for the CSV attachments
max_attachment_size_mb = 10
# Path to the directory containing font files
fonts_path =
# Name of the TrueType font file with regular style
font_regular = DejaVuSansCondensed.ttf
# Name of the TrueType font file with bold style
font_bold = DejaVuSansCondensed-Bold.ttf
# Name of the TrueType font file with italic style
font_italic = DejaVuSansCondensed-Oblique.ttf

Report settings

Note: Available in Grafana Enterprise version 7.2 and later, and Grafana Cloud Pro and Advanced.

You can configure organization-wide report settings in the Settings tab on the Reporting page. Settings are applied to all the reports for current organization.

You can customize the branding options.

Report branding:

Company logo URL - Company logo displayed in the report PDF. Defaults to the Grafana logo.

Email branding:

Company logo URL - Company logo displayed in the report PDF. Defaults to the Grafana logo.
Email footer - Toggle to enable report email footer. Select Sent by or None.
Footer link text - Text for the link in the report email footer. Defaults to “Grafana”.
Footer link URL - Link for the report email footer.

Troubleshoot reporting

To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to Configuration for more information.

[log]
filters = report:debug

Export dashboard as PDF

Fri, 07 Mar 2025 11:34:44 +0100

Export dashboard as PDF

You can generate and save PDF files from any of your dashboards.

Note: Available in Grafana Enterprise.

In the upper right corner of the dashboard that you want to export as PDF, click the Share dashboard icon.
On the PDF tab, select the layout option for exported dashboard: Portrait or Landscape.
Click Save as PDF to render the dashboard as a PDF file. Grafana opens the PDF file in a new window or browser tab.