public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[v9.4.x] [feat] docs; update admonition syntax (#68855)

Browse Source 
[feat] docs; update admonition syntax (#68842)

* [feat] docs; update admonition syntax

- Standardizes according to style conventions: https://grafana.com/docs/writers-toolkit/style-guide/style-conventions/#admonitions
- Prepares docs for better, uniform admonition style.

* Remove false positives and irregularities

* false positive removal

* Update docs/sources/datasources/mysql/_index.md

* Update docs/sources/developers/angular_deprecation/angular-plugins.md

* fix link errors

* Prettify some nested blockquotes

* remoe unnecessary admonition

(cherry picked from commit 1c4bb9ca00)

Co-authored-by: Matt Dodson <47385188+MattDodsonEnglish@users.noreply.github.com>
This commit is contained in:
Grot (@grafanabot)
2023-05-23 07:46:19 -05:00
committed by GitHub
co-authored by Matt Dodson
parent ad2a920191
commit 048de5d09a
144 changed files with 3887 additions and 1238 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/administration/api-keys/index.md
+300 -27
View File
@@ -17,7 +17,9 @@ An API key is a randomly generated string that external systems use to interact
When you create an API key, you specify a **Role** that determines the permissions associated with the API key. Role permissions control that actions the API key can perform on Grafana resources.
> **Note:** If you use Grafana v8.5 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service accounts]({{< relref "../service-accounts/" >}}).
{{% admonition type="note" %}}
If you use Grafana v9.1 or newer, use service accounts instead of API keys. For more information, refer to [Grafana service accounts]({{< relref "../service-accounts/" >}}).
{{% /admonition %}}
{{< section >}}
@@ -27,14 +29,23 @@ Create an API key when you want to manage your computed workload with a user.
This topic shows you how to create an API key using the Grafana UI. You can also create an API key using the Grafana HTTP API. For more information about creating API keys via the API, refer to [Create API key via API]({{< relref "../../developers/http_api/create-api-tokens-for-org/#how-to-create-a-new-organization-and-an-api-token" >}}).
### Before you begin:
### Before you begin
- Ensure you have permission to create and edit API keys. For more information about permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions/#" >}}).
To follow these instructions, you need at least one of the following:
**To create an API key:**
- Administrator permissions
- Editor permissions
- Service account writer
1. Sign in to Grafana, hover your cursor over **Configuration** (the gear icon), and click **API Keys**.
1. Click **New API key**.
- To ensure you have permission to create and edit API keys, follow the instructions in [Roles and permissions]({{< relref "../roles-and-permissions/#" >}}).
### Steps
To create an API, complete the following steps:
1. Sign in to Grafana.
1. Click **Administration** in the left-side menu and select **API Keys**.
1. Click **Add API key**.
1. Enter a unique name for the key.
1. In the **Role** field, select one of the following access levels you want to assign to the key.
- **Admin**: Enables a user to use APIs at the broadest, most powerful administrative level.
@@ -44,39 +55,301 @@ This topic shows you how to create an API key using the Grafana UI. You can also
- If you are unsure about how long an API key should be valid, we recommend that you choose a short duration, such as a few hours. This approach limits the risk of having API keys that are valid for a long time.
1. Click **Add**.
## Migrate API Keys to Grafana service accounts
## Migrate API keys to Grafana service accounts
You can migrate one or all API keys to [Grafana service accounts]({{< relref "../service-accounts/" >}}). When you migrate an API key to a service account, a service account will be created with a service account token.
The API key will continue to work, and you can find it in the [Grafana service account tokens]({{< relref "../service-accounts/#service-account-tokens" >}}) details.
For more information about benefits of service accounts, refer to [Grafana service account benefits]({{< relref "../service-accounts/#service-account-benefits" >}}).
As an alternative to using API keys for authentication, you can use a service account-based authentication system. When compared to API keys, service accounts have limited scopes that provide more security than using API keys.
You can choose to migrate a single API key or all API keys. Note that when you migrate all API keys, you can't create new API keys anymore and will have to use service accounts instead.
For more information about the benefits of service accounts, refer to [Grafana service account benefits]({{< relref "../service-accounts/#service-account-benefits" >}}).
### Before you begin
The service account endpoints generate a machine user for authentication instead of using API keys. When you migrate an API key to a service account, a service account will be created with a service account token.
- Ensure you have permission to create Grafana service accounts. For more information about permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions/#" >}}).
{{% admonition type="note" %}}
If you're currently using API keys for authentication, we strongly recommend to use Grafana Service Accounts instead. Rest assured, when migrating to Service Accounts, your existing API keys will continue working as before. To find the migrated API keys, navigate to the Service Accounts section and select the Service Account Tokens tab. For more information, please refer to the [Grafana service account tokens]({{< relref "../service-accounts/#service-account-tokens" >}}) details.
{{% /admonition %}}
**To migrate all API keys to service accounts:**
## Ways of migrating API keys to service accounts
1. Sign in to Grafana, hover your cursor over **Configuration** (the gear icon), and click **API Keys**.
2. In the top of the page, find the section which says **Switch from API keys to service accounts**
3. Click **Migrate to service accounts now**.
4. A confirmation window will appear, asking to confirm the migration. Click **Yes, migrate now** if you are willing to continue.
5. Once migration is successful, you can choose to forever hide the API keys page. Click **Hide API keys page forever** if you want to do that.
If you are currently using API keys in your environment, you need to reconfigure your setup to use service accounts.
**To migrate single API key to a service account:**
Depending on your current setup, you may need to use one or all of the following methods to migrate your environment to service accounts:
1. Sign in to Grafana, hover your cursor over **Configuration** (the gear icon), and click **API Keys**.
- The Grafana user interface: Use this method if you have been using the UI to manage your API keys and want to switch to using service accounts.
- The Grafana API: Use this method if you have been using API calls to manage your API keys and want to switch to using service accounts programmatically.
- Terraform: If you have a Terraform configuration that sets up API keys, you need to reconfigure your Terraform to use service accounts instead.
By following these steps, you can successfully migrate your integration from API keys to service accounts and continue using Grafana seamlessly.
### Migrate API keys to Grafana service accounts using the Grafana user interface
This section shows you how to migrate API keys to Grafana service accounts using the Grafana user interface. You can choose to migrate a single API key or all API keys. When you migrate all API keys, you can no longer create API keys and must use service accounts instead.
#### Before you begin
To follow these instructions, you need at least one of the following:
- Administrator permissions
- Editor permissions
- Service account writer
For more information about permissions, refer to [Roles and permissions]({{< relref "../roles-and-permissions/#" >}}).
#### Steps
To migrate all API keys to service accounts, complete the following steps:
1. Sign in to Grafana, point to **Configuration** (the gear icon), and click **API Keys**.
1. In the top of the page, find the section which says **Switch from API keys to service accounts**
1. Click **Migrate to service accounts now**.
1. A confirmation window will appear, asking to confirm the migration. Click **Yes, migrate now** if you are willing to continue.
1. Once migration is successful, you can choose to forever hide the API keys page. Click **Hide API keys page forever** if you want to do that.
To migrate a single API key to a service account, complete the following steps:
1. Sign in to Grafana.
1. Click **Administration** in the left-side menu and select **API Keys**.
1. Find the API Key you want to migrate.
1. Click **Migrate to service account**.
### Revert service account token to API key
### Migrate API keys to Grafana service accounts for API calls
**Note:** This is undesired operation and should be used only in emergency situations.
This section shows you how to migrate API keys to Grafana service accounts for Grafana API workflows. For references see: [Grafana Service Accounts for the Grafana API]({{< relref "../../developers/http_api/serviceaccount/#create-service-account" >}}).
It is possible to convert back service account token to API key. You can use the [Revert service account token to API key HTTP API]({{< relref "../../developers/http_api/create-api-tokens-for-org/#how-to-create-a-new-organization-and-an-api-token" >}}) for that.
#### Before you begin
**The revert will perform the following actions:**
To follow these instructions, you need one of the following:
1. Convert the given service account token back to API key
1. Delete the service account associated with the given key. **Make sure there are no other tokens associated with the service account, otherwise they all will be deleted.**
- Administrator permissions
- Editor permissions
- Service account writer
#### Steps
Complete the following steps to migrate from API keys to service accounts for API:
1. Call the `POST /api/serviceaccounts` endpoint and the `POST /api/serviceaccounts/<id>/tokens`.
This action generates a service account token.
1. Store the ID and secret that the system returns to you.
1. Pass the token in the `Authrorization` header, prefixed with `Bearer`.
This action authenticates API requests.
1. SATs used for authentication
1. Remove code that handles the old `/api/auth/keys` endpoint.
1. Track the [API keys](http://localhost:3000/org/apikeys) in use and migrate them to SATs.
#### Example
Your current setup
```sh
curl -X POST -H "Content-Type: application/json" -d '{"name": "my-api-key", "role": "Viewer"}' http://admin:admin@localhost:3000/api/auth/keys
# response from the api
{"id":2,"name":"my-api-key","key":"eyJrIjoiTFRSN1RBOVc3SGhjblc0bWZodXZ3MnNDcU92Um5VZUIiLKJuIjoibXktYXBpLWtleSIsImlkIjoxfQ=="}%
```
New setup
```sh
# create a service account
curl -X POST -H "Content-Type: application/json" -d '{"name": "my-service-account", "role": "Viewer"}' http://admin:admin@localhost:3000/api/serviceaccounts
# response with the created service account id,name, login
{"id":1,"name":"my-service-account","login":"sa-my-service-account","orgId":1,"isDisabled":false,"role":"Viewer","tokens":0,"avatarUrl":""}%
# create the service account token with the service account id 1 - /serviceaccounts/{id} returned from the previous step
curl -X POST -H "Content-Type: application/json" -d '{"name": "my-service-account-token"}' http://admin:admin@localhost:3000/api/serviceaccounts/1/tokens
# response with the created SAT id,name and key.
{"id":2,"name":"my-service-account-token","key":"glsa_9244xlVFZK0j8Lh4fU8Cz6Z5tO664zIi_7a762939"}%
# now you can authenticate the same way as you did with the API key
curl --request GET --url http://localhost:3000/api/folders --header 'Authorization: Bearer glsa_9244xlVFZK0j8Lh4fU8Cz6Z5tO664zIi_7a762939'
# response
[{"id":1,"uid":"a5261a84-eebc-4733-83a9-61f4713561d1","title":"gdev dashboards"}]%
```
### Migrate API keys to Grafana service accounts in Terraform
This section shows you how to migrate your Terraform configuration for API keys to Grafana service accounts. For resources, see [Grafana Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/service_account_token).
For migration your cloud stack api keys, use the `grafana_cloud_stack_service_account` and `gafana_cloud_stack_service_account_token` resources see [Grafana Cloud Stack Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_stack_service_account).
#### Steps
Complete the following steps to migrate from API keys to service accounts using Terraform:
1. Generate `grafana_service_account` and `grafana_service_account_token` resources.
1. Specify the desired scopes and expiration date when creating the service account.
1. Use the token returned from `grafana_service_account_token` to authenticate the API requests.
1. Remove the terraform configuration for creating your `grafana_api_key` resources.
**Example: your current Terraform configuration**
```tf
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
}
}
}
# configure the provider with basic auth
provider "grafana" {
url = "http://localhost:3000"
auth = "admin:admin"
}
resource "grafana_api_key" "foo" {
name = "key_foo"
role = "Viewer"
}
resource "grafana_api_key" "bar" {
name = "key_bar"
role = "Admin"
seconds_to_live = 30
}
```
**Your new Terraform configuration**
_Note:_ you can create multiple tokens using one service account.
```tf
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
}
}
}
# configure the provider with basic auth
provider "grafana" {
url = "http://localhost:3000"
auth = "admin:admin"
}
# Creating a service account in Grafana instance to be used as auth and attach tokens
# notice we can attach multiple tokens to one service account
resource "grafana_service_account" "sa-admin" {
name = "sa-admin"
role = "Admin"
}
# Creating a service account token in Grafana instance to be used for creating resources in Grafana instance
resource "grafana_service_account_token" "sat-bar" {
name = "sat-bar"
service_account_id = grafana_service_account.sa-admin.id
}
# Creating a service account token in Grafana instance to be used for creating resources in Grafana instance
resource "grafana_service_account_token" "sat-foo" {
name = "sat-foo"
service_account_id = grafana_service_account.sa-admin.id
seconds_to_live = 30
}
```
### Migrate Cloud **Stack** API keys to Grafana cloud stack service accounts in Terraform
This section shows you how to migrate your Terraform configuration for Grafana cloud stack API keys to Grafana cloud stack service accounts. For migration your cloud stack api keys, use the `grafana_cloud_stack_service_account` and `gafana_cloud_stack_service_account_token` resources see [Grafana Cloud Stack Service Accounts in Terraform](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_stack_service_account).
{{% admonition type="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.
{{% /admonition %}}
#### Steps
Complete the following steps to migrate from cloud stack API keys to cloud stack service accounts using Terraform:
1. Generate `grafana_cloud_stack_service_account` and `grafana_cloud_stack_service_account_token` resources.
1. Specify the desired scopes and expiration date when creating the service account.
1. Use the token returned from `grafana_cloud_stack_service_account_token` to authenticate the API requests.
1. Remove the Terraform configuration for creating your `grafana_cloud_stack_api_key` resources.
**Example: Your current Terraform configuration**
```tf
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
}
}
}
# Declaring the first provider to be only used for creating the cloud-stack
provider "grafana" {
alias = "cloud"
cloud_api_key = "<API-Key>"
}
resource "grafana_cloud_stack" "my_stack" {
provider = grafana.cloud
name = "my_stack"
slug = "my_stack"
region_slug = "eu" # Example “us”,”eu” etc
}
# Creating a Grafana API key to be used as auth
resource "grafana_cloud_stack_api_key" "management" {
provider = grafana.cloud
stack_slug = grafana_cloud_stack.my_stack.slug
name = "management-key"
role = "Admin"
}
```
**Your new Terraform configuration**
```tf
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
}
}
}
# Declaring the first provider to be only used for creating the cloud-stack
provider "grafana" {
alias = "cloud"
cloud_api_key = "<API-Key>"
}
resource "grafana_cloud_stack" "my_stack" {
provider = grafana.cloud
name = "my_stack"
slug = "my_stack"
region_slug = "eu" # Example “us”,”eu” etc
}
# Creating a grafana cloud stack service account
resource "grafana_cloud_stack_service_account" "mystack_cloud-stack_service_account" {
provider = grafana.cloud
stack_slug = grafana_cloud_stack.my_stack.slug
name = "mystack-cloud-stack-sa"
role = "Admin"
}
# Creating a grafana cloud stack service account token
resource "grafana_cloud_stack_service_account_token" "mystack_cloud-stack_service-account_token" {
provider = grafana.cloud
stack_slug = grafana_cloud_stack.my_stack.slug
name = "mystack-cloud-stack-sa-token"
service_account_id = grafana_cloud_stack_service_account.mystack_cloud-stack_service_account.id
}
```
docs/sources/administration/data-source-management/index.md
+59 -66
View File
@@ -21,84 +21,63 @@ Only users with the organization admin role can add data sources.
Before you can create your first dashboard, you need to add your data source.
> **Note:** Only users with the organization admin role can add data sources.
{{% admonition type="note" %}}
Only users with the organization admin role can add data sources.
{{% /admonition %}}
**To add a data source:**
1. Select the cog icon on the side menu to show the configuration options.
1. Select **Data sources**.
This opens the data sources page, which displays a list of previously configured data sources for the Grafana instance.
1. Select **Add data source** to see a list of all supported data sources.
{{< figure src="/static/img/docs/v75/add-data-source-7-5.png" max-width="600px" class="docs-image--no-shadow">}}
1. Enter the name of a specific data source in the search dialog.
You can also scroll through supported data sources grouped into time series, logging, tracing, and other categories.
1. Move the cursor over the data source you want to add.
1. Click **Select**.
This opens the data source configuration page.
1. Click **Connections** in the left-side menu.
1. Enter the name of a specific data source in the search dialog. You can filter by **Data source** to only see data sources.
1. Click the data source you want to add.
1. Configure the data source following instructions specific to that data source.
For links to data source-specific documentation, see [Data sources]({{< relref "../../datasources" >}}).
## Data source permissions
You can configure data source permissions to allow or deny certain users the ability to query a data source.
Each data source's configuration includes a permissions page where you can enable permissions and restrict query permissions to specific **Users** and **Teams**.
You can configure data source permissions to allow or deny certain users the ability to query or edit a data source. Each data source’s configuration includes a Permissions tab where you can restrict data source permissions to specific users, teams, or roles.
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud).
{{% /admonition %}}
### Enable data source permissions
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 they have access to.
When permissions are enabled for a data source in an organization, the user who created the datasource can edit the datasource and in addition, viewers can query the datasource.
**Enable permissions for a data source:**
1. Navigate to **Configuration > Data Sources**.
1. Select the data source you want to enable permissions for.
1. On the Permissions tab, click **Enable**.
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.
<div class="clearfix"></div>
> **Caution:** Enabling permissions for the default data source makes users not listed in the permissions unable to invoke queries. Panels using default data source will return `Access denied to data source` error for those users.
### Assign data source permissions to users, teams, or roles
### Allow users and teams to query a data source
You can assign data source permissions to users, teams, and roles which will allow access to query or edit the data source.
After you have enabled permissions for a data source you can assign query permissions to users and teams which will allow access to query the data source.
**Assign query permission to users and teams:**
1. Navigate to **Configuration > Data Sources**.
1. Select the data source you want to assign query permissions to.
1. On the **Permissions** tab, click **Add Permission**.
1. Select **Team**, **User**, or **Role**.
1. Select the entity you want to modify permissions for.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Select the data source to which you want to assign permissions.
1. On the Permissions tab, click **Add a permission**.
1. Select **User**, **Team**, or **Role**.
1. Select the entity for which you want to modify permissions.
1. Select the **Query** or **Edit** permission.
1. Click **Save**.
<div class="clearfix"></div>
### Disable data source permissions
### Edit data source permissions for users, teams, or roles
If you have enabled permissions for a data source and want to return data source permissions to the default, then you can disable permissions with a click of a button.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Select the data source for which you want to edit permissions.
1. On the Permissions tab, find the user, team, or role permission you want to update.
1. Select a different option in the **Permission** dropdown.
Note that _all_ existing permissions created for the data source will be deleted.
<div class="clearfix"></div>
**Disable permissions for a data source:**
### Remove data source permissions for users, teams, or roles
1. Navigate to **Configuration > Data Sources**.
1. Select the data source you want to disable permissions for.
1. On the Permissions tab, click **Disable Permissions**.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Select the data source from which you want to remove permissions.
1. On the Permissions tab, find the user, team, or role permission you want to remove.
1. Click the **X** next to the permission.
<div class="clearfix"></div>
@@ -108,11 +87,15 @@ When query caching is enabled, Grafana temporarily stores the results of data so
Query caching works for all backend data sources. You can enable the cache globally and configure the cache duration (also called Time to Live, or TTL).
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
The following cache backends are available: in-memory, Redis, and Memcached.
> **Note:** Storing cached queries in-memory can increase Grafana's memory footprint. In production environments, a Redis or Memcached backend is highly recommended.
{{% admonition type="note" %}}
Storing cached queries in-memory can increase Grafana's memory footprint. In production environments, a Redis or Memcached backend is highly recommended.
{{% /admonition %}}
When a panel queries a cached data source, the time until this query fetches fresh data is determined by the panel's **interval.** This means that wider panels and dashboards with shorter time ranges fetch new data more frequently than narrower panels and dashboards with longer time ranges.
@@ -150,13 +133,20 @@ You must be an Org admin or Grafana admin to enable query caching for a data sou
By default, data source queries are not cached. To enable query caching for a single data source:
1. On the side menu, click Configuration > Data Sources.
1. Click **Connections** in the left-side menu.
1. Under Your Connections, click **Data sources**.
1. In the data source list, click the data source that you want to turn on caching for.
1. Open the Cache tab.
1. Press the Enable button.
1. Go to the Cache tab.
1. Click **Enable**.
1. (Optional) Choose custom TTLs for the data source's queries and resources caching. If you skip this step, then Grafana uses the default TTL.
> **Note:** If query caching is enabled and the Cache tab is not visible in a data source's settings, then query caching is not available for that data source.
You can optionally override a data source's configured TTL for individual dashboard panels. This can be be useful when you have queries whose results change more or less often than the configured TTL. In the Edit Panel view, select the caching-enabled data source, expand the Query options, and enter your the TTL in milliseconds.
{{< figure max-width="500px" src="/media/docs/grafana/per-panel-cache-ttl-9-4.png" caption="Set Cache TTL for a single panel" >}}
{{% admonition type="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 %}}
To configure global settings for query caching, refer to the [Query caching section of Enterprise Configuration]({{< relref "../../setup-grafana/configure-grafana/enterprise-configuration/#caching" >}}).
@@ -164,9 +154,10 @@ To configure global settings for query caching, refer to the [Query caching sect
To disable query caching for a single data source:
1. On the side menu, click Configuration > Data Sources.
1. Click **Connections** in the left-side menu.
1. Under Your Connections, click **Data sources**.
1. In the data source list, click the data source that you want to turn off caching for.
1. In the Cache tab, click Disable.
1. On the Cache tab, click **Disable**.
To disable query caching for an entire Grafana instance, set the `enabled` flag to `false` in the [Query caching section of Enterprise Configuration]({{< relref "../../setup-grafana/configure-grafana/enterprise-configuration/#caching" >}}). You will no longer see the Cache tab on any data sources, and no data source queries will be cached.
@@ -174,12 +165,14 @@ 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.
> **Note:** This action impacts all cache-enabled data sources. If you are using Memcached, the system clears all data from the Memcached instance.
{{% admonition type="note" %}}
This action impacts all cache-enabled data sources. If you are using Memcached, the system clears all data from the Memcached instance.
{{% /admonition %}}
1. Sign in to Grafana and click **Settings > Data Sources**.
1. Select a data source.
1. Click the **Cache** tab.
1. Click **Clear cache**.
1. Click **Connections** in the left-side menu.
1. Under Your Connections, click **Data sources**.
1. In the data source list, click the data source that you want to clear the cache for.
1. In the Cache tab, click **Clear cache**.
### Sending a request without cache
docs/sources/administration/organization-management/index.md
+3 -1
View File
@@ -90,7 +90,9 @@ For more information about adding users to an organization, refer to [Add a user
This action permanently removes an organization from your Grafana server.
> **Warning:** Deleting the organization also deletes all teams and dashboards associated the organization.
{{% admonition type="warning" %}}
Deleting the organization also deletes all teams and dashboards associated the organization.
{{% /admonition %}}
### Before you begin
docs/sources/administration/organization-preferences/index.md
+3 -1
View File
@@ -204,7 +204,9 @@ Users with the Grafana Server Admin flag on their account or access to the confi
default_home_dashboard_path = data/main-dashboard.json
```
> **Note:** On Linux, Grafana uses `/usr/share/grafana/public/dashboards/home.json` as the default home dashboard location.
{{% admonition type="note" %}}
On Linux, Grafana uses `/usr/share/grafana/public/dashboards/home.json` as the default home dashboard location.
{{% /admonition %}}
### Set the home dashboard for your organization
docs/sources/administration/plugin-management/index.md
+6 -2
View File
@@ -49,7 +49,9 @@ With [RBAC]({{< relref "../roles-and-permissions/access-control/#about-rbac" >}}
By default, Viewers, Editors and Admins have access to all App Plugins that their organization role allows them to access, thanks to the `fixed:plugins.app:reader` role.
> **Note:** Revoking this RBAC role from some users, will prevent them from accessing app plugins. But granting this RBAC role to users will only allow them to see app plugins their organization role allows them to see.
{{% admonition type="note" %}}
Revoking this RBAC role from some users, will prevent them from accessing app plugins. But granting this RBAC role to users will only allow them to see app plugins their organization role allows them to see.
{{% /admonition %}}
To prevent users from seeing an app plugin, refer to [this permissions scenarios]({{< relref "../roles-and-permissions/access-control/plan-rbac-rollout-strategy#prevent-viewers-from-accessing-an-app-plugin" >}}).
@@ -195,7 +197,9 @@ If you've allowed loading of an unsigned plugin, then Grafana writes a warning m
WARN[06-01|16:45:59] Running an unsigned plugin pluginID=<plugin id>
```
> **Note:** If you're developing a plugin, then you can enable development mode to allow all unsigned plugins.
{{% admonition type="note" %}}
If you're developing a plugin, then you can enable development mode to allow all unsigned plugins.
{{% /admonition %}}
## Learn more
docs/sources/administration/provisioning/index.md
+40 -18
View File
@@ -27,10 +27,12 @@ See [Configuration]({{< relref "../../setup-grafana/configure-grafana/" >}}) for
- Custom configuration from `$WORKING_DIR/conf/custom.ini`
- The custom configuration file path can be overridden using the `--config` parameter
> **Note:** If you have installed Grafana using the `deb` or `rpm`
> packages, then your configuration file is located at
> `/etc/grafana/grafana.ini`. This path is specified in the Grafana
> init.d script using `--config` file parameter.
{{% admonition type="note" %}}
If you have installed Grafana using the `deb` or `rpm`
packages, then your configuration file is located at
`/etc/grafana/grafana.ini`. This path is specified in the Grafana
init.d script using `--config` file parameter.
{{% /admonition %}}
### Using Environment Variables
@@ -67,7 +69,9 @@ Currently we do not provide any scripts/manifests for configuring Grafana. Rathe
## Data sources
> **Note:** Available in Grafana v5.0 and higher.
{{% admonition type="note" %}}
Available in Grafana v5.0 and higher.
{{% /admonition %}}
You can manage data sources in Grafana by adding YAML configuration files in the [`provisioning/datasources`]({{< relref "../../setup-grafana/configure-grafana#provisioning" >}}) directory.
Each config file can contain a list of `datasources` to add or update during startup.
@@ -167,7 +171,9 @@ To provision the rest of a data source's settings, include them as a JSON blob i
Common settings in the [built-in core data sources]({{< relref "../../datasources#built-in-core-data-sources" >}}) include:
> **Note:** Data sources tagged with _HTTP\*_ communicate using the HTTP protocol, which includes all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% admonition type="note" %}}
Data sources tagged with _HTTP\*_ communicate using the HTTP protocol, which includes all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% /admonition %}}
| Name | Type | Data source | Description |
| -------------------------- | ------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -227,7 +233,9 @@ For examples of specific data sources' JSON data, refer to that [data source's d
Secure JSON data is a map of settings that will be encrypted with [secret key]({{< relref "../../setup-grafana/configure-grafana#secret_key" >}}) from the Grafana config. The purpose of this is only to hide content from the users of the application. This should be used for storing TLS Cert and password that Grafana will append to the request on the server side. All of these settings are optional.
> **Note:** The _HTTP\*_ tag denotes data sources that communicate using the HTTP protocol, including all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% admonition type="note" %}}
The _HTTP\*_ tag denotes data sources that communicate using the HTTP protocol, including all core data source plugins except MySQL, PostgreSQL, and MSSQL.
{{% /admonition %}}
| Name | Type | Data source | Description |
| ----------------- | ------ | ---------------------------------- | -------------------------------------------------------- |
@@ -262,12 +270,16 @@ datasources:
## Plugins
> **Note:** Available in Grafana v7.1 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.1 and higher.
{{% /admonition %}}
You can manage plugin applications in Grafana by adding one or more YAML config files in the [`provisioning/plugins`]({{< relref "../../setup-grafana/configure-grafana#provisioning" >}}) directory. Each config file can contain a list of `apps` that will be updated during start up. Grafana updates each app to match the configuration file.
> **Note:** This feature enables you to provision plugin configurations, not the plugins themselves.
> The plugins must already be installed on the Grafana instance.
{{% admonition type="note" %}}
This feature enables you to provision plugin configurations, not the plugins themselves.
The plugins must already be installed on the Grafana instance.
{{% /admonition %}}
### Example plugin configuration file
@@ -354,10 +366,12 @@ If the dashboard in the JSON file contains an [UID]({{< relref "../../dashboards
When Grafana starts, it updates/inserts all dashboards available in the configured folders. If you modify the file, then the dashboard is also updated.
By default, Grafana deletes dashboards in the database if the file is removed. You can disable this behavior using the `disableDeletion` setting.
> **Note:** Provisioning allows you to overwrite existing dashboards
> which leads to problems if you re-use settings that are supposed to be unique.
> Be careful not to re-use the same `title` multiple times within a folder
> or `uid` within the same installation as this will cause weird behaviors.
{{% admonition type="note" %}}
Provisioning allows you to overwrite existing dashboards
which leads to problems if you re-use settings that are supposed to be unique.
Be careful not to re-use the same `title` multiple times within a folder
or `uid` within the same installation as this will cause weird behaviors.
{{% /admonition %}}
### Provision folders structure from filesystem to Grafana
@@ -391,9 +405,13 @@ providers:
`server` and `application` will become new folders in Grafana menu.
> **Note:** `folder` and `folderUid` options should be empty or missing to make `foldersFromFilesStructure` work.
{{% admonition type="note" %}}
`folder` and `folderUid` options should be empty or missing to make `foldersFromFilesStructure` work.
{{% /admonition %}}
> **Note:** To provision dashboards to the General folder, store them in the root of your `path`.
{{% admonition type="note" %}}
To provision dashboards to the General folder, store them in the root of your `path`.
{{% /admonition %}}
## Alerting
@@ -401,7 +419,9 @@ For information on provisioning Grafana Alerting, refer to [Provision Grafana Al
## Alert Notification Channels
> **Note:** Alert Notification Channels are part of legacy alerting, which is deprecated and will be removed in Grafana 10. Use the Provision contact points section in [Create and manage alerting resources using file provisioning]({{< relref "../../alerting/set-up/provision-alerting-resources/file-provisioning" >}}).
{{% admonition type="note" %}}
Alert Notification Channels are part of legacy alerting, which is deprecated and will be removed in Grafana 10. Use the Provision contact points section in [Create and manage alerting resources using file provisioning]({{< relref "../../alerting/set-up/provision-alerting-resources/file-provisioning" >}}).
{{% /admonition %}}
Alert Notification Channels can be provisioned by adding one or more YAML config files in the [`provisioning/notifiers`](/administration/configuration/#provisioning) directory.
@@ -473,7 +493,9 @@ delete_notifiers:
The following sections detail the supported settings and secure settings for each alert notification type. Secure settings are stored encrypted in the database and you add them to `secure_settings` in the YAML file instead of `settings`.
> **Note:** Secure settings is supported since Grafana v7.2.
{{% admonition type="note" %}}
Secure settings is supported since Grafana v7.2.
{{% /admonition %}}
#### Alert notification `pushover`
docs/sources/administration/recorded-queries/index.md
+6 -2
View File
@@ -21,11 +21,15 @@ Recorded queries allow you to see trends over time by taking a snapshot of a dat
For our plugins that do not return time series, it might be useful to plot historical data. For example, you might want to query ServiceNow to see a history of request response times but it can only return current point-in-time metrics.
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}).
{{% /admonition %}}
## How recorded queries work
> **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 type="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 %}}
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 three types of queries:
docs/sources/administration/roles-and-permissions/_index.md
+12 -4
View File
@@ -20,13 +20,17 @@ 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
> **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 type="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 %}}
## Grafana server administrators
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.
> **Note:** The server administrator role does not mean that the user is also a Grafana [organization administrator]({{< relref "#organization-roles" >}}).
{{% admonition type="note" %}}
The server administrator role does not mean that the user is also a Grafana [organization administrator]({{< relref "#organization-roles" >}}).
{{% /admonition %}}
A server administrator can perform the following tasks:
@@ -36,7 +40,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.
> **Note:** The server administrator role does not exist in Grafana Cloud.
{{% admonition type="note" %}}
The server administrator role does not exist in Grafana Cloud.
{{% /admonition %}}
To assign or remove server administrator privileges, see [Server user management]({{< relref "../user-management/server-user-management/assign-remove-server-admin-privileges/" >}}).
@@ -112,7 +118,9 @@ For more information about assigning dashboard permissions, refer to [Grant dash
If you have access to the Grafana server, you can modify the default editor role so that editors can use administrator permissions to manage dashboard folders, dashboards, and teams that they create.
> **Note**: This permission does not allow editors to manage folders, dashboards, and teams that they do not create.
{{% admonition type="note" %}}
This permission does not allow editors to manage folders, dashboards, and teams that they do not create.
{{% /admonition %}}
This setting can be used to enable self-organizing teams to administer their own dashboards.
docs/sources/administration/roles-and-permissions/access-control/_index.md
+6 -2
View File
@@ -18,7 +18,9 @@ weight: 120
# Role-based access control (RBAC)
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /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.
@@ -62,7 +64,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.
> **Note:** You can't have a Grafana user without a basic role assigned.
{{% admonition type="note" %}}
You can't have a Grafana user without a basic role assigned.
{{% /admonition %}}
#### Basic role modification
docs/sources/administration/roles-and-permissions/access-control/assign-rbac-roles/index.md
+3 -1
View File
@@ -11,7 +11,9 @@ weight: 40
# Assign RBAC roles
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
In this topic you'll learn how to use the role picker, provisioning, and the HTTP API to assign fixed and custom roles to users and teams.
docs/sources/administration/roles-and-permissions/access-control/configure-rbac/index.md
+3 -1
View File
@@ -9,7 +9,9 @@ weight: 30
# Configure RBAC in Grafana
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
The table below describes all RBAC configuration options. Like any other Grafana configuration, you can apply these options as [environment variables]({{< relref "../../../../setup-grafana/configure-grafana/#configure-with-environment-variables" >}}).
docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md
+3 -1
View File
@@ -10,7 +10,9 @@ weight: 80
# RBAC permissions, actions, and scopes
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
A permission is comprised of an action and a scope. When creating a custom role, consider the actions the user can perform and the resource(s) on which they can perform those actions.
docs/sources/administration/roles-and-permissions/access-control/manage-rbac-roles/index.md
+10 -4
View File
@@ -12,7 +12,9 @@ weight: 50
# Manage RBAC roles
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles.
@@ -192,7 +194,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]({{< relref "../../../../developers/http_api/access_control/#create-a-new-custom-role" >}}).
> **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 type="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 %}}
The following example creates a `custom:users:admin` role and assigns the `users:create` action to it.
@@ -301,8 +305,10 @@ roles:
scope: 'folder:*'
```
> **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.
> <br/> **Note**: Make sure to **increment** the role version for the changes to be accounted for.
{{% admonition type="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 %}}
You can also change basic roles' permissions using the API. Refer to the [RBAC HTTP API]({{< relref "../../../../developers/http_api/access_control/#update-a-role" >}}) for more details.
docs/sources/administration/roles-and-permissions/access-control/plan-rbac-rollout-strategy/index.md
+9 -3
View File
@@ -11,7 +11,9 @@ weight: 20
# Plan your RBAC rollout strategy
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
An RBAC rollout strategy helps you determine _how_ you want to implement RBAC prior to assigning RBAC roles to users and teams.
@@ -60,7 +62,9 @@ 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.
> **Note:** Changes that you make to basic roles impact the role definition for all [organizations]({{< relref "../../../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 type="note" %}}
Changes that you make to basic roles impact the role definition for all [organizations]({{< relref "../../../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 %}}
- **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.
@@ -77,7 +81,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.
> **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 type="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 %}}
### Provide internal viewer employees with the ability to use Explore, but prevent external viewer contractors from using Explore
docs/sources/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/index.md
+10 -4
View File
@@ -11,7 +11,9 @@ weight: 70
# RBAC role definitions
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
The following tables list permissions associated with basic and fixed roles.
@@ -106,10 +108,14 @@ For more information about the permissions required to access alert rules, refer
### Grafana OnCall roles (beta)
> **Note:** Available from Grafana 9.4 in early access.
{{% admonition type="note" %}}
Available from Grafana 9.4 in early access.
{{% /admonition %}}
> **Note:** This feature is behind the `accessControlOnCall` feature toggle.
> You can enable feature toggles through configuration file or environment variables. See configuration [docs]({{< relref "../../../../setup-grafana/configure-grafana/#feature_toggles" >}}) for details.
{{% admonition type="note" %}}
This feature is behind the `accessControlOnCall` feature toggle.
You can enable feature toggles through configuration file or environment variables. See configuration [docs]({{< relref "../../../../setup-grafana/configure-grafana/#feature_toggles" >}}) for details.
{{% /admonition %}}
If you are using [Grafana OnCall](https://grafana.com/docs/oncall/latest/get-started/), you can try out the integration between Grafana OnCall and RBAC.
This will allow you to control access to different OnCall features using the following RBAC roles:
docs/sources/administration/roles-and-permissions/access-control/rbac-grafana-provisioning/index.md
+3 -1
View File
@@ -11,7 +11,9 @@ weight: 60
# Provisioning RBAC with Grafana
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
You can create, change or remove [Custom roles]({{< relref "./manage-rbac-roles/#create-custom-roles-using-provisioning" >}}) and create or remove [basic role assignments]({{< relref "./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.
docs/sources/administration/roles-and-permissions/access-control/rbac-terraform-provisioning/index.md
+3 -1
View File
@@ -10,7 +10,9 @@ weight: 60
# Provisioning RBAC with Terraform
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /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).
docs/sources/administration/roles-and-permissions/access-control/troubleshooting/index.md
+94
View File
@@ -0,0 +1,94 @@
---
aliases:
- ../../../enterprise/access-control/troubleshooting/
labels:
products:
- cloud
- enterprise
- oss
description: RBAC troubleshooting guide.
menuTitle: Troubleshooting RBAC
title: Troubleshooting RBAC
weight: 80
---
# Troubleshooting RBAC
In this section, you’ll learn about logs that are available for RBAC and you’ll find the most common RBAC issues.
## Enable debug logging
You can enable debug log messages for RBAC in the Grafana configuration file. Debug logs are added to the Grafana server logs.
```bash
[log]
filters = accesscontrol:debug accesscontrol.evaluator:debug dashboard.permissions:debug
```
## Enable audit logging
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.3 and later, and [Grafana Cloud Advanced](/docs/grafana-cloud).
{{% /admonition %}}
You can enable auditing in the Grafana configuration file.
```bash
[auditing]
enabled = true
```
All permission and role updates, and role assignments are added to audit logs.
Learn more about [access control audit logs]({{< relref "../../../../setup-grafana/configure-security/audit-grafana/#access-control" >}}).
## Missing dashboard, folder or data source permissions
[Dashboard and folder permissions]({{< relref "../../#dashboard-permissions" >}}) and [data source permissions]({{< relref "../../#data-source-permissions" >}}) can go out of sync if a Grafana instance version is upgraded, downgraded and then upgraded again.
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" %}}
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.
{{% /admonition %}}
To resynchronize the permissions:
1. make a backup of your database
1. run the following SQL queries
```sql
DELETE
FROM builtin_role
where role_id IN (SELECT id
FROM role
WHERE name LIKE 'managed:%');
DELETE
FROM team_role
where role_id IN (SELECT id
FROM role
WHERE name LIKE 'managed:%');
DELETE
FROM user_role
where role_id IN (SELECT id
FROM role
WHERE name LIKE 'managed:%');
DELETE
FROM permission
where role_id IN (SELECT id
FROM role
WHERE name LIKE 'managed:%');
DELETE
FROM role
WHERE name LIKE 'managed:%';
DELETE
FROM migration_log
WHERE migration_id IN ('teams permissions migration',
'dashboard permissions',
'dashboard permissions uid scopes',
'data source permissions',
'data source uid permissions',
'managed permissions migration',
'managed folder permissions alert actions repeated migration',
'managed permissions migration enterprise');
```
1. restart your Grafana instance
docs/sources/administration/service-accounts/index.md
+10 -4
View File
@@ -17,7 +17,9 @@ weight: 800
You can use a service account to run automated workloads in Grafana, such as dashboard provisioning, configuration, or report generation. Create service accounts and tokens to authenticate applications, such as Terraform, with the Grafana API.
> **Note:** Service accounts will eventually replace [API keys]({{< relref "../api-keys/" >}}) as the primary way to authenticate applications that interact with Grafana.
{{% admonition type="note" %}}
Service accounts will eventually replace [API keys]({{< relref "../api-keys/" >}}) as the primary way to authenticate applications that interact with Grafana.
{{% /admonition %}}
A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
@@ -28,7 +30,9 @@ A common use case for creating a service account is to perform operations on aut
In [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}), you can also use service accounts in combination with [role-based access control]({{< relref "../roles-and-permissions/access-control/" >}}) to grant very specific permissions to applications that interact with Grafana.
> **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.
{{% admonition type="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.
{{% /admonition %}}
{{< vimeo 742056367 >}}
<br>
@@ -174,8 +178,10 @@ To list your token's permissions, use the `/api/access-control/user/permissions`
#### Example
> **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 type="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 %}}
```bash
curl -H "Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7FDsNSLAa_54e2f8be" -X GET '<grafana_url>/api/access-control/user/permissions' | jq
docs/sources/administration/user-management/manage-dashboard-permissions/index.md
+6 -2
View File
@@ -40,7 +40,9 @@ When you grant dashboard folder permissions, that setting applies to all dashboa
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.
> **Note**: If you have assigned a user dashboard folder permissions, you cannot also assign the user permission to dashboards contained in the folder.
{{% admonition type="note" %}}
If you have assigned a user dashboard folder permissions, you cannot also assign the user permission to dashboards contained in the folder.
{{% /admonition %}}
Grant dashboard permissions when you want to restrict or enhance dashboard access for users who do not have permissions defined in the associated dashboard folder.
@@ -66,7 +68,9 @@ By default, the viewer organization role does not allow viewers to create dashbo
This modification is useful for public Grafana installations where you want anonymous users to be able to edit panels and queries but not save or create new dashboards.
> **Note**: If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `viewers_can_edit` flag.
{{% admonition type="note" %}}
If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `viewers_can_edit` flag.
{{% /admonition %}}
### Before you begin
docs/sources/administration/user-management/manage-org-users/index.md
+21 -9
View File
@@ -30,14 +30,20 @@ You can see a list of users with accounts in your Grafana organization. If neces
**To view a list of organization users**:
1. Sign in to Grafana as an organization administrator.
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Users**.
1. Navigate to **Administration > Users**.
> **Note:** If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [view a global list of users]({{< relref "../server-user-management#view-a-list-of-users" >}}) in the Server Admin section of Grafana.
{{% admonition type="note" %}}
If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [view a global list of users]({{< relref "../server-user-management#view-a-list-of-users" >}}) in the Server Admin section of Grafana.
{{% /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]({{< relref "../../roles-and-permissions/#organization-roles" >}}).
{{% admonition type="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]({{< relref "../../../setup-grafana/configure-grafana/#authgrafana_com-skip_org_role_sync" >}}) for more information.
{{% /admonition %}}
### Before you begin
- Ensure you have organization administrator privileges
@@ -45,7 +51,7 @@ Update user permissions when you want to enhance or restrict a user's access to
**To change the organization role of a user**:
1. Sign in to Grafana as an organization administrator.
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Users**.
1. Navigate to **Administration > Users**.
1. Find the user account for which you want to change the role.
If necessary, use the search field to filter the list.
@@ -54,7 +60,9 @@ Update user permissions when you want to enhance or restrict a user's access to
1. Select the role that you want to assign.
1. Click **Update**.
> **Note:** If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [change a user's organization permissions]({{< relref "../server-user-management/change-user-org-permissions/" >}}) in the Server Admin section.
{{% admonition type="note" %}}
If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also [change a user's organization permissions]({{< relref "../server-user-management/change-user-org-permissions/" >}}) in the Server Admin section.
{{% /admonition %}}
## Invite a user to join an organization
@@ -63,7 +71,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.
> **Note:** If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also manually [add a user to an organization]({{< relref "../server-user-management/add-remove-user-to-org/" >}}).
{{% admonition type="note" %}}
If you have [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can also manually [add a user to an organization]({{< relref "../server-user-management/add-remove-user-to-org/" >}}).
{{% /admonition %}}
### Before you begin
@@ -78,7 +88,7 @@ When you invite users to join an organization, you assign the **Admin**, **Edito
> **Note**: It might be that you are currently in the proper organization and don't need to switch organizations.
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Users**.
1. Navigate to **Administration > Users**.
1. Click **Invite**.
1. Enter the following information:
@@ -97,7 +107,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.
> **Note:** The **Pending Invites** button is only visible if there are unanswered invitations.
{{% admonition type="note" %}}
The **Pending Invites** button is only visible if there are unanswered invitations.
{{% /admonition %}}
### Before you begin
@@ -106,7 +118,7 @@ Periodically review invitations you have sent so that you can see a list of user
**To manage a pending invitation**:
1. Sign in to Grafana as an organization administrator.
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Users**.
1. Navigate to **Administration > Users**.
1. Click **Pending Invites**.
The **Pending Invites** button appears only when there are unaccepted invitations.
@@ -128,7 +140,7 @@ This action does not remove the user account from the Grafana server.
**To remove a user from an organization**:
1. Sign in to Grafana as an organization administrator.
1. Hover your cursor over the **Configuration** (gear) icon in the side menu and click **Users**.
1. Navigate to **Administration > Users**.
1. Find the user account that you want to remove from the organization.
Use the search field to filter the list, if necessary.
docs/sources/administration/user-management/server-user-management/_index.md
+6 -2
View File
@@ -37,7 +37,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. Hover your cursor over the **Server Admin** (shield) icon until a menu appears, and click **Users**.
> **Note:** If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still [view of list of users in a given organization]({{< relref "../manage-org-users/#view-a-list-of-organization-users" >}}).
{{% admonition type="note" %}}
If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still [view of list of users in a given organization]({{< relref "../manage-org-users/#view-a-list-of-organization-users" >}}).
{{% /admonition %}}
## View user details
@@ -115,7 +117,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]({{< relref "add-remove-user-to-org/" >}}).
> **Note:** If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still add users by [inviting a user to join an organization]({{< relref "../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% admonition type="note" %}}
If you have [organization administrator]({{< relref "../../roles-and-permissions/#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../roles-and-permissions/#grafana-server-administrators" >}}) permissions, you can still add users by [inviting a user to join an organization]({{< relref "../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% /admonition %}}
## Force a user to log out of Grafana
docs/sources/administration/user-management/server-user-management/add-remove-user-to-org/index.md
+3 -1
View File
@@ -38,7 +38,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.
> **Note:** If you have [organization administrator]({{< relref "../../../roles-and-permissions#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../../roles-and-permissions#grafana-server-administrators" >}}) permissions, you can still [invite a user to join an organization]({{< relref "../../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% admonition type="note" %}}
If you have [organization administrator]({{< relref "../../../roles-and-permissions#organization-roles" >}}) permissions and _not_ [server administrator]({{< relref "../../../roles-and-permissions#grafana-server-administrators" >}}) permissions, you can still [invite a user to join an organization]({{< relref "../../manage-org-users#invite-a-user-to-join-an-organization" >}}).
{{% /admonition %}}
## Remove a user from an organization
docs/sources/administration/user-management/server-user-management/assign-remove-server-admin-privileges/index.md
+3 -1
View File
@@ -11,7 +11,9 @@ weight: 20
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]({{< relref "../../../roles-and-permissions#grafana-server-administrators" >}}).
> **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.
{{% admonition type="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.
{{% /admonition %}}
## Before you begin
docs/sources/administration/user-management/server-user-management/grant-editor-admin-permissions/index.md
+3 -1
View File
@@ -16,7 +16,9 @@ When `editors_can_admin` is enabled:
- Users with the Editor role in an organization are Administrators for new dashboards and folders they create, meaning they can edit dashboard permissions. To learn more about dashboard permissions, refer to [Manage dashboard permissions]({{< relref "../../manage-dashboard-permissions/" >}}).
- Users with the Editor role in an organization can create teams, and they are Administrators of the teams they create. To learn more about team permissions, refer to [Team management]({{< relref "../../../team-management/" >}}).
> **Note**: If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `editors_can_admin` flag.
{{% admonition type="note" %}}
If you use Grafana Enterprise and customize users' permissions using RBAC, the RBAC permissions override the functionality enabled by the `editors_can_admin` flag.
{{% /admonition %}}
## Before you begin
docs/sources/administration/user-management/user-preferences/index.md
+3 -1
View File
@@ -22,7 +22,9 @@ You can also view important information about your account, such as the organiza
You can change your Grafana password at any time.
> **Note**: If your Grafana instance uses an <!--[external authentication provider]({{< relref "../../../setup-grafana/configure-security/configure-authentication/" >}})--> external authentication provider, then you might not be able to change your password in Grafana. Contact your Grafana administrator for more information.
{{% admonition type="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.
{{% /admonition %}}
**To change your password**:
docs/sources/alerting/alerting-rules/create-mimir-loki-managed-recording-rule.md
+3 -1
View File
@@ -28,7 +28,9 @@ You can create and manage recording rules for an external Grafana Mimir or Loki
- **Grafana Mimir** - use the `/prometheus` prefix. The Prometheus data source supports both Grafana Mimir and Prometheus, and Grafana expects that both the [Query API](https://grafana.com/docs/mimir/latest/operators-guide/reference-http-api/#querier--query-frontend) and [Ruler API](https://grafana.com/docs/mimir/latest/operators-guide/reference-http-api/#ruler) are under the same URL. You cannot provide a separate URL for the Ruler API.
> **Note:** If you do not want to manage alerting rules for a particular Loki or Prometheus data source, go to its settings and clear the **Manage alerts via Alerting UI** checkbox.
{{% admonition type="note" %}}
If you do not want to manage alerting rules for a particular Loki or Prometheus data source, go to its settings and clear the **Manage alerts via Alerting UI** checkbox.
{{% /admonition %}}
## Add a Grafana Mimir or Loki managed recording rule
docs/sources/alerting/alerting-rules/create-mimir-loki-managed-rule.md
+10 -5
View File
@@ -30,12 +30,17 @@ Grafana allows you to create alerting rules for an external Grafana Mimir or Lok
Watch this video to learn more about how to create a Mimir managed alert rule: {{< vimeo 720001865 >}}
> **Note:** If you do not want to manage alerting rules for a particular Loki or Prometheus data source, go to its settings and clear the **Manage alerts via Alerting UI** checkbox.
_Refer to [Add a Grafana Mimir or Loki managed alerting rule]({{< relref "#add-a-grafana-mimir-or-loki-managed-alerting-rule" >}}) (following) for current instructions._
{{% admonition type="note" %}}
If you do not want to manage alerting rules for a particular Loki or Prometheus data source, go to its settings and clear the **Manage alerts via Alerting UI** checkbox.
{{% /admonition %}}
## Add a Grafana Mimir or Loki managed alerting rule
1. In the Grafana menu, click the **Alerting** (bell) icon to open the Alerting page listing existing alerts.
1. Click **Create alert rule**. The new alerting rule page opens where the Grafana managed alerts option is selected by default.
1. In the left-side menu, click **Alerts & IRM** and then **Alerting**.
1. Click **Alert rules**.
1. Click **+ Create alert rule**. The new alerting rule page opens where the **Grafana managed alerts** option is selected by default.
1. In Step 1, add the rule name.
- In **Rule name**, add a descriptive name. This name is displayed in the alert rule list. It is also the `alertname` label for every alert instance that is created from this rule.
1. In Step 2, select **Mimir or Loki alert** option.
@@ -45,8 +50,8 @@ Watch this video to learn more about how to create a Mimir managed alert rule: {
- In the **For** text box, specify the duration for which the condition must be true before an alert fires. If you specify `5m`, the condition must be true for 5 minutes before the alert fires.
> **Note:** Once a condition is met, the alert goes into the `Pending` state. If the condition remains active for the duration specified, the alert transitions to the `Firing` state, else it reverts to the `Normal` state.
1. In Step 4, add the namespace, rule group, as well as additional metadata associated with the rule.
- From the **Namespace** drop-down, select an existing rule namespace. Otherwise, click **Add new** and enter a name to create a new one. Namespaces can contain one or more rule groups and only have an organizational purpose. For more information, see [Grafana Mimir or Loki rule groups and namespaces]({{< relref "edit-mimir-loki-namespace-group/" >}}).
- From the **Group** drop-down, select an existing group within the selected namespace. Otherwise, click **Add new** and enter a name to create a new one. Newly created rules are appended to the end of the group. Rules within a group are run sequentially at a regular interval, with the same evaluation time.
- From the **Namespace** dropdown, select an existing rule namespace. Otherwise, click **Add new** and enter a name to create a new one. Namespaces can contain one or more rule groups and only have an organizational purpose. For more information, see [Grafana Mimir or Loki rule groups and namespaces]({{< relref "edit-mimir-loki-namespace-group/" >}}).
- From the **Group** dropdown, select an existing group within the selected namespace. Otherwise, click **Add new** and enter a name to create a new one. Newly created rules are appended to the end of the group. Rules within a group are run sequentially at a regular interval, with the same evaluation time.
- Add a description and summary to customize alert messages. Use the guidelines in [Annotations and labels for alerting]({{< relref "../fundamentals/annotation-label/" >}}).
- Add Runbook URL, panel, dashboard, and alert IDs.
1. In Step 5, add custom labels.
docs/sources/alerting/alerting-rules/view-state-health.md
+3 -1
View File
@@ -35,7 +35,9 @@ An alert rule can be in either of the following states:
| **Pending** | At least one time series returned by the evaluation engine is `Pending`. |
| **Firing** | At least one time series returned by the evaluation engine is `Firing`. |
> **Note:** Alerts will transition first to `pending` and then `firing`, thus it will take at least two evaluation cycles before an alert is fired.
{{% admonition type="note" %}}
Alerts will transition first to `pending` and then `firing`, thus it will take at least two evaluation cycles before an alert is fired.
{{% /admonition %}}
## Alert instance state
docs/sources/alerting/fundamentals/annotation-label/how-to-use-labels.md
+4 -2
View File
@@ -37,8 +37,10 @@ Example: A label key/value pair `Alert! 🔔="🔥"` will become `Alert_0x1f514=
# Grafana reserved labels
> **Note:** Labels prefixed with `grafana_` are reserved by Grafana for special use. If a manually configured label is added beginning with `grafana_` it may be overwritten in case of collision.
> To stop the Grafana Alerting engine from adding a reserved label, you can disable it via the `disabled_labels` option in [unified_alerting.reserved_labels]({{< relref "/docs/grafana/latest/setup-grafana/configure-grafana#unified_alertingreserved_labels" >}}) configuration.
{{% admonition type="note" %}}
Labels prefixed with `grafana_` are reserved by Grafana for special use. If a manually configured label is added beginning with `grafana_` it may be overwritten in case of collision.
To stop the Grafana Alerting engine from adding a reserved label, you can disable it via the `disabled_labels` option in [unified_alerting.reserved_labels]({{< relref "/docs/grafana/latest/setup-grafana/configure-grafana#unified_alertingreserved_labels" >}}) configuration.
{{% /admonition %}}
Grafana reserved labels can be used in the same way as manually configured labels. The current list of available reserved labels are:
docs/sources/alerting/fundamentals/state-and-health.md
+3 -1
View File
@@ -27,7 +27,9 @@ An alert rule can be in either of the following states:
| **Pending** | At least one time series returned by the evaluation engine is `Pending`. |
| **Firing** | At least one time series returned by the evaluation engine is `Firing`. |
> **Note:** Alerts will transition first to `pending` and then `firing`, thus it will take at least two evaluation cycles before an alert is fired.
{{% admonition type="note" %}}
Alerts will transition first to `pending` and then `firing`, thus it will take at least two evaluation cycles before an alert is fired.
{{% /admonition %}}
## Alert instance state
docs/sources/alerting/manage-notifications/create-contact-point.md
+3 -1
View File
@@ -49,7 +49,9 @@ Complete the following steps to delete a contact point.
1. Find the contact point to delete, then click **Delete** (trash icon).
1. In the confirmation dialog, click **Yes, delete**.
> **Note:** You cannot delete contact points that are in use by a notification policy. You will have to either delete the notification policy or update it to use another contact point.
{{% admonition type="note" %}}
You cannot delete contact points that are in use by a notification policy. You will have to either delete the notification policy or update it to use another contact point.
{{% /admonition %}}
## Test a contact point
docs/sources/alerting/manage-notifications/create-notification-policy.md
+28 -25
View File
@@ -16,14 +16,12 @@ weight: 300
# Manage notification policies
Notification policies determine how alerts are routed to contact points. Policies have a tree structure, where each policy can have one or more child policies. Each policy, except for the root policy, can also match specific alert labels. Each alert is evaluated by the root policy and subsequently by each child policy. If the `Continue matching subsequent sibling nodes` option is enabled for a specific policy, then evaluation continues even after one or more matches. A parent policy’s configuration settings and contact point information govern the behavior of an alert that does not match any of the child policies. A root policy governs any alert that does not match a specific policy.
Notification policies determine how alerts are routed to contact points. Policies have a tree structure, where each policy can have one or more nested policies. Each policy, except for the default policy, can also match specific alert labels. Each alert is evaluated by the default policy and subsequently by each nested policy. If the **Continue matching subsequent sibling nodes** option is enabled for a nested policy, then evaluation continues even after one or more matches. A parent policy’s configuration settings and contact point information govern the behavior of an alert that does not match any of the nested policies. A default policy governs any alert that does not match a nested policy.
You can configure Grafana managed notification policies as well as notification policies for an external Alertmanager data source.
## Grouping
{{< figure max-width="40%" src="/static/img/docs/alerting/unified/notification-policies-grouping.png" max-width="650px" caption="Notification policies grouping" >}}
Grouping is a new and key concept of Grafana Alerting that categorizes alert notifications of similar nature into a single funnel. This allows you to properly route alert notifications during larger outages when many parts of a system fail at once causing a high number of alerts to fire simultaneously.
For example, suppose you have 100 services connected to a database in different environments. These services are differentiated by the label `env=environmentname`. An alert rule is in place to monitor whether your services can reach the database named `alertname=DatabaseUnreachable`.
@@ -32,16 +30,20 @@ When a network partition occurs, half of your services can no longer reach the d
You can configure grouping to be `group_by: [alertname]` (take note that the `env` label is omitted). With this configuration in place, Grafana sends a single compact notification that has all the affected environments for this alert rule.
> **Note:** Grafana also has a special label named `...` that you can use to group all alerts by all labels (effectively disabling grouping), therefore each alert will go into its own group. It is different from the default of `group_by: null` where **all** alerts go into a single group.
{{% admonition type="note" %}}
Grafana also has a special label named `...` that you can use to group all alerts by all labels (effectively disabling grouping), therefore each alert will go into its own group. It is different from the default of `group_by: null` where **all** alerts go into a single group.
{{% /admonition %}}
## Edit root notification policy
## Edit default notification policy
> **Note:** Before Grafana v8.2, the configuration of the embedded Alertmanager was shared across organisations. Users of Grafana 8.0 and 8.1 are advised to use the new Grafana 8 Alerts only if they have one organisation. Otherwise, silences for the Grafana managed alerts will be visible by all organizations.
{{% admonition type="note" %}}
Before Grafana v8.2, the configuration of the embedded Alertmanager was shared across organizations. Users of Grafana 8.0 and 8.1 are advised to use the new Grafana 8 Alerts only if they have one organization. Otherwise, silences for the Grafana managed alerts will be visible by all organizations.
{{% /admonition %}}
1. In the Grafana menu, click the **Alerting** (bell) icon to open the Alerting page listing existing alerts.
1. In the left-side menu, click **Alerts & IRM** and then **Alerting**.
1. Click **Notification policies**.
1. From the **Alertmanager** dropdown, select an external Alertmanager. By default, the Grafana Alertmanager is selected.
1. In the Root policy section, click **Edit** (pen icon).
1. From the **Choose Alertmanager** dropdown, select an external Alertmanager. By default, the **Grafana Alertmanager** is selected.
1. In the Root policy section, click **Edit**.
1. In **Default contact point**, update the contact point to whom notifications should be sent for rules when alert rules do not match any specific policy.
1. In **Group by**, choose labels to group alerts by. If multiple alerts are matched for this policy, then they are grouped by these labels. A notification is sent per group. If the field is empty (default), then all notifications are sent in a single group. Use a special label `...` to group alerts by all labels (which effectively disables grouping).
1. In **Timing options**, select from the following options:
@@ -50,29 +52,32 @@ You can configure grouping to be `group_by: [alertname]` (take note that the `en
- **Repeat interval** Minimum time interval for re-sending a notification if no new alerts were added to the group. Default is 4 hours.
1. Click **Save** to save your changes.
## Add new specific policy
## Add new nested policy
1. In the Grafana menu, click the **Alerting** (bell) icon to open the Alerting page listing existing alerts.
1. In the left-side menu, click **Alerts & IRM** and then **Alerting**.
1. Click **Notification policies**.
1. From the **Alertmanager** dropdown, select an Alertmanager. By default, the Grafana Alertmanager is selected.
1. To add a top level specific policy, go to the **Specific routing** section and click **New specific policy**.
1. In **Matching labels** section, add one or more rules for matching alert labels.
1. In **Contact point**, add the contact point to send notification to if alert matches only this specific policy and not any of the nested policies.
1. From the **Choose Alertmanager** dropdown, select an Alertmanager. By default, the **Grafana Alertmanager** is selected.
1. To add a top level specific policy, go to the Specific routing section and click **+ New specific policy**.
1. In the Matching labels section, add one or more rules for matching alert labels.
1. In the **Contact point** dropdown, select the contact point to send notification to if alert matches only this specific policy and not any of the nested policies.
1. Optionally, enable **Continue matching subsequent sibling nodes** to continue matching sibling policies even after the alert matched the current policy. When this option is enabled, you can get more than one notification for one alert.
1. Optionally, enable **Override grouping** to specify the same grouping as the root policy. If this option is not enabled, the root policy grouping is used.
1. Optionally, enable **Override grouping** to specify the same grouping as the default policy. If this option is not enabled, the default policy grouping is used.
1. Optionally, enable **Override general timings** to override the timing options configured in the group notification policy.
1. Click **Save policy** to save your changes.
## Add nested policy
1. In the left-side menu, click **Alerts & IRM** and then **Alerting**.
1. Click **Notification policies**.
1. Expand the specific policy you want to update.
1. Click **Add nested policy**, then add the details using information in [Add new specific policy](#add-new-specific-policy).
1. Click **+ Add nested policy**, then add the details using information in [Add new specific policy](#add-new-specific-policy).
1. Click **Save policy** to save your changes.
## Edit specific policy
1. In the Alerting page, click **Notification policies** to open the page listing existing policies.
1. Find the policy you want to edit, then click **Edit** (pen icon).
1. In the left-side menu, click **Alerts & IRM**, and then **Alerting**.
1. Click **Notification policies**.
1. Find the policy you want to edit, then click **Edit**.
1. Make any changes using instructions in [Add new specific policy](#add-new-specific-policy).
1. Click **Save policy**.
@@ -83,7 +88,7 @@ Grafana allows you to search within the tree of policies by the following:
- **Label matchers**
- **Contact Points**
To search by contact point, simply enter a part or full name you are looking for.
To search by contact point simply select a contact point from the **Search by contact point** dropdown. The policies that use that contact point will be highlighted in the user interface.
To search by label matchers simply enter a valid matcher in the **Search by matchers** input field. Multiple matchers can be combined with a comma (`,`).
@@ -97,10 +102,8 @@ An example of a valid matchers search input is:
An example of an alert configuration.
- Create a "default" contact point for slack notifications, and set it on root policy.
- Edit the root policy grouping to group alerts by `cluster`, `namespace` and `severity` so that you get a notification per alert rule and specific kubernetes cluster and namespace.
- Create a "default" contact point for slack notifications, and set it on the default policy.
- Edit the default policy grouping to group alerts by `cluster`, `namespace` and `severity` so that you get a notification per alert rule and specific kubernetes cluster and namespace.
- Create specific route for alerts coming from the development cluster with an appropriate contact point.
- Create a specific route for alerts with "critical" severity with a more invasive contact point integration, like pager duty notification.
- Create specific routes for particular teams that handle their own onduty rotations.
{{< figure max-width="40%" src="/static/img/docs/alerting/unified/notification-policies-8-0.png" max-width="650px" caption="Notification policies" >}}
- Create specific routes for particular teams that handle their own on-call rotations.
docs/sources/alerting/manage-notifications/images-in-notifications.md
+6 -2
View File
@@ -13,7 +13,9 @@ weight: 500
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.
> **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 type="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 %}}
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.
@@ -43,7 +45,9 @@ Refer to the table at the end of this page for a list of contact points and thei
## Configuration
> **Note:** Grafana Cloud users can request this feature by [opening a support ticket in the Cloud Portal](/profile/org#support).
{{% admonition type="note" %}}
Grafana Cloud users can request this feature by [opening a support ticket in the Cloud Portal](/profile/org#support).
{{% /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`:
docs/sources/alerting/migrating-alerts/_index.md
+6 -2
View File
@@ -12,7 +12,9 @@ weight: 110
Grafana Alerting is enabled by default for new installations or existing installations whether or not legacy alerting is configured.
> **Note**: When upgrading, your dashboard alerts are migrated to a new format. This migration can be rolled back easily by [opting out]({{< relref "opt-out/" >}}). If you have any questions regarding this migration, please contact us.
{{% admonition type="note" %}}
When upgrading, your dashboard alerts are migrated to a new format. This migration can be rolled back easily by [opting out]({{< relref "opt-out/" >}}). If you have any questions regarding this migration, please contact us.
{{% /admonition %}}
Existing installations that do not use legacy alerting will have Grafana Alerting enabled by default unless alerting is disabled in the configuration.
@@ -20,7 +22,9 @@ Likewise, existing installations that use legacy alerting will be automatically
Once the upgrade has taken place, you still have the option to [roll back]({{< relref "roll-back/" >}}) to legacy alerting. However, we do not recommend choosing this option. If you do choose to roll back, Grafana will restore your alerts to the alerts you had at the point in time when the upgrade took place. All new alerts and changes made exclusively in Grafana Alerting will be deleted.
> **Note**: Cloud customers, who do not want to upgrade to Grafana Alerting, should contact customer support.
{{% admonition type="note" %}}
Cloud customers, who do not want to upgrade to Grafana Alerting, should contact customer support.
{{% /admonition %}}
If you have opted out or rolled back, you can always choose to [opt in]({{< relref "opt-in/" >}}) to Grafana Alerting at a later point in time.
docs/sources/alerting/migrating-alerts/opt-out.md
+3 -1
View File
@@ -28,7 +28,9 @@ enabled = false
Installations that have been migrated to Grafana Alerting can [roll back]({{< relref "roll-back/" >}}) to legacy alerting at any time.
> **Note:** This topic is only relevant for OSS and Enterprise customers. Contact customer support to enable or disable Grafana Alerting for your Grafana Cloud stack.
{{% admonition type="note" %}}
This topic is only relevant for OSS and Enterprise customers. Contact customer support to enable or disable Grafana Alerting for your Grafana Cloud stack.
{{% /admonition %}}
The `ngalert` toggle previously used to enable or disable Grafana Alerting is no longer available.
docs/sources/cli.md
+3 -1
View File
@@ -25,7 +25,9 @@ grafana-cli -h
To invoke Grafana CLI, add the path to the grafana binaries in your `PATH` environment variable. Alternately, if your current directory is the `bin` directory, use `./grafana-cli`. Otherwise, you can specify full path to the CLI. For example, on Linux `/usr/share/grafana/bin/grafana-cli` and on Windows `C:\Program Files\GrafanaLabs\grafana\bin\grafana-cli.exe`.
> **Note:** Some commands, such as installing or removing plugins, require `sudo` on Linux. If you are on Windows, run Windows PowerShell as Administrator.
{{% admonition type="note" %}}
Some commands, such as installing or removing plugins, require `sudo` on Linux. If you are on Windows, run Windows PowerShell as Administrator.
{{% /admonition %}}
## Grafana CLI command syntax
docs/sources/dashboards/assess-dashboard-usage/index.md
+3 -1
View File
@@ -20,7 +20,9 @@ weight: 200
Usage insights enables you to have a better understanding of how your Grafana instance is used.
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/). Grafana Cloud insights logs include additional fields with their own dashboards. Read more in the [Grafana Cloud documentation](/docs/grafana-cloud/usage-insights/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/). Grafana Cloud insights logs include additional fields with their own dashboards. Read more in the [Grafana Cloud documentation](/docs/grafana-cloud/usage-insights/).
{{% /admonition %}}
The usage insights feature collects a number of aggregated data and stores them in the database:
docs/sources/dashboards/build-dashboards/create-dashboard-url-variables/index.md
+3 -1
View File
@@ -61,7 +61,9 @@ https://${your-domain}/path/to/your/dashboard?var-adhoc=example_key|=|example_va
The query parameter `var-adhoc=key|=|value` applies the ad hoc filter configured as the `adhoc` dashboard variable using the `example_key` key, the `=` operator, and the `example_value` value.
> **Note:** When sharing URLs with ad hoc filters, remember to encode the URL. In the above example, replace the pipes (`|`) with `%7C` and the equality operator (`=`) with `%3D`.
{{% admonition type="note" %}}
When sharing URLs with ad hoc filters, remember to encode the URL. In the above example, replace the pipes (`|`) with `%7C` and the equality operator (`=`) with `%3D`.
{{% /admonition %}}
### Example
docs/sources/dashboards/build-dashboards/create-dashboard/index.md
+3 -1
View File
@@ -81,7 +81,9 @@ To see an example of repeating rows, refer to [Dashboard with repeating rows](ht
1. On the **Row Options** dialog box, add a title and select the variable for which you want to add repeating rows.
> **Note:** To provide context to dashboard users, add the variable to the row title.
{{% admonition type="note" %}}
To provide context to dashboard users, add the variable to the row title.
{{% /admonition %}}
## Move a panel
docs/sources/dashboards/build-dashboards/view-dashboard-json-model/index.md
+3 -1
View File
@@ -26,7 +26,9 @@ To view the JSON of a dashboard:
When a user creates a new dashboard, a new dashboard JSON object is initialized with the following fields:
> **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.
{{% admonition type="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.
{{% /admonition %}}
```json
{
docs/sources/dashboards/create-reports/index.md
+35 -13
View File
@@ -70,15 +70,21 @@ Only organization administrators can create reports by default. You can customiz
### Choose template variables
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.5 and later behind the `reportVariables` feature flag, Grafana Enterprise version 8.0 and later without a feature flag, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
You can configure report-specific template variables for the dashboard on the report page. The variables that you select will override the variables from the dashboard, and they are used when rendering a PDF file of the report. For detailed information about using template variables, refer to the [Templates and variables]({{< relref "../variables/" >}}) section.
> **Note:** The query variables saved with a report might become of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that occurs, the selected variables must be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report stays up-to-date as new values are added.
{{% admonition type="note" %}}
The query variables saved with a report might become of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that occurs, the selected variables must be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report stays up-to-date as new values are added.
{{% /admonition %}}
### Render a report with panels or rows set to repeat by a variable
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to [Repeat panels or rows]({{< relref "../../panels-visualizations/configure-panel-options/#configure-repeating-rows-or-panels" >}}).
@@ -93,7 +99,9 @@ You can include dynamic dashboards with panels or rows, set to repeat by a varia
### Report time range
> **Note:** You can set custom report time ranges in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 7.2+ and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
You can set custom report time ranges in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 7.2+ and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
By default, reports use the saved time range of the dashboard. You can change the time range of the report by:
@@ -117,7 +125,9 @@ If the time zone is set differently between your Grafana server and its remote i
### CSV export
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 8+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) 8+ with the [Grafana image renderer plugin](/grafana/plugins/grafana-image-renderer) v3.0+, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
You can attach a CSV file to the report email for each table panel on the selected dashboard, along with the PDF report. By default, CSVs larger than 10Mb are not sent which keeps email servers from rejecting the email. You can increase or decrease this limit in the [reporting configuration]({{< relref "#rendering-configuration" >}}).
@@ -129,8 +139,10 @@ A background job runs every 10 minutes and removes temporary CSV files. You can
### Scheduling
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
> The scheduler was significantly changed in Grafana Enterprise version 8.1.
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
The scheduler was significantly changed in Grafana Enterprise version 8.1.
{{% /admonition %}}
Scheduled reports can be sent once, or repeated on an hourly, daily, weekly, or monthly basis, or sent at custom intervals. You can also disable scheduling by selecting **Never**, for example to send the report via the API.
@@ -150,7 +162,9 @@ When you schedule a report with a monthly frequency, and set the start date betw
#### Send a test email
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 7.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
1. In the report, click **Send test email**.
1. In the **Email** field, enter the email address or addresses that you want to test, separated by a semicolon.
@@ -161,19 +175,25 @@ The last saved version of the report will be sent to selected emails. You can us
### Pause a report
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 8.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
You can pause sending reports from the report list view by clicking the pause icon. The report will not be sent according to its schedule until it is resumed by clicking the resume button on the report row.
### Add multiple dashboards to a report
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
You can add more than one dashboard to a report. Additional dashboards will be rendered as new pages in the same PDF file, or additional images if you chose to embed images in your report email. You cannot add the same dashboard to a report multiple times.
### Embed a dashboard as an image into a report
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 9.0 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
You can send a report email with an image of the dashboard embedded in the email instead of attached as a PDF. In this case, the email recipients can see the dashboard at a glance instead of having to open the PDF.
@@ -181,7 +201,9 @@ You can send a report email with an image of the dashboard embedded in the email
You can generate and save PDF files of any dashboard.
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 6.7 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) version 6.7 and later, and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
1. In the upper-right corner of the dashboard that you want to export as PDF, click the **Share dashboard** icon.
1. On the PDF tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
@@ -245,7 +267,7 @@ Email branding:
- **Footer link text:** Text of the link in the report email footer. Defaults to `Grafana`.
- **Footer link URL:** Link of the report email footer.
> Note: Currently, the API does not allow for the simultaneous upload of files with identical names for both the email logo and report logo. You can still upload the same file for each logo separately in two distinct steps.
Currently, the API does not allow for the simultaneous upload of files with identical names for both the email logo and report logo. You can still upload the same file for each logo separately in two distinct steps.
## Troubleshoot reporting
docs/sources/dashboards/dashboard-public/index.md
+139 -41
View File
@@ -6,24 +6,33 @@ title: Public dashboards
weight: 8
---
## Public dashboards
# Public dashboards
> **Note:** This is an opt-in alpha feature.
{{% admonition type="note" %}}
> **Caution:** Making your dashboard public could result in a large number of queries to the datasources used by your dashboard.
> This can be mitigated by utilizing the enterprise [caching](https://grafana.com/docs/grafana/latest/enterprise/query-caching/) and/or rate limiting features.
This feature is in [public preview](/docs/release-life-cycle/).
Public dashboards allow you to share your Grafana dashboard with anyone. This is useful when you want to expose your
dashboard to the world.
{{% /admonition %}}
#### Security implications of making your dashboard public
{{% admonition type="caution" %}}
Making your dashboard public could result in a large number of queries to the data sources used by your dashboard.
This can be mitigated by utilizing the enterprise [caching]({{< relref "../../administration/data-source-management/#query-caching" >}}) and/or rate limiting features.
{{% /admonition %}}
Public dashboards allow you to share your Grafana dashboard with anyone. This is useful when you want to make your dashboard available to the world without requiring access to your Grafana organization. This differs from [dashboard sharing]({{< relref "../share-dashboards-panels" >}}), which either requires recipients to be users in the same Grafana organization or provides limited information, as with a snapshot.
You can see a list of all your public dashboards in one place by navigating to **Dashboards > Public dashboards**. For each dashboard in the list, the page displays the status, a link to view the dashboard, a link to the public dashboard configuration, and the option to revoke the public URL.
## Security implications of making your dashboard public
- Anyone with the URL can access the dashboard.
- Public dashboards are read-only.
- Arbitrary queries **cannot** be run against your datasources through public dashboards. Public dashboards can only execute the
- Arbitrary queries **cannot** be run against your data sources through public dashboards. Public dashboards can only execute the
queries stored on the original dashboard.
#### Enable the feature
## Enable the feature
Add the `publicDashboards` feature toggle to your `custom.ini` file.
@@ -38,31 +47,117 @@ If you are using Docker, use an environment variable to enable public dashboards
--env GF_FEATURE_TOGGLES_ENABLE=publicDashboards
```
> **Note:** For Grafana Cloud, you will need to contact support to have the feature enabled.
{{% admonition type="note" %}}
#### Make a dashboard public
For Grafana Cloud (Pro and Advanced only), contact support to have the feature enabled.
- Click on the sharing icon to the right of the dashboard title.
- Click on the Public Dashboard tab.
- Acknowledge the implications of making the dashboard public by checking all the checkboxes.
- Turn on the Enabled toggle.
- Click `Save Sharing Configuration` to make the dashboard public and make your link live.
- Copy the public dashboard link if you'd like to share it. You can always come back later for it.
{{% /admonition %}}
#### Revoke access
## Make a dashboard public
- Click on the sharing icon to the right of the dashboard title.
- Click on the Public Dashboard tab.
- Turn off the Enabled toggle.
- Click `Save Sharing Configuration` to save your changes.
- Anyone with the link will not be able to access the dashboard publicly anymore.
1. Click the sharing icon in the dashboard header.
1. Click the **Public dashboard** tab.
1. Acknowledge the implications of making the dashboard public by selecting all the checkboxes.
1. Click **Generate public URL** to make the dashboard public and make your link live.
1. Copy the public dashboard link if you'd like to share it. You can always come back later for it.
#### Supported Datasources
Once you've made the dashboard public, a **Public** tag is displayed in the header of the dashboard.
Public dashboards _should_ work with any datasource that has the properties `backend` and `alerting` both set to true in it's `package.json`. However, this cannot always be
guaranteed because plugin developers can override this functionality. The following lists include data sources confirmed to work with public dashboards and data sources that should work but have not been confirmed as compatible.
## Pause access
##### Confirmed:
1. Click the sharing icon in the dashboard header.
1. Click the **Public dashboard** tab.
1. Enable the **Pause sharing dashboard** toggle.
The dashboard is no longer accessible, even with the link, until you make it shareable again.
## Revoke access
1. Click the sharing icon in the dashboard header.
1. Click the **Public dashboard** tab.
1. Click **Revoke public URL** to delete the public dashboard.
The link no longer works. You must create a new public URL, as in [Make a dashboard public](#make-a-dashboard-public).
## Email sharing
{{% admonition type="note" %}}
Available in [public preview](/docs/release-life-cycle/) in [Grafana Cloud Pro and Advanced](/docs/grafana-cloud). Please contact support to have the feature enabled.
{{% /admonition %}}
Email sharing allows you to share your public dashboard with only specific people by email, instead of having it accessible to anyone with the URL. When you use email sharing, recipients receive a one-time use link that's valid for **one hour**. Once the link is used, the viewer has access to the public dashboard for **30 days**.
### Invite a viewer
1. Click the sharing icon in the dashboard header.
1. Click the **Public dashboard** tab.
1. Acknowledge the implications of making the dashboard public by selecting all the checkboxes.
1. Click **Generate public URL** to make the dashboard public and make your link live.
1. Under Can view dashboard, click **Only specified people**.
1. Enter the email you want to share the public dashboard with.
1. Click **Invite**.
1. The recipient will receive an email with a one-time use link.
### Viewers requesting access
If a viewer without access tries to navigate to the public dashboard, they'll be asked to request access by providing their email. They will receive an email with a new one-time use link if the email they provided has already been invited to view the public dashboard and has not been revoked.
If the viewer doesn't have an invitation or it's been revoked, you won't be notified and no link is sent.
### Revoke access for a viewer
1. Click the sharing icon in the dashboard header.
1. Click the **Public dashboard** tab.
1. Click **Revoke** on the viewer you'd like to revoke access for.
Immediately, the viewer no longer has access to the public dashboard, nor can they use any existing one-time use links they may have.
### Reinvite a viewer
1. Click the sharing icon in the dashboard header.
1. Click the **Public dashboard** tab.
1. Click **Resend** on the viewer you'd like to re-share the public dashboard with.
The viewer will receive an email with a new one-time use link. This will invalidate all previously issued links for that viewer.
### View public dashboard users
To see a list of users who have accessed your dashboard by way of email sharing, take the following steps:
1. In the main sidebar navigation, click **Administration**.
1. Click **Users**.
1. Click the **Public dashboard users** tab.
From here, you can see the earliest time a user has been active in a dashboard, which public dashboards they have access to, and their role.
### Access limitations
One-time use links use browser cookies, so when a viewer is granted access through one of these links, they will only have access on the browser they used to claim the link.
A single viewer cannot generate multiple valid one-time use links. When a new one-time use link is issued for a viewer, all previous ones are invalidated.
If a Grafana user has read access to the parent dashboard, they can view the public dashboard without needing to have access granted.
## Assess public dashboard usage
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}) and [Grafana Cloud Pro and Advanced](/docs/grafana-cloud).
{{% /admonition %}}
You can check usage analytics about your public dashboard by clicking the insights icon in the dashboard header:
{{< figure src="/media/docs/grafana/dashboards/screenshot-dashboard-insights.png" max-width="400px" class="docs-image--no-shadow" alt="Dashboard insights icon" >}}
Learn more about the kind of information provided in the [dashboard insights documentation]({{< relref "../assess-dashboard-usage/#dashboard-insights" >}}).
## Supported data sources
Public dashboards _should_ work with any data source that has the properties `backend` and `alerting` both set to true in its `package.json`. However, this can't always be
guaranteed because plugin developers can override this functionality. The following lists include data sources confirmed to work with public dashboards and data sources that should work, but have not been confirmed as compatible.
### Confirmed:
<table>
<tr>
@@ -93,9 +188,13 @@ guaranteed because plugin developers can override this functionality. The follow
</tr>
</table>
##### Unconfirmed:
### Unconfirmed:
> **Note:** If you've confirmed one of these datasources work with public dashboards, let us know in our [Github](https://github.com/grafana/grafana/discussions/49253) discussion, and we'll mark it as confirmed!
{{% admonition type="note" %}}
If you've confirmed one of these data sources work with public dashboards, let us know in our [Github](https://github.com/grafana/grafana/discussions/49253) discussion, and we'll mark it as confirmed!
{{% /admonition %}}
<table>
<tr>
@@ -143,32 +242,31 @@ guaranteed because plugin developers can override this functionality. The follow
<li>Snowflake</li>
<li>Splunk</li>
<li>Splunk Infrastructure Monitoring</li>
<li>Sqlyze Datasource</li>
<li>Sqlyze data source</li>
<li>TDengine</li>
<li>Vertica</li>
<li>Wavefront</li>
<li>X-Ray</li>
<li>kdb+</li>
<li>simple grpc datasource</li>
<li>simple grpc data source</li>
</ul>
</td>
</tr>
</table>
#### Limitations
## Limitations
- Panels that use frontend datasources will fail to fetch data.
- Template variables are currently not supported, but are planned to be in the future.
- The time range is permanently set to the default time range on the dashboard. If you update the default time range for a dashboard, it will be reflected in the public dashboard.
- Panels that use frontend data sources will fail to fetch data.
- Template variables are not currently supported, but support is planned in the future.
- Exemplars will be omitted from the panel.
- Only annotations that query the `-- Grafana --` datasource are supported.
- Only annotations that query the `-- Grafana --` data source are supported.
- Organization annotations are not supported.
- Grafana Live and real-time event streams are not supported.
- Library panels are currently not supported, but are planned to be in the future.
- Datasources using Reverse Proxy functionality are not supported.
- Library panels are currently not supported, but support is planned in the future.
- Data sources using Reverse Proxy functionality are not supported.
We are excited to share this enhancement with you and we’d love your feedback! Please check out the [Github](https://github.com/grafana/grafana/discussions/49253) discussion and join the conversation.
We're excited to share this enhancement with you and we’d love your feedback! Please check out the [Github](https://github.com/grafana/grafana/discussions/49253) discussion and join the conversation.
#### Custom branding
## Custom branding
If you are a Grafana Enterprise customer, you can use custom branding to change the appearance of a public dashboard footer. For more information, refer to [Custom branding](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/configure-custom-branding/).
If you're a Grafana Enterprise customer, you can use custom branding to change the appearance of a public dashboard footer. For more information, refer to [Custom branding](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/configure-custom-branding/).
docs/sources/dashboards/share-dashboards-panels/index.md
+9 -3
View File
@@ -42,7 +42,9 @@ You must have an authorized viewer permission to see an image rendered by a dire
The same permission is also required to view embedded links unless you have anonymous access permission enabled for your Grafana instance.
> **Note:** As of Grafana 8.0, anonymous access permission is not available in Grafana Cloud.
{{% admonition type="note" %}}
As of Grafana 8.0, anonymous access permission is not available in Grafana Cloud.
{{% /admonition %}}
When you share a panel or dashboard as a snapshot, a snapshot (which is a panel or dashboard at the moment you take the snapshot) is publicly available on the web. Anyone with a link to it can access it. Because snapshots do not require any authorization to view, Grafana removes information related to the account it came from, as well as any sensitive data from the snapshot.
@@ -50,7 +52,9 @@ When you share a panel or dashboard as a snapshot, a snapshot (which is a panel
You can share a dashboard as a direct link or as a snapshot. You can also export a dashboard.
> **Note:** If you change a dashboard, ensure that you save the changes before sharing.
{{% admonition type="note" %}}
If you change a dashboard, ensure that you save the changes before sharing.
{{% /admonition %}}
1. Navigate to the home page of your Grafana instance.
1. Click on the share icon in the top navigation.
@@ -89,7 +93,9 @@ Grafana dashboards can easily be exported and imported. For more information, re
You can generate and save PDF files of any dashboard.
> **Note:** Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}).
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../introduction/grafana-enterprise/" >}}).
{{% /admonition %}}
1. In the upper-right corner of the dashboard that you want to export as PDF, click the **Share dashboard** icon.
1. On the PDF tab, select a layout option for the exported dashboard: **Portrait** or **Landscape**.
docs/sources/dashboards/variables/add-template-variables/index.md
+24 -8
View File
@@ -81,7 +81,9 @@ Query variables are generally only supported for strings. If your query returns
Query expressions can contain references to other variables and in effect create linked variables. Grafana detects this and automatically refreshes a variable when one of its linked variables change.
> **Note:** Query expressions are different for each data source. For more information, refer to the documentation for your [data source]({{< relref "../../../datasources/" >}}).
{{% admonition type="note" %}}
Query expressions are different for each data source. For more information, refer to the documentation for your [data source]({{< relref "../../../datasources/" >}}).
{{% /admonition %}}
1. [Enter general options](#enter-general-options).
1. In the **Data source** list, select the target data source for the query. For more information about data sources, refer to [Add a data source]({{< relref "../../../administration/data-source-management#add-a-data-source" >}}).
@@ -176,7 +178,9 @@ groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5
_Ad hoc filters_ enable you to add key/value filters that are automatically added to all metric queries that use the specified data source. Unlike other variables, you do not use ad hoc filters in queries. Instead, you use ad hoc filters to write filters for existing queries.
> **Note:** Ad hoc filter variables only work with Prometheus, Loki, InfluxDB, and Elasticsearch data sources.
{{% admonition type="note" %}}
Ad hoc filter variables only work with Prometheus, Loki, InfluxDB, and Elasticsearch data sources.
{{% /admonition %}}
1. [Enter general options](#enter-general-options).
1. In the **Data source** list, select the target data source. For more information about data sources, refer to [Add a data source]({{< relref "../../../administration/data-source-management#add-a-data-source" >}}).
@@ -194,7 +198,9 @@ Ad hoc filters are one of the most complex and flexible variable options availab
Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values into a string that is valid in the given context where the variable is used. Grafana tries to solve this by allowing each data source plugin to inform the templating interpolation engine what format to use for multiple values.
> **Note:** The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If it is left blank, then Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value will be something like `*` or `all`.
{{% admonition type="note" %}}
The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If it is left blank, then Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value will be something like `*` or `all`.
{{% /admonition %}}
#### Multi-value variables with a Graphite data source
@@ -245,7 +251,9 @@ This variable is the name of the current dashboard.
Grafana has two built-in time range variables: `$__from` and `$__to`. They are currently always interpolated as epoch milliseconds by default, but you can control date formatting.
> **Note:** This special formatting syntax is only available in Grafana 7.1.2+
{{% admonition type="note" %}}
This special formatting syntax is only available in Grafana 7.1.2+
{{% /admonition %}}
| Syntax | Example result | Description |
| ------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------- |
@@ -281,7 +289,9 @@ This variable is the `$__interval` variable in milliseconds, not a time interval
This variable is only available in the Singlestat panel and can be used in the prefix or suffix fields on the Options tab. The variable will be replaced with the series name or alias.
> **Note:** The Singlestat panel is no longer available from Grafana 8.0.
{{% admonition type="note" %}}
The Singlestat panel is no longer available from Grafana 8.0.
{{% /admonition %}}
### $\_\_org
@@ -380,7 +390,9 @@ The query returns all servers associated with `fakesite`, including `web_server_
##### More variables
> **Note:** This example is theoretical. The Graphite server used in the example does not contain CPU metrics.
{{% admonition type="note" %}}
This example is theoretical. The Graphite server used in the example does not contain CPU metrics.
{{% /admonition %}}
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected servers, you could copy the `server` variable and extend the query so that it reads:
@@ -440,7 +452,9 @@ The query returns all servers associated with `Europe`, including `server3`, `se
##### More variables
> **Note:** This example is theoretical. The InfluxDB server used in the example does not contain CPU metrics.
{{% admonition type="note" %}}
This example is theoretical. The InfluxDB server used in the example does not contain CPU metrics.
{{% /admonition %}}
The dashboard stops at two levels, but you could keep going. For example, if you wanted to get CPU metrics for selected hosts, you could copy the `host` variable and extend the query so that it reads:
@@ -565,7 +579,9 @@ demo.robustperception.io:9100
### Filter and modify using named text and value capture groups
> **Note:** This feature is available in Grafana 7.4+.
{{% admonition type="note" %}}
This feature is available in Grafana 7.4+.
{{% /admonition %}}
Using named capture groups, you can capture separate 'text' and 'value' parts from the options returned by the variable query. This allows the variable drop-down list to contain a friendly name for each value that can be selected.
docs/sources/dashboards/variables/inspect-variable/index.md
+3 -1
View File
@@ -17,7 +17,9 @@ weight: 200
The variables page lets you easily identify whether a variable is being referenced (or used) in other variables or dashboard. In addition, you can also [add]({{< relref "./add-template-variables/" >}}) and [manage variables]({{< relref "./add-template-variables/#manage-variables" >}}) on this page.
> **Note:** This feature is available in Grafana 7.4 and later versions.
{{% admonition type="note" %}}
This feature is available in Grafana 7.4 and later versions.
{{% /admonition %}}
![Variables list](/static/img/docs/variables-templates/variables-list-7-4.png)
docs/sources/datasources/aws-cloudwatch/_index.md
+10 -4
View File
@@ -27,7 +27,9 @@ Administrators can also [provision the data source]({{< relref "#provision-the-d
Once you've added the data source, you can [configure it]({{< relref "#configure-the-data-source" >}}) so that your Grafana instance's users can create queries in its [query editor]({{< relref "./query-editor/" >}}) when they [build dashboards]({{< relref "../../dashboards/build-dashboards/" >}}) and use [Explore]({{< relref "../../explore/" >}}).
> **Note:** To troubleshoot issues while setting up the CloudWatch data source, check the `/var/log/grafana/grafana.log` file.
{{% admonition type="note" %}}
To troubleshoot issues while setting up the CloudWatch data source, check the `/var/log/grafana/grafana.log` file.
{{% /admonition %}}
## Configure the data source
@@ -343,7 +345,9 @@ filter @message like /Exception/
| sort exceptionCount desc
```
> **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 type="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 %}}
For more information on Grafana alerts, refer to [Alerting]({{< relref "../../alerting" >}}).
@@ -354,8 +358,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.
> **Note:** Grafana v6.5 and higher 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 type="note" %}}
Grafana v6.5 and higher 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 %}}
For more information, refer to the [CloudWatch pricing page](https://aws.amazon.com/cloudwatch/pricing/).
docs/sources/datasources/aws-cloudwatch/aws-authentication/index.md
+3 -1
View File
@@ -77,7 +77,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.
> **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 type="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 %}}
### Credentials file example
docs/sources/datasources/aws-cloudwatch/query-editor/index.md
+9 -3
View File
@@ -90,7 +90,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.
> **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 type="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 %}}
##### Period macro
@@ -109,7 +111,9 @@ This feature is not available for metrics based on [metric math expressions](#me
### Create a Metric Insights query
> **Note:** This query option is available only in Grafana v8.3 and higher.
{{% admonition type="note" %}}
This query option is available only in Grafana v8.3 and higher.
{{% /admonition %}}
The Metrics Query option in the CloudWatch data source is referred to as **Metric Insights** in the AWS console.
It's a fast, flexible, SQL-based query engine that you can use to identify trends and patterns across millions of operational metrics in real time.
@@ -171,7 +175,9 @@ The suggestions appear after typing a space, comma, or dollar (`$`) character, o
{{< figure src="/static/img/docs/cloudwatch/cloudwatch-code-editor-autocomplete-8.3.0.png" max-width="500px" class="docs-image--right" caption="Code editor autocomplete" >}}
> **Note:** Template variables in the code editor can interfere with autocompletion.
{{% admonition type="note" %}}
Template variables in the code editor can interfere with autocompletion.
{{% /admonition %}}
To run the query, click **Run query** above the code editor.
docs/sources/datasources/elasticsearch/_index.md
+30 -30
View File
@@ -30,27 +30,30 @@ Once you've added the Elasticsearch data source, you can [configure it]({{< relr
This data source supports these versions of Elasticsearch:
- v7.10+
- v7.16+
- v8.x
## Configure the data source
**To access the data source configuration page:**
To configure basic settings for the data source, complete the following steps:
1. Hover the cursor over the **Configuration** (gear) icon.
1. Select **Data Sources**.
1. Select the Elasticsearch data source.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `Elasticsearch` in the search bar.
1. Click **Elasticsearch**.
Set the data source's basic configuration options carefully:
The **Settings** tab of the data source is displayed.
| Name | Description |
| ----------- | -------------------------------------------------------------------------- |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Sets the data source that's pre-selected for new panels. |
| **Url** | Sets the HTTP protocol, IP, and port of your Elasticsearch server. |
| **Access** | Don't modify Access. Use "Server (default)" or the data source won't work. |
1. Set the data source's basic configuration options:
You must also configure settings specific to the Elasticsearch data source.
| Name | Description |
| ----------- | -------------------------------------------------------------------------- |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Sets the data source that's pre-selected for new panels. |
| **Url** | Sets the HTTP protocol, IP, and port of your Elasticsearch server. |
| **Access** | Don't modify Access. Use `Server (default)` or the data source won't work. |
You must also configure settings specific to the Elasticsearch data source. These options are described in the sections below.
### Index settings
@@ -59,18 +62,6 @@ You must also configure settings specific to the Elasticsearch data source.
Use the index settings to specify a default for the `time field` and your Elasticsearch index's name.
You can use a time pattern, such as `YYYY.MM.DD`, or a wildcard for the index name.
### Elasticsearch version
Select the version of your Elasticsearch data source from the version selection dropdown.
Different versions provide different query compositions and functionalities in the [query editor]({{< relref "./query-editor/" >}}).
Available Elasticsearch versions are `2.x`, `5.x`, `5.6+`, `6.0+`, `7.0+`, `7.7+`, and `7.10+`.
Grafana assumes you're running the lowest possible version for a specified range.
This ensures that new features or breaking changes in a future Elasticsearch release don't affect your configuration.
For example, if you run Elasticsearch `7.6.1` and select `7.0+`, and a new feature is made available for Elasticsearch `7.5.0` or newer releases, then a `7.5+` option will be available.
However, your configuration won't be affected until you explicitly select the new `7.5+` option in your settings.
### Configure Min time interval
The **Min time interval** setting defines a lower limit for the auto group-by time interval.
@@ -101,7 +92,9 @@ Toggle this to enable `X-Pack`-specific features and options, which provide the
When the "X-Pack enabled" setting is active and the configured Elasticsearch version is higher than `6.6.0`, you can configure Grafana to not ignore [frozen indices](https://www.elastic.co/guide/en/elasticsearch/reference/7.13/frozen-indices.html) when performing search requests.
> **Note:** Frozen indices are [deprecated in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/frozen-indices.html) since v7.14.
{{% admonition type="note" %}}
Frozen indices are [deprecated in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/frozen-indices.html) since v7.14.
{{% /admonition %}}
### Logs
@@ -135,7 +128,9 @@ For details on AWS SigV4, refer to the [AWS documentation](https://docs.aws.amaz
#### AWS Signature Version 4 authentication
> **Note:** Available in Grafana v7.3 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.3 and higher.
{{% /admonition %}}
To sign requests to your Amazon Elasticsearch Service domain, you can enable SigV4 in Grafana's [configuration]({{< relref "../../setup-grafana/configure-grafana/#sigv4_auth_enabled" >}}).
@@ -149,6 +144,12 @@ For more information about AWS authentication options, refer to [AWS authenticat
You can define and configure the data source in YAML files as part of Grafana's provisioning system.
For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning/#data-sources" >}}).
{{% admonition type="note" %}}
The previously used `database` field has now been [deprecated](https://github.com/grafana/grafana/pull/58647).
You should now use the `index` field in `jsonData` to store the index name.
Please see the examples below.
{{% /admonition %}}
#### Provisioning examples
**Basic provisioning:**
@@ -160,9 +161,9 @@ datasources:
- name: Elastic
type: elasticsearch
access: proxy
database: '[metrics-]YYYY.MM.DD'
url: http://localhost:9200
jsonData:
index: '[metrics-]YYYY.MM.DD'
interval: Daily
timeField: '@timestamp'
```
@@ -176,12 +177,11 @@ datasources:
- name: elasticsearch-v7-filebeat
type: elasticsearch
access: proxy
database: '[filebeat-]YYYY.MM.DD'
url: http://localhost:9200
jsonData:
index: '[filebeat-]YYYY.MM.DD'
interval: Daily
timeField: '@timestamp'
esVersion: '7.0.0'
logMessageField: message
logLevelField: fields.level
dataLinks:
docs/sources/datasources/elasticsearch/template-variables/index.md
+3 -1
View File
@@ -47,7 +47,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.
> **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 type="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 %}}
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.
docs/sources/datasources/google-cloud-monitoring/_index.md
+3 -1
View File
@@ -24,7 +24,9 @@ weight: 350
Grafana ships with built-in support for Google Cloud Monitoring.
This topic describes queries, templates, variables, and other configuration specific to the Google Cloud Monitoring data source.
> **Note:** Before Grafana v7.1, Google Cloud Monitoring was referred to as Google Stackdriver.
{{% admonition type="note" %}}
Before Grafana v7.1, Google Cloud Monitoring was referred to as Google Stackdriver.
{{% /admonition %}}
For instructions on how to add a data source to Grafana, refer to the [administration documentation]({{< relref "../../administration/data-source-management/" >}}).
Only users with the organization administrator role can add data sources.
docs/sources/datasources/google-cloud-monitoring/query-editor/index.md
+9 -3
View File
@@ -177,7 +177,9 @@ An expected result would look like: `gce_instance - compute.googleapis.com/insta
### Deep-link from Grafana panels to the Google Cloud Console Metrics Explorer
> **Note:** Available in Grafana v7.1 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.1 and higher.
{{% /admonition %}}
{{< figure src="/static/img/docs/v71/cloudmonitoring_deep_linking.png" max-width="500px" class="docs-image--no-shadow" caption="Google Cloud Monitoring deep linking" >}}
@@ -199,7 +201,9 @@ If the query editor rows return different units, Grafana uses the unit from the
### Use the Monitoring Query Language
> **Note:** Available in Grafana v7.4 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.4 and higher.
{{% /admonition %}}
The Monitoring Query Language (MQL) query builder helps you query and display MQL results in time series format.
To understand basic MQL concepts, refer to [Introduction to Monitoring Query Language](https://cloud.google.com/monitoring/mql).
@@ -222,7 +226,9 @@ However, `{{metric.service}}` is not supported, and `{{metric.type}}` and `{{met
## Query Service Level Objectives
> **Note:** Available in Grafana v7.0 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.0 and higher.
{{% /admonition %}}
{{< figure src="/static/img/docs/google-cloud-monitoring/slo-query-builder-8-0.png" max-width="400px" class="docs-image--no-shadow" caption="Service Level Objectives (SLO) query editor" >}}
docs/sources/datasources/graphite/query-editor/index.md
+8 -4
View File
@@ -66,8 +66,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.
> **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 type="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 %}}
### Combine time series
@@ -82,8 +84,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.
> **Tip:** 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.
{{% admonition type="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.
{{% /admonition %}}
## Nest queries
docs/sources/datasources/graphite/template-variables/index.md
+3 -1
View File
@@ -104,7 +104,9 @@ For example, `apps.$app.servers.*` uses the variable `$app` in its query definit
### Use `__searchFilter` to filter query variable results
> **Note:** Available in Grafana v6.5 and higher.
{{% admonition type="note" %}}
Available in Grafana v6.5 and higher.
{{% /admonition %}}
You can use `__searchFilter` in the query field to filter the query result based on what the user types in the dropdown select box.
The default value for `__searchFilter` is `*` if you've not entered anything, and `` when used as part of a regular expression.
docs/sources/datasources/influxdb/_index.md
+32 -20
View File
@@ -30,23 +30,26 @@ Once you've added the InfluxDB data source, you can [configure it]({{< relref "#
## Configure the data source
**To access the data source configuration page:**
To configure basic settings for the data source, complete the following steps:
1. Hover the cursor over the **Configuration** (gear) icon.
1. Select **Data Sources**.
1. Select the InfluxDB data source.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `InfluxDB` in the search bar.
1. Select **InfluxDB**.
Set the data source's basic configuration options carefully:
The **Settings** tab of the data source is displayed.
| Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. We recommend something like `InfluxDB-InfluxQL`. |
| **Default** | Sets whether the data source is pre-selected for new panels. |
| **URL** | The HTTP protocol, IP address, and port of your InfluxDB API. InfluxDB's default API port is 8086. |
| **Min time interval** | _(Optional)_ Refer to [Min time interval]({{< relref "#configure-min-time-interval" >}}). |
| **Max series** | _(Optional)_ Limits the number of series and tables that Grafana processes. Lower this number to prevent abuse, and increase it if you have many small time series and not all are shown. Defaults to 1,000. |
1. Set the data source's basic configuration options carefully:
You can also configure settings specific to the InfluxDB data source:
| Name | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. We recommend something like `InfluxDB-InfluxQL`. |
| **Default** | Sets whether the data source is pre-selected for new panels. |
| **URL** | The HTTP protocol, IP address, and port of your InfluxDB API. InfluxDB's default API port is 8086. |
| **Min time interval** | _(Optional)_ Refer to [Min time interval]({{< relref "#configure-min-time-interval" >}}). |
| **Max series** | _(Optional)_ Limits the number of series and tables that Grafana processes. Lower this number to prevent abuse, and increase it if you have many small time series and not all are shown. Defaults to 1,000. |
You can also configure settings specific to the InfluxDB data source. These options are described in the sections below.
### Min time interval
@@ -81,10 +84,13 @@ InfluxDB data source options differ depending on which query language you select
To help choose the best language for your needs, refer to a [comparison of Flux vs InfluxQL](https://docs.influxdata.com/influxdb/v1.8/flux/flux-vs-influxql/) and [why InfluxData created Flux](https://www.influxdata.com/blog/why-were-building-flux-a-new-data-scripting-and-query-language/).
> **Note:** Though not required, we recommend that you append your query language choice to the data source's **Name** setting:
>
> - InfluxDB-InfluxQL
> - InfluxDB-Flux
{{% admonition type="note" %}}
Though not required, we recommend that you append your query language choice to the data source's **Name** setting:
- InfluxDB-InfluxQL
- InfluxDB-Flux
{{% /admonition %}}
### Configure InfluxQL
@@ -114,6 +120,12 @@ Configure these options if you select the Flux query language:
You can define and configure the data source in YAML files as part of Grafana's provisioning system.
For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning/#data-sources" >}}).
{{% admonition type="note" %}}
`database` [field is deprecated](https://github.com/grafana/grafana/pull/58647).
We suggest to use `dbName` field in `jsonData`. Please see the examples below.
No need to change existing provisioning settings.
{{% /admonition %}}
#### Provisioning examples
**InfluxDB 1.x example:**
@@ -125,10 +137,10 @@ datasources:
- name: InfluxDB_v1
type: influxdb
access: proxy
database: site
user: grafana
url: http://localhost:8086
jsonData:
dbName: site
httpMode: GET
secureJsonData:
password: grafana
@@ -163,9 +175,9 @@ datasources:
type: influxdb
access: proxy
url: http://localhost:8086
# This database should be mapped to a bucket
database: site
jsonData:
# This database should be mapped to a bucket
dbName: site
httpMode: GET
httpHeaderName1: 'Authorization'
secureJsonData:
docs/sources/datasources/jaeger/_index.md
+150 -78
View File
@@ -15,75 +15,114 @@ weight: 800
# Jaeger data source
Grafana ships with built-in support for Jaeger, which provides open source, end-to-end distributed tracing.
This topic explains configuration and queries specific to the Jaeger data source.
Grafana ships with built-in support for Jaeger, which provides open source, end-to-end distributed tracing. This topic explains configuration and queries specific to the Jaeger data source.
For instructions on how to add a data source to Grafana, refer to the [administration documentation]({{< relref "../../administration/data-source-management" >}}).
Only users with the organization administrator role can add data sources.
Administrators can also [configure the data source via YAML]({{< relref "#provision-the-data-source" >}}) with Grafana's provisioning system.
You can also [upload a JSON trace file]({{< relref "#upload-a-json-trace-file" >}}), and [link a trace ID from logs]({{< relref "#link-a-trace-id-from-logs" >}}) in Loki.
Once you've added the data source, you can [configure it]({{< relref "#configure-the-data-source" >}}) so your Grafana instance's users can create queries in the [query editor]({{< relref "#query-the-data-source" >}}) when the users [build dashboards]({{< relref "../../dashboards/build-dashboards/" >}}) and use [Explore]({{< relref "../../explore/" >}}).
You can also [upload a JSON trace file]({{< relref "#upload-a-json-trace-file" >}}), [link to a trace ID from logs]({{< relref "#link-to-a-trace-id-from-logs" >}}), and [link to a trace ID from metrics]({{< relref "#link-to-a-trace-id-from-metrics" >}}).
## Configure the data source
**To access the data source configuration page:**
To configure basic settings for the data source, complete the following steps:
1. Hover the cursor over the **Configuration** (gear) icon.
1. Select **Data Sources**.
1. Select the Jaeger data source.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `Jaeger` in the search bar.
1. Select **Jaeger**.
Set the data source's basic configuration options carefully:
The **Settings** tab of the data source is displayed.
| Name | Description |
| -------------- | ------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Defines whether this data source is pre-selected for new panels. |
| **URL** | Sets the URL of the Jaeger instance, such as `http://localhost:16686`. |
| **Basic Auth** | Enables basic authentication for the Jaeger data source. |
| **User** | Defines the user name for basic authentication. |
| **Password** | Defines the password for basic authentication. |
1. Set the data source's basic configuration options:
You can also configure settings specific to the Jaeger data source:
| Name | Description |
| -------------- | ------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Defines whether this data source is pre-selected for new panels. |
| **URL** | Sets the URL of the Jaeger instance, such as `http://localhost:16686`. |
| **Basic Auth** | Enables basic authentication for the Jaeger data source. |
| **User** | Defines the user name for basic authentication. |
| **Password** | Defines the password for basic authentication. |
### Configure trace to logs
You can also configure settings specific to the Jaeger data source. These options are described in the sections below.
{{< figure src="/static/img/docs/explore/traces-to-logs-settings-8-2.png" class="docs-image--no-shadow" caption="Screenshot of the trace to logs settings" >}}
### Trace to logs
> **Note:** Available in Grafana v7.4 and higher.
![Trace to logs settings](/media/docs/tempo/tempo-trace-to-logs-9-4.png)
{{% admonition type="note" %}}
Available in Grafana v7.4 and higher.
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
The **Trace to logs** setting configures the [trace to logs feature]({{< relref "../../explore/trace-integration" >}}) that is available when you integrate Grafana with Jaeger.
**To configure trace to logs:**
There are two ways to configure the trace to logs feature:
- Use a simplified configuration with default query, or
- Configure a custom query where you can use a [template language]({{< relref "../../dashboards/variables/variable-syntax">}}) to interpolate variables from the trace or span.
#### Use a simple configuration
1. Select the target data source.
2. Select which tags to use in the logs query. The tags you configure must be present in the spans attributes or resources for a trace to logs span link to appear.
- **Single tag**
- Configuring `job` as a tag and clicking on a span link will take you to your configured logs datasource with the query `{job='value from clicked span'}`.
- **Multiple tags**
- If multiple tags are used they will be concatenated so the logs query would look like `{job='value from clicked span', service='value from clicked span'}`.
- **Mapped tags**
- For a mapped tag `service.name` with value `service`, clicking on a span link will take you to your configured logs datasource with the query `{service='value from clicked span'}` instead of `{service.name='value from clicked span'}`.
- This is useful for instances where your tracing datasource tags and your logs datasource tags don't match one-to-one.
1. Set start and end time shift. Since the logs timestamps may not exactly match the timestamps of the spans in trace, it may be necessary to search in larger or shifted time range to find the desired logs.
1. Select which tags to use in the logs query. The tags you configure must be present in the spans attributes or resources for a trace to logs span link to appear. You can optionally configure a new name for the tag. This is useful if the tag has dots in the name and the target data source does not allow dots in labels. In that case, you can, for example, remap `http.status` to `http_status`.
1. Optionally, switch on the **Filter by trace ID** and/or **Filter by span ID** setting to further filter the logs if your logs consistently contain trace or span IDs.
#### Configure a custom query
1. Select the target data source.
1. Set start and end time shift. Since the logs timestamps may not exactly match the timestamps of the spans in the trace, you may need to widen or shift the time range to find the desired logs.
1. Optionally, select tags to map. These tags can be used in the custom query with `${__tags}` variable. This variable will interpolate the mapped tags as a list in an appropriate syntax for the data source and will only include the tags that were present in the span omitting those that weren't present. You can optionally configure a new name for the tag. This is useful in cases where the tag has dots in the name and the target data source does not allow dots in labels. For example, you can remap `http.status` to `http_status`. If you don't map any tags here, you can still use any tag in the query like this `method="${__span.tags.method}"`.
1. Skip **Filter by trace ID** and **Filter by span ID** settings as these cannot be used with a custom query.
1. Switch on **Use custom query**.
1. Specify a custom query to be used to query the logs. You can use various variables to make that query relevant for current span. The link is present only if all the variables are interpolated with non-empty values to prevent creating an invalid query.
#### Variables that can be used in a custom query
To use a variable you need to wrap it in `${}`. For example: `${__span.name}`.
| Variable name | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\_\_tags** | This variable uses the tag mapping from the UI to create a label matcher string in the specific data source syntax. The variable only uses tags that are present in the span. The link is still created even if only one of those tags is present in the span. You can use this if all tags are not required for the query to be useful. |
| **\_\_span.spanId** | The ID of the span. |
| **\_\_span.traceId** | The ID of the trace. |
| **\_\_span.duration** | The duration of the span. |
| **\_\_span.name** | Name of the span. |
| **\_\_span.tags** | Namespace for the tags in the span. To access a specific tag named `version`, you would use `${__span.tags.version}`. In case the tag contains dot, you have to access it as `${__span.tags["http.status"]}`. |
| **\_\_trace.traceId** | The ID of the trace. |
| **\_\_trace.duration** | The duration of the trace. |
| **\_\_trace.name** | The name of the trace. |
The following table describes the ways in which you can configure your trace to logs settings:
| Name | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source** | Sets the target data source. |
| **Tags** | Defines the tags to use in the logs query. Default is `'cluster', 'hostname', 'namespace', 'pod'`. |
| **Map tag names** | Enables configuring how Jaeger tag names map to logs label names. For example, map `service.name` to `service`. |
| **Span start time shift** | Shifts the start time for the logs query based on the span start time. To extend to the past, use a negative value. Use time interval units like `5s`, `1m`, `3h`. Default is `0`. |
| **Span end time shift** | Shifts the end time for the logs query based on the span end time. Use time interval units. Default is `0`. |
| **Filter by Trace ID** | Toggles whether to append the trace ID to the logs query. |
| **Filter by Span ID** | Toggles whether to append the span ID to the logs query. |
| Setting name | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source** | Defines the target data source. You can select only Loki or Splunk \[logs\] data sources. |
| **Span start time shift** | Shifts the start time for the logs query, based on the span's start time. You can use time units, such as `5s`, `1m`, `3h`. To extend the time to the past, use a negative value. Default: `0`. |
| **Span end time shift** | Shifts the end time for the logs query, based on the span's end time. You can use time units. Default: `0`. |
| **Tags** | Defines the tags to use in the logs query. Default: `cluster`, `hostname`, `namespace`, `pod`. You can change the tag name for example to remove dots from the name if they are not allowed in the target data source. For example, map `http.status` to `http_status`. |
| **Filter by trace ID** | Toggles whether to append the trace ID to the logs query. |
| **Filter by span ID** | Toggles whether to append the span ID to the logs query. |
| **Use custom query** | Toggles use of custom query with interpolation. |
| **Query** | Input to write custom query. Use variable interpolation to customize it with variables from span. |
### Configure trace to metrics
### Trace to metrics
> **Note:** This feature is behind the `traceToMetrics` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
{{% admonition type="note" %}}
This feature is behind the `traceToMetrics` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
The **Trace to metrics** section configures the [trace to metrics feature](/blog/2022/08/18/new-in-grafana-9.1-trace-to-metrics-allows-users-to-navigate-from-a-trace-span-to-a-selected-data-source/).
The **Trace to metrics** setting configures the [trace to metrics feature](/blog/2022/08/18/new-in-grafana-9.1-trace-to-metrics-allows-users-to-navigate-from-a-trace-span-to-a-selected-data-source/) available when integrating Grafana with Jaeger.
Use the settings to select the target Prometheus data source, and create any desired linked queries.
To configure trace to metrics:
1. Select the target data source.
1. Create any desired linked queries.
| Setting name | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -97,15 +136,15 @@ Each linked query consists of:
Interpolate tags using the `$__tags` keyword.
For example, when you configure the query `requests_total{$__tags}`with the tags `k8s.pod=pod` and `cluster`, the result looks like `requests_total{pod="nginx-554b9", cluster="us-east-1"}`.
### Enable Node Graph
### Node Graph
The **Node Graph** setting enables the [Node Graph visualization]({{< relref "../../panels-visualizations/visualizations/node-graph/" >}}), which is disabled by default.
Once enabled, Grafana displays the Node Graph after loading the trace view.
Once enabled, Grafana displays the Node Graph above the trace view.
### Configure the span bar label
### Span bar
The **Span bar label** section helps you display additional information in the span bar row.
The **Span bar** setting helps you display additional information in the span bar row.
You can choose one of three options:
@@ -118,11 +157,9 @@ You can choose one of three options:
### Provision the data source
You can define and configure the data source in YAML files as part of Grafana's provisioning system.
For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning#data-sources" >}}).
For more information about provisioning and available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning#data-sources" >}}).
#### Provisioning examples
**Using basic auth and the trace-to-logs field:**
#### Provisioning example
```yaml
apiVersion: 1
@@ -130,51 +167,51 @@ apiVersion: 1
datasources:
- name: Jaeger
type: jaeger
uid: jaeger-spectra
uid: EbPG8fYoz
url: http://localhost:16686
access: proxy
url: http://localhost:16686/
basicAuth: true
basicAuthUser: my_user
editable: true
readOnly: false
isDefault: false
jsonData:
tracesToLogs:
# Field with internal link pointing to a logs data source in Grafana.
# datasourceUid value must match the datasourceUid value of the logs data source.
tracesToLogsV2:
# Field with an internal link pointing to a logs data source in Grafana.
# datasourceUid value must match the uid value of the logs data source.
datasourceUid: 'loki'
tags: ['job', 'instance', 'pod', 'namespace']
mappedTags: [{ key: 'service.name', value: 'service' }]
mapTagNamesEnabled: false
spanStartTimeShift: '1h'
spanEndTimeShift: '1h'
spanEndTimeShift: '-1h'
tags: ['job', 'instance', 'pod', 'namespace']
filterByTraceID: false
filterBySpanID: false
customQuery: true
query: 'method="${__span.tags.method}"'
tracesToMetrics:
datasourceUid: 'prom'
spanStartTimeShift: '1h'
spanEndTimeShift: '-1h'
tags: [{ key: 'service.name', value: 'service' }, { key: 'job' }]
queries:
- name: 'Sample query'
query: 'sum(rate(traces_spanmetrics_latency_bucket{$__tags}[5m]))'
nodeGraph:
enabled: true
traceQuery:
timeShiftEnabled: true
spanStartTimeShift: '1h'
spanEndTimeShift: '-1h'
spanBar:
type: 'None'
secureJsonData:
basicAuthPassword: my_password
```
## Query traces
## Query the data source
You can query and display traces from Jaeger via [Explore]({{< relref "../../explore" >}}).
{{< figure src="/static/img/docs/explore/jaeger-search-form.png" class="docs-image--no-shadow" caption="Screenshot of the Jaeger query editor" >}}
You can query by trace ID, or use the search form to find traces.
### Query by trace ID
{{< figure src="/static/img/docs/explore/jaeger-trace-id.png" class="docs-image--no-shadow" caption="Screenshot of the Jaeger query editor with trace ID selected" >}}
**To query by trace ID:**
1. Select **TraceID** from the **Query** type selector.
1. Insert the ID into the text input.
This topic explains configuration and queries specific to the Jaeger data source.
For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../../panels-visualizations/query-transform-data" >}}).
### Query by search
@@ -188,10 +225,21 @@ You can query by trace ID, or use the search form to find traces.
| **Service** | Returns a list of services. |
| **Operation** | Populated when you select a service with related operations. Select `All` to query all operations. |
| **Tags** | Sets tags with values in the [logfmt](https://brandur.org/logfmt) format, such as `error=true db.statement="select * from User"`. |
| **Min Duration** | Filters all traces with a duration higher than the set value. Valid values are `1.2s, 100ms, 500us`. |
| **Max Duration** | Filters all traces with a duration lower than the set value. Valid values are `1.2s, 100ms, 500us`. |
| **Min Duration** | Filters all traces with a duration higher than the set value. Possible values are `1.2s, 100ms, 500us`. |
| **Max Duration** | Filters all traces with a duration lower than the set value. Possible values are `1.2s, 100ms, 500us`. |
| **Limit** | Limits the number of traces returned. |
{{< figure src="/static/img/docs/explore/jaeger-search-form.png" class="docs-image--no-shadow" caption="Screenshot of the Jaeger query editor" >}}
### Query by trace ID
To query a particular trace:
1. Select the **TraceID** query type.
1. Enter the trace's ID into the **Trace ID** field.
{{< figure src="/static/img/docs/explore/jaeger-trace-id.png" class="docs-image--no-shadow" caption="Screenshot of the Jaeger query editor with TraceID selected" >}}
## Upload a JSON trace file
You can upload a JSON file that contains a single trace and visualize it.
@@ -249,8 +297,32 @@ If the file has multiple traces, Grafana visualizes its first trace.
}
```
## Link a trace ID from logs
## Span Filters
You can link to a Jaeger trace from logs in [Loki](/docs/loki/latest/) by configuring a derived field with an internal link.
{{% admonition type="note" %}}
This feature is behind the `newTraceViewHeader` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
For details, refer to [Derived fields]({{< relref "../loki/#configure-derived-fields" >}}) section of the [Loki data source]({{< relref "../loki/" >}}) documentation.
![Screenshot of span filtering](/media/docs/tempo/screenshot-grafana-tempo-span-filters.png)
Using span filters, you can filter your spans in the trace timeline viewer. The more filters you add, the more specific are the filtered spans.
You can add one or more of the following filters:
- Service name
- Span name
- Duration
- Tags (which include tags, process tags, and log fields)
## Link to a trace ID from logs
You can link to Jaeger traces from logs in Loki, Elasticsearch, Splunk, and other logs data sources by configuring an internal link.
To configure this feature, see the [Derived fields]({{< relref "../loki#configure-derived-fields" >}}) section of the Loki data source docs or the [Data links]({{< relref "../elasticsearch#data-links" >}}) section of the Elasticsearch or Splunk data source docs.
## Link to a trace ID from metrics
You can link to Jaeger traces from metrics in Prometheus data sources by configuring an exemplar.
To configure this feature, see the [introduction to exemplars]({{< relref "docs/grafana/latest/fundamentals/exemplars" >}}) documentation.
docs/sources/datasources/loki/_index.md
+6 -2
View File
@@ -42,7 +42,9 @@ Set the data source's basic configuration options carefully:
| **Allowed cookies** | Defines which cookies are forwarded to the data source. Grafana Proxy deletes all other cookies. |
| **Maximum lines** | Sets the upper limit for the number of log lines returned by Loki. Defaults to 1,000. Lower this limit if your browser is sluggish when displaying logs in Explore. |
> **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 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 %}}
### Configure derived fields
@@ -54,7 +56,9 @@ The **Derived Fields** configuration helps you:
For example, you can link to your tracing backend directly from your logs, or link to a user profile page if the log line contains a corresponding userId.
These links appear in the [log details]({{< relref "../../explore/logs-integration/#labels-and-detected-fields" >}}).
> **Note:** If you use Grafana Cloud, you can request modifications to this feature by [opening a support ticket in the Cloud Portal](/profile/org#support).
{{% admonition type="note" %}}
If you use Grafana Cloud, you can request modifications to this feature by [opening a support ticket in the Cloud Portal](/profile/org#support).
{{% /admonition %}}
Each derived field consists of:
docs/sources/datasources/loki/query-editor/index.md
+6 -2
View File
@@ -30,7 +30,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.
> **Note:** To run Loki queries in [Explore]({{< relref "../../../explore/" >}}), select **Run query**.
{{% admonition type="note" %}}
To run Loki queries in [Explore]({{< relref "../../../explore/" >}}), select **Run query**.
{{% /admonition %}}
Each mode is synchronized with the other modes, so you can switch between them without losing your work, although there are some limitations.
@@ -206,7 +208,9 @@ In your `server` section, add the following configuration:
}
```
> **Note:** Available in Grafana v6.3 and higher.
{{% admonition type="note" %}}
Available in Grafana v6.3 and higher.
{{% /admonition %}}
## Create a metric query
docs/sources/datasources/mysql/_index.md
+3 -1
View File
@@ -118,7 +118,9 @@ The response from MySQL can be formatted as either a table or as a time series.
### Dataset and Table selection
> **Note:** If your table or database name contains a reserved word or a [not permitted character](https://dev.mysql.com/doc/refman/8.0/en/identifiers.html) the editor will put quotes around them. For example a table name like `table-name` will be quoted with backticks `` `table-name` ``.
{{% admonition type="note" %}}
If your table or database name contains a reserved word or a [not permitted character](https://dev.mysql.com/doc/refman/8.0/en/identifiers.html) the editor will put quotes around them. For example a table name like `table-name` will be quoted with backticks `` `table-name` ``.
{{% /admonition %}}
In the dataset dropdown, choose the MySQL database to query. The dropdown is be populated with the databases that the user has access to.
When the dataset is selected, the table dropdown is populated with the tables that are available.
docs/sources/datasources/opentsdb/_index.md
+3 -1
View File
@@ -64,7 +64,9 @@ can be used to query opentsdb. Fill Policy is also introduced in OpenTSDB 2.2.
![](/static/img/docs/v43/opentsdb_query_editor.png)
> **Note:** 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 type="note" %}}
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 %}}
### Auto complete suggestions
docs/sources/datasources/postgres/_index.md
+3 -1
View File
@@ -138,7 +138,9 @@ datasources:
timescaledb: false
```
> **Note:** In the above code, the `postgresVersion` value of `10` refers to version PostgreSQL 10 and above.
{{% admonition type="note" %}}
In the above code, the `postgresVersion` value of `10` refers to version PostgreSQL 10 and above.
{{% /admonition %}}
#### Troubleshoot provisioning
docs/sources/datasources/prometheus/_index.md
+6 -2
View File
@@ -123,7 +123,9 @@ For details on AWS SigV4, refer to the [AWS documentation](https://docs.aws.amaz
#### AWS Signature Version 4 authentication
> **Note:** Available in Grafana v7.3.5 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.3.5 and higher.
{{% /admonition %}}
To connect the Prometheus data source to Amazon Managed Service for Prometheus using SigV4 authentication, refer to the AWS guide to [Set up Grafana open source or Grafana Enterprise for use with AMP](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-onboard-query-standalone-grafana.html).
@@ -131,7 +133,9 @@ If you run Grafana in an Amazon EKS cluster, follow the AWS guide to [Query usin
### Configure exemplars
> **Note:** Available in Prometheus v2.26 and higher with Grafana v7.4 and higher.
{{% admonition type="note" %}}
Available in Prometheus v2.26 and higher with Grafana v7.4 and higher.
{{% /admonition %}}
Grafana 7.4 and higher can show exemplars data alongside a metric both in Explore and in Dashboards.
Exemplars associate higher-cardinality metadata from a specific event with traditional time series data.
docs/sources/datasources/prometheus/query-editor/index.md
+7 -3
View File
@@ -85,8 +85,10 @@ The **Type** setting selects the query type.
- An **Exemplars** query runs with the regular query and shows exemplars in the graph.
> **Note:** Grafana modifies the request dates for queries to align them with the dynamically calculated step.
> This ensures a consistent display of metrics data, but it can result in a small gap of data at the right edge of a graph.
{{% admonition type="note" %}}
Grafana modifies the request dates for queries to align them with the dynamically calculated step.
This ensures a consistent display of metrics data, but it can result in a small gap of data at the right edge of a graph.
{{% /admonition %}}
## Code mode
@@ -118,7 +120,9 @@ When you select a metric, the browser narrows down the available labels to show
You can then select one or more labels for which the available label values are shown in lists in the bottom section.
Select one or more values for each label to tighten your query scope.
> **Note:** If you do not remember a metric name to start with, you can also select a few labels to narrow down the list, then find relevant label values.
{{% admonition type="note" %}}
If you do not remember a metric name to start with, you can also select a few labels to narrow down the list, then find relevant label values.
{{% /admonition %}}
All lists in the metrics browser have a search field above them to quickly filter for metrics or labels that match a certain string.
The values section has only one search field, and its filtering applies to all labels to help you find values across labels once selected.
docs/sources/datasources/prometheus/template-variables/index.md
+3 -1
View File
@@ -63,7 +63,9 @@ Regex:
## Use `$__rate_interval`
> **Note:** Available in Grafana v7.2 and higher.
{{% admonition type="note" %}}
Available in Grafana v7.2 and higher.
{{% /admonition %}}
We recommend using `$__rate_interval` in the `rate` and `increase` functions instead of `$__interval` or a fixed interval value.
Because `$__rate_interval` is always at least four times the value of the Scrape interval, it avoid problems specific to Prometheus.
docs/sources/datasources/tempo/_index.md
+152 -91
View File
@@ -15,7 +15,7 @@ weight: 1400
# Tempo data source
Grafana ships with built-in support for Tempo, a high-volume, minimal-dependency trace storage, open-source tracing solution from Grafana Labs.
Grafana ships with built-in support for [Tempo](https://grafana.com/docs/tempo/latest/), a high-volume, minimal-dependency trace storage, open-source tracing solution from Grafana Labs. This topic explains configuration and queries specific to the Tempo data source.
For instructions on how to add a data source to Grafana, refer to the [administration documentation]({{< relref "../../administration/data-source-management/" >}}).
Only users with the organization administrator role can add data sources.
@@ -23,92 +23,103 @@ Administrators can also [configure the data source via YAML]({{< relref "#provis
Once you've added the data source, you can [configure it]({{< relref "#configure-the-data-source" >}}) so that your Grafana instance's users can create queries in its [query editor]({{< relref "./query-editor/" >}}) when they [build dashboards]({{< relref "../../dashboards/build-dashboards/" >}}) and use [Explore]({{< relref "../../explore/" >}}).
You can also [use the service graph]({{< relref "#use-the-service-graph" >}}) to view service relationships, [track RED metrics]({{< relref "#open-the-service-graph-view" >}}), [upload a JSON trace file]({{< relref "#upload-a-json-trace-file" >}}), and [link a trace ID from logs]({{< relref "#link-a-trace-id-from-logs" >}}) in Loki or Elasticsearch.
You can also [use the Service Graph]({{< relref "#use-the-service-graph" >}}) to view service relationships, [track RED metrics]({{< relref "#open-the-service-graph-view" >}}), [upload a JSON trace file]({{< relref "#upload-a-json-trace-file" >}}), [link to a trace ID from logs]({{< relref "#link-to-a-trace-id-from-logs" >}}), and [link to a trace ID from metrics]({{< relref "#link-to-a-trace-id-from-metrics" >}}).
## Configure the data source
**To access the data source configuration page:**
To configure basic settings for the data source, complete the following steps:
1. Hover the cursor over the **Configuration** (gear) icon.
1. Select **Data Sources**.
1. Select the Tempo data source.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `Tempo` in the search bar.
1. Select **Tempo**.
Set the data source's basic configuration options carefully:
The **Settings** tab of the data source is displayed.
| Name | Description |
| -------------- | ------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Sets the data source that's pre-selected for new panels. |
| **URL** | Sets the URL of the Tempo instance, such as `http://tempo`. |
| **Basic Auth** | Enables basic authentication to the Tempo data source. |
| **User** | Sets the user name for basic authentication. |
| **Password** | Sets the password for basic authentication. |
1. Set the data source's basic configuration options:
You can also configure settings specific to the Tempo data source:
| Name | Description |
| -------------- | ------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Sets the data source that's pre-selected for new panels. |
| **URL** | Sets the URL of the Tempo instance, such as `http://tempo`. |
| **Basic Auth** | Enables basic authentication to the Tempo data source. |
| **User** | Sets the user name for basic authentication. |
| **Password** | Sets the password for basic authentication. |
### Configure trace to logs
You can also configure settings specific to the Tempo data source. These options are described in the sections below.
### Trace to logs
![Trace to logs settings](/media/docs/tempo/tempo-trace-to-logs-9-4.png)
> **Note:** Available in Grafana v7.4 and higher.
> If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% admonition type="note" %}}
Available in Grafana v7.4 and higher.
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
The **Trace to logs** setting configures the [trace to logs feature]({{< relref "../../explore/trace-integration" >}}) that is available when you integrate Grafana with Tempo.
There are two ways to configure the trace to logs feature. You can use simplified configuration with default query, or you can configure custom query where you can use a [template language]({{< relref "../../dashboards/variables/variable-syntax">}}) to interpolate variables from the trace or span.
There are two ways to configure the trace to logs feature:
**To use simple configuration:**
- Use a simplified configuration with default query, or
- Configure a custom query where you can use a [template language]({{< relref "../../dashboards/variables/variable-syntax">}}) to interpolate variables from the trace or span.
#### Use a simple configuration
1. Select the target data source.
1. Set start and end time shift. As the logs timestamps may not exactly match the timestamps of the spans in trace it may be necessary to search in larger or shifted time range to find the desired logs.
1. Select which tags to use in the logs query. The tags you configure must be present in the spans attributes or resources for a trace to logs span link to appear. You can optionally configure a new name for the tag. This is useful for example if the tag has dots in the name and the target data source does not allow using dots in labels. In that case you can for example remap `http.status` to `http_status`.
1. Optionally switch on Filter by Trace ID and/or Filter by Span ID to further filter the logs if your logs consistently contain trace or span IDs.
1. Optionally switch on the **Filter by trace ID** and/or **Filter by span ID** setting to further filter the logs if your logs consistently contain trace or span IDs.
**To use custom query configuration:**
#### Configure a custom query
1. Select the target data source.
1. Set start and end time shift. As the logs timestamps may not exactly match the timestamps of the spans in the trace it may be necessary to widen or shift the time range to find the desired logs.
1. Optionally select tags to map. These tags can be used in the custom query with `${__tags}` variable. This variable will interpolate the mapped tags as list in an appropriate syntax for the data source and will only include the tags that were present in the span omitting those that weren't present. You can optionally configure a new name for the tag. This is useful in cases where the tag has dots in the name and the target data source does not allow using dots in labels. For example, you can remap `http.status` to `http_status` in such a case. If you don't map any tags here, you can still use any tag in the query like this `method="${__span.tags.method}"`.
1. Skip Filter by Trace ID or Filter by Span ID as these cannot be used with custom query.
1. Switch on Use custom query.
1. Specify custom query to be used to query the logs. You can use various variables to make that query relevant for current span. The link will only be shown only if all the variables are interpolated with non-empty values to prevent creating invalid query.
1. Skip **Filter by trace ID** and **Filter by span ID** settings as these cannot be used with a custom query.
1. Switch on **Use custom query**.
1. Specify a custom query to be used to query the logs. You can use various variables to make that query relevant for current span. The link will only be shown only if all the variables are interpolated with non-empty values to prevent creating an invalid query.
#### Variables that can be used in a custom query
**Variables that can be used in custom query**
To use a variable you need to wrap it in `${}`. For example `${__span.name}`.
| Variable name | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| \_\_tags | This variable is special because it uses the tag mapping in from the UI to create a label matcher string in the specific data source syntax. It uses only tags that are present in the span so the link will still be created even if only one of those tags is present in the span. You can use this if not all the tags are required for the query to be useful. |
| \_\_span.spanId | The ID of the span. |
| \_\_span.traceId | The ID of the trace. |
| \_\_span.duration | The duration of the span. |
| \_\_span.name | Name of the span. |
| \_\_span.tags | Namespace for the tags in the span. To access a specific tag named "version" you would use `${__span.tags.version}`. In case the tag contains dot you have to access it as `${__span.tags["http.status"]}`. |
| \_\_trace.traceId | The ID of the trace. |
| \_\_trace.duration | The duration of the trace. |
| \_\_trace.name | The name of the trace. |
| Variable name | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\_\_tags** | This variable uses the tag mapping from the UI to create a label matcher string in the specific data source syntax. The variable only uses tags that are present in the span. The link is still created even if only one of those tags is present in the span. You can use this if all tags are not required for the query to be useful. |
| **\_\_span.spanId** | The ID of the span. |
| **\_\_span.traceId** | The ID of the trace. |
| **\_\_span.duration** | The duration of the span. |
| **\_\_span.name** | Name of the span. |
| **\_\_span.tags** | Namespace for the tags in the span. To access a specific tag named `version`, you would use `${__span.tags.version}`. In case the tag contains dot, you have to access it as `${__span.tags["http.status"]}`. |
| **\_\_trace.traceId** | The ID of the trace. |
| **\_\_trace.duration** | The duration of the trace. |
| **\_\_trace.name** | The name of the trace. |
The following table describes the ways in which you can configure your trace to logs settings:
| Setting name | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source** | Defines the target data source. You can select only Loki or Splunk \[logs\] data sources. |
| **Span start time shift** | Shifts the start time for the logs query, based on the span's start time. You can use time units, such as `5s`, `1m`, `3h`. To extend the time to the past, use a negative value. Default is 0. |
| **Span end time shift** | Shifts the end time for the logs query, based on the span's end time. You can use time units. Default is 0. |
| **Tags** | Defines the the tags to use in the logs query. Default is `'cluster', 'hostname', 'namespace', 'pod'`. You can change the tag name for example to remove dots from the name if they are not allowed in the target data source. For example map `http.status` to `http_status` |
| **Filter by Trace ID** | Toggles whether to append the trace ID to the logs query. |
| **Filter by Span ID** | Toggles whether to append the span ID to the logs query. |
| **Use custom query** | Toggles use of custom query with interpolation. |
| **Query** | Input to write custom query. Use variable interpolation to customize it with variables from span. |
| Setting name | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source** | Defines the target data source. You can select only Loki or Splunk \[logs\] data sources. |
| **Span start time shift** | Shifts the start time for the logs query, based on the span's start time. You can use time units, such as `5s`, `1m`, `3h`. To extend the time to the past, use a negative value. Default: `0`. |
| **Span end time shift** | Shifts the end time for the logs query, based on the span's end time. You can use time units. Default: `0`. |
| **Tags** | Defines the tags to use in the logs query. Default: `cluster`, `hostname`, `namespace`, `pod`. You can change the tag name for example to remove dots from the name if they are not allowed in the target data source. For example, map `http.status` to `http_status`. |
| **Filter by trace ID** | Toggles whether to append the trace ID to the logs query. |
| **Filter by span ID** | Toggles whether to append the span ID to the logs query. |
| **Use custom query** | Toggles use of custom query with interpolation. |
| **Query** | Input to write custom query. Use variable interpolation to customize it with variables from span. |
### Configure trace to metrics
### Trace to metrics
> **Note:** This feature is behind the `traceToMetrics` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
> If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% admonition type="note" %}}
This feature is behind the `traceToMetrics` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
The **Trace to metrics** setting configures the [trace to metrics feature](/blog/2022/08/18/new-in-grafana-9.1-trace-to-metrics-allows-users-to-navigate-from-a-trace-span-to-a-selected-data-source/) available when integrating Grafana with Tempo.
**To configure trace to metrics:**
To configure trace to metrics:
1. Select the target data source.
1. Create any desired linked queries.
@@ -125,36 +136,48 @@ Each linked query consists of:
Interpolate tags using the `$__tags` keyword.
For example, when you configure the query `requests_total{$__tags}`with the tags `k8s.pod=pod` and `cluster`, the result looks like `requests_total{pod="nginx-554b9", cluster="us-east-1"}`.
### Configure service graph
### Service Graph
The **Service Graph** section configures the [Service Graph](/docs/tempo/latest/grafana-agent/service-graphs/) feature.
The **Service Graph** setting configures the [Service Graph](/docs/tempo/latest/grafana-agent/service-graphs/) feature.
Configure the **Data source** setting to define in which Prometheus instance the Service Graph data is stored.
To use the service graph, refer to the [Service graph section]({{< relref "#use-the-service-graph" >}}).
To use the Service Graph, refer to the [Service Graph documentation]({{< relref "#use-the-service-graph" >}}).
### Configure Tempo search integration
### Node Graph
The **Search** section configures [Tempo search](/docs/tempo/latest/configuration/#search).
The **Node Graph** setting enables the [node graph visualization]({{< relref "../../panels-visualizations/visualizations/node-graph/" >}}), which is disabled by default.
Optionally configure the **Hide search** setting to hide the search query option in Explore if search is not configured in the Tempo instance.
Once enabled, Grafana displays the node graph above the trace view.
### Enable Node Graph
### Tempo search
The **Node Graph** setting enables the [Node Graph visualization]({{< relref "../../panels-visualizations/visualizations/node-graph/" >}}), which is disabled by default.
The **Search** setting configures [Tempo search](/docs/tempo/latest/configuration/#search).
Once enabled, Grafana displays the Node Graph after loading the trace view.
You can configure the **Hide search** setting to hide the search query option in **Explore** if search is not configured in the Tempo instance.
### Configure Loki search
### Loki search
The **Loki search** section configures the Loki search query type.
The **Loki search** setting configures the Loki search query type.
Configure the **Data source** setting to define which Loki instance you want to use to search traces.
You must configure [derived fields]({{< relref "../loki#configure-derived-fields" >}}) in the Loki instance.
### Span bar label
### TraceID query
The **Span bar label** section helps you display additional information in the span bar row.
The **TraceID query** setting modifies how TraceID queries are run. The time range can be used when there are performance issues or timeouts since it will narrow down the search to the defined range. This setting is disabled by default.
You can configure this setting as follows:
| Name | Description |
| --------------------- | ----------------------------------------------------------- |
| **Enable time range** | Use a time range in the TraceID query. Default: `disabled`. |
| **Time shift start** | Time shift for start of search. Default: `30m`. |
| **Time shift end** | Time shift for end of search. Default: `30m`. |
### Span bar
The **Span bar** setting helps you display additional information in the span bar row.
You can choose one of three options:
@@ -167,9 +190,9 @@ You can choose one of three options:
### Provision the data source
You can define and configure the Tempo data source in YAML files as part of Grafana's provisioning system.
For more information about provisioning, and for available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning/#data-sources" >}}).
For more information about provisioning and available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning/#data-sources" >}}).
#### Provisioning examples
#### Provisioning example
```yaml
apiVersion: 1
@@ -177,34 +200,45 @@ apiVersion: 1
datasources:
- name: Tempo
type: tempo
# Access mode - proxy (server in the UI) or direct (browser in the UI).
access: proxy
uid: EbPG8fYoz
url: http://localhost:3200
access: proxy
basicAuth: false
jsonData:
httpMethod: GET
tracesToLogs:
tracesToLogsV2:
# Field with an internal link pointing to a logs data source in Grafana.
# datasourceUid value must match the uid value of the logs data source.
datasourceUid: 'loki'
tags: ['job', 'instance', 'pod', 'namespace']
mappedTags: [{ key: 'service.name', value: 'service' }]
mapTagNamesEnabled: false
spanStartTimeShift: '1h'
spanEndTimeShift: '1h'
spanEndTimeShift: '-1h'
tags: ['job', 'instance', 'pod', 'namespace']
filterByTraceID: false
filterBySpanID: false
customQuery: true
query: 'method="${__span.tags.method}"'
tracesToMetrics:
datasourceUid: 'prom'
spanStartTimeShift: '1h'
spanEndTimeShift: '-1h'
tags: [{ key: 'service.name', value: 'service' }, { key: 'job' }]
queries:
- name: 'Sample query'
query: 'sum(rate(traces_spanmetrics_latency_bucket{$__tags}[5m]))'
serviceMap:
datasourceUid: 'prometheus'
search:
hide: false
nodeGraph:
enabled: true
search:
hide: false
lokiSearch:
datasourceUid: 'loki'
traceQuery:
timeShiftEnabled: true
spanStartTimeShift: '1h'
spanEndTimeShift: '-1h'
spanBar:
type: 'Tag'
tag: 'http.path'
```
## Query the data source
@@ -218,11 +252,11 @@ For details, refer to the [query editor documentation]({{< relref "./query-edito
You can upload a JSON file that contains a single trace and visualize it.
If the file has multiple traces, Grafana visualizes its first trace.
**To download a trace or service graph through the inspector:**
**To download a trace or Service Graph through the inspector:**
1. Open the inspector.
1. Navigate to the **Data** tab.
1. Click **Download traces** or **Download service graph**.
1. Click **Download traces** or **Download Service Graph**.
### Trace JSON example
@@ -268,18 +302,18 @@ If the file has multiple traces, Grafana visualizes its first trace.
}
```
## Use the service graph
## Use the Service Graph
A service graph is a visual representation of the relationships between services.
The Service Graph is a visual representation of the relationships between services.
Each node on the graph represents a service such as an API or database.
You use a service graph to detect performance issues; track increases in error, fault, or throttle rates in services; and investigate root causes by viewing corresponding traces.
You use the Service Graph to detect performance issues; track increases in error, fault, or throttle rates in services; and investigate root causes by viewing corresponding traces.
{{< figure src="/static/img/docs/node-graph/node-graph-8-0.png" class="docs-image--no-shadow" max-width="500px" caption="Screenshot of a Node Graph" >}}
**To display the service graph:**
**To display the Service Graph:**
1. [Configure Grafana Agent](/docs/tempo/latest/grafana-agent/service-graphs/#quickstart) or [Tempo or GET](/docs/tempo/latest/metrics-generator/service_graphs/#tempo) to generate service graph data.
1. [Configure Grafana Agent](/docs/tempo/latest/grafana-agent/service-graphs/#quickstart) or [Tempo or GET](/docs/tempo/latest/metrics-generator/service_graphs/#tempo) to generate Service Graph data.
1. Link a Prometheus data source in the Tempo data source's [Service Graph](#configure-service-graph) settings.
1. Navigate to [Explore]({{< relref "../../explore/" >}}).
1. Select the Tempo data source.
@@ -307,7 +341,7 @@ Each circle's color represents the percentage of requests in each state:
Service graph view displays a table of request rate, error rate, and duration metrics (RED) calculated from your incoming spans. It also includes a node graph view built from your spans.
{{< figure src="/static/img/docs/tempo/apm-table.png" class="docs-image--no-shadow" max-width="500px" caption="Screenshot of the Service Graph view table" >}}
{{< figure src="/static/img/docs/tempo/apm-table.png" class="docs-image--no-shadow" max-width="500px" caption="Screenshot of the Service Graph view" >}}
For details, refer to the [Service Graph view documentation](/docs/tempo/latest/metrics-generator/service-graph-view/).
@@ -316,18 +350,45 @@ To open the Service Graph view:
1. Link a Prometheus data source in the Tempo data source settings.
1. Navigate to [Explore]({{< relref "../../explore/" >}}).
1. Select the Tempo data source.
1. Select the **Service Graph** query type and run the query.
1. Select the **Service Graph** query type.
1. Run the query.
1. _(Optional)_ Filter your results.
> **Note:** Grafana uses the `traces_spanmetrics_calls_total` metric to display the name, rate, and error rate columns, and `traces_spanmetrics_latency_bucket` to display the duration column.
> These metrics must exist in your Prometheus data source.
{{% admonition type="note" %}}
Grafana uses the `traces_spanmetrics_calls_total` metric to display the name, rate, and error rate columns, and `traces_spanmetrics_latency_bucket` to display the duration column.
These metrics must exist in your Prometheus data source.
{{% /admonition %}}
To open a query in Prometheus with the span name of that row automatically set in the query, click a row in the **rate**, **error rate**, or **duration** columns.
To open a query in Tempo with the span name of that row automatically set in the query, click a row in the **links** column.
## Link a trace ID from logs
## Span Filters
You can link to Tempo trace from logs in [Loki](/docs/loki/latest) or Elasticsearch by configuring an internal link.
{{% admonition type="note" %}}
This feature is behind the `newTraceViewHeader` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
To configure this feature, see the [Derived fields]({{< relref "../loki#configure-derived-fields" >}}) section of the [Loki data source docs]({{< relref "../loki/" >}}), or the [Data links]({{< relref "../elasticsearch#data-links" >}}) section of the [Elasticsearch data source docs]({{< relref "../elasticsearch" >}}).
![Screenshot of span filtering](/media/docs/tempo/screenshot-grafana-tempo-span-filters.png)
Using span filters, you can filter your spans in the trace timeline viewer. The more filters you add, the more specific are the filtered spans.
You can add one or more of the following filters:
- Service name
- Span name
- Duration
- Tags (which include tags, process tags, and log fields)
## Link to a trace ID from logs
You can link to Tempo traces from logs in Loki, Elasticsearch, Splunk, and other logs data sources by configuring an internal link.
To configure this feature, see the [Derived fields]({{< relref "../loki#configure-derived-fields" >}}) section of the Loki data source docs or the [Data links]({{< relref "../elasticsearch#data-links" >}}) section of the Elasticsearch or Splunk data source docs.
## Link to a trace ID from metrics
You can link to Tempo traces from metrics in Prometheus data sources by configuring an exemplar.
To configure this feature, see the [introduction to exemplars]({{< relref "docs/grafana/latest/fundamentals/exemplars" >}}) documentation.
docs/sources/datasources/zipkin/_index.md
+172 -50
View File
@@ -15,73 +15,112 @@ weight: 1600
# Zipkin data source
Grafana ships with built-in support for Zipkin, an open source, distributed tracing system.
Grafana ships with built-in support for Zipkin, an open source, distributed tracing system. This topic explains configuration and queries specific to the Zipkin data source.
For instructions on how to add a data source to Grafana, refer to the [administration documentation]({{< relref "../../administration/data-source-management/" >}}).
Only users with the organization administrator role can add data sources.
Administrators can also [configure the data source via YAML]({{< relref "#provision-the-data-source" >}}) with Grafana's provisioning system.
Once you've added the Zipkin data source, you can [configure it]({{< relref "#configure-the-data-source" >}}) so that your Grafana instance's users can create queries in its [query editor]({{< relref "#query-traces" >}}) when they [build dashboards]({{< relref "../../dashboards/build-dashboards/" >}}) and use [Explore]({{< relref "../../explore/" >}}).
Once you've added the Zipkin data source, you can [configure it]({{< relref "#configure-the-data-source" >}}) so that your Grafana instance's users can create queries in its [query editor]({{< relref "#query-the-data-source" >}}) when they [build dashboards]({{< relref "../../dashboards/build-dashboards/" >}}) and use [Explore]({{< relref "../../explore/" >}}).
You can also [upload a JSON trace file]({{< relref "#upload-a-json-trace-file" >}}), [link to a trace ID from logs]({{< relref "#link-to-a-trace-id-from-logs" >}}), and [link to a trace ID from metrics]({{< relref "#link-to-a-trace-id-from-metrics" >}}).
## Configure the data source
**To access the data source configuration page:**
To configure basic settings for the data source, complete the following steps:
1. Hover the cursor over the **Configuration** (gear) icon.
1. Select **Data Sources**.
1. Select the Zipkin data source.
1. Click **Connections** in the left-side menu.
1. Under Your connections, click **Data sources**.
1. Enter `Zipkin` in the search bar.
1. Select **Zipkin**.
Set the data source's basic configuration options carefully:
The **Settings** tab of the data source is displayed.
| Name | Description |
| -------------- | ------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Defines whether this data source is pre-selected for new panels. |
| **URL** | Sets the URL of the Zipkin instance, such as `http://localhost:9411`. |
| **Basic Auth** | Enables basic authentication for the Zipkin data source. |
| **User** | Defines the user name for basic authentication. |
| **Password** | Defines the password for basic authentication. |
1. Set the data source's basic configuration options:
### Configure trace to logs
| Name | Description |
| -------------- | ------------------------------------------------------------------------ |
| **Name** | Sets the name you use to refer to the data source in panels and queries. |
| **Default** | Defines whether this data source is pre-selected for new panels. |
| **URL** | Sets the URL of the Zipkin instance, such as `http://localhost:9411`. |
| **Basic Auth** | Enables basic authentication for the Zipkin data source. |
| **User** | Defines the user name for basic authentication. |
| **Password** | Defines the password for basic authentication. |
{{< figure src="/static/img/docs/explore/traces-to-logs-settings-8-2.png" class="docs-image--no-shadow" caption="Screenshot of the trace to logs settings" >}}
### Trace to logs
> **Note:** Available in Grafana v7.4 and higher.
![Trace to logs settings](/media/docs/tempo/tempo-trace-to-logs-9-4.png)
{{% admonition type="note" %}}
Available in Grafana v7.4 and higher.
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
The **Trace to logs** setting configures the [trace to logs feature]({{< relref "../../explore/trace-integration" >}}) that is available when you integrate Grafana with Zipkin.
**To configure trace to logs:**
There are two ways to configure the trace to logs feature:
- Use a simplified configuration with default query, or
- Configure a custom query where you can use a [template language]({{< relref "../../dashboards/variables/variable-syntax">}}) to interpolate variables from the trace or span.
#### Use a simple configuration
1. Select the target data source.
1. Select which tags to use in the logs query. The tags you configure must be present in the spans attributes or resources for a trace to logs span link to appear.
1. Set start and end time shift. As the logs timestamps may not exactly match the timestamps of the spans in trace it may be necessary to search in larger or shifted time range to find the desired logs.
1. Select which tags to use in the logs query. The tags you configure must be present in the spans attributes or resources for a trace to logs span link to appear. You can optionally configure a new name for the tag. This is useful if the tag has dots in the name and the target data source does not allow using dots in labels. In that case, you can for example remap `http.status` to `http_status`.
1. Optionally, switch on the **Filter by trace ID** and/or **Filter by span ID** setting to further filter the logs if your logs consistently contain trace or span IDs.
- **Single tag**
- Configuring `job` as a tag and clicking on a span link will take you to your configured logs datasource with the query `{job='value from clicked span'}`.
- **Multiple tags**
- If multiple tags are used they will be concatenated so the logs query would look like `{job='value from clicked span', service='value from clicked span'}`.
- **Mapped tags**
- For a mapped tag `service.name` with value `service`, clicking on a span link will take you to your configured logs datasource with the query `{service='value from clicked span'}` instead of `{service.name='value from clicked span'}`.
- This is useful for instances where your tracing datasource tags and your logs datasource tags don't match one-to-one.
#### Configure a custom query
1. Select the target data source.
1. Set start and end time shift. Since the logs timestamps may not exactly match the timestamps of the spans in the trace, you may need to widen or shift the time range to find the desired logs.
1. Optionally, select tags to map. These tags can be used in the custom query with `${__tags}` variable. This variable will interpolate the mapped tags as list in an appropriate syntax for the data source and will only include the tags that were present in the span omitting those that weren't present. You can optionally configure a new name for the tag. This is useful when the tag has dots in the name and the target data source does not allow using dots in labels. For example, you can remap `http.status` to `http_status`. If you don't map any tags here, you can still use any tag in the query like this `method="${__span.tags.method}"`.
1. Skip **Filter by trace ID** and **Filter by span ID** settings as these cannot be used with a custom query.
1. Switch on **Use custom query**.
1. Specify a custom query to be used to query the logs. You can use various variables to make that query relevant for current span. The link will only be shown only if all the variables are interpolated with non-empty values to prevent creating an invalid query.
#### Variables that can be used in a custom query
To use a variable you need to wrap it in `${}`. For example `${__span.name}`.
| Variable name | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\_\_tags** | This variable uses the tag mapping from the UI to create a label matcher string in the specific data source syntax. The variable only uses tags that are present in the span. The link is still created even if only one of those tags is present in the span. You can use this if all tags are not required for the query to be useful. |
| **\_\_span.spanId** | The ID of the span. |
| **\_\_span.traceId** | The ID of the trace. |
| **\_\_span.duration** | The duration of the span. |
| **\_\_span.name** | Name of the span. |
| **\_\_span.tags** | Namespace for the tags in the span. To access a specific tag named `version`, you would use `${__span.tags.version}`. In case the tag contains dot, you have to access it as `${__span.tags["http.status"]}`. |
| **\_\_trace.traceId** | The ID of the trace. |
| **\_\_trace.duration** | The duration of the trace. |
| **\_\_trace.name** | The name of the trace. |
The following table describes the ways in which you can configure your trace to logs settings:
| Name | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source** | Sets the target data source. |
| **Tags** | Defines the tags to use in the logs query. Default is `'cluster', 'hostname', 'namespace', 'pod'`. |
| **Map tag names** | Enables configuring how Jaeger tag names map to logs label names. For example, map `service.name` to `service`. |
| **Span start time shift** | Shifts the start time for the logs query based on the span start time. To extend to the past, use a negative value. Use time interval units like `5s`, `1m`, `3h`. Default is `0`. |
| **Span end time shift** | Shifts the end time for the logs query based on the span end time. Use time interval units. Default is `0`. |
| **Filter by Trace ID** | Toggles whether to append the trace ID to the logs query. |
| **Filter by Span ID** | Toggles whether to append the span ID to the logs query. |
| Setting name | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Data source** | Defines the target data source. You can select only Loki or Splunk \[logs\] data sources. |
| **Span start time shift** | Shifts the start time for the logs query, based on the span's start time. You can use time units, such as `5s`, `1m`, `3h`. To extend the time to the past, use a negative value. Default: `0`. |
| **Span end time shift** | Shifts the end time for the logs query, based on the span's end time. You can use time units. Default: `0`. |
| **Tags** | Defines the tags to use in the logs query. Default: `cluster`, `hostname`, `namespace`, `pod`. You can change the tag name for example to remove dots from the name if they are not allowed in the target data source. For example, map `http.status` to `http_status`. |
| **Filter by trace ID** | Toggles whether to append the trace ID to the logs query. |
| **Filter by span ID** | Toggles whether to append the span ID to the logs query. |
| **Use custom query** | Toggles use of custom query with interpolation. |
| **Query** | Input to write custom query. Use variable interpolation to customize it with variables from span. |
### Configure trace to metrics
### Trace to metrics
> **Note:** This feature is behind the `traceToMetrics` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
{{% admonition type="note" %}}
This feature is behind the `traceToMetrics` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
The **Trace to metrics** section configures the [trace to metrics feature](/blog/2022/08/18/new-in-grafana-9.1-trace-to-metrics-allows-users-to-navigate-from-a-trace-span-to-a-selected-data-source/).
The **Trace to metrics** setting configures the [trace to metrics feature](/blog/2022/08/18/new-in-grafana-9.1-trace-to-metrics-allows-users-to-navigate-from-a-trace-span-to-a-selected-data-source/) available when integrating Grafana with Zipkin.
Use the settings to select the target Prometheus data source, and create any desired linked queries.
To configure trace to metrics:
1. Select the target data source.
1. Create any desired linked queries.
| Setting name | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -95,15 +134,15 @@ Each linked query consists of:
Interpolate tags using the `$__tags` keyword.
For example, when you configure the query `requests_total{$__tags}`with the tags `k8s.pod=pod` and `cluster`, the result looks like `requests_total{pod="nginx-554b9", cluster="us-east-1"}`.
### Enable Node Graph
### Node Graph
The **Node Graph** setting enables the [Node Graph visualization]({{< relref "../../panels-visualizations/visualizations/node-graph/" >}}), which is disabled by default.
Once enabled, Grafana displays the Node Graph after loading the trace view.
### Configure the span bar label
### Span bar
The **Span bar label** section helps you display additional information in the span bar row.
The **Span bar** setting helps you display additional information in the span bar row.
You can choose one of three options:
@@ -113,18 +152,75 @@ You can choose one of three options:
| **Duration** | _(Default)_ Displays the span duration on the span bar row. |
| **Tag** | Displays the span tag on the span bar row. You must also specify which tag key to use to get the tag value, such as `span.kind`. |
## Query traces
### Provision the data source
You can define and configure the data source in YAML files as part of Grafana's provisioning system.
For more information about provisioning and available configuration options, refer to [Provisioning Grafana]({{< relref "../../administration/provisioning#data-sources" >}}).
#### Provisioning example
```yaml
apiVersion: 1
datasources:
- name: Zipkin
type: zipkin
uid: EbPG8fYoz
url: http://localhost:16686
access: proxy
basicAuth: true
basicAuthUser: my_user
readOnly: true
isDefault: false
jsonData:
tracesToLogsV2:
# Field with an internal link pointing to a logs data source in Grafana.
# datasourceUid value must match the uid value of the logs data source.
datasourceUid: 'loki'
spanStartTimeShift: '1h'
spanEndTimeShift: '-1h'
tags: ['job', 'instance', 'pod', 'namespace']
filterByTraceID: false
filterBySpanID: false
customQuery: true
query: 'method="${__span.tags.method}"'
tracesToMetrics:
datasourceUid: 'prom'
spanStartTimeShift: '1h'
spanEndTimeShift: '-1h'
tags: [{ key: 'service.name', value: 'service' }, { key: 'job' }]
queries:
- name: 'Sample query'
query: 'sum(rate(traces_spanmetrics_latency_bucket{$__tags}[5m]))'
nodeGraph:
enabled: true
traceQuery:
timeShiftEnabled: true
spanStartTimeShift: '1h'
spanEndTimeShift: '-1h'
spanBar:
type: 'None'
secureJsonData:
basicAuthPassword: my_password
```
## Query the data source
You can query and display traces from Zipkin via [Explore]({{< relref "../../explore/" >}}).
This topic explains configuration and queries specific to the Zipkin data source.
For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../../panels-visualizations/query-transform-data" >}}).
### Query by trace ID
To query a particular trace:
1. Select the **TraceID** query type.
1. Enter the trace's ID into the **Trace ID** field.
{{< figure src="/static/img/docs/v70/zipkin-query-editor.png" class="docs-image--no-shadow" caption="Screenshot of the Zipkin query editor" >}}
To query by trace ID, enter it.
{{< figure src="/static/img/docs/v70/zipkin-query-editor-open.png" class="docs-image--no-shadow" caption="Screenshot of the Zipkin query editor with trace selector expanded" >}}
### Query by trace selector
To select a particular trace from all traces logged in the time range you have selected in Explore, you can also query by trace selector.
The trace selector has three levels of nesting:
@@ -133,6 +229,8 @@ The trace selector has three levels of nesting:
- Particular operation, part of the selected service
- Specific trace in which the selected operation occurred, represented by the root operation name and trace duration
{{< figure src="/static/img/docs/v70/zipkin-query-editor-open.png" class="docs-image--no-shadow" caption="Screenshot of the Zipkin query editor with trace selector expanded" >}}
## View data mapping in the trace UI
You can view Zipkin annotations in the trace view as logs with annotation value displayed under the annotation key.
@@ -168,8 +266,32 @@ If the file has multiple traces, Grafana visualizes its first trace.
]
```
## Link a trace ID from logs
## Span Filters
You can link to a Zipkin trace from logs in [Loki](/docs/loki/latest/) or Splunk by configuring a derived field with an internal link.
{{% admonition type="note" %}}
This feature is behind the `newTraceViewHeader` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
For details, refer to [Derived fields]({{< relref "../loki/#configure-derived-fields" >}}) section of the [Loki data source]({{< relref "../loki/" >}}) documentation.
![Screenshot of span filtering](/media/docs/tempo/screenshot-grafana-tempo-span-filters.png)
Using span filters, you can filter your spans in the trace timeline viewer. The more filters you add, the more specific are the filtered spans.
You can add one or more of the following filters:
- Service name
- Span name
- Duration
- Tags (which include tags, process tags, and log fields)
## Link to a trace ID from logs
You can link to Zipkin traces from logs in Loki, Elasticsearch, Splunk, and other logs data sources by configuring an internal link.
To configure this feature, see the [Derived fields]({{< relref "../loki#configure-derived-fields" >}}) section of the Loki data source docs or the [Data links]({{< relref "../elasticsearch#data-links" >}}) section of the Elasticsearch or Splunk data source docs.
## Link to a trace ID from metrics
You can link to Zipkin traces from metrics in Prometheus data sources by configuring an exemplar.
To configure this feature, see the [introduction to exemplars]({{< relref "docs/grafana/latest/fundamentals/exemplars" >}}) documentation.
docs/sources/developers/angular_deprecation/angular-plugins.md
+676
View File
@@ -0,0 +1,676 @@
---
keywords:
- grafana
- plugins
- plugin
- angular
- deprecation
- migration
title: Plugins using AngularJS
---
The use of AngularJS in Grafana has been [deprecated]({{< relref "../angular_deprecation" >}}) and support for it will be removed in a future release.
This page is to help users of Grafana understand how they might be impacted by the removal of Angular support, and whether a migration option exists.
It lists the latest versions of plugins currently available in the [Plugins Catalog](https://grafana.com/plugins) which depend on Angular, and will stop working when Angular support is removed from Grafana. The list will be updated as more plugins migrate to React or offer migration advice.
{{% admonition type="note" %}}
We advise you to ensure you are running the latest version of plugins, as previous releases of plugins not listed here may still require AngularJS.
{{% /admonition %}}
We also list the year in which the plugin was last updated in the catalog and where appropriate, highlight warnings for plugins where the source repository has not been updated in a number of years and appears inactive. This may help indicate the likelihood of a migration being undertaken, but is informational rather than definitive.
{{% admonition type="note" %}}
Plugins were updated to include signatures in 2021, so whilst a plugin may show as having been updated at that point - the last update to its functionality or dependencies may have been longer ago.
{{% /admonition %}}
## What should I do with the information below?
- Consider the available migration steps.
- Check your Grafana instances for usage of these plugins - see information here on [browsing installed plugins]({{< relref "../../administration/plugin-management/#browse-plugins" >}}).
- Review the project repositories to add your support to any migration issues.
## I'm a plugin author
We are greatly appreciative of the developers who have contributed plugins to the Grafana ecosystem, your work has helped support millions of users to gain insights into their data. A plugin being listed below is no reflection on its quality, and is purely to help users understand the impact of the removal of Angular support in Grafana.
Guidance on migrating a plugin to React can be found in our [migration guide]({{< relref "../plugins/migration-guide/angular-react/" >}}). If you would like to add any specific migration guidance for your plugin here or update our assessment, please open a PR by clicking the `Suggest an edit` button at the bottom of this page.
# Current AngularJS based plugins
## Apps
### [Cloudflare Grafana App](https://grafana.com/grafana/plugins/cloudflare-app/)
Latest Version: 0.2.4 | Signature: Commercial | Last Updated: 2022
### [DevOpsProdigy KubeGraf](https://grafana.com/grafana/plugins/devopsprodigy-kubegraf-app/)
Latest Version: 1.5.2 | Signature: Community | Last Updated: 2021
> **Warning:** [Issues](https://github.com/devopsprodigy/kubegraf/issues/71) in the project repository suggest that the project _may_ be unsupported.
> **Migration available - potential alternative:** Grafana Cloud includes a [Kubernetes integration](https://grafana.com/solutions/kubernetes/).
### [Kentik Connect Pro](https://grafana.com/grafana/plugins/kentik-connect-app/)
Latest Version: 1.6.2 | Signature: Commercial | Last Updated: 2023
## Datasources
### [Druid](https://grafana.com/grafana/plugins/abhisant-druid-datasource/)
Latest Version: v0.0.6 | Signature: Community | Last Updated: 2021
> **Migration available - plugin superseded:** The original plugin only claims support for Grafana v4.x.x, it was replaced with a [new plugin](https://grafana.com/grafana/plugins/grafadruid-druid-datasource/) based on React.
### [Akumuli](https://grafana.com/grafana/plugins/akumuli-datasource/)
Latest Version: 1.3.12 | Signature: Community | Last Updated: 2021
> **Warning:** [Issues](https://github.com/akumuli/Akumuli/issues/379) in the project repository suggest that the project _may_ be unsupported.
> **Warning:** Lack of recent activity in the [project repository](https://github.com/akumuli/Akumuli/) in the past 3 years suggests project _may_ not be actively maintained.
### [DarkSky](https://grafana.com/grafana/plugins/andig-darksky-datasource/)
Latest Version: 1.0.2 | Signature: Community | Last Updated: 2021
> **Warning:** [Project repository](https://github.com/andig/grafana-darksky) was archived on September 27, 2022.
> **Warning:** Apple removed support for the DarkSky API on March 31, 2023 - [source](https://support.apple.com/en-us/HT213526).
### [Finance](https://grafana.com/grafana/plugins/ayoungprogrammer-finance-datasource/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** [Issues](https://github.com/ayoungprogrammer/grafana-finance/issues/7) in the project repository suggest that the project _may_ be unsupported.
> **Warning:** Lack of recent activity in the [project repository](https://github.com/ayoungprogrammer/grafana-finance) in the past 6 years suggests project _may_ not be actively maintained.
### [Prometheus AlertManager](https://grafana.com/grafana/plugins/camptocamp-prometheus-alertmanager-datasource/)
Latest Version: 1.2.1 | Signature: Community | Last Updated: 2022
> **Warning:** Lack of recent activity in the [project repository](https://github.com/camptocamp/grafana-prometheus-alertmanager-datasource) in the past year suggests project _may_ not be actively maintained.
> **Migration available - potential alternative:** Grafana includes an AlertManager data source as a Core plugin.
### [Chaos Mesh](https://grafana.com/grafana/plugins/chaosmeshorg-datasource/)
Latest Version: 2.2.3 | Signature: Community | Last Updated: 2022
> **Warning:** Lack of recent activity in the [project repository](https://github.com/chaos-mesh/datasource) in the past year suggests project _may_ not be actively maintained.
### [Cognite Data Fusion](https://grafana.com/grafana/plugins/cognitedata-datasource/)
Latest Version: 3.0.0 | Signature: Commercial | Last Updated: 2023
### [DeviceHive](https://grafana.com/grafana/plugins/devicehive-devicehive-datasource/)
Latest Version: 2.0.2 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/devicehive/devicehive-grafana-datasource) in the past 5 years suggests project _may_ not be actively maintained.
### [Google BigQuery](https://grafana.com/grafana/plugins/doitintl-bigquery-datasource/)
Latest Version: 2.0.3 | Signature: Community | Last Updated: 2022
> **Migration available - plugin superseded:** Grafana provides its own [Google BigQuery Plugin](https://grafana.com/grafana/plugins/grafana-bigquery-datasource/). The previous [Project repository](https://github.com/doitintl/bigquery-grafana) was archived on December 11, 2022 with a recommendation to migrate to the aforementioned Grafana provided plugin.
### [Open-Falcon](https://grafana.com/grafana/plugins/fastweb-openfalcon-datasource/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** [Project repository](https://github.com/open-falcon/grafana-openfalcon-datasource) suggests support for Grafana v4.2 - Grafana v5.4.
> **Warning:** Lack of recent activity in the [project repository](https://github.com/open-falcon/grafana-openfalcon-datasource) in the past year suggests project _may_ not be actively maintained.
### [GraphQL Data Source](https://grafana.com/grafana/plugins/fifemon-graphql-datasource/)
Latest Version: 1.3.0 | Signature: Community | Last Updated: 2021
> **Warning:** Project support is unclear after a request for new maintainers - [source](https://github.com/fifemon/graphql-datasource/issues/77).
> **Migration available - potential alternative:** The [Infinity](https://grafana.com/grafana/plugins/yesoreyeram-infinity-datasource/) data source supports GraphQL.
### [Cloudera Manager](https://grafana.com/grafana/plugins/foursquare-clouderamanager-datasource/)
Latest Version: 0.9.3 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/foursquare/datasource-plugin-clouderamanager) in the past 7 years suggests project _may_ not be actively maintained.
### [Simple Annotations](https://grafana.com/grafana/plugins/fzakaria-simple-annotations-datasource/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** Plugin only claims support for Grafana v4.x.x.
> **Warning:** Lack of recent activity in the [project repository](https://github.com/fzakaria/simple-annotations-plugin/) in the past 6 years suggests project _may_ not be actively maintained.
> **Warning:** Developer no longer maintains the project, but is open to contributions: https://github.com/fzakaria/simple-annotations-plugin/issues/2
### [Gnocchi](https://grafana.com/grafana/plugins/gnocchixyz-gnocchi-datasource/)
Latest Version: 1.7.1 | Signature: Community | Last Updated: 2021
> **Warning:** Plugin only claims support for Grafana v4.x.x
> **Warning:** Lack of recent activity in the [project repository](https://github.com/gnocchixyz/grafana-gnocchi-datasource) in the past 3 years suggests project _may_ not be actively maintained.
### [MetaQueries](https://grafana.com/grafana/plugins/goshposh-metaqueries-datasource/)
Latest Version: 0.0.9 | Signature: Community | Last Updated: 2022
> **Warning:** Lack of recent activity in the [project repository](https://github.com/GoshPosh/grafana-meta-queries) in the past year suggests project _may_ not be actively maintained.
### [Open Distro for Elasticsearch](https://grafana.com/grafana/plugins/grafana-es-open-distro-datasource/)
Latest Version: 1.0.6 | Signature: Grafana | Last Updated: 2021
> **Migration available - plugin superseded:** Plugin was deprecated in favour of the [OpenSearch Plugin](https://grafana.com/grafana/plugins/grafana-opensearch-datasource/).
### [KairosDB](https://grafana.com/grafana/plugins/grafana-kairosdb-datasource/)
Latest Version: 3.0.2 | Signature: Grafana | Last Updated: 2021
> **Warning:** [Project repository](https://github.com/grafana/kairosdb-datasource) was archived on August 30th, 2021 and is no longer maintained.
### [SimpleJson](https://grafana.com/grafana/plugins/grafana-simple-json-datasource/)
Latest Version: 1.4.2 | Signature: Grafana | Last Updated: 2021
> **Migration available - potential alternative:** [Project repository](https://github.com/grafana/simple-json-datasource) is no longer maintained, but a number of alternatives exist, including - [Infinity](https://grafana.com/grafana/plugins/yesoreyeram-infinity-datasource/), [JSON](https://grafana.com/grafana/plugins/simpod-json-datasource) and [JSON API](https://grafana.com/grafana/plugins/marcusolsson-json-datasource).
> **Note:** If you're looking for an example of a data source plugin to start from, refer to [grafana-starter-datasource-backend](https://github.com/grafana/grafana-starter-datasource-backend).
### [Splunk](https://grafana.com/grafana/plugins/grafana-splunk-datasource/)
Latest Version: 4.1.6 | Signature: Grafana | Last Updated: 2023
> **Note:** Removal of any angular dependency is on the near term roadmap.
### [Strava](https://grafana.com/grafana/plugins/grafana-strava-datasource/)
Latest Version: 1.5.1 | Signature: Grafana | Last Updated: 2022
> **Note:** Removal of any angular dependency is on the near term roadmap.
### [openHistorian](https://grafana.com/grafana/plugins/gridprotectionalliance-openhistorian-datasource/)
Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/GridProtectionAlliance/openHistorian-grafana/) in the past 2 years suggests project _may_ not be actively maintained.
### [OSIsoft-PI](https://grafana.com/grafana/plugins/gridprotectionalliance-osisoftpi-datasource/)
Latest Version: 3.1.0 | Signature: Community | Last Updated: 2023
> **Note:** Fixed in 4.0.0 which should be published soon - [source](https://github.com/GridProtectionAlliance/osisoftpi-grafana/issues/119#issuecomment-1493566212).
### [Hawkular](https://grafana.com/grafana/plugins/hawkular-datasource/)
Latest Version: 1.1.2 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/hawkular/hawkular-grafana-datasource) in the past 5 years suggests project _may_ not be actively maintained.
### [Humio](https://grafana.com/grafana/plugins/humio-datasource/)
Latest Version: 3.3.1 | Signature: Commercial | Last Updated: 2022
### [IBM APM](https://grafana.com/grafana/plugins/ibm-apm-datasource/)
Latest Version: 0.9.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/rafal-szypulka/grafana-ibm-apm) in the past 3 years suggests project _may_ not be actively maintained.
### [PRTG](https://grafana.com/grafana/plugins/jasonlashua-prtg-datasource/)
Latest Version: 4.0.4 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/neuralfraud/grafana-prtg) in the past 4 years suggests project _may_ not be actively maintained.
> **Warning:** Unmaintained since 2017 - [source](https://github.com/neuralfraud/grafana-prtg/wiki).
### [LinkSmart HDS Datasource](https://grafana.com/grafana/plugins/linksmart-hds-datasource/)
Latest Version: 1.0.2 | Signature: Community | Last Updated: 2021
> **Warning:** [Project repository](https://github.com/linksmart/grafana-hds-datasource) was archived on April 4th, 2022 and is no longer maintained.
### [LinkSmart SensorThings](https://grafana.com/grafana/plugins/linksmart-sensorthings-datasource/)
Latest Version: 1.3.1 | Signature: Community | Last Updated: 2021
> **Warning:** [Project repository](https://github.com/linksmart/grafana-sensorthings-datasource) was archived on April 4th, 2022 and is no longer maintained.
### [Monasca](https://grafana.com/grafana/plugins/monasca-datasource/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/openstack/monasca-grafana-datasource) in the past 2 years suggests project _may_ not be actively maintained.
> **Warning:** Last updated to support Grafana v7.
### [Monitoring Art](https://grafana.com/grafana/plugins/monitoringartist-monitoringart-datasource/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/monitoringartist/grafana-monitoring-art) in the past 6 years suggests project _may_ not be actively maintained.
### [GoogleCalendar](https://grafana.com/grafana/plugins/mtanda-google-calendar-datasource/)
Latest Version: 1.0.5 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/mtanda/grafana-google-calendar-datasource) in the past 2 years suggests project _may_ not be actively maintained.
### [USGS Water Services](https://grafana.com/grafana/plugins/natel-usgs-datasource/)
Latest Version: 0.0.3 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/natel-usgs-datasource) in the past 3 years suggests project _may_ not be actively maintained.
### [ntopng](https://grafana.com/grafana/plugins/ntop-ntopng-datasource/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Migration available - plugin superseded:** this plugin was [discontinued in favour of the InfluxDB data source](https://github.com/ntop/ntopng-grafana-datasource) - a Core plugin included in Grafana, additional guidance is available [here](https://www.ntop.org/guides/ntopng/basic_concepts/timeseries.html#influxdb-driver).
### [Oracle Cloud Infrastructure Logs](https://grafana.com/grafana/plugins/oci-logs-datasource/)
Latest Version: 3.0.0 | Signature: Commercial | Last Updated: 2023
### [Oracle Cloud Infrastructure Metrics](https://grafana.com/grafana/plugins/oci-metrics-datasource/)
Latest Version: 4.0.0 | Signature: Commercial | Last Updated: 2023
### [Warp 10](https://grafana.com/grafana/plugins/ovh-warp10-datasource/)
Latest Version: 2.2.1 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
[Project repository](https://github.com/ovh/ovh-warp10-datasource) was archived on March 22nd, 2023 and is no longer maintained.
{{% /admonition %}}
### [KapacitorSimpleJson](https://grafana.com/grafana/plugins/paytm-kapacitor-datasource/)
Latest Version: 0.1.3 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Lack of recent activity in the [project repository](https://github.com/paytm/kapacitor-grafana-datasource-plugin) in the past 4 years suggests project _may_ not be actively maintained.
{{% /admonition %}}
### [Ambari Metrics](https://grafana.com/grafana/plugins/praj-ams-datasource/)
Latest Version: 1.2.1 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Lack of recent activity in the [project repository](https://github.com/prajwalrao/ambari-metrics-grafana) in the past 5 years suggests project _may_ not be actively maintained.
{{% /admonition %}}
### [Solr](https://grafana.com/grafana/plugins/pue-solr-datasource/)
Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Unclear progress on migration to React - [issue](https://github.com/pueteam/datasource-plugin-solr/issues/12).
{{% /admonition %}}
> **Migration available - potential alternative:** Users could configure the solr-exporter for Prometheus as described [here](https://solr.apache.org/guide/solr/latest/deployment-guide/monitoring-with-prometheus-and-grafana.html).
### [QuasarDB](https://grafana.com/grafana/plugins/quasardb-datasource/)
Latest Version: 3.8.3 | Signature: Community | Last Updated: 2021
### [Blueflood](https://grafana.com/grafana/plugins/rackerlabs-blueflood-datasource/)
Latest Version: 0.0.3 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Lack of recent activity in the [project repository](https://github.com/rax-maas/blueflood-grafana) in the past 7 years suggests project _may_ not be actively maintained.
{{% /admonition %}}
### [NetXMS](https://grafana.com/grafana/plugins/radensolutions-netxms-datasource/)
Latest Version: 1.2.3 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Lack of recent activity in the [project repository](https://github.com/netxms/grafana) in the past 2 years suggests project _may_ not be actively maintained.
{{% /admonition %}}
### [Shoreline Data Source](https://grafana.com/grafana/plugins/shorelinesoftware-shoreline-datasource/)
Latest Version: 1.1.0 | Signature: Commercial | Last Updated: 6 months ago
### [Sidewinder](https://grafana.com/grafana/plugins/sidewinder-datasource/)
Latest Version: 0.2.1 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Lack of recent activity in the [project repository](https://github.com/srotya/sidewinder-grafana) in the past 5 years suggests project _may_ not be actively maintained.
{{% /admonition %}}
### [Skydive](https://grafana.com/grafana/plugins/skydive-datasource/)
Latest Version: 1.2.1 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Lack of recent activity in the [project repository](https://github.com/skydive-project/skydive-grafana-datasource) in the past 4 years suggests project _may_ not be actively maintained.
{{% /admonition %}}
{{% admonition type="warning" %}}
Issues suggest the entire project, not just the plugin, may be abandoned - [source](https://github.com/skydive-project/skydive/issues/2417).
{{% /admonition %}}
### [Heroic](https://grafana.com/grafana/plugins/spotify-heroic-datasource/)
Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
[Plugin](https://github.com/spotify/spotify-heroic-datasource) and [Heroic](https://github.com/spotify/heroic) were both archived on April 17th, 2021 and March 27th, 2021 respectively.
{{% /admonition %}}
### [Heroic](https://grafana.com/grafana/plugins/udoprog-heroic-datasource/)
Latest Version: 0.1.1 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
[Plugin](https://github.com/udoprog/udoprog-heroic-datasource) and [Heroic](https://github.com/spotify/heroic) were both archived on October 16th, 2022 and March 27th, 2021 respectively.
{{% /admonition %}}
### [Altinity plugin for ClickHouse](https://grafana.com/grafana/plugins/vertamedia-clickhouse-datasource/)
Latest Version: 2.5.3 | Signature: Community | Last Updated: 2022
{{% admonition type="note" %}}
The [migration issue](https://github.com/Altinity/clickhouse-grafana/issues/475) has been assigned to a new major version milestone.
{{% /admonition %}}
### [Pagerduty](https://grafana.com/grafana/plugins/xginn8-pagerduty-datasource/)
Latest Version: 0.2.2 | Signature: Community | Last Updated: 2021
{{% admonition type="warning" %}}
Lack of recent activity in the [project repository](https://github.com/skydive-project/skydive-grafana-datasource) in the past year suggests project _may_ not be actively maintained.
{{% /admonition %}}
{{% admonition type="warning" %}}
Plugin only claims support for Grafana v5.
{{% /admonition %}}
### [Chaos Mesh](https://grafana.com/grafana/plugins/yeya24-chaosmesh-datasource/)
Latest Version: 0.2.3 | Signature: Community | Last Updated: 2022
{{% admonition type="warning" %}}
Plugin declares itself deprecated in favour of [chaosmeshorg-datasource](https://grafana.com/grafana/plugins/chaosmeshorg-datasource/) which also appears above in this list with warnings around its future.
{{% /admonition %}}
## Panels
### [FlowCharting](https://grafana.com/grafana/plugins/agenty-flowcharting-panel/)
Latest Version: 0.9.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/algenty/grafana-flowcharting) in the past year suggests project _may_ not be actively maintained.
### [HTML](https://grafana.com/grafana/plugins/aidanmountford-html-panel/)
Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/aidanmountford/aidanmountford-html-panel) in the past 4 years suggests project _may_ not be actively maintained.
> **Migration available - potential alternative:** The [Text]({{< relref "../../panels-visualizations/visualizations/text/#html" >}}) panel included with Grafana supports rendering HTML content.
### [Track Map](https://grafana.com/grafana/plugins/alexandra-trackmap-panel/)
Latest Version: 1.2.6 | Signature: Community | Last Updated: 2021
> **Warning:** [Issue](https://github.com/alexandrainst/alexandra-trackmap-panel/issues/72#issuecomment-1332179974) suggests problems with ongoing maintenance unless new contributors are found.
> **Warning:** [Migration issue](https://github.com/alexandrainst/alexandra-trackmap-panel/issues/105) has been marked as needing help.
### [PictureIt](https://grafana.com/grafana/plugins/bessler-pictureit-panel/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/vbessler/grafana-pictureit) in the past 6 years suggests project _may_ not be actively maintained.
> **Migration available - potential alternative:** another plugin exists which provides similar capabilities - [ePict](https://grafana.com/grafana/plugins/larona-epict-panel/).
### [Singlestat Math](https://grafana.com/grafana/plugins/blackmirror1-singlestat-math-panel/)
Latest Version: 1.1.8 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/black-mirror-1/singlestat-math) in the past 5 years suggests project _may_ not be actively maintained.
### [Status By Group Panel](https://grafana.com/grafana/plugins/blackmirror1-statusbygroup-panel/)
Latest Version: 1.1.2 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/black-mirror-1/Grafana_Status_panel) in the past 5 years suggests project _may_ not be actively maintained.
### [Datatable Panel](https://grafana.com/grafana/plugins/briangann-datatable-panel/)
Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
> **Note:** Migration to react is planned - [issue](https://github.com/briangann/grafana-datatable-panel/issues/174).
### [D3 Gauge](https://grafana.com/grafana/plugins/briangann-gauge-panel/)
Latest Version: 0.0.9 | Signature: Community | Last Updated: 2021
> **Note:** Migration to react is a planned [update](https://github.com/briangann/grafana-gauge-panel/issues/740).
### [GeoLoop](https://grafana.com/grafana/plugins/citilogics-geoloop-panel/)
Latest Version: 1.1.2 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/CitiLogics/citilogics-geoloop-panel) in the past 2 years suggests project _may_ not be actively maintained.
### [Progress List](https://grafana.com/grafana/plugins/corpglory-progresslist-panel/)
Latest Version: 1.0.6 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/CorpGlory/grafana-progress-list) in the past 2 years suggests project _may_ not be actively maintained.
### [Bubble Chart](https://grafana.com/grafana/plugins/digrich-bubblechart-panel/)
Latest Version: 1.2.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/digrich/bubblechart-panel) in the past 3 years suggests project _may_ not be actively maintained.
### [Blendstat](https://grafana.com/grafana/plugins/farski-blendstat-panel/)
Latest Version: 1.0.3 | Signature: Community | Last Updated: 2021
> **Migration available - potential alternative:** plugin author recommends use of single stat panel and transformations functionality - [source](https://github.com/farski/blendstat-grafana/issues/11#issuecomment-1112158909).
### [WindRose](https://grafana.com/grafana/plugins/fatcloud-windrose-panel/)
Latest Version: 0.7.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/fatcloud/windrose-panel) in the past 4 years suggests project _may_ not be actively maintained.
### [Statusmap](https://grafana.com/grafana/plugins/flant-statusmap-panel/)
Latest Version: 0.5.1 | Signature: Community | Last Updated: 2022
> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/flant/grafana-statusmap/issues/302).
### [Singlestat](https://grafana.com/grafana/plugins/grafana-singlestat-panel/)
Latest Version: 2.0.0 | Signature: Grafana | Last Updated: 2022
> **Migration available - plugin superseded:** Singlestat plugin was replaced by the [Stat]({{< relref "../../panels-visualizations/visualizations/stat/" >}})panel included in Grafana.
### [Worldmap Panel](https://grafana.com/grafana/plugins/grafana-worldmap-panel/)
Latest Version: 1.0.3 | Signature: Grafana | Last Updated: 2023
> **Migration available - plugin superseded:** Worldmap plugin was replaced by [Geomap]({{< relref "../../panels-visualizations/visualizations/geomap/" >}}) panel included in Grafana.
### [Topology Panel](https://grafana.com/grafana/plugins/gretamosa-topology-panel/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/gretamosa/gretamosa-topology-panel) in the past 4 years suggests project _may_ not be actively maintained
### [SVG](https://grafana.com/grafana/plugins/marcuscalidus-svg-panel/)
Latest Version: 0.3.4 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/MarcusCalidus/marcuscalidus-svg-panel) in the past year suggests project _may_ not be actively maintained.
> **Migration available - potential alternative:** another plugin exists which provides similar capabilities - [aceiot-svg-panel](https://grafana.com/grafana/plugins/aceiot-svg-panel/)
### [Annunciator](https://grafana.com/grafana/plugins/michaeldmoore-annunciator-panel/)
Latest Version: 1.1.0 | Signature: Community | Last Updated: 2021
> **Warning:** Plugin developer has indicated they will retire the plugin once Angular support is discontinued - [source](https://github.com/michaeldmoore/michaeldmoore-annunciator-panel/issues/24#issuecomment-1479372673).
### [Multistat](https://grafana.com/grafana/plugins/michaeldmoore-multistat-panel/)
Latest Version: 1.7.2 | Signature: Community | Last Updated: 2021
> **Warning:** Plugin developer has indicated they will retire the plugin once Angular support is discontinued - [source](https://github.com/michaeldmoore/michaeldmoore-multistat-panel/issues/71#issuecomment-1479372977).
### [HeatmapEpoch](https://grafana.com/grafana/plugins/mtanda-heatmap-epoch-panel/)
Latest Version: 0.1.8 | Signature: Community | Last Updated: 2021
> **Warning:** Plugin advises caution as not stable; [project repository](https://github.com/mtanda/grafana-heatmap-epoch-panel) has not been updated in 7 years.
> **Migration available - potential alternative:** Other Heatmap panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/heatmap/" >}}).
### [Histogram](https://grafana.com/grafana/plugins/mtanda-histogram-panel/)
Latest Version: 0.1.7 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/mtanda/grafana-histogram-panel) in the past 7 years suggests project _may_ not be actively maintained
> **Migration available - potential alternative:** other Histogram panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/histogram/" >}}).
### [Separator](https://grafana.com/grafana/plugins/mxswat-separator-panel/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/mxswat/grafana-separator-panel) in the past 5 years suggests project _may_ not be actively maintained
> **Migration available - potential alternative:** the [Text]({{< relref "../../panels-visualizations/visualizations/text/#html" >}}) panel can be used with no data to provide space within dashboards.
### [Discrete](https://grafana.com/grafana/plugins/natel-discrete-panel/)
Latest Version: 0.1.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/grafana-discrete-panel) in the past 3 years suggests project _may_ not be actively maintained
### [Influx Admin](https://grafana.com/grafana/plugins/natel-influx-admin-panel/)
Latest Version: 0.0.6 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/grafana-influx-admin) in the past 5 years suggests project _may_ not be actively maintained.
### [Plotly](https://grafana.com/grafana/plugins/natel-plotly-panel/)
Latest Version: 0.0.7 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/NatelEnergy/grafana-plotly-panel) in the past 2 years suggests project _may_ not be actively maintained.
> **Migration available - potential alternative:** another plugin exists which provides similar capabilities - [nline-plotlyjs-panel/](https://grafana.com/grafana/plugins/nline-plotlyjs-panel/).
### [Cal-HeatMap](https://grafana.com/grafana/plugins/neocat-cal-heatmap-panel/)
Latest Version: 0.0.4 | Signature: Community | Last Updated: 2021
> **Warning:** Plugin advises caution as not stable; [project repository](https://github.com/NeoCat/grafana-cal-heatmap-panel) has not been updated in 7 years.
> **Migration available - potential alternative:** other Heatmap panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/heatmap/" >}}).
### [Annotation Panel](https://grafana.com/grafana/plugins/novalabs-annotations-panel/)
Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/novalabs/grafana-annotations-panel) in the past 6 years suggests project _may_ not be actively maintained.
### [Carpet plot](https://grafana.com/grafana/plugins/petrslavotinek-carpetplot-panel/)
Latest Version: 0.1.2 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/petrslavotinek/grafana-carpetplot) in the past 6 years suggests project _may_ not be actively maintained.
### [TrackMap](https://grafana.com/grafana/plugins/pr0ps-trackmap-panel/)
Latest Version: 2.1.4 | Signature: Community | Last Updated: 2023
> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/pR0Ps/grafana-trackmap-panel/issues/84).
### [AJAX](https://grafana.com/grafana/plugins/ryantxu-ajax-panel/)
Latest Version: 0.1.0 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/ryantxu/ajax-panel) in the past 2 years suggests project _may_ not be actively maintained.
### [Annotation List](https://grafana.com/grafana/plugins/ryantxu-annolist-panel/)
Latest Version: 0.0.2 | Signature: Community | Last Updated: 2021
> **Migration available - plugin superseded:** [Project repository](https://github.com/ryantxu/annotations-panel) for the plugin was archived on July 13th, 2019 in favour of native [annotations]({{< relref "../../panels-visualizations/visualizations/annotations/" >}}).
### [3D Globe Panel](https://grafana.com/grafana/plugins/satellogic-3d-globe-panel/)
Latest Version: 0.1.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/satellogic/grafana-3d-globe-panel) in the past 5 years suggests project _may_ not be actively maintained.
### [Heatmap](https://grafana.com/grafana/plugins/savantly-heatmap-panel/)
Latest Version: 0.2.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/savantly-net/grafana-heatmap) in the past 6 years suggests project _may_ not be actively maintained.
> **Migration available - potential alternative:** other Heatmap panels exist including natively in Grafana - [learn more]({{< relref "../../panels-visualizations/visualizations/heatmap/" >}}).
### [SCADAvis Synoptic Panel](https://grafana.com/grafana/plugins/scadavis-synoptic-panel/)
Latest Version: 1.0.5 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/riclolsen/scadavis-synoptic-panel) in the past 3 years suggests project _may_ not be actively maintained.
### [TrafficLight](https://grafana.com/grafana/plugins/smartmakers-trafficlight-panel/)
Latest Version: 1.0.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/smartmakers/grafana-trafficlight) in the past 5 years suggests project _may_ not be actively maintained.
### [Radar Graph](https://grafana.com/grafana/plugins/snuids-radar-panel/)
Latest Version: 1.5.1 | Signature: Community | Last Updated: 2022
> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/snuids/grafana-radar-panel/issues/29).
### [Traffic Lights](https://grafana.com/grafana/plugins/snuids-trafficlights-panel/)
Latest Version: 1.6.0 | Signature: Community | Last Updated: 2023
> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/snuids/trafficlights-panel/issues/44).
### [Status Panel](https://grafana.com/grafana/plugins/vonage-status-panel/)
Latest Version: 1.0.11 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/Vonage/Grafana_Status_panel) in the past 3 years suggests project _may_ not be actively maintained.
### [Boom Table](https://grafana.com/grafana/plugins/yesoreyeram-boomtable-panel/)
Latest Version: 1.4.1 | Signature: Community | Last Updated: 2021
> **Warning:** Lack of recent activity in the [project repository](https://github.com/yesoreyeram/yesoreyeram-boomtable-panel) in the past 3 years suggests project _may_ not be actively maintained.
### [Parity Report](https://grafana.com/grafana/plugins/zuburqan-parity-report-panel/)
Latest Version: 1.2.2 | Signature: Community | Last Updated: 2021
> **Warning:** Unknown whether migration to react will be undertaken - [migration issue](https://github.com/zuburqan/grafana-parity-report/issues/17).
docs/sources/developers/http_api/admin.md
+6 -2
View File
@@ -192,7 +192,9 @@ Content-Type: application/json
`PUT /api/admin/settings`
> **Note:** Available in Grafana Enterprise v8.0+.
{{% admonition type="note" %}}
Available in Grafana Enterprise v8.0+.
{{% /admonition %}}
Updates / removes and reloads database settings. You must provide either `updates`, `removals` or both.
@@ -471,7 +473,9 @@ Content-Type: application/json
`POST /api/admin/pause-all-alerts`
> **Note:** This API is relevant for the [legacy dashboard alerts](https://grafana.com/docs/grafana/v8.5/alerting/old-alerting/) only. For default alerting, use silences to stop alerts from being delivered.
{{% admonition type="note" %}}
This API is relevant for the [legacy dashboard alerts](https://grafana.com/docs/grafana/v8.5/alerting/old-alerting/) only. For default alerting, use silences to stop alerts from being delivered.
{{% /admonition %}}
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
docs/sources/developers/http_api/alerting.md
+3 -1
View File
@@ -15,7 +15,9 @@ title: 'Alerting HTTP API '
# Legacy Alerting API
> **Note:** Starting with v9.0, the Legacy Alerting HTTP API is deprecated. It will be removed in a future release.
{{% admonition type="note" %}}
Starting with v9.0, the Legacy Alerting HTTP API is deprecated. It will be removed in a future release.
{{% /admonition %}}
This topic is relevant for the [legacy dashboard alerts](https://grafana.com/docs/grafana/v8.5/alerting/old-alerting/) only.
docs/sources/developers/http_api/alerting_notification_channels.md
+3 -1
View File
@@ -16,7 +16,9 @@ title: 'Alerting Notification Channels HTTP API '
# Legacy Alerting Notification Channels API
> **Note:** Starting with v9.0, the Legacy Alerting Notification Channels API is deprecated. It will be removed in a future release.
{{% admonition type="note" %}}
Starting with v9.0, the Legacy Alerting Notification Channels API is deprecated. It will be removed in a future release.
{{% /admonition %}}
This page documents the Alerting Notification Channels API.
docs/sources/developers/http_api/dashboard_permissions.md
+6 -2
View File
@@ -176,7 +176,9 @@ Status Codes:
## Get permissions for a dashboard by id
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#get-permissions-for-a-dashboard).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#get-permissions-for-a-dashboard).
{{% /admonition %}}
`GET /api/dashboards/id/:dashboardId/permissions`
@@ -257,7 +259,9 @@ Status Codes:
## Update permissions for a dashboard by id
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#update-permissions-for-a-dashboard).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard permissions API](#update-permissions-for-a-dashboard).
{{% /admonition %}}
`POST /api/dashboards/id/:dashboardId/permissions`
docs/sources/developers/http_api/dashboard_versions.md
+9 -3
View File
@@ -18,7 +18,9 @@ title: 'Dashboard Versions HTTP API '
## Get all dashboard versions
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard versions API](#get-all-dashboard-versions-by-dashboard-uid).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new dashboard versions API](#get-all-dashboard-versions-by-dashboard-uid).
{{% /admonition %}}
Query parameters:
@@ -138,7 +140,9 @@ Status Codes:
## Get dashboard version
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new get dashboard version API](#get-dashboard-version-by-dashboard-uid).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new get dashboard version API](#get-dashboard-version-by-dashboard-uid).
{{% /admonition %}}
`GET /api/dashboards/id/:dashboardId/versions/:version`
@@ -363,7 +367,9 @@ Status Codes:
## Restore dashboard
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new restore dashboard API](#restore-dashboard-by-dashboard-uid).
{{% admonition type="warning" %}}
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new restore dashboard API](#restore-dashboard-by-dashboard-uid).
{{% /admonition %}}
`POST /api/dashboards/id/:dashboardId/restore`
docs/sources/developers/http_api/data_source.md
+27 -9
View File
@@ -77,7 +77,9 @@ Content-Type: application/json
`GET /api/datasources/:datasourceId`
> **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 type="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 %}}
**Required permissions**
@@ -342,7 +344,9 @@ Content-Type: application/json
}
```
> **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 type="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 %}}
**Example Graphite Request with basic auth enabled**:
@@ -429,7 +433,9 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
`PUT /api/datasources/:datasourceId`
> **Warning:** 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 type="warning" %}}
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 %}}
**Required permissions**
@@ -506,7 +512,9 @@ Content-Type: application/json
}
```
> **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.
{{% admonition type="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.
{{% /admonition %}}
## Update an existing data source
@@ -588,13 +596,17 @@ Content-Type: application/json
}
```
> **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.## Update an existing data source by id
{{% admonition type="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.## Update an existing data source by id
{{% /admonition %}}
## Delete an existing data source by id
`DELETE /api/datasources/:datasourceId`
> **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 type="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 %}}
**Required permissions**
@@ -696,7 +708,9 @@ Content-Type: application/json
## Data source proxy calls by id
> **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 type="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 %}}
`GET /api/datasources/proxy/:datasourceId/*`
@@ -770,7 +784,9 @@ Content-Type: application/json
## Fetch data source resources by id
> **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 type="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 %}}
`GET /api/datasources/:datasourceId/resources/*`
@@ -870,7 +886,9 @@ Queries a data source having a backend implementation.
`POST /api/ds/query`
> **Note:** Grafana's built-in data sources usually have a backend implementation.
{{% admonition type="note" %}}
Grafana's built-in data sources usually have a backend implementation.
{{% /admonition %}}
**Example request for the Test data source**:
docs/sources/developers/http_api/library_element.md
+3 -1
View File
@@ -437,7 +437,9 @@ Status Codes:
Deletes an existing library element as specified by the UID. This operation cannot be reverted.
> **Note:** You cannot delete a library element that is connected. This operation cannot be reverted.
{{% admonition type="note" %}}
You cannot delete a library element that is connected. This operation cannot be reverted.
{{% /admonition %}}
**Example Request**:
docs/sources/developers/http_api/licensing.md
+9 -3
View File
@@ -61,7 +61,9 @@ Status codes:
## Add license
> **Note:** Available in Grafana Enterprise v7.4+.
{{% admonition type="note" %}}
Available in Grafana Enterprise v7.4+.
{{% /admonition %}}
`POST /api/licensing/token`
@@ -121,7 +123,9 @@ Status Codes:
## Manually force license refresh
> **Note:** Available in Grafana Enterprise v7.4+.
{{% admonition type="note" %}}
Available in Grafana Enterprise v7.4+.
{{% /admonition %}}
`POST /api/licensing/token/renew`
@@ -180,7 +184,9 @@ Status Codes:
## Remove license from database
> **Note:** Available in Grafana Enterprise v7.4+.
{{% admonition type="note" %}}
Available in Grafana Enterprise v7.4+.
{{% /admonition %}}
`DELETE /api/licensing/token`
docs/sources/developers/http_api/query_and_resource_caching.md
+297
View File
@@ -0,0 +1,297 @@
---
aliases:
- ../../http_api/query_caching/
- ../../http_api/resource_caching/
- ../../http_api/caching/
canonical: /docs/grafana/latest/developers/http_api/query_and_resource_caching/
description: Grafana Enterprise Query and Resource Caching HTTP API
keywords:
- grafana
- http
- documentation
- api
- caching
- query caching
- resource caching
- data source
title: Query and Resource Caching HTTP API
---
# Query and resource caching API
{{% admonition type="note" %}}
If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
{{% /admonition %}}
## Enable caching for a data source
`POST /api/datasources/:dataSourceUID/cache/enable`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache/enable HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message": "Data source cache enabled",
"dataSourceID": 1,
"dataSourceUID": "jZrmlLCGka",
"enabled": true,
"ttlQueriesMs": 300000,
"ttlResourcesMs": 300000,
"useDefaultTTL": true,
"defaultTTLMs": 300000,
"created": "2023-04-21T11:49:22-04:00",
"updated": "2023-04-24T16:30:29-04:00"
}
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Disable caching for a data source
`POST /api/datasources/:dataSourceUID/cache/disable`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache/disable HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message": "Data source cache disabled",
"dataSourceID": 1,
"dataSourceUID": "jZrmlLCGka",
"enabled": false,
"ttlQueriesMs": 300000,
"ttlResourcesMs": 300000,
"useDefaultTTL": true,
"defaultTTLMs": 0,
"created": "2023-04-21T11:49:22-04:00",
"updated": "2023-04-24T16:30:31-04:00"
}
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Clean cache for all data sources
`POST /api/datasources/:dataSourceUID/cache/clean`
Will clean cached data for _all_ data sources with caching enabled. The `dataSourceUID` specified will only be used to return the configuration for that data source.
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache/clean HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message": "Data source cache cleaned",
"dataSourceID": 1,
"dataSourceUID": "jZrmlLCGka",
"enabled": false,
"ttlQueriesMs": 300000,
"ttlResourcesMs": 300000,
"useDefaultTTL": true,
"defaultTTLMs": 0,
"created": "2023-04-21T11:49:22-04:00",
"updated": "2023-04-24T16:30:31-04:00"
}
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Update cache configuration for a data source
`POST /api/datasources/:dataSourceUID/cache`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------- | -------------- |
| datasources.caching:write | datasources:\* |
### Examples
**Example Request**:
```http
POST /api/datasources/jZrmlLCGka/cache HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"dataSourceID": 1,
"dataSourceUID": "jZrmlLCGka",
"enabled": true,
"useDefaultTTL": false,
"ttlQueriesMs": 60000,
"ttlResourcesMs": 300000,
}
```
#### JSON Body Schema
| Field name | Data type | Description |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| dataSourceID | number | The ID of the data source to configure. |
| dataSourceUID | string | The UID of the data source to configure. |
| enabled | boolean | Whether or not to enable caching for this data source. |
| useDefaultTTL | boolean | Whether the configured default TTL (Time-To-Live) should be used for both query and resource caching, instead of the user-specified values. |
| ttlQueriesMs | number | The TTL to use for query caching, in milliseconds. |
| ttlResourcesMs | number | The TTL to use for resource caching, in milliseconds. |
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message": "Data source cache settings updated",
"dataSourceID": 1,
"dataSourceUID": "jZrmlLCGka",
"enabled": true,
"useDefaultTTL": false,
"ttlQueriesMs": 60000,
"ttlResourcesMs": 300000,
"defaultTTLMs": 300000,
"created": "2023-04-21T11:49:22-04:00",
"updated": "2023-04-24T17:03:40-04:00"
}
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 400 | Request errors (invalid json, missing or invalid fields, etc) |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
## Get cache configuration for a data source
`GET /api/datasources/:dataSourceUID/cache`
**Required permissions**
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
| Action | Scope |
| ------------------------ | -------------- |
| datasources.caching:read | datasources:\* |
### Examples
**Example Request**:
```http
GET /api/datasources/jZrmlLCGka/cache HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message": "Data source cache settings loaded",
"dataSourceID": 1,
"dataSourceUID": "jZrmlLCGka",
"enabled": true,
"useDefaultTTL": false,
"ttlQueriesMs": 60000,
"ttlResourcesMs": 300000,
"defaultTTLMs": 300000,
"created": "2023-04-21T11:49:22-04:00",
"updated": "2023-04-24T17:03:40-04:00"
}
```
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------ |
| 200 | Cache was successfully enabled for the data source |
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
docs/sources/developers/http_api/snapshot.md
+3 -1
View File
@@ -65,7 +65,9 @@ JSON Body schema:
- **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`.
> **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.
{{% admonition type="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.
{{% /admonition %}}
**Example Response**:
docs/sources/explore/_index.md
+3 -1
View File
@@ -65,7 +65,9 @@ To close the newly created query, click on the Close Split button.
## Share shortened link
> **Note:** Available in Grafana 7.3 and later versions.
{{% admonition type="note" %}}
Available in Grafana 7.3 and later versions.
{{% /admonition %}}
The Share shortened link capability allows you to create smaller and simpler URLs of the format /goto/:uid instead of using longer URLs with query parameters. To create a shortened link to the executed query, click the **Share** option in the Explore toolbar. A shortened link that is never used will automatically get deleted after seven (7) days.
docs/sources/explore/query-management.md
+3 -1
View File
@@ -19,7 +19,9 @@ This functionality is similar to the panel inspector tasks [Inspect query perfor
Query history is a list of queries that you used in Explore. The history is stored in the Grafana database and it is not shared with other users. The retention period for queries in history is two weeks. Queries older than two weeks are automatically deleted. To open and interact with your history, click the **Query history** button in Explore.
> **Note**: Starred queries are not subject to the two weeks retention period and they are not deleted.
{{% admonition type="note" %}}
Starred queries are not subject to the two weeks retention period and they are not deleted.
{{% /admonition %}}
### View query history
docs/sources/explore/trace-integration.md
+46 -18
View File
@@ -13,16 +13,16 @@ Explore allows you to visualize traces from tracing data sources. This is availa
Supported data sources are:
- [Jaeger]({{< relref "../datasources/jaeger/" >}})
- [Tempo]({{< relref "../datasources/tempo/" >}})
- [X-Ray](https://grafana.com/grafana/plugins/grafana-x-ray-datasource)
- [Jaeger]({{< relref "../datasources/jaeger/" >}})
- [Zipkin]({{< relref "../datasources/zipkin/" >}})
- [X-Ray](https://grafana.com/grafana/plugins/grafana-x-ray-datasource)
For information on how to configure queries for the data sources listed above, refer to the documentation for specific data source.
## Trace View explanation
## Trace View
This section explains the elements of the Trace View dashboard.
This section explains the elements of the Trace View.
{{< figure src="/static/img/docs/explore/explore-trace-view-full-8-0.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the trace view" >}}
@@ -40,6 +40,24 @@ This section explains the elements of the Trace View dashboard.
Shows condensed view or the trace timeline. Drag your mouse over the minimap to zoom into smaller time range. Zooming will also update the main timeline, so it is easy to see shorter spans. Hovering over the minimap, when zoomed, will show Reset Selection button which resets the zoom.
### Span Filters
{{% admonition type="note" %}}
This feature is behind the `newTraceViewHeader` [feature toggle]({{< relref "../../setup-grafana/configure-grafana#feature_toggles" >}}).
If you use Grafana Cloud, open a [support ticket in the Cloud Portal](/profile/org#support) to access this feature.
{{% /admonition %}}
![Screenshot of span filtering](/media/docs/tempo/screenshot-grafana-tempo-span-filters.png)
Using span filters, you can filter your spans in the trace timeline viewer. The more filters you add, the more specific are the filtered spans.
You can add one or more of the following filters:
- Service name
- Span name
- Duration
- Tags (which include tags, process tags, and log fields)
### Timeline
{{< figure src="/static/img/docs/v70/explore-trace-view-timeline.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the trace view timeline" >}}
@@ -57,34 +75,44 @@ Clicking anywhere on the span row shows span details.
{{< figure src="/static/img/docs/v70/explore-trace-view-span-details.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the trace view span details" >}}
- Operation name
- Span metadata
- Operation name.
- Span metadata.
- Tags: Any tags associated with this span.
- Process metadata: Metadata about the process that logged this span.
- Logs: List of logs logged by this span and associated key values. In case of Zipkin logs section shows Zipkin annotations.
### Node graph
You can optionally expand the node graph for the displayed trace. Depending on the data source, this can show spans of the trace as nodes in the graph, or as some additional context like service graph based on the current trace.
![Node graph](/static/img/docs/explore/explore-trace-view-node-graph-8-0.png 'Node graph')
### Trace to logs
> **Note:** Available in Grafana 7.4 and later versions.
{{% admonition type="note" %}}
Available in Grafana 7.4 and later versions.
{{% /admonition %}}
You can navigate from a span in a trace view directly to logs relevant for that span. This is available for Tempo, Jaeger, and Zipkin data sources at this moment. Refer to their relevant documentation for instructions on how to configure this feature.
You can navigate from a span in a trace view directly to logs relevant for that span. This feature is available for Tempo, Jaeger, and Zipkin data sources. Refer to their [relevant documentation](/docs/grafana/latest/datasources/tempo/#trace-to-logs) for configuration instructions.
{{< figure src="/static/img/docs/explore/trace-to-log-7-4.png" class="docs-image--no-shadow" max-width= "600px" caption="Screenshot of the trace view in Explore with icon next to the spans" >}}
Click the document icon to open a split view in Explore with the configured data source and query relevant logs for the span.
## Service Graph view
### Trace to metrics
The Service Graph view visualizes the span metrics (traces data for rates, error rates, and durations (RED)) and service graphs.
{{% admonition type="note" %}}
This feature is currently in beta & behind the `traceToMetrics` feature toggle.
{{% /admonition %}}
You can navigate from a span in a trace view directly to metrics relevant for that span. This feature is available for Tempo, Jaeger, and Zipkin data sources. Refer to their [relevant documentation](/docs/grafana/latest/datasources/tempo/#trace-to-metrics) for configuration instructions.
## Node Graph
You can optionally expand the node graph for the displayed trace. Depending on the data source, this can show spans of the trace as nodes in the graph, or as some additional context like service graph based on the current trace.
![Node graph](/static/img/docs/explore/explore-trace-view-node-graph-8-0.png 'Node graph')
## Service Graph
The Service Graph visualizes the span metrics (traces data for rates, error rates, and durations (RED)) and service graphs.
Once the requirements are set up, this pre-configured view is immediately available.
For more information, refer to the [Service Graph view table section](https://grafana.com/docs/grafana/latest/datasources/tempo/#service-graph-view-table) of the Tempo data source page and the [service graph view page](https://grafana.com/docs/tempo/latest/metrics-generator/service-graph-view/) in the Tempo documentation.
For more information, refer to the [Service Graph view section]({{< relref "/docs/grafana/latest/datasources/tempo/#open-the-service-graph-view" >}}) of the Tempo data source page and the [service graph view page]({{< relref "/docs/tempo/latest/metrics-generator/service-graph-view/" >}}) in the Tempo documentation.
{{< figure src="/static/img/docs/grafana-cloud/apm-overview.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the Service Graph view" >}}
@@ -118,4 +146,4 @@ Optional fields:
| stackTraces | string[] | List of stack traces associated with the current span. |
| errorIconColor | string | Color of the error icon in case span is tagged with `error: true`. |
For details about the types see [TraceSpanRow](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/trace.ts#L28), [TraceKeyValuePair](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/trace.ts#L4) and [TraceLog](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/trace.ts#L12)
For details about the types see [TraceSpanRow](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/trace.ts#L28), [TraceKeyValuePair](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/trace.ts#L4) and [TraceLog](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/trace.ts#L12).
docs/sources/fundamentals/dashboards-overview/index.md
+87
View File
@@ -0,0 +1,87 @@
---
description: Learn how Grafana dashboards are built.
keywords:
- grafana
- dashboards
- panel
- data source
- transform
- query
title: Grafana dashboards overview
menuTitle: Dashboard overview
weight: 300
---
# Grafana dashboards overview
Have you ever wondered what a dashboard is? In the observability world, this term is frequently used, but what exactly does it mean? The concept is borrowed from automobiles, where a dashboard gives drivers access to the controls necessary to operate a vehicle. Similarly, digital dashboards help us comprehend and manage systems. This topic explains how Grafana dashboards function, enabling you to create your own with greater ease.
The following image illustrates a sample Grafana dashboard.
{{< figure src="/media/docs/grafana/dashboards-overview/complex-dashboard-example.png" max-width="750px" caption="Example Grafana Dashboard" >}}
A Grafana dashboard consists of panels displaying data in beautiful graphs, charts, and other visualizations. These panels are created using components that transform raw data from a data source into visualizations. The process involves passing data through three gates: a plugin, a query, and an optional transformation.
The image below displays all the gates, followed by detailed explanations of their purpose, usage, and significance. The process of creating a visualization starts from the data source and progresses towards a Grafana dashboard.
{{< figure src="/media/docs/grafana/dashboards-overview/dashboard-component-architecture.png" max-width="750px" caption="Dashboard component architecture" >}}
## Data source
A data source refers to any entity that consists of data. It can be a SQL database, Grafana Loki, Grafana Mimir, or a JSON-based API. It can even be a basic CSV file. The first step in creating a dashboard visualization is selecting the data source that contains the data you need.
It can be difficult to understand the distinctions between different data sources as each possesses its own structure and requires different query methods. However, to streamline this complexity, Grafana Labs has created plugins that unify data sources into one coherent view.
## Plugins
A Grafana plugin is software that adds new capabilities to Grafana. They come in many types, but right now we will address _data source plugins_. The job of a Grafana data source plugin is to take a query you want answered, retrieve the data from the data source, and reconcile the differences in data models using a unified data structure called a [data frame](/docs/grafana/latest/developers/plugins/data-frames/). The data coming into the plugin from the data source might be many different formats (such as JSON, rows and columns, or CSV), but when it leaves the plugin and moves through the rest of the gates toward a visualization, it is always data frames.
Currently, Grafana offers a diverse range of 155 data sources that you can use. The most commonly used options are already pre-installed and accessible. Before exploring other options, look for an existing data source that matches your requirements. Grafana constantly updates the list, but if you don't find a suitable data source, you can browse through the [plugin catalog](/grafana/plugins/?type=datasource) or [create a plugin](/tutorials/build-a-data-source-plugin/).
## Query
Queries allow for the reduction of data to a specific dataset, providing a more manageable visualization. They help answer questions you have about system and operational processes. For instance, a company with an online store might want to determine the number of customers who add products to their shopping carts. This can be achieved through a query that aggregates access metrics for the shopping cart service, revealing the number of users accessing the service per second.
When working with data sources, it is crucial to recognize that each one has its own distinct query language. For example, Prometheus data sources utilize [PromQL](/blog/2020/02/04/introduction-to-promql-the-prometheus-query-language/), while [LogQL](/docs/loki/latest/logql/) is used for logs, and particular databases employ SQL. A query supports every visualization in Grafana, and a dashboard might feature a range of query languages.
The following image shows the Query Editor associated with the Prometheus data source. The `node_cpu_seconds_total` query is written in PromQL and requests just one metric.
{{< figure src="/media/docs/grafana/dashboards-overview/example-query.png" max-width="750px" caption="Example Query" >}}
## Transforms
When the data format in a visualization doesn’t meet your requirements, you can apply a [transformation]({{< relref "../../panels-visualizations/query-transform-data/transform-data" >}}) that manipulates the data returned by a query. You might not need to transform data when you are first starting out, but they are powerful and worth mentioning.
Transforming data is useful in the following kinds of situations:
- You want to combine two fields together, for example, concatenating `Given Name` and `Family Name` into a `Full Name` field
- You have CSV data (all text), and you want to convert a field types (such as parsing a date or a number out of a string)
- You want to filter, join, merge, or perform other SQL-like operations that might not be supported by the underlying data source or query language
Transforms are located next to the **Query** tab in the edit dialog for a panel. Select the transform you want, and define the transform. The following image shows that you can have as many transforms as you want, just like queries. For example, you can chain together a series of transforms that make a change to a data type, filter results, organize columns, and sort the result into one data pipeline. Every time the dashboard is refreshed, the transform applies to the latest data from the data source.
The following image shows the transform dialog.
{{< figure src="/media/docs/grafana/dashboards-overview/example-transform-chain.png" max-width="750px" caption="Example chain of transforms" >}}
## Panel
After the data is sourced, queried, and transformed, it passes to a panel which is the final gate in the journey to a Grafana visualization. A panel is a container that displays the visualization and provides you with various controls to manipulate it. The panel configuration is where you specify how you want to see the data. For example, you use a drop-down menu in the top-right of the panel to specify the type of visualization you want to see, such as a bar chart, pie chart, or histogram.
The panel options enable you to customize many aspects of the visualization and change them based on the visualization you select. Panels also contain queries that specify the data the panel is visualizing.
The following image shows a table panel being edited, the panel settings showing the query at the bottom, and the panel options on the right. In this image, you can see how the data source, plugin, query, and panel all come together.
{{< figure src="/media/docs/grafana/dashboards-overview/example-table-panel.png" max-width="750px" caption="Example table panel" >}}
Selecting the best visualization depends on the data and how you want it presented. To see examples of dashboards in one place that you can browse and inspect, refer to [Grafana Play](https://play.grafana.org/), which has feature showcases and a variety of examples.
## Conclusion
With the data source, plugin, query, transform, and panel model in mind, you can now see right through any Grafana dashboard you encounter, and imagine how to build your own.
Building a Grafana dashboard is a process that starts with determining your dashboard requirements and identifying which data sources support those requirements. If you want to integrate a specialized database with a Grafana dashboard, you must ensure the correct plugin is installed so that you can create a data source to use with that plugin.
And with the data source identified and the plugin installed, you can write your query, transform the data, and format the visualization to meet your needs.
This component architecture is part of what makes Grafana so powerful and general. Given the data source plugin and data frame abstraction, any data source you can access can work with the same general approach.
docs/sources/fundamentals/timeseries-dimensions/index.md
+8 -4
View File
@@ -18,7 +18,7 @@ weight: 600
# Time series dimensions
In [Introduction to time series]({{< relref "timeseries/#time-series-databases" >}}), the concept of _labels_, also called _tags_, is introduced:
In [Introduction to time series]({{< relref "../timeseries#time-series-databases" >}}), the concept of _labels_, also called _tags_, is introduced:
> Another feature of a TSDB is the ability to filter measurements using _tags_. Each data point is labeled with a tag that adds context information, such as where the measurement was taken.
@@ -84,12 +84,16 @@ 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}`.
> **Note:** More than one dimension is currently only supported in the Logs queries within the Azure Monitor service as of version 7.1.
{{% admonition type="note" %}}
More than one dimension is currently only supported in the Logs queries within the Azure Monitor service as of version 7.1.
{{% /admonition %}}
> **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 See the documentation on [creating alerts with multiple series]({{< relref "../../alerting/alerting-rules/create-grafana-managed-rule/#single-and-multi-dimensional-rule" >}}).
{{% admonition type="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 See the documentation on [creating alerts with multiple series]({{< relref "../../alerting/alerting-rules/create-grafana-managed-rule#single-and-multi-dimensional-rule" >}}).
{{% /admonition %}}
### Multiple values
In the case of SQL-like data sources, more than one numeric column can be selected, with or without additional string columns to be used as dimensions. For example, `AVG(Temperature) AS AvgTemp, MAX(Temperature) AS MaxTemp`. This, if combined with multiple dimensions, can result in a lot of series. Selecting multiple values is currently only designed to be used with visualization.
Additional technical information on tabular time series formats and how dimensions are extracted can be found in [the developer documentation on data frames as time series]({{< relref "../../developers/plugins/data-frames/#data-frames-as-time-series" >}}).
Additional technical information on tabular time series formats and how dimensions are extracted can be found in [the developer documentation on data frames as time series]({{< relref "../../developers/plugins/data-frames#data-frames-as-time-series" >}}).
docs/sources/getting-started/build-first-dashboard.md
+26 -18
View File
@@ -10,13 +10,15 @@ weight: 200
# Build your first dashboard
This topic helps you get started with Grafana and build your first dashboard using the built-in `Grafana` data source. To learn more about Grafana, refer to [Introduction to Grafana]({{< relref "../introduction/" >}}).
This topic helps you get started with Grafana and build your first dashboard using the built-in `Grafana` data source. To learn more about Grafana, refer to [Introduction to Grafana]({{< relref "../introduction" >}}).
> **Note:** Grafana also offers a [free account with Grafana Cloud](https://grafana.com/signup/cloud/connect-account?pg=gsdocs) to help getting started even easier and faster. You can install Grafana to self-host or get a free Grafana Cloud account.
{{% admonition type="note" %}}
Grafana also offers a [free account with Grafana Cloud](/signup/cloud/connect-account?pg=gsdocs) to help getting started even easier and faster. You can install Grafana to self-host or get a free Grafana Cloud account.
{{% /admonition %}}
#### Install Grafana
Grafana can be installed on many different operating systems. For a list of the minimum hardware and software requirements, as well as instructions on installing Grafana, refer to [Install Grafana]({{< relref "../setup-grafana/installation/" >}}).
Grafana can be installed on many different operating systems. For a list of the minimum hardware and software requirements, as well as instructions on installing Grafana, refer to [Install Grafana]({{< relref "../setup-grafana/installation" >}}).
#### Sign in to Grafana
@@ -33,18 +35,24 @@ To sign in to Grafana for the first time:
1. Click **OK** on the prompt and change your password.
> **Note:** We strongly recommend that you change the default administrator password.
{{% admonition type="note" %}}
We strongly recommend that you change the default administrator password.
{{% /admonition %}}
#### Create a dashboard
If you've already set up a data source that you know how to query, refer to [Create a dashboard]({{< relref "../dashboards/build-dashboards/create-dashboard/" >}}) instead.
If you've already set up a data source that you know how to query, refer to [Create a dashboard]({{< relref "../dashboards/build-dashboards/create-dashboard" >}}) instead.
To create your first dashboard using the built-in `Grafana` data source:
1. Click the **New dashboard** item under the **Dashboards** icon in the side menu.
1. On the dashboard, click **Add a new panel**.
1. Click **Dashboards** in the left-side menu.
1. On the Dashboards page, click **New** and select **New Dashboard** from the dropdown menu.
1. On the dashboard, click **+ Add visualization**.
![Empty dashboard state](/media/docs/grafana/dashboards/empty-dashboard-9.5.png)
1. In the New dashboard/Edit panel view, go to the **Query** tab.
1. Configure your [query]({{< relref "../panels-visualizations/query-transform-data/#add-a-query" >}}) by selecting `-- Grafana --` from the data source selector.
1. Configure your [query]({{< relref "../panels-visualizations/query-transform-data#add-a-query" >}}) by selecting `-- Grafana --` from the data source selector.
This generates the Random Walk dashboard.
@@ -62,19 +70,19 @@ Congratulations, you have created your first dashboard and it is displaying resu
#### Next steps
Continue to experiment with what you have built, try the [explore workflow]({{< relref "../explore/" >}}) or another visualization feature. Refer to [Data sources]({{< relref "../datasources/" >}}) for a list of supported data sources and instructions on how to [add a data source]({{< relref "../administration/data-source-management#add-a-data-source" >}}). The following topics will be of interest to you:
Continue to experiment with what you have built, try the [explore workflow]({{< relref "../explore" >}}) or another visualization feature. Refer to [Data sources]({{< relref "../datasources" >}}) for a list of supported data sources and instructions on how to [add a data source]({{< relref "../administration/data-source-management#add-a-data-source" >}}). The following topics will be of interest to you:
- [Panels and visualizations]({{< relref "../panels-visualizations/" >}})
- [Dashboards]({{< relref "../dashboards/" >}})
- [Keyboard shortcuts]({{< relref "../dashboards/use-dashboards/#keyboard-shortcuts" >}})
- [Plugins](https://grafana.com/grafana/plugins?orderBy=weight&direction=asc)
- [Panels and visualizations]({{< relref "../panels-visualizations" >}})
- [Dashboards]({{< relref "../dashboards" >}})
- [Keyboard shortcuts]({{< relref "../dashboards/use-dashboards#keyboard-shortcuts" >}})
- [Plugins](/grafana/plugins?orderBy=weight&direction=asc)
##### Admins
The following topics are of interest to Grafana server admin users:
- [Grafana configuration]({{< relref "../setup-grafana/configure-grafana/" >}})
- [Authentication]({{< relref "../setup-grafana/configure-security/configure-authentication/" >}})
- [User permissions and roles]({{< relref "../administration/roles-and-permissions/" >}})
- [Provisioning]({{< relref "../administration/provisioning/" >}})
- [Grafana CLI]({{< relref "../cli/" >}})
- [Grafana configuration]({{< relref "../setup-grafana/configure-grafana" >}})
- [Authentication]({{< relref "../setup-grafana/configure-security/configure-authentication" >}})
- [User permissions and roles]({{< relref "../administration/roles-and-permissions" >}})
- [Provisioning]({{< relref "../administration/provisioning" >}})
- [Grafana CLI]({{< relref "../cli" >}})
docs/sources/getting-started/get-started-grafana-prometheus.md
+11 -7
View File
@@ -38,7 +38,9 @@ Prometheus node_exporter is a widely used tool that exposes system metrics. For
When you run node_exporter locally, navigate to `http://localhost:9100/metrics` to check that it is exporting metrics.
> **Note**: The instructions in the referenced topic are intended for Linux users. You may have to alter the instructions slightly depending on your operating system. For example, if you are on Windows, use the [windows_exporter](https://github.com/prometheus-community/windows_exporter) instead.
{{% admonition type="note" %}}
The instructions in the referenced topic are intended for Linux users. You may have to alter the instructions slightly depending on your operating system. For example, if you are on Windows, use the [windows_exporter](https://github.com/prometheus-community/windows_exporter) instead.
{{% /admonition %}}
#### Install and configure Prometheus
@@ -82,11 +84,11 @@ You can see that the node_exporter metrics have been delivered to Prometheus. Ne
#### Configure Prometheus for Grafana
When running Prometheus locally, there are two ways to configure Prometheus for Grafana. You can use a hosted Grafana instance at [Grafana Cloud](https://grafana.com/) or run Grafana locally.
When running Prometheus locally, there are two ways to configure Prometheus for Grafana. You can use a hosted Grafana instance at [Grafana Cloud](/) or run Grafana locally.
This guide describes configuring Prometheus in a hosted Grafana instance on Grafana Cloud.
1. Sign up for [https://grafana.com/](https://grafana.com/auth/sign-up/create-user). Grafana gives you a Prometheus instance out of the box.
1. Sign up for [https://grafana.com/](/auth/sign-up/create-user). Grafana gives you a Prometheus instance out of the box.
![Prometheus details in Grafana.com](/static/img/docs/getting-started/screenshot-grafana-prometheus-details.png)
@@ -102,15 +104,17 @@ remote_write:
password: <Your Grafana.com API Key>
```
> **Note**: To configure your Prometheus instance to work with Grafana locally instead of Grafana Cloud, install Grafana [here](https://grafana.com/grafana/download) and follow the configuration steps listed [here](https://grafana.com/docs/grafana/latest/datasources/prometheus/#configure-the-data-source).
{{% admonition type="note" %}}
To configure your Prometheus instance to work with Grafana locally instead of Grafana Cloud, install Grafana [here](/grafana/download) and follow the configuration steps listed [here](/docs/grafana/latest/datasources/prometheus/#configure-the-data-source).
{{% /admonition %}}
#### Check Prometheus metrics in Grafana Explore view
In your Grafana instance, go to the [Explore]({{< relref "../explore/" >}}) view and build queries to experiment with the metrics you want to monitor. Here you can also debug issues related to collecting metrics from Prometheus. Pay special attention to the [Prometheus-specific features]({{< relref "../explore/#prometheus-specific-features" >}}) to avail custom querying experience for Prometheus.
In your Grafana instance, go to the [Explore]({{< relref "../explore" >}}) view and build queries to experiment with the metrics you want to monitor. Here you can also debug issues related to collecting metrics from Prometheus.
#### Start building dashboards
Now that you have a curated list of queries, create [dashboards]({{< relref "../dashboards/" >}}) to render system metrics monitored by Prometheus. When you install Prometheus and node_exporter or windows_exporter, you will find recommended dashboards for use.
Now that you have a curated list of queries, create [dashboards]({{< relref "../dashboards" >}}) to render system metrics monitored by Prometheus. When you install Prometheus and node_exporter or windows_exporter, you will find recommended dashboards for use.
The following image shows a dashboard with three panels showing some system metrics.
@@ -118,5 +122,5 @@ The following image shows a dashboard with three panels showing some system metr
To learn more:
- Grafana documentation: [Prometheus data source]({{< relref "../datasources/prometheus/" >}})
- Grafana documentation: [Prometheus data source]({{< relref "../datasources/prometheus" >}})
- Prometheus documentation: [What is Prometheus?](https://prometheus.io/docs/introduction/overview/)
docs/sources/old-alerting/_index.md
+3 -1
View File
@@ -8,7 +8,9 @@ weight: 114
Grafana Alerting is enabled by default for new OSS installations. For older installations, it is still an [opt-in]({{< relref "../unified-alerting/opt-in/" >}}) feature.
> **Note**: Legacy dashboard alerts are deprecated and will be removed in Grafana 9. We encourage you to migrate to [Grafana Alerting]({{< relref "../unified-alerting/" >}}) for all existing installations.
{{% admonition type="note" %}}
Legacy dashboard alerts are deprecated and will be removed in Grafana 9. We encourage you to migrate to [Grafana Alerting]({{< relref "../unified-alerting/" >}}) for all existing installations.
{{% /admonition %}}
Legacy dashboard alerts have two main components:
docs/sources/old-alerting/create-alerts.md
+3 -1
View File
@@ -46,7 +46,9 @@ This section describes the fields you fill out to create an alert.
You can set a minimum evaluation interval in the `alerting.min_interval_seconds` configuration field, to set a minimum time between evaluations. Refer to [Configuration]({{< relref "../../administration/configuration/" >}}#min-interval-seconds) for more information.
> **Caution:** Do not use `For` with the `If no data or all values are null` setting set to `No Data`. The triggering of `No Data` will trigger instantly and not take `For` into consideration. This may also result in that an OK notification not being sent if alert transitions from `No Data -> Pending -> OK`.
{{% admonition type="caution" %}}
Do not use `For` with the `If no data or all values are null` setting set to `No Data`. The triggering of `No Data` will trigger instantly and not take `For` into consideration. This may also result in that an OK notification not being sent if alert transitions from `No Data -Pending -OK`.
{{% /admonition %}}
If an alert rule has a configured `For` and the query violates the configured threshold, then it will first go from `OK` to `Pending`. Going from `OK` to `Pending` Grafana will not send any notifications. Once the alert rule has been firing for more than `For` duration, it will change to `Alerting` and send alert notifications.
docs/sources/old-alerting/notifications.md
+15 -5
View File
@@ -20,7 +20,9 @@ to add and configure a `notification` channel (can be email, PagerDuty, or other
This is done from the Notification channels page.
> **Note:** Alerting is only available in Grafana v4.0 and above.
{{% admonition type="note" %}}
Alerting is only available in Grafana v4.0 and above.
{{% /admonition %}}
## Add a notification channel
@@ -86,7 +88,9 @@ external image destination if available or fallback to attaching the image to th
Be aware that if you use the `local` image storage email servers and clients might not be
able to access the image.
> **Note:** Template variables are not supported in email alerts.
{{% admonition type="note" %}}
Template variables are not supported in email alerts.
{{% /admonition %}}
| Setting | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
@@ -128,7 +132,9 @@ To setup Opsgenie you will need an API Key and the Alert API Url. These can be o
| Override priority | Configures the alert priority using the `og_priority` tag. The `og_priority` tag must have one of the following values: `P1`, `P2`, `P3`, `P4`, or `P5`. Default is `False`. |
| Send notification tags as | Specify how you would like [Notification Tags]({{< relref "create-alerts/#notifications" >}}) delivered to Opsgenie. They can be delivered as `Tags`, `Extra Properties` or both. Default is Tags. See note below for more information. |
> **Note:** When notification tags are sent as `Tags` they are concatenated into a string with a `key:value` format. If you prefer to receive the notifications tags as key/values under Extra Properties in Opsgenie then change the `Send notification tags as` to either `Extra Properties` or `Tags & Extra Properties`.
{{% admonition type="note" %}}
When notification tags are sent as `Tags` they are concatenated into a string with a `key:value` format. If you prefer to receive the notifications tags as key/values under Extra Properties in Opsgenie then change the `Send notification tags as` to either `Extra Properties` or `Tags & Extra Properties`.
{{% /admonition %}}
### PagerDuty
@@ -261,7 +267,9 @@ Notifications can be sent by setting up an incoming webhook in Google Hangouts c
Alertmanager handles alerts sent by client applications such as Prometheus server or Grafana. It takes care of deduplicating, grouping, and routing them to the correct receiver. Grafana notifications can be sent to Alertmanager via a simple incoming webhook. Refer to the official [Prometheus Alertmanager documentation](https://prometheus.io/docs/alerting/alertmanager) for configuration information.
> **Caution:** In case of a high-availability setup, do not load balance traffic between Grafana and Alertmanagers to keep coherence between all your Alertmanager instances. Instead, point Grafana to a list of all Alertmanagers, by listing their URLs comma-separated in the notification channel configuration.
{{% admonition type="caution" %}}
In case of a high-availability setup, do not load balance traffic between Grafana and Alertmanagers to keep coherence between all your Alertmanager instances. Instead, point Grafana to a list of all Alertmanagers, by listing their URLs comma-separated in the notification channel configuration.
{{% /admonition %}}
### Sensu Go
@@ -283,6 +291,8 @@ This URL is based on the [domain]({{< relref "../../administration/configuration
## Notification templating
> **Note:** Alert notification templating is only available in Grafana v7.4 and above.
{{% admonition type="note" %}}
Alert notification templating is only available in Grafana v7.4 and above.
{{% /admonition %}}
The alert notification template feature allows you to take the [label]({{< relref "../../basics/timeseries-dimensions/#labels" >}}) value from an alert query and [inject that into alert notifications]({{< relref "add-notification-template/" >}}).
docs/sources/panels-visualizations/configure-data-links/index.md
+3 -1
View File
@@ -28,7 +28,9 @@ You can use variables in data links to refer to series fields, labels, and value
To see a list of available variables, type `$` in the data link **URL** field to see a list of variables that you can use.
> **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 type="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 %}}
You can also use template variables in your data links URLs, refer to [Templates and variables]({{< relref "../../dashboards/variables/" >}}) for more information on template variables.
docs/sources/panels-visualizations/configure-legend/index.md
+3 -1
View File
@@ -71,6 +71,8 @@ You can change legend mode to **Table** and choose [calculations]({{< relref "..
The sort order affects the positions of the bars in the Bar chart panel as well as the order of stacked series in the Time series and Bar chart panels.
> **Note:** This feature is only supported in these panels: Bar chart, Histogram, Time series, XY Chart.
{{% admonition type="note" %}}
This feature is only supported in these panels: Bar chart, Histogram, Time series, XY Chart.
{{% /admonition %}}
![Sort legend series](/static/img/docs/legend/legend-series-sort-8-3.png).
docs/sources/panels-visualizations/configure-panel-options/index.md
+3 -1
View File
@@ -80,7 +80,9 @@ Explore and export panel, panel data, and data frame JSON models.
You can configure Grafana to dynamically add panels or rows to a dashboard. A dynamic panel is a panel that the system creates based on the value of a variable. Variables dynamically change your queries across all panels in a dashboard. For more information about repeating rows, refer to [Configure repeating rows](../add-organize-panels/#configure-repeating-rows).
> **Note:** Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
{{% admonition type="note" %}}
Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
{{% /admonition %}}
To see an example of repeating panels, refer to [Prometheus dashboard with repeating panels](https://play.grafana.org/d/000000036/prometheus-repeat).
docs/sources/panels-visualizations/configure-standard-options/index.md
+3 -1
View File
@@ -45,7 +45,9 @@ You can apply standard options to most built-in Grafana panels. Some older panel
Most field options will not affect the visualization until you click outside of the field option box you are editing or press Enter.
> **Note:** We are constantly working to add and expand options for all visualization, so all options might not be available for all visualizations.
{{% admonition type="note" %}}
We are constantly working to add and expand options for all visualization, so all options might not be available for all visualizations.
{{% /admonition %}}
### Unit
docs/sources/panels-visualizations/configure-value-mappings/index.md
+3 -1
View File
@@ -24,7 +24,9 @@ Values mapped via value mappings bypass the unit formatting. This means that a t
If value mappings are present in a panel, then Grafana displays a summary in the side pane of the panel editor.
> **Note:** The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap.
{{% admonition type="note" %}}
The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap.
{{% /admonition %}}
## Types of value mappings
docs/sources/panels-visualizations/panel-editor-overview/index.md
+15 -4
View File
@@ -24,13 +24,20 @@ weight: 1
# Panel editor overview
{{< figure src="/static/img/docs/panel-editor/panel-editor-8-0.png" class="docs-image--no-shadow" max-width="1500px" >}}
In the panel editor, you can update all the elements of a visualization including the data source, queries, time range, and visualization display options.
![Panel editor](/media/docs/grafana/panels-visualizations/screenshot-panel-editor-view.png)
To add a panel in a new dashboard click **+ Add visualization** in the middle of the dashboard. To add a panel to an existing dashboard, click **Add** in the dashboard header and select **Visualization** in the dropdown:
![Add dropdown](/media/docs/grafana/dashboards/screenshot-add-dropdown-9.5.png)
## Panel editor
This section describes the areas of the Grafana panel editor.
1. Panel header: The header section lists the dashboard in which the panel appears and the following controls:
- **Dashboard settings (gear) icon:** Click to access the dashboard settings.
- **Discard:** Discards changes you have made to the panel since you last saved the dashboard.
- **Save:** Saves changes you made to the panel.
- **Apply:** Applies changes you made and closes the panel editor, returning you to the dashboard. You will have to save the dashboard to persist the applied changes.
@@ -50,11 +57,15 @@ This section describes the areas of the Grafana panel editor.
1. Panel display options: The display options section contains tabs where you configure almost every aspect of your data visualization.
## Open the panel inspect drawer
## Panel inspect drawer
The inspect drawer helps you understand and troubleshoot your panels. You can view the raw data for any panel, export that data to a comma-separated values (CSV) file, view query requests, and export panel and data JSON.
> **Note:** Not all panel types include all tabs. For example, dashboard list panels do not have raw data to inspect, so they do not display the Stats, Data, or Query tabs.
To access the panel inspect drawer from the edit view, hover over any part of the panel to display the actions menu on the top right corner. Click the menu and select **Inspect**.
{{% admonition type="note" %}}
Not all panel types include all tabs. For example, dashboard list panels do not have raw data to inspect, so they do not display the Stats, Data, or Query tabs.
{{% /admonition %}}
The panel inspector consists of the following options:
docs/sources/panels-visualizations/query-transform-data/expression-queries/index.md
+9 -3
View File
@@ -21,11 +21,15 @@ Server-side expressions allow you to manipulate data returned from queries with
Expressions are primarily used by [Grafana Alerting]({{< relref "../../../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.
> **Note:** Expressions do not work with legacy dashboard alerts.
{{% admonition type="note" %}}
Expressions do not work with legacy dashboard alerts.
{{% /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.
> **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 type="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 %}}
Expressions work with data source queries that return time series or number data. They also operate on [multiple-dimensional data]({{< relref "../../../fundamentals/timeseries-dimensions/" >}}). For example, a query that returns multiple series, where each series is identified by labels or tags.
@@ -111,7 +115,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)`.
> **Note:** If you need to specifically check for negative infinity for example, you can do a comparison like `$A == infn()`.
{{% admonition type="note" %}}
If you need to specifically check for negative infinity for example, you can do a comparison like `$A == infn()`.
{{% /admonition %}}
###### is_nan
docs/sources/panels-visualizations/query-transform-data/transform-data/index.md
+23 -5
View File
@@ -47,7 +47,8 @@ The order in which Grafana applies transformations directly impacts the results.
The following steps guide you in adding a transformation to data. This documentation does not include steps for each type of transformation. For a complete list of transformations, refer to [Transformation functions]({{< relref "#transformation-functions" >}}).
1. Navigate to the panel where you want to add one or more transformations.
1. Click the panel title and then click **Edit**.
1. Hover over any part of the panel to display the actions menu on the top right corner.
1. Click the menu and select **Edit**.
1. Click the **Transform** tab.
1. Click a transformation.
A transformation row appears where you configure the transformation options. For more information about how to configure a transformation, refer to [Transformation functions]({{< relref "#transformation-functions" >}}).
@@ -89,6 +90,7 @@ Use this transformation to add a new field calculated from two other fields. Eac
- **Mode -** Select a mode:
- **Reduce row -** Apply selected calculation on each row of selected fields independently.
- **Binary option -** Apply basic math operation(sum, multiply, etc) on values in a single row from two selected fields.
- **Index -** Will insert a field with the row index.
- **Field name -** Select the names of fields you want to use in the calculation for the new field.
- **Calculation -** If you select **Reduce row** mode, then the **Calculation** field appears. Click in the field to see a list of calculation choices you can use to create the new field. For information about available calculations, refer to [Calculation types]({{< relref "../../calculation-types" >}}).
- **Operation -** If you select **Binary option** mode, then the **Operation** fields appear. These fields allow you to do basic math operations on values in a single row from two selected fields. You can also use numerical values for binary operations.
@@ -198,7 +200,9 @@ In the example below, the panel has three queries (A, B, C). I removed the B que
{{< figure src="/static/img/docs/transformations/filter-by-query-stat-example-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
> **Note:** This transformation is not available for Graphite because this data source does not support correlating returned data with queries.
{{% admonition type="note" %}}
This transformation is not available for Graphite because this data source does not support correlating returned data with queries.
{{% /admonition %}}
### Filter data by value
@@ -488,7 +492,9 @@ Here is the result after applying the Merge transformation.
Use this transformation to rename, reorder, or hide fields returned by the query.
> **Note:** This transformation only works in panels with a single query. If your panel has multiple queries, then you must either apply an Outer join transformation or remove the extra queries.
{{% admonition type="note" %}}
This transformation only works in panels with a single query. If your panel has multiple queries, then you must either apply an Outer join transformation or remove the extra queries.
{{% /admonition %}}
Grafana displays a list of fields returned by the query. You can:
@@ -659,7 +665,9 @@ As you can see each row in the source data becomes a separate field. Each field
### Prepare time series
> **Note:** This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
{{% admonition type="note" %}}
This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
{{% /admonition %}}
Prepare time series transformation is useful when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames]({{< relref "../../../developers/plugins/data-frames/" >}}).
@@ -671,7 +679,9 @@ Select the `Wide time series` option to transform the time series data frame fro
### Series to rows
> **Note:** This transformation is available in Grafana 7.1+.
{{% admonition type="note" %}}
This transformation is available in Grafana 7.1+.
{{% /admonition %}}
Use this transformation to combine the result from multiple time series data queries into one single result. This is helpful when using the table panel visualization.
@@ -732,3 +742,11 @@ Here is the result after adding a Limit transformation with a value of '3':
| 2020-07-07 11:34:20 | Temperature | 25 |
| 2020-07-07 11:34:20 | Humidity | 22 |
| 2020-07-07 10:32:20 | Humidity | 29 |
### Time series to table transform
{{% admonition type="note" %}}
This transformation is available in Grafana 9.5+ as an opt-in beta feature. Modify Grafana [configuration file]({{< relref "../../../setup-grafana/configure-grafana/#configuration-file-location" >}}) to enable the `timeSeriesTable` [feature toggle]({{< relref "../../../setup-grafana/configure-grafana/#feature_toggles" >}}) to use it.
{{% /admonition %}}
Use this transformation to convert time series result into a table, converting time series data frame into a "Trend" field. "Trend" field can then be rendered using [sparkline cell type]({{< relref "../../visualizations/table/#sparkline" >}}), producing an inline sparkline for each table row. If there are multiple time series queries, each will result in a separate table data frame. These can be joined using join or merge transforms to produce a single table with multiple sparklines per row.
docs/sources/panels-visualizations/visualizations/_index.md
+3 -1
View File
@@ -14,7 +14,9 @@ weight: 75
Grafana offers a variety of visualizations to support different use cases. This section of the documentation highlights the built-in panels, their options and typical usage.
> **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.
{{% admonition type="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.
{{% /admonition %}}
- Graphs & charts
- [Time series]({{< relref "time-series/" >}}) is the default and main Graph visualization.
docs/sources/panels-visualizations/visualizations/annotations/index.md
+3 -1
View File
@@ -39,7 +39,9 @@ Use the time range option to specify whether the list should be limited to the c
Use the tags option to filter the annotations by tags. You can add multiple tags in order to refine the list.
> **Note:** Optionally, leave the tag list empty and filter on the fly by selecting tags that are listed as part of the results on the panel itself.
{{% admonition type="note" %}}
Optionally, leave the tag list empty and filter on the fly by selecting tags that are listed as part of the results on the panel itself.
{{% /admonition %}}
### Limit
docs/sources/panels-visualizations/visualizations/candlestick/index.md
+3 -1
View File
@@ -48,7 +48,9 @@ The **Up color** and **Down color** options select which colors are used when th
The candlestick panel will attempt to map fields to the appropriate dimension. The **Open**, **High**, **Low**, and **Close** options allow you to map your data to these dimensions if the panel is unable to do so.
> **Note**: These values are hidden from the legend.
{{% admonition type="note" %}}
These values are hidden from the legend.
{{% /admonition %}}
- **Open** corresponds to the starting value of the given period.
- **High** corresponds to the highest value of the given period.
docs/sources/panels-visualizations/visualizations/geomap/index.md
+9 -3
View File
@@ -88,7 +88,9 @@ There are also five alpha layer types.
- **Route (alpha)** render data points as a route.
- [Photos layer (Alpha)]({{< relref "#photos-layer-alpha" >}}) renders a photo at each data point.
> **Note:** [Basemap layer types]({{< relref "#types-1" >}}) can also be added as layers. You can specify an opacity.
{{% admonition type="note" %}}
[Basemap layer types]({{< relref "#types-1" >}}) can also be added as layers. You can specify an opacity.
{{% /admonition %}}
### Layer Controls
@@ -410,7 +412,9 @@ Displays scale information in the bottom left corner.
{{< figure src="/static/img/docs/geomap-panel/geomap-map-controls-scale-9-1-0.png" max-width="1200px" caption="Geomap panel scale" >}}
> **Note:** Currently only displays units in [m]/[km].
{{% admonition type="note" %}}
Currently only displays units in [m]/[km].
{{% /admonition %}}
### Show measure tools
@@ -422,7 +426,9 @@ Displays measure tools in the upper right corner. Measurements appear only when
- **Continue clicking** to continue measurement
- **Double-click** to end measurement
> **Note:** <br /> - When you change measurement type or units, the previous measurement is removed from the map. <br /> - If the control is closed and then re-opened, the most recent measurement is displayed. <br /> - A measurement can be modified by clicking and dragging on it.
{{% admonition type="note" %}}
<br /- When you change measurement type or units, the previous measurement is removed from the map. <br /- If the control is closed and then re-opened, the most recent measurement is displayed. <br /- A measurement can be modified by clicking and dragging on it.
{{% /admonition %}}
#### Length

Some files were not shown because too many files have changed in this diff Show More