Data source-managed alert rule |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| Create alert rules
that query [data sources supporting Alerting](#supported-data-sources) | Yes | No. Only query Prometheus-based data sources. |
+| Create alert rules
that query [data sources supporting Alerting](#supported-data-sources) | Yes | Only supports creating rules for Mimir and Loki. |
| Mix and match data sources | Yes | No |
| Add [expressions](ref:expression-queries) to transform
your data and set [alert conditions](ref:alert-condition) | Yes | No |
| Use [images in alert notifications](ref:notification-images) | Yes | No |
diff --git a/docs/sources/alerting/fundamentals/notifications/group-alert-notifications.md b/docs/sources/alerting/fundamentals/notifications/group-alert-notifications.md
index 70a6c7ab1e6..8e2eab652e8 100644
--- a/docs/sources/alerting/fundamentals/notifications/group-alert-notifications.md
+++ b/docs/sources/alerting/fundamentals/notifications/group-alert-notifications.md
@@ -35,6 +35,10 @@ refs:
Grouping in Grafana Alerting allows you to batch relevant alerts together into a smaller number of notifications. This is particularly important if notifications are delivered to first-responders, such as engineers on-call, where receiving lots of notifications in a short period of time can be overwhelming. In some cases, it can negatively impact a first-responders ability to respond to an incident. For example, consider a large outage where many of your systems are down. In this case, grouping can be the difference between receiving 1 phone call and 100 phone calls.
+{{< admonition type="tip" >}}
+For a practical example of grouping, refer to our [Getting Started with Grouping tutorial](https://grafana.com/tutorials/alerting-get-started-pt3/).
+{{< /admonition >}}
+
## Group notifications
Grouping combines similar alert instances within a specific period into a single notification, reducing alert noise.
diff --git a/docs/sources/alerting/fundamentals/notifications/notification-policies.md b/docs/sources/alerting/fundamentals/notifications/notification-policies.md
index 11943f85e66..48a4bd70e37 100644
--- a/docs/sources/alerting/fundamentals/notifications/notification-policies.md
+++ b/docs/sources/alerting/fundamentals/notifications/notification-policies.md
@@ -75,6 +75,10 @@ Each policy consists of a set of label matchers (0 or more) that specify which a
{{< figure src="/media/docs/alerting/notification-routing.png" max-width="750px" caption="Matching alert instances with notification policies" alt="Example of a notification policy tree" >}}
+{{< admonition type="tip" >}}
+For a practical example of routing with notification policies, refer to our [Getting Started with Alert Instances and Notification Routing tutorial](https://grafana.com/tutorials/alerting-get-started-pt4/).
+{{< /admonition >}}
+
## Routing
To determine which notification policies handle an alert instance, the system looks for matching policies starting from the top of the tree—beginning with the default notification policy.
diff --git a/docs/sources/alerting/fundamentals/templates.md b/docs/sources/alerting/fundamentals/templates.md
index 8dabe94816c..3b2fa4de8c5 100644
--- a/docs/sources/alerting/fundamentals/templates.md
+++ b/docs/sources/alerting/fundamentals/templates.md
@@ -69,6 +69,10 @@ In Grafana, you have various options to template your alert notification message
- Template notifications when you want to customize the appearance and information of your notifications.
- Avoid using notification templates to add extra information to alert instances—use annotations instead.
+{{< admonition type="tip" >}}
+For a practical example of templating, refer to our [Getting Started with Templating tutorial](https://grafana.com/tutorials/alerting-get-started-pt4/).
+{{< /admonition >}}
+
This diagram illustrates the entire templating process, from querying labels and templating the alert summary and notification to the final alert notification message.
{{< figure src="/media/docs/alerting/how-notification-templates-works.png" max-width="1200px" caption="How templating works" >}}
diff --git a/docs/sources/alerting/monitor-status/view-alert-state.md b/docs/sources/alerting/monitor-status/view-alert-state.md
index e485482e36e..1c92f5ac7cd 100644
--- a/docs/sources/alerting/monitor-status/view-alert-state.md
+++ b/docs/sources/alerting/monitor-status/view-alert-state.md
@@ -45,6 +45,16 @@ refs:
destination: /docs/grafana/
/alerting/fundamentals/alert-rule-evaluation/state-and-health/#alert-instance-state
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rule-evaluation/state-and-health/#alert-instance-state
+ alert-instance-state:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//alerting/fundamentals/alert-rule-evaluation/state-and-health/#alert-instance-state
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rule-evaluation/state-and-health/#alert-instance-state
+ alert-rule-health:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//alerting/fundamentals/alert-rule-evaluation/state-and-health/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rule-evaluation/state-and-health/
---
# View alert state
diff --git a/docs/sources/cli.md b/docs/sources/cli.md
index 3352c8e85ba..3a0df07cbd2 100644
--- a/docs/sources/cli.md
+++ b/docs/sources/cli.md
@@ -17,7 +17,9 @@ weight: 400
# Grafana CLI
-Grafana CLI is a small executable that is bundled with Grafana server. It can be executed on the same machine Grafana server is running on. Grafana CLI has `plugins` and `admin` commands, as well as global options.
+Grafana CLI is a small executable that's bundled with Grafana server.
+You can run it on the same machine Grafana server is running on.
+Grafana CLI has `plugins` and `admin` commands, as well as global options.
To list all commands and options:
@@ -25,13 +27,17 @@ To list all commands and options:
grafana cli -h
```
-## Invoking Grafana CLI
+## Run Grafana CLI
-To invoke Grafana CLI, add the path to the grafana binaries in your `PATH` environment variable. Alternately, if your current directory is the `bin` directory, use `./grafana cli`. Otherwise, you can specify full path to the CLI. For example, on Linux `/usr/share/grafana/bin/grafana` and on Windows `C:\Program Files\GrafanaLabs\grafana\bin\grafana.exe`, and invoke it with `grafana cli`.
+To run Grafana CLI, add the path to the Grafana binaries in your `PATH` environment variable.
+Alternately, if your current directory is the `bin` directory, run `./grafana cli`.
+Otherwise, you can specify full path to the binary.
+For example, on Linux `/usr/share/grafana/bin/grafana` and on Windows `C:\Program Files\GrafanaLabs\grafana\bin\grafana.exe`, and run it with `grafana cli`.
-{{% admonition type="note" %}}
-Some commands, such as installing or removing plugins, require `sudo` on Linux. If you are on Windows, run Windows PowerShell as Administrator.
-{{% /admonition %}}
+{{< admonition type="note" >}}
+Some commands, such as installing or removing plugins, require `sudo` on Linux.
+If you're on Windows, run Windows PowerShell as Administrator.
+{{< /admonition >}}
## Grafana CLI command syntax
diff --git a/docs/sources/dashboards/_index.md b/docs/sources/dashboards/_index.md
index bd2fc73180e..37b0e0a1f83 100644
--- a/docs/sources/dashboards/_index.md
+++ b/docs/sources/dashboards/_index.md
@@ -15,13 +15,13 @@ hero:
width: 110
height: 110
description: >-
- Dashboards allow you to query, transform, visualize, and understand your data no matter where it’s stored.
+ Dashboards allow you to query, transform, visualize, and understand your data no matter where it's stored.
cards:
title_class: pt-0 lh-1
items:
- title: Build dashboards
href: ./build-dashboards/
- description: Get step-by-step directions for how to create or import your first dashboard and modify dashboard settings. Learn about reusable library panels, dashboard links, annotatations, and dashboard JSON.
+ description: Get step-by-step directions for how to create or import your first dashboard and modify dashboard settings. Learn about reusable library panels, dashboard links, annotations, and dashboard JSON.
height: 24
- title: Manage dashboards
href: ./manage-dashboards/
@@ -63,7 +63,7 @@ A data source can be an SQL database, Grafana Loki, Grafana Mimir, or a JSON-bas
Queries allow you to reduce the entirety of your data to a specific dataset, providing a more manageable visualization. Since data sources have their own distinct query languages, Grafana dashboards provide you with a query editor to accommodate these differences.
-A panel is the container that displays the visualization and provides you with various controls to manipulate it. Panel options let you customize many aspects of a visualization and the options differ based on which visualization you select. When the data format in a visualization doesn’t meet your requirements, you can apply a transformation that manipulates the data returned by a query.
+A panel is the container that displays the visualization and provides you with various controls to manipulate it. Panel options let you customize many aspects of a visualization and the options differ based on which visualization you select. When the data format in a visualization doesn't meet your requirements, you can apply a transformation that manipulates the data returned by a query.
With 150+ data source plugins, you can unify all your data sources into a single dashboard to streamline data monitoring and troubleshooting. With Grafana, you can translate, transform, and visualize data in flexible and versatile dashboards.
diff --git a/docs/sources/dashboards/assess-dashboard-usage/index.md b/docs/sources/dashboards/assess-dashboard-usage/index.md
index 5c0c46a2e8a..e989ec12470 100644
--- a/docs/sources/dashboards/assess-dashboard-usage/index.md
+++ b/docs/sources/dashboards/assess-dashboard-usage/index.md
@@ -151,7 +151,7 @@ You can sort the dashboards by:
## Visualize usage insights data
-If you set up your installation to [export logs of usage insights](ref:export-logs-of-usage-insights), we've created two dashboards to help you take advantage of this data.
+If you set up your installation to [export logs of usage insights](ref:export-logs-of-usage-insights), there are two dashboards to help you take advantage of this data.
1. [Usage Insights overview](/grafana/dashboards/13785) provides a top-level perspective of user activity.
1. [Data source details](/grafana/dashboards/13786) dashboard provides a view of data source activity and health.
diff --git a/docs/sources/dashboards/build-dashboards/annotate-visualizations/index.md b/docs/sources/dashboards/build-dashboards/annotate-visualizations/index.md
index 34d5086ea22..13220b2f56a 100644
--- a/docs/sources/dashboards/build-dashboards/annotate-visualizations/index.md
+++ b/docs/sources/dashboards/build-dashboards/annotate-visualizations/index.md
@@ -74,7 +74,7 @@ To add an annotation, complete the following steps:
1. Click **Edit** in the top-right corner of the dashboard.
1. Click the panel to which you're adding the annotation.
- A context menu will appear.
+ A context menu appears.
1. In the context menu, click **Add annotation**.
@@ -82,7 +82,7 @@ To add an annotation, complete the following steps:
1. Click **Save dashboard**.
1. Click **Exit edit**.
-Alternatively, to add an annotation, press Ctrl/Cmd and click the panel, and the **Add annotation** context menu will appear.
+Alternatively, to add an annotation, press Ctrl/Cmd and click the panel, and the **Add annotation** context menu appears.
### Add a region annotation
@@ -132,7 +132,7 @@ To add a new annotation query to a dashboard, follow these steps:
1. Enter a name for the annotation query.
- This name is given to the toggle (checkbox) that will allow you to enable/disable showing annotation events from this query.
+ This name is given to the toggle (checkbox) that allows you to enable/disable showing annotation events from this query.
1. Select the data source for the annotations.
@@ -158,7 +158,7 @@ To add a new annotation query to a dashboard, follow these steps:
## Built-in query
-After you add an annotation, they will still be visible. This is due to the built-in annotation query that exists on all dashboards. This annotation query will fetch all annotation events that originate from the current dashboard, which are stored in Grafana, and show them on the panel where they were created. This includes alert state history annotations.
+After you add an annotation, they are still visible. This is due to the built-in annotation query that exists on all dashboards. This annotation query fetches all annotation events that originate from the current dashboard, which are stored in Grafana, and show them on the panel where they were created. This includes alert state history annotations.
By default, the built-in annotation query uses the `-- Grafana --` special data source, and manual annotations are only supported using this data source. You can use another data source in the built-in annotation query, but you'll only be able to create automated annotations using the query editor for that data source.
@@ -182,7 +182,7 @@ You can stop annotations from being fetched and drawn by taking the following st
1. Click **Save dashboard**.
1. Click **Back to dashboard** and **Exit edit**.
-When you copy a dashboard using the **Save As** feature it will get a new dashboard id, so annotations created on the source dashboard will no longer be visible on the copy. You can still show them if you add a new **Annotation Query** and filter by tags. However, this only works if the annotations on the source dashboard had tags to filter by.
+When you copy a dashboard using the **Save As** feature it gets a new dashboard id, so annotations created on the source dashboard is no longer be visible on the copy. You can still show them if you add a new **Annotation Query** and filter by tags. However, this only works if the annotations on the source dashboard had tags to filter by.
Following are some query options specific to the built-in annotation query.
@@ -192,7 +192,7 @@ You can create new queries to fetch annotations from the built-in annotation que
Grafana also supports typeahead of existing tags, provide at least one tag.
-For example, create an annotation query name `outages` and specify a tag `outage`. This query will show all annotations (from any dashboard or via API) with the `outage` tag. If multiple tags are defined in an annotation query, then Grafana will only show annotations matching all the tags. To modify the behavior, enable `Match any`, and Grafana will show annotations that contain any one of the tags you provided.
+For example, create an annotation query name `outages` and specify a tag `outage`. This query shows all annotations (from any dashboard or via API) with the `outage` tag. If multiple tags are defined in an annotation query, then Grafana only shows annotations matching all the tags. To modify the behavior, enable `Match any`, and Grafana shows annotations that contain any one of the tags you provided.
{{< figure src="/media/docs/grafana/dashboards/screenshot-annotations-typeahead-support-10.0.png" max-width="600px" alt="Annotation query options" >}}
@@ -206,6 +206,6 @@ When adding or editing an annotation, you can define a repeating time region by
{{< figure src="/media/docs/grafana/dashboards/screenshot-annotation-timeregions-10-v2.png" max-width="600px" alt="Time regions options set to business hours" >}}
-The above configuration will produce the following result in the Time series panel:
+The above configuration produces the following result in the Time series panel:
{{< figure src="/media/docs/grafana/screenshot-grafana-10-0-timeseries-time-regions.png" max-width="600px" alt="Time series visualization with time regions business hours" >}}
diff --git a/docs/sources/dashboards/build-dashboards/best-practices/index.md b/docs/sources/dashboards/build-dashboards/best-practices/index.md
index e7710fcb03e..e67a1a87ead 100644
--- a/docs/sources/dashboards/build-dashboards/best-practices/index.md
+++ b/docs/sources/dashboards/build-dashboards/best-practices/index.md
@@ -124,7 +124,7 @@ This method is similar to the RED method, but it includes saturation.
## Dashboard management maturity model
-_Dashboard management maturity_ refers to how well-designed and efficient your dashboard ecosystem is. We recommend periodically reviewing your dashboard setup to gauge where you are and how you can improve.
+_Dashboard management maturity_ refers to how well-designed and efficient your dashboard ecosystem is. It's recommended that you periodically review your dashboard setup to gauge where you are and how you can improve.
Broadly speaking, dashboard maturity can be defined as low, medium, or high.
@@ -167,7 +167,7 @@ How can you tell you are here?
- Example of meaningful color: Blue means it's good, red means it's bad. [Thresholds](ref:thresholds) can help with that.
- Example of normalizing axes: When comparing CPU usage, measure by percentage rather than raw number, because machines can have a different number of cores. Normalizing CPU usage by the number of cores reduces cognitive load because the viewer can trust that at 100% all cores are being used, without having to know the number of CPUs.
- Directed browsing cuts down on "guessing."
- - Template variables make it harder to “just browse” randomly or aimlessly.
+ - Template variables make it harder to "just browse" randomly or aimlessly.
- Most dashboards should be linked to by alerts.
- Browsing is directed with links. For more information, refer to [Manage dashboard links](ref:manage-dashboard-links).
- Version-controlled dashboard JSON.
@@ -204,13 +204,17 @@ Keep your graphs simple and focused on answering the question that you are askin
#### Dashboards should reduce cognitive load, not add to it
-_Cognitive load_ is basically how hard you need to think about something in order to figure it out. Make your dashboard easy to interpret. Other users and future you (when you're trying to figure out what broke at 2AM) will appreciate it.
+
+
+_Cognitive load_ is basically how hard you need to think about something in order to figure it out. Make your dashboard easy to interpret. Other users and future you (when you're trying to figure out what broke at 2 AM) will appreciate it.
Ask yourself:
- Can I tell what exactly each graph represents? Is it obvious, or do I have to think about it?
- If I show this to someone else, how long will it take them to figure it out? Will they get lost?
+
+
#### Have a monitoring strategy
It's easy to make new dashboards. It's harder to optimize dashboard creation and adhere to a plan, but it's worth it. This strategy should govern both your overall dashboard scheme and enforce consistency in individual dashboard design.
@@ -233,9 +237,9 @@ Once you have a strategy or design guidelines, write them down to help maintain
- Use the left and right Y-axes when displaying time series with different units or ranges.
- Add documentation to dashboards and panels.
- To add documentation to a dashboard, add a [Text panel visualization](ref:text-panel-visualization) to the dashboard. Record things like the purpose of the dashboard, useful resource links, and any instructions users might need to interact with the dashboard. Check out this [Wikimedia example](https://grafana.wikimedia.org/d/000000066/resourceloader?orgId=1).
- - To add documentation to a panel, edit the panel settings and add a description. Any text you add will appear if you hover your cursor over the small `i` in the top left corner of the panel.
+ - To add documentation to a panel, edit the panel settings and add a description. Any text you add appears if you hover your cursor over the small `i` in the top left corner of the panel.
- Reuse your dashboards and enforce consistency by using [templates and variables](ref:templates-and-variables).
-- Be careful with stacking graph data. The visualizations can be misleading, and hide important data. We recommend turning it off in most cases.
+- Be careful with stacking graph data. The visualizations can be misleading, and hide important data. It's recommended that you turn it off in most cases.
## Best practices for managing dashboards
@@ -257,9 +261,9 @@ What is your dashboard maturity level? Analyze your current dashboard setup and
### Best practices to follow
-- Avoid dashboard sprawl, meaning the uncontrolled growth of dashboards. Dashboard sprawl negatively affects time to find the right dashboard. Duplicating dashboards and changing “one thing” (worse: keeping original tags) is the easiest kind of sprawl.
+- Avoid dashboard sprawl, meaning the uncontrolled growth of dashboards. Dashboard sprawl negatively affects time to find the right dashboard. Duplicating dashboards and changing "one thing" (worse: keeping original tags) is the easiest kind of sprawl.
- Periodically review the dashboards and remove unnecessary ones.
- - If you create a temporary dashboard, perhaps to test something, prefix the name with `TEST: `. Delete the dashboard when you are finished.
+ - If you create a temporary dashboard, perhaps to test something, prefix the name with `TEST:`. Delete the dashboard when you are finished.
- Copying dashboards with no significant changes is not a good idea.
- You miss out on updates to the original dashboard, such as documentation changes, bug fixes, or additions to metrics.
- In many cases copies are being made to simply customize the view by setting template parameters. This should instead be done by maintaining a link to the master dashboard and customizing the view with [URL parameters](ref:url-parameters).
diff --git a/docs/sources/dashboards/build-dashboards/create-dashboard-url-variables/index.md b/docs/sources/dashboards/build-dashboards/create-dashboard-url-variables/index.md
index 5bf7de58165..49639f74d01 100644
--- a/docs/sources/dashboards/build-dashboards/create-dashboard-url-variables/index.md
+++ b/docs/sources/dashboards/build-dashboards/create-dashboard-url-variables/index.md
@@ -100,7 +100,7 @@ When sharing URLs with ad hoc filters, remember to encode the URL. In the preced
### Example
-[This dashboard in Grafana Play](https://play.grafana.org/d/000000002/influxdb-templated?orgId=1&var-datacenter=America&var-host=All&var-summarize=1m&var-adhoc=datacenter%7C%3D%7CAmerica) passes the ad hoc filter variable `adhoc` with the filter value `datacenter = America`.
+[This dashboard in Grafana Play](https://play.grafana.org/d/p-k6QtkGz/template-redux?var-interval=$__auto&orgId=1&from=now-5m&to=now&timezone=utc&var-query=$__all&var-query2=$__all&var-query3=$__all&var-Filters=job%7C%3D%7Cmetrictank%2Ftsdb-gw&var-textbox=foo&var-custom=lisa&var-datasource=grafanacloud-demoinfra-prom) passes the ad hoc filter variable `Filters` with the filter value `job = metrictank/tsdb-gw`.
## Time range control using the URL
diff --git a/docs/sources/dashboards/create-reports/_index.md b/docs/sources/dashboards/create-reports/_index.md
new file mode 100644
index 00000000000..b29c4fe6f72
--- /dev/null
+++ b/docs/sources/dashboards/create-reports/_index.md
@@ -0,0 +1,351 @@
+---
+aliases:
+ - ../administration/reports/ # /docs/grafana/latest/administration/reports/
+ - ../enterprise/export-pdf/ # /docs/grafana/latest/enterprise/export-pdf/
+ - ../enterprise/reporting/ # /docs/grafana/latest/enterprise/reporting/
+ - ../panels/create-reports/ # /docs/grafana/latest/panels/create-reports/
+ - reporting/ # /docs/grafana/latest/dashboards/reporting/
+keywords:
+ - grafana
+ - reporting
+ - export
+ - pdf
+labels:
+ products:
+ - cloud
+ - enterprise
+menuTitle: Reporting
+title: Create and manage reports
+description: Generate and share PDF reports from your Grafana dashboards
+weight: 600
+refs:
+ repeat-panels-or-rows:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//panels-visualizations/configure-panel-options/#configure-repeating-panels
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-panel-options/#configure-repeating-panels
+ http-apis:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//developers/http_api/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//developers/http_api/
+ image-rendering:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/image-rendering/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/image-rendering/
+ rbac:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//administration/roles-and-permissions/access-control/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//administration/roles-and-permissions/access-control/
+ permission:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//administration/roles-and-permissions/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//administration/roles-and-permissions/
+ role-based-access-control:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//administration/roles-and-permissions/access-control/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//administration/roles-and-permissions/access-control/
+ configuration:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/configure-grafana/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/configure-grafana/
+ image-rendering:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/image-rendering/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/image-rendering/
+ templates-and-variables:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/variables/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/dashboards/variables/
+ grafana-enterprise:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//introduction/grafana-enterprise/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//introduction/grafana-enterprise/
+ configuration:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#filters
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#filters
+ time-range-controls:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/use-dashboards/#set-dashboard-time-range
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/dashboards/use-dashboards/#set-dashboard-time-range
+ send-report:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//developers/http_api/reporting/#send-a-report
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/reporting/#send-a-report
+ smtp:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#smtp
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#smtp
+ temp-data-lifetime:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#temp_data_lifetime
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#temp_data_lifetime
+ rendering-configuration:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/create-reports/report-settings/#rendering-configuration
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//dashboards/create-reports/report-settings/#rendering-configuration
+ reporting-configuration:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/configure-grafana/enterprise-configuration/#reporting
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/configure-grafana/enterprise-configuration/#reporting
+
+---
+
+# Create and manage reports
+
+**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 and in Grafana Enterprise.
+
+{{< admonition type="note" >}}
+If you have [Role-based access control](ref: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.
+{{< /admonition >}}
+
+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 also changes, unless you've configured a custom time range.
+
+## Requirements
+
+- SMTP must be configured for reports to be sent. Refer to [SMTP](ref:smtp) in [Configuration](ref:configuration) for more information.
+- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering](ref:image-rendering) for more information.
+
+### Rendering configuration
+
+When generating reports, each panel renders separately before being collected in a PDF. You can configure the per-panel rendering timeout and number of concurrently rendered panels.
+
+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 [reporting configuration](ref:reporting-configuration) of the `ini` file for Enterprise Grafana.
+
+## Access control
+
+When [RBAC](ref:rbac) is enabled, you need to have the relevant [Permissions](ref:permission) to create and manage reports.
+
+## Create a report
+
+Only organization administrators can create reports by default. You can customize who can create reports with [Role-based access control](ref:role-based-access-control).
+
+The report creation process is multi-step, but you don't need to complete these steps in order and you can skip steps by clicking a step name at the top of the page:
+
+
+
+To create a report, follow these steps:
+
+1. Click **Dashboards > Reporting** in the main menu.
+1. Click **+ Create a new report**.
+1. Complete the report steps, as needed; you don't need to complete these steps in order and you can skip steps by clicking a step name at the top of the page:
+ - [Select dashboard](#1-select-dashboard)
+ - [Format report](#2-format-report)
+ - [Schedule](#3-schedule)
+ - [Share](#4-share)
+ - [Confirm](#5-confirm)
+1. Click one of the following buttons in the top-right corner of the screen:
+ - **Send now** or **Schedule send** - The report is sent according the schedule you've set.
+ - **Save as draft** - You can save a draft at any point during the report creation or update process, even if it's missing required fields. The report won't be sent according to its schedule while it's a draft.
+ - **Discard** - Delete the report draft. This action can't be reversed.
+
+### 1. Select dashboard
+
+At this step, select the dashboard or dashboards on which the report is based, as well as the variables and time range for those dashboards. The options are:
+
+
+
+| Option | Description |
+| ------ | ----------- |
+| Source dashboard | Select the dashboard from which you want to generate the report. |
+| [Template variables (optional)](#template-variables) | Select the variable values for the selected dashboard. This option is only displayed if the dashboard has variables. |
+| [Time range (optional)](#time-range) | By default, reports use the saved time range of the dashboard. Optionally, you can change the time range of the report. |
+| Add another dashboard | Add more dashboards to the 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 can't add the same dashboard to a report multiple times. |
+
+
+
+#### Template variables
+
+This option is only displayed if the dashboard has variables.
+
+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](ref:templates-and-variables) section.
+
+The query variables saved with a report might become 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 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.
+
+#### Time range
+
+By default, reports use the saved time range of the dashboard. Optionally, you can change the time range of the report by:
+
+- Saving a modified time range to the dashboard. Changing the dashboard time range without saving it doesn't change the time zone of the report.
+- Setting a time range via the **Time range** field in the report form. If specified, the custom time range overrides the time range from the report's dashboard.
+
+The page header of the report displays the time range for the dashboard's data queries.
+
+##### Report time zones
+
+Reports use the time zone of the dashboard from which they’re generated. You can control the time zone for your reports by setting the dashboard to a specific time zone. Note that this affects the display of the dashboard for all users.
+
+If a dashboard has the **Browser Time** setting, the reports generated from that dashboard use the time zone of the Grafana server. As a result, this time zone might not match the time zone of users creating or receiving the report.
+
+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](ref:time-range-controls).
+
+### 2. Format report
+
+At this step, set the report formatting options. You can select multiple options:
+
+- [Attach the report as a PDF](#attach-the-report-as-a-pdf)
+- [Include table data as PDF appendix](#table-data-in-pdf) (Public preview only)
+- [Embed a dashboard image in the email](#embed-a-dashboard-as-an-image-in-the-email)
+- [Attach a CSV file of the table panel data](#attach-a-csv-file-of-the-table-panel-data)
+- [Attach a separate PDF of table data](#table-data-in-pdf) (Public preview only)
+
+#### Attach the report as a PDF
+
+If you selected the PDF format option, under the **Style the PDF** section, set the following options:
+
+- **Show template variables** - Click the checkbox to select this option.
+- **Orientation** - Set the report orientation in **Portrait** or **Landscape**. Refer to the [Layout and orientation table](#layout-and-orientation) to see examples.
+- **Layout** - Select one of the following:
+ - **Simple** - Renders each panel as full-width across the PDF. Refer to the [Layout and orientation table](#layout-and-orientation) to see examples.
+ - **Grid** - Renders the PDF with the same panel arrangement and width as the source dashboard. Refer to the [Layout and orientation table](#layout-and-orientation) to see examples.
+- **Zoom** - Zoom in to enlarge text in your PDF, or zoom out to see more data (like table columns) per panel.
+
+Click **Preview PDF** in the top-right corner of the screen to view a rendered PDF with the options you selected.
+
+##### Layout and orientation
+
+
+
+| Layout | Orientation | Description | Preview |
+| ------ | ----------- | --------------------------------------------------------------------------------------------------------- | ------------ |
+| Simple | Portrait | Generates an A4 page in portrait mode with three panels per page. | {{< figure src="/static/img/docs/enterprise/reports_portrait_preview.png" max-width="500px" alt="Simple layout in portrait" >}} |
+| Simple | Landscape | Generates an A4 page in landscape mode with a single panel per page. | {{< figure src="/static/img/docs/enterprise/reports_landscape_preview.png" max-width="500px" alt="Simple layout in landscape" >}} |
+| Grid | Portrait | Generates an A4 page in portrait mode with panels arranged in the same way as at the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_portrait_preview.png" max-width="500px" alt="Grid layout in portrait" >}} |
+| Grid | Landscape | Generates an A4 page in landscape mode with panels arranged in the same way as in the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_landscape_preview.png" max-width="500px" alt="Grid layout in landscape" >}} |
+
+
+
+#### Embed a dashboard as an image in the email
+
+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.
+
+#### Attach a CSV file of the table panel data
+
+{{< admonition type="note" >}}
+To use this feature in Grafana Enterprise, you must have [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0.
+{{< /admonition >}}
+
+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, CSV files 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](ref:rendering-configuration).
+
+This feature relies on the same plugin that supports the [image rendering](ref: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](ref:temp-data-lifetime) setting. This setting also affects how long a renderer PNG file should be stored.
+
+Click **Download CSV** in the top-right corner of the screen to see the file.
+
+#### Table data in PDF
+
+{{% admonition type="note" %}}
+Available in public preview (`pdfTables` feature toggle) in [Grafana Enterprise](ref:grafana-enterprise) v10.3+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, as well as [Grafana Cloud](/docs/grafana-cloud/).
+{{% /admonition %}}
+
+When there's more data in your table visualizations than can be shown in the dashboard PDF, you can select one of these two options to access all table visualization data as PDF in your reports:
+
+- **Include table data as PDF appendix** - Adds an appendix to the main dashboard PDF.
+- **Attach a separate PDF of table data** - Generates a separate PDF file.
+
+This feature relies on the same plugin that supports the [image rendering](ref:image-rendering) features.
+
+### 3. Schedule
+
+At this step, set scheduling information. Options vary depending on the frequency you select.
+
+
+
+| Option | Description |
+| ------ | ----------- |
+| Frequency | 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 using the API. |
+| Time | Choose one of the following:- **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.
- **Send later** schedules a report for a later date. When you select this option, the required **Start date**, **Start time**, and **Time zone** options are displayed.
|
+| End date | 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 this 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. |
+
+
+
+### 4. Share
+
+At this step, enter information related to sharing the report:
+
+
+
+| Option | Description |
+| ------ | ----------- |
+| Report name | Name of the report as you want it to appear in the **Reports** list. The report name also populates the email subject line. |
+| Recipients | Enter the email addresses of the people or teams that you want to receive the report, separated by commas or semicolons. |
+| Reply-to email address | The address that appears in the **Reply to** field of the email. |
+| Message | Message body in the email with the report. |
+| Include a dashboard link | Include a link to the dashboard from within the report email. |
+
+
+
+Click **Send test email** in the top-right corner of the screen to verify that the configuration works as expected and to verify that emails are working. 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. The last saved version of the report will be sent to selected emails.
+
+### 5. Confirm
+
+At this step, the confirmation page displays all your the settings. Review them and confirm that they're correct or click the provided **Edit** links for each section to make updates.
+
+Then, click **Send now** or **Schedule send**.
+
+You can also save the report as a draft or discard it. Discarding the report is irreversible.
+
+## Send a report using the API
+
+You can send reports programmatically with the [send report](ref:send-report) endpoint in the [HTTP APIs](ref:http-apis).
+
+## Manage reports
+
+On the **Reports** page, you can view and manage your existing reports or create new ones.
+
+
+
+### Edit
+
+To edit a report, follow these steps:
+
+1. In the main menu, click **Dashboards > Reporting**.
+1. Click the row of the report you want to update.
+1. Click the **Edit report** button in the top-right hand corner or click the **Edit** link for a specific section to go to that one directly.
+1. When you've finished making changes, click **Confirm** at the top of the screen to go to the last step.
+1. Click **Update report**.
+
+### Pause or resume a report
+
+You can pause and resume sending reports from the report list view. To do this, follow these steps:
+
+1. In the main menu, click **Dashboards > Reporting**.
+1. On the row of the report you want to update, do one of the following:
+
+ - Click the pause icon - The report won't be sent according to its schedule until it's resumed.
+ - Click the resume icon - The report resumes on its previous schedule.
+
+## Troubleshoot Reporting
+
+To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration](ref:configuration) for more information.
+
+```bash
+[log]
+filters = report:debug
+```
diff --git a/docs/sources/dashboards/create-reports/index.md b/docs/sources/dashboards/create-reports/index.md
deleted file mode 100644
index 07c97cac575..00000000000
--- a/docs/sources/dashboards/create-reports/index.md
+++ /dev/null
@@ -1,363 +0,0 @@
----
-aliases:
- - ../administration/reports/ # /docs/grafana/latest/administration/reports/
- - ../enterprise/export-pdf/ # /docs/grafana/latest/enterprise/export-pdf/
- - ../enterprise/reporting/ # /docs/grafana/latest/enterprise/reporting/
- - ../panels/create-reports/ # /docs/grafana/latest/panels/create-reports/
- - reporting/ # /docs/grafana/latest/dashboards/reporting/
-keywords:
- - grafana
- - reporting
- - export
- - pdf
-labels:
- products:
- - cloud
- - enterprise
-menuTitle: Reporting
-title: Create and manage reports
-description: Generate and share PDF reports from your Grafana dashboards
-weight: 600
-refs:
- repeat-panels-or-rows:
- - pattern: /docs/grafana/
- destination: /docs/grafana//panels-visualizations/configure-panel-options/#configure-repeating-rows-or-panels
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana-cloud/visualizations/panels-visualizations/configure-panel-options/#configure-repeating-rows-or-panels
- http-apis:
- - pattern: /docs/grafana/
- destination: /docs/grafana//developers/http_api/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//developers/http_api/
- image-rendering:
- - pattern: /docs/grafana/
- destination: /docs/grafana//setup-grafana/image-rendering/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//setup-grafana/image-rendering/
- rbac:
- - pattern: /docs/grafana/
- destination: /docs/grafana//administration/roles-and-permissions/access-control/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//administration/roles-and-permissions/access-control/
- permission:
- - pattern: /docs/grafana/
- destination: /docs/grafana//administration/roles-and-permissions/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//administration/roles-and-permissions/
- role-based-access-control:
- - pattern: /docs/grafana/
- destination: /docs/grafana//administration/roles-and-permissions/access-control/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//administration/roles-and-permissions/access-control/
- configuration:
- - pattern: /docs/grafana/
- destination: /docs/grafana//setup-grafana/configure-grafana/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//setup-grafana/configure-grafana/
- image-rendering:
- - pattern: /docs/grafana/
- destination: /docs/grafana//setup-grafana/image-rendering/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//setup-grafana/image-rendering/
- templates-and-variables:
- - pattern: /docs/grafana/
- destination: /docs/grafana//dashboards/variables/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana-cloud/visualizations/dashboards/variables/
- grafana-enterprise:
- - pattern: /docs/grafana/
- destination: /docs/grafana//introduction/grafana-enterprise/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//introduction/grafana-enterprise/
- configuration:
- - pattern: /docs/grafana/
- destination: /docs/grafana//setup-grafana/configure-grafana/#filters
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//setup-grafana/configure-grafana/#filters
- time-range-controls:
- - pattern: /docs/grafana/
- destination: /docs/grafana//dashboards/use-dashboards/#set-dashboard-time-range
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana-cloud/visualizations/dashboards/use-dashboards/#set-dashboard-time-range
- send-report:
- - pattern: /docs/grafana/
- destination: /docs/grafana//developers/http_api/reporting/#send-a-report
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/reporting/#send-a-report
- smtp:
- - pattern: /docs/grafana/
- destination: /docs/grafana//setup-grafana/configure-grafana/#smtp
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//setup-grafana/configure-grafana/#smtp
- temp-data-lifetime:
- - pattern: /docs/grafana/
- destination: /docs/grafana//setup-grafana/configure-grafana/#temp-data-lifetime
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//setup-grafana/configure-grafana/#temp-data-lifetime
----
-
-# Create and manage reports
-
-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](ref: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 also changes, unless you've configured a custom time range.
-
-For information about recent improvements to the reporting UI, refer to [Grafana reporting: How we improved the UX in Grafana](https://grafana.com/blog/2022/06/29/grafana-reporting-how-we-improved-the-ux-in-grafana/).
-
-## Requirements
-
-- SMTP must be configured for reports to be sent. Refer to [SMTP](ref:smtp) in [Configuration](ref:configuration) for more information.
-- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering](ref:image-rendering) for more information.
-
-## Access control
-
-When [RBAC](ref:rbac) is enabled, you need to have the relevant [Permissions](ref:permission) 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](ref:role-based-access-control).
-
-1. Click **Dashboards > Reports** in the side navigation menu.
-
- The Reports page 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.
-
-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](#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.
- - 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.
- - Select a zoom level for the report. Zoom in to enlarge text in your PDF, or zoom out to see more data (like table columns) per panel.
- - Click **Preview PDF** to view a rendered PDF with the options you selected.
-1. Schedule report.
- - Enter scheduling information. Options vary depending on the frequency selected.
-1. 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. The report name populates the email subject line.
- - **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 appears 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 configuration works 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.
-1. Preview and save the report.
-
-### Save as draft
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) 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
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) 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](ref: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.
-{{% /admonition %}}
-
-### Render a report with panels or rows set to repeat by a variable
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) 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](ref:repeat-panels-or-rows).
-
-### Report time range
-
-> **Note:** You can set custom report time ranges in [Grafana Enterprise](ref: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:
-
-- Saving a modified time range to the dashboard. Changing the dashboard time range without saving it doesn't change the time zone of the report.
-- Setting a time range via the **Time range** field in the report form. If specified, the custom time range overrides the time range from the report's dashboard.
-
-The page header of the report displays the time range for the dashboard's data queries.
-
-#### Report time zones
-
-Reports use the time zone of the dashboard from which they’re generated. You can control the time zone for your reports by setting the dashboard to a specific time zone. Note that this affects the display of the dashboard for all users.
-
-If a dashboard has the **Browser Time** setting, the reports generated from that dashboard use the time zone of the Grafana server. As a result, this time zone might not match the time zone of users creating or receiving the report.
-
-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](ref:time-range-controls).
-
-### Layout and orientation
-
-| Layout | Orientation | Support | Description | Preview |
-| ------ | ----------- | ------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Simple | Portrait | v6.4+ | Generates an A4 page in portrait mode with three panels per page. | {{< figure src="/static/img/docs/enterprise/reports_portrait_preview.png" max-width="500px" max-height="500px" class="docs-image--no-shadow" alt="Simple layout in portrait" >}} |
-| Simple | Landscape | v6.7+ | Generates an A4 page in landscape mode with a single panel per page. | {{< figure src="/static/img/docs/enterprise/reports_landscape_preview.png" max-width="500px" class="docs-image--no-shadow" alt="Simple layout in landscape" >}} |
-| Grid | Portrait | v7.2+ | Generates an A4 page in portrait mode with panels arranged in the same way as at the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_portrait_preview.png" max-width="500px" max-height="500px" class="docs-image--no-shadow" alt="Grid layout in portrait" >}} |
-| Grid | Landscape | v7.2+ | Generates an A4 page in landscape mode with panels arranged in the same way as in the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_landscape_preview.png" max-width="500px" class="docs-image--no-shadow" alt="Grid layout in landscape" >}} |
-
-### CSV export
-
-> **Note:** Available in [Grafana Enterprise](ref: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](#rendering-configuration).
-
-This feature relies on the same plugin that supports the [image rendering](ref: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](ref:temp-data-lifetime) setting. This setting also affects how long a renderer PNG file should be stored.
-
-### Table data in PDF
-
-{{% admonition type="note" %}}
-Available in public preview (`pdfTables` feature toggle) in [Grafana Enterprise](ref:grafana-enterprise) v10.3+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud](/docs/grafana-cloud/).
-{{% /admonition %}}
-
-When there's more data in your table visualizations than can be shown in the dashboard PDF, you can select one of these two options to access all table visualization data as PDF in your reports:
-
-- **Include table data as PDF appendix** - Adds an appendix to the main dashboard PDF.
-- **Attach a separate PDF of table data** - Generates a separate PDF file.
-
-This feature relies on the same plugin that supports the [image rendering](ref:image-rendering) features.
-
-### Scheduling
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud/).
-
-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](ref:grafana-enterprise) 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.
- If you want to use email addresses from the report, then select the **Use emails from report** check box.
-1. 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](ref:grafana-enterprise) 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
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) 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
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) 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.
-
-## Export dashboard as PDF
-
-You can generate and save PDF files of any dashboard.
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) and [Grafana Cloud](/docs/grafana-cloud/).
-
-1. In the dashboard that you want to export as PDF, click the **Share** button.
-1. On the PDF tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
-1. Click **Save as PDF** to render the dashboard as a PDF file.
-
- Grafana opens the PDF file in a new window or browser tab.
-
-## Send a report via the API
-
-You can send reports programmatically with the [send report](ref:send-report) endpoint in the [HTTP APIs](ref:http-apis).
-
-## Rendering configuration
-
-When generating reports, each panel renders separately before being collected in a PDF. You can configure the per-panel rendering timeout and number of concurrently rendered panels.
-
-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](ref:configuration) file.
-
-```ini
-[reporting]
-# Use this option to enable or disable the reporting feature. When disabled, no reports are generated, and the UI is hidden. By default, reporting is enabled.
-enabled = true
-# Set timeout for the following reporting rendering requests: generating PDFs, generating embedded dashboard images for report emails, and generating attached CSV files.
-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 report email 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
-# Maximum number of times the following reporting rendering requests are retried before returning an error: generating PDFs, generating embedded dashboard images for report emails, and generating attached CSV files. To disable the retry feature, enter `0`. This is available in public preview and requires the `reportingRetries` feature toggle.
-max_retries_per_panel = 3
-# Allowed domains to receive reports. Use an asterisk (`*`) to allow all domains. Use a comma-separated list to allow multiple domains. Example: allowed_domains = grafana.com, example.org
-allowed_domains = *
-```
-
-## Report settings
-
-> **Note:** Available in [Grafana Enterprise](ref:grafana-enterprise) 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.
-
-You can customize the branding options.
-
-### Attachment settings
-
-#### PDF
-
-- **Company logo:** Company logo displayed in the report PDF. It can be configured by specifying a URL, or by uploading a file. The maximum file size is 16 MB. Defaults to the Grafana logo.
-
-- **Theme:** Theme of the PDF attached to the report. Defaults to **Light**. The selected theme is also applied to the PDFs generated when you click **Preview PDF** during report creation or select the **Export as PDF** option on a dashboard. If **Current** is selected, the PDF in the report will be in the Admin's instance theme, but the preview and exported PDFs will be in the user's instance theme.
-
-#### Embedded Image
-
-- **Theme:** Theme of the dashboard image embedded in the email. Defaults to **Dark**.
-
-### Email branding
-
-- **Company logo:** Company logo displayed in the report email. It can be configured by specifying a URL, or by uploading a file. The maximum file size is 16 MB. Defaults to the Grafana logo.
-- **Email footer:** Toggle to enable the report email footer. Select **Sent by** or **None**.
-- **Footer link text:** Text of the link in the report email footer. Defaults to `Grafana`.
-- **Footer link URL:** Link of the report email footer.
-
-Currently, the API does not allow for the simultaneous upload of files with identical names for both the email logo and report logo. You can still upload the same file for each logo separately in two distinct steps.
-
-## Troubleshoot reporting
-
-To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration](ref:configuration) for more information.
-
-```bash
-[log]
-filters = report:debug
-```
diff --git a/docs/sources/dashboards/create-reports/report-settings/index.md b/docs/sources/dashboards/create-reports/report-settings/index.md
new file mode 100644
index 00000000000..c442a4346a8
--- /dev/null
+++ b/docs/sources/dashboards/create-reports/report-settings/index.md
@@ -0,0 +1,56 @@
+---
+keywords:
+ - grafana
+ - reporting
+ - settings
+labels:
+ products:
+ - cloud
+ - enterprise
+menuTitle: Settings
+title: Reporting settings
+description: Manage organizational Reporting settings
+weight: 700
+refs:
+ grafana-enterprise:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//introduction/grafana-enterprise/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//introduction/grafana-enterprise/
+ configuration:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#filters
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//setup-grafana/configure-grafana/#filters
+---
+
+# Reporting settings
+
+You can configure organization-wide report settings and branding options in **Dashboards > Reporting > Settings**. Settings are applied to all the reports for the current organization.
+
+## Attachment settings
+
+The options in this section control the branding and theming of the report attachments.
+
+### PDF
+
+- **Company logo** - Company logo displayed in the report PDF. It can be configured by specifying a URL, or by uploading a file. The maximum file size is 16 MB. Defaults to the Grafana logo.
+
+- **Theme** - Theme of the PDF attached to the report. Defaults to **Light**. The selected theme is also applied to the PDFs generated when you click **Preview PDF** during report creation or select the **Export as PDF** option on a dashboard. If **Current** is selected, the PDF in the report will be in the instance theme of the Admin, but the preview and exported PDFs will be in the user's instance theme.
+
+### Embedded Image
+
+- **Theme** - Theme of the dashboard image embedded in the email. Defaults to **Dark**.
+
+
+
+## Email branding
+
+
+
+- **Company logo** - Company logo displayed in the report email. It can be configured by specifying a URL, or by uploading a file. The maximum file size is 16 MB. Defaults to the Grafana logo.
+- **Email footer** - Toggle to enable the report email footer. Select **Sent by** or **None**.
+- **Footer link text** - Text of the link in the report email footer. Defaults to `Grafana`.
+- **Footer link URL** - Link of the report email footer.
+
+Currently, the API does not allow for the simultaneous upload of files with identical names for both the email logo and report logo. You can still upload the same file for each logo separately in two distinct steps.
diff --git a/docs/sources/dashboards/share-dashboards-panels/shared-dashboards/index.md b/docs/sources/dashboards/share-dashboards-panels/shared-dashboards/index.md
index 43f71608d8f..d3859377ec2 100644
--- a/docs/sources/dashboards/share-dashboards-panels/shared-dashboards/index.md
+++ b/docs/sources/dashboards/share-dashboards-panels/shared-dashboards/index.md
@@ -244,8 +244,10 @@ guaranteed because plugin developers can override this functionality. The follow
### Unsupported
-- Graphite
+- DynamoDB
- Dynatrace
+- Graphite
+- Google Sheets
### Unconfirmed
diff --git a/docs/sources/dashboards/use-dashboards/index.md b/docs/sources/dashboards/use-dashboards/index.md
index df3323b38f0..5292924fa86 100644
--- a/docs/sources/dashboards/use-dashboards/index.md
+++ b/docs/sources/dashboards/use-dashboards/index.md
@@ -131,14 +131,14 @@ Grafana has a number of keyboard shortcuts available. Press `?` on your keyboard
- `d+e`: Expand all rows.
- `d+s`: Dashboard settings.
- `Ctrl+K`: Opens the command palette.
-- `Esc`: Exits panel when in fullscreen view or edit mode. Also returns you to the dashboard from dashboard settings.
+- `Esc`: Exits panel when in full screen view or edit mode. Also returns you to the dashboard from dashboard settings.
**Focused panel**
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
+- `v`: Toggle panel full screen view
- `pu`: Open share panel link configuration
- `pe`: Open share panel embed configuration
- `ps`: Open share panel snapshot configuration
diff --git a/docs/sources/dashboards/variables/add-template-variables/index.md b/docs/sources/dashboards/variables/add-template-variables/index.md
index c98f9d09472..fa4e49ef5a4 100644
--- a/docs/sources/dashboards/variables/add-template-variables/index.md
+++ b/docs/sources/dashboards/variables/add-template-variables/index.md
@@ -169,7 +169,7 @@ Query expressions are different for each data source. For more information, refe
- If you need more room in a single input field query editor, then hover your cursor over the lines in the lower right corner of the field and drag downward to expand.
1. (Optional) In the **Regex** field, type a regex expression to filter or capture specific parts of the names returned by your data source query. To see examples, refer to [Filter variables with regex](#filter-variables-with-regex).
-1. In the **Sort** drop-down list, select the sort order for values to be displayed in the dropdown list. The default option, **Disabled**, means that the order of options returned by your data source query will be used.
+1. In the **Sort** drop-down list, select the sort order for values to be displayed in the dropdown list. The default option, **Disabled**, means that the order of options returned by your data source query is used.
1. Under **Refresh**, select when the variable should update options:
- **On dashboard load** - Queries the data source every time the dashboard loads. This slows down dashboard loading, because the variable query needs to be completed before dashboard can be initialized.
@@ -268,8 +268,8 @@ You can use an interval variable as a parameter to group by time (for InfluxDB),
This option allows you to specify how many times the current time range should be divided to calculate the current `auto` time span. If you turn it on, then two more options appear:
- - **Step count** - Select the number of times the current time range will be divided to calculate the value, similar to the **Max data points** query option. For example, if the current visible time range is 30 minutes, then the `auto` interval groups the data into 30 one-minute increments. The default value is 30 steps.
- - **Min interval** - The minimum threshold below which the step count intervals will not divide the time. To continue the 30 minute example, if the minimum interval is set to 2m, then Grafana would group the data into 15 two-minute increments.
+ - **Step count** - Select the number of times the current time range is divided to calculate the value, similar to the **Max data points** query option. For example, if the current visible time range is 30 minutes, then the `auto` interval groups the data into 30 one-minute increments. The default value is 30 steps.
+ - **Min interval** - The minimum threshold below which the step count intervals does not divide the time. To continue the 30 minute example, if the minimum interval is set to 2m, then Grafana would group the data into 15 two-minute increments.
1. In the **Preview of values** section, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. Click **Save dashboard**.
@@ -327,7 +327,7 @@ Now you can [filter data on the dashboard](ref:filter-dashboard).
Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values into a string that is valid in the given context where the variable is used. Grafana tries to solve this by allowing each data source plugin to inform the templating interpolation engine what format to use for multiple values.
{{% admonition type="note" %}}
-The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If it is left blank, then Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value will be something like `*` or `all`.
+The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If it is left blank, then Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value is something like `*` or `all`.
{{% /admonition %}}
#### Multi-value variables with a Graphite data source
@@ -363,7 +363,7 @@ Enter regex, globs, or lucene syntax in the **Custom all value** field to define
By default the `All` value includes all options in combined expression. This can become very long and can have performance problems. Sometimes it can be better to specify a custom all value, like a wildcard regex.
-In order to have custom regex, globs, or lucene syntax in the **Custom all value** option, it is never escaped so you will have to think about what is a valid value for your data source.
+In order to have custom regex, globs, or lucene syntax in the **Custom all value** option, it is never escaped so you have to think about what is a valid value for your data source.
## Global variables
@@ -393,7 +393,7 @@ You can use this variable in URLs, as well. For example, you can send a user to
You can use the `$__interval` variable as a parameter to group by time (for InfluxDB, MySQL, Postgres, MSSQL), Date histogram interval (for Elasticsearch), or as a _summarize_ function parameter (for Graphite).
-Grafana automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph, then queries can be made more efficient by grouping by a larger interval. It is more efficient to group by 1 day than by 10s when looking at 3 months of data and the graph will look the same and the query will be faster. The `$__interval` is calculated using the time range and the width of the graph (the number of pixels).
+Grafana automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph, then queries can be made more efficient by grouping by a larger interval. It is more efficient to group by 1 day than by 10s when looking at 3 months of data. The graph looks the same and the query is faster. The `$__interval` is calculated using the time range and the width of the graph (the number of pixels).
Approximate Calculation: `(to - from) / resolution`
@@ -409,7 +409,7 @@ This variable is the `$__interval` variable in milliseconds, not a time interval
### $\_\_name
-This variable is only available in the Singlestat panel and can be used in the prefix or suffix fields on the Options tab. The variable will be replaced with the series name or alias.
+This variable is only available in the Singlestat panel and can be used in the prefix or suffix fields on the Options tab. The variable is replaced with the series name or alias.
{{% admonition type="note" %}}
The Singlestat panel is no longer available from Grafana 8.0.
@@ -453,7 +453,7 @@ This is used in several places, including:
The `$__timezone` variable returns the currently selected time zone, either `utc` or an entry of the IANA time zone database (for example, `America/New_York`).
-If the currently selected time zone is _Browser Time_, Grafana will try to determine your browser time zone.
+If the currently selected time zone is _Browser Time_, Grafana tries to determine your browser time zone.
## Chained variables
@@ -605,7 +605,7 @@ SHOW TAG VALUES WITH KEY = "cpu" WHERE "datacenter" =~ /^Europe/ AND "host" =~ /
### Best practices and tips
-The following practices will make your dashboards and variables easier to use.
+The following practices make your dashboards and variables easier to use.
#### Creating new linked variables
@@ -623,7 +623,7 @@ You can change the orders of variables in the dashboard variable list by clickin
#### Complexity consideration
-The more layers of dependency you have in variables, the longer it will take to update dashboards after you change variables.
+The more layers of dependency you have in variables, the longer it takes to update dashboards after you change variables.
For example, if you have a series of four linked variables (country, region, server, metric) and you change a root variable value (country), then Grafana must run queries for all the dependent variables before it updates the visualizations in the dashboard.
diff --git a/docs/sources/datasources/aws-cloudwatch/query-editor/index.md b/docs/sources/datasources/aws-cloudwatch/query-editor/index.md
index fe44e0d7542..b65bd308e77 100644
--- a/docs/sources/datasources/aws-cloudwatch/query-editor/index.md
+++ b/docs/sources/datasources/aws-cloudwatch/query-editor/index.md
@@ -274,7 +274,6 @@ To enable cross-account observability, complete the following steps:
Cross-account querying is available in the plugin through the **Logs**, **Metric search**, and **Metric Insights** modes.
After you have it configured, you'll see a **Monitoring account** badge in the query editor header.
-To support cross-account query building in the **Metric Insight** builder mode, the `cloudwatchMetricInsightsCrossAccount` feature toggle should be enabled.
{{< figure src="/static/img/docs/cloudwatch/cloudwatch-monitoring-badge-9.3.0.png" max-width="1200px" caption="Monitoring account badge" >}}
diff --git a/docs/sources/datasources/azure-monitor/_index.md b/docs/sources/datasources/azure-monitor/_index.md
index 7474ba3165d..cdc50ba8993 100644
--- a/docs/sources/datasources/azure-monitor/_index.md
+++ b/docs/sources/datasources/azure-monitor/_index.md
@@ -213,7 +213,7 @@ The public cloud name is `AzureCloud`, the Chinese national cloud name is `Azure
### Configure Managed Identity
{{< admonition type="note" >}}
-Managed Identity is available only in [Azure Managed Grafana](https://azure.microsoft.com/en-us/products/managed-grafana) or Grafana Enterprise when deployed in Azure. It is not available in Grafana Cloud.
+Managed Identity is available only in [Azure Managed Grafana](https://azure.microsoft.com/en-us/products/managed-grafana) or Grafana OSS/Enterprise when deployed in Azure. It is not available in Grafana Cloud.
{{< /admonition >}}
You can use managed identity to configure Azure Monitor in Grafana if you host Grafana in Azure (such as an App Service or with Azure Virtual Machines) and have managed identity enabled on your VM.
diff --git a/docs/sources/datasources/elasticsearch/configure-elasticsearch-data-source.md b/docs/sources/datasources/elasticsearch/configure-elasticsearch-data-source.md
index 841f7ea5a92..9741f03d072 100644
--- a/docs/sources/datasources/elasticsearch/configure-elasticsearch-data-source.md
+++ b/docs/sources/datasources/elasticsearch/configure-elasticsearch-data-source.md
@@ -42,7 +42,7 @@ You can create a variety of queries to visualize logs or metrics stored in Elast
For instructions on how to add a data source to Grafana, refer to the [administration documentation](ref:administration-documentation).
Only users with the organization `administrator` role can add data sources.
-Administrators can also [configure the data source via YAML](#provision-the-data-source) with Grafana's provisioning system.
+Administrators can also [configure the data source via YAML](ref:provisioning-data-sources) with Grafana's provisioning system.
## Configuring permissions
diff --git a/docs/sources/datasources/mysql/_index.md b/docs/sources/datasources/mysql/_index.md
index 72923a252ae..33067e51983 100644
--- a/docs/sources/datasources/mysql/_index.md
+++ b/docs/sources/datasources/mysql/_index.md
@@ -2,7 +2,7 @@
aliases:
- ../data-sources/mysql/
- ../features/datasources/mysql/
-description: Guide for using MySQL in Grafana
+description: introduction to the MySQL data source in Grafana
keywords:
- grafana
- mysql
@@ -16,584 +16,52 @@ menuTitle: MySQL
title: MySQL data source
weight: 1000
refs:
- add-template-variables-interval:
- - pattern: /docs/grafana/
- destination: /docs/grafana//dashboards/variables/add-template-variables/#__interval
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//dashboards/variables/add-template-variables/#__interval
- query-transform-data:
- - pattern: /docs/grafana/
- destination: /docs/grafana//panels-visualizations/query-transform-data/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//panels-visualizations/query-transform-data/
- add-template-variables-interval-ms:
- - pattern: /docs/grafana/
- destination: /docs/grafana//dashboards/variables/add-template-variables/#__interval_ms
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//dashboards/variables/add-template-variables/#__interval_ms
- variables:
- - pattern: /docs/grafana/
- destination: /docs/grafana//dashboards/variables/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//dashboards/variables/
- provisioning-data-sources:
- - pattern: /docs/grafana/
- destination: /docs/grafana//administration/provisioning/#data-sources
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//administration/provisioning/#data-sources
- variable-syntax-advanced-variable-format-options:
- - pattern: /docs/grafana/
- destination: /docs/grafana//dashboards/variables/variable-syntax/#advanced-variable-format-options
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//dashboards/variables/variable-syntax/#advanced-variable-format-options
- data-source-management:
- - pattern: /docs/grafana/
- destination: /docs/grafana//administration/data-source-management/
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//administration/data-source-management/
- configure-standard-options-display-name:
- - pattern: /docs/grafana/
- destination: /docs/grafana//panels-visualizations/configure-standard-options/#display-name
- - pattern: /docs/grafana-cloud/
- destination: /docs/grafana//panels-visualizations/configure-standard-options/#display-name
annotate-visualizations:
- pattern: /docs/grafana/
destination: /docs/grafana//dashboards/build-dashboards/annotate-visualizations/
- pattern: /docs/grafana-cloud/
- destination: /docs/grafana//dashboards/build-dashboards/annotate-visualizations/
+ destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/annotate-visualizations/
+ configure-mysql-data-source:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//datasources/mysql/configuration/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//datasources/mysql/configuration/
+ mysql-query-editor:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//datasources/mysql/query-editor/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//datasources/mysql/query-editor/
+ alerting:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//alerting/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/alerting-and-irm/alerting/
+ transformations:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//panels-visualizations/query-transform-data/transform-data/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/transform-data/
---
# MySQL data source
-> Starting from Grafana v5.1 you can name the time column _time_ in addition to earlier supported _time_sec_. Usage of _time_sec_ will eventually be deprecated.
+Grafana ships with a built-in MySQL data source plugin that allows you to query and visualize data from a MySQL-compatible database like MariaDB or Percona Server. You don't need to install a plugin in order to add the MySQL data source to your Grafana instance.
-Grafana ships with a built-in MySQL data source plugin that allows you to query and visualize data from a MySQL compatible database like MariaDB or Percona Server.
+Grafana offers several configuration options for this data source as well as a visual and code-based query editor.
-For instructions on how to add a data source to Grafana, refer to the [administration documentation](ref:data-source-management).
-Only users with the organization administrator role can add data sources.
-Administrators can also [configure the data source via YAML](#provision-the-data-source) with Grafana's provisioning system.
+## Get started with the MySQL data source
+
+The following documents will help you get started with the MySQL data source in Grafana:
+
+- [Configure the MySQL data source](ref:configure-mysql-data-source)
+- [MySQL query editor](ref:mysql-query-editor)
+
+Once you have configured the data source you can:
+
+- Add [annotations](ref:annotate-visualizations)
+- Set up [alerting](ref:alerting)
+- Add [transformations](ref:transformations)
+
+View a MySQL overview on Grafana Play:
{{< docs/play title="MySQL Overview" url="https://play.grafana.org/d/edyh1ib7db6rkb/mysql-overview" >}}
-
-## Configure the data source
-
-**To access the data source configuration page:**
-
-1. Click **Connections** in the left-side menu.
-1. Under Your connections, click **Data sources**.
-1. Enter `MySQL` in the search bar.
-1. Select **MySQL**.
-
- The **Settings** tab of the data source is displayed.
-
-1. Set the data source's basic configuration options.
-
-| Name | Description |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Name** | The data source name. This is how you refer to the data source in panels and queries. |
-| **Default** | Default data source means that it will be pre-selected for new panels. |
-| **Host** | The IP address/hostname and optional port of your MySQL instance. |
-| **Database** | Name of your MySQL database. |
-| **User** | Database user's login/username |
-| **Password** | Database user's password |
-| **Session Timezone** | Specifies the timezone used in the database session, such as `Europe/Berlin` or `+02:00`. Required if the timezone of the database (or the host of the database) is set to something other than UTC. Set this to `+00:00` so Grafana can handle times properly. Set the value used in the session with `SET time_zone='...'`. If you leave this field empty, the timezone will not be updated. For more information, refer to [MySQL Server Time Zone Support](https://dev.mysql.com/doc/en/time-zone-support.html). |
-| **Max open** | The maximum number of open connections to the database, default `100`. |
-| **Max idle** | The maximum number of connections in the idle connection pool, default `100`. |
-| **Auto (max idle)** | Toggle to set the maximum number of idle connections to the number of maximum open connections. Default is `true`. |
-| **Allow cleartext passwords** | Allows the use of the [cleartext client side plugin](https://dev.mysql.com/doc/en/cleartext-pluggable-authentication.html) as required by a specific type of account, such as one defined with the [PAM authentication plugin](https://dev.mysql.com/doc/en/pam-pluggable-authentication.html).
**Sending passwords in clear text may be a security problem in some configurations**. To avoid password issues, it is recommended that clients connect to a MySQL server using a method that protects the password. Possibilities include [TLS / SSL](https://github.com/go-sql-driver/mysql#tls), IPsec, or a private network. Default is `false`. |
-| **Max lifetime** | The maximum amount of time in seconds a connection may be reused. This should always be lower than configured [wait_timeout](https://dev.mysql.com/doc/en/server-system-variables.html#sysvar_wait_timeout) in MySQL. The default is `14400` or 4 hours. |
-
-### Min time interval
-
-The **Min time interval** setting defines a lower limit for the [`$__interval`](ref:add-template-variables-interval) and [`$__interval_ms`](ref:add-template-variables-interval-ms) variables.
-
-This value _must_ be formatted as a number followed by a valid time identifier:
-
-| Identifier | Description |
-| ---------- | ----------- |
-| `y` | year |
-| `M` | month |
-| `w` | week |
-| `d` | day |
-| `h` | hour |
-| `m` | minute |
-| `s` | second |
-| `ms` | millisecond |
-
-We recommend setting this value to match your MySQL write frequency.
-For example, use `1m` if MySQL writes data every minute.
-
-You can also override this setting in a dashboard panel under its data source options.
-
-### Database User Permissions (Important!)
-
-The database user you specify when you add the data source should only be granted SELECT permissions on
-the specified database and tables you want to query. Grafana does not validate that the query is safe. The query
-could include any SQL statement. For example, statements like `USE otherdb;` and `DROP TABLE user;` would be
-executed. To protect against this we **Highly** recommend you create a specific mysql user with restricted permissions.
-
-Example:
-
-```sql
- CREATE USER 'grafanaReader' IDENTIFIED BY 'password';
- GRANT SELECT ON mydatabase.mytable TO 'grafanaReader';
-```
-
-You can use wildcards (`*`) in place of database or table if you want to grant access to more databases and tables.
-
-### Provision the data source
-
-You can define and configure the data source in YAML files as part of Grafana's provisioning system.
-For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana](ref:provisioning-data-sources).
-
-#### Provisioning examples
-
-##### Basic Provisioning
-
-```yaml
-apiVersion: 1
-
-datasources:
- - name: MySQL
- type: mysql
- url: localhost:3306
- user: grafana
- jsonData:
- database: grafana
- maxOpenConns: 100
- maxIdleConns: 100
- maxIdleConnsAuto: true
- connMaxLifetime: 14400
- secureJsonData:
- password: ${GRAFANA_MYSQL_PASSWORD}
-```
-
-##### Using TLS verification
-
-```yaml
-apiVersion: 1
-
-datasources:
- - name: MySQL
- type: mysql
- url: localhost:3306
- user: grafana
- jsonData:
- tlsAuth: true
- database: grafana
- maxOpenConns: 100
- maxIdleConns: 100
- maxIdleConnsAuto: true
- connMaxLifetime: 14400
- secureJsonData:
- password: ${GRAFANA_MYSQL_PASSWORD}
- tlsClientCert: ${GRAFANA_TLS_CLIENT_CERT}
- tlsCACert: ${GRAFANA_TLS_CA_CERT}
-```
-
-##### Use TLS and Skip Certificate Verification
-
-```yaml
-apiVersion: 1
-
-datasources:
- - name: MySQL
- type: mysql
- url: localhost:3306
- user: grafana
- jsonData:
- tlsAuth: true
- tlsSkipVerify: true
- database: grafana
- maxOpenConns: 100
- maxIdleConns: 100
- maxIdleConnsAuto: true
- connMaxLifetime: 14400
- secureJsonData:
- password: ${GRAFANA_MYSQL_PASSWORD}
- tlsClientCert: ${GRAFANA_TLS_CLIENT_CERT}
- tlsCACert: ${GRAFANA_TLS_CA_CERT}
-```
-
-## Query builder
-
-{{< figure src="/static/img/docs/v92/mysql_query_builder.png" class="docs-image--no-shadow" >}}
-
-The MySQL query builder is available when editing a panel using a MySQL data source.
-
-This topic explains querying specific to the MySQL data source.
-For general documentation on querying data sources in Grafana, see [Query and transform data](ref:query-transform-data).
-
-You can run the built query by pressing the `Run query` button in the top right corner of the editor.
-
-### Format
-
-The response from MySQL can be formatted as either a table or as a time series. To use the time series format one of the columns must be named `time`.
-
-### Dataset and Table selection
-
-{{% admonition type="note" %}}
-If your table or database name contains a reserved word or a [prohibited character](https://dev.mysql.com/doc/en/identifiers.html) the editor will put quotes around the name. For example, the name `table-name` will be quoted with backticks - `` `table-name` ``.
-{{% /admonition %}}
-
-In the dataset dropdown, choose the MySQL database to query. The dropdown is be populated with the databases that the user has access to.
-When the dataset is selected, the table dropdown is populated with the tables that are available.
-
-**Note:** If a default database has been configured through the Data Source Configuration page (or through a provisioning configuration file), the user will only be able to use that single preconfigured database for querying.
-
-### Columns and Aggregation functions (SELECT)
-
-Using the dropdown, select a column to include in the data. You can also specify an optional aggregation function.
-
-Add further value columns by clicking the plus button and another column dropdown appears.
-
-{{< docs/shared source="grafana" lookup="datasources/sql-query-builder-macros.md" version="" >}}
-
-### Filter data (WHERE)
-
-To add a filter, toggle the **Filter** switch at the top of the editor.
-This reveals a **Filter by column value** section with two dropdown selectors.
-
-Use the first dropdown to choose whether all of the filters need to match (`AND`), or if only one of the filters needs to match (`OR`).
-Use the second dropdown to choose a filter.
-
-To filter on more columns, click the plus (`+`) button to the right of the condition dropdown.
-
-To remove a filter, click the `x` button next to that filter's dropdown.
-
-After selecting a date type column, you can choose Macros from the operators list and select timeFilter which will add the $\_\_timeFilter macro to the query with the selected date column.
-
-### Group By
-
-To group the results by column, flip the group switch at the top of the editor. You can then choose which column to group the results by. The group by clause can be removed by pressing the X button.
-
-### Preview
-
-By flipping the preview switch at the top of the editor, you can get a preview of the SQL query generated by the query builder.
-
-## Code editor
-
-{{< figure src="/static/img/docs/v92/sql_code_editor.png" class="docs-image--no-shadow" >}}
-
-To make advanced queries, switch to the code editor by clicking `code` in the top right corner of the editor. The code editor support autocompletion of tables, columns, SQL keywords, standard sql functions, Grafana template variables and Grafana macros. Columns cannot be completed before a table has been specified.
-
-You can expand the code editor by pressing the `chevron` pointing downwards in the lower right corner of the code editor.
-
-`CTRL/CMD + Return` works as a keyboard shortcut to run the query.
-
-## Macros
-
-To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.
-
-| Macro example | Description |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `$__time(dateColumn)` | Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, _UNIX_TIMESTAMP(dateColumn) as time_sec_ |
-| `$__timeEpoch(dateColumn)` | Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, _UNIX_TIMESTAMP(dateColumn) as time_sec_ |
-| `$__timeFilter(dateColumn)` | Will be replaced by a time range filter using the specified column name. For example, _dateColumn BETWEEN FROM_UNIXTIME(1494410783) AND FROM_UNIXTIME(1494410983)_ |
-| `$__timeFrom()` | Will be replaced by the start of the currently active time selection. For example, _FROM_UNIXTIME(1494410783)_ |
-| `$__timeTo()` | Will be replaced by the end of the currently active time selection. For example, _FROM_UNIXTIME(1494410983)_ |
-| `$__timeGroup(dateColumn,'5m')` | Will be replaced by an expression usable in GROUP BY clause. For example, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed),\* |
-| `$__timeGroup(dateColumn,'5m', 0)` | Same as above but with a fill parameter so missing points in that series will be added by grafana and 0 will be used as value (only works with time series queries). |
-| `$__timeGroup(dateColumn,'5m', NULL)` | Same as above but NULL will be used as value for missing points (only works with time series queries). |
-| `$__timeGroup(dateColumn,'5m', previous)` | Same as above but the previous value in that series will be used as fill value if no value has been seen yet NULL will be used (only works with time series queries). |
-| `$__timeGroupAlias(dateColumn,'5m')` | Will be replaced identical to $\_\_timeGroup but with an added column alias. |
-| `$__unixEpochFilter(dateColumn)` | Will be replaced by a time range filter using the specified column name with times represented as Unix timestamp. For example, _dateColumn > 1494410783 AND dateColumn < 1494497183_ |
-| `$__unixEpochFrom()` | Will be replaced by the start of the currently active time selection as Unix timestamp. For example, _1494410783_ |
-| `$__unixEpochTo()` | Will be replaced by the end of the currently active time selection as Unix timestamp. For example, _1494497183_ |
-| `$__unixEpochNanoFilter(dateColumn)` | Will be replaced by a time range filter using the specified column name with times represented as nanosecond timestamp. For example, _dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872_ |
-| `$__unixEpochNanoFrom()` | Will be replaced by the start of the currently active time selection as nanosecond timestamp. For example, _1494410783152415214_ |
-| `$__unixEpochNanoTo()` | Will be replaced by the end of the currently active time selection as nanosecond timestamp. For example, _1494497183142514872_ |
-| `$__unixEpochGroup(dateColumn,'5m', [fillmode])` | Same as $\_\_timeGroup but for times stored as Unix timestamp (`fillMode` only works with time series queries). |
-| `$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])` | Same as above but also adds a column alias (`fillMode` only works with time series queries). |
-
-## Table queries
-
-If the `Format as` query option is set to `Table` then you can basically do any type of SQL query. The table panel will automatically show the results of whatever columns and rows your query returns.
-
-Query editor with example query:
-
-{{< figure src="/static/img/docs/v45/mysql_table_query.png" >}}
-
-The query:
-
-```sql
-SELECT
- title as 'Title',
- user.login as 'Created By' ,
- dashboard.created as 'Created On'
- FROM dashboard
-INNER JOIN user on user.id = dashboard.created_by
-WHERE $__timeFilter(dashboard.created)
-```
-
-You can control the name of the Table panel columns by using regular `as ` SQL column selection syntax.
-
-The resulting table panel:
-
-
-
-## Time series queries
-
-The examples in this section query the following table:
-
-```text
-+---------------------+--------------+---------------------+----------+
-| time_date_time | value_double | CreatedAt | hostname |
-+---------------------+--------------+---------------------+----------+
-| 2020-01-02 03:05:00 | 3.0 | 2020-01-02 03:05:00 | 10.0.1.1 |
-| 2020-01-02 03:06:00 | 4.0 | 2020-01-02 03:06:00 | 10.0.1.2 |
-| 2020-01-02 03:10:00 | 6.0 | 2020-01-02 03:10:00 | 10.0.1.1 |
-| 2020-01-02 03:11:00 | 7.0 | 2020-01-02 03:11:00 | 10.0.1.2 |
-| 2020-01-02 03:20:00 | 5.0 | 2020-01-02 03:20:00 | 10.0.1.2 |
-+---------------------+--------------+---------------------+----------+
-```
-
-If the `Format as` query option is set to `Time Series` then the query must have a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch in seconds. In addition, result sets of time series queries must be sorted by time for panels to properly visualize the result.
-
-A time series query result is returned in a [wide data frame format](https://grafana.com/developers/plugin-tools/key-concepts/data-frames#wide-format). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result.
-
-> For backward compatibility, there's an exception to the above rule for queries that return three columns including a string column named metric. Instead of transforming the metric column into field labels, it becomes the field name, and then the series name is formatted as the value of the metric column. See the example with the metric column below.
-
-To optionally customize the default series name formatting, refer to [Standard options definitions](ref:configure-standard-options-display-name).
-
-**Example with `metric` column:**
-
-```sql
-SELECT
- $__timeGroupAlias(time_date_time,'5m'),
- min(value_double),
- 'min' as metric
-FROM test_data
-WHERE $__timeFilter(time_date_time)
-GROUP BY time
-ORDER BY time
-```
-
-Data frame result:
-
-```text
-+---------------------+-----------------+
-| Name: time | Name: min |
-| Labels: | Labels: |
-| Type: []time.Time | Type: []float64 |
-+---------------------+-----------------+
-| 2020-01-02 03:05:00 | 3 |
-| 2020-01-02 03:10:00 | 6 |
-| 2020-01-02 03:20:00 | 5 |
-+---------------------+-----------------+
-```
-
-**Example using the fill parameter in the $\_\_timeGroupAlias macro to convert null values to be zero instead:**
-
-```sql
-SELECT
- $__timeGroupAlias(createdAt,'5m',0),
- sum(value_double) as value,
- hostname
-FROM test_data
-WHERE
- $__timeFilter(createdAt)
-GROUP BY time, hostname
-ORDER BY time
-```
-
-Given the data frame result in the following example and using the graph panel, you will get two series named _value 10.0.1.1_ and _value 10.0.1.2_. To render the series with a name of _10.0.1.1_ and _10.0.1.2_ , use a [Standard options definitions](ref:configure-standard-options-display-name) display value of `${__field.labels.hostname}`.
-
-Data frame result:
-
-```text
-+---------------------+---------------------------+---------------------------+
-| Name: time | Name: value | Name: value |
-| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 |
-| Type: []time.Time | Type: []float64 | Type: []float64 |
-+---------------------+---------------------------+---------------------------+
-| 2020-01-02 03:05:00 | 3 | 4 |
-| 2020-01-02 03:10:00 | 6 | 7 |
-| 2020-01-02 03:15:00 | 0 | 0 |
-| 2020-01-02 03:20:00 | 0 | 5 |
-+---------------------+---------------------------+---------------------------+
-```
-
-**Example with multiple columns:**
-
-```sql
-SELECT
- $__timeGroupAlias(time_date_time,'5m'),
- min(value_double) as min_value,
- max(value_double) as max_value
-FROM test_data
-WHERE $__timeFilter(time_date_time)
-GROUP BY time
-ORDER BY time
-```
-
-Data frame result:
-
-```text
-+---------------------+-----------------+-----------------+
-| Name: time | Name: min_value | Name: max_value |
-| Labels: | Labels: | Labels: |
-| Type: []time.Time | Type: []float64 | Type: []float64 |
-+---------------------+-----------------+-----------------+
-| 2020-01-02 03:05:00 | 3 | 4 |
-| 2020-01-02 03:10:00 | 6 | 7 |
-| 2020-01-02 03:20:00 | 5 | 5 |
-+---------------------+-----------------+-----------------+
-```
-
-Currently, there is no support for a dynamic group by time based on time range and panel width.
-This is something we plan to add.
-
-## Templating
-
-This feature is currently available in the nightly builds and will be included in the 5.0.0 release.
-
-Instead of hard-coding things like server, application and sensor name in your metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the data being displayed in your dashboard.
-
-Check out the [Templating](ref:variables) documentation for an introduction to the templating feature and the different types of template variables.
-
-### Query Variable
-
-If you add a template variable of the type `Query`, you can write a MySQL query that can
-return things like measurement names, key names or key values that are shown as a dropdown select box.
-
-For example, you can have a variable that contains all values for the `hostname` column in a table if you specify a query like this in the templating variable _Query_ setting.
-
-```sql
-SELECT hostname FROM my_host
-```
-
-A query can return multiple columns and Grafana will automatically create a list from them. For example, the query below will return a list with values from `hostname` and `hostname2`.
-
-```sql
-SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city
-```
-
-To use time range dependent macros like `$__timeFilter(column)` in your query the refresh mode of the template variable needs to be set to _On Time Range Change_.
-
-```sql
-SELECT event_name FROM event_log WHERE $__timeFilter(time_column)
-```
-
-Another option is a query that can create a key/value variable. The query should return two columns that are named `__text` and `__value`. The `__text` column value should be unique (if it is not unique then the first value is used). The options in the dropdown will have a text and value that allows you to have a friendly name as text and an id as the value. An example query with `hostname` as the text and `id` as the value:
-
-```sql
-SELECT hostname AS __text, id AS __value FROM my_host
-```
-
-You can also create nested variables. For example if you had another variable named `region`. Then you could have
-the hosts variable only show hosts from the current selected region with a query like this (if `region` is a multi-value variable then use the `IN` comparison operator rather than `=` to match against multiple values):
-
-```sql
-SELECT hostname FROM my_host WHERE region IN($region)
-```
-
-#### Using `__searchFilter` to filter results in Query Variable
-
-Using `__searchFilter` in the query field will filter the query result based on what the user types in the dropdown select box.
-When nothing has been entered by the user the default value for `__searchFilter` is `%`.
-
-> Important that you surround the `__searchFilter` expression with quotes as Grafana does not do this for you.
-
-The example below shows how to use `__searchFilter` as part of the query field to enable searching for `hostname` while the user types in the dropdown select box.
-
-Query
-
-```sql
-SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter'
-```
-
-### Using Variables in Queries
-
-Template variable values are only quoted when the template variable is a `multi-value`.
-
-If the variable is a multi-value variable then use the `IN` comparison operator rather than `=` to match against multiple values.
-
-There are two syntaxes:
-
-`$` Example with a template variable named `hostname`:
-
-```sql
-SELECT
- UNIX_TIMESTAMP(atimestamp) as time,
- aint as value,
- avarchar as metric
-FROM my_table
-WHERE $__timeFilter(atimestamp) and hostname in($hostname)
-ORDER BY atimestamp ASC
-```
-
-`[[varname]]` Example with a template variable named `hostname`:
-
-```sql
-SELECT
- UNIX_TIMESTAMP(atimestamp) as time,
- aint as value,
- avarchar as metric
-FROM my_table
-WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
-ORDER BY atimestamp ASC
-```
-
-#### Disabling Quoting for Multi-value Variables
-
-Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. To disable quoting, use the csv formatting option for variables:
-
-`${servers:csv}`
-
-Read more about variable formatting options in the [Variables](ref:variable-syntax-advanced-variable-format-options) documentation.
-
-## Annotations
-
-[Annotations](ref:annotate-visualizations) allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.
-
-**Example query using time column with epoch values:**
-
-```sql
-SELECT
- epoch_time as time,
- metric1 as text,
- CONCAT(tag1, ',', tag2) as tags
-FROM
- public.test_data
-WHERE
- $__unixEpochFilter(epoch_time)
-```
-
-**Example region query using time and timeend columns with epoch values:**
-
-```sql
-SELECT
- epoch_time as time,
- epoch_timeend as timeend,
- metric1 as text,
- CONCAT(tag1, ',', tag2) as tags
-FROM
- public.test_data
-WHERE
- $__unixEpochFilter(epoch_time)
-```
-
-**Example query using time column of native SQL date/time data type:**
-
-```sql
-SELECT
- native_date_time as time,
- metric1 as text,
- CONCAT(tag1, ',', tag2) as tags
-FROM
- public.test_data
-WHERE
- $__timeFilter(native_date_time)
-```
-
-| Name | Description |
-| --------- | ----------------------------------------------------------------------------------------------------------------- |
-| `time` | The name of the date/time field. Could be a column with a native SQL date/time data type or epoch value. |
-| `timeend` | Optional name of the end date/time field. Could be a column with a native SQL date/time data type or epoch value. |
-| `text` | Event description field. |
-| `tags` | Optional field name to use for event tags as a comma separated string. |
-
-## Alerting
-
-Time series queries should work in alerting conditions. Table formatted queries are not yet supported in alert rule conditions.
diff --git a/docs/sources/datasources/mysql/configuration/_index.md b/docs/sources/datasources/mysql/configuration/_index.md
new file mode 100644
index 00000000000..d98aff95019
--- /dev/null
+++ b/docs/sources/datasources/mysql/configuration/_index.md
@@ -0,0 +1,211 @@
+---
+description: This document provides instructions for configuring the MySQL data source and explains available configuration options.
+keywords:
+ - grafana
+ - mysql
+ - guide
+ - configure
+labels:
+ products:
+ - cloud
+ - enterprise
+ - oss
+menuTitle: Configure the MySQL data source
+title: Configure the MySQL data source
+weight: 10
+refs:
+ add-template-variables-interval:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/variables/add-template-variables/#__interval
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#__interval
+ add-template-variables-interval-ms:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/variables/add-template-variables/#__interval_ms
+ - pattern: /docs/grafana-cloud/
+ destination: docs/grafana-cloud/visualizations/dashboards/variables/add-template-variables/#__interval_ms
+ provisioning-data-sources:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//administration/provisioning/#data-sources
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//administration/provisioning/#data-sources
+ data-source-management:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//administration/data-source-management/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//administration/data-source-management/
+---
+
+# Configure the MySQL data source
+
+This document provides instructions for configuring the MySQL data source and explains available configuration options. For general information on managing data sources refer to [Data source management](ref:data-source-management).
+
+## Before you begin
+
+You must have the `Organization administrator` role in order to configure the MySQL data source.
+Administrators can also [configure the data source via YAML](#provision-the-data-source) with Grafana's provisioning system.
+
+Grafana ships with the MySQL plugin, so no additional installation is required.
+
+{{< admonition type="note" >}}
+When adding a data source, ensure the database user you specify has only `SELECT` permissions on the relevant database and tables. Grafana does not validate the safety of queries, which means they can include potentially harmful SQL statements, such as `USE otherdb;` or `DROP TABLE user;`, which could get executed. To minimize this risk, Grafana strongly recommends creating a dedicated MySQL user with restricted permissions.
+{{< /admonition >}}
+
+Example:
+
+```sql
+ CREATE USER 'grafanaReader' IDENTIFIED BY 'password';
+ GRANT SELECT ON mydatabase.mytable TO 'grafanaReader';
+```
+
+Use wildcards (`*`) in place of a database or table if you want to grant access to more databases and tables.
+
+## Add the MySQL data source
+
+To add the MySQL data source complete the following steps:
+
+1. Click **Connections** in the left-side menu.
+1. Click **Add new connection** and type `MySQL` in the search bar.
+1. Select the **MySQL data source** option.
+1. Click **Add new data source** in the upper right.
+
+You are taken to the **Settings** tab where you will configure the data source.
+
+## MySQL configuration options
+
+Following is a list of MySQL configuration options:
+
+- **Name** - Sets the name you use to refer to the data source in panels and queries. Examples:
+ `mysql-assets-1`, `mysqldb1`.
+- **Default** - Toggle to make this specific MySQL data source the default pre-selected data source in panels and visualizations.
+
+**Connection:**
+
+- **Host URL** - Enter the IP address/hostname and optional port of your MySQL instance. If the port is omitted the default 3306 port will be used.
+- **Database** - Enter the name of your MySQL database.
+
+**Authentication:**
+
+- **Username**- Enter the username used to connect to your MySQL database.
+- **Password** - Enter the password used to connect to the MySQL database.
+- **Use TLS Client Auth** - Toggle to enable TLS authentication using the client certificate specified in the secure JSON configuration. Refer to [Using TLS Connections](https://dev.mysql.com/doc/refman/8.4/en/mysql-cluster-tls-using.html) and [Configuring MySQL to Use Encrypted Connections](https://dev.mysql.com/doc/refman/8.4/en/using-encrypted-connections.html) for more information regarding TLS and configuring encrypted connections in MySQL. Provide the client certificate under **TLS/SSL Client Certificate**. Provide the key under **TLS/SSL Client Key**.
+- **With CA Cert** - Toggle to authenticate using a CA certificate. Required for verifying self-signed TLS Certs. Follow the instructions of your CA (Certificate Authority) to download the certificate file. Provide the root certificate under **TLS/SSL Root Certificate** if TLS/SSL mode requires it.
+- **Skip TLS Verification** - Toggle to skip verification of the MySQL server's TLS certificate chain and host name.
+- **Allow Cleartext Passwords** - Toggle to allow the use of the [cleartext client-side plugin](https://dev.mysql.com/doc/en/cleartext-pluggable-authentication.html) when required by a specific type of account, such as one defined with the [PAM authentication plugin](https://dev.mysql.com/doc/refman/8.4/en/pam-pluggable-authentication.html). Note that transmitting passwords in plain text can pose a security risk in certain configurations. To prevent password-related issues, it is recommended that clients connect to a MySQL server using a secure method that protects the password. Options include [TLS/SSL](https://github.com/go-sql-driver/mysql#tls), IPsec, or a private network.
+
+## Additional settings
+
+The following are additional MySQL settings.
+
+**MySQL options:**
+
+- **Session Timezone** - Specifies the timezone used in the database session, such as `Europe/Berlin` or `+02:00`. Required if the timezone of the database (or the host of the database) is set to something other than UTC. Set this to `+00:00` so Grafana can handle times properly. Set the value used in the session with `SET time_zone='...'`. If you leave this field empty, the timezone will not be updated. For more information, refer to [MySQL Server Time Zone Support](https://dev.mysql.com/doc/en/time-zone-support.html).
+- **Min time interval** - Defines a lower limit for the [`$__interval`](ref:add-template-variables-interval) and [`$__interval_ms`](ref:add-template-variables-interval-ms) variables. Grafana recommends aligning this setting with the data write frequency. For example, set it to `1m` if your data is written every minute. Refer to [Min time interval](#min-time-interval) for format examples.
+
+**Connection limits:**
+
+- **Max open** - The maximum number of open connections to the database, default `100`.
+- **Max idle** - The maximum number of connections in the idle connection pool, default `100`.
+- **Auto (max idle)** - Toggle to set the maximum number of idle connections to the number of maximum open connections. The default is `true`.
+- **Max lifetime** - The maximum amount of time in seconds a connection may be reused. This should always be lower than configured [wait_timeout](https://dev.mysql.com/doc/en/server-system-variables.html#sysvar_wait_timeout) in MySQL. The default is `14400`, or 4 hours.
+
+**Private data source connect:**
+
+**Private data source connect** - _Only for Grafana Cloud users._ Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to [Private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/).
+
+Click **Manage private data source connect** to be taken to your PDC connection page, where you’ll find your PDC configuration details.
+
+Once you have added your MySQL connection settings, click **Save & test** to test and save the data source connection.
+
+### Min time interval
+
+The **Min time interval** setting defines a lower limit for the [`$__interval`](ref:add-template-variables-interval) and [`$__interval_ms`](ref:add-template-variables-interval-ms) variables.
+
+This value must be formatted as a number followed by a valid time identifier:
+
+| Identifier | Description |
+| ---------- | ----------- |
+| `y` | year |
+| `M` | month |
+| `w` | week |
+| `d` | day |
+| `h` | hour |
+| `m` | minute |
+| `s` | second |
+| `ms` | millisecond |
+
+You can override this setting in a dashboard panel under its data source options.
+
+## Provision the data source
+
+You can define and configure the data source in YAML files as part of Grafana's provisioning system.
+For more information about provisioning, and available configuration options, refer to [Provision Grafana](ref:provisioning-data-sources).
+
+### MySQL provisioning examples
+
+**Basic provisioning:**
+
+```yaml
+apiVersion: 1
+
+datasources:
+ - name: MySQL
+ type: mysql
+ url: localhost:3306
+ user: grafana
+ jsonData:
+ database: grafana
+ maxOpenConns: 100
+ maxIdleConns: 100
+ maxIdleConnsAuto: true
+ connMaxLifetime: 14400
+ secureJsonData:
+ password: ${GRAFANA_MYSQL_PASSWORD}
+```
+
+**Using TLS verification:**
+
+```yaml
+apiVersion: 1
+
+datasources:
+ - name: MySQL
+ type: mysql
+ url: localhost:3306
+ user: grafana
+ jsonData:
+ tlsAuth: true
+ database: grafana
+ maxOpenConns: 100
+ maxIdleConns: 100
+ maxIdleConnsAuto: true
+ connMaxLifetime: 14400
+ secureJsonData:
+ password: ${GRAFANA_MYSQL_PASSWORD}
+ tlsClientCert: ${GRAFANA_TLS_CLIENT_CERT}
+ tlsCACert: ${GRAFANA_TLS_CA_CERT}
+```
+
+**Use TLS and skip certificate verification:**
+
+```yaml
+apiVersion: 1
+
+datasources:
+ - name: MySQL
+ type: mysql
+ url: localhost:3306
+ user: grafana
+ jsonData:
+ tlsAuth: true
+ tlsSkipVerify: true
+ database: grafana
+ maxOpenConns: 100
+ maxIdleConns: 100
+ maxIdleConnsAuto: true
+ connMaxLifetime: 14400
+ secureJsonData:
+ password: ${GRAFANA_MYSQL_PASSWORD}
+ tlsClientCert: ${GRAFANA_TLS_CLIENT_CERT}
+ tlsCACert: ${GRAFANA_TLS_CA_CERT}
+```
diff --git a/docs/sources/datasources/mysql/query-editor/_index.md b/docs/sources/datasources/mysql/query-editor/_index.md
new file mode 100644
index 00000000000..f11f0218ea3
--- /dev/null
+++ b/docs/sources/datasources/mysql/query-editor/_index.md
@@ -0,0 +1,440 @@
+---
+description: This document describes the MySQL query editor.
+keywords:
+ - grafana
+ - mysql
+ - query
+labels:
+ products:
+ - cloud
+ - enterprise
+ - oss
+menuTitle: MySQL query editor
+title: MySQL query editor
+weight: 30
+refs:
+ variables:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/variables/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/dashboards/variables/
+ variable-syntax-advanced-variable-format-options:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/variables/variable-syntax/#advanced-variable-format-options
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/dashboards/variables/variable-syntax/#advanced-variable-format-options
+ annotate-visualizations:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//dashboards/build-dashboards/annotate-visualizations/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/dashboards/build-dashboards/annotate-visualizations/
+ explore:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//explore/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana//explore/
+ query-transform-data:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//panels-visualizations/query-transform-data/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/
+ panel-inspector:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//panels-visualizations/panel-inspector/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/panels-visualizations/panel-inspector/
+ query-editor:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//panels-visualizations/query-transform-data/#query-editors
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/visualizations/panels-visualizations/query-transform-data/#query-editors
+ alert-rules:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//alerting/fundamentals/alert-rules/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/
+ template-annotations-and-labels:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//alerting/alerting-rules/templates/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/templates/
+---
+
+# MySQL query editor
+
+Grafana’s query editors are unique for each data source. For general information on Grafana query editors, refer to [Query editors](ref:query-editor). For general information on querying data sources in Grafana, refer to [Query and transform data](ref:query-transform-data).
+
+The MySQL query editor is located on the [Explore page](ref:explore). You can also access the MySQL query editor from a dashboard panel. Click the ellipsis in the upper right of the panel and select **Edit**.
+
+{{% admonition type="note" %}}
+If a default database is configured in the **Data Source Configuration page**, or via a provisioning configuration file, users will be restricted to querying only that pre-configured database. This feature is behind a feature flag and is available once you enable `sqlDatasourceDatabaseSelection`.
+{{% /admonition %}}
+
+## MySQL query editor components
+
+The MySQL query editor has two modes: **Builder** and **Code**.
+
+Builder mode helps you build a query using a visual interface. Code mode allows for advanced querying and offers support for complex SQL query writing.
+
+{{% admonition type="note" %}}
+If your table or database name contains a reserved word or a [prohibited character](https://dev.mysql.com/doc/en/identifiers.html) the editor will put quotes around the name. For example, the name `table-name` will be quoted with backticks - `` `table-name` ``.
+{{% /admonition %}}
+
+## MySQL Builder mode
+
+{{< figure alt="Builder mode" src="/media/docs/mysql/screenshot-mysql-query-editor.v11.3.png" class="docs-image--no-shadow" >}}
+
+The following components will help you build a MySQL query:
+
+- **Format** - Select a format response from the drop-down for the MySQL query. The default is **Table**. If you use the **Time series** format option, one of the columns must be `time`.
+
+- **Dataset** - Select a database to query from the drop-down.
+
+ - **Table** - Select a table from the drop-down. Tables correspond to the chosen database.
+
+ - **Data operations** - _Optional_ Select an aggregation from the drop-down. You can add multiple data operations by clicking the **+ sign**. Click the **X** to remove a data operation. Click the **garbage can icon** to remove the entire column.
+
+ - **Column** - Select a column on which to run the aggregation.
+
+ - **Alias** - _Optional_ Add an alias from the drop-down. You can also add your own alias by typing it in the box and clicking **Enter**. Remove an alias by clicking the **X**.
+
+- **Filter** - Toggle to add filters.
+
+ - **Filter by column value** - _Optional_ If you toggle **Filter** you can add a column to filter by from the drop-down. To filter on more columns, click the **+ sign** to the right of the condition drop-down. You can choose a variety of operators from the drop-down next to the condition. When multiple filters are added you can add an `AND` operator to display all true conditions or an `OR` operator to display any true conditions. Use the second drop-down to choose a filter. To remove a filter, click the `X` button next to that filter's drop-down. After selecting a date type column, you can choose **Macros** from the operators list and select `timeFilter` which will add the `$\_\_timeFilter` macro to the query with the selected date column.
+
+- **Group** - Toggle to add **Group by column**.
+
+ - **Group by column** - Select a column to filter by from the drop-down. Click the **+ sign** to filter by multiple columns. Click the **X** to remove a filter.
+
+- **Order** - Toggle to add an ORDER BY statement.
+
+ - **Order by** - Select a column to order by from the drop-down. Select ascending (`ASC`) or descending (`DESC`) order.
+ - **Limit** - You can add an optional limit on the number of retrieved results. Default is 50.
+
+- **Preview** - Toggle for a preview of the SQL query generated by the query builder. Preview is toggled on by default.
+
+## MySQL Code mode
+
+To create advanced queries, switch to **Code mode** by clicking **Code** in the upper right of the editor window. Code mode supports the auto-completion of tables, columns, SQL keywords, standard SQL functions, Grafana template variables, and Grafana macros. Columns cannot be completed before a table has been specified.
+
+{{< figure src="/static/img/docs/v92/sql_code_editor.png" class="docs-image--no-shadow" >}}
+
+Select **Table** or **Time Series** as the format. Click the **{}** in the bottom right to format the query. Click the **downward caret** to expand the Code mode editor. **CTRL/CMD + Return** serves as a keyboard shortcut to execute the query.
+
+{{% admonition type="warning" %}}
+Changes made to a query in Code mode will not transfer to Builder mode and will be discarded. You will be prompted to copy your code to the clipboard to save any changes.
+{{% /admonition %}}
+
+## Macros
+
+You can add macros to your queries to simplify the syntax and enable dynamic elements, such as date range filters.
+
+| Macro example | Description |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$__time(dateColumn)` | Replaces the value with an expression to convert to a UNIX timestamp and renames the column to `time_sec`. Example: _UNIX_TIMESTAMP(dateColumn) AS time_sec_. |
+| `$__timeEpoch(dateColumn)` | Replaces the value with an expression to convert to a UNIX Epoch timestamp and renames the column to `time_sec`. Example: _UNIX_TIMESTAMP(dateColumn) AS time_sec_. |
+| `$__timeFilter(dateColumn)` | Replaces the value a time range filter using the specified column name. Example: _dateColumn BETWEEN FROM_UNIXTIME(1494410783) AND FROM_UNIXTIME(1494410983)_ |
+| `$__timeFrom()` | Replaces the value with the start of the currently active time selection. Example: _FROM_UNIXTIME(1494410783)_ |
+| `$__timeTo()` | Replaces the value with the end of the currently active time selection. Example: _FROM_UNIXTIME(1494410983)_ |
+| `$__timeGroup(dateColumn,'5m')` | Replaces the value with an expression suitable for use in a GROUP BY clause. Example: *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)*300 as signed),\* |
+| `$__timeGroup(dateColumn,'5m', 0)` | Same as the `$__timeGroup(dateColumn,'5m')` macro, but includes a fill parameter to ensure missing points in the series are added by Grafana, using 0 as the default value. **This applies only to time series queries.** |
+| `$__timeGroup(dateColumn,'5m', NULL)` | Same as the `$__timeGroup(dateColumn,'5m', 0)` but NULL is used as the value for missing points. **This applies only to time series queries.** |
+| `$__timeGroup(dateColumn,'5m', previous)` | Same as the `$__timeGroup(dateColumn,'5m', previous)` macro, but uses the previous value in the series as the fill value. If no previous value exists,`NULL` will be used. **This applies only to time series queries.** |
+| `$__timeGroupAlias(dateColumn,'5m')` | Replaces the value identical to $\_\_timeGroup but with an added column alias. |
+| `$__unixEpochFilter(dateColumn)` | Replaces the value by a time range filter using the specified column name with times represented as a UNIX timestamp. Example: _dateColumn > 1494410783 AND dateColumn < 1494497183_ |
+| `$__unixEpochFrom()` | Replaces the value with the start of the currently active time selection as a UNIX timestamp. Example: _1494410783_ |
+| `$__unixEpochTo()` | Replaces the value with the end of the currently active time selection as UNIX timestamp. Example: _1494497183_ |
+| `$__unixEpochNanoFilter(dateColumn)` | Replaces the value with a time range filter using the specified column name with time represented as a nanosecond timestamp. Example: _dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872_ |
+| `$__unixEpochNanoFrom()` | Replaces the value with the start of the currently active time selection as nanosecond timestamp. Example: _1494410783152415214_ |
+| `$__unixEpochNanoTo()` | Replaces the value with the end of the currently active time selection as nanosecond timestamp. Example: _1494497183142514872_ |
+| `$__unixEpochGroup(dateColumn,'5m', [fillmode])` | Same as $\_\_timeGroup but for times stored as Unix timestamp. **Note that `fillMode` only works with time series queries.** |
+| `$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])` | Same as $\_\_timeGroup but also adds a column alias. **Note that `fillMode` only works with time series queries.** |
+
+## Table SQL queries
+
+If the **Format** option is set to **Table**, you can execute virtually any type of SQL query. The Table panel will automatically display the resulting columns and rows from your query.
+
+You can change or customize the name of a Table panel column by using the SQL keyword `AS` syntax.
+
+```sql
+SELECT
+ title as 'Title',
+ user.login as 'Created By' ,
+ dashboard.created as 'Created On'
+ FROM dashboard
+INNER JOIN user on user.id = dashboard.created_by
+WHERE $__timeFilter(dashboard.created)
+```
+
+Table panel results:
+
+
+
+## Time series queries
+
+Set the **Format** option to **Time series** to create and run time series queries.
+
+{{% admonition type="note" %}}
+To run a time series query you must include a column named `time` that returns either a SQL datetime value or a numeric datatype representing the UNIX epoch time in seconds. Additionally, the query results must be sorted by the `time` column for proper visualization in panels.
+{{% /admonition %}}
+
+The examples in this section refer to the data in the following table:
+
+```text
++---------------------+--------------+---------------------+----------+
+| time_date_time | value_double | CreatedAt | hostname |
++---------------------+--------------+---------------------+----------+
+| 2020-01-02 03:05:00 | 3.0 | 2020-01-02 03:05:00 | 10.0.1.1 |
+| 2020-01-02 03:06:00 | 4.0 | 2020-01-02 03:06:00 | 10.0.1.2 |
+| 2020-01-02 03:10:00 | 6.0 | 2020-01-02 03:10:00 | 10.0.1.1 |
+| 2020-01-02 03:11:00 | 7.0 | 2020-01-02 03:11:00 | 10.0.1.2 |
+| 2020-01-02 03:20:00 | 5.0 | 2020-01-02 03:20:00 | 10.0.1.2 |
++---------------------+--------------+---------------------+----------+
+```
+
+A time series query result is returned in a [wide data frame format](https://grafana.com/developers/plugin-tools/key-concepts/data-frames#wide-format). Any column except time or of type string transforms into value fields in the data frame query result. Any string column transforms into field labels in the data frame query result.
+
+{{% admonition type="note" %}}
+For backward compatibility, an exception to the aforementioned rule applies to queries returning three columns, including a string column named `metric`. Instead of converting the metric column into field labels, it is used as the field name, and the series name is set to the value of the metric column. Refer to the following example with a metric column.
+{{% /admonition %}}
+
+**Example with `metric` column:**
+
+```sql
+SELECT
+ $__timeGroupAlias(time_date_time,'5m'),
+ min(value_double),
+ 'min' as metric
+FROM test_data
+WHERE $__timeFilter(time_date_time)
+GROUP BY time
+ORDER BY time
+```
+
+Data frame result:
+
+```text
++---------------------+-----------------+
+| Name: time | Name: min |
+| Labels: | Labels: |
+| Type: []time.Time | Type: []float64 |
++---------------------+-----------------+
+| 2020-01-02 03:05:00 | 3 |
+| 2020-01-02 03:10:00 | 6 |
+| 2020-01-02 03:20:00 | 5 |
++---------------------+-----------------+
+```
+
+To customize the default series name formatting (optional), refer to [Standard options definitions](ref:configure-standard-options-display-name).
+
+**Example using the fill parameter in the $\_\_timeGroupAlias macro to convert null values to be zero instead:**
+
+```sql
+SELECT
+ $__timeGroupAlias(createdAt,'5m',0),
+ sum(value_double) as value,
+ hostname
+FROM test_data
+WHERE
+ $__timeFilter(createdAt)
+GROUP BY time, hostname
+ORDER BY time
+```
+
+Given the data frame result in the following example and using the graph panel, you will get two series named _value 10.0.1.1_ and _value 10.0.1.2_. To render the series with a name of _10.0.1.1_ and _10.0.1.2_ , use a [Standard options definitions](ref:configure-standard-options-display-name) display value of `${__field.labels.hostname}`.
+
+Data frame result:
+
+```text
++---------------------+---------------------------+---------------------------+
+| Name: time | Name: value | Name: value |
+| Labels: | Labels: hostname=10.0.1.1 | Labels: hostname=10.0.1.2 |
+| Type: []time.Time | Type: []float64 | Type: []float64 |
++---------------------+---------------------------+---------------------------+
+| 2020-01-02 03:05:00 | 3 | 4 |
+| 2020-01-02 03:10:00 | 6 | 7 |
+| 2020-01-02 03:15:00 | 0 | 0 |
+| 2020-01-02 03:20:00 | 0 | 5 |
++---------------------+---------------------------+---------------------------+
+```
+
+**Example with multiple columns:**
+
+```sql
+SELECT
+ $__timeGroupAlias(time_date_time,'5m'),
+ min(value_double) as min_value,
+ max(value_double) as max_value
+FROM test_data
+WHERE $__timeFilter(time_date_time)
+GROUP BY time
+ORDER BY time
+```
+
+Data frame result:
+
+```text
++---------------------+-----------------+-----------------+
+| Name: time | Name: min_value | Name: max_value |
+| Labels: | Labels: | Labels: |
+| Type: []time.Time | Type: []float64 | Type: []float64 |
++---------------------+-----------------+-----------------+
+| 2020-01-02 03:05:00 | 3 | 4 |
+| 2020-01-02 03:10:00 | 6 | 7 |
+| 2020-01-02 03:20:00 | 5 | 5 |
++---------------------+-----------------+-----------------+
+```
+
+## Templating
+
+Instead of hardcoding values like server, application, or sensor names in your metric queries, you can use variables. Variables appear as drop-down select boxes at the top of the dashboard. These drop-downs make it easy to change the data being displayed in your dashboard.
+
+Refer to [Templates](ref:variables) for an introduction to creating template variables as well as the different types.
+
+### Query variable
+
+If you add a `Query` template variable you can write a MySQL query to retrieve items such as measurement names, key names, or key values, which will be displayed in the drop-down menu.
+
+For example, you can use a variable to retrieve all the values from the `hostname` column in a table by creating the following query in the templating variable _Query_ setting.
+
+```sql
+SELECT hostname FROM my_host
+```
+
+A query can return multiple columns, and Grafana will automatically generate a list based on the query results. For example, the following query returns a list with values from `hostname` and `hostname2`.
+
+```sql
+SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city
+```
+
+To use time range dependent macros like `$__timeFilter(column)` in your query,you must set the template variable's refresh mode to _On Time Range Change_.
+
+```sql
+SELECT event_name FROM event_log WHERE $__timeFilter(time_column)
+```
+
+Another option is a query that can create a key/value variable. The query should return two columns that are named `__text` and `__value`. The `__text` column must contain unique values (if not, only the first value is used). This allows the drop-down options to display a text-friendly name as the text while using an ID as the value. For example, a query could use `hostname` as the text and `id` as the value:
+
+```sql
+SELECT hostname AS __text, id AS __value FROM my_host
+```
+
+You can also create nested variables. For example, if you have a variable named `region`, you can configure the `hosts` variable to display only the hosts within the currently selected region as shown in the following example. If `region` is a multi-value variable, use the `IN` operator instead of `=` to match multiple values.
+
+```sql
+SELECT hostname FROM my_host WHERE region IN($region)
+```
+
+#### Use `__searchFilter` to filter results in a query variable
+
+Using `__searchFilter` in the query field allows the query results to be filtered based on the user’s input in the drop-down selection box. If you do not enter anything, the default value for `__searchFilter` is %
+
+Note that you must enclose the `__searchFilter` expression in quotes as Grafana does not add them automatically.
+
+The following example demonstrates how to use `__searchFilter` in the query field to enable real-time searching for `hostname` as the user type in the drop-down selection box.
+
+```sql
+SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter'
+```
+
+### Using variables in queries
+
+Template variable values are only quoted when the template variable is a `multi-value`.
+
+If the variable is a multi-value variable, use the `IN` comparison operator instead of `=` to match against multiple values.
+
+You can use two different syntaxes:
+
+`$` Example with a template variable named `hostname`:
+
+```sql
+SELECT
+ UNIX_TIMESTAMP(atimestamp) as time,
+ aint as value,
+ avarchar as metric
+FROM my_table
+WHERE $__timeFilter(atimestamp) and hostname in($hostname)
+ORDER BY atimestamp ASC
+```
+
+`[[varname]]` Example with a template variable named `hostname`:
+
+```sql
+SELECT
+ UNIX_TIMESTAMP(atimestamp) as time,
+ aint as value,
+ avarchar as metric
+FROM my_table
+WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
+ORDER BY atimestamp ASC
+```
+
+#### Disabling quoting for multi-value variables
+
+Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. To disable quoting, use the csv formatting option for variables:
+
+Grafana automatically formats multi-value variables as a quoted, comma-separated string. For example, if `server01` and `server02` are selected, they are formatted as `'server01'`, `'server02'`. To remove the quotes, enable the CSV formatting option for the variables.
+
+`${servers:csv}`
+
+Read more about variable formatting options in the [Variables](ref:variable-syntax-advanced-variable-format-options) documentation.
+
+## Annotations
+
+[Annotations](ref:annotate-visualizations) allow you to overlay rich event information on top of graphs. You add annotation queries via the **Dashboard settings > Annotations view**.
+
+**Example query using a`time` column with epoch values:**
+
+```sql
+SELECT
+ epoch_time as time,
+ metric1 as text,
+ CONCAT(tag1, ',', tag2) as tags
+FROM
+ public.test_data
+WHERE
+ $__unixEpochFilter(epoch_time)
+```
+
+**Example region query using `time` and `timeend` columns with epoch values:**
+
+```sql
+SELECT
+ epoch_time as time,
+ epoch_timeend as timeend,
+ metric1 as text,
+ CONCAT(tag1, ',', tag2) as tags
+FROM
+ public.test_data
+WHERE
+ $__unixEpochFilter(epoch_time)
+```
+
+**Example query using a `time` column with a native SQL date/time data type:**
+
+```sql
+SELECT
+ native_date_time as time,
+ metric1 as text,
+ CONCAT(tag1, ',', tag2) as tags
+FROM
+ public.test_data
+WHERE
+ $__timeFilter(native_date_time)
+```
+
+| Name | Description |
+| --------- | --------------------------------------------------------------------------------------------------------------------- |
+| `time` | The name of the date/time field, which can be a column with a native SQL date/time data type or epoch value. |
+| `timeend` | Optional name of the end date/time field, which can be a column with a native SQL date/time data type or epoch value. |
+| `text` | Event description field. |
+| `tags` | Optional field name to use for event tags as a comma separated string. |
+
+## Alerting
+
+Use time series queries to create alerts. Table formatted queries aren't yet supported in alert rule conditions.
+
+For more information regarding alerting refer to the following:
+
+- [Alert rules](ref:alert-rules)
+- [Template annotations and labels](ref:template-annotations-and-labels)
diff --git a/docs/sources/datasources/prometheus/configure-prometheus-data-source.md b/docs/sources/datasources/prometheus/configure-prometheus-data-source.md
index 014487ae277..077b6aeff04 100644
--- a/docs/sources/datasources/prometheus/configure-prometheus-data-source.md
+++ b/docs/sources/datasources/prometheus/configure-prometheus-data-source.md
@@ -31,6 +31,11 @@ refs:
destination: /docs/grafana//panels-visualizations/configure-data-links/#value-variables
- pattern: /docs/grafana-cloud/
destination: /docs/grafana//panels-visualizations/configure-data-links/#value-variables
+ alerting-alert-rules:
+ - pattern: /docs/grafana/
+ destination: /docs/grafana//alerting/fundamentals/alert-rules/
+ - pattern: /docs/grafana-cloud/
+ destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rules/
---
# Configure Prometheus
@@ -115,11 +120,17 @@ Following are additional configuration options.
### Alerting
-- **Manage alerts via Alerting UI** - Toggle to enable `Alertmanager` integration for this data source.
+- **Manage alerts via Alerting UI** - Toggle to enable [data source-managed rules in Grafana Alerting](ref:alerting-alert-rules) for this data source. For `Mimir`, it enables managing data source-managed rules and alerts. For `Prometheus`, it only supports viewing existing rules and alerts, which are displayed as data source-managed.
+
+{{% admonition type="note" %}}
+
+The **Manage alerts via Alerting UI** toggle is enabled by default. You can change this behavior by setting the [default_manage_alerts_ui_toggle]({{< relref "../../setup-grafana/configure-grafana/#default_manage_alerts_ui_toggle" >}}) option in the Grafana configuration file.
+
+{{% /admonition %}}
### Interval behavior
-- **Scrape interval** - Set this to the typical scrape and evaluation interval configured in Prometheus. The default is `15s`.
+- **Scrape interval** - Set to the typical scrape and evaluation interval configured in Prometheus. The default is `15s`.
- **Query timeout** - The default is `60s`.
diff --git a/docs/sources/developers/http_api/team.md b/docs/sources/developers/http_api/team.md
index f7eec3d6260..e2c4cc654b4 100644
--- a/docs/sources/developers/http_api/team.md
+++ b/docs/sources/developers/http_api/team.md
@@ -179,7 +179,7 @@ Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
HTTP/1.1 200
Content-Type: application/json
-{"message":"Team created","teamId":2}
+{"message":"Team created","teamId":2,"uid":"ceaulqadfoav4e"}
```
Status Codes:
diff --git a/docs/sources/explore/get-started-with-explore.md b/docs/sources/explore/get-started-with-explore.md
index 321bc709cbb..7e78e4e80c3 100644
--- a/docs/sources/explore/get-started-with-explore.md
+++ b/docs/sources/explore/get-started-with-explore.md
@@ -43,7 +43,7 @@ In order to access Explore, you must have either the `editor` or `administrator`
Refer to [Role-based access control (RBAC)](https://grafana.com/docs/grafana//administration/roles-and-permissions/access-control/) in Grafana Enterprise to understand how you can manage Explore with role-based permissions.
{{< admonition type="note" >}}
-If you are using Grafana Cloud, open a [support ticket in the Cloud Portal](/https://grafana.com/auth/sign-in) to enable the `viewers_can_edit` option.
+If you are using Grafana Cloud, open a [support ticket in the Cloud Portal](https://grafana.com/auth/sign-in) to enable the `viewers_can_edit` option.
{{< /admonition >}}
## Explore elements
diff --git a/docs/sources/panels-visualizations/configure-tooltips/index.md b/docs/sources/panels-visualizations/configure-tooltips/index.md
index 4c7ee9e11e6..1ab9584df57 100644
--- a/docs/sources/panels-visualizations/configure-tooltips/index.md
+++ b/docs/sources/panels-visualizations/configure-tooltips/index.md
@@ -128,6 +128,10 @@ When you set the **Tooltip mode** to **All**, the **Values sort order** option i
- **Ascending** - Values in the tooltip are listed from smallest to largest.
- **Descending** - Values in the tooltip are listed from largest to smallest.
+### Hide zeros
+
+When you set the **Tooltip mode** to **All**, the **Hide zeros** option is displayed. This option controls whether or not series with `0` values are shown in the list in the tooltip.
+
### Hover proximity
Set the hover proximity (in pixels) to control how close the cursor must be to a data point to trigger the tooltip to display.
diff --git a/docs/sources/panels-visualizations/visualizations/traces/index.md b/docs/sources/panels-visualizations/visualizations/traces/index.md
index ba7926f1b6d..ac99c3a07bd 100644
--- a/docs/sources/panels-visualizations/visualizations/traces/index.md
+++ b/docs/sources/panels-visualizations/visualizations/traces/index.md
@@ -51,7 +51,7 @@ refs:
# Traces
Traces visualizations let you follow a request as it traverses the services in your infrastructure.
-The traces visualization displays traces data in a diagram that allows you to easily interpret it.
+The traces visualization displays traces data in a diagram that allows you to easily interpret it. Traces visualizations currently render one trace traversal based on the traceID used in TraceQL or using a variable.
For more information about traces and how to use them, refer to the following documentation:
@@ -166,3 +166,17 @@ You should now see a list of matching traces in the table visualization. While s
## Panel options
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="" >}}
+
+## Span filters
+
+The **Span filters** options control the initial state of the span filters when the visualization loads, allowing you to customize your trace analysis view.
+
+- **Find in trace** - Set the initial value to focus on spans relevant to your query.
+- **Show matches only** - Toggle the switch on to display only spans that match the defined filter criteria. This helps simplify trace interpretation.
+- **Show critical path only** - Toggle the switch on to highlight only the spans in the critical path, which helps identify performance bottlenecks and their impact on overall latency.
+- **Service name** and **Service name operator** - Define a specific service or pattern to narrow analysis to spans related to particular services.
+- **Span name** and **Span name operator** - Filter spans by name or pattern to focus on specific span types or processes.
+- **Min duration** and **Max duration** - Set duration thresholds to exclude spans outside the desired time range.
+- **Tags** - Add one or more tags to further refine the filtering criteria so only relevant spans are displayed.
+
+The options support variable interpolation, where you can set the service name to a variable `$var` and the visualization will replace it with the value for the variable named `$var` in the span filters. This applies to the service name, span name, duration fields, and tags.
diff --git a/docs/sources/setup-grafana/configure-grafana/_index.md b/docs/sources/setup-grafana/configure-grafana/_index.md
index 238da2179f5..6469a11891b 100644
--- a/docs/sources/setup-grafana/configure-grafana/_index.md
+++ b/docs/sources/setup-grafana/configure-grafana/_index.md
@@ -1,70 +1,88 @@
---
aliases:
- - ../administration/configuration/
- - ../installation/configuration/
-description: Configuration documentation
+ - ../administration/configuration/ # /docs/grafana/latest/administration/configuration/
+ - ../installation/configuration/ # /docs/grafana/latest/installation/configuration/
+description: Learn how to configure Grafana and understand configuration options.
labels:
products:
- enterprise
- oss
title: Configure Grafana
+toc:
+ endLevel: 4
weight: 200
---
# Configure Grafana
-Grafana has default and custom configuration files. You can customize your Grafana instance by modifying the custom configuration file or by using environment variables. To see the list of settings for a Grafana instance, refer to [View server settings]({{< relref "../../administration/stats-and-license#view-server-settings" >}}).
+Grafana has default and custom configuration files.
+You can customize your Grafana instance by modifying the custom configuration file or by using environment variables.
+To see the list of settings for a Grafana instance, refer to [View server settings](/docs/grafana//administration/stats-and-license#view-server-settings).
-{{% admonition type="note" %}}
-After you add custom options, [uncomment](#remove-comments-in-the-ini-files) the relevant sections of the configuration file. Restart Grafana for your changes to take effect.
-{{% /admonition %}}
+{{< admonition type="note" >}}
+After you add custom options, [uncomment](#remove-comments-in-the-ini-files) the relevant sections of the configuration file.
+
+Restart Grafana for your changes to take effect.
+{{< /admonition >}}
## Configuration file location
-The default settings for a Grafana instance are stored in the `$WORKING_DIR/conf/defaults.ini` file. _Do not_ change this file.
+The default settings for a Grafana instance are stored in the `/conf/defaults.ini` file.
+_Don't_ change this file.
-Depending on your OS, your custom configuration file is either the `$WORKING_DIR/conf/custom.ini` file or the `/usr/local/etc/grafana/grafana.ini` file. The custom configuration file path can be overridden using the `--config` parameter.
+Depending on your OS, your custom configuration file is either the `/conf/custom.ini` file or the `/usr/local/etc/grafana/grafana.ini` file.
+You can use a custom configuration path with the `--config` option.
### Linux
-If you installed Grafana using the `deb` or `rpm` packages, then your configuration file is located at `/etc/grafana/grafana.ini` and a separate `custom.ini` is not used. This path is specified in the Grafana init.d script using `--config` file parameter.
+If you installed Grafana using the deb or RPM packages, then your configuration file is located at `/etc/grafana/grafana.ini` and a separate `custom.ini` is not used.
+This path is specified in the Grafana init.d script using `--config` option.
### Docker
-Refer to [Configure a Grafana Docker image]({{< relref "../configure-docker" >}}) for information about environmental variables, persistent storage, and building custom Docker images.
+Refer to [Configure a Grafana Docker image](/docs/grafana//setup-grafana/configure-docker/) for information about environmental variables, persistent storage, and building custom Docker images.
### Windows
-On Windows, the `sample.ini` file is located in the same directory as `defaults.ini` file. It contains all the settings commented out. Copy `sample.ini` and name it `custom.ini`.
+On Windows, the `sample.ini` file is located in the same directory as `defaults.ini` file.
+It contains all the settings commented out.
+Copy `sample.ini` and name it `custom.ini`.
### macOS
-By default, the configuration file is located at `/opt/homebrew/etc/grafana/grafana.ini` or `/usr/local/etc/grafana/grafana.ini`. For a Grafana instance installed using Homebrew, edit the `grafana.ini` file directly. Otherwise, add a configuration file named `custom.ini` to the `conf` folder to override the settings defined in `conf/defaults.ini`.
+By default, the configuration file is located at `/opt/homebrew/etc/grafana/grafana.ini` or `/usr/local/etc/grafana/grafana.ini`.
+For a Grafana instance installed using Homebrew, edit the `grafana.ini` file directly.
+Otherwise, add a configuration file named `custom.ini` to the `conf` directory to override the settings defined in `conf/defaults.ini`.
## Remove comments in the .ini files
-Grafana uses semicolons (the `;` char) to comment out lines in a `.ini` file. You must uncomment each line in the `custom.ini` or the `grafana.ini` file that you are modify by removing `;` from the beginning of that line. Otherwise your changes will be ignored.
+Grafana uses semicolons (`;`) to comment out lines in the INI file.
+To uncomment a line, remove the semicolon (`;`) from the beginning of that line.
+
+Grafana ignores all configuration lines that begin with a semicolon.
For example:
-```
-# The HTTP port to use
+```ini
;http_port = 3000
```
## Override configuration with environment variables
-Do not use environment variables to _add_ new configuration settings. Instead, use environmental variables to _override_ existing options.
+Don't use environment variables to _add_ new configuration settings.
+Instead, use environmental variables to _override_ existing options.
To override an option:
```bash
-GF__
+GF__
```
-Where the section name is the text within the brackets. Everything should be uppercase, `.` and `-` should be replaced by `_`. For example, if you have these configuration settings:
+Where _``_ is the text within the square brackets (`[` and `]`) in the configuration file.
+All letters must be uppercase, periods (`.`) and dashes (`-`) must replaced by underscores (`_`).
+For example, if you have these configuration settings:
-```bash
+```ini
# default section
instance_name = ${HOSTNAME}
@@ -93,75 +111,87 @@ export GF_FEATURE_TOGGLES_ENABLE=newNavigation
## Variable expansion
-If any of your options contains the expression `$__{}`
-or `${}`, then they will be processed by Grafana's
-variable expander. The expander runs the provider with the provided argument
-to get the final value of the option.
+If any of your options contains the expression `$__{}`or `${}`, then Grafana evaluates them.
+The evaluation runs the provider with the provided argument to get the final value of the option.
There are three providers: `env`, `file`, and `vault`.
-### Env provider
+### `env` provider
-The `env` provider can be used to expand an environment variable. If you
-set an option to `$__env{PORT}` the `PORT` environment variable will be
-used in its place. For environment variables you can also use the
-short-hand syntax `${PORT}`.
-Grafana's log directory would be set to the `grafana` directory in the
-directory behind the `LOGDIR` environment variable in the following
-example.
+The `env` provider expands environment variables.
+If you set an option to `$__env{PORT}` the value of the `PORT` environment variable replaces it.
+For environment variables you can also use the short-hand syntax `${PORT}`.
+
+The following example sets the log directory to the path in the `LOGDIR` environment variable:
```ini
[paths]
logs = $__env{LOGDIR}/grafana
```
-### File provider
+### `file` provider
-`file` reads a file from the filesystem. It trims whitespace from the
-beginning and the end of files.
-The database password in the following example would be replaced by
-the content of the `/etc/secrets/gf_sql_password` file:
+The `file` provider reads a file from the filesystem.
+It trims whitespace from the beginning and the end of files.
+
+The following example sets the database password to the contents of the `/etc/secrets/gf_sql_password` file:
```ini
[database]
password = $__file{/etc/secrets/gf_sql_password}
```
-### Vault provider
+### `vault` provider
-The `vault` provider allows you to manage your secrets with [Hashicorp Vault](https://www.hashicorp.com/products/vault).
+The `vault` provider lets manage your secrets with [Hashicorp Vault](https://www.hashicorp.com/products/vault).
-> Vault provider is only available in Grafana Enterprise v7.1+. For more information, refer to [Vault integration]({{< relref "../configure-security/configure-database-encryption/integrate-with-hashicorp-vault" >}}) in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise" >}}).
+{{< admonition type="note" >}}
+The `vault` provider is only available in Grafana Enterprise.
+
+For more information, refer to [Integrate Grafana with Hashicorp Vault](/docs/grafana//setup-grafana/configure-security/configure-database-encryption/integrate-with-hashicorp-vault).
+
+{{< /admonition >}}
+
+## Configuration options
+
+The following headings describe the sections and configuration options of the Grafana configuration file.
+
+### `app_mode`
+
+Options are `production` and `development`.
+Default is `production`. _Don't_ change this option unless you are working on Grafana development.
+
+### `instance_name`
+
+Set the name of the Grafana server instance.
+Used in logging, internal metrics, and clustering info.
+Defaults to: `${HOSTNAME}`, which uses the value of the environment variable `HOSTNAME`, if that is empty or doesn't exist Grafana tries to use system calls to get the machine name.
-## app_mode
+### `[paths]`
-Options are `production` and `development`. Default is `production`. _Do not_ change this option unless you are working on Grafana development.
+#### `data`
-## instance_name
-
-Set the name of the grafana-server instance. Used in logging, internal metrics, and clustering info. Defaults to: `${HOSTNAME}`, which will be replaced with
-environment variable `HOSTNAME`, if that is empty or does not exist Grafana will try to use system calls to get the machine name.
-
-
-
-## [paths]
-
-### data
-
-Path to where Grafana stores the sqlite3 database (if used), file-based sessions (if used), and other data. This path is usually specified via command line in the init.d script or the systemd service file.
+Path to where Grafana stores the sqlite3 database (if used), file-based sessions (if used), and other data.
+This path is usually specified via command line in the init.d script or the systemd service file.
**macOS:** The default SQLite database is located at `/usr/local/var/lib/grafana`
-### temp_data_lifetime
+#### `temp_data_lifetime`
How long temporary images in `data` directory should be kept. Defaults to: `24h`. Supported modifiers: `h` (hours),
`m` (minutes), for example: `168h`, `30m`, `10h30m`. Use `0` to never clean up temporary files.
-### logs
+#### `logs`
-Path to where Grafana stores logs. This path is usually specified via command line in the init.d script or the systemd service file. You can override it in the configuration file or in the default environment variable file. However, please note that by overriding this the default log path will be used temporarily until Grafana has fully initialized/started.
+Path to where Grafana stores logs.
+This path is usually specified via command line in the init.d script or the systemd service file.
+You can override it in the configuration file or in the default environment variable file.
+
+{{< admonition type="note" >}}
+When overriding the default log path in the configuration file or environment variable file, Grafana still logs to the default log path until it has fully started.
+{{< /admonition >}}
Override log path using the command line argument `cfg:default.paths.logs`:
@@ -171,144 +201,147 @@ Override log path using the command line argument `cfg:default.paths.logs`:
**macOS:** By default, the log file should be located at `/usr/local/var/log/grafana/grafana.log`.
-### plugins
+#### `plugins`
Directory where Grafana automatically scans and looks for plugins. For information about manually or automatically installing plugins, refer to [Install Grafana plugins]({{< relref "../../administration/plugin-management#install-grafana-plugins" >}}).
**macOS:** By default, the Mac plugin location is: `/usr/local/var/lib/grafana/plugins`.
-### provisioning
+#### `provisioning`
-Folder that contains [provisioning]({{< relref "../../administration/provisioning" >}}) config files that Grafana will apply on startup. Dashboards will be reloaded when the json files changes.
+Directory that contains [provisioning]({{< relref "../../administration/provisioning" >}}) configuration files that Grafana applies on startup.
+Dashboards are reloaded when the JSON files change.
-## [server]
+### `[server]`
-### protocol
+#### `protocol`
`http`,`https`,`h2` or `socket`
-### min_tls_version
+#### `min_tls_version`
The TLS Handshake requires a minimum TLS version. The available options are TLS1.2 and TLS1.3.
If you do not specify a version, the system uses TLS1.2.
-### http_addr
+#### `http_addr`
-The host for the server to listen on. If your machine has more than one network interface, you can use this setting to expose the Grafana service on only one network interface and not have it available on others, such as the loopback interface. An empty value is equivalent to setting the value to `0.0.0.0`, which means the Grafana service binds to all interfaces.
+The host for the server to listen on.
+If your machine has more than one network interface, you can use this setting to expose the Grafana service on only one network interface and not have it available on others, such as the loopback interface.
+An empty value is equivalent to setting the value to `0.0.0.0`, which means the Grafana service binds to all interfaces.
In environments where network address translation (NAT) is used, ensure you use the network interface address and not a final public address; otherwise, you might see errors such as `bind: cannot assign requested address` in the logs.
-### http_port
+#### `http_port`
The port to bind to, defaults to `3000`. To use port 80 you need to either give the Grafana binary permission for example:
```bash
-$ sudo setcap 'cap_net_bind_service=+ep' /usr/sbin/grafana-server
+sudo setcap 'cap_net_bind_service=+ep' /usr/sbin/grafana-server
```
Or redirect port 80 to the Grafana port using:
```bash
-$ sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3000
+sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3000
```
Another way is to put a web server like Nginx or Apache in front of Grafana and have them proxy requests to Grafana.
-### domain
+#### `domain`
This setting is only used in as a part of the `root_url` setting (see below). Important if you use GitHub or Google OAuth.
-### enforce_domain
+#### `enforce_domain`
Redirect to correct domain if the host header does not match the domain. Prevents DNS rebinding attacks. Default is `false`.
-### root_url
+#### `root_url`
This is the full URL used to access Grafana from a web browser. This is
important if you use Google or GitHub OAuth authentication (for the
callback URL to be correct).
-{{% admonition type="note" %}}
-This setting is also important if you have a reverse proxy
-in front of Grafana that exposes it through a subpath. In that
-case add the subpath to the end of this URL setting.
-{{% /admonition %}}
+{{< admonition type="note" >}}
+This setting is also important if you have a reverse proxy in front of Grafana that exposes it through a sub-path.
-### serve_from_sub_path
+In that case add the sub-path to the end of this URL setting.
+{{< /admonition >}}
-Serve Grafana from subpath specified in `root_url` setting. By default it is set to `false` for compatibility reasons.
+#### `serve_from_sub_path`
-By enabling this setting and using a subpath in `root_url` above, e.g.`root_url = http://localhost:3000/grafana`, Grafana is accessible on `http://localhost:3000/grafana`. If accessed without subpath Grafana will redirect to
-an URL with the subpath.
+Serve Grafana from sub-path specified in `root_url` setting. By default it is set to `false` for compatibility reasons.
-### router_logging
+By enabling this setting and using a sub-path in `root_url` like `root_url = http://localhost:3000/grafana`, Grafana is accessible on `http://localhost:3000/grafana`.
+If accessed without sub-path Grafana redirects the request to the sub-path.
+
+#### `router_logging`
Set to `true` for Grafana to log all HTTP requests (not just errors). These are logged as Info level events to the Grafana log.
-### static_root_path
+#### `static_root_path`
-The path to the directory where the front end files (HTML, JS, and CSS
+The path to the directory where the frontend files (HTML, JS, and CSS
files). Defaults to `public` which is why the Grafana binary needs to be
executed with working directory set to the installation path.
-### enable_gzip
+#### `enable_gzip`
Set this option to `true` to enable HTTP compression, this can improve
transfer speed and bandwidth utilization. It is recommended that most
users set it to `true`. By default it is set to `false` for compatibility
reasons.
-### cert_file
+#### `cert_file`
Path to the certificate file (if `protocol` is set to `https` or `h2`).
-### cert_key
+#### `cert_key`
Path to the certificate key file (if `protocol` is set to `https` or `h2`).
-### certs_watch_interval
+#### `certs_watch_interval`
Controls whether `cert_key` and `cert_file` are periodically watched for changes.
Disabled, by default. When enabled, `cert_key` and `cert_file`
are watched for changes. If there is change, the new certificates are loaded automatically.
-{{% admonition type="warning" %}}
-After the new certificates are loaded, connections with old certificates
-will not work. You must reload the connections to the old certs for them to work.
-{{% /admonition %}}
+{{< admonition type="warning" >}}
+After the new certificates are loaded, connections with old certificates don't work.
+You must reload the connections with old certificates for them to work.
+{{< /admonition >}}
-### socket_gid
+#### `socket_gid`
GID where the socket should be set when `protocol=socket`.
Make sure that the target group is in the group of Grafana process and that Grafana process is the file owner before you change this setting.
-It is recommended to set the gid as http server user gid.
-Not set when the value is -1.
+It is recommended to set the GID as HTTP server user GID.
+Not set when the value is `-1`.
-### socket_mode
+#### `socket_mode`
Mode where the socket should be set when `protocol=socket`. Make sure that Grafana process is the file owner before you change this setting.
-### socket
+#### `socket`
Path where the socket should be created when `protocol=socket`. Make sure Grafana has appropriate permissions for that path before you change this setting.
-### cdn_url
+#### `cdn_url`
-Specify a full HTTP URL address to the root of your Grafana CDN assets. Grafana will add edition and version paths.
+Specify a full HTTP URL address to the root of your Grafana CDN assets. Grafana adds edition and version paths.
-For example, given a cdn url like `https://cdn.myserver.com` grafana will try to load a javascript file from
-`http://cdn.myserver.com/grafana-oss/7.4.0/public/build/app..js`.
+For example, given a CDN URL like `https://cdn.myserver.com`, Grafana tries to load a JavaScript file from
+`http://cdn.myserver.com/grafana-oss/7.4.0/public/build/app..js`.
-### read_timeout
+#### `read_timeout`
Sets the maximum time using a duration format (5s/5m/5ms) before timing out read of an incoming request and closing idle connections.
`0` means there is no timeout for reading the request.
-## [server.custom_response_headers]
+### `[server.custom_response_headers]`
This setting enables you to specify additional headers that the server adds to HTTP(S) responses.
@@ -319,398 +352,430 @@ exampleHeader2 = exampleValue2
-## [database]
+### `[database]`
Grafana needs a database to store users and dashboards (and other
things). By default it is configured to use [`sqlite3`](https://www.sqlite.org/index.html) which is an
embedded database (included in the main Grafana binary).
-### type
+#### `type`
Either `mysql`, `postgres` or `sqlite3`, it's your choice.
-### host
+#### `host`
Only applicable to MySQL or Postgres. Includes IP or hostname and port or in case of Unix sockets the path to it.
For example, for MySQL running on the same host as Grafana: `host = 127.0.0.1:3306` or with Unix sockets: `host = /var/run/mysqld/mysqld.sock`
-### name
+#### `name`
The name of the Grafana database. Leave it set to `grafana` or some
other name.
-### user
+#### `user`
The database user (not applicable for `sqlite3`).
-### password
+#### `password`
The database user's password (not applicable for `sqlite3`). If the password contains `#` or `;` you have to wrap it with triple quotes. For example `"""#password;"""`
-### url
+#### `url`
Use either URL or the other fields below to configure the database
Example: `mysql://user:secret@host:port/database`
-### max_idle_conn
+#### `max_idle_conn`
The maximum number of connections in the idle connection pool.
-### max_open_conn
+#### `max_open_conn`
The maximum number of open connections to the database. For MYSQL, configure this setting on both Grafana and the database. For more information, refer to [`sysvar_max_connections`](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections).
-### conn_max_lifetime
+#### `conn_max_lifetime`
Sets the maximum amount of time a connection may be reused. The default is 14400 (which means 14400 seconds or 4 hours). For MySQL, this setting should be shorter than the [`wait_timeout`](https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_wait_timeout) variable.
-### migration_locking
+#### `migration_locking`
Set to `false` to disable database locking during the migrations. Default is true.
-### locking_attempt_timeout_sec
+#### `locking_attempt_timeout_sec`
-For "mysql" and "postgres" only. Specify the time (in seconds) to wait before failing to lock the database for the migrations. Default is 0.
+For `mysql` and `postgres` only.
+Specify the time, in seconds, to wait before failing to lock the database for the migrations.
+Default is `0`.
-### log_queries
+#### `log_queries`
-Set to `true` to log the sql calls and execution times.
+Set to `true` to log the SQL calls and execution times.
-### ssl_mode
+#### `ssl_mode`
-For Postgres, use use any [valid libpq `sslmode`](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS), e.g.`disable`, `require`, `verify-full`, etc.
+For Postgres, use any [valid `libpq` `sslmode`](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS), for example, `disable`, `require`, `verify-full`, etc.
For MySQL, use either `true`, `false`, or `skip-verify`.
-### ssl_sni
+#### `ssl_sni`
-For Postgres, set to `0` to disable [Server Name Indication](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLSNI). This is enabled by default on SSL-enabled connections.
+For Postgres, set to `0` to disable [Server Name Indication](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-SSLSNI).
+This is enabled by default on SSL-enabled connections.
-### isolation_level
+#### `isolation_level`
Only the MySQL driver supports isolation levels in Grafana. In case the value is empty, the driver's default isolation level is applied. Available options are "READ-UNCOMMITTED", "READ-COMMITTED", "REPEATABLE-READ" or "SERIALIZABLE".
-### ca_cert_path
+#### `ca_cert_path`
The path to the CA certificate to use. On many Linux systems, certs can be found in `/etc/ssl/certs`.
-### client_key_path
+#### `client_key_path`
The path to the client key. Only if server requires client authentication.
-### client_cert_path
+#### `client_cert_path`
The path to the client cert. Only if server requires client authentication.
-### server_cert_name
+#### `server_cert_name`
The common name field of the certificate used by the `mysql` or `postgres` server. Not necessary if `ssl_mode` is set to `skip-verify`.
-### path
+#### `path`
-Only applicable for `sqlite3` database. The file path where the database
-will be stored.
+Only applicable for `sqlite3` database.
+The path to the database file.
-### cache_mode
+#### `cache_mode`
For "sqlite3" only. [Shared cache](https://www.sqlite.org/sharedcache.html) setting used for connecting to the database. (private, shared)
Defaults to `private`.
-### wal
+#### `wal`
For "sqlite3" only. Setting to enable/disable [Write-Ahead Logging](https://sqlite.org/wal.html). The default value is `false` (disabled).
-### query_retries
+#### `query_retries`
This setting applies to `sqlite` only and controls the number of times the system retries a query when the database is locked. The default value is `0` (disabled).
-### transaction_retries
+#### `transaction_retries`
This setting applies to `sqlite` only and controls the number of times the system retries a transaction when the database is locked. The default value is `5`.
-### instrument_queries
+#### `instrument_queries`
Set to `true` to add metrics and tracing for database queries. The default value is `false`.
-## [remote_cache]
+### `[remote_cache]`
Caches authentication details and session information in the configured database, Redis or Memcached. This setting does not configure [Query Caching in Grafana Enterprise]({{< relref "../../administration/data-source-management#query-and-resource-caching" >}}).
-### type
+#### `type`
Either `redis`, `memcached`, or `database`. Defaults to `database`
-### connstr
+#### `connstr`
The remote cache connection string. The format depends on the `type` of the remote cache. Options are `database`, `redis`, and `memcache`.
-#### database
+##### `database`
-Leave empty when using `database` since it will use the primary database.
+Leave empty when using `database` and Grafana uses the primary database.
-#### redis
+##### `redis`
-Example connstr: `addr=127.0.0.1:6379,pool_size=100,db=0,ssl=false`
+Example connection string: `addr=127.0.0.1:6379,pool_size=100,db=0,ssl=false`
-- `addr` is the host `:` port of the redis server.
-- `pool_size` (optional) is the number of underlying connections that can be made to redis.
-- `db` (optional) is the number identifier of the redis database you want to use.
-- `ssl` (optional) is if SSL should be used to connect to redis server. The value may be `true`, `false`, or `insecure`. Setting the value to `insecure` skips verification of the certificate chain and hostname when making the connection.
+- `addr` is the host `:` port of the Redis server.
+- `pool_size` (optional) is the number of underlying connections that can be made to Redis.
+- `db` (optional) is the number identifier of the Redis database you want to use.
+- `ssl` (optional) is if SSL should be used to connect to Redis server. The value may be `true`, `false`, or `insecure`. Setting the value to `insecure` skips verification of the certificate chain and hostname when making the connection.
-#### memcache
+##### `memcache`
-Example connstr: `127.0.0.1:11211`
+Example connection string: `127.0.0.1:11211`
-## [dataproxy]
+### `[dataproxy]`
-### logging
+#### `logging`
This enables data proxy logging, default is `false`.
-### timeout
+#### `timeout`
How long the data proxy should wait before timing out. Default is 30 seconds.
This setting also applies to core backend HTTP data sources where query requests use an HTTP client with timeout set.
-### keep_alive_seconds
+#### `keep_alive_seconds`
-Interval between keep-alive probes. Default is `30` seconds. For more details check the [Dialer.KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive) documentation.
+Interval between keep-alive probes. Default is `30` seconds. For more details, refer to the [`Dialer.KeepAlive`](https://golang.org/pkg/net/#Dialer.KeepAlive) documentation.
-### tls_handshake_timeout_seconds
+#### `tls_handshake_timeout_seconds`
-The length of time that Grafana will wait for a successful TLS handshake with the datasource. Default is `10` seconds. For more details check the [Transport.TLSHandshakeTimeout](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout) documentation.
+The length of time that Grafana waits for a successful TLS handshake with the data source.
+Default is `10` seconds.
+For more information, refer to the [`Transport.TLSHandshakeTimeout`](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout) documentation.
-### expect_continue_timeout_seconds
+#### `expect_continue_timeout_seconds`
-The length of time that Grafana will wait for a datasource’s first response headers after fully writing the request headers, if the request has an “Expect: 100-continue” header. A value of `0` will result in the body being sent immediately. Default is `1` second. For more details check the [Transport.ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout) documentation.
+The length of time that Grafana waits for the first response headers from a data source after fully writing the request headers, if the request has an `Expect: 100-continue` header.
+A value of `0` results in the body being sent immediately.
+Default is `1` second.
+For more information, refer to the [`Transport.ExpectContinueTimeout`](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout) documentation.
-### max_conns_per_host
+#### `max_conns_per_host`
-Optionally limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials are blocked. A value of `0` means that there are no limits. Default is `0`.
-For more details check the [Transport.MaxConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxConnsPerHost) documentation.
+Limits the total number of connections per host, including connections in the dialing, active, and idle states.
+On limit violation, dials are blocked.
+A value of `0` means that there are no limits.
+Default is `0`.
+For more information, refer to the [`Transport.MaxConnsPerHost`](https://golang.org/pkg/net/http/#Transport.MaxConnsPerHost) documentation.
-### max_idle_connections
+#### `max_idle_connections`
-The maximum number of idle connections that Grafana will maintain. Default is `100`. For more details check the [Transport.MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns) documentation.
+The maximum number of idle connections that Grafana maintains. Default is `100`.
+For more information, refer to the [`Transport.MaxIdleConns`](https://golang.org/pkg/net/http/#Transport.MaxIdleConns) documentation.
-### idle_conn_timeout_seconds
+#### `idle_conn_timeout_seconds`
-The length of time that Grafana maintains idle connections before closing them. Default is `90` seconds. For more details check the [Transport.IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout) documentation.
+The length of time that Grafana maintains idle connections before closing them. Default is `90` seconds.
+For more information, refer to the [`Transport.IdleConnTimeout`](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout) documentation.
-### send_user_header
+#### `send_user_header`
-If enabled and user is not anonymous, data proxy will add X-Grafana-User header with username into the request. Default is `false`.
+If enabled and user is not anonymous, data proxy adds the `X-Grafana-User` header with username into the request. Default is `false`.
-### response_limit
+#### `response_limit`
-Limits the amount of bytes that will be read/accepted from responses of outgoing HTTP requests. Default is `0` which means disabled.
+Limits the amount of bytes that Grafana reads from responses of outgoing HTTP requests. Default is `0` which means disabled.
-### row_limit
+#### `row_limit`
-Limits the number of rows that Grafana will process from SQL (relational) data sources. Default is `1000000`.
+Limits the number of rows that Grafana processes from SQL data sources. Default is `1000000`.
-### user_agent
+#### `user_agent`
Sets a custom value for the `User-Agent` header for outgoing data proxy requests. If empty, the default value is `Grafana/` (for example `Grafana/9.0.0`).
-## [analytics]
+### `[analytics]`
-### enabled
+#### `enabled`
This option is also known as _usage analytics_. When `false`, this option disables the writers that write to the Grafana database and the associated features, such as dashboard and data source insights, presence indicators, and advanced dashboard search. The default value is `true`.
-### reporting_enabled
+#### `reporting_enabled`
-When enabled Grafana will send anonymous usage statistics to
-`stats.grafana.org`. No IP addresses are being tracked, only simple counters to
-track running instances, versions, dashboard and error counts. It is very helpful
-to us, so please leave this enabled. Counters are sent every 24 hours. Default
-value is `true`.
+When enabled Grafana sends anonymous usage statistics to `stats.grafana.org`.
+Grafana doesn't track IP addresses, only counters of running instances, versions, dashboards, and errors.
-### check_for_updates
+The anonymous usage statistics help inform the future development of Grafana.
+Counters are sent every 24 hours.
+Default value is `true`.
-Set to false, disables checking for new versions of Grafana from Grafana's GitHub repository. When enabled, the check for a new version runs every 10 minutes. It will notify, via the UI, when a new version is available. The check itself will not prompt any auto-updates of the Grafana software, nor will it send any sensitive information.
+#### `check_for_updates`
-### check_for_plugin_updates
+Set to `false` to disable checking for new versions of Grafana in GitHub.
+When enabled, the check for a new version runs every ten minutes.
+It notifies, via the UI, when a new version is available.
+The check itself doesn't cause automatic updates of the Grafana software, nor does it send any sensitive information.
-Set to false disables checking for new versions of installed plugins from https://grafana.com. When enabled, the check for a new plugin runs every 10 minutes. It will notify, via the UI, when a new plugin update exists. The check itself will not prompt any auto-updates of the plugin, nor will it send any sensitive information.
+#### `check_for_plugin_updates`
-### google_analytics_ua_id
+Set to `false` to disable checking for new versions of installed plugins from https://grafana.com.
+When enabled, the check for a new plugin runs every ten minutes.
+It notifies, via the UI, when a new plugin update exists.
+The check itself doesn't cause any automatic updates of any plugins, nor does it send any sensitive information.
-If you want to track Grafana usage via Google analytics specify _your_ Universal
-Analytics ID here. By default this feature is disabled.
+#### `google_analytics_ua_id`
-### google_analytics_4_id
+If you want to track Grafana usage with Google Analytics specify _your_ Universal Analytics ID here.
+By default this feature is disabled.
-If you want to track Grafana usage via Google Analytics 4 specify _your_ GA4 ID here. By default this feature is disabled.
+#### `google_analytics_4_id`
-### google_tag_manager_id
+If you want to track Grafana usage with Google Analytics 4 specify _your_ GA4 ID here.
+By default this feature is disabled.
+
+#### `google_tag_manager_id`
Google Tag Manager ID, only enabled if you enter an ID here.
-### rudderstack_write_key
+#### `rudderstack_write_key`
-If you want to track Grafana usage via Rudderstack specify _your_ Rudderstack
+If you want to track Grafana usage via RudderStack specify _your_ RudderStack
Write Key here. The `rudderstack_data_plane_url` must also be provided for this
feature to be enabled. By default this feature is disabled.
-### rudderstack_data_plane_url
+#### `rudderstack_data_plane_url`
-Rudderstack data plane url that will receive Rudderstack events. The
-`rudderstack_write_key` must also be provided for this feature to be enabled.
+RudderStack data plane URL to receive RudderStack events.
+You must also provide the `rudderstack_write_key` to enable this feature.
-### rudderstack_sdk_url
+#### `rudderstack_sdk_url`
-Optional. If tracking with Rudderstack is enabled, you can provide a custom
-URL to load the Rudderstack SDK.
+Optional.
+If tracking with RudderStack is enabled, you can provide a custom URL to load the RudderStack SDK.
-### rudderstack_config_url
+#### `rudderstack_config_url`
-Optional. If tracking with Rudderstack is enabled, you can provide a custom
-URL to load the Rudderstack config.
+Optional.
+If tracking with RudderStack is enabled, you can provide a custom URL to load the RudderStack configuration.
-### rudderstack_integrations_url
+#### `rudderstack_integrations_url`
-Optional. If tracking with Rudderstack is enabled, you can provide a custom
-URL to load the SDK for destinations running in device mode. This setting is only valid for
-Rudderstack version 1.1 and higher.
+Optional.
+If tracking with RudderStack is enabled, you can provide a custom URL to load the SDK for destinations running in device mode.
+This setting is only valid for RudderStack version 1.1 and higher.
-### application_insights_connection_string
+#### `application_insights_connection_string`
If you want to track Grafana usage via Azure Application Insights, then specify _your_ Application Insights connection string. Since the connection string contains semicolons, you need to wrap it in backticks (`). By default, tracking usage is disabled.
-### application_insights_endpoint_url
+#### `application_insights_endpoint_url`
Optionally, use this option to override the default endpoint address for Application Insights data collecting. For details, refer to the [Azure documentation](https://docs.microsoft.com/en-us/azure/azure-monitor/app/custom-endpoints?tabs=js).
-### feedback_links_enabled
+#### `feedback_links_enabled`
Set to `false` to remove all feedback links from the UI. Default is `true`.
-## [security]
+### `[security]`
-### disable_initial_admin_creation
+#### `disable_initial_admin_creation`
-Disable creation of admin user on first start of Grafana. Default is `false`.
+Disable creation of a Grafana Admin user on first start of Grafana. Default is `false`.
-### admin_user
+#### `admin_user`
The name of the default Grafana Admin user, who has full permissions.
Default is `admin`.
-### admin_password
+#### `admin_password`
The password of the default Grafana Admin. Set once on first-run. Default is `admin`.
-### admin_email
+#### `admin_email`
The email of the default Grafana Admin, created on startup. Default is `admin@localhost`.
-### secret_key
+#### `secret_key`
Used for signing some data source settings like secrets and passwords, the encryption format used is AES-256 in CFB mode. Cannot be changed without requiring an update
to data source settings to re-encode them.
-### disable_gravatar
+#### `disable_gravatar`
Set to `true` to disable the use of Gravatar for user profile images.
Default is `false`.
-### data_source_proxy_whitelist
+#### `data_source_proxy_whitelist`
-Define a whitelist of allowed IP addresses or domains, with ports, to be used in data source URLs with the Grafana data source proxy. Format: `ip_or_domain:port` separated by spaces. PostgreSQL, MySQL, and MSSQL data sources do not use the proxy and are therefore unaffected by this setting.
+Define a allowlist of IP addresses or domains with ports, that can be used in data source URLs with the Grafana data source proxy.
-### disable_brute_force_login_protection
+The format is `` or `:` separated by spaces.
+PostgreSQL, MySQL, and MSSQL data sources don't use the proxy and are not affected by this setting.
-Set to `true` to disable [brute force login protection](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#account-lockout). Default is `false`. An existing user's account will be unable to login for 5 minutes if all login attempts are spent within a 5 minute window.
+#### `disable_brute_force_login_protection`
-### brute_force_login_protection_max_attempts
+Set to `true` to disable [brute force login protection](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#account-lockout).
+Default is `false`.
+An existing user's account is unable to login for five minutes if all login attempts are spent within a 5 minute window.
-Configure how many login attempts a user have within a 5 minute window before the account will be locked. Default is `5`.
+#### `brute_force_login_protection_max_attempts`
-### cookie_secure
+Configure how many login attempts a user can have within a five minute window before their account is locked.
+Default is `5`.
+
+#### `cookie_secure`
Set to `true` if you host Grafana behind HTTPS. Default is `false`.
-### cookie_samesite
+#### `cookie_samesite`
Sets the `SameSite` cookie attribute and prevents the browser from sending this cookie along with cross-site requests. The main goal is to mitigate the risk of cross-origin information leakage. This setting also provides some protection against cross-site request forgery attacks (CSRF), [read more about SameSite here](https://owasp.org/www-community/SameSite). Valid values are `lax`, `strict`, `none`, and `disabled`. Default is `lax`. Using value `disabled` does not add any `SameSite` attribute to cookies.
-### allow_embedding
+#### `allow_embedding`
-When `false`, the HTTP header `X-Frame-Options: deny` will be set in Grafana HTTP responses which will instruct
-browsers to not allow rendering Grafana in a ``, `