@ -31,9 +31,9 @@ You can configure data source permissions to allow or deny certain users the abi
- The `edit` permission allows users to query the data source, edit the data source’s configuration and delete the data source.
- The `admin` permission allows users to query and edit the data source, change permissions on the data source and enable or disable query caching for the data source.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](../../introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
By default, data sources in an organization can be queried by any user in that organization. For example, a user with the `Viewer` role can issue any possible query to a data source, not just queries that exist on dashboards to which they have access. Additionally, by default, data sources can be edited by the user who created the data source, as well as users with the `Admin` role.
@ -82,15 +82,15 @@ When using Grafana, a query pertains to a request for data frames to be modified
The caching feature works for **all** backend data sources. You can enable the cache globally in Grafana's [configuration](../../setup-grafana/configure-grafana/enterprise-configuration/#caching), and configure a cache duration (also called Time to Live, or TTL) for each data source individually.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](../../introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
{{</admonition>}}
The following cache backend options are available: in-memory, Redis, and Memcached.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Storing cached queries in-memory can increase Grafana's memory footprint. In production environments, a Redis or Memcached backend is highly recommended.
{{% /admonition %}}
{{</admonition>}}
When a panel queries a data source with cached data, it will either fetch fresh data or use cached data depending on the panel's **interval.** The interval is used to round the query time range to a nearby cached time range, increasing the likelihood of cache hits. Therefore, wider panels and dashboards with shorter time ranges fetch new data more often than narrower panels and dashboards with longer time ranges.
@ -110,15 +110,15 @@ By reducing the number of queries and requests sent to data sources, caching can
Query caching works for Grafana's [built-in data sources](../../datasources/#built-in-core-data-sources), and [backend data source plugins](https://grafana.com/grafana/plugins/?type=datasource) that extend the `DataSourceWithBackend` class in the plugins SDK.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Logs Insights for the CloudWatch data source does not support query caching due to the way logs are requested from AWS.
{{% /admonition %}}
{{</admonition>}}
To verify that a data source works with query caching, follow the [instructions below](#enable-and-configure-query-caching) to **Enable and Configure query caching**. If caching is enabled in Grafana but the Caching tab is not visible for the given data source, then query caching is not available for that data source.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Some data sources, such as Elasticsearch, Prometheus, and Loki, cache queries themselves, so Grafana _query_ caching does not significantly improve performance. However, _resource_ caching may help. Refer to [plugin resources](https://grafana.com/developers/plugin-tools/key-concepts/backend-plugins/) for details.
{{% /admonition %}}
{{</admonition>}}
### Enable and configure query caching
@ -137,9 +137,9 @@ You can optionally override a data source's configured TTL for individual dashbo
{{<figuremax-width="500px"src="/media/docs/grafana/per-panel-cache-ttl-9-4.png"caption="Set Cache TTL for a single panel">}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If query caching is enabled and the Cache tab is not visible in a data source's settings, then query caching is not available for that data source.
{{% /admonition %}}
{{</admonition>}}
To configure global settings for query caching, refer to the `caching` section of [Configure Grafana Enterprise](../../setup-grafana/configure-grafana/enterprise-configuration/#caching).
@ -158,9 +158,9 @@ To disable query caching for an entire Grafana instance, set the `enabled` flag
If you experience performance issues or repeated queries become slower to execute, consider clearing your cache.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
This action impacts all cache-enabled data sources. If you are using Memcached, the system clears all data from the Memcached instance.
{{% /admonition %}}
{{</admonition>}}
1. Click **Connections** in the left-side menu.
1. Under Your Connections, click **Data sources**.
@ -52,13 +52,13 @@ To download your Grafana Enterprise license:
You must install a Grafana Enterprise build to use the enterprise features, which you can [download](https://grafana.com/grafana/download?edition=enterprise).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you already use Grafana OSS, you can replace it with the same version of Grafana Enterprise.
Ensure that you back up the configuration and database before proceeding.
For more information, refer to [Back up Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/back-up-grafana/).
{{% /admonition %}}
{{</admonition>}}
There is more than one way to add the license to a Grafana instance:
@ -222,7 +222,7 @@ All plugins are signed under a _signature level_. The signature level determines
{{<admonitiontype="note">}}
Unsigned plugins are not supported in Grafana Cloud.
{{% /admonition %}}
{{</admonition>}}
We strongly recommend that you don't run unsigned plugins in your Grafana instance. However, if you're aware of the risks and you still want to load an unsigned plugin, refer to [Configuration](../../setup-grafana/configure-grafana/#allow_loading_unsigned_plugins).
Recorded queries are deprecated. Please use the new [Grafana-managed recording rules](/docs/grafana/latest/alerting/alerting-rules/create-recording-rules/create-grafana-managed-recording-rules) instead.
To learn how to migrate your recorded queries to Grafana-managed recording rules, refer to the migration documentation [here.](/docs/grafana/latest/alerting/alerting-rules/create-recording-rules/migrate-recorded-queries)
{{% /admonition %}}
{{</admonition>}}
Recorded queries allow you to see trends over time by taking a snapshot of a data point on a set interval. This can give you insight into historic trends.
For our plugins that do not return time series, it might be useful to plot historical data. For example, you might want to query ServiceNow to see a history of request response times but it can only return current point-in-time metrics.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](https://grafana.com/docs/grafana-cloud/).
{{% /admonition %}}
{{</admonition>}}
## How recorded queries work
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
An administrator must configure a Prometheus data source and associate it with a [Remote write target](#remote-write-target) before recorded queries can be used.
{{% /admonition %}}
{{</admonition>}}
Recorded queries only work with backend data source plugins. Refer to [Backend data source plugin](/tutorials/build-a-data-source-backend-plugin/) for more information about backend data source plugins. You can recorded four types of queries:
@ -25,9 +25,9 @@ You can assign a user one of three types of permissions:
- Organization permissions: Manage access to dashboards, alerts, plugins, teams, playlists, and other resources for an entire organization. The available roles are Viewer, Editor, and Admin.
- Dashboard and folder permission: Manage access to dashboards and folders
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you are running Grafana Enterprise, you can also control access to data sources and use role-based access control to grant user access to read and write permissions to specific Grafana resources. For more information about access control options available with Grafana Enterprise, refer to [Grafana Enterprise user permissions features](#grafana-enterprise-user-permissions-features).
{{% /admonition %}}
{{</admonition>}}
{{<admonitiontype="note">}}
For Grafana Cloud users, Grafana Support is not authorised to make org role changes. Instead, contact your org administrator.
@ -37,9 +37,9 @@ For Grafana Cloud users, Grafana Support is not authorised to make org role chan
A Grafana server administrator manages server-wide settings and access to resources such as organizations, users, and licenses. Grafana includes a default server administrator that you can use to manage all of Grafana, or you can divide that responsibility among other server administrators that you create.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The server administrator role does not mean that the user is also a Grafana [organization administrator](#organization-roles).
{{% /admonition %}}
{{</admonition>}}
A server administrator can perform the following tasks:
@ -49,9 +49,9 @@ A server administrator can perform the following tasks:
- View Grafana server statistics, including total users and active sessions
- Upgrade the server to Grafana Enterprise.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The server administrator role does not exist in Grafana Cloud.
{{% /admonition %}}
{{</admonition>}}
To assign or remove server administrator privileges, see [Server user management](../user-management/server-user-management/assign-remove-server-admin-privileges/).
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
RBAC provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as dashboards, reports, and administrative settings.
@ -151,9 +151,9 @@ Each basic role is comprised of a number of _permissions_. For example, the view
- `Action: annotations:write, Scope: annotations:type:dashboard`: Enables the viewer to modify annotations of a dashboard.
- `Action: annotations:delete, Scope: annotations:type:dashboard`: Enables the viewer to remove annotations from a dashboard.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You can't have a Grafana user without a basic role assigned. The `None` role contains no permissions.
{{% /admonition %}}
{{</admonition>}}
#### Basic role modification
@ -165,9 +165,9 @@ For example, if you modify Viewer basic role and grant additional permission, Ed
For more information about the permissions associated with each basic role, refer to [Basic role definitions](ref:rbac-role-definitions-basic-role-assignments).
To interact with the API and view or modify basic roles permissions, refer to [the table](ref:rbac-basic-role-uid-mapping) that maps basic role names to the associated UID.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You cannot use a service account to modify basic roles via the RBAC API. To update basic roles, you must be a Grafana administrator and use basic authentication with the request.
{{% /admonition %}}
{{</admonition>}}
For Cloud customers, contact Support to reset roles.
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
The table below describes all RBAC configuration options. Like any other Grafana configuration, you can apply these options as [environment variables](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#override-configuration-with-environment-variables).
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles.
@ -255,9 +255,9 @@ roles:
The following examples show you how to create a custom role using the Grafana HTTP API. For more information about the HTTP API, refer to [Create a new custom role](ref:api-rbac-create-a-new-custom-role).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You cannot create a custom role with permissions that you do not have. For example, if you only have `users:create` permissions, then you cannot create a role that includes other permissions.
{{% /admonition %}}
{{</admonition>}}
The following example creates a `custom:users:admin` role and assigns the `users:create` action to it.
@ -314,9 +314,9 @@ If the default basic role definitions do not meet your requirements, you can cha
- Determine the permissions you want to add or remove from a basic role. For more information about the permissions associated with basic roles, refer to [RBAC role definitions](ref:rbac-fixed-basic-role-definitions-basic-role-assignments).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You cannot modify the `No Basic Role` permissions.
{{% /admonition %}}
{{</admonition>}}
**To change permissions from a basic role:**
@ -371,10 +371,10 @@ roles:
scope: 'folder:*'
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You can add multiple `fixed`, `basic` or `custom` roles to the `from` section. Their permissions will be copied and added to the basic role.
Make sure to **increment** the role version for the changes to be accounted for.
{{% /admonition %}}
{{</admonition>}}
You can also change basic roles' permissions using the API. Refer to the [RBAC HTTP API](ref:api-rbac-update-a-role) for more details.
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
An RBAC rollout strategy helps you determine _how_ you want to implement RBAC prior to assigning RBAC roles to users and teams.
@ -92,13 +92,13 @@ Consider the following guidelines when you determine if you should modify basic
- **Modify basic roles** when Grafana's definitions of what viewers, editors, and admins can do does not match your definition of these roles. You can add or remove permissions from any basic role.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Changes that you make to basic roles impact the role definition for all [organizations](/docs/grafana/<GRAFANA_VERSION>/administration/organization-management/) in the Grafana instance. For example, when you add the `fixed:users:writer` role's permissions to the viewer basic role, all viewers in any org in the Grafana instance can create users within that org.
{{% /admonition %}}
{{</admonition>}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You cannot modify the `No Basic Role` permissions.
{{% /admonition %}}
{{</admonition>}}
- **Create custom roles** when fixed role definitions don't meet you permissions requirements. For example, the `fixed:dashboards:writer` role allows users to delete dashboards. If you want some users or teams to be able to create and update but not delete dashboards, you can create a custom role with a name like `custom:dashboards:creator` that lacks the `dashboards:delete` permission.
@ -115,9 +115,9 @@ Use any of the following methods to assign RBAC roles to users and teams.
We've compiled the following permissions rollout scenarios based on current Grafana implementations.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have a use case that you'd like to share, feel free to contribute to this docs page. We'd love to hear from you!
{{% /admonition %}}
{{</admonition>}}
### Provide internal viewer employees with the ability to use Explore, but prevent external viewer contractors from using Explore
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
You can create, change or remove [Custom roles](ref:manage-rbac-roles-create-custom-roles-using-provisioning) and create or remove [basic role assignments](ref:assign-rbac-roles-assign-a-fixed-role-to-a-basic-role-using-provisioning), by adding one or more YAML configuration files in the `provisioning/access-control/` directory.
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
You can create, change or remove [Custom roles](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/role) and create or remove [basic and custom role assignments](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/role_assignment), by using [Terraform's Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
You can enable auditing in the Grafana configuration file.
@ -46,10 +46,10 @@ Learn more about [access control audit logs](/docs/grafana/<GRAFANA_VERSION>/set
This happens when an instance is downgraded from a version that uses RBAC to a version that uses the legacy access control, and dashboard, folder or data source permissions are updated.
These permission updates will not be applied to RBAC, so permissions will be out of sync when the instance is next upgraded to a version with RBAC.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
the steps provided below will set all dashboard, folder and data source permissions to what they are set to with the legacy access control.
If you have made dashboard, folder or data source permission updates with RBAC enabled, these updates will be wiped.
@ -78,11 +78,11 @@ A common use case for creating a service account is to perform operations on aut
In [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/), you can also use service accounts in combination with [role-based access control](ref:rbac) to grant very specific permissions to applications that interact with Grafana.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Service accounts can only act in the organization they are created for. If you have the same task that is needed for multiple organizations, we recommend creating service accounts in each organization.
Service accounts can't be used for instance-wide operations, such as global user management and organization management. For these tasks, you need to use a user with [Grafana server administrator permissions](ref:roles-and-permissions).
{{% /admonition %}}
{{</admonition>}}
{{<vimeo742056367>}}
@ -168,9 +168,9 @@ You can assign organization roles to a service account using the Grafana UI or v
In [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/), you can also [assign RBAC roles](ref:rbac-assign-rbac-roles) to grant very specific permissions to applications that interact with Grafana.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Since Grafana 10.2.0, the `No Basic Role` is available for organization users or service accounts. This role has no permissions. Permissions can be granted with RBAC.
{{% /admonition %}}
{{</admonition>}}
### Before you begin
@ -237,10 +237,10 @@ To list your token's permissions, use the `/api/access-control/user/permissions`
#### Example
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The following command output is shortened to show only the relevant content.
Authorize your request with the token whose permissions you want to check.
{{% /admonition %}}
{{</admonition>}}
```bash
curl -H "Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7FDsNSLAa_54e2f8be" -X GET '<grafana_url>/api/access-control/user/permissions' | jq
API keys are deprecated. [Service accounts](ref:service-accounts) now replace API keys for authenticating with the **HTTP APIs** and interacting with Grafana.
{{% /admonition %}}
{{</admonition>}}
API keys specify a role—either **Admin**, **Editor**, or **Viewer**—that determine the permissions associated with interacting with Grafana.
@ -252,9 +252,9 @@ This section shows you how to migrate your Terraform configuration for Grafana c
For migration your cloud stack api keys, use the `grafana_cloud_stack_service_account` and `gafana_cloud_stack_service_account_token` resources. For additional information, refer to [Grafana Cloud Stack Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_stack_service_account).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
This is only relevant for Grafana Cloud **Stack** API keys `grafana_cloud_stack_api_key`. Grafana Cloud API keys resource `grafana_cloud_api_key` are not deprecated and should be used for authentication for managing your Grafana cloud.
@ -41,9 +41,9 @@ When you grant folder permissions, that setting applies to all dashboards and su
For example, if a user with the viewer organization role requires editor (or admin) access to a dashboard, you can assign those elevated permissions on an individual basis.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have assigned a user dashboard folder permissions, you cannot also assign the user permission to dashboards contained in the folder.
{{% /admonition %}}
{{</admonition>}}
Grant dashboard permissions when you want to restrict or enhance dashboard access for users who do not have permissions defined in the associated folder.
@ -21,9 +21,9 @@ Organization administrators can invite users to join their organization. Organiz
For more information about organization user permissions, refer to [Organization users and permissions](../../roles-and-permissions/#organization-users-and-permissions).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Users added at the organization level will have access to all stacks and services by default, without the ability to be filtered by stack unless Single Sign-On (SSO) or Role-Based Access Control (RBAC) is implemented.
{{% /admonition %}}
{{</admonition>}}
{{<section>}}
@ -40,17 +40,17 @@ You can see a list of users with accounts in your Grafana organization. If neces
1. Sign in to Grafana as an organization administrator.
1. Navigate to **Administration > Users and access > Users**.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have [server administrator](../../roles-and-permissions/#grafana-server-administrators) permissions, you can also [view a global list of users](../server-user-management/#view-a-list-of-users) in the Server Admin section of Grafana.
{{% /admonition %}}
{{</admonition>}}
## Change a user's organization permissions
Update user permissions when you want to enhance or restrict a user's access to organization resources. For more information about organization permissions, refer to [Organization roles](../../roles-and-permissions/#organization-roles).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Organization roles sync from the authentication provider on user sign-in. To prevent synchronization of organization roles from the authentication provider regardless of their role in the authentication provider, then refer to the `skip_org_role_sync` setting in your Grafana configuration. Refer to [skip org role sync](../../../setup-grafana/configure-grafana/#authgrafana_com-skip_org_role_sync) for more information.
{{% /admonition %}}
{{</admonition>}}
### Before you begin
@ -68,9 +68,9 @@ Organization roles sync from the authentication provider on user sign-in. To pre
1. Select the role that you want to assign.
1. Click **Update**.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have [server administrator](../../roles-and-permissions/#grafana-server-administrators) permissions, you can also [change a user's organization permissions](../server-user-management/change-user-org-permissions/) in the Server Admin section.
{{% /admonition %}}
{{</admonition>}}
## Invite a user to join an organization
@ -79,9 +79,9 @@ When you invite users to join an organization, you assign the **Admin**, **Edito
- If you know that the user already has access Grafana and you know their user name, then you issue an invitation by entering their user name.
- If the user is new to Grafana, then use their email address to issue an invitation. The system automatically creates the user account on first sign in.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have [server administrator](../../roles-and-permissions/#grafana-server-administrators) permissions, you can also manually [add a user to an organization](../server-user-management/add-remove-user-to-org/).
{{% /admonition %}}
{{</admonition>}}
### Before you begin
@ -116,9 +116,9 @@ If the invitee is not already a user, the system adds them.
Periodically review invitations you have sent so that you can see a list of users that have not yet accepted the invitation or cancel a pending invitation.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The **Pending Invites** button is only visible if there are unanswered invitations.
@ -41,9 +41,9 @@ You can see a list of users with accounts on your Grafana server. This action mi
1. Sign in to Grafana as a server administrator.
1. Click **Administration** in the left-side menu, **Users and access**, and then **Users**.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have [organization administrator](../../roles-and-permissions/#organization-roles) permissions and _not_ [server administrator](../../roles-and-permissions/#grafana-server-administrators) permissions, you can still [view of list of users in a given organization](../manage-org-users/#view-a-list-of-organization-users).
{{% /admonition %}}
{{</admonition>}}
## View user details
@ -121,9 +121,9 @@ When you configure advanced authentication using Oauth, SAML, LDAP, or the Auth
When you create a user, the system assigns the user viewer permissions in a default organization, which you can change. You can now [add a user to a second organization](add-remove-user-to-org/).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have [organization administrator](../../roles-and-permissions/#organization-roles) permissions and _not_ [server administrator](../../roles-and-permissions/#grafana-server-administrators) permissions, you can still add users by [inviting a user to join an organization](../manage-org-users/#invite-a-user-to-join-an-organization).
@ -42,9 +42,9 @@ You are required to specify an Admin role for each organization. The first user
The next time the user signs in, they will be able to navigate to their new organization using the Switch Organizations option in the user profile menu.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you have [organization administrator](../../../roles-and-permissions/#organization-roles) permissions and _not_ [server administrator](../../../roles-and-permissions/#grafana-server-administrators) permissions, you can still [invite a user to join an organization](../../manage-org-users/#invite-a-user-to-join-an-organization).
Grafana server administrators are responsible for creating users, organizations, and managing permissions. For more information about the server administration role, refer to [Grafana server administrators](../../../roles-and-permissions/#grafana-server-administrators).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Server administrators are "super-admins" with full permissions to create, read, update, and delete all resources and users in all organizations, as well as update global settings such as licenses. Only grant this permission to trusted users.
@ -26,9 +26,9 @@ You can also view important information about your account, such as the organiza
You can change your Grafana password at any time.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If your Grafana instance uses an external authentication provider, then you might not be able to change your password in Grafana. Contact your Grafana administrator for more information.
@ -81,9 +81,9 @@ You can then [view the alert state on the panel](ref:view-alert-state-on-panels)
By default, notification messages include a link to the dashboard panel. Additionally, you can [enable displaying panel screenshots in notifications](ref:images-in-notifications).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Changes to panel and alert rule queries aren't synchronized. If you change a query, you have to update it in both the panel and the alert rule.
{{% /admonition %}}
{{</admonition>}}
## Access linked alert rules from panels
@ -95,4 +95,4 @@ This option is available only in [time series panels](ref:time-series-visualizat
{{<admonitiontype="tip">}}
For a practical example, refer to our [Getting started: Link alerts to visualizations tutorial](http://www.grafana.com/tutorials/alerting-get-started-pt6/).
@ -72,9 +72,9 @@ At the start of notification templates, dot (`.`) refers to [Notification Data](
In annotation and label templates, dot (`.`) is initialized with all alert data. It’s recommended to use the [`$labels` and `$values` variables](ref:alert-rule-template-reference-variables) instead to directly access the alert labels and query values.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Dot (`.`) might refer to something else when used in a [range](#range), a [with](#with), or when writing [templates](#templates) used in other templates.
{{% /admonition %}}
{{</admonition>}}
[//]: <> (The above section is not included in the shared file because `refs` links are not supported in shared files.)
The _Math_ expression works as long as each series in `$A` can be matched with exactly one series in `$B`. They must align in a way that produces a one-to-one match between series in `$A` and `$B`.
{{% admonition type="caution" %}}
{{<admonitiontype="caution">}}
If a series in one query doesn’t match any series in the other, it’s excluded from the result and a warning message is displayed:
_1 items **dropped from union(s)**: ["$A > $B": ($B: {service=payment-api})]_
{{% /admonition %}}
{{</admonition>}}
**Labels in both series don’t need to be identical**. If labels are a subset of the other, they can join. For example:
@ -78,9 +78,9 @@ When an alert instance is assigned to a notification policy, the notification po
- Controlling when notifications are sent using the [timing options](ref:policy-timing-options).
- Determining the [contact points](ref:configure-contact-points) that receive the alert notification.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The default notification policy and its child policies are assigned to a [specific Alertmanager](ref:alertmanager-architecture), and they cannot use contact points or mute timings from other Alertmanagers.
@ -111,9 +111,9 @@ A label matchers consists of 3 distinct parts, the **label**, the **value** and
| `=~` | Select labels that regex-match the value. |
| `!~` | Select labels that do not regex-match the value. |
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you are using multiple label matchers, they are combined using the AND logical operator. This means that all matchers must match in order to link a rule to a policy.
@ -133,9 +133,9 @@ On the **Contact Points** tab, you can:
- Export individual contact points or all contact points in JSON, YAML, or Terraform format.
- Delete contact points. Note that you cannot delete contact points that are in use by a notification policy. To proceed, either delete the notification policy or update it to use another contact point.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Contact points are assigned to a [specific Alertmanager](ref:configure-alertmanager) and cannot be used by notification policies in other Alertmanagers.
@ -37,11 +37,11 @@ For example, a team might run its own Alertmanager to manage notifications from
This setup avoids duplicating Alertmanager configurations for better maintenance.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
To send all Grafana-managed alerts to an Alertmanager, add it as a data source and enable it to receive all alerts. With this setup, you can configure multiple Alertmanagers to receive all alerts.
For setup instructions, refer to [Configure Alertmanagers](ref:configure-alertmanagers).
@ -85,11 +85,11 @@ The notification message would look like this:
Description: This alert fires when a web server responds with more 5xx errors than is expected. This could be an issue with the web server or a backend service.
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Avoid adding extra information about alert instances in notification templates, as this information will only be visible in the notification message.
Instead, you should [use annotations or labels](ref:template-annotations-and-labels) to add information directly to the alert, ensuring it's also visible in the alert state and alert history within Grafana. You can then print the new alert annotation or label in notification templates.
{{% /admonition %}}
{{</admonition>}}
#### Select a notification template for a contact point
@ -73,11 +73,11 @@ Notification templates allows you to change the default notification messages.
You can modify the content and format of notification messages. For example, you can customize the content to show only specific information or adjust the format to suit a particular contact point, such as Slack or Email.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Avoid adding extra information about alert instances in notification templates, as this information is only visible in the notification message.
Instead, you should [use annotations or labels](ref:template-annotations-and-labels) to add information directly to the alert, ensuring it's also visible in the alert state and alert history within Grafana. You can then print the new alert annotation or label in notification templates.
{{% /admonition %}}
{{</admonition>}}
This page provides various examples illustrating how to template common notification messages. For more details about notification templates, refer to:
Grafana Cloud users can request this feature by [opening a support ticket in the Cloud Portal](/profile/org#support).
{{% /admonition %}}
{{</admonition>}}
Images in notifications helps recipients of alert notifications better understand why an alert has fired or resolved by including a screenshot of the panel associated with the alert.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
This feature is not supported in Mimir or Loki, or when Grafana is configured to send alerts to other Alertmanagers such as the Prometheus Alertmanager.
{{% /admonition %}}
{{</admonition>}}
When an alert is fired or resolved Grafana takes a screenshot of the panel associated with the alert. This is determined via the Dashboard UID and Panel ID annotations of the rule. Grafana cannot take a screenshot for alerts that are not associated with a panel.
@ -60,9 +60,9 @@ Refer to the table at the end of this page for a list of contact points and thei
## Configuration
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana Cloud users can request this feature by [opening a support ticket in the Cloud Portal](/profile/org#support).
{{% /admonition %}}
{{</admonition>}}
Having installed either the image rendering plugin, or set up Grafana to use a remote rendering service, set `capture` in `[unified_alerting.screenshots]` to `true`:
@ -76,9 +76,9 @@ At the start of notification templates, dot (`.`) refers to [Notification Data](
In annotation and label templates, dot (`.`) is initialized with all alert data. It’s recommended to use the [`$labels` and `$values` variables](ref:alert-rule-template-reference-variables) instead to directly access the alert labels and query values.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Dot (`.`) might refer to something else when used in a [range](#range), a [with](#with), or when writing [templates](#templates) used in other templates.
{{% /admonition %}}
{{</admonition>}}
[//]: <> (The above section is not included in the shared file because `refs` links are not supported in shared files.)
@ -100,9 +100,9 @@ For more details on how to write notification templates, refer to the [template
Preview how your notification templates should look before using them in your contact points, helping you understand the result of the template you are creating as well as enabling you to fix any errors before saving it.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Notification template preview is only for Grafana Alertmanager.
@ -90,9 +90,9 @@ A label matchers consists of 3 distinct parts, the **label**, the **value** and
| `=~` | Select labels that regex-match the value. |
| `!~` | Select labels that do not regex-match the value. |
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you are using multiple label matchers, they are combined using the AND logical operator. This means that all matchers must match in order to link a rule to a policy.
{{% /admonition %}}
{{</admonition>}}
**Label matching example**
@ -138,13 +138,13 @@ If a matching policy is found, the system continues to evaluate its child polici
By default, once a matching policy is found, the system does not continue to look for sibling policies. If you want sibling policies of one matching policy to handle the alert instance as well, then enable **Continue matching siblings** on the particular matching policy.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The default notification policy matches all alert instances. It always handles alert instances if there are no child policies or if none of the child policies match the alert instance's labels—this prevents any alerts from being missed.
If alerts use multiple labels, these labels must also be present in a notification policy to match and route notifications to a specific contact point.
{{% /admonition %}}
{{</admonition>}}
{{<collapsetitle="Routing example">}}
@ -156,9 +156,9 @@ The `team=security` policy is not a match and **Continue matching siblings** was
**Disk Usage – 80%** has both a `team` and `severity` label, and matches a child policy of the operations team.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When an alert matches both a parent policy and a child policy (like it does in this case), the routing follows the child policy (`severity`) as it provides a more specific match.
{{% /admonition %}}
{{</admonition>}}
**Unauthorized log entry** has a `team` label but does not match the first policy (`team=operations`) since the values are not the same, so it will continue searching and match the `team=security` policy. It does not have any child policies, so the additional `severity=high` label is ignored.
@ -24,13 +24,13 @@ An alert event is displayed each time an alert instance changes its state over a
## View from the History page
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
For Grafana Enterprise and OSS users:
The feature is available starting with Grafana 11.2.
To try out the new alert history page, enable the `alertingCentralAlertHistory` feature toggle and configure [Loki annotations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/alerting/set-up/configure-alert-state-history/).
Users can only see the history and transitions of alert rules they have access to (RBAC).
{{% /admonition %}}
{{</admonition>}}
To access the History view, complete the following steps.
@ -44,9 +44,9 @@ To access the History view, complete the following steps.
3. Filter by current state and previous state by selecting a state from the drop-down or by clicking the states from the list of events.
Zoom in by dragging on the chart or use the time picker.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you exceed the 5000 alerts limit, you may see data missing from the chart. To see complete results, narrow the time frame.
{{% /admonition %}}
{{</admonition>}}
4. Under the chart, there is a list of events. Each event represents a state change on an alert instance. Expand a row to see the number of transitions for the alert instance, a state graph, and the value in the transition.
5. Click the alert rule name to jump to the History tab in the Alert Rule view.
@ -59,9 +59,9 @@ Use the State history view to get insight into how your individual alert instanc
View information on when a state change occurred, what the previous state was, the current state, any other alert instances that changed their state at the same time as well as what the query value was that triggered the change.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Open source users must [configure alert state history](/docs/grafana/latest/alerting/set-up/configure-alert-state-history/) in order to be able to access the view.
{{% /admonition %}}
{{</admonition>}}
To access the State history view, complete the following steps.
@ -101,9 +101,9 @@ For provisioning instructions, refer to the [Alertmanager data source documentat
After adding an Alertmanager, you can use the Grafana Alerting UI to manage notification policies, contact points, silences, and other alerting resources from within Grafana.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When using Prometheus, you can manage silences in the Grafana Alerting UI. However, other Alertmanager resources such as contact points, notification policies, and templates are read-only because the Prometheus Alertmanager HTTP API does not support updates for these resources.
{{% /admonition %}}
{{</admonition>}}
When using multiple Alertmanagers, use the `Choose Alertmanager` dropdown to switch between Alertmanagers.
@ -119,9 +119,9 @@ After enabling **Receive Grafana Alerts** in the Data Source Settings, you must
All Grafana-managed alerts are forwarded to Alertmanagers marked as `Receiving Grafana-managed alerts`.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana Alerting does not support forwarding Grafana-managed alerts to the AlertManager in Amazon Managed Service for Prometheus. For more details, refer to [this GitHub issue](https://github.com/grafana/grafana/issues/64064).
{{% /admonition %}}
{{</admonition>}}
## Use an Alertmanager as a contact point to receive specific alerts
@ -69,11 +69,11 @@ For a demo, see this [example using Docker Compose](https://github.com/grafana/a
As an alternative to Memberlist, you can configure Redis to enable high availability. Redis standalone, Redis Cluster and Redis Sentinel modes are supported.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Memberlist is the preferred option for high availability. Use Redis only in environments where direct communication between Grafana servers is not possible, such as when TCP or UDP ports are blocked.
{{% /admonition %}}
{{</admonition>}}
1. Make sure you have a Redis server that supports pub/sub. If you use a proxy in front of your Redis cluster, make sure the proxy supports pub/sub.
1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the `[unified_alerting]` section.
@ -163,13 +163,13 @@ For a demo, see this [example using Docker Compose](https://github.com/grafana/a
When running multiple Grafana instances, all alert rules are evaluated on every instance. This multiple evaluation of alert rules is visible in the [state history](ref:state-history) and provides a straightforward way to verify that your high availability configuration is working correctly.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If using a mix of `execute_alerts=false` and `execute_alerts=true` on the HA nodes, since the alert state is not shared amongst the Grafana instances, the instances with `execute_alerts=false` do not show any alert status.
The HA settings (`ha_peers`, etc.) apply only to communication between alertmanagers, synchronizing silences and attempting to avoid duplicate notifications, as described in the introduction.
{{% /admonition %}}
{{</admonition>}}
You can also confirm your high availability setup by monitoring Alertmanager metrics exposed by Grafana.
@ -137,7 +137,7 @@ To export alert rules from the Grafana UI, complete the following steps.
### Modify alert rule and export rule group without saving changes
{{% admonition type="note" %}} This feature is for Grafana-managed alert rules only. It is available to Admin, Viewer, and Editor roles. {{% /admonition %}}
{{<admonitiontype="note">}} This feature is for Grafana-managed alert rules only. It is available to Admin, Viewer, and Editor roles. {{</admonition>}}
Use the **Modify export** mode to edit and export an alert rule without updating it. The exported data includes all alert rules within the same alert group.
@ -155,7 +155,7 @@ To export a modified alert rule without saving the modifications, complete the f
### Export a new alert rule definition without saving changes
{{% admonition type="note" %}} You can only export in Terraform (HCL) format. {{% /admonition %}}
{{<admonitiontype="note">}} You can only export in Terraform (HCL) format. {{</admonition>}}
Add a new alert rule definition to an existing provisioned rule group rather than creating the code manually. You can then copy it to your Terraform pipeline, and quickly deploy and manage alert rules as part of your infrastructure as code.
@ -27,11 +27,11 @@ For our purposes, a breaking change is any change that requires users or operato
- Changes that affect some plugins or functions of Grafana
- Migrations that can’t be rolled back
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
To learn what's available in a Grafana release, refer to the [What's new ](../whatsnew/) page for each version. For the steps we recommend when you upgrade, check out the [Upgrade guide](../upgrade-guide/) for each version.
{{% /admonition %}}
{{</admonition>}}
Refer to any of the following breaking changes guides:
When a user creates a new dashboard, a new dashboard JSON object is initialized with the following fields:
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
In the following JSON, id is shown as null which is the default value assigned to it until a dashboard is saved. Once a dashboard is saved, an integer value is assigned to the `id` field.
When you search within a folder, its subfolders are not part of the results returned. You need to be on the **Dashboards** page (or the root level) to search for subfolders by name.
{{% /admonition %}}
{{</admonition>}}
## Search dashboards using panel title
@ -120,6 +120,6 @@ To filter dashboard search result by a tag, complete one of the following steps:
All tags will be shown, and when you select a tag, the dashboard search will be instantly filtered.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When using only a keyboard, press the `tab` key and navigate to the **Filter by tag** drop-down menu, press the down arrow key `▼` to activate the menu and locate a tag, and press `Enter` to select the tag.
@ -174,14 +174,14 @@ The following table provides example relative ranges:
| This Year | `now/Y` | `now/Y` |
| Previous fiscal year | `now-1y/fy` | `now-1y/fy` |
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana Alerting does not support the following syntaxes at this time:
- now+n for future timestamps.
- now-1n/n for "start of n until end of n" because this is an absolute timestamp.
{{% /admonition %}}
{{</admonition>}}
### Common time range controls
@ -229,11 +229,11 @@ This section also displays recently used absolute ranges.
#### Semi-relative time range
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana Alerting does not support semi-relative time ranges.
{{% /admonition %}}
{{</admonition>}}
You can also use the absolute time range settings to set a semi-relative time range. Semi-relative time range dashboards are useful when you need to monitor the progress of something over time, but you also want to see the entire history from a starting point.
@ -68,9 +68,9 @@ Administrators can also [provision the data source](#provision-the-data-source)
Once you've added the data source, you can [configure it](#configure-the-data-source) so that your Grafana instance's users can create queries in its [query editor](query-editor/) when they [build dashboards](ref:build-dashboards) and use [Explore](ref:explore).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
To troubleshoot issues while setting up the CloudWatch data source, check the `/var/log/grafana/grafana.log` file.
{{% /admonition %}}
{{</admonition>}}
## Configure the data source
@ -407,9 +407,9 @@ filter @message like /Exception/
| sort exceptionCount desc
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you receive an error like `input data must be a wide series but got ...` when trying to alert on a query, make sure that your query returns valid numeric data that can be output to a Time series panel.
{{% /admonition %}}
{{</admonition>}}
For more information on Grafana alerts, refer to [Alerting](ref:alerting).
@ -420,10 +420,10 @@ Pricing for CloudWatch Logs is based on the amount of data ingested, archived, a
Each time you select a dimension in the query editor, Grafana issues a `ListMetrics` API request.
Each time you change queries in the query editor, Grafana issues a new request to the `GetMetricData` API.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana replaced all `GetMetricStatistics` API requests with calls to GetMetricData to provide better support for CloudWatch metric math, and enables the automatic generation of search expressions when using wildcards or disabling the `Match Exact` option.
The `GetMetricStatistics` API qualified for the CloudWatch API free tier, but `GetMetricData` calls don't.
{{% /admonition %}}
{{</admonition>}}
For more information, refer to the [CloudWatch pricing page](https://aws.amazon.com/cloudwatch/pricing/).
@ -67,9 +67,9 @@ Open source Grafana enables the `AWS SDK Default`, `Credentials file`, and `Acce
## Assume a role
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Assume a role is required for the Grafana Assume Role.
{{% /admonition %}}
{{</admonition>}}
You can specify an IAM role to assume in the **Assume Role ARN** field.
@ -87,9 +87,9 @@ To disable this feature in open source Grafana or Grafana Enterprise, refer to t
### Use an external ID
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You cannot use an external ID for the Grafana Assume Role authentication provider.
{{% /admonition %}}
{{</admonition>}}
To assume a role in another account that was created with an external ID, specify the external ID in the **External ID** field.
@ -128,9 +128,9 @@ For more information on why and how to use service endpoints, refer to the [AWS
Create a file at `~/.aws/credentials`, the `HOME` path for the user running the `grafana-server` service.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you think you have the credentials file in the right location, but it's not working, try moving your `.aws` file to `/usr/share/grafana/` and grant your credentials file at most 0644 permissions.
{{% /admonition %}}
{{</admonition>}}
### Credentials file example
@ -159,13 +159,13 @@ securityContext:
## Use Grafana Assume Role
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana Assume Role is currently in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud.
It's currently only available for Amazon CloudWatch.
To gain early access to this feature, contact Customer Support and ask for the `awsDatasourcesTempCredentials` feature toggle to be enabled on your account.
{{% /admonition %}}
{{</admonition>}}
The Grafana Assume Role authentication provider lets you authenticate with AWS without having to create and maintain long term AWS users or rotate their access and secret keys. Instead, you can create an IAM role that has permissions to access CloudWatch and a trust relationship with Grafana's AWS account. Grafana's AWS account then makes an STS request to AWS to create temporary credentials to access your AWS data. It makes this STS request by passing along an `externalID` that's unique per Cloud account, to ensure that Grafana Cloud users can only access their own AWS data. For more information, refer to the [AWS documentation on external ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html).
@ -111,9 +111,9 @@ For details on the available functions, refer to [AWS Metric Math](https://docs.
For example, to apply arithmetic operations to a metric, apply a unique string id to the raw metric, then use this id and apply arithmetic operations to it in the Expression field of the new metric.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you use the expression field to reference another query, like `queryA * 2`, you can't create an alert rule based on that query.
{{% /admonition %}}
{{</admonition>}}
#### Period macro
@ -192,9 +192,9 @@ The suggestions appear after typing a space, comma, or dollar (`$`) character, o
@ -66,9 +66,9 @@ In contrast, Azure Monitor Logs can store a variety of data types, each with the
1. Select a resource from which to query metrics by using the subscription, resource group, resource type, and resource fields. Multiple resources can also be selected as long as they belong to the same subscription, region and resource type. Note that only a limited amount of resource types support this feature.
1. To select a different namespace than the default—for instance, to select resources like storage accounts that are organized under multiple namespaces—use the **Namespace** option.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Not all metrics returned by the Azure Monitor Metrics API have values.
{{% /admonition %}}
{{</admonition>}}
> The data source retrieves lists of supported metrics for each subscription and ignores metrics that never have values.
@ -139,10 +139,10 @@ The Azure Monitor data source also supports querying of [Basic Logs](https://lea
1. Select a resource to query. Multiple resources can be selected as long as they are of the same type.
Alternatively, you can dynamically query all resources under a single resource group or subscription.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If a timespan is specified in the query, the overlap of the timespan between the query and the dashboard will be used as the query timespan. See the [API documentation for
@ -155,10 +155,10 @@ You can also augment queries by using [template variables](../template-variables
1. Select the **Logs** service.
1. Select a resource to query. Multiple resources can be selected as long as they are of the same type.
1. Switch the `Logs` toggle from `Analytics` to `Basic`. A modal will display to notify users of potential additional costs.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Basic Logs queries do not support time-ranges specified in the query. The time-range will be hardcoded to the dashboard time-range. There are also other query limitations. See the
[documentation for details.](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/basic-logs-query?tabs=portal-1#limitations)
{{% /admonition %}}
{{</admonition>}}
1. Enter your KQL query.
You can also augment queries by using [template variables](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/datasources/azure-monitor/template-variables/).
@ -348,17 +348,17 @@ Application Insights stores trace data in an underlying Log Analytics workspace
1. Select the **Traces** service.
1. Select a resource to query. Multiple resources can be selected as long as they are of the same type.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
This query type only supports Application Insights resources.
{{% /admonition %}}
{{</admonition>}}
Running a query of this kind will return all trace data within the timespan specified by the panel/dashboard.
Optionally, you can apply further filtering or select a specific Operation ID to query. The result format can also be switched between a tabular format or the trace format which will return the data in a format that can be used with the Trace visualization.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Selecting the trace format will filter events with the `trace` type.
@ -95,9 +95,9 @@ Select one of the following authentication methods from the dropdown menu.
### TLS settings
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Use TLS (Transport Layer Security) for an additional layer of security when working with Elasticsearch. For information on setting up TLS encryption with Elasticsearch see [Configure TLS](https://www.elastic.co/guide/en/elasticsearch/reference/8.8/configuring-tls.html#configuring-tls). You must add TLS settings to your Elasticsearch configuration file **prior** to setting these options in Grafana.
{{% /admonition %}}
{{</admonition>}}
- **Add self-signed certificate** - Check the box to authenticate with a CA certificate. Follow the instructions of the CA (Certificate Authority) to download the certificate file. Required for verifying self-signed TLS certificates.
@ -166,9 +166,9 @@ You can also override this setting in a dashboard panel under its data source op
- **Include frozen indices** - Toggle on when the `X-Pack enabled` setting is active. Includes frozen indices in searches. You can configure Grafana to include [frozen indices](https://www.elastic.co/guide/en/elasticsearch/reference/7.13/frozen-indices.html) when performing search requests.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Frozen indices are [deprecated in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/frozen-indices.html) since v7.14.
Grafana provides a query editor for Elasticsearch. Elasticsearch queries are in Lucene format.
See [Lucene query syntax](https://www.elastic.co/guide/en/kibana/current/lucene-query.html) and [Query string syntax](https://www.elastic.co/guide/en/elasticsearch/reference/8.9/query-dsl-query-string-query.html#query-string-syntax) if you are new to working with Lucene queries in Elasticsearch.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When composing Lucene queries, ensure that you use uppercase boolean operators: `AND`, `OR`, and `NOT`. Lowercase versions of these operators are not supported by the Lucene query syntax.
@ -68,9 +68,9 @@ These queries by default return results in term order (which can then be sorted
To produce a list of terms sorted by doc count (a top-N values list), add an `orderBy` property of "doc_count".
This automatically selects a descending sort.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
To use an ascending sort (`asc`) with doc_count (a bottom-N list), set `order: "asc"`. However, Elasticsearch [discourages this](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html#search-aggregations-bucket-terms-aggregation-order) because sorting by ascending doc count can return inaccurate results.
{{% /admonition %}}
{{</admonition>}}
To keep terms in the doc count order, set the variable's Sort dropdown to **Disabled**.
You can alternatively use other sorting criteria, such as **Alphabetical**, to re-sort them.
@ -74,9 +74,9 @@ In the case that the metric value type is a distribution, the aggregation will b
The various metrics are documented [here](https://cloud.google.com/monitoring/api/metrics_gcp) and further details on the kinds and types of metrics can be found [here](https://cloud.google.com/monitoring/api/v3/kinds-and-types).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Distribution metrics are typically best visualized as either a heatmap or histogram. When visualizing in this way, aggregation is not necessary. However, for other visualization types, performance degradation may be observed when attempting to query distribution metrics that are not aggregated due to the number of potential buckets that can be returned. For more information on how to visualize distribution metrics refer to [this page](https://cloud.google.com/monitoring/charts/charting-distribution-metrics).
@ -71,9 +71,9 @@ Some functions like aliasByNode support an optional second argument. To add an a
To learn more, refer to [Graphite's documentation on functions](https://graphite.readthedocs.io/en/latest/functions.html).
{{% admonition type="warning" %}}
{{<admonitiontype="warning">}}
Some functions take a second argument that may be a function that returns a series. If you are adding a second argument that is a function, it is suggested to use a series reference from a second query instead of the function itself. The query editor does not currently support parsing of a second argument that is a function when switching between the query editor and the code editor.
{{% /admonition %}}
{{</admonition>}}
### Sort labels
@ -91,10 +91,10 @@ Grafana consolidates all Graphite metrics so that Graphite doesn't return more d
By default, Grafana consolidates data points using the `avg` function.
To control how Graphite consolidates metrics, use the Graphite `consolidateBy()` function.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Legend summary values (max, min, total) can't all be correct at the same time because they are calculated client-side by Grafana.
Depending on your consolidation function, only one or two can be correct at the same time.
{{% /admonition %}}
{{</admonition>}}
### Combine time series
@ -109,10 +109,10 @@ To select data, use the `seriesByTag` function, which takes tag expressions (`=`
The Grafana query builder does this for you automatically when you select a tag.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The regular expression search can be slow on high-cardinality tags, so try to use other tags to reduce the scope first.
To help reduce the results, start by filtering on a particular name or namespace.
@ -109,9 +109,9 @@ You can also configure settings specific to the Jaeger data source. These option
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
{{</admonition>}}
The **Trace to logs** setting configures the [trace to logs feature](ref:explore-trace-integration) that is available when you integrate Grafana with Jaeger.
@ -72,9 +72,9 @@ Administrators can also [configure the data source via YAML](#provision-the-data
Once you've added the Loki data source, you can [configure it](#configure-the-data-source) so that your Grafana instance's users can create queries in its [query editor](query-editor/) when they [build dashboards](ref:build-dashboards), use [Explore](ref:explore), and [annotate visualizations](query-editor/#apply-annotations).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
To troubleshoot configuration and other issues, check the log file located at `/var/log/grafana/grafana.log` on Unix systems, or in `<grafana_install_dir>/data/log` on other platforms and manual installations.
@ -61,9 +61,9 @@ The first option to configure is the name of your connection:
There are several authentication methods you can choose in the Authentication section.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Use TLS (Transport Layer Security) for an additional layer of security when working with Loki. For information on setting up TLS encryption with Loki see [Grafana Loki configuration parameters](/docs/loki/latest/configuration/).
{{% /admonition %}}
{{</admonition>}}
- **Basic authentication** - The most common authentication method. Use your `data source` user name and `data source` password to connect.
@ -91,9 +91,9 @@ Use TLS (Transport Layer Security) for an additional layer of security when work
- **Maximum lines** - Sets the maximum number of log lines returned by Loki. Increase the limit to have a bigger results set for ad-hoc analysis. Decrease the limit if your browser is sluggish when displaying log results. The default is `1000`.
<!-- {{% admonition type="note" %}}
<!-- {{< admonition type="note" >}}
To troubleshoot configuration and other issues, check the log file located at `/var/log/grafana/grafana.log` on Unix systems, or in `<grafana_install_dir>/data/log` on other platforms and manual installations.
{{% /admonition %}} -->
{{</admonition>}} -->
### Derived fields
@ -104,9 +104,9 @@ These links appear in the [log details](ref:log-details).
You can add multiple derived fields.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you use Grafana Cloud, you can request modifications to this feature by clicking **Open a Support Ticket** from the Grafana Cloud Portal.
{{% /admonition %}}
{{</admonition>}}
Each derived field consists of the following:
@ -114,9 +114,9 @@ Each derived field consists of the following:
- **Type** - Defines the type of the derived field. It can be either:
{{% admonition type="caution" %}}
{{<admonitiontype="caution">}}
Using complex regular expressions in either type can impact browser performance when processing large volumes of logs. Consider using simpler patterns when possible.
{{% /admonition %}}
{{</admonition>}}
- **Regex**: A regular expression to parse a part of the log message and capture it as the value of the new field. Can contain only one capture group.
@ -55,9 +55,9 @@ To switch between the editor modes, select the corresponding **Builder** and **C
To run a query, select **Run queries** located at the top of the editor.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
To run Loki queries in [Explore](ref:explore), select **Run query**.
{{% /admonition %}}
{{</admonition>}}
Each mode is synchronized, so you can switch between them without losing your work, although there are some limitations. Builder mode doesn't support some complex queries.
When you switch from Code mode to Builder mode with such a query, the editor displays a warning message that explains how you might lose parts of the query if you continue.
@ -66,9 +66,9 @@ Grafana’s query editors are unique for each data source. For general informati
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" %}}
{{<admonitiontype="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 %}}
{{</admonition>}}
## MySQL query editor components
@ -76,9 +76,9 @@ 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" %}}
{{<admonitiontype="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 %}}
{{</admonition>}}
## MySQL Builder mode
@ -121,9 +121,9 @@ To create advanced queries, switch to **Code mode** by clicking **Code** in the
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" %}}
{{<admonitiontype="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 %}}
{{</admonition>}}
## Macros
@ -174,9 +174,9 @@ Table panel results:
Set the **Format** option to **Time series** to create and run time series queries.
{{% admonition type="note" %}}
{{<admonitiontype="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 %}}
{{</admonition>}}
The examples in this section refer to the data in the following table:
@ -194,9 +194,9 @@ The examples in this section refer to the data in the following table:
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" %}}
{{<admonitiontype="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.
While using OpenTSDB 2.2 data source, make sure you use either Filters or Tags as they are mutually exclusive. If used together, might give you weird results.
{{% /admonition %}}
{{</admonition>}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When using OpenTSDB 2.4 with alerting, queries are executed with the parameter `arrays=true`. This causes OpenTSDB to return data points as an array of arrays instead of a map of key-value pairs. Grafana then converts this data into the appropriate data frame format.
@ -297,9 +297,9 @@ Add the following setting in the **[auth]** section of the .ini configuration fi
azure_auth_enabled = true
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you are using Azure authentication, don't enable `Forward OAuth identity`. Both methods use the same HTTP authorization headers, and the OAuth token will override your Azure credentials.
@ -123,15 +123,15 @@ Click **+ Operations** to select from a list of operations including Aggregation
a set of time series where each series includes multiple data points over a period of time. You can choose to visualize the data as lines, bars, points, stacked lines, or stacked bars.
- **Instant** - Returns a single data point per series — the most recent value within the selected time range. The results can be displayed in a table or as raw data. To visualize instant query results in a time series panel, start by adding field override, then add a property to the override called `Transform`, and set the Transform value to `Constant` in the drop-down. For more information, refer to the [Time Series Transform option documentation](ref:time-series-transform).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana adjusts the query time range to align with the dynamically calculated step interval. This alignment ensures consistent metric visualization and supports Prometheus's result caching requirements. However, this alignment can cause minor visual differences, such as a slight gap at the graph's right edge or a shifted start time. For example, a `15s` step aligns timestamps to Unix times divisible by 15 seconds. A `1w``minstep` aligns the range to the start of the week, which for Prometheus is Thursday at 00:00 UTC.
{{% /admonition %}}
{{</admonition>}}
- **Exemplars** - Toggle on to run a query that includes exemplars in the graph. Exemplars are unique to Prometheus. For more information see [Introduction to exemplars](ref:exemplars).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
There is no option to add exemplars with an **Instant** query type.
{{% /admonition %}}
{{</admonition>}}
### Filter metrics
@ -159,9 +159,9 @@ The following options are included under the **Additional Settings** drop-down:
- **Disable text wrap**: Toggle on to disable text wrapping.
- **Enable regex search**: Toggle on to filter metric names by regex search, which uses an additional call on the Prometheus API.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The Metrics explorer (Builder mode) and [Metrics browser (Code mode)](#metrics-browser-in-code-mode) are separate elements. The Metrics explorer does not have the ability to browse labels yet, but the Metrics browser can display all labels on a metric name.
{{% /admonition %}}
{{</admonition>}}
### Operations
@ -220,9 +220,9 @@ You can then select one or more labels shown in **Step 2**.
Select one or more values in **Step 3** for each label to tighten your query scope.
In **Step 4**, you can select **Use query** to run the query, **Use as rate query** to add the rate operation to your query (`$__rate_interval`), **Validate selector** to verify the selector is valid and show the number of series found, or **Clear** to clear your selections and start over.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you don't remember the exact metric name, you can start by selecting a few labels to filter the list. This helps you find relevant label values and narrow down your options.
{{% /admonition %}}
{{</admonition>}}
All lists in the Metrics browser include a search field to quickly filter metrics or labels by keyword.
In the **Values** section, there's a single search field that filters across all selected labels, making it easier to find matching values. For example, if you have labels like `app`, `job`, and `job_name`, only one of them might contain the value you're looking for.
@ -20,9 +20,9 @@ The use of AngularJS in Grafana has been [deprecated](../) in favor of React. Su
This page explains how Grafana users might be impacted by the removal of Angular support based on plugins dependent on this legacy framework. You will also see if there is a migration option available for a given plugin.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
We are greatly appreciative of the developers who have contributed plugins to the Grafana ecosystem. Guidance on migrating a plugin to React can be found in our [migration guide](/developers/plugin-tools/migration-guides/migrate-angularjs-to-react).
{{% /admonition %}}
{{</admonition>}}
## What should I do with the list of AngularJS plugins?
@ -34,9 +34,9 @@ Refer to the [table below](#angularjs-based-plugins) and take the appropriate ac
- Customers of Grafana Enterprise and users of Grafana Cloud can also leverage [usage insights](../../../dashboards/assess-dashboard-usage/) to prioritize any migration efforts.
- Review the plugin source repositories to add your support to any migration issues or consider forking the repo.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you want to add any specific migration guidance for your plugin here or update our assessment, please open a PR by clicking **Suggest an edit** at the bottom of this page.
If you're running Grafana Enterprise, you'll need to have specific permissions for some endpoints. Refer to [Role-based access control permissions](ref:role-based-access-control-permissions) for more information.
This API currently doesn't handle pagination. The default maximum number of data sources returned is 5000. You can change this value in the default.ini file.
{{% /admonition %}}
{{</admonition>}}
**Required permissions**
@ -84,9 +84,9 @@ Content-Type: application/json
`GET /api/datasources/:datasourceId`
{{% admonition type="warning" %}}
{{<admonitiontype="warning">}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [API for getting a single data source by UID](#get-a-single-data-source-by-uid) or to the [API for getting a single data source by its name](#get-a-single-data-source-by-name).
{{% /admonition %}}
{{</admonition>}}
**Required permissions**
@ -351,9 +351,9 @@ Content-Type: application/json
}
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
By defining `password` and `basicAuthPassword` under `secureJsonData` Grafana encrypts them securely as an encrypted blob in the database. The response then lists the encrypted fields under `secureJsonFields`.
{{% /admonition %}}
{{</admonition>}}
**Example Graphite Request with basic auth enabled**:
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source update API](#update-an-existing-data-source).
{{% /admonition %}}
{{</admonition>}}
**Required permissions**
@ -519,9 +519,9 @@ Content-Type: application/json
}
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Similar to [creating a data source](#create-a-data-source), `password` and `basicAuthPassword` should be defined under `secureJsonData` in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under `secureJsonFields` section in the response.
Similar to [creating a data source](#create-a-data-source), `password` and `basicAuthPassword` should be defined under `secureJsonData` in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under `secureJsonFields` section in the response.
{{% /admonition %}}
{{</admonition>}}
## Delete an existing data source by id
`DELETE /api/datasources/:datasourceId`
{{% admonition type="warning" %}}
{{<admonitiontype="warning">}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [API for deleting an existing data source by UID](#delete-an-existing-data-source-by-uid) or to the [API for deleting an existing data source by its name](#delete-an-existing-data-source-by-name)
{{% /admonition %}}
{{</admonition>}}
**Required permissions**
@ -715,9 +715,9 @@ Content-Type: application/json
## Data source proxy calls by id
{{% admonition type="warning" %}}
{{<admonitiontype="warning">}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source API for proxying requests](#data-source-proxy-calls).
{{% /admonition %}}
{{</admonition>}}
`GET /api/datasources/proxy/:datasourceId/*`
@ -791,9 +791,9 @@ Content-Type: application/json
## Fetch data source resources by id
{{% admonition type="warning" %}}
{{<admonitiontype="warning">}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source resources API](#fetch-data-source-resources).
{{% /admonition %}}
{{</admonition>}}
`GET /api/datasources/:datasourceId/resources/*`
@ -893,9 +893,9 @@ Queries a data source having a backend implementation.
`POST /api/ds/query`
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana's built-in data sources usually have a backend implementation.
@ -23,9 +23,9 @@ title: Query and Resource Caching HTTP API
# Query and resource caching API
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
- **key** - Optional. Define the unique key. Required if **external** is `true`.
- **deleteKey** - Optional. Unique key used to delete the snapshot. It is different from the **key** so that only the creator can delete the snapshot. Required if **external** is `true`.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When creating a snapshot using the API, you have to provide the full dashboard payload including the snapshot data. This endpoint is designed for the Grafana UI.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available since Grafana 11. SAML support is in public preview behind the `ssoSettingsSAML` feature flag.
{{% /admonition %}}
{{</admonition>}}
The API can be used to create, update, delete, get, and list SSO Settings for OAuth2 and SAML.
@ -167,11 +167,11 @@ Grafana verifies whether the given settings are allowed and valid.
If they are, then Grafana stores the settings in the database and reloads
Grafana services with no need to restart the instance.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you run Grafana in high availability mode, configuration changes
may not get applied to all Grafana instances immediately. You may need
to wait a few minutes for the configuration to propagate to all Grafana instances.
The Explore editor is available in 10.1 and later versions. In the editor, transformations is available in Grafana 10.3 and later versions.
{{% /admonition %}}
{{</admonition>}}
Correlations allow users to build a link between any two data sources. For more information about correlations in general, please see the [correlations](/docs/grafana/<GRAFANA_VERSION>/administration/correlations/) topic in the administration page.
@ -131,10 +131,10 @@ Select **Mixed** from the data source dropdown to run queries across multiple da
When using Explore, the URL in the browser address bar updates as you make changes to the queries. You can share or bookmark this URL.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Explore may generate long URLs, which some tools, like messaging or videoconferencing applications, might truncate due to fixed message lengths. In such cases, Explore displays a warning and loads a default state.
If you encounter issues when sharing Explore links in these applications, you can generate shortened links. See [Share shortened link](#share-shortened-link) for more information.
Grafana Explore provides a variety of tools to help manage your queries.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
For help with debugging queries, Explore allows you to investigate query requests and responses, as well as query statistics, via the Query inspector. Refer to [Query inspector in Explore](/docs/grafana/<GRAFANA_VERSION>/explore/explore-inspector/) for more information.
{{% /admonition %}}
{{</admonition>}}
## Query history
Query history contains the list of queries that you created in Explore. This history is stored in the Grafana database and isn't shared with other users. The retention period for a query history is **two weeks**. Queries older than two weeks are automatically deleted.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Starred queries aren't subject to the two-week retention period and aren't deleted.
{{% /admonition %}}
{{</admonition>}}
To view your query history:
@ -65,9 +65,9 @@ Filter query history in both the **Query history** and **Starred** tabs by data
1. Click the **Filter queries for specific data source(s)** field.
1. Select the data source in the dropdown by which you want to filter your history. You can select multiple data sources.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Queries with the **Mixed** data source appear only when filtering for "Mixed" and not when filtering by individual data source.
{{% /admonition %}}
{{</admonition>}}
You can also filter queries by date using the vertical slider:
@ -87,8 +87,8 @@ You can customize your query history in the **Settings** tab.
Toggle **Change the default active tab from "Query history" to "Starred"** to make the **Starred tab** the default active tab.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Query history settings are global, and applied to both panels in split mode.
{{% /admonition %}}
{{</admonition>}}
<!-- All queries that have been starred in the Query history tab are displayed in the Starred tab. This allows you to access your favorite queries faster and to reuse these queries without typing them from scratch. -->
@ -100,14 +100,14 @@ If the query is updated to select and group by more than just one string column,
In this case the labels that represent the dimensions will have two keys based on the two string typed columns `Location` and `Sensor`. This data results four series: `Temp {Location=LGA,Sensor=A}`, `Temp {Location=LGA,Sensor=B}`, `Temp {Location=BOS,Sensor=A}`, and `Temp {Location=BOS,Sensor=B}`.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
More than one dimension is currently only supported in the Logs queries within the Azure Monitor service as of version 7.1.
{{% /admonition %}}
{{</admonition>}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Multiple dimensions are not supported in a way that maps to multiple alerts in Grafana, but rather they are treated as multiple conditions to a single alert.
For more information, see the documentation on [creating alerts with multiple series](ref:create-grafana-managed-rule).
Prometheus is an open source monitoring system for which Grafana provides out-of-the-box support. This topic walks you through the steps to create a series of dashboards in Grafana to display system metrics for a server monitored by Prometheus.
{{% admonition type="tip" %}}
{{<admonitiontype="tip">}}
Check out our Prometheus **Learning Journeys**.
- [Connect to a Prometheus data source in Grafana Cloud](https://www.grafana.com/docs/learning-journeys/prometheus/) to visualize your metrics directly from where they are stored.
- [Send metrics to Grafana Cloud using Prometheus remote write](https://www.grafana.com/docs/learning-journeys/prom-remote-write/) to explore Grafana Cloud without making significant changes to your existing configuration.
@ -201,9 +201,9 @@ Variables in data links and actions let you send people to a detailed dashboard
To see a list of available variables, enter `$` in the data link or action **URL** field.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
These variables changed in 6.4 so if you have an older version of Grafana, then use the version picker to select docs for an older version of Grafana.
{{% /admonition %}}
{{</admonition>}}
Azure Monitor, [CloudWatch](ref:cloudwatch), and [Google Cloud Monitoring](ref:google-cloud-monitoring) have pre-configured data links called _deep links_.
@ -152,9 +152,9 @@ This section explains all available standard options.
To set these options, expand the **Standard options** section in the panel editor pane. Most field options won't affect the visualization until you click outside of the field option box you're editing or press Enter.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Not all of the options listed apply to all visualizations with standard options.
@ -117,9 +117,9 @@ To get started adding panels, ensure that you have configured a data source:
- For details about using data sources, refer to [Data sources](ref:data-sources).
- For more information about managing data sources as an administrator, refer to [Data source management](ref:data-source-management).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
[Data source management](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/) is only available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](https://grafana.com/docs/grafana-cloud/).
@ -189,9 +189,9 @@ Panel data source query options include:
If a data point is saved every 15 seconds, you don't benefit from having an interval lower than that.
You can also set this to a higher minimum than the scrape interval to retrieve queries that are more coarse-grained and well-functioning.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The **Min interval** corresponds to the min step in Prometheus. Changing the Prometheus interval can change the start and end of the query range because Prometheus aligns the range to the interval. Refer to [Min step](https://grafana.com/docs/grafana/latest/datasources/prometheus/query-editor/#min-step) for more details.
{{% /admonition %}}
{{</admonition>}}
- **Interval:** Sets a time span that you can use when aggregating or grouping data points by time.
@ -48,15 +48,15 @@ Server-side expressions allow you to manipulate data returned from queries with
Expressions are most commonly used for [Grafana Alerting](ref:grafana-alerting). The processing is done server-side, so expressions can operate without a browser session. However, expressions can also be used with backend data sources and visualization.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Expressions do not work with legacy dashboard alerts.
{{% /admonition %}}
{{</admonition>}}
Expressions are meant to augment data sources by enabling queries from different data sources to be combined or by providing operations unavailable in a data source.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When possible, you should do data processing inside the data source. Copying data from storage to the Grafana server for processing is inefficient, so expressions are targeted at lightweight data processing.
{{% /admonition %}}
{{</admonition>}}
Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data](ref:multiple-dimensional-data). For example, a query that returns multiple series, where each series is identified by labels or tags.
@ -142,9 +142,9 @@ abs returns the absolute value of its argument which can be a number or a series
is_inf takes a number or a series and returns `1` for `Inf` values (negative or positive) and `0` for other values. For example `is_inf($A)`.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you need to specifically check for negative infinity for example, you can do a comparison like `$A == infn()`.
@ -157,7 +157,7 @@ Grafana offers a variety of visualizations to support different use cases. This
{{<youtubeid="JwF6FgeotaU">}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you are unsure which visualization to pick, Grafana can provide visualization suggestions based on the panel query. When you select a visualization, Grafana will show a preview with that visualization applied.
@ -116,9 +116,9 @@ The candlestick visualization attempts to map fields from your data to the appro
- **Close** - Final (end) value of the given period.
- **Volume** - Sample count in the given period (for example, number of trades).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The candlestick visualization legend doesn't display these values.
{{% /admonition %}}
{{</admonition>}}
If your data can't be mapped to these dimensions for some reason (for example, because the column names aren't the same), you can map them manually using the **Open**, **High**, **Low**, and **Close** fields under the **Candlestick** options in the panel editor:
@ -63,9 +63,9 @@ Elements are the basic building blocks of a canvas and they help you visualize d
Add elements in the [Layer](#layer-options) section of canvas options.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Element snapping and alignment only works when the canvas is not zoomed in.
{{% /admonition %}}
{{</admonition>}}
### Element types
@ -136,9 +136,9 @@ The server element lets you easily represent a single server, a stack of servers
The button element lets you add a basic button to the canvas. Button elements support triggering basic, unauthenticated API calls. [API settings](#button-api-options) are found in the button element editor. You can also pass template variables in the API editor.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
A button click will only trigger an API call when [inline editing](#inline-editing) is disabled.
{{% /admonition %}}
{{</admonition>}}
{{<video-embedsrc="/media/docs/grafana/2023-20-10-Canvas-Button-Element-Enablement-Video.mp4"max-width="650px"alt="Canvas button element demo">}}
@ -271,9 +271,9 @@ Use the following pointer and keyboard strokes:
You can enable infinite panning in a canvas when pan and zoom is enabled. This allows you to pan and zoom the canvas and uncover larger designs.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Infinite panning is an experimental feature that may not work as expected in all scenarios. For example, elements that are not top-left constrained may experience unexpected movement when panning.
@ -221,9 +221,9 @@ There are seven map layer types to choose from in a geomap.
- [ArcGIS MapServer](#arcgis-mapserver-layer) adds a layer from an ESRI ArcGIS MapServer.
- [XYZ Tile layer](#xyz-tile-layer) adds a map from a generic tile layer.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Beta is equivalent to the [public preview](/docs/release-life-cycle/) release stage.
{{% /admonition %}}
{{</admonition>}}
There are also two experimental (or alpha) layer types.
@ -358,9 +358,9 @@ The Night / Day layer displays night and day regions based on the current time r
#### Route layer (Beta)
{{% admonition type="caution" %}}
{{<admonitiontype="caution">}}
The Route layer is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{% /admonition %}}
{{</admonition>}}
The Route layer renders data points as a route.
@ -387,9 +387,9 @@ The layer can also render a route with arrows.
#### Photos layer (Beta)
{{% admonition type="caution" %}}
{{<admonitiontype="caution">}}
The Photos layer is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{% /admonition %}}
{{</admonition>}}
The Photos layer renders a photo at each data point.
@ -414,9 +414,9 @@ The Photos layer renders a photo at each data point.
#### Network layer (Beta)
{{% admonition type="caution" %}}
{{<admonitiontype="caution">}}
The Network layer is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
{{% /admonition %}}
{{</admonition>}}
The Network layer renders a network graph. This layer supports the same [data format supported by the node graph visualization](ref:data-format) with the addition of [geospatial data](#location-mode) included in the nodes data. The geospatial data is used to locate and render the nodes on the map.
@ -24,9 +24,9 @@ The news visualization displays an RSS feed. By default, it displays articles fr
{{<figuresrc="/static/img/docs/news/news-visualization.png"max-width="1025px"alt="A news visualization showing the latest Grafana news feed">}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
In version 8.5, we discontinued the "Use Proxy" option for Grafana news visualizations. As a result, RSS feeds that are not configured for request by Grafana's frontend (with the appropriate [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)) may not load.
{{% /admonition %}}
{{</admonition>}}
You can use the news visualization to provide regular news and updates to your users.
@ -92,9 +92,9 @@ Both nodes and edges can have associated metadata or statistics. The data source
#### Nodes
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Node graphs can show only 1,500 nodes. If this limit is crossed a warning will be visible in upper right corner, and some nodes will be hidden. You can expand hidden parts of the graph by clicking on the "Hidden nodes" markers in the graph.
{{% /admonition %}}
{{</admonition>}}
Usually, nodes show two statistical values inside the node and two identifiers just below the node, usually name and type. Nodes can also show another set of values as a color circle around the node, with sections of different color represents different values that should add up to 1.
@ -36,9 +36,9 @@ For example, if you're monitoring the health status of different services, you c
{{<figuresrc="/media/docs/grafana/panels-visualizations/screenshot-status-history-v11.6.png"max-width="800px"alt="A status history panel showing the health status of different sensors">}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
A status history is similar to a [state timeline](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/state-timeline/), but has different [configuration options](#status-history-options). Unlike state timelines, status histories don't merge consecutive values.
{{% /admonition %}}
{{</admonition>}}
Use a status history when you need to:
Some files were not shown because too many files have changed in this diff
Show More
Jack Baldry
1 week ago
committed by