Docs: Sync all doc changes in main to v8.0.x (#35333)
This commit is contained in:
Torkel Ödegaard
+1
-1
@@ -15,7 +15,7 @@ docs-quick: pull
|
||||
docker run -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) /bin/bash -c "ln -s /frontend-docs/packages_api /hugo/content/docs/grafana/next/packages_api && make server-quick"
|
||||
|
||||
docs-no-pull:
|
||||
docker run -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) /bin/bash -c "make server-quick"
|
||||
docker run -v $(shell pwd)/sources:$(CONTENT_PATH):Z -p $(PORT) --rm -it $(IMAGE) /bin/bash -c "make server"
|
||||
|
||||
docs-test: pull
|
||||
docker run -v $(shell pwd)/sources:$(CONTENT_PATH):Z --rm -it $(IMAGE) /bin/bash -c 'make prod'
|
||||
|
||||
@@ -64,8 +64,8 @@ aliases = ["/docs/grafana/v1.1", "/docs/grafana/latest/guides/reference/admin",
|
||||
<h4>Provisioning</h4>
|
||||
<p>Learn how to automate your Grafana configuration.</p>
|
||||
</a>
|
||||
<a href="{{< relref "whatsnew/whats-new-in-v7-5.md" >}}" class="nav-cards__item nav-cards__item--guide">
|
||||
<h4>What's new in v7.5</h4>
|
||||
<a href="{{< relref "whatsnew/whats-new-in-v8-0.md" >}}" class="nav-cards__item nav-cards__item--guide">
|
||||
<h4>What's new in v8.0</h4>
|
||||
<p>Explore the features and enhancements in the latest release.</p>
|
||||
</a>
|
||||
|
||||
|
||||
@@ -1487,6 +1487,20 @@ Custom install/learn more URL for enterprise plugins. Defaults to https://grafan
|
||||
|
||||
<hr>
|
||||
|
||||
## [live]
|
||||
|
||||
### max_connections
|
||||
|
||||
> **Note**: Available in Grafana v8.0 and later versions.
|
||||
|
||||
The `max_connections` option specifies the maximum number of connections to the Grafana Live WebSocket endpoint per Grafana server instance. Default is `100`.
|
||||
|
||||
Refer to [Grafana Live configuration documentation]({{< relref "../live/configure-grafana-live.md" >}}) if you specify a number higher than default since this can require some operating system and infrastructure tuning.
|
||||
|
||||
0 disables Grafana Live, -1 means unlimited connections.
|
||||
|
||||
<hr>
|
||||
|
||||
## [plugin.grafana-image-renderer]
|
||||
|
||||
For more information, refer to [Image rendering]({{< relref "image_rendering.md" >}}).
|
||||
|
||||
@@ -7,7 +7,7 @@ weight = 300
|
||||
|
||||
# Image rendering
|
||||
|
||||
Grafana supports automatic rendering of panels as PNG images. This allows Grafana to automatically generate images of your panels to include in [alert notifications]({{< relref "../alerting/notifications.md" >}}).
|
||||
Grafana supports automatic rendering of panels as PNG images. This allows Grafana to automatically generate images of your panels to include in [alert notifications]({{< relref "../alerting/old-alerting/notifications.md" >}}).
|
||||
|
||||
>**Note:** Image rendering of dashboards is not supported at this time.
|
||||
|
||||
@@ -150,7 +150,7 @@ ldd chrome-linux/chrome
|
||||
On Ubuntu 18.10 the following dependencies have been confirmed as needed for the image rendering to function.
|
||||
|
||||
```bash
|
||||
libx11-6 libx11-xcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrender1 libxtst6 libglib2.0-0 libnss3 libcups2 libdbus-1-3 libxss1 libxrandr2 libgtk-3-0 libgtk-3-0 libasound2
|
||||
libx11-6 libx11-xcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrender1 libxtst6 libglib2.0-0 libnss3 libcups2 libdbus-1-3 libxss1 libxrandr2 libgtk-3-0 libgtk-3-0 libasound2 libxcb-dri3-0 libgbm1
|
||||
```
|
||||
|
||||
**Debian:**
|
||||
@@ -172,7 +172,7 @@ libxdamage1 libxext6 libxi6 libxtst6 libnss3 libnss3 libcups2 libxss1 libxrandr2
|
||||
On a minimal Centos installation, the following dependencies have been confirmed as needed for the image rendering to function:
|
||||
|
||||
```bash
|
||||
libXcomposite libXdamage libXtst cups libXScrnSaver pango atk adwaita-cursor-theme adwaita-icon-theme at at-spi2-atk at-spi2-core cairo-gobject colord-libs dconf desktop-file-utils ed emacs-filesystem gdk-pixbuf2 glib-networking gnutls gsettings-desktop-schemas gtk-update-icon-cache gtk3 hicolor-icon-theme jasper-libs json-glib libappindicator-gtk3 libdbusmenu libdbusmenu-gtk3 libepoxy liberation-fonts liberation-narrow-fonts liberation-sans-fonts liberation-serif-fonts libgusb libindicator-gtk3 libmodman libproxy libsoup libwayland-cursor libwayland-egl libxkbcommon m4 mailx nettle patch psmisc redhat-lsb-core redhat-lsb-submod-security rest spax time trousers xdg-utils xkeyboard-config
|
||||
libXcomposite libXdamage libXtst cups libXScrnSaver pango atk adwaita-cursor-theme adwaita-icon-theme at at-spi2-atk at-spi2-core cairo-gobject colord-libs dconf desktop-file-utils ed emacs-filesystem gdk-pixbuf2 glib-networking gnutls gsettings-desktop-schemas gtk-update-icon-cache gtk3 hicolor-icon-theme jasper-libs json-glib libappindicator-gtk3 libdbusmenu libdbusmenu-gtk3 libepoxy liberation-fonts liberation-narrow-fonts liberation-sans-fonts liberation-serif-fonts libgusb libindicator-gtk3 libmodman libproxy libsoup libwayland-cursor libwayland-egl libxkbcommon m4 mailx nettle patch psmisc redhat-lsb-core redhat-lsb-submod-security rest spax time trousers xdg-utils xkeyboard-config alsa-lib
|
||||
```
|
||||
|
||||
### Certificate signed by internal certificate authorities
|
||||
|
||||
@@ -583,3 +583,9 @@ The following sections detail the supported settings and secure settings for eac
|
||||
| Name |
|
||||
| ---- |
|
||||
| url |
|
||||
|
||||
## Grafana Enterprise
|
||||
|
||||
Grafana Enterprise supports provisioning for the following resources:
|
||||
|
||||
- [Access Control Provisioning]({{< relref "../enterprise/access-control/provisioning.md" >}})
|
||||
|
||||
@@ -22,7 +22,7 @@ Grafana will now persist all long term data in the database. How to configure th
|
||||
|
||||
## Alerting
|
||||
|
||||
Currently alerting supports a limited form of high availability. [Alert notifications]({{< relref "../alerting/notifications.md" >}}) are deduplicated when running multiple servers. This means all alerts are executed on every server but alert notifications are only sent once per alert. Grafana does not support load distribution between servers.
|
||||
Currently alerting supports a limited form of high availability. [Alert notifications]({{< relref "../alerting/old-alerting/notifications.md" >}}) are deduplicated when running multiple servers. This means all alerts are executed on every server but alert notifications are only sent once per alert. Grafana does not support load distribution between servers.
|
||||
|
||||
## User sessions
|
||||
|
||||
|
||||
@@ -19,10 +19,10 @@ Currently only the graph panel visualization supports alerts.
|
||||
|
||||
You can perform the following tasks for alerts:
|
||||
|
||||
- [Add or edit an alert notification channel]({{< relref "notifications.md" >}})
|
||||
- [Create an alert rule]({{< relref "create-alerts.md" >}})
|
||||
- [View existing alert rules and their current state]({{< relref "view-alerts.md" >}})
|
||||
- [Test alert rules and troubleshoot]({{< relref "troubleshoot-alerts.md" >}})
|
||||
- [Add or edit an alert notification channel]({{< relref "./old-alerting/notifications.md" >}})
|
||||
- [Create an alert rule]({{< relref "./old-alerting/create-alerts.md" >}})
|
||||
- [View existing alert rules and their current state]({{< relref "./old-alerting/view-alerts.md" >}})
|
||||
- [Test alert rules and troubleshoot]({{< relref "./old-alerting/troubleshoot-alerts.md" >}})
|
||||
|
||||
## Clustering
|
||||
|
||||
@@ -39,7 +39,7 @@ The actual notifications are configured and shared between multiple alerts.
|
||||
Alert rules are evaluated in the Grafana backend in a scheduler and query execution engine that is part
|
||||
of core Grafana. Alert rules can query only backend data sources with alerting enabled. Such data sources are:
|
||||
- builtin or developed and maintained by grafana, such as: `Graphite`, `Prometheus`, `Loki`, `InfluxDB`, `Elasticsearch`,
|
||||
`Google Cloud Monitoring`, `Cloudwatch`, `Azure Monitor`, `MySQL`, `PostgreSQL`, `MSSQL`, `OpenTSDB`, `Oracle`, and `Azure Data Explorer`
|
||||
`Google Cloud Monitoring`, `Cloudwatch`, `Azure Monitor`, `MySQL`, `PostgreSQL`, `MSSQL`, `OpenTSDB`, `Oracle`, and `Azure Data Explorer`
|
||||
- any community backend data sources with alerting enabled (`backend` and `alerting` properties are set in the [plugin.json]({{< relref "../developers/plugins/metadata.md" >}}))
|
||||
|
||||
## Metrics from the alert engine
|
||||
|
||||
@@ -1,18 +1,21 @@
|
||||
+++
|
||||
title = "Difference between new and old alerts"
|
||||
description = "Pause an existing alert rule"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "view"]
|
||||
weight = 400
|
||||
title = "What's New with Grafana 8 Alerts"
|
||||
description = "What's New with Grafana 8 Alerts"
|
||||
keywords = ["grafana", "alerting", "guide"]
|
||||
weight = 112
|
||||
+++
|
||||
|
||||
# Difference between new and old alerts
|
||||
# Differences between Grafana 8 alerts and legacy alerts
|
||||
The Alerts released with Grafana 8.0 are an opt-in feature that centralizes alerting information for Grafana managed alerts and alerts from Prometheus-compatible datasources in one UI and API. You are able to create and edit alerting rules for Grafana managed alerts, Cortex alerts, and Loki alerts as well as see alerting information from prometheus-compatible datasources in a single, searchable view.
|
||||
|
||||
The `ngalert` feature toggle enables the beta version of our new alerting system.
|
||||
## Multi-dimensional alerting
|
||||
Create alerts that will give you system-wide visibility with a single alerting rule. With Grafana 8 alerts, you are able to generate multiple alert instances from a single rule eg. creating a rule to monitor disk usage for multiple mount points on a single host. The evaluation engine is able to return multiple time series from a single query. Each time series is identified by its label set.
|
||||
|
||||
>**Note:** It is recommended to backup Grafana's database before enabling this feature.
|
||||
## Create alerts outside of Dashboards
|
||||
Grafana legacy alerts were tied to a dashboard. Grafana 8 Alerts allow you to create queries and expressions that can combine data from multiple sources, in unique ways. You are still able to link dashboards and panels to alerting rules, allowing you to quickly troubleshoot the system under observation, by linking a dashboard and/or panel ID to the alerting rule.
|
||||
|
||||
When the feature flag is enabled, dashboard alerting is disabled and dashboard alerts are migrated into the system. Going to "Alert List" will take you to the new system.
|
||||
## Create Loki and Cortex alerting rules
|
||||
With Grafana 8 Alerts you are able to manage your Loki and Cortex alerting rules using the same UI and API as your Grafana managed alerts.
|
||||
|
||||
Once you disable the new alters, all migrated and newly created alerts in the new system are deleted, and dashboard alerting will be enabled again.
|
||||
|
||||
During beta, the migration of existing dashboard rules may change.
|
||||
## View and search for alerts from Prometheus
|
||||
You can now display all of your alerting information in one, searchable UI. Alerts for Prometheus compatible datasources are listed below Grafana managed alerts. Search for labels across multiple datasources to quickly find all of the relevant alerts.
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
+++
|
||||
title = "Old Grafana Alerts"
|
||||
aliases = ["/docs/grafana/latest/alerting/rules/", "/docs/grafana/latest/alerting/metrics/"]
|
||||
weight = 114
|
||||
+++
|
||||
|
||||
# Old Grafana alerts
|
||||
|
||||
Alerts allow you to know about problems in your systems moments after they occur. Robust and actionable alerts help you identify and resolve issues quickly, minimizing disruption to your services.
|
||||
|
||||
Alerts have four main components:
|
||||
|
||||
- Alert rule - One or more conditions, the frequency of evaluation, and the (optional) duration that a condition must be met before notifying.
|
||||
- Contact point - A channel for sending notifications when the conditions of an alert rule are met.
|
||||
- Notification policy - A set of matching and grouping criteria used to determine where, and how frequently, to send notifications.
|
||||
- Silences - Date and matching criteria used to silence notifications.
|
||||
|
||||
## Alert tasks
|
||||
|
||||
You can perform the following tasks for alerts:
|
||||
|
||||
- [Create an alert rule]({{< relref "create-alerts.md" >}})
|
||||
- [View existing alert rules and their current state]({{< relref "view-alerts.md" >}})
|
||||
- [Test alert rules and troubleshoot]({{< relref "troubleshoot-alerts.md" >}})
|
||||
- [Add or edit an alert contact point]({{< relref "notifications.md" >}})
|
||||
|
||||
## Clustering
|
||||
|
||||
Currently alerting supports a limited form of high availability. Since v4.2.0 of Grafana, alert notifications are deduped when running multiple servers. This means all alerts are executed on every server but no duplicate alert notifications are sent due to the deduping logic. Proper load balancing of alerts will be introduced in the future.
|
||||
|
||||
## Alert evaluation
|
||||
|
||||
Grafana managed alerts are evaluated by the Grafana backend. Rule evaluations are scheduled, according to the alert rule configuration, and queries are evaluated by an engine that is part of core Grafana.
|
||||
|
||||
Alert rules can only query backend data sources with alerting enabled:
|
||||
- builtin or developed and maintained by grafana: `Graphite`, `Prometheus`, `Loki`, `InfluxDB`, `Elasticsearch`,
|
||||
`Google Cloud Monitoring`, `Cloudwatch`, `Azure Monitor`, `MySQL`, `PostgreSQL`, `MSSQL`, `OpenTSDB`, `Oracle`, and `Azure Data Explorer`
|
||||
- any community backend data sources with alerting enabled (`backend` and `alerting` properties are set in the [plugin.json]({{< relref "../../developers/plugins/metadata.md" >}}))
|
||||
|
||||
## Metrics from the alert engine
|
||||
|
||||
The alert engine publishes some internal metrics about itself. You can read more about how Grafana publishes [internal metrics]({{< relref "../../administration/view-server/internal-metrics.md" >}}).
|
||||
|
||||
Metric Name | Type | Description
|
||||
---------- | ----------- | ----------
|
||||
`alerting.alerts` | gauge | How many alerts by state
|
||||
`alerting.request_duration_seconds` | histogram | Histogram of requests to the Alerting API
|
||||
`alerting.active_configurations` | gauge | The number of active, non default alertmanager configurations for grafana managed alerts
|
||||
`alerting.rule_evaluations_total` | counter | The total number of rule evaluations
|
||||
`alerting.rule_evaluation_failures_total` | counter | The total number of rule evaluation failures
|
||||
`alerting.rule_evaluation_duration_seconds` | summary | The duration for a rule to execute
|
||||
`alerting.rule_group_rules` | gauge | The number of rules
|
||||
@@ -0,0 +1,23 @@
|
||||
+++
|
||||
title = "Alert notification templating"
|
||||
keywords = ["grafana", "documentation", "alerting", "alerts", "notification", "templating"]
|
||||
weight = 110
|
||||
+++
|
||||
|
||||
# Alert notification templating
|
||||
|
||||
You can provide detailed information to alert notification recipients by injecting alert query data into an alert notification. This topic explains how you can use alert query labels in alert notifications.
|
||||
|
||||
Labels that exist from the evaluation of the alert query can be used in the alert rule name and in the alert notification message fields. The alert label data is injected into the notification fields when the alert is in the alerting state. When there are multiple unique values for the same label, the values are comma-separated.
|
||||
|
||||
This topic explains how you can use alert query labels in alert notifications.
|
||||
|
||||
## Adding alert label data into your alert notification
|
||||
|
||||
1. Navigate to the panel you want to add or edit an alert rule for.
|
||||
1. Click on the panel title, and then click **Edit**.
|
||||
1. On the Alert tab, click **Create Alert**. If an alert already exists for this panel, then you can edit the alert directly.
|
||||
1. Refer to the alert query labels in the alert rule name and/or alert notification message field by using the `${Label}` syntax.
|
||||
1. Click **Save** in the upper right corner to save the alert rule and the dashboard.
|
||||
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
+++
|
||||
title = "Create alerts"
|
||||
description = "Configure alert rules"
|
||||
keywords = ["grafana", "alerting", "guide", "rules"]
|
||||
weight = 200
|
||||
+++
|
||||
|
||||
# Create alerts
|
||||
|
||||
Grafana alerting allows you to attach rules to your dashboard panels. When you save the dashboard, Grafana extracts the alert rules into a separate alert rule storage and schedules them for evaluation.
|
||||
|
||||
|
||||
|
||||
In the Alert tab of the graph panel you can configure how often the alert rule should be evaluated and the conditions that need to be met for the alert to change state and trigger its [notifications]({{< relref "notifications.md" >}}).
|
||||
|
||||
Currently only the graph panel supports alert rules.
|
||||
|
||||
## Add or edit an alert rule
|
||||
|
||||
1. Navigate to the panel you want to add or edit an alert rule for, click the title, and then click **Edit**.
|
||||
1. On the Alert tab, click **Create Alert**. If an alert already exists for this panel, then you can just edit the fields on the Alert tab.
|
||||
1. Fill out the fields. Descriptions are listed below in [Alert rule fields](#alert-rule-fields).
|
||||
1. When you have finished writing your rule, click **Save** in the upper right corner to save alert rule and the dashboard.
|
||||
1. (Optional but recommended) Click **Test rule** to make sure the rule returns the results you expect.
|
||||
|
||||
## Delete an alert
|
||||
|
||||
To delete an alert, scroll to the bottom of the alert and then click **Delete**.
|
||||
|
||||
## Alert rule fields
|
||||
|
||||
This section describes the fields you fill out to create an alert.
|
||||
|
||||
### Rule
|
||||
|
||||
- **Name -** Enter a descriptive name. The name will be displayed in the Alert Rules list. This field supports [templating]({{< relref "./add-notification-template.md" >}}).
|
||||
- **Evaluate every -** Specify how often the scheduler should evaluate the alert rule. This is referred to as the _evaluation interval_.
|
||||
- **For -** Specify how long the query needs to violate the configured thresholds before the alert notification triggers.
|
||||
|
||||
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.md" >}}#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`.
|
||||
|
||||
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.
|
||||
|
||||
Typically, it's always a good idea to use this setting since it's often worse to get false positive than wait a few minutes before the alert notification triggers. Looking at the `Alert list` or `Alert list panels` you will be able to see alerts in pending state.
|
||||
|
||||
Below you can see an example timeline of an alert using the `For` setting. At ~16:04 the alert state changes to `Pending` and after 4 minutes it changes to `Alerting` which is when alert notifications are sent. Once the series falls back to normal the alert rule goes back to `OK`.
|
||||
{{< figure class="float-right" src="/static/img/docs/v54/alerting-for-dark-theme.png" caption="Alerting For" >}}
|
||||
|
||||
{{< figure class="float-right" max-width="40%" src="/static/img/docs/v4/alerting_conditions.png" caption="Alerting Conditions" >}}
|
||||
|
||||
### Conditions
|
||||
|
||||
Currently the only condition type that exists is a `Query` condition that allows you to
|
||||
specify a query letter, time range and an aggregation function.
|
||||
|
||||
#### Query condition example
|
||||
|
||||
```sql
|
||||
avg() OF query(A, 15m, now) IS BELOW 14
|
||||
```
|
||||
|
||||
- `avg()` Controls how the values for **each** series should be reduced to a value that can be compared against the threshold. Click on the function to change it to another aggregation function.
|
||||
- `query(A, 15m, now)` The letter defines what query to execute from the **Metrics** tab. The second two parameters define the time range, `15m, now` means 15 minutes ago to now. You can also do `10m, now-2m` to define a time range that will be 10 minutes ago to 2 minutes ago. This is useful if you want to ignore the last 2 minutes of data.
|
||||
- `IS BELOW 14` Defines the type of threshold and the threshold value. You can click on `IS BELOW` to change the type of threshold.
|
||||
|
||||
The query used in an alert rule cannot contain any template variables. Currently we only support `AND` and `OR` operators between conditions and they are executed serially.
|
||||
For example, we have 3 conditions in the following order:
|
||||
_condition:A(evaluates to: TRUE) OR condition:B(evaluates to: FALSE) AND condition:C(evaluates to: TRUE)_
|
||||
so the result will be calculated as ((TRUE OR FALSE) AND TRUE) = TRUE.
|
||||
|
||||
We plan to add other condition types in the future, like `Other Alert`, where you can include the state of another alert in your conditions, and `Time Of Day`.
|
||||
|
||||
#### Multiple Series
|
||||
|
||||
If a query returns multiple series, then the aggregation function and threshold check will be evaluated for each series. What Grafana does not do currently is track alert rule state **per series**. This has implications that are detailed in the scenario below.
|
||||
|
||||
- Alert condition with query that returns 2 series: **server1** and **server2**
|
||||
- **server1** series causes the alert rule to fire and switch to state `Alerting`
|
||||
- Notifications are sent out with message: _load peaking (server1)_
|
||||
- In a subsequent evaluation of the same alert rule, the **server2** series also causes the alert rule to fire
|
||||
- No new notifications are sent as the alert rule is already in state `Alerting`.
|
||||
|
||||
So, as you can see from the above scenario Grafana will not send out notifications when other series cause the alert to fire if the rule already is in state `Alerting`. To improve support for queries that return multiple series we plan to track state **per series** in a future release.
|
||||
|
||||
> Starting with Grafana v5.3 you can configure reminders to be sent for triggered alerts. This will send additional notifications
|
||||
> when an alert continues to fire. If other series (like server2 in the example above) also cause the alert rule to fire they will be included in the reminder notification. Depending on what notification channel you're using you may be able to take advantage of this feature for identifying new/existing series causing alert to fire.
|
||||
|
||||
### No Data & Error Handling
|
||||
|
||||
Below are conditions you can configure how the rule evaluation engine should handle queries that return no data or only null values.
|
||||
|
||||
| No Data Option | Description |
|
||||
| --------------- | ------------------------------------------------------------------------------------------ |
|
||||
| No Data | Set alert rule state to `NoData` |
|
||||
| Alerting | Set alert rule state to `Alerting` |
|
||||
| Keep Last State | Keep the current alert rule state, whatever it is. |
|
||||
| Ok | Not sure why you would want to send yourself an alert when things are okay, but you could. |
|
||||
|
||||
### Execution errors or timeouts
|
||||
|
||||
Tell Grafana how to handle execution or timeout errors.
|
||||
|
||||
| Error or timeout option | Description |
|
||||
| ----------------------- | --------------------------------------------------- |
|
||||
| Alerting | Set alert rule state to `Alerting` |
|
||||
| Keep Last State | Keep the current alert rule state, whatever it is. |
|
||||
|
||||
If you have an unreliable time series store from which queries sometime timeout or fail randomly you can set this option to `Keep Last State` in order to basically ignore them.
|
||||
|
||||
## Notifications
|
||||
|
||||
In alert tab you can also specify alert rule notifications along with a detailed message about the alert rule. The message can contain anything, information about how you might solve the issue, link to runbook, and so on.
|
||||
|
||||
The actual notifications are configured and shared between multiple alerts. Read
|
||||
[Alert notifications]({{< relref "notifications.md" >}}) for information on how to configure and set up notifications.
|
||||
|
||||
- **Send to -** Select an alert notification channel if you have one set up.
|
||||
- **Message -** Enter a text message to be sent on the notification channel. Some alert notifiers support transforming the text to HTML or other rich formats. This field supports [templating]({{< relref "./add-notification-template.md" >}}).
|
||||
- **Tags -** Specify a list of tags (key/value) to be included in the notification. It is only supported by [some notifiers]({{< relref "notifications/#all-supported-notifiers" >}}).
|
||||
|
||||
## Alert state history and annotations
|
||||
|
||||
Alert state changes are recorded in the internal annotation table in Grafana's database. The state changes are visualized as annotations in the alert rule's graph panel. You can also go into the `State history` submenu in the alert tab to view and clear state history.
|
||||
|
||||
@@ -0,0 +1,283 @@
|
||||
+++
|
||||
title = "Alert notifications"
|
||||
description = "Alerting notifications guide"
|
||||
keywords = ["Grafana", "alerting", "guide", "notifications"]
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Alert notifications
|
||||
|
||||
When an alert changes state, it sends out notifications. Each alert rule can have
|
||||
multiple notifications. In order to add a notification to an alert rule you first need
|
||||
to add and configure a `notification` channel (can be email, PagerDuty, or other integration).
|
||||
|
||||
This is done from the Notification channels page.
|
||||
|
||||
> **Note:** Alerting is only available in Grafana v4.0 and above.
|
||||
|
||||
## Add a notification channel
|
||||
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Notification channels**.
|
||||
1. Click **Add channel**.
|
||||
1. Fill out the fields or select options described below.
|
||||
|
||||
## New notification channel fields
|
||||
|
||||
### Default (send on all alerts)
|
||||
|
||||
- **Name -** Enter a name for this channel. It will be displayed when users add notifications to alert rules.
|
||||
- **Type -** Select the channel type. Refer to the [List of supported notifiers](#list-of-supported-notifiers) for details.
|
||||
- **Default (send on all alerts) -** When selected, this option sends a notification on this channel for all alert rules.
|
||||
- **Include Image -** See [Enable images in notifications](#enable-images-in-notifications-external-image-store) for details.
|
||||
- **Disable Resolve Message -** When selected, this option disables the resolve message [OK] that is sent when the alerting state returns to false.
|
||||
- **Send reminders -** When this option is checked additional notifications (reminders) will be sent for triggered alerts. You can specify how often reminders should be sent using number of seconds (s), minutes (m) or hours (h), for example `30s`, `3m`, `5m` or `1h`.
|
||||
|
||||
**Important:** Alert reminders are sent after rules are evaluated. Therefore a reminder can never be sent more frequently than a configured alert rule evaluation interval.
|
||||
|
||||
These examples show how often and when reminders are sent for a triggered alert.
|
||||
|
||||
Alert rule evaluation interval | Send reminders every | Reminder sent every (after last alert notification)
|
||||
---------- | ----------- | -----------
|
||||
`30s` | `15s` | ~30 seconds
|
||||
`1m` | `5m` | ~5 minutes
|
||||
`5m` | `15m` | ~15 minutes
|
||||
`6m` | `20m` | ~24 minutes
|
||||
`1h` | `15m` | ~1 hour
|
||||
`1h` | `2h` | ~2 hours
|
||||
|
||||
<div class="clearfix"></div>
|
||||
|
||||
## List of supported notifiers
|
||||
|
||||
Name | Type | Supports images | Support alert rule tags
|
||||
-----|------|---------------- | -----------------------
|
||||
[DingDing](#dingdingdingtalk) | `dingding` | yes, external only | no
|
||||
[Discord](#discord) | `discord` | yes | no
|
||||
[Email](#email) | `email` | yes | no
|
||||
[Google Hangouts Chat](#google-hangouts-chat) | `googlechat` | yes, external only | no
|
||||
Hipchat | `hipchat` | yes, external only | no
|
||||
[Kafka](#kafka) | `kafka` | yes, external only | no
|
||||
Line | `line` | yes, external only | no
|
||||
Microsoft Teams | `teams` | yes, external only | no
|
||||
[Opsgenie](#opsgenie) | `opsgenie` | yes, external only | yes
|
||||
[Pagerduty](#pagerduty) | `pagerduty` | yes, external only | yes
|
||||
Prometheus Alertmanager | `prometheus-alertmanager` | yes, external only | yes
|
||||
[Pushover](#pushover) | `pushover` | yes | no
|
||||
Sensu | `sensu` | yes, external only | no
|
||||
[Sensu Go](#sensu-go) | `sensugo` | yes, external only | no
|
||||
[Slack](#slack) | `slack` | yes | no
|
||||
Telegram | `telegram` | yes | no
|
||||
Threema | `threema` | yes, external only | no
|
||||
VictorOps | `victorops` | yes, external only | yes
|
||||
[Webhook](#webhook) | `webhook` | yes, external only | yes
|
||||
[Zenduty](#zenduty) | `webhook` | yes, external only | yes
|
||||
|
||||
### Email
|
||||
|
||||
To enable email notifications you have to set up [SMTP settings]({{< relref "../../administration/configuration/#smtp" >}})
|
||||
in the Grafana config. Email notifications will upload an image of the alert graph to an
|
||||
external image destination if available or fallback to attaching the image to the email.
|
||||
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.
|
||||
|
||||
Setting | Description
|
||||
---------- | -----------
|
||||
Single email | Send a single email to all recipients. Disabled per default.
|
||||
Addresses | Email addresses to recipients. You can enter multiple email addresses using a ";" separator.
|
||||
|
||||
### Slack
|
||||
|
||||
{{< figure class="float-right" max-width="40%" src="/static/img/docs/v4/slack_notification.png" caption="Alerting Slack Notification" >}}
|
||||
|
||||
To set up Slack, you need to configure an incoming Slack webhook URL. You can follow
|
||||
[Sending messages using Incoming Webhooks](https://api.slack.com/incoming-webhooks) on how to do that. If you want to include screenshots of the
|
||||
firing alerts in the Slack messages you have to configure either the [external image destination](#external-image-store)
|
||||
in Grafana or a bot integration via Slack Apps. [Follow Slack's guide to set up a bot integration](https://api.slack.com/bot-users) and use the token
|
||||
provided, which starts with "xoxb".
|
||||
|
||||
Setting | Description
|
||||
---------- | -----------
|
||||
Url | Slack incoming webhook URL, or eventually the [chat.postMessage](https://api.slack.com/methods/chat.postMessage) Slack API endpoint.
|
||||
Username | Set the username for the bot's message.
|
||||
Recipient | Allows you to override the Slack recipient. You must either provide a channel Slack ID, a user Slack ID, a username reference (@<user>, all lowercase, no whitespace), or a channel reference (#<channel>, all lowercase, no whitespace). If you use the `chat.postMessage` Slack API endpoint, this is required.
|
||||
Icon emoji | Provide an emoji to use as the icon for the bot's message. Ex :smile:
|
||||
Icon URL | Provide a URL to an image to use as the icon for the bot's message.
|
||||
Mention Users | Optionally mention one or more users in the Slack notification sent by Grafana. You have to refer to users, comma-separated, via their corresponding Slack IDs (which you can find by clicking the overflow button on each user's Slack profile).
|
||||
Mention Groups | Optionally mention one or more groups in the Slack notification sent by Grafana. You have to refer to groups, comma-separated, via their corresponding Slack IDs (which you can get from each group's Slack profile URL).
|
||||
Mention Channel | Optionally mention either all channel members or just active ones.
|
||||
Token | If provided, Grafana will upload the generated image via Slack's file.upload API method, not the external image destination. If you use the `chat.postMessage` Slack API endpoint, this is required.
|
||||
|
||||
If you are using the token for a slack bot, then you have to invite the bot to the channel you want to send notifications and add the channel to the recipient field.
|
||||
|
||||
### Opsgenie
|
||||
|
||||
To setup Opsgenie you will need an API Key and the Alert API Url. These can be obtained by configuring a new [Grafana Integration](https://docs.opsgenie.com/docs/grafana-integration).
|
||||
|
||||
Setting | Description
|
||||
--------|------------
|
||||
Alert API URL | The API URL for your Opsgenie instance. This will normally be either `https://api.opsgenie.com` or, for EU customers, `https://api.eu.opsgenie.com`.
|
||||
API Key | The API Key as provided by Opsgenie for your configured Grafana integration.
|
||||
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.md/#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`.
|
||||
|
||||
### PagerDuty
|
||||
|
||||
To set up PagerDuty, all you have to do is to provide an integration key.
|
||||
|
||||
Setting | Description
|
||||
---------- | -----------
|
||||
Integration Key | Integration key for PagerDuty.
|
||||
Severity | Level for dynamic notifications, default is `critical` (1)
|
||||
Auto resolve incidents | Resolve incidents in PagerDuty once the alert goes back to ok
|
||||
Message in details | Removes the Alert message from the PD summary field and puts it into custom details instead (2)
|
||||
|
||||
>**Note:** The tags `Severity`, `Class`, `Group`, `dedup_key`, and `Component` have special meaning in the [Pagerduty Common Event Format - PD-CEF](https://support.pagerduty.com/docs/pd-cef). If an alert panel defines these tag keys, then they are transposed to the root of the event sent to Pagerduty. This means they will be available within the Pagerduty UI and Filtering tools. A Severity tag set on an alert overrides the global Severity set on the notification channel if it's a valid level.
|
||||
|
||||
>Using Message In Details will change the structure of the `custom_details` field in the PagerDuty Event.
|
||||
This might break custom event rules in your PagerDuty rules if you rely on the fields in `payload.custom_details`.
|
||||
Move any existing rules using `custom_details.myMetric` to `custom_details.queries.myMetric`.
|
||||
This behavior will become the default in a future version of Grafana.
|
||||
|
||||
> **Note:** The `dedup_key` tag overrides the Grafana-generated `dedup_key` with a custom key.
|
||||
|
||||
> **Note:** The `state` tag overrides the current alert state inside the `custom_details` payload.
|
||||
|
||||
### VictorOps
|
||||
|
||||
To configure VictorOps, provide the URL from the Grafana Integration and substitute `$routing_key` with a valid key.
|
||||
|
||||
> **Note:** The tag `Severity` has special meaning in the [VictorOps Incident Fields](https://help.victorops.com/knowledge-base/incident-fields-glossary/). If an alert panel defines this key, then it replaces the `message_type` in the root of the event sent to VictorOps.
|
||||
### Pushover
|
||||
|
||||
To set up Pushover, you must provide a user key and an API token. Refer to [What is Pushover and how do I use it](https://support.pushover.net/i7-what-is-pushover-and-how-do-i-use-it) for instructions on how to generate them.
|
||||
|
||||
|
||||
Setting | Description
|
||||
---------- | -----------
|
||||
API Token | Application token
|
||||
User key(s) | A comma-separated list of user keys
|
||||
Device(s) | A comma-separated list of devices
|
||||
Priority | The priority alerting nottifications are sent
|
||||
OK priority | The priority OK notifications are sent; if not set, then OK notifications are sent with the priority set for alerting notifications
|
||||
Retry | How often (in seconds) the Pushover servers send the same notification to the user. (minimum 30 seconds)
|
||||
Expire | How many seconds your notification will continue to be retried for (maximum 86400 seconds)
|
||||
Alerting sound | The sound for alerting notifications
|
||||
OK sound | The sound for OK notifications
|
||||
|
||||
### Webhook
|
||||
|
||||
The webhook notification is a simple way to send information about a state change over HTTP to a custom endpoint.
|
||||
Using this notification you could integrate Grafana into a system of your choosing.
|
||||
|
||||
Example json body:
|
||||
|
||||
```json
|
||||
{
|
||||
"dashboardId":1,
|
||||
"evalMatches":[
|
||||
{
|
||||
"value":1,
|
||||
"metric":"Count",
|
||||
"tags":{}
|
||||
}
|
||||
],
|
||||
"imageUrl":"https://grafana.com/assets/img/blog/mixed_styles.png",
|
||||
"message":"Notification Message",
|
||||
"orgId":1,
|
||||
"panelId":2,
|
||||
"ruleId":1,
|
||||
"ruleName":"Panel Title alert",
|
||||
"ruleUrl":"http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1",
|
||||
"state":"alerting",
|
||||
"tags":{
|
||||
"tag name":"tag value"
|
||||
},
|
||||
"title":"[Alerting] Panel Title alert"
|
||||
}
|
||||
```
|
||||
|
||||
- **state** - The possible values for alert state are: `ok`, `paused`, `alerting`, `pending`, `no_data`.
|
||||
|
||||
### DingDing/DingTalk
|
||||
|
||||
DingTalk supports the following "message type": `text`, `link` and `markdown`. Only the `link` message type is supported. Refer to the [configuration instructions](https://developers.dingtalk.com/document/app/custom-robot-access) in Chinese language.
|
||||
|
||||
In DingTalk PC Client:
|
||||
|
||||
1. Click "more" icon on upper right of the panel.
|
||||
|
||||
2. Click "Robot Manage" item in the pop menu, there will be a new panel call "Robot Manage".
|
||||
|
||||
3. In the "Robot Manage" panel, select "customized: customized robot with Webhook".
|
||||
|
||||
4. In the next new panel named "robot detail", click "Add" button.
|
||||
|
||||
5. In "Add Robot" panel, input a nickname for the robot and select a "message group" which the robot will join in. click "next".
|
||||
|
||||
6. There will be a Webhook URL in the panel, looks like this: https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxx. Copy this URL to the Grafana DingTalk setting page and then click "finish".
|
||||
|
||||
### Discord
|
||||
|
||||
To set up Discord, you must create a Discord channel webhook. For instructions on how to create the channel, refer to
|
||||
[Intro to Webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) f.
|
||||
|
||||
Setting | Description
|
||||
---------- | -----------
|
||||
Webhook URL | Discord webhook URL.
|
||||
Message Content | Mention a group using @ or a user using <@ID> when notifying in a channel.
|
||||
Avatar URL | Optionally, provide a URL to an image to use as the avatar for the bot's message.
|
||||
|
||||
Alternately, use the [Slack](#slack) notifier by appending `/slack` to a Discord webhook URL.
|
||||
|
||||
### Kafka
|
||||
|
||||
Notifications can be sent to a Kafka topic from Grafana using the [Kafka REST Proxy](https://docs.confluent.io/1.0/kafka-rest/docs/index.html).
|
||||
There are a couple of configuration options which need to be set up in Grafana UI under Kafka Settings:
|
||||
|
||||
1. Kafka REST Proxy endpoint.
|
||||
|
||||
1. Kafka Topic.
|
||||
|
||||
Once these two properties are set, you can send the alerts to Kafka for further processing or throttling.
|
||||
|
||||
### Google Hangouts Chat
|
||||
|
||||
Notifications can be sent by setting up an incoming webhook in Google Hangouts chat. For more information about configuring a webhook, refer to [webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks).
|
||||
|
||||
### Prometheus Alertmanager
|
||||
|
||||
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.
|
||||
|
||||
### Zenduty
|
||||
|
||||
[Zenduty](https://www.zenduty.com) is an incident alerting and response orchestration platform that not alerts the right teams via SMS, Phone(Voice), Email, Slack, Microsoft Teams and Push notifications(Android/iOS) whenever a Grafana alert is triggered, but also helps you rapidly triage and remediate critical, user impacting incidents. Grafana alert are sent to Zenduty through Grafana's native webhook dispatcher. Refer the Zenduty-Grafana [integration documentation](https://docs.zenduty.com/docs/grafana) for configuring the integration.
|
||||
|
||||
### Sensu Go
|
||||
|
||||
[Sensu](https://sensu.io) is a complete solution for monitoring and observability at scale. Sensu Go is designed to give you visibility into everything you care about: traditional server closets, containers, applications, the cloud, and more. Grafana notifications can be sent to Sensu Go as events via the API. This operation requires an API Key. Refer to the [Sensu Go documentation](https://docs.sensu.io/sensu-go/latest/operations/control-access/use-apikeys/#api-key-authentication) for information on creating this key.
|
||||
|
||||
## Enable images in notifications {#external-image-store}
|
||||
|
||||
Grafana can render the panel associated with the alert rule as a PNG image and include that in the notification. Read more about the requirements and how to configure
|
||||
[image rendering]({{< relref "../../administration/image_rendering/" >}}).
|
||||
|
||||
You must configure an [external image storage provider]({{< relref "../../administration/configuration/#external-image-storage" >}}) in order to receive images in alert notifications. If your notification channel requires that the image be publicly accessible (e.g. Slack, PagerDuty), configure a provider which uploads the image to a remote image store like Amazon S3, Webdav, Google Cloud Storage, or Azure Blob Storage. Otherwise, the local provider can be used to serve the image directly from Grafana.
|
||||
|
||||
Notification services which need public image access are marked as 'external only'.
|
||||
|
||||
## Configure the link back to Grafana from alert notifications
|
||||
|
||||
All alert notifications contain a link back to the triggered alert in the Grafana instance.
|
||||
This URL is based on the [domain]({{< relref "../../administration/configuration/#domain" >}}) setting in Grafana.
|
||||
|
||||
## Notification templating
|
||||
|
||||
> **Note:** Alert notification templating is only available in Grafana v7.4 and above.
|
||||
|
||||
The alert notification template feature allows you to take the [label]({{< relref "../../basics/timeseries-dimensions.md#labels" >}}) value from an alert query and [inject that into alert notifications]({{< relref "./add-notification-template.md" >}}).
|
||||
@@ -0,0 +1,14 @@
|
||||
+++
|
||||
title = "Pause alert rule"
|
||||
description = "Pause an existing alert rule"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "view"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Pause an alert rule
|
||||
|
||||
Pausing the evaluation of an alert rule can sometimes be useful. For example, during a maintenance window, pausing alert rules can avoid triggering a flood of alerts.
|
||||
|
||||
1. In the Grafana side bar, hover your cursor over the Alerting (bell) icon and then click **Alert Rules**. All configured alert rules are listed, along with their current state.
|
||||
1. Find your alert in the list, and click the **Pause** icon on the right. The **Pause** icon turns into a **Play** icon.
|
||||
1. Click the **Play** icon to resume evaluation of your alert.
|
||||
@@ -0,0 +1,41 @@
|
||||
+++
|
||||
title = "Troubleshoot alerts"
|
||||
description = "Troubleshoot alert rules"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "troubleshoot"]
|
||||
weight = 500
|
||||
+++
|
||||
|
||||
# Troubleshoot alerts
|
||||
|
||||
If alerts are not behaving as you expect, here are some steps you can take to troubleshoot and figure out what is going wrong.
|
||||
|
||||
|
||||
|
||||
The first level of troubleshooting you can do is click **Test Rule**. You will get result back that you can expand to the point where you can see the raw data that was returned from your query.
|
||||
|
||||
Further troubleshooting can also be done by inspecting the grafana-server log. If it's not an error or for some reason the log does not say anything you can enable debug logging for some relevant components. This is done in Grafana's ini config file.
|
||||
|
||||
Example showing loggers that could be relevant when troubleshooting alerting.
|
||||
|
||||
```ini
|
||||
[log]
|
||||
filters = alerting.scheduler:debug \
|
||||
alerting.engine:debug \
|
||||
alerting.resultHandler:debug \
|
||||
alerting.evalHandler:debug \
|
||||
alerting.evalContext:debug \
|
||||
alerting.extractor:debug \
|
||||
alerting.notifier:debug \
|
||||
alerting.notifier.slack:debug \
|
||||
alerting.notifier.pagerduty:debug \
|
||||
alerting.notifier.email:debug \
|
||||
alerting.notifier.webhook:debug \
|
||||
tsdb.graphite:debug \
|
||||
tsdb.prometheus:debug \
|
||||
tsdb.opentsdb:debug \
|
||||
tsdb.influxdb:debug \
|
||||
tsdb.elasticsearch:debug \
|
||||
tsdb.elasticsearch.client:debug \
|
||||
```
|
||||
|
||||
If you want to log raw query sent to your TSDB and raw response in log you also have to set grafana.ini option `app_mode` to `development`.
|
||||
@@ -0,0 +1,19 @@
|
||||
+++
|
||||
title = "View alerts"
|
||||
description = "View existing alert rules"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "view"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# View existing alert rules
|
||||
|
||||
Grafana stores individual alert rules in the panels where they are defined, but you can also view a list of all existing alert rules and their current state.
|
||||
|
||||
In the Grafana side bar, hover your cursor over the Alerting (bell) icon and then click **Alert Rules**. All configured alert rules are listed, along with their current state.
|
||||
|
||||
You can do several things while viewing alerts.
|
||||
|
||||
- **Filter alerts by name -** Type an alert name in the **Search alerts** field.
|
||||
- **Filter alerts by state -** In **States**, select which alert states you want to see. All others will be hidden.
|
||||
- **Pause or resume an alert -** Click the **Pause** or **Play** icon next to the alert to pause or resume evaluation. See [Pause an alert rule]({{< relref "pause-an-alert-rule.md" >}}) for more information.
|
||||
- **Access alert rule settings -** Click the alert name or the **Edit alert rule** (gear) icon. Grafana opens the Alert tab of the panel where the alert rule is defined. This is helpful when an alert is firing but you don't know which panel it is defined in.
|
||||
@@ -0,0 +1,60 @@
|
||||
+++
|
||||
title = "Grafana 8 Alerts"
|
||||
aliases = ["/docs/grafana/latest/alerting/metrics/"]
|
||||
weight = 113
|
||||
+++
|
||||
|
||||
# Grafana 8 alerts
|
||||
Alerts allow you to know about problems in your systems moments after they occur. Robust and actionable alerts help you identify and resolve issues quickly, minimizing disruption to your services.
|
||||
|
||||
>**Note:** This information is for the new, Grafana 8 Alerts. This is an [opt-in]({{< relref"./opt-in.md" >}}) feature released in Grafana 8.0. Grafana still supports [dashboard alerts]({{< relref "../old-alerting/_index.md" >}}) out of the box
|
||||
|
||||
Alerts have four main components:
|
||||
|
||||
- Alerting rule - One or more query and/or expression, a condition, the frequency of evaluation, and the (optional) duration that a condition must be met before creating an alert.
|
||||
- Contact point - A channel for sending notifications when the conditions of an alerting rule are met.
|
||||
- Notification policy - A set of matching and grouping criteria used to determine where, and how frequently, to send notifications.
|
||||
- Silences - Date and matching criteria used to silence notifications.
|
||||
|
||||
## Alerting tasks
|
||||
|
||||
You can perform the following tasks for alerts:
|
||||
|
||||
|
||||
- [Create a Grafana managed alert rule]({{< relref "alerting-rules/create-grafana-managed-rule.md" >}})
|
||||
- [Create a Cortex or Loki managed alert rule]({{< relref "alerting-rules/create-cortex-loki-managed-rule.md" >}})
|
||||
- [View existing alert rules and their current state]({{< relref "alerting-rules/rule-list.md" >}})
|
||||
- [Test alert rules and troubleshoot]({{< relref "./troubleshoot-alerts.md" >}})
|
||||
- [Add or edit an alert contact point]({{< relref "./contact-points.md" >}})
|
||||
- [Add or edit notification policies]({{< relref "./notification-policies.md" >}})
|
||||
- [Create and edit silences]({{< relref "./silences.md" >}})
|
||||
|
||||
## Clustering
|
||||
|
||||
Currently alerting supports a limited form of high availability. Alert notifications are deduped when running multiple servers. This means all alerts are executed on every server but no duplicate alert notifications are sent due to the deduping logic. Proper load balancing of alerts will be introduced in the future.
|
||||
|
||||
## Alert evaluation
|
||||
|
||||
Grafana managed alerts are evaluated by the Grafana backend. Rule evaluations are scheduled, according to the alert rule configuration, and queries are evaluated by an engine that is part of core Grafana.
|
||||
|
||||
Alerting rules can only query backend data sources with alerting enabled:
|
||||
- builtin or developed and maintained by grafana: `Graphite`, `Prometheus`, `Loki`, `InfluxDB`, `Elasticsearch`,
|
||||
`Google Cloud Monitoring`, `Cloudwatch`, `Azure Monitor`, `MySQL`, `PostgreSQL`, `MSSQL`, `OpenTSDB`, `Oracle`, and `Azure Data Explorer`
|
||||
- any community backend data sources with alerting enabled (`backend` and `alerting` properties are set in the [plugin.json]({{< relref "../../developers/plugins/metadata.md" >}}))
|
||||
|
||||
## Metrics from the alerting engine
|
||||
|
||||
The alerting engine publishes some internal metrics about itself. You can read more about how Grafana publishes [internal metrics]({{< relref "../../administration/view-server/internal-metrics.md" >}}).
|
||||
|
||||
Metric Name | Type | Description
|
||||
---------- | ----------- | ----------
|
||||
`alerting.alerts` | gauge | How many alerts by state
|
||||
`alerting.request_duration_seconds` | histogram | Histogram of requests to the Alerting API
|
||||
`alerting.active_configurations` | gauge | The number of active, non default Alertmanager configurations for grafana managed alerts
|
||||
`alerting.rule_evaluations_total` | counter | The total number of rule evaluations
|
||||
`alerting.rule_evaluation_failures_total` | counter | The total number of rule evaluation failures
|
||||
`alerting.rule_evaluation_duration_seconds` | summary | The duration for a rule to execute
|
||||
`alerting.rule_group_rules` | gauge | The number of rules
|
||||
|
||||
|
||||
- [View alert rules and their current state]({{< relref "alerting-rules/rule-list.md" >}})
|
||||
@@ -0,0 +1,12 @@
|
||||
+++
|
||||
title = "Alerting Rules"
|
||||
aliases = ["/docs/grafana/latest/alerting/rules/"]
|
||||
+++
|
||||
|
||||
# Alerting Rules
|
||||
One or more queries and/or expressions, a condition, the frequency of evaluation, and the (optional) duration that a condition must be met before creating an alert. Alerting rules are how you express the criteria for creating an alert. Queries and expressions select and can operate on the data you wish to alert on. A condition sets the threshold that an alert must meet or exceed to create an alert. The interval specifies how frequently the rule should be evaluated. The duration, when configured, sets a period that a condition must be met or exceeded before an alert is created. Alerting rules also can contain settings for what to do when your query does not return any data, or there is an error attempting to execute the query.
|
||||
|
||||
- [View existing alert rules and their current state]({{< relref "./rule-list.md" >}})
|
||||
- [Create Cortex or Loki managed alert rule]({{< relref "./create-cortex-loki-managed-rule.md" >}})
|
||||
- [Create Grafana managed alert rule]({{< relref "./create-grafana-managed-rule.md" >}})
|
||||
- [State and Health of alerting rules]({{< relref "./state-and-health.md" >}})
|
||||
+62
@@ -0,0 +1,62 @@
|
||||
+++
|
||||
title = "Create Cortex or Loki managed alert rule"
|
||||
description = "Create Cortex or Loki managed alerting rule"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "create"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Create a Cortex or Loki managed alerting rule
|
||||
|
||||
Grafana allows you manage alerting rules for an external Cortex or Loki instance.
|
||||
|
||||
## Add or edit a Cortex or Loki managed alerting rule
|
||||
|
||||
1. In the Grafana menu hover your cursor over the Alerting (bell) icon.
|
||||
1. To create a new alert rule, click **New alert rule**. To edit an existing rule, expand one of the rules in the **Cortex / Loki** section and click **Edit**.
|
||||
1. Click on the **Alert type** drop down and select **Cortex / Loki managed alert**.
|
||||
1. Fill out the rest of the fields. Descriptions are listed below in [Alert rule fields](#alert-rule-fields).
|
||||
1. When you have finished writing your rule, click **Save** in the upper right corner to save the rule,, or **Save and exit** to save and exit rule editing.
|
||||
|
||||
## Alert rule fields
|
||||
|
||||
This section describes the fields you fill out to create an alert.
|
||||
|
||||
### Alert type
|
||||
|
||||
- **Alert name -** Enter a descriptive name. The name will be displayed in the alert rule list, as well as added as `alertname` label to every alert instance that is created from this rule.
|
||||
- **Alert type -** Select **Cortex / Loki managed alert**.
|
||||
- **Data source -** Select a Prometheus or Loki data source. Only Prometheus data sources that support Cortex ruler API will be available.
|
||||
- **Namespace -** Select an existing rule namespace or click **Add new** to create a new one.
|
||||
- **Group -** Select an existing group within the selected namespace or click **Add new** to create a new one. Newly created rules will be added to the end of the rule group.
|
||||
|
||||
|
||||
|
||||
### Query
|
||||
|
||||
Enter a PromQL or LogQL expression. Rule will fire if evaluation result has at least one series with value > 0. An alert will be created per each such series.
|
||||
|
||||
|
||||
|
||||
### Conditions
|
||||
|
||||
- **For -** For how long the selected condition should violated before an alert enters `Firing` state. When condition threshold is violated for the first time, an alert becomes `Pending`. If the **for** time elapses and the condition is still violated, it becomes `Firing`. Else it reverts back to `Normal`.
|
||||
|
||||
|
||||
|
||||
### Details
|
||||
|
||||
Annotations and labels can be optionally added in the details section.
|
||||
|
||||
#### Annotations
|
||||
|
||||
Annotations are key and value pairs that provide additional meta information about the alert, for example description, summary, runbook URL. They are displayed in rule and alert details in the UI and can be used in contact type message templates. Annotations can also be templated, for example `Instance {{ $labels.instance }} down` will have the evaluated `instance` label value added for every alert this rule produces.
|
||||
|
||||
#### Labels
|
||||
|
||||
Labels are key value pairs that categorize or identify an alert. Labels are used to match alerts in silences or match and groups alerts in notification policies. Labels are also shown in rule or alert details in the UI and can be used in contact type message templates. For example, it is common to add a `severity` label and then configure a separate notification policy for each severity. Or one could add a `team` label and configure team specific notification policies, or silence all alerts for a particular team.
|
||||
|
||||
|
||||
|
||||
## Preview alerts
|
||||
|
||||
To evaluate the rule and see what alerts it would produce, click **Preview alerts**. It will display a list of alerts with state and value of for each one.
|
||||
@@ -0,0 +1,108 @@
|
||||
+++
|
||||
title = "Create Grafana managed alert rule"
|
||||
description = "Create Grafana managed alert rule"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "create"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Create a Grafana managed alerting rule
|
||||
|
||||
Grafana allows you to create alerting rules that query one or more data sources, reduce or transform the results and compare them to each other or to fix thresholds. These rules will be executed and notifications sent by Grafana itself.
|
||||
|
||||
## Add or edit a Grafana managed alerting rule
|
||||
|
||||
1. In the Grafana menu hover your cursor over the Alerting (bell) icon.
|
||||
1. To create a new alert rule, click **New alert rule**. To edit an existing rule, expand one of the rules in the **Grafana** section and click **Edit**.
|
||||
1. Click on the **Alert type** drop down and select **Grafana managed alert**.
|
||||
1. Fill out the rest of the fields. Descriptions are listed below in [Alert rule fields](#alert-rule-fields).
|
||||
1. When you have finished writing your rule, click **Save** in the upper right corner to save the rule,, or **Save and exit** to save and exit rule editing.
|
||||
|
||||
## Alert rule fields
|
||||
|
||||
This section describes the fields you fill out to create an alert.
|
||||
|
||||
### Alert type
|
||||
|
||||
- **Alert name -** Enter a descriptive name. The name will be displayed in the alert rule list, as well as added as `alertname` label to every alert instance that is created from this rule.
|
||||
- **Alert type -** Select **Grafana managed alert**.
|
||||
- **Folder -** Select a folder this alert rule will belong to. To create a new folder, click on the drop down and type in a new folder name.
|
||||
|
||||
|
||||
|
||||
### Query
|
||||
|
||||
Add one or more [queries]({{< relref "../../../panels/queries.md" >}}) or [expressions]({{< relref "../../../panels/expressions.md" >}}). You can use classic condition expression to create a rule that will trigger a single alert if it's threshold is met, or use reduce and math expressions to create a multi dimensional alert rule that can trigger multiple alerts, one per matching series in the query result.
|
||||
|
||||
#### Rule with classic condition
|
||||
|
||||
You can use classic condition expression to create a rule that will trigger a single alert if it's conditions is met. It works about the same way as dashboard alerts in previous versions of Grafana.
|
||||
|
||||
1. Add one or more queries
|
||||
1. Add an expression. Click on **Operation** dropdown and select **Classic condition**.
|
||||
1. Add one or more conditions. For each condition you can specify operator (`AND` / `OR`), aggregation function, query letter and threshold value.
|
||||
|
||||
If a query returns multiple series, then the aggregation function and threshold check will be evaluated for each series.It will not track alert state **per series**. This has implications that are detailed in the scenario below.
|
||||
|
||||
- Alert condition with query that returns 2 series: **server1** and **server2**
|
||||
- **server1** series causes the alert rule to fire and switch to state `Firing`
|
||||
- Notifications are sent out with message: _load peaking (server1)_
|
||||
- In a subsequent evaluation of the same alert rule, the **server2** series also causes the alert rule to fire
|
||||
- No new notifications are sent as the alert rule is already in state `Firing`.
|
||||
|
||||
So, as you can see from the above scenario Grafana will not send out notifications when other series cause the alert to fire if the rule already is in state `Firing`. If you want to have alert per series, create a multi dimensional alert rule as described in the section below.
|
||||
|
||||
|
||||
|
||||
#### Multi dimensional rule
|
||||
|
||||
You can use reduce and math expressions to create a rule that will create an alert per series returned by the query.
|
||||
|
||||
1. Add one or more queries
|
||||
2. Add a `reduce` expression for each query to aggregate values in the selected time range into a single value. With some data sources this is not needed for [rules using numeric data]({{< relref "../grafana-managed-numeric-rule.md" >}}).
|
||||
3. Add a `math` expressions with the condition for the rule. Not needed in case a query or a reduce expression already returns 0 if rule should not be firing, or > 0 if it should be firing. Some examples: `$B > 70` if it should fire in case value of B query/expression is more than 70. `$B < $C * 100` in case it should fire if value of B is less than value of C multiplied by 100. If queries being compared have multiple series in their results, series from different queries are matched if they have the same labels or one is a subset of the other.
|
||||
|
||||
See or [expressions documentation]({{< relref "../../../panels/expressions.md" >}}) for in depth explanation of `math` and `reduce` expressions.
|
||||
|
||||
|
||||
|
||||
### Conditions
|
||||
|
||||
- **Condition -** Select the letter of the query or expression whose result will trigger the alert rule. You will likely want to select either a `classic condition` or a `math` expression.
|
||||
- **Evaluate every -** How often the rule should be evaluated, executing the defined queries and expressions. Must be no less than 10 seconds and a multiple of 10 seconds. Examples: `1m`, `30s`
|
||||
- **Evaluate for -** For how long the selected condition should violated before an alert enters `Alerting` state. When condition threshold is violated for the first time, an alert becomes `Pending`. If the **for** time elapses and the condition is still violated, it becomes `Alerting`. Else it reverts back to `Normal`.
|
||||
|
||||
#### No Data & Error handling
|
||||
|
||||
Toggle **Configure no data and error handling** switch to configure how the rule should handle cases where evaluation results in error or returns no data.
|
||||
|
||||
| No Data Option | Description |
|
||||
| --------------- | ------------------------------------------------------------------------------------------ |
|
||||
| No Data | Set alert state to `NoData` and rule state to `Normal` |
|
||||
| Alerting | Set alert rule state to `Alerting` |
|
||||
| Ok | Set alert rule state to `Normal` |
|
||||
|
||||
|
||||
| Error or timeout option | Description |
|
||||
| ----------------------- | --------------------------------------------------- |
|
||||
| Alerting | Set alert rule state to `Alerting` |
|
||||
| OK | Set alert rule state to `Normal` |
|
||||
|
||||
|
||||
|
||||
### Details
|
||||
|
||||
Annotations and labels can be optionally added in the details section.
|
||||
|
||||
#### Annotations
|
||||
|
||||
Annotations are key and value pairs that provide additional meta information about the alert, for example description, summary, runbook URL. They are displayed in rule and alert details in the UI and can be used in contact type message templates. Annotations can also be templated, for example `Instance {{ $labels.instance }} down` will have the evaluated `instance` label value added for every alert this rule produces.
|
||||
|
||||
#### Labels
|
||||
|
||||
Labels are key value pairs that categorize or identify an alert. Labels are used to match alerts in silences or match and groups alerts in notification policies. Labels are also shown in rule or alert details in the UI and can be used in contact type message templates. For example, it is common to add a `severity` label and then configure a separate notification policy for each severity. Or one could add a `team` label and configure team specific notification policies, or silence all alerts for a particular team. Labels can also be templated like annotations, for example `{{ $labels.namespace }}/{{ $labels.job }}` will produce a new rule label that will have the evaluated `namespace` and `job` label value added for every alert this rule produces. The rule labels take precedence over the labels produced by the query/condition.
|
||||
|
||||
|
||||
|
||||
## Preview alerts
|
||||
|
||||
To evaluate the rule and see what alerts it would produce, click **Preview alerts**. It will display a list of alerts with state and value for each one.
|
||||
@@ -0,0 +1,48 @@
|
||||
+++
|
||||
title = "View alert rules"
|
||||
description = "View alert rules"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "view"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# View alert rules
|
||||
|
||||
To view alters:
|
||||
1. In the Grafana menu hover your cursor over the Alerting (bell) icon.
|
||||
1. Click **Alert Rules**. You can see all configured Grafana alert rules as well as any rules from Loki or Prometheus data sources.
|
||||
By default, the group view is shown. You can toggle between group or state views by clicking the relevant **View as** buttons in the options area at the top of the page.
|
||||
|
||||
### Group view
|
||||
|
||||
Group view shows Grafana alert rules grouped by folder and Loki or Prometheus alert rules grouped by `namespace` + `group`. This is the default rule list view, intended for managing rules. You can expand each group to view a list of rules in this group. Each rule can be further expanded to view its details. Action buttons and any alerts spawned by this rule, and each alert can be further expanded to view its details.
|
||||
|
||||
|
||||
|
||||
### State view
|
||||
|
||||
State view shows alert rules grouped by state. Use this view to get an overview of which rules are in what state. Each rule can be expanded to view its details. Action buttons and any alerts spawned by this rule, and each alert can be further expanded to view its details.
|
||||
|
||||
|
||||
|
||||
## Filter alert rules
|
||||
You can use the following filters to view only alert rules that match specific criteria:
|
||||
|
||||
- **Filter alerts by name or label -** Type an alert name, label name or value in the **Search** input.
|
||||
- **Filter alerts by state -** In **States** Select which alert states you want to see. All others are hidden.
|
||||
- **Filter alerts by data source -** Click the **Select data source** and select an alerting data source. Only alert rules that query selected data source will be visible.
|
||||
|
||||
## Rule details
|
||||
|
||||
A rule row shows the rule state, health, and summary annotation if the rule has one. You can expand the rule row to display rule labels, all annotations, data sources this rule queries, and a list of alert instances spawned from this rule.
|
||||
|
||||
|
||||
|
||||
### Edit or delete rule
|
||||
|
||||
Grafana rules can only be edited or deleted by users with Edit permissions for the folder which contains the rule. Prometheus or Loki rules can be edited or deleted by users with Editor or Admin roles.
|
||||
|
||||
To edit or delete a rule:
|
||||
|
||||
1. Expand this rule to reveal rule controls.
|
||||
1. Click **Edit** to go to the rule editing form. Make changes following [instructions listed here]({{< relref "./create-grafana-managed-rule.md" >}}).
|
||||
1. Click **Delete"** to delete a rule.
|
||||
@@ -0,0 +1,27 @@
|
||||
+++
|
||||
title = "State and Health of alerting rules"
|
||||
description = "State and Health of alerting rules"
|
||||
keywords = ["grafana", "alerting", "guide", "state"]
|
||||
+++
|
||||
|
||||
The concepts of state and health for alerting rules help you understand, at a glance, several key status indicators about your alerts. Alert state, alerting rule state, and alerting rule health are related, but they each convey subtly different information.
|
||||
|
||||
## Alerting rule state
|
||||
Indicates whether any of the timeseries resulting from evaluation of the alerting rule are in an alerting state. Alerting rule state only requires a single alerting instance to be in a pending or firing state for the alerting rule state to not be normal.
|
||||
- Normal: none of the timeseries returned are in an alerting state.
|
||||
- Pending: at least one of the timeseries returned are in a pending state.
|
||||
- Firing: at least one of the timeseries returned are in an alerting state.
|
||||
|
||||
## Alert state
|
||||
Alert state is an indication of the output of the alerting evaluation engine.
|
||||
- Normal: the condition for the alerting rule has evaluated to **false** for every timeseries returned by the evaluation engine.
|
||||
- Alerting: the condition for the alerting rule has evaluated to **true** for at least one timeseries returned by the evaluation engine and the duration, if set, **has** been met or exceeded.
|
||||
- Pending: the condition for the alerting rule has evaluated to **true** for at least one timeseries returned by the evaluation engine and the duration, if set, **has not** been met or exceeded.
|
||||
- NoData: the alerting rule has not returned a timeseries, all values for the timeseries are null, or all values for the timeseries are zero.
|
||||
- Error: There was an error encountered when attempting to evaluate the alerting rule.
|
||||
|
||||
## Alerting rule health
|
||||
Indicates the status of alerting rule evaluation.
|
||||
- Ok: the rule is being evaluated, data is being returned, and no errors have been encountered.
|
||||
- Error: an error was encountered when evaluating the alerting rule.
|
||||
- NoData: at least one of the timeseries returned during evaluation is in a NoData state.
|
||||
@@ -0,0 +1,73 @@
|
||||
+++
|
||||
title = "Contact points"
|
||||
description = "Create or edit contact point"
|
||||
keywords = ["grafana", "alerting", "guide", "contact point", "notification channel", "create"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Contact points
|
||||
|
||||
Contact points define where to send notifications about alerts that match a particular [notification policy]({{< relref "./notification-policies.md" >}}). A contact point can contain one or more contact point types, eg email, slack, webhook and so on. A notification will dispatched to all contact point types defined on a contact point. [Templating]({{< relref "./message-templating/_index.md" >}}) can be used to customize contact point type message with alert data. Grafana alerting UI can be used to configure both Grafana managed contact points and contact points for an [external Alertmanager if one is configured]({{< relref "../../datasources/alertmanager.md" >}}).
|
||||
|
||||
## Add a contact point
|
||||
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Contact points**.
|
||||
1. Click **Add contact point**.
|
||||
1. Enter a **Name** for the contact point
|
||||
1. Select contact point type and fill out mandatory fields. **Optional settings** can be expanded for more options.
|
||||
1. If you'd like this contact point to notify via multiple channels, for example both email and slack, click **New contact point type** and fill out additional contact point type details.
|
||||
1. Click **Save contact point** button at the bottom of the page.
|
||||
|
||||
## Editing a contact point
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Contact points**.
|
||||
1. Find the contact point you want to edit in the contact points table and click the **pen icon** on the right side.
|
||||
1. Make any changes and click **Save contact point** button at the bottom of the page.
|
||||
|
||||
## Deleting a contact point
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Contact points**.
|
||||
1. Find the contact point you want to edit in the contact points table and click the **trash can icon** on the right side.
|
||||
1. A confirmation dialog will open. Click **Yes, delete**.
|
||||
|
||||
**Note** You will not be able to delete contact points that are currently used by any notification policy. If you want to delete such contact point, you will have to first go to [notification policies]({{< relref "./notification-policies.md" >}}) and delete the policy or update it to use another contact point.
|
||||
|
||||
## List of notifiers supported by Grafana
|
||||
|
||||
Name | Type
|
||||
-----|-----
|
||||
[DingDing](#dingdingdingtalk) | `dingding`
|
||||
[Discord](#discord) | `discord`
|
||||
[Email](#email) | `email`
|
||||
[Google Hangouts Chat](#google-hangouts-chat) | `googlechat`
|
||||
[Kafka](#kafka) | `kafka`
|
||||
Line | `line`
|
||||
Microsoft Teams | `teams`
|
||||
[Opsgenie](#opsgenie) | `opsgenie`
|
||||
[Pagerduty](#pagerduty) | `pagerduty`
|
||||
Prometheus Alertmanager | `prometheus-alertmanager`
|
||||
[Pushover](#pushover) | `pushover`
|
||||
Sensu | `sensu`
|
||||
[Sensu Go](#sensu-go) | `sensugo`
|
||||
[Slack](#slack) | `slack`
|
||||
Telegram | `telegram`
|
||||
Threema | `threema`
|
||||
VictorOps | `victorops`
|
||||
[Webhook](#webhook) | `webhook`
|
||||
[Zenduty](#zenduty) | `webhook`
|
||||
|
||||
## Manage contact points for an external Alertmanager
|
||||
|
||||
Grafana alerting UI supports managing external Alertmanager configuration. Once you add an [Alertmanager data source]({{< relref "../../datasources/alertmanager.md" >}}), a dropdown displays at the top of the page where you can select either `Grafana` or an external Alertmanager as your data source.
|
||||
|
||||
{{< figure max-width="40%" src="/static/img/docs/alerting/unified/contact-points-select-am-8-0.gif" caption="Select Alertmanager" >}}
|
||||
|
||||
### Edit Alertmanager global config
|
||||
|
||||
To edit global configuration options for an alertmanager, like SMTP server that is used by default for all email contact types:
|
||||
|
||||
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Contact points**.
|
||||
1. In the dropdown at the top of the page, select an Alertmanager data source.
|
||||
1. Click **Edit global config** button at the bottom of the page.
|
||||
1. Fill out the form and click **Save global config**.
|
||||
|
||||
**Note** this is only for external Alertmanagers. Some global options for Grafana contact types, like email settings, can be configured via [Grafana configuration]({{< relref "../../administration/configuration.md" >}}).
|
||||
@@ -0,0 +1,67 @@
|
||||
+++
|
||||
title = "Grafana managed alert rules for numeric data"
|
||||
description = "Grafana managed alert rules for numeric data"
|
||||
keywords = ["grafana", "alerting", "guide", "rules", "create"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Alerting on numeric data
|
||||
|
||||
Among certain data sources numeric data that is not time series can be directly alerted on, or passed into Server Side Expressions (SSE). This allows for more processing and resulting efficiency within the data source, and it can also simplify alert rules.
|
||||
When alerting on numeric data instead of time series data, there is no need to reduce each labeled time series into a single number. Instead labeled numbers are returned to Grafana instead.
|
||||
|
||||
## Tabular Data
|
||||
|
||||
This feature is supported with backend data sources that query tabular data:
|
||||
|
||||
- SQL data sources such as MySQL, Postgres, MSSQL, and Oracle.
|
||||
- The Azure Kusto based services: Azure Monitor (Logs), Azure Monitor (Azure Resource Graph), and Azure Data Explorer.
|
||||
|
||||
A query with Grafana managed alerts or SSE is considered numeric with these data sources, if:
|
||||
|
||||
- The "Format AS" option is set to "Table" in the data source query.
|
||||
- The table response returned to Grafana from the query includes only one numeric (e.g. int, double, float) column, and optionally additional string columns.
|
||||
|
||||
If there are string columns then those columns become labels. The name of column becomes the label name, and the value for each row becomes the value of the corresponding label. If multiple rows are returned, then each row should be uniquely identified their labels.
|
||||
|
||||
## Example
|
||||
|
||||
For a MySQL table called "DiskSpace":
|
||||
|
||||
| Time | Host | Disk | PercentFree
|
||||
| ----------- | --- | -----| --------
|
||||
| 2021-June-7 | web1 | /etc | 3
|
||||
| 2021-June-7 | web2 | /var | 4
|
||||
| 2021-June-7 | web3 | /var | 8
|
||||
| ... | ... | ... | ...
|
||||
|
||||
You can query the data filtering on time, but without returning the time series to Grafana. For example, an alert that would trigger per Host, Disk when there is less than 5% free space:
|
||||
|
||||
```sql
|
||||
SELECT Host, Disk, CASE WHEN PercentFree < 5.0 THEN PercentFree ELSE 0 END FROM (
|
||||
SELECT
|
||||
Host,
|
||||
Disk,
|
||||
Avg(PercentFree)
|
||||
FROM DiskSpace
|
||||
Group By
|
||||
Host,
|
||||
Disk
|
||||
Where __timeFilter(Time)
|
||||
```
|
||||
|
||||
This query returns the following Table response to Grafana:
|
||||
|
||||
| Host | Disk | PercentFree
|
||||
| --- | -----| --------
|
||||
| web1 | /etc | 3
|
||||
| web2 | /var | 4
|
||||
| web3 | /var | 0
|
||||
|
||||
When this query is used as the **condition** in an alert rule, then the non-zero will be alerting. As a result, three alert instances are produced:
|
||||
|
||||
| Labels | Status
|
||||
| ----------------------| ------
|
||||
| {Host=web1,disk=/etc} | Alerting
|
||||
| {Host=web2,disk=/var} | Alerting
|
||||
| {Host=web3,disk=/var} | Normal
|
||||
@@ -0,0 +1,102 @@
|
||||
+++
|
||||
title = "Message templating"
|
||||
description = "Message templating"
|
||||
aliases = ["/docs/grafana/latest/alerting/message-templating/"]
|
||||
keywords = ["grafana", "alerting", "guide", "contact point", "templating"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Message templating
|
||||
|
||||
Notifications sent via [contact points]({{< relref "../contact-points.md" >}}) are built using templates. Grafana comes with default templates which you can customize. Grafana's notification templates are based on the [Go templating system](https://golang.org/pkg/text/template) where some fields are evaluated as text, while others are evaluated as HTML which can affect escaping. Since most of the contact point fields can be templated, you can create reusable templates and them in multiple contact points. See [template data reference]({{< relref "./template-data.md" >}}) to check what variables are available in the templates.
|
||||
|
||||
|
||||
## Using templating in contact point fields
|
||||
|
||||
This section shows an example of using templating to render a number of firing or resolved alerts in Slack message title, and listing alerts with status and name in the message body:
|
||||
|
||||
<img src="/static/img/docs/alerting/unified/contact-points-template-fields-8-0.png" width="600px">
|
||||
|
||||
## Reusable templates
|
||||
|
||||
You can create named templates and then reuse them in contact point fields or other templates.
|
||||
|
||||
### Create a template
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Contact points**.
|
||||
1. Click **Add template**.
|
||||
1. Fill in **Name** and **Content** fields.
|
||||
1. Click **Save template** button at the bottom of the page.
|
||||
|
||||
**Note** The template name used to reference this template in templating is not the value of the **Name** field, but the parameter to `define` tag in the content. When creating a template you can omit `define` entirely and it will be added automatically with same value as **Name** field. It's recommended to use the same name for `define` and **Name** field to avoid confusion.
|
||||
|
||||
|
||||
<img src="/static/img/docs/alerting/unified/templates-create-8-0.png" width="600px">
|
||||
|
||||
### Edit a template
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Contact points**.
|
||||
1. Find the template you want to edit in the templates table and click the **pen icon** on the right side.
|
||||
1. Make any changes and click **Save template** button at the bottom of the page.
|
||||
|
||||
### Delete a template
|
||||
1. In the Grafana side bar, hover your cursor over the **Alerting** (bell) icon and then click **Contact points**.
|
||||
1. Find the template you want to edit in the templates table and click the **trash can icon** on the right side.
|
||||
1. A confirmation dialog will open. Click **Yes, delete**.
|
||||
|
||||
**Note** You are not prevented from deleting templates that are in use somewhere in contact points or other templates. Be careful!
|
||||
|
||||
### Use a template in a contact point field
|
||||
|
||||
To use a template:
|
||||
|
||||
Enter `{{ template "templatename" . }}` into a contact point field, where `templatename` is the `define` parameter of a template.
|
||||
|
||||
<img src="/static/img/docs/alerting/unified/contact-points-use-template-8-0.png" width="600px">
|
||||
|
||||
|
||||
### Template examples
|
||||
|
||||
Here is an example of a template to render a single alert:
|
||||
```
|
||||
{{ define "alert" }}
|
||||
[{{.Status}}] {{ .Labels.alertname }}
|
||||
|
||||
Labels:
|
||||
{{ range .Labels.SortedPairs }}
|
||||
{{ .Name }}: {{ .Value }}
|
||||
{{ end }}
|
||||
|
||||
{{ if gt (len .Annotations) 0 }}
|
||||
Annotations:
|
||||
{{ range .Annotations.SortedPairs }}
|
||||
{{ .Name }}: {{ .Value }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{ if gt (len .SilenceURL ) 0 }}
|
||||
Silence alert: {{ .SilenceURL }}
|
||||
{{ end }}
|
||||
{{ if gt (len .DashboardURL ) 0 }}
|
||||
Go to dashboard: {{ .Dashboard URL }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Template to render entire notification message:
|
||||
```
|
||||
{{ define "message" }}
|
||||
{{ if gt (len .Alerts.Firing) 0 }}
|
||||
{{ len .Alerts.Firing }} firing:
|
||||
{{ range .Alerts.Firing }} {{ template "alert" .}} {{ end }}
|
||||
{{ end }}
|
||||
{{ if gt (len .Alerts.Resolved) 0 }}
|
||||
{{ len .Alerts.Resolved }} resolved:
|
||||
{{ range .Alerts.Resolved }} {{ template "alert" .}} {{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Manage templates for an external Alertmanager
|
||||
|
||||
Grafana alerting UI supports managing external Alertmanager configuration. Once you add an [Alertmanager data source]({{< relref "../../../datasources/alertmanager.md" >}}), a dropdown displays at the top of the page, allowing you to select either `Grafana` or an external Alertmanager data source.
|
||||
|
||||
{{< figure max-width="40%" src="/static/img/docs/alerting/unified/contact-points-select-am-8-0.gif" caption="Select Alertmanager" >}}
|
||||
@@ -0,0 +1,75 @@
|
||||
+++
|
||||
title = "Template data"
|
||||
keywords = ["grafana", "alerting", "guide", "contact point", "templating"]
|
||||
+++
|
||||
|
||||
|
||||
# Template data
|
||||
|
||||
Template data is passed on to [message templates]({{< relref "./_index.md" >}}) as well as sent as payload to webhook pushes.
|
||||
|
||||
Name | Type | Notes
|
||||
------------------|----------|-----------------------------------------------------------------
|
||||
Receiver | string | Name of the contact point that the notification is being sent to.
|
||||
Status | string | `firing` if at least one alert is firing, otherwise `resolved`.
|
||||
Alerts | Alert | List of alert objects that are included in this notification (see below).
|
||||
GroupLabels | KeyValue | Labels these alerts were grouped by.
|
||||
CommonLabels | KeyValue | Labels common to all the alerts included in this notification.
|
||||
CommonAnnotations | KeyValue | Annotations common to all the alerts included in this notification.
|
||||
ExternalURL | string | Back link to the Grafana that sent the notification. If using external Alertmanager, back link to this Alertmanager.
|
||||
|
||||
The `Alerts` type exposes functions for filtering alerts:
|
||||
|
||||
* `Alerts.Firing` returns a list of firing alerts.
|
||||
* `Alerts.Resolved` returns a list of resolved alerts.
|
||||
|
||||
## Alert
|
||||
|
||||
Name | Type | Notes
|
||||
-------------|-----------|---------------------------------------------------------------------
|
||||
Status | string | `firing` or `resolved`.
|
||||
Labels | KeyValue | A set of labels attached to the alert.
|
||||
Annotations | KeyValue | A set of annotations attached to the alert.
|
||||
StartsAt | time.Time | Time the alert started firing.
|
||||
EndsAt | time.Time | Only set if the end time of an alert is known. Otherwise set to a configurable timeout period from the time since the last alert was received.
|
||||
GeneratorURL | string | A back link to Grafana or external Alertmanager.
|
||||
SilenceURL | string | Link to grafana silence for with labels for this alert pre-filled. Only for Grafana managed alerts.
|
||||
DashboardURL | string | Link to grafana dashboard, if alert rule belongs to one. Only for Grafana managed alerts.
|
||||
PanelURL | string | Link to grafana dashboard panel, if alert rule belongs to one. Only for Grafana managed alerts.
|
||||
Fingerprint | string | Fingerprint that can be used to identify the alert.
|
||||
|
||||
## KeyValue
|
||||
|
||||
`KeyValue` is a set of key/value string pairs that represent labels and annotations.
|
||||
|
||||
Here is an example containing two annotations:
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": "alert summary",
|
||||
"description": "alert description"
|
||||
}
|
||||
```
|
||||
|
||||
In addition to direct access of data (labels and annotations) stored as KeyValue, there are also methods for sorting, removing and transforming.
|
||||
|
||||
Name | Arguments | Returns | Notes
|
||||
------------|-----------|-----------------------------------------|----------------
|
||||
SortedPairs | | Sorted list of key & value string pairs |
|
||||
Remove | []string | KeyValue | Returns a copy of the Key/Value map without the given keys.
|
||||
Names | | []string | List of label names
|
||||
Values | | []string | List of label values
|
||||
|
||||
## Functions
|
||||
|
||||
Some functions to transform values are also available, along with [default functions provided by Go templating](https://golang.org/pkg/text/template/#hdr-Functions).
|
||||
|
||||
Name | Arguments | Returns
|
||||
-------------|------------------------------|----------------------------------------------
|
||||
title | string | Capitalizes first character of each word.
|
||||
toUpper | string | Converts all characters to upper case.
|
||||
match | pattern, string | Match a string using RegExp.
|
||||
reReplaceAll | pattern, replacement, string | RegExp substitution, unanchored.
|
||||
join | string, []string | Concatenates the elements of the second argument to create a single string. First argument is the separator.
|
||||
safeHtml | string | Marks string as HTML, not requiring auto-escaping.
|
||||
stringSlice | ...string | Returns passed strings as slice of strings.
|
||||
@@ -0,0 +1,76 @@
|
||||
+++
|
||||
title = "Notification policies"
|
||||
description = "Notification policies"
|
||||
keywords = ["grafana", "alerting", "guide", "notification policies", "routes"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# 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 enters policy tree at the root and then traverses each child policy. If `Continue matching subsequent sibling nodes` is not checked, it stops at the first matching node, otherwise, it continues matching it's siblings as well. If an alert does not match any children of a policy, the alert is handled based on the configuration settings of this policy and notified to the contact point configured on this policy. Alert that does not match any specific policy is handled by the root policy.
|
||||
|
||||
Grafana alerting UI allows you to configure Grafana notification policies as well as notification policies (routes) for an [external Alertmanager if one is configured]({{< relref "../../datasources/alertmanager.md" >}}).
|
||||
|
||||
|
||||
## Edit notification policies
|
||||
|
||||
To access notification policy editing page, In the Grafana side bar, hover your cursor over the **Alerting (bell)** icon and then click **Notification policies**.
|
||||
|
||||
### Edit root notification policy
|
||||
|
||||
1. Click **edit** button on the top right of the root policy box.
|
||||
1. Make changes and click **save** button.
|
||||
|
||||
### Add new specific policy
|
||||
|
||||
To add a top level specific policy, click **New policy** button in the **Specific routing** section, fill in the form and click **Save policy**.
|
||||
|
||||
To add a nested policy to an existing specific policy, expand the parent policy in specific routing table and click **Add nested policy**. fill in the form and click **Save policy**.
|
||||
|
||||
### Edit specific policy
|
||||
|
||||
To edit a specific policy, find it in the specific routing table and click **Edit** button. Make your changes and click **Save policy**.
|
||||
|
||||
|
||||
### Root policy fields
|
||||
|
||||
- **Default contact point -** The [contact point]({{< relref "./contact-points.md" >}}) to send notifications to that did not match any specific policy.
|
||||
- **Group by -** Labels to group alerts by. If multiple alerts are matched for this policy, they will be grouped based on these labels and a notification will be sent per group. Mandatory for root policy, optional for nested specific policies. If a specific policy does not specify own grouping, root policy grouping will be used.
|
||||
|
||||
Group timing options
|
||||
|
||||
- **Group wait -** - How long to wait to buffer alerts of the same group before sending a notification initially. Default is 30 seconds.
|
||||
- **Group interval -** - How long to wait before sending an notification when an alert has been added to a group for which there has already been a notification. Default is 5 minutes.
|
||||
- **Repeat interval -** - How long to wait before re-sending a notification after one has already been sent and no new alerts were added to the group. Default is 4 hours.
|
||||
|
||||
|
||||
### Specific policy fields
|
||||
|
||||
- **Contact point -** The [contact point]({{< relref "./contact-points.md" >}}) to send notification to if alert matched this specific policy but did not match any of it's nested policies, or there were no nested specific policies.
|
||||
- **Matching labels -** Rules for matching alert labels. See ["How label matching works"](#how-label-matching-works) below for details.
|
||||
- **Continue matching subsequent sibling nodes -** If not enabled and an alert matches this policy but not any of it's nested policies, matching will stop and a notification will be sent to the contact point defined on this policy. If enabled, notification will be sent but alert will continue matching subsequent siblings of this policy, thus sending more than one notification. Use this if for example you want to send notification to a catch-all contact point as well as to one of more specific contact points handled by subsequent policies.
|
||||
- **Override grouping** - Toggle if you want to override grouping for this policy. If toggled, you will be able to specify grouping same as for root policy described above. If not toggled, root policy grouping will be used.
|
||||
- **Override group timings** Toggle if you want to override group timings for this policy. If toggled, you will be able to specify group timings same as for root policy described above. If not toggled, root policy group timings will be used.
|
||||
|
||||
|
||||
### How label matching works
|
||||
|
||||
A policy will match an alert if alert's labels match all of the "Matching Labels" specified on the policy.
|
||||
|
||||
- The **Label** field is the name of the label to match. It must exactly match the label name.
|
||||
- The **Value** field matches against the corresponding value for the specified **Label** name. How it matches depends on the **Regex** and **Equal** checkboxes.
|
||||
- The **Regex** checkbox specifies if the inputted **Value** should be matched against labels as a regular expression. The regular expression is always anchored. If not selected it is an exact string match.
|
||||
- The **Equal** checkbox specifies if the match should include alert instances that match or do not match. If not checked, the silence includes alert instances _do not_ match.
|
||||
|
||||
|
||||
## Example setup
|
||||
|
||||
One usage example would be:
|
||||
* Create a "default" contact point for most alerts with a non invasive contact point type, like a slack message, and set it on root policy
|
||||
* Edit root policy grouping to group alerts by `cluster`, `namespace` and `alertname` so you get a notification per alert rule and specific k8s cluster & namespace.
|
||||
* Create specific route for alerts coming from development cluster with an appropriate contact point
|
||||
* Create a specific route for alerts with "critical" severity with a more invasive contact point type, like pager duty notification
|
||||
* Create specific routes for particular teams that handle their own onduty rotations
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
+++
|
||||
title = "Opt-in to Grafana 8 Alerts"
|
||||
description = "How to enable Grafana 8 Alerts"
|
||||
+++
|
||||
|
||||
# Enable Grafana 8 Alerts
|
||||
Setting the `ngalert` feature toggle enables the new Grafana 8 Alerting system.
|
||||
|
||||
>**Note:** It is recommended to backup Grafana's database before enabling this feature. If you are using PostgreSQL as the backend data source, then the minimum required version is 9.5.
|
||||
|
||||
At startup, when the feature toggle is enabled, Grafana dashboard alerting is disabled and existing dashboard alerts are migrated into a format that is compatible with the Grafana 8 Alerting system. You are able to view these migrated rules, alongside any new alerts you create after the migration, from the Alerting page of your grafana installation.
|
||||
Also notification channels are migrated to an Alertmanager configuration with the appropriate routes and receivers. Default notification channels are added as contact points to the default route. Notification channels not associated with any dahsboard alert go to the `autogen-unlinked-channel-recv` route.
|
||||
Since `Hipchat` and `Sensu` are discontinued, they are not migrated to the new alerting. If you have dashboard alerts associated with those types of channels and you want to migrate to the new alerting, make sure you assign another supported notification channel, so that you continue to receive notifications for those alerts.
|
||||
Finally, silences (expiring after one year) are created for all paused dashboard alerts.
|
||||
|
||||
During beta, the migration of existing dashboard rules may change.
|
||||
|
||||
## Disabling Grafana 8 Alerting after migration
|
||||
To disable Grafana 8 Alerting, remove or disable the `ngalert` feature toggle. Dashboard alerts will be re-enabled and any alerts created during or after the migration are deleted.
|
||||
|
||||
>**Note:** Any alerting rules created in the Grafana 8 Alerting system will be lost when migrating back to dashboard alerts
|
||||
@@ -0,0 +1,41 @@
|
||||
+++
|
||||
title = "Silence alert notifications"
|
||||
description = "Silence alert notifications"
|
||||
keywords = ["grafana", "alerting", "silence", "mute"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Silence alert notifications
|
||||
|
||||
Grafana allows to you to prevent notifications from one or more alert rules by creating a silence. This silence lasts for a specified window of time.
|
||||
|
||||
Silences do not prevent alert rules from being evaluated. They also do not stop alert instances being shown in the user interface. Silences only prevent notifications from being created.
|
||||
|
||||
## Add a silence
|
||||
|
||||
To add a silence:
|
||||
|
||||
1. In the Grafana menu, hover your cursor over the **Alerting** (bell) icon and then select **Silences** (crossed out bell icon).
|
||||
1. Click the **New Silence** button.
|
||||
1. Select the start and end date in **Silence start and end** to indicate when the silence should go into effect and expire.
|
||||
1. Optionally, update the **Duration** to alter the time for the end of silence in the previous step to correspond to the start plus the duration.
|
||||
1. Enter one or more *Matching Labels* by filling out the **Name** and **Value** fields. Matchers determine which rules the silence will apply to.
|
||||
1. Enter a **Comment**.
|
||||
1. Enter the name of the owner in **Creator**.
|
||||
1. Click **Create**.
|
||||
|
||||
## How label matching works
|
||||
|
||||
Alert instances that have labels that match all of the "Matching Labels" specified in the silence will have their notifications suppressed.
|
||||
|
||||
- The **Label** field is the name of the label to match. It must exactly match the label name.
|
||||
- The **Value** field matches against the corresponding value for the specified **Label** name. How it matches depends on the **Regex** and **Equal** checkboxes.
|
||||
- The **Regex** checkbox specifies if the inputted **Value** should be matched against labels as a regular expression. The regular expression is always anchored. If not selected it is an exact string match.
|
||||
- The **Equal** checkbox specifies if the match should include alert instances that match or do not match. If not checked, the silence includes alert instances _do not_ match.
|
||||
|
||||
## Viewing and editing silences
|
||||
|
||||
1. In the Grafana menu hover your cursor over the **Alerting** (bell) icon, then select **Silences** (crossed out bell icon).
|
||||
1. To end the silence, click the **Unsilence** option next to the listed silence. Silences that have ended are still listed and are automatically removed after 5 days. There is no method for manual removal.
|
||||
1. To edit a silence, click the pencil icon next to the listed silence. Edit the silence using instructions on how to create a silence.
|
||||
1. Click **Submit** to save your changes.
|
||||
@@ -76,7 +76,7 @@ In this case the labels that represent the dimensions will have two keys based o
|
||||
|
||||
> **Note:** More than one dimension is currently only supported in the Logs queries within the Azure Monitor service as of version 7.1.
|
||||
|
||||
> **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. See the documentation on [creating alerts with multiple series]({{< relref "../alerting/create-alerts.md#multiple-series" >}}).
|
||||
> **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. See the documentation on [creating alerts with multiple series]({{< relref "../alerting/old-alerting/create-alerts.md#multiple-series" >}}).
|
||||
|
||||
### Multiple values
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
+++
|
||||
title = "Time series"
|
||||
title = "Intro to time series"
|
||||
description = "Introduction to time series"
|
||||
keywords = ["grafana", "intro", "guide", "concepts", "timeseries"]
|
||||
weight = 400
|
||||
|
||||
@@ -30,7 +30,7 @@ You can also hold down Ctrl/Cmd and select region to create a region annotation.
|
||||
{{< figure src="/static/img/docs/annotations/region-annotation-still.png"
|
||||
max-width="600px" animated-gif="/static/img/docs/annotations/region-annotation.gif" >}}
|
||||
|
||||
### Built in query
|
||||
### Built-in query
|
||||
|
||||
After you added an annotation they will still be visible. This is due to the built in annotation query that exists on all dashboards. This annotation query will
|
||||
fetch all annotation events that originate from the current dashboard and show them on the panel where they were created. This includes alert state history annotations. You can
|
||||
|
||||
@@ -16,6 +16,7 @@ Each data source has a specific Query Editor that is customized for the features
|
||||
|
||||
The following data sources are officially supported:
|
||||
|
||||
- [Alertmanager]({{< relref "alertmanager.md" >}})
|
||||
- [AWS CloudWatch]({{< relref "cloudwatch.md" >}})
|
||||
- [Azure Monitor]({{< relref "azuremonitor.md" >}})
|
||||
- [Elasticsearch]({{< relref "elasticsearch.md" >}})
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
+++
|
||||
title = "Alertmanager"
|
||||
description = "Guide for using Alertmanager in Grafana"
|
||||
keywords = ["grafana", "prometheus", "guide"]
|
||||
aliases = ["/docs/grafana/latest/features/datasources/alertmanager"]
|
||||
weight = 1300
|
||||
+++
|
||||
|
||||
# Alertmanager data source
|
||||
|
||||
Grafana includes built-in support for Prometheus Alertmanager. It is presently in alpha and not accessible unless [alpha plugins are enabled in Grafana settings](https://grafana.com/docs/grafana/latest/administration/configuration/#enable_alpha). Once you add it as a data source, you can use the [Grafana alerting UI](https://grafana.com/docs/grafana/latest/alerting/) to manage silences, contact points as well as notification policies. A drop down option in these pages allows you to switch between Grafana and any configured Alertmanager data sources .
|
||||
|
||||
>**Note:** New in Grafana 8.0.
|
||||
|
||||
>**Note:** Currently only the [Cortex implementation of Prometheus alertmanager](https://cortexmetrics.io/docs/proposals/scalable-alertmanager/) is supported.
|
||||
|
||||
## Provision the Alertmanager data source
|
||||
|
||||
Configure the Alertmanager data sources by updating Grafana's configuration files. For more information on how it works and the settings available, refer to the [provisioning docs page]({{< relref "../administration/provisioning/#datasources" >}}).
|
||||
|
||||
Here is an example for provisioning the Alertmanager data source:
|
||||
|
||||
```yaml
|
||||
apiVersion: 1
|
||||
|
||||
datasources:
|
||||
- name: Alertmanager
|
||||
type: alertmanager
|
||||
url: http://localhost:9090
|
||||
access: proxy
|
||||
# optionally
|
||||
basicAuth: true
|
||||
basicAuthUser: my_user
|
||||
basicAuthPassword: test_password
|
||||
```
|
||||
@@ -221,7 +221,7 @@ The default display name format is:
|
||||
|
||||
`metricName{dimensionName=dimensionValue,dimensionTwoName=DimensionTwoValue}`
|
||||
|
||||
This can be customized by using the [display name field option]({{< relref "../panels/field-options/_index.md#display-name" >}}).
|
||||
This can be customized by using the [display name field option]({{< relref "../panels/standard-options.md#display-name" >}}).
|
||||
|
||||
### Logs macros
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@ a time pattern for the index name or a wildcard.
|
||||
### Elasticsearch version
|
||||
|
||||
Select the version of your Elasticsearch data source from the version selection dropdown. Different query compositions and functionalities are available in the query editor for different versions.
|
||||
Available Elasticsearch versions are `2.x`, `5.x`, `5.6+`, `6.0+`, and `7.0+`. Select the option that best matches your data source version.
|
||||
Available Elasticsearch versions are `2.x`, `5.x`, `5.6+`, `6.0+`, `7.0+` and `7.7+`. Select the option that best matches your data source version.
|
||||
|
||||
Grafana assumes that you are running the lowest possible version for a specified range. This ensures that new features or breaking changes in a future Elasticsearch release will not affect your configuration.
|
||||
|
||||
|
||||
@@ -111,7 +111,7 @@ When the operator is set to `=~` or `!=~` it is possible to add regular expressi
|
||||
|
||||
Preprocessing options are displayed in the UI when the selected metric has a metric kind of `delta` or `cumulative`. If the selected metric has a metric kind of `gauge`, no pre-processing option will be displayed.
|
||||
|
||||
If you select 'Rate', data points are aligned and converted to a rate per time series. If you select 'Delta', data points are aligned by their delta (difference) per time series.
|
||||
If you select `Rate`, data points are aligned and converted to a rate per time series. If you select `Delta`, data points are aligned by their delta (difference) per time series.
|
||||
|
||||
#### Grouping
|
||||
|
||||
|
||||
@@ -18,12 +18,12 @@ Add it as a data source and you are ready to build dashboards or query your log
|
||||
|
||||
To access Loki settings, click the **Configuration** (gear) icon, then click **Data Sources**, and then click the Loki data source.
|
||||
|
||||
| Name | Description |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Name` | The data source name. This is how you refer to the data source in panels, queries, and Explore. |
|
||||
| `Default` | Default data source means that it will be pre-selected for new panels. |
|
||||
| `URL` | The URL of the Loki instance, e.g., `http://localhost:3100` |
|
||||
| `Whitelisted Cookies` | Grafana Proxy deletes forwarded cookies by default. Specify cookies by name that should be forwarded to the data source. |
|
||||
| Name | Description |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Name` | The data source name. This is how you refer to the data source in panels, queries, and Explore. |
|
||||
| `Default` | Default data source that is pre-selected for new panels. |
|
||||
| `URL` | URL of the Loki instance, e.g., `http://localhost:3100`. |
|
||||
| `Whitelisted Cookies` | Grafana Proxy deletes forwarded cookies by default. Specify cookies by name that should be forwarded to the data source. |
|
||||
| `Maximum lines` | Upper limit for the number of log lines returned by Loki (default is 1000). Lower this limit if your browser is sluggish when displaying logs in Explore. |
|
||||
|
||||
### Derived fields
|
||||
@@ -52,21 +52,22 @@ The new field with the link shown in log details:
|
||||
|
||||
You can use the Loki query editor to create log and metric queries.
|
||||
|
||||
| Name | Description |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Query expression` | Loki query expression, refer to the [LogQL documentation](https://grafana.com/docs/loki/latest/logql/) for more information. |
|
||||
| Name | Description |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Query expression` | Loki query expression, refer to the [LogQL documentation](https://grafana.com/docs/loki/latest/logql/) for more information. |
|
||||
| `Query type` | Choose the type of query to run. The instant type queries against a single point in time. We are using "To" time from the time range. The range type queries over the selected range of time. |
|
||||
| `Line limit` | Upper limit for number of log lines returned by query. The default is the Maximum lines limit set in Loki settings. |
|
||||
| `Legend` | Available only in Dashboard. Controls the name of the time series, using name or pattern. For example `{{hostname}}` is replaced with the label value for the label `hostname`. |
|
||||
| `Line limit` | Upper limit for number of log lines returned by query. The default is the Maximum lines limit set in Loki settings. |
|
||||
| `Legend` | Available only in Dashboard. Controls the name of the time series, using name or pattern. For example `{{hostname}}` is replaced with the label value for the label `hostname`. |
|
||||
|
||||
### Log browser
|
||||
|
||||
With Loki log browser you can easily navigate trough your list of labels and values and construct the query of your choice. Log browser has multi-step selection:
|
||||
|
||||
1. Choose the labels you would like to consider for your search.
|
||||
2. Pick the values for selected labels. Log browser supports facetting and therefore it shows you only possible label combinations.
|
||||
3. Choose the type of query - logs query or rate metrics query. Additionally, you can also validate selector.
|
||||
|
||||
{{< figure src="/static/img/docs/v75/loki_log_browser.png" class="docs-image--no-shadow" max-width="800px" caption="Screenshot of the derived fields debugging" >}}
|
||||
{{< figure src="/static/img/docs/v75/loki_log_browser.png" class="docs-image--no-shadow" max-width="800px" caption="Screenshot of the log browser for Loki" >}}
|
||||
|
||||
## Querying with Loki
|
||||
|
||||
|
||||
@@ -21,17 +21,18 @@ Grafana ships with a built-in MySQL data source plugin that allows you to query
|
||||
|
||||
### Data source options
|
||||
|
||||
Name | Description
|
||||
-------------- | -------------
|
||||
`Name` | The data source name. This is how you refer to the data source in panels and queries.
|
||||
`Default` | Default data source means that it will be pre-selected for new panels.
|
||||
`Host` | The IP address/hostname and optional port of your MySQL instance.
|
||||
`Database` | Name of your MySQL database.
|
||||
`User` | Database user's login/username
|
||||
`Password` | Database user's password
|
||||
`Max open` | The maximum number of open connections to the database, default `unlimited` (Grafana v5.4+).
|
||||
`Max idle` | The maximum number of connections in the idle connection pool, default `2` (Grafana v5.4+).
|
||||
`Max lifetime` | The maximum amount of time in seconds a connection may be reused, default `14400`/4 hours. This should always be lower than configured [wait_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_wait_timeout) in MySQL (Grafana v5.4+).
|
||||
Name | Description
|
||||
------------------ | -------------
|
||||
`Name` | The data source name. This is how you refer to the data source in panels and queries.
|
||||
`Default` | Default data source means that it will be pre-selected for new panels.
|
||||
`Host` | The IP address/hostname and optional port of your MySQL instance.
|
||||
`Database` | Name of your MySQL database.
|
||||
`User` | Database user's login/username
|
||||
`Password` | Database user's password
|
||||
`Session Timezone` | Specify the time zone used in the database session, such as `Europe/Berlin` or `+02:00`. This is necessary, if the timezone of the database (or the host of the database) is set to something other than UTC. Set the value used in the session with `SET time_zone='...'`. If you leave this field empty, then the time zone is not updated. For more information, refer to the [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html).
|
||||
`Max open` | The maximum number of open connections to the database, default `unlimited` (Grafana v5.4+).
|
||||
`Max idle` | The maximum number of connections in the idle connection pool, default `2` (Grafana v5.4+).
|
||||
`Max lifetime` | The maximum amount of time in seconds a connection may be reused, default `14400`/4 hours. This should always be lower than configured [wait_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_wait_timeout) in MySQL (Grafana v5.4+).
|
||||
|
||||
### Min time interval
|
||||
|
||||
|
||||
@@ -14,22 +14,22 @@ Grafana includes built-in support for Prometheus. This topic explains options, v
|
||||
|
||||
To access Prometheus settings, hover your mouse over the **Configuration** (gear) icon, then click **Data Sources**, and then click the Prometheus data source.
|
||||
|
||||
| Name | Description |
|
||||
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Name` | The data source name. This is how you refer to the data source in panels and queries. |
|
||||
| `Default` | Default data source means that it will be pre-selected for new panels. |
|
||||
| `Url` | The URL of your Prometheus server, e.g. `http://prometheus.example.org:9090`. |
|
||||
| `Access` | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. |
|
||||
| `Basic Auth` | Enable basic authentication to the Prometheus data source. |
|
||||
| `User` | User name for basic authentication. |
|
||||
| `Password` | Password for basic authentication. |
|
||||
| `Scrape interval` | Set this to the typical scrape and evaluation interval configured in Prometheus. Defaults to 15s.
|
||||
| `HTTP method` | Use either POST or GET HTTP method to query your data source. POST is the recommended and pre-selected method as it allows bigger queries. Change this to GET if you have a Prometheus version older than 2.1 or if POST requests are restricted in your network. |
|
||||
| `Disable metrics lookup` | Checking this option will disable the metrics chooser and metric/label support in the query field's autocomplete. This helps if you have performance issues with bigger Prometheus instances. |
|
||||
| `Custom Query Parameters` | Add custom parameters to the Prometheus query URL. For example `timeout`, `partial_response`, `dedup`, or `max_source_resolution`. Multiple parameters should be concatenated together with an '&'. |
|
||||
| `Label name` | Add the name of the field in the label object. |
|
||||
| `URL` | If the link is external, then enter the full link URL. You can interpolate the value from the field with `${__value.raw }` macro. |
|
||||
| `Internal link` | Select if the link is internal or external. In the case of an internal link, a data source selector allows you to select the target data source. Supports tracing data sources only. |
|
||||
| Name | Description |
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Name` | The data source name. This is how you refer to the data source in panels and queries. |
|
||||
| `Default` | Default data source that is pre-selected for new panels. |
|
||||
| `Url` | The URL of your Prometheus server, for example, `http://prometheus.example.org:9090`. |
|
||||
| `Access` | Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser. |
|
||||
| `Basic Auth` | Enable basic authentication to the Prometheus data source. |
|
||||
| `User` | User name for basic authentication. |
|
||||
| `Password` | Password for basic authentication. |
|
||||
| `Scrape interval` | Set this to the typical scrape and evaluation interval configured in Prometheus. Defaults to 15s. |
|
||||
| `HTTP method` | Use either POST or GET HTTP method to query your data source. POST is the recommended and pre-selected method as it allows bigger queries. Change this to GET if you have a Prometheus version older than 2.1 or if POST requests are restricted in your network. |
|
||||
| `Disable metrics lookup` | Checking this option will disable the metrics chooser and metric/label support in the query field's autocomplete. This helps if you have performance issues with bigger Prometheus instances. |
|
||||
| `Custom Query Parameters` | Add custom parameters to the Prometheus query URL. For example `timeout`, `partial_response`, `dedup`, or `max_source_resolution`. Multiple parameters should be concatenated together with an '&'. |
|
||||
| `Label name` | Add the name of the field in the label object. |
|
||||
| `URL` | If the link is external, then enter the full link URL. You can interpolate the value from the field with `${__value.raw }` macro. |
|
||||
| `Internal link` | Select if the link is internal or external. In the case of an internal link, a data source selector allows you to select the target data source. Supports tracing data sources only. |
|
||||
|
||||
## Prometheus query editor
|
||||
|
||||
@@ -76,6 +76,29 @@ To show a horizontal line across the whole graph, add a series override and sele
|
||||
| `Query type` | `Range`, `Instant`, or `Both`. When running **Range query**, the result of the query is displayed in graph and table. Instant query returns only the latest value that Prometheus has scraped for the requested time series and it is displayed in the table. When **Both** is selected, both instant query and range query is run. Result of range query is displayed in graph and the result of instant query is displayed in the table. |
|
||||
| `Exemplars` | Run and show exemplars in the graph. |
|
||||
|
||||
### Metrics browser
|
||||
|
||||
The metrics browser allows you to quickly find metrics and select relevant labels to build basic queries.
|
||||
When you open the browser you will see all available metrics and labels.
|
||||
If supported by your Prometheus instance, each metric will show its HELP and TYPE as a tooltip.
|
||||
|
||||
{{< figure src="/static/img/docs/v8/prometheus_metrics_browser.png" class="docs-image--no-shadow" max-width="800px" caption="Screenshot of the metrics browser for Prometheus" >}}
|
||||
|
||||
When you select a metric, the browser narrows down the available labels to show only the ones applicable to the metric.
|
||||
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 first, to narrow down the list and then find relevant label values.
|
||||
|
||||
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 only has one search field. Its filtering applies to all labels to help you find values across labels once they have been selected, for example, among your labels `app`, `job`, `job_name` only one might with the value you are looking for.
|
||||
|
||||
Once you are satisfied with your query, click "Use query" to run the query. The button "Use as rate query" adds a `rate(...)[$__interval]` around your query to help write queries for counter metrics.
|
||||
The "Validate selector" button will check with Prometheus how many time series are available for that selector.
|
||||
|
||||
#### Limitations
|
||||
|
||||
The metrics browser has a hard limit of 10,000 labels (keys) and 50,000 label values (including metric names). If your Prometheus instance returns more results, the browser will continue functioning. However, the result sets will be cut off above those maximum limits.
|
||||
|
||||
## Templating
|
||||
|
||||
Instead of hard-coding things like server, application and sensor name in your metric queries, you can use variables in their place.
|
||||
|
||||
@@ -3,23 +3,114 @@ title = "Add authentication for data source plugins"
|
||||
aliases = ["/docs/grafana/latest/plugins/developing/auth-for-datasources/", "/docs/grafana/next/developers/plugins/authentication/"]
|
||||
+++
|
||||
|
||||
# Add authentication for data source plugins
|
||||
# Add authentication for data source plugins
|
||||
|
||||
This page explains how to use the Grafana data source proxy to authenticate against a third-party API from a data source plugin.
|
||||
This page explains how to configure your data source plugin to authenticate against a third-party API.
|
||||
|
||||
When a user saves a password or any other sensitive data as a data source option, Grafana encrypts the data and stores it in the Grafana database. Any encrypted data source options can only be decrypted on the Grafana server. This means that any data source that makes authenticated queries needs to request the decrypted data to be sent to the browser.
|
||||
There are two ways you can perform authenticated requests from your plugin—using the [_data source proxy_](#authenticate-using-the-data-source-proxy), or by building a [_backend plugin_](#authenticate-using-a-backend-plugin). The one you choose depends on how your plugin authenticates against the third-party API.
|
||||
|
||||
To minimize the amount of sensitive information sent to and from the browser, data source plugins can use the Grafana _data source proxy_. When using the data source proxy, any requests containing sensitive information go through the Grafana server. No sensitive data is sent to the browser after the data is saved.
|
||||
- Use the data source proxy if you need to authenticate using Basic Auth or API keys
|
||||
- Use the data source proxy if the API supports OAuth 2.0 using client credentials
|
||||
- Use a backend plugin if the API uses a custom authentication method that isn't supported by the data source proxy, or if your API communicates over a different protocol than HTTP
|
||||
|
||||
Some data sources, like [Prometheus]({{< relref "../../datasources/prometheus.md" >}}) and [InfluxDB]({{< relref "../../datasources/influxdb" >}}), allow users to configure whether to use the data source proxy, through a setting called _access modes_.
|
||||
Regardless of which approach you use, you first need to encrypt any sensitive information that the plugin needs to store.
|
||||
|
||||
## Add a proxy route to your plugin
|
||||
## Encrypt data source configuration
|
||||
|
||||
To forward requests through the Grafana proxy, you need to configure one or more _routes_. A route specifies how the proxy transforms outgoing requests. All routes for a given plugin are defined in the [plugin.json]({{< relref "metadata.md" >}}) file.
|
||||
Data source plugins have two ways of storing custom configuration: `jsonData` and `secureJsonData`.
|
||||
|
||||
Let's add a route to proxy requests to `https://api.example.com/foo/bar`.
|
||||
Users with the _Viewer_ role can access data source configuration—such as the contents of `jsonData`—in cleartext. If you've enabled anonymous access, anyone that can access Grafana in their browser can see the contents of `jsonData`. **Only use `jsonData` to store non-sensitive configuration.**
|
||||
|
||||
1. Add the route to `plugin.json`. Note that you need to reload the Grafana server every time you make a change to your `plugin.json` file.
|
||||
> **Note:** You can see the settings that the current user has access to by entering `window.grafanaBootData` in the developer console of your browser.
|
||||
|
||||
> **Note:** Users of [Grafana Enterprise](https://grafana.com/products/enterprise/grafana/) can restrict access to data sources to specific users and teams. For more information, refer to [Data source permissions](https://grafana.com/docs/grafana/latest/enterprise/datasource_permissions).
|
||||
|
||||
If you need to store sensitive information, such as passwords, tokens and API keys, use `secureJsonData` instead. Whenever the user saves the data source configuration, the secrets in `secureJsonData` are sent to the Grafana server and encrypted before they're stored.
|
||||
|
||||
Once the secure configuration has been encrypted, it can no longer be accessed from the browser. The only way to access secrets after they've been saved is by using the [_data source proxy_](#authenticate-using-the-data-source-proxy).
|
||||
|
||||
#### Add secret configuration to your data source plugin
|
||||
|
||||
To demonstrate how you can add secrets to a data source plugin, let's add support for configuring an API key.
|
||||
|
||||
Create a new interface in `types.go` to hold the API key.
|
||||
|
||||
```ts
|
||||
export interface MySecureJsonData {
|
||||
apiKey?: string;
|
||||
}
|
||||
```
|
||||
|
||||
Add type information to your `secureJsonData` object by updating the props for your `ConfigEditor` to accept the interface as a second type parameter.
|
||||
|
||||
```ts
|
||||
interface Props extends DataSourcePluginOptionsEditorProps<MyDataSourceOptions, MySecureJsonData> {}
|
||||
```
|
||||
|
||||
You can access the value of the secret from the `options` prop inside your `ConfigEditor` until the user saves the configuration. When the user saves the configuration, Grafana clears the value. After that, you can use the `secureJsonFields` to determine whether the property has been configured.
|
||||
|
||||
```ts
|
||||
const { secureJsonData, secureJsonFields } = options;
|
||||
const { apiKey } = secureJsonData;
|
||||
```
|
||||
|
||||
To securely update the secret in your plugin's configuration editor, update the `secureJsonData` object using the `onOptionsChange` prop.
|
||||
|
||||
```ts
|
||||
const onAPIKeyChange = (event: ChangeEvent<HTMLInputElement>) => {
|
||||
onOptionsChange({
|
||||
...options,
|
||||
secureJsonData: {
|
||||
apiKey: event.target.value,
|
||||
},
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
Next, define a component that can accept user input.
|
||||
|
||||
```ts
|
||||
<Input
|
||||
type="password"
|
||||
placeholder={secureJsonFields?.apiKey ? 'configured' : ''}
|
||||
value={secureJsonData.apiKey ?? ''}
|
||||
onChange={onAPIKeyChange}
|
||||
/>
|
||||
```
|
||||
|
||||
Finally, if you want the user to be able to reset the API key, then you need to set the property to `false` in the `secureJsonFields` object.
|
||||
|
||||
```ts
|
||||
const onResetAPIKey = () => {
|
||||
onOptionsChange({
|
||||
...options,
|
||||
secureJsonFields: {
|
||||
...options.secureJsonFields,
|
||||
apiKey: false,
|
||||
},
|
||||
secureJsonData: {
|
||||
...options.secureJsonData,
|
||||
apiKey: '',
|
||||
},
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
Now that users can configure secrets, the next step is to see how we can add them to our requests.
|
||||
|
||||
## Authenticate using the data source proxy
|
||||
|
||||
Once the user has saved the configuration for a data source, any secret data source configuration will no longer be available in the browser. Encrypted secrets can only be accessed on the server. So how do you add them to you request?
|
||||
|
||||
The Grafana server comes with a proxy that lets you define templates for your requests. We call them _proxy routes_. Grafana sends the proxy route to the server, decrypts the secrets along with other configuration, and adds them to the request before sending it off.
|
||||
|
||||
> **Note:** Be sure not to confuse the data source proxy with the [auth proxy]({{< relref "../../auth/auth-proxy.md" >}}). The data source proxy is used to authenticate a data source, while the auth proxy is used to log into Grafana itself.
|
||||
|
||||
### Add a proxy route to your plugin
|
||||
|
||||
To forward requests through the Grafana proxy, you need to configure one or more proxy routes. A proxy route is a template for any outgoing request that is handled by the proxy. You can configure proxy routes in the [plugin.json](https://grafana.com/docs/grafana/latest/developers/plugins/metadata/) file.
|
||||
|
||||
1. Add the route to plugin.json. Note that you need to restart the Grafana server every time you make a change to your plugin.json file.
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
@@ -43,27 +134,30 @@ Let's add a route to proxy requests to `https://api.example.com/foo/bar`.
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
1. In the `query` method, make a request using [BackendSrv]({{< relref "../../packages_api/runtime/backendsrv.md" >}}).
|
||||
1. In the `query` method, make a request using `BackendSrv`. The first section of the URL path needs to match the `path` of your proxy route. The data source proxy replaces `this.url + routePath` with the `url` of the route. The following request will be made to `https://api.example.com/v1/users`.
|
||||
|
||||
```ts
|
||||
import { getBackendSrv } from '@grafana/runtime';
|
||||
```
|
||||
|
||||
```ts
|
||||
const routePath = '/example';
|
||||
|
||||
getBackendSrv()
|
||||
.datasourceRequest({
|
||||
url: this.url + routePath + '/foo/bar',
|
||||
url: this.url + routePath + '/v1/users',
|
||||
method: 'GET',
|
||||
});
|
||||
```
|
||||
|
||||
## Add a dynamic proxy route to your plugin
|
||||
### Add a dynamic proxy route to your plugin
|
||||
|
||||
In the example above, the URL stays the same for everyone using the plugin. Let's look at how you can create dynamic routes based on data source options that are provided by the user.
|
||||
Grafana sends the proxy route to the server, where the data source proxy decrypts any sensitive data and interpolates the template variables with the decrypted data before making the request.
|
||||
|
||||
Many of the properties in the `route` object can use templates in the form of `{{ .JsonData.YOUR_OPTION_NAME }}`, where `YOUR_OPTION_NAME` is the name of a property in the `jsonData` object.
|
||||
To add user-defined configuration to your routes, add `{{ .JsonData.apiKey }}` to the route, where `apiKey` is the name of a property in the `jsonData` object.
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
@@ -74,7 +168,7 @@ Many of the properties in the `route` object can use templates in the form of `{
|
||||
]
|
||||
```
|
||||
|
||||
You can also access sensitive data in your route configuration by changing `.JsonData` into `.SecureJsonData`.
|
||||
You can also configure your route to use sensitive data by using `.SecureJsonData`.
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
@@ -85,17 +179,9 @@ You can also access sensitive data in your route configuration by changing `.Jso
|
||||
]
|
||||
```
|
||||
|
||||
Now you know how to define routes for your data source plugin. Next, let's look at how to authenticate requests for your routes.
|
||||
In addition to the URL, you can also add headers, URL parameters, and a request body, to a proxy route.
|
||||
|
||||
## Configure the authentication method for a route
|
||||
|
||||
The Grafana proxy supports a number of different authentication methods. For more information on how to configure each authentication method, refer to [plugin.json]({{< relref "metadata.md" >}}).
|
||||
|
||||
For any sensitive data, make sure that you encrypt data source options, and that you use `{{ .SecureJsonData.YOUR_OPTION_NAME }}` when using sensitive data source options in your routes.
|
||||
|
||||
### Add HTTP header
|
||||
|
||||
To add HTTP headers to proxied requests, use the `headers` property.
|
||||
#### Add HTTP headers to a proxy route
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
@@ -112,9 +198,7 @@ To add HTTP headers to proxied requests, use the `headers` property.
|
||||
]
|
||||
```
|
||||
|
||||
### Add URL parameters
|
||||
|
||||
To add URL parameters to proxied requests, use the `urlParams` property.
|
||||
#### Add URL parameters to a proxy route
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
@@ -131,9 +215,7 @@ To add URL parameters to proxied requests, use the `urlParams` property.
|
||||
]
|
||||
```
|
||||
|
||||
### Set body content
|
||||
|
||||
To set the body content and length of proxied requests, use the `body` property.
|
||||
#### Add a request body to a proxy route
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
@@ -148,25 +230,79 @@ To set the body content and length of proxied requests, use the `body` property.
|
||||
]
|
||||
```
|
||||
|
||||
### Enable token authentication
|
||||
### Add a OAuth 2.0 proxy route to your plugin
|
||||
|
||||
To enable token-based authentication for proxied requests, use the `tokenAuth` property.
|
||||
The data source proxy supports OAuth 2.0 authentication.
|
||||
|
||||
Grafana automatically renews the token when it expires.
|
||||
Since the request to each route is made server-side, only machine-to-machine authentication is supported. In order words, if you need to use a different grant than client credentials, you need to implement it yourself.
|
||||
|
||||
To authenticate using OAuth 2.0, add a `tokenAuth` object to the proxy route definition. If necessary, Grafana performs a request to the URL defined in `tokenAuth` to retrieve a token before making the request to the URL in your proxy route. Grafana automatically renews the token when it expires.
|
||||
|
||||
Any parameters defined in `tokenAuth.params` are encoded as `application/x-www-form-urlencoded` and sent to the token URL.
|
||||
|
||||
```json
|
||||
"routes": [
|
||||
{
|
||||
"path": "example",
|
||||
"url": "https://api.example.com",
|
||||
"tokenAuth": {
|
||||
"url": "https://login.example.com/oauth2/token",
|
||||
"params": {
|
||||
"grant_type": "client_credentials",
|
||||
"client_id": "{{ .JsonData.clientId }}",
|
||||
"client_secret": "{{ .SecureJsonData.clientSecret }}"
|
||||
{
|
||||
"routes": [
|
||||
{
|
||||
"path": "api",
|
||||
"url": "https://api.example.com/v1",
|
||||
"tokenAuth": {
|
||||
"url": "https://api.example.com/v1/oauth/token",
|
||||
"params": {
|
||||
"grant_type": "client_credentials",
|
||||
"client_id": "{{ .SecureJsonData.clientId }}",
|
||||
"client_secret": "{{ .SecureJsonData.clientSecret }}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Authenticate using a backend plugin
|
||||
|
||||
While the data source proxy supports the most common authentication methods for HTTP APIs, using proxy routes has a few limitations:
|
||||
|
||||
- Proxy routes only support HTTP or HTTPS
|
||||
- Proxy routes don't support custom token authentication
|
||||
|
||||
If any of these limitations apply to your plugin, you need to add a [backend plugin]({{< relref "./backend/_index.md" >}}). Since backend plugins run on the server they can access decrypted secrets, which makes it easier to implement custom authentication methods.
|
||||
|
||||
The decrypted secrets are available from the `DecryptedSecureJSONData` field in the instance settings.
|
||||
|
||||
```go
|
||||
func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
|
||||
instanceSettings := req.PluginContext.DataSourceInstanceSettings
|
||||
|
||||
if apiKey, exists := settings.DecryptedSecureJSONData["apiKey"]; exists {
|
||||
// Use the decrypted API key.
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## Forward OAuth identity for the logged-in user
|
||||
|
||||
If your data source uses the same OAuth provider as Grafana itself, for example using [Generic OAuth Authentication]({{< relref "../../auth/generic-oauth.md" >}}), your data source plugin can reuse the access token for the logged-in Grafana user.
|
||||
|
||||
To allow Grafana to pass the access token to the plugin, the user needs to enable **Forward OAuth Identity** on the data source configuration page. This tells Grafana to pass the token to the plugin in a Authorization header. Note that your plugin needs to use the [DataSourceHttpSettings](https://developers.grafana.com/ui/latest/index.html?path=/story/data-source-datasourcehttpsettings--basic) component in the configuration editor to expose the setting for your data source plugin.
|
||||
|
||||
The Authorization header is available on the `DataQuery` object on the query data request in your backend data source.
|
||||
|
||||
```go
|
||||
func (ds *dataSource) QueryData(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) {
|
||||
for _, q := range req.Queries {
|
||||
token := strings.Fields(q.Headers.Get("Authorization"))
|
||||
|
||||
var (
|
||||
tokenType = token[0]
|
||||
accessToken = token[1]
|
||||
)
|
||||
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** Due to a bug in Grafana, using this feature with PostgreSQL can cause a deadlock. For more information, refer to [Grafana causes deadlocks in PostgreSQL, while trying to refresh users token](https://github.com/grafana/grafana/issues/20515).
|
||||
|
||||
@@ -12,7 +12,7 @@ However, one limitation with these plugins are that they execute on the client-s
|
||||
|
||||
We use the term _backend plugin_ to denote that a plugin has a backend component. Still, normally a backend plugin requires frontend components as well. This is for example true for backend data source plugins which normally need configuration and query editor components implemented for the frontend.
|
||||
|
||||
Data source plugins can be extended with a backend component. In the future we plan to support additional types and possibly new kinds of plugins, such as [notifiers for Grafana Alerting]({{< relref "../../../alerting/notifications.md" >}}) and custom authentication to name a few.
|
||||
Data source plugins can be extended with a backend component. In the future we plan to support additional types and possibly new kinds of plugins, such as [notifiers for Grafana Alerting]({{< relref "../../../alerting/old-alerting/notifications.md" >}}) and custom authentication to name a few.
|
||||
|
||||
## Use cases for implementing a backend plugin
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ For more information, refer to [@grafana/toolkit](https://www.npmjs.com/package/
|
||||
|
||||
### Field options
|
||||
|
||||
Grafana 7.0 introduced the concept of [_field options_]({{< relref "../../panels/field-options/_index.md#field-options" >}}), a new way of configuring your data before it gets visualized. Since this was not available in previous versions, any plugin that enables field-based configuration will not work in previous versions of Grafana.
|
||||
Grafana 7.0 introduced the concept of _field options_, a new way of configuring your data before it gets visualized. Since this was not available in previous versions, any plugin that enables field-based configuration will not work in previous versions of Grafana.
|
||||
|
||||
For plugins prior to Grafana 7.0, all options are considered _Display options_. The tab for field configuration isn't available.
|
||||
|
||||
|
||||
@@ -90,7 +90,7 @@ view.forEach(row => {
|
||||
|
||||
## Display values from a data frame
|
||||
|
||||
[Field options]({{< relref "../../panels/field-options/_index.md" >}}) let the user control how Grafana displays the data in a data frame.
|
||||
Field options let the user control how Grafana displays the data in a data frame.
|
||||
|
||||
To apply the field options to a value, use the `display` method on the corresponding field. The result contains information such as the color and suffix to use when display the value.
|
||||
|
||||
|
||||
@@ -43,6 +43,7 @@ With Grafana Enterprise [enhanced LDAP]({{< relref "enhanced_ldap.md" >}}), you
|
||||
|
||||
With Grafana Enterprise, you get access to new features, including:
|
||||
|
||||
- [Fine-grained access control]({{< relref "access-control/_index.md" >}}) to control access with fine-grained roles and permissions.
|
||||
- [Data source permissions]({{< relref "datasource_permissions.md" >}}) to restrict query access to specific teams and users.
|
||||
- [Data source query caching]({{< relref "query-caching.md" >}}) to temporarily store query results in Grafana to reduce data source load and rate limiting.
|
||||
- [Reporting]({{< relref "reporting.md" >}}) to generate a PDF report from any dashboard and set up a schedule to have it emailed to whoever you choose.
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
+++
|
||||
title = "Fine-grained access control"
|
||||
description = "Grant, change, or revoke access to Grafana resources"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "enterprise"]
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Fine-grained access control
|
||||
|
||||
> **Note:** Fine-grained access control is in beta, and you can expect changes in future releases.
|
||||
|
||||
Fine-grained access control provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as users and reports.
|
||||
Fine-grained access control works alongside the current [Grafana permissions]({{< relref "../../permissions/_index.md" >}}), and it allows you granular control of users’ actions.
|
||||
|
||||
To learn more about how fine-grained access control works, refer to [Roles]({{< relref "./roles.md" >}}) and [Permissions]({{< relref "./permissions.md" >}}).
|
||||
To use the fine-grained access control system, refer to [Fine-grained access control usage scenarios]({{< relref "./usage-scenarios.md" >}}).
|
||||
|
||||
## Access management
|
||||
|
||||
Fine-grained access control considers a) _who_ has an access (`identity`), and b) _what they can do_ and on which _Grafana resource_ (`role`).
|
||||
|
||||
You can grant, change, or revoke access to _users_ (`identity`). When an authenticated user tries to access a Grafana resource, the authorization system checks the required fine-grained permissions for the resource and determines whether or not the action is allowed. Refer to [Fine-grained permissions]({{< relref "./permissions.md" >}}) for a complete list of available permissions.
|
||||
|
||||
To grant or revoke access to your users, create or remove built-in role assignments. For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
|
||||
|
||||
## Resources with fine-grained permissions
|
||||
|
||||
Fine-grained access control is currently available for [Reporting]({{< relref "../reporting.md" >}}) and [Managing Users]({{< relref "../../manage-users/_index.md" >}}).
|
||||
To learn more about specific endpoints where you can use access control, refer to [Permissions]({{< relref "./permissions.md" >}}) and to the relevant API guide:
|
||||
|
||||
- [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}})
|
||||
- [Admin API]({{< relref "../../http_api/admin.md" >}})
|
||||
- [Organization API]({{< relref "../../http_api/org.md" >}})
|
||||
- [Reporting API]({{< relref "../../http_api/reporting.md" >}})
|
||||
- [User API]({{< relref "../../http_api/user.md" >}})
|
||||
|
||||
## Enable fine-grained access control
|
||||
|
||||
Fine-grained access control is available behind the `accesscontrol` feature toggle in Grafana Enterprise 8.0+.
|
||||
You can enable it either in a [config file](({{< relref "../../administration/configuration.md#fconfig-file-locations" >}})) or by [configuring an environment variable](http://localhost:3002/docs/grafana/next/administration/configuration/#configure-with-environment-variables).
|
||||
|
||||
### Enable in config file
|
||||
|
||||
In your [config file](({{< relref "../../administration/configuration.md#config-file-locations" >}})), add `accesscontrol` as a [feature_toggle](({{< relref "../../administration/configuration.md#feature_toggle" >}})).
|
||||
|
||||
```
|
||||
[feature_toggles]
|
||||
# enable features, separated by spaces
|
||||
enable = accesscontrol
|
||||
```
|
||||
|
||||
### Enable with an environment variable
|
||||
|
||||
You can use `GF_FEATURE_TOGGLES_ENABLE = accesscontrol` environment variable to override the config file configuration and enable fine-grained access control.
|
||||
|
||||
Refer to [Configuring with environment variables]({{< relref "../../administration/configuration.md#configure-with-environment-variables" >}}) for more information.
|
||||
|
||||
### Verify if enabled
|
||||
|
||||
You can verify if fine-grained access control is enabled or not by sending an HTTP request to the [Check endpoint]({{< relref "../../http_api/access_control.md#check-if-enabled" >}}).
|
||||
@@ -0,0 +1,31 @@
|
||||
+++
|
||||
title = "Fine-grained access control references"
|
||||
description = "Refer to fine-grained access control references"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "fixed-roles", "built-in-role-assignments", "permissions", "enterprise"]
|
||||
weight = 130
|
||||
+++
|
||||
|
||||
# Fine-grained access control references
|
||||
The reference information that follows complements conceptual information about [Roles]({{< relref "./roles.md" >}}).
|
||||
|
||||
## Fine-grained access fixed roles
|
||||
|
||||
Fixed roles | Permissions | Descriptions
|
||||
--- | --- | ---
|
||||
fixed:permissions:admin:read | roles:read<br>roles:list<br>roles.builtin:list | Allows to list and get available roles and built-in role assignments.
|
||||
fixed:permissions:admin:edit | All permissions from `fixed:permissions:admin:read` and <br>roles:write<br>roles:delete<br>roles.builtin:add<br>roles.builtin:remove | Allows every read action and in addition allows to create, change and delete custom roles and create or remove built-in role assignments.
|
||||
fixed:reporting:admin:read | reports:read<br>reports:send<br>reports.settings:read | Allows to read reports and report settings.
|
||||
fixed:reporting:admin:edit | All permissions from `fixed:reporting:admin:read` and <br>reports.admin:write<br>reports:delete<br>reports.settings:write | Allows every read action for reports and in addition allows to administer reports.
|
||||
fixed:users:admin:read | users.authtoken:list<br>users.quotas:list<br>users:read<br>users.teams:read | Allows to list and get users and related information.
|
||||
fixed:users:admin:edit | All permissions from `fixed:users:admin:read` and <br>users.password:update<br>users:write<br>users:create<br>users:delete<br>users:enable<br>users:disable<br>users.permissions:update<br>users:logout<br>users.authtoken:update<br>users.quotas:update | Allows every read action for users and in addition allows to administer users.
|
||||
fixed:users:org:read | org.users:read | Allows to get user organizations.
|
||||
fixed:users:org:edit | All permissions from `fixed:users:org:read` and <br>org.users:add<br>org.users:remove<br>org.users.role:update | Allows every read action for user organizations and in addition allows to administer user organizations.
|
||||
fixed:ldap:admin:read | ldap.user:read<br>ldap.status:read | Allows to read LDAP information and status.
|
||||
fixed:ldap:admin:edit | All permissions from `fixed:ldap:admin:read` and <br>ldap.user:sync | Allows every read action for LDAP and in addition allows to administer LDAP.
|
||||
|
||||
## Default built-in role assignments
|
||||
|
||||
Built-in roles | Associated roles | Descriptions
|
||||
--- | --- | ---
|
||||
Grafana Admin | fixed:permissions:admin:edit<br>fixed:permissions:admin:read<br>fixed:reporting:admin:edit<br>fixed:reporting:admin:read<br>fixed:users:admin:edit<br>fixed:users:admin:read<br>fixed:users:org:edit<br>fixed:users:org:read<br>fixed:ldap:admin:edit<br>fixed:ldap:admin:read | Allows access to resources which [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) has permissions by default.
|
||||
Admin | fixed:users:org:edit<br>fixed:users:org:read<br>fixed:reporting:admin:edit<br>fixed:reporting:admin:read | Allows access to resource which [Admin]({{< relref "../../permissions/organization_roles.md" >}}) has permissions by default.
|
||||
@@ -0,0 +1,77 @@
|
||||
+++
|
||||
title = "Permissions"
|
||||
description = "Understand fine-grained access control permissions"
|
||||
keywords = ["grafana", "fine-grained access-control", "roles", "permissions", "enterprise"]
|
||||
weight = 115
|
||||
+++
|
||||
|
||||
# Permissions
|
||||
|
||||
A permission is an action and a scope. When creating a fine-grained access control, consider what specific action a user should be allowed to perform, and on what resources (its scope).
|
||||
|
||||
To grant permissions to a user, you create a built-in role assignment to map a role to a built-in role. A built-in role assignment *modifies* to one of the existing built-in roles in Grafana (Viewer, Editor, Admin). For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
|
||||
|
||||
To learn more about which permissions are used for which resources, refer to [Resources with fine-grained permissions]({{< relref "./_index.md#resources-with-fine-grained-permissions" >}}).
|
||||
|
||||
action
|
||||
: The specific action on a resource defines what a user is allowed to perform if they have permission with the relevant action assigned to it.
|
||||
|
||||
scope
|
||||
: The scope describes where an action can be performed, such as reading a specific user profile. In such case, a permission is associated with the scope `users:<userId>` to the relevant role.
|
||||
|
||||
## Action definitions
|
||||
|
||||
The following list contains fine-grained access control actions.
|
||||
|
||||
Actions | Applicable scopes | Descriptions
|
||||
--- | --- | ---
|
||||
roles:list | roles:* | List available roles without permissions.
|
||||
roles:read | roles:* | Read a specific role with it's permissions.
|
||||
roles:write | permissions:delegate | Create or update a custom role.
|
||||
roles:delete | permissions:delegate | Delete a custom role.
|
||||
roles.builtin:list | roles:* | List built-in role assignments.
|
||||
roles.builtin:add | permissions:delegate | Create a built-in role assignment.
|
||||
roles.builtin:remove | permissions:delegate | Delete a built-in role assignment.
|
||||
reports.admin:create | reports:* | Create reports.
|
||||
reports.admin:write | reports:* | Update reports.
|
||||
reports:delete | reports:* | Delete reports.
|
||||
reports:read | reports:* | List all available reports or get a specific report.
|
||||
reports:send | reports:* | Send a report email.
|
||||
reports.settings:write | n/a | Update report settings.
|
||||
reports.settings:read | n/a | Read report settings.
|
||||
provisioning:reload | service:access-control | Reload provisioning files.
|
||||
users:read | global:users:* | Read or search user profiles.
|
||||
users:write | global:users:* | Update a user’s profile.
|
||||
users.teams:read | global:users:* | Read a user’s teams.
|
||||
users.authtoken:list | global:users:* | List authentication tokens that are assigned to a user.
|
||||
users.authtoken:update | global:users:* | Update authentication tokens that are assigned to a user.
|
||||
users.password:update | global:users:* | Update a user’s password.
|
||||
users:delete | global:users:* | Delete a user.
|
||||
users:create | n/a | Create a user.
|
||||
users:enable | global:users:* | Enable a user.
|
||||
users:disable | global:users:* | Disable a user.
|
||||
users.permissions:update | global:users:* | Update a user’s organization-level permissions.
|
||||
users:logout | global:users:* | Log out a user.
|
||||
users.quotas:list | global:users:* | List a user’s quotas.
|
||||
users.quotas:update | global:users:* | Update a user’s quotas.
|
||||
org.users.read | users:* | Get user profiles within an organization.
|
||||
org.users.add | users:* | Add a user to an organization.
|
||||
org.users.remove | users:* | Remove a user from an organization.
|
||||
org.users.role:update | users:* | Update the organization role (`Viewer`, `Editor`, `Admin`) for an organization.
|
||||
ldap.user:read | n/a | Get a user via LDAP.
|
||||
ldap.user:sync | n/a | Sync a user via LDAP.
|
||||
ldap.status:read | n/a | Verify the LDAP servers’ availability.
|
||||
status:accesscontrol | service:access-control | Get access-control enabled status.
|
||||
|
||||
## Scope definitions
|
||||
|
||||
The following list contains fine-grained access control scopes.
|
||||
|
||||
Scopes | Descriptions
|
||||
--- | ---
|
||||
roles:* | Restrict an action to a set of roles. For example, `roles:*` matches any role, `roles:randomuid` matches only the role with UID `randomuid` and `roles:custom:reports:{editor,viewer}` matches both `custom:reports:editor` and `custom:reports:viewer` roles.
|
||||
permissions:delegate | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment.
|
||||
reports:* | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:1` matches the report with id `1`.
|
||||
service:accesscontrol | Restrict an action to target only the fine-grained access control service. For example, you can use this in conjunction with the `provisioning:reload` or the `status:accesscontrol` actions.
|
||||
global:users:* | Restrict an action to a set of global users.
|
||||
users:* | Restrict an action to a set of users from an organization.
|
||||
@@ -0,0 +1,264 @@
|
||||
+++
|
||||
title = "Provisioning roles and assignments"
|
||||
description = "Understand how to provision roles and assignments in fine-grained access control"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "provisioning", "assignments", "permissions", "enterprise"]
|
||||
weight = 120
|
||||
+++
|
||||
|
||||
# Provisioning
|
||||
|
||||
You can create, change or remove [Custom roles]({{< relref "./roles.md#custom-roles" >}}) and create or remove [built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}), by adding one or more YAML configuration files in the [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}) directory.
|
||||
Refer to [Grafana provisioning]({{< relref "../../administration/configuration/#provisioning" >}}) to learn more about provisioning.
|
||||
|
||||
If you want to manage roles and built-in role assignments by API, refer to the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control/" >}}).
|
||||
|
||||
## Configuration
|
||||
|
||||
The configuration files must be placed in [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}).
|
||||
Grafana performs provisioning during the startup. Refer to the [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}) to understand how you can reload configuration at runtime.
|
||||
|
||||
## Manage custom roles
|
||||
|
||||
You can create, update, and delete custom roles, as well as create and remove built-in role assignments.
|
||||
|
||||
### Create or update roles
|
||||
|
||||
To create or update custom roles, you can add a list of `roles` in the configuration.
|
||||
|
||||
Every role has a [version]({{< relref "./roles.md#custom-roles" >}}) number. For each role you update, you must remember to increment it, otherwise changes won't be accounted for.
|
||||
|
||||
When you update a role, the existing role inside grafana is altered to be exactly what is specified in the YAML file, including permissions.
|
||||
|
||||
Here is an example YAML file to create a local role with a set of permissions:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# Roles to insert into the database, or roles to update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: "This role allows users to list, create, or update other users within the organization."
|
||||
version: 1
|
||||
orgId: 1
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
- action: "users:write"
|
||||
scope: "users:*"
|
||||
- action: "users:create"
|
||||
scope: "users:*"
|
||||
```
|
||||
|
||||
Here is an example YAML file to create a global role with a set of permissions, where the `global:true` option makes a role global:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# Roles to insert into the database, or roles to update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: "This role allows users to list, create, or update other users within the organization."
|
||||
version: 1
|
||||
global: true
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
- action: "users:write"
|
||||
scope: "users:*"
|
||||
- action: "users:create"
|
||||
scope: "users:*"
|
||||
```
|
||||
The `orgId` is lost when the role is set to global.
|
||||
|
||||
### Delete roles
|
||||
|
||||
To delete a role, you can add a list of roles under the `deleteRoles` section in the configuration file. Such a deletion is performed after a role is inserted or updated.
|
||||
|
||||
Here is an example YAML file to delete a role:
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
- name: custom:reports:editor
|
||||
orgId: 1
|
||||
force: true
|
||||
```
|
||||
|
||||
### Assign your custom role to specific built-in roles
|
||||
|
||||
To assign roles to built-in roles, add said built-in roles to the `builtInRoles` section of your roles. To remove a specific assignment, remove it from the list.
|
||||
|
||||
For example, the following role is assigned to an organization editor or an organization administrator:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# Roles to insert/update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: "This role allows users to list/create/update other users in the organization"
|
||||
version: 1
|
||||
orgId: 1
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
- action: "users:write"
|
||||
scope: "users:*"
|
||||
- action: "users:create"
|
||||
scope: "users:*"
|
||||
builtInRoles:
|
||||
- name: "Editor"
|
||||
- name: "Admin"
|
||||
```
|
||||
|
||||
## Manage default built-in role assignments
|
||||
|
||||
During startup, Grafana creates [default built-in role assignments]({{< relref "./roles#default-built-in-role-assignments" >}}) with [fixed roles]({{< relref "./roles#fixed-roles" >}}). You can remove and later restore those assignments with provisioning.
|
||||
|
||||
### Remove default assignment
|
||||
|
||||
To remove default built-in role assignments, use the `removeDefaultAssignments` element in the configuration file. You need to provide the built-in role name and fixed role name.
|
||||
|
||||
Here is an example:
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of default built-in role assignments that should be removed
|
||||
removeDefaultAssignments:
|
||||
- builtInRole: "Grafana server administrator"
|
||||
fixedRole: "fixed:permissions:admin"
|
||||
|
||||
```
|
||||
|
||||
### Restore default assignment
|
||||
|
||||
To restore the default built-in role assignment, use the `addDefaultAssignments` element in the configuration file. You need to provide the built-in role name and the fixed-role name.
|
||||
|
||||
Here is an example:
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of default built-in role assignments that should be added back
|
||||
addDefaultAssignments:
|
||||
- builtInRole: "Admin"
|
||||
fixedRole: "fixed:reporting:admin:read"
|
||||
```
|
||||
|
||||
## Full example of a role configuration file
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of default built-in role assignments that should be removed
|
||||
removeDefaultAssignments:
|
||||
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
- builtInRole: "Grafana Admin"
|
||||
# <string>, must be one of the existing fixed roles
|
||||
fixedRole: "fixed:permissions:admin"
|
||||
|
||||
# list of default built-in role assignments that should be added back
|
||||
addDefaultAssignments:
|
||||
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
- builtInRole: "Admin"
|
||||
# <string>, must be one of the existing fixed roles
|
||||
fixedRole: "fixed:reporting:admin:read"
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
# <string> name of the role you want to create. Required if no uid is set
|
||||
- name: "custom:reports:editor"
|
||||
# <string> uid of the role. Required if no name
|
||||
uid: "customreportseditor1"
|
||||
# <int> org id. will default to Grafana's default if not specified
|
||||
orgId: 1
|
||||
# <bool> force deletion revoking all grants of the role
|
||||
force: true
|
||||
- name: "custom:global:reports:reader"
|
||||
uid: "customglobalreportsreader1"
|
||||
# <bool> overwrite org id and removes a global role
|
||||
global: true
|
||||
force: true
|
||||
|
||||
# list of roles to insert/update depending on what is available in the database
|
||||
roles:
|
||||
# <string, required> name of the role you want to create. Required
|
||||
- name: "custom:users:editor"
|
||||
# <string> uid of the role. Has to be unique for all orgs.
|
||||
uid: customuserseditor1
|
||||
# <string> description of the role, informative purpose only.
|
||||
description: "Role for our custom user editors"
|
||||
# <int> version of the role, Grafana will update the role when increased
|
||||
version: 2
|
||||
# <int> org id. will default to Grafana's default if not specified
|
||||
orgId: 1
|
||||
# <list> list of the permissions granted by this role
|
||||
permissions:
|
||||
# <string, required> action allowed
|
||||
- action: "users:read"
|
||||
#<string> scope it applies to
|
||||
scope: "users:*"
|
||||
- action: "users:write"
|
||||
scope: "users:*"
|
||||
- action: "users:create"
|
||||
scope: "users:*"
|
||||
# <list> list of builtIn roles the role should be assigned to
|
||||
builtInRoles:
|
||||
# <string, required> name of the builtin role you want to assign the role to
|
||||
- name: "Editor"
|
||||
# <int> org id. will default to the role org id
|
||||
orgId: 1
|
||||
- name: "custom:global:users:reader"
|
||||
uid: "customglobalusersreader1"
|
||||
description: "Global Role for custom user readers"
|
||||
version: 1
|
||||
# <bool> overwrite org id and creates a global role
|
||||
global: true
|
||||
permissions:
|
||||
- action: "users:read"
|
||||
scope: "users:*"
|
||||
builtInRoles:
|
||||
- name: "Viewer"
|
||||
orgId: 1
|
||||
- name: "Editor"
|
||||
# <bool> overwrite org id and assign role globally
|
||||
global: true
|
||||
```
|
||||
|
||||
## Supported settings
|
||||
|
||||
The following sections detail the supported settings for roles and built-in role assignments.
|
||||
|
||||
- Refer to [Permissions]({{< relref "./permissions.md#action-definitions" >}}) for full list of valid permissions.
|
||||
- Check [Custom roles]({{< relref "./roles.md#custom-roles" >}}) to understand attributes for roles.
|
||||
- The [default org ID]({{< relref "../../administration/configuration#auto_assign_org_id" >}}) is used if `orgId` is not specified in any of the configuration blocks.
|
||||
|
||||
## Validation rules
|
||||
|
||||
A basic set of validation rules are applied to the input `yaml` files.
|
||||
|
||||
### Roles
|
||||
|
||||
- `name` must not be empty
|
||||
- `name` must not have `fixed:` prefix.
|
||||
|
||||
### Permissions
|
||||
|
||||
- `name` must not be empty
|
||||
|
||||
### Built-in role assignments
|
||||
|
||||
- `name` must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`.
|
||||
- When `orgId` is not specified, it inherits the `orgId` from `role`. For global roles the default `orgId` is used.
|
||||
- `orgId` in the `role` and in the assignment must be the same for none global roles.
|
||||
|
||||
### Role deletion
|
||||
|
||||
- Either the role `name` or `uid` must be provided
|
||||
@@ -0,0 +1,85 @@
|
||||
+++
|
||||
title = "Roles"
|
||||
description = "Understand roles in fine-grained access control"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "fixed-roles", "built-in-role-assignments", "permissions", "enterprise"]
|
||||
weight = 105
|
||||
+++
|
||||
|
||||
# Roles
|
||||
|
||||
A role represents set of permissions that allow you to perform specific actions on Grafana resources. Refer to [Permissions]({{< relref "./permissions.md" >}}) to understand how permissions work.
|
||||
|
||||
There are two types of roles:
|
||||
- [Fixed roles]({{< relref "./roles.md#fixed-roles" >}}), which provide granular access for specific resources within Grafana and are managed by the Grafana itself.
|
||||
- [Custom roles]({{< relref "./roles.md#custom-roles.md" >}}), which provide granular access based on the user specified set of permissions.
|
||||
|
||||
You can use [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) to list available roles and permissions.
|
||||
|
||||
## Role scopes
|
||||
|
||||
A role can be either _global_ or _organization local_. _Global_ roles are not mapped to any specific organization and can be reused across multiple organizations, whereas _organization local_ roles are only available for that specific organization.
|
||||
|
||||
## Fixed roles
|
||||
|
||||
Fixed roles provide convenience and guarantee of consistent behaviour by combining relevant [permissions]({{< relref "./permissions.md" >}}) together. Fixed roles are created and updated by Grafana during startup.
|
||||
There are few basic rules for fixed roles:
|
||||
|
||||
- All fixed roles are _global_.
|
||||
- All fixed roles have a `fixed:` prefix.
|
||||
- You can’t change or delete a fixed role.
|
||||
|
||||
For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#fine-grained-access-fixed-roles" >}}).
|
||||
|
||||
## Custom roles
|
||||
|
||||
Custom roles allow you to manage access to your users the way you want, by mapping [fine-grained permissions]({{< relref "./permissions.md" >}}) to it and creating [built-in role assignments]({{< ref "#built-in-role-assignments.md" >}}).
|
||||
|
||||
To create, update or delete a custom role, you can use the [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
|
||||
|
||||
### Role name
|
||||
|
||||
A role's name is intended as a human friendly identifier for the role, helping administrators understand the purpose of a role. The name cannot be longer than 190 characters, and we recommend using ASCII characters.
|
||||
Role names must be unique within an organization.
|
||||
|
||||
Roles with names prefixed by `fixed:` are fixed roles created by Grafana and cannot be created or modified by users.
|
||||
|
||||
### Role version
|
||||
|
||||
The version of a role is a positive integer which defines the current version of the role. When updating a role, you can either omit the version field to increment the previous value by 1 or set a new version which must be strictly larger than the previous version for the update to succeed.
|
||||
|
||||
### Permissions
|
||||
|
||||
You manage access to Grafana resources by mapping [permissions]({{< relref "./permissions.md" >}}) to roles. You can create and assign roles without any permissions as placeholders.
|
||||
|
||||
### Role UID
|
||||
|
||||
Each custom role has a UID defined which is a unique identifier associated with the role allowing you to change or delete the role. You can either generate UID yourself, or let Grafana generate one for you.
|
||||
|
||||
The same UID cannot be used for roles in different organizations within the same Grafana instance.
|
||||
|
||||
## Create, update and delete roles
|
||||
|
||||
You can create, update and delete custom roles by using the [Access Control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
|
||||
|
||||
By default, Grafana Server Admin has a [built-in role assignment]({{< ref "#built-in-role-assignments" >}}) which allows a user to create, update or delete custom roles.
|
||||
If a Grafana Server Admin wants to delegate that privilege to other users, they can create a custom role with relevant [permissions]({{< relref "./permissions.md" >}}) and `permissions:delegate` scope will allow those users to manage roles themselves.
|
||||
|
||||
Note that you won't be able to create, update or delete a custom role with permissions which you yourself do not have. For example, if the only permission you have is a `users:create`, you won't be able to create a role with other permissions.
|
||||
|
||||
## Built-in role assignments
|
||||
|
||||
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
|
||||
These assignments are called built-in role assignments.
|
||||
|
||||
During startup, Grafana will create default assignments for you. When you make any changes to the built-on role assignments, Grafana will take them into account and won’t overwrite during next start.
|
||||
|
||||
For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#default-built-in-role-assignments" >}}).
|
||||
|
||||
## Create and remove built-in role assignments
|
||||
|
||||
You can create or remove built-in role assignments using [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or using [Grafana Provisioning]({{< relref "./provisioning" >}}).
|
||||
|
||||
### Scope of assignments
|
||||
|
||||
A built-in role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
|
||||
You can only create _organization local_ assignments for _organization local_ roles.
|
||||
@@ -0,0 +1,226 @@
|
||||
+++
|
||||
title = "Fine-grained access control usage scenarios"
|
||||
description = "Fine-grained access control usage scenarios"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
|
||||
weight = 125
|
||||
+++
|
||||
|
||||
# Fine-grained access control usage scenarios
|
||||
|
||||
This guide contains several examples and usage scenarios of using fine-grained roles and permissions for controlling access to Grafana resources.
|
||||
|
||||
Before you get started, make sure to [enable fine-grained access control]({{< relref "./_index.md#enable-fine-grained-access-control" >}}).
|
||||
|
||||
## Check all built-in role assignments
|
||||
|
||||
You can use the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available built-in role assignments.
|
||||
The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or fixed roles.
|
||||
|
||||
Example request:
|
||||
```
|
||||
curl --location --request GET '<grafana_url>/api/access-control/builtin-roles' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
|
||||
```
|
||||
|
||||
Example response:
|
||||
```
|
||||
{
|
||||
"Admin": [
|
||||
...
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "Kz9m_YjGz",
|
||||
"name": "fixed:reporting:admin:edit",
|
||||
"description": "Gives access to edit any report or the organization's general reporting settings.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
...
|
||||
],
|
||||
"Grafana Admin": [
|
||||
...
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "ajum_YjGk",
|
||||
"name": "fixed:users:admin:read",
|
||||
"description": "Allows to list and get users and related information.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:17+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "K3um_LCMk",
|
||||
"name": "fixed:users:admin:edit",
|
||||
"description": "Allows every read action for users and in addition allows to administer users.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:17+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
To see what permissions each of the assigned roles have, you can a [Get a role]({{< relref "../../http_api/access_control.md#get-a-role" >}}) by using an HTTP API.
|
||||
|
||||
Example request:
|
||||
|
||||
```
|
||||
curl --location --request GET '<grafana_url>/api/access-control/roles/qQui_LCMk' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "org.users:add",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
},
|
||||
{
|
||||
"action": "org.users:read",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
},
|
||||
{
|
||||
"action": "org.users:remove",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
},
|
||||
{
|
||||
"action": "org.users.role:update",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
}
|
||||
],
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
## Create your first custom role
|
||||
|
||||
You can create your custom role by either using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}) or by using [Grafana provisioning]({{< relref "./provisioning.md" >}}).
|
||||
You can take a look at [actions and scopes]({{< relref "./provisioning.md#action-definitions" >}}) to decide what permissions would you like to map to your role.
|
||||
|
||||
Example HTTP request:
|
||||
```
|
||||
curl --location --request POST '<grafana_url>/api/access-control/roles/' \
|
||||
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"version": 1,
|
||||
"uid": "jZrmlLCkGksdka",
|
||||
"name": "custom:users:admin",
|
||||
"description": "My custom role which gives users permissions to create users",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "users:create"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "jZrmlLCkGksdka",
|
||||
"name": "custom:users:admin",
|
||||
"description": "My custom role which gives users permissions to create users",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "users:create"
|
||||
"updated": "2021-05-17T22:07:31.569936+02:00",
|
||||
"created": "2021-05-17T22:07:31.569935+02:00"
|
||||
}
|
||||
],
|
||||
"updated": "2021-05-17T22:07:31.564403+02:00",
|
||||
"created": "2021-05-17T22:07:31.564403+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
Once the custom role is created, you can create a built-in role assignment by using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-built-in-role-assignment" >}}).
|
||||
If you created your role using [Grafana provisioning]({{< relref "./provisioning.md" >}}), you can also create the assignment with it.
|
||||
|
||||
Example HTTP request:
|
||||
|
||||
```
|
||||
curl --location --request POST '<grafana_url>/api/access-control/builtin-roles' \
|
||||
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"roleUid": "jZrmlLCkGksdka",
|
||||
"builtinRole": "Viewer",
|
||||
"global": true
|
||||
}'
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```
|
||||
{
|
||||
"message": "Built-in role grant added"
|
||||
}
|
||||
```
|
||||
|
||||
## Allow Viewers to create reports
|
||||
|
||||
In order to create reports, you would need to have `reports.admin:write` permission. By default, Grafana Admin's or organization Admin can create reports as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `reports.admin:write` permission.
|
||||
|
||||
If you want your users who have `Viewer` organization role to create reports, you have two options:
|
||||
|
||||
1. First option is to create a built-in role assignment and map `fixed:reporting:admin:edit` fixed role to the `Viewer` built-in role. Note that `fixed:reporting:admin:edit` fixed role allows doing more than creating reports. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
|
||||
1. Second option is to [create a custom role]({{< ref "#create-your-custom-role" >}}) with `reports.admin:write` permission, and create a built-in role assignment for `Viewer` organization role.
|
||||
|
||||
## Prevent Grafana Admin from creating and inviting users
|
||||
|
||||
In order to create users, you would need to have `users:create` permission. By default, user with Grafana Admin role can create users as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `users:create` permission.
|
||||
|
||||
If you want to prevent Grafana Admin from creating users, you can do the following:
|
||||
|
||||
1. [Check all built-in role assignments]({{< ref "#check-all-built-in-role-assignments" >}}) to see what built-in role assignments are available.
|
||||
1. From built-in role assignments, find the role which gives `users:create` permission. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
|
||||
1. Remove the built-in role assignment by using an [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana provisioning]({{< relref "./provisioning" >}}).
|
||||
|
||||
## Allow Editors to create new custom roles
|
||||
|
||||
By default, Grafana Server Admin is the only user who can create and manage custom roles. If you want your users to do the same, you have two options:
|
||||
|
||||
1. First option is to create a built-in role assignment and map `fixed:permissions:admin:edit` and `fixed:permissions:admin:read` fixed roles to the `Editor` built-in role.
|
||||
1. Second option is to [create a custom role]({{< ref "#create-your-custom-role" >}}) with `roles.builtin:add` and `roles:write` permissions, and create a built-in role assignment for `Editor` organization role.
|
||||
|
||||
Note that in any scenario, your `Editor` would be able to create and manage roles only with the permissions they have, or with a subset of them.
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Auditing"
|
||||
description = "Auditing"
|
||||
keywords = ["grafana", "auditing", "audit", "logs"]
|
||||
weight = 700
|
||||
weight = 1100
|
||||
+++
|
||||
|
||||
# Auditing
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Data source permissions"
|
||||
description = "Grafana Datasource Permissions Guide "
|
||||
keywords = ["grafana", "configuration", "documentation", "datasource", "permissions", "users", "teams", "enterprise"]
|
||||
weight = 200
|
||||
weight = 500
|
||||
+++
|
||||
|
||||
# Data source permissions
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Enhanced LDAP Integration"
|
||||
description = "Grafana Enhanced LDAP Integration Guide "
|
||||
keywords = ["grafana", "configuration", "documentation", "ldap", "active directory", "enterprise"]
|
||||
weight = 300
|
||||
weight = 600
|
||||
+++
|
||||
|
||||
# Enhanced LDAP integration
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Enterprise configuration"
|
||||
description = "Enterprise configuration documentation"
|
||||
keywords = ["grafana", "configuration", "documentation", "enterprise"]
|
||||
weight = 300
|
||||
weight = 700
|
||||
+++
|
||||
|
||||
# Grafana Enterprise configuration
|
||||
@@ -133,6 +133,10 @@ Maximum number of concurrent calls to the rendering service.
|
||||
|
||||
Scale factor for rendering images. Value `2` is enough for monitor resolutions, `4` would be better for printed material. Setting a higher value affects performance and memory.
|
||||
|
||||
### max_attachment_size_mb
|
||||
|
||||
Set the maximum file size in megabytes for the CSV attachments.
|
||||
|
||||
### fonts_path
|
||||
|
||||
Path to the directory containing font files.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Export dashboard as PDF"
|
||||
description = ""
|
||||
keywords = ["grafana", "export", "pdf", "share"]
|
||||
weight = 900
|
||||
weight = 1400
|
||||
+++
|
||||
|
||||
# Export dashboard as PDF
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
title = "Grafana Enterprise license"
|
||||
description = "Enterprise license"
|
||||
keywords = ["grafana", "licensing", "enterprise"]
|
||||
weight = 100
|
||||
weight = 10
|
||||
+++
|
||||
|
||||
# Grafana Enterprise license
|
||||
|
||||
To run Grafana Enterprise, you need a valid license. Contact a Grafana Labs representative](https://grafana.com/contact?about=grafana-enterprise) to obtain the license. For information on how to activate your license, refer to [Activate an Enterprise license]({{< relref "./activate-license.md" >}}).
|
||||
To run Grafana Enterprise, you need a valid license. [Contact a Grafana Labs representative](https://grafana.com/contact?about=grafana-enterprise) to obtain the license. For information on how to activate your license, refer to [Activate an Enterprise license]({{< relref "./activate-license.md" >}}).
|
||||
|
||||
See also:
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Query caching"
|
||||
description = "Grafana Enterprise data source query caching"
|
||||
keywords = ["grafana", "plugins", "query", "caching"]
|
||||
weight = 110
|
||||
weight = 300
|
||||
+++
|
||||
|
||||
# Query caching
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "Reporting"
|
||||
description = ""
|
||||
keywords = ["grafana", "reporting"]
|
||||
aliases = ["/docs/grafana/latest/administration/reports"]
|
||||
weight = 400
|
||||
weight = 800
|
||||
+++
|
||||
|
||||
# Reporting
|
||||
@@ -12,6 +12,9 @@ Reporting allows you to automatically generate PDFs from any of your dashboards
|
||||
|
||||
> Only available in Grafana Enterprise v6.4+.
|
||||
|
||||
> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some actions you would need to have relevant permissions.
|
||||
Refer to specific guides to understand what permissions are required.
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports_list.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
Any changes you make to a dashboard used in a report are reflected the next time the report is sent. For example, if you change the time range in the dashboard, then the time range in the report changes as well.
|
||||
@@ -21,9 +24,13 @@ Any changes you make to a dashboard used in a report are reflected the next time
|
||||
- SMTP must be configured for reports to be sent. Refer to [SMTP]({{< relref "../administration/configuration.md#smtp" >}}) in [Configuration]({{< relref "../administration/configuration.md" >}}) for more information.
|
||||
- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering]({{< relref "../administration/image_rendering.md" >}}) for more information.
|
||||
|
||||
## Access control
|
||||
|
||||
When [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) is enabled, you need to have the relevant [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) to create and manage reports.
|
||||
|
||||
## Create or update a report
|
||||
|
||||
Currently only Organization Admins can create reports.
|
||||
Only organization admins can create reports by default. You can customize who can create reports with [fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}).
|
||||
|
||||
1. Click on the reports icon in the side menu. The Reports tab allows you to view, create, and update your reports.
|
||||
1. Enter report information. All fields are required unless otherwise indicated.
|
||||
@@ -44,6 +51,39 @@ Currently only Organization Admins can create reports.
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports-create-new-8.0.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
### Choose template variables
|
||||
|
||||
> **Note:** Available in Grafana Enterprise version 7.5+ (behind `reportVariables` feature flag) and Grafana Enterprise version 8+ without a feature flag.
|
||||
|
||||
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/_index.md" >}}) section.
|
||||
|
||||
> **Note:** The query variables saved with a report might go out of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that happens, the selected variables will need to be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report will stay up-to-date as new values are added.
|
||||
|
||||
### Render a report with panels or rows set to repeat by a variable
|
||||
|
||||
> **Note:** Available in Grafana Enterprise v8+.
|
||||
|
||||
You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to the [Repeat panels or rows]({{< relref "../panels/repeat-panels-or-rows.md" >}}) section.
|
||||
|
||||
#### Caveats:
|
||||
|
||||
- Rendering repeating panels for dynamic variable types (e.g. `query` variables) with selected `All` value is currently not supported. As a workaround, it is possible to individually select all the values instead.
|
||||
- If you select different template variables in a report for a dashboard with repeating rows, you might see empty space or missing values at the bottom of the report. This is because the dimensions of the panels from the dashboard are used to generate the report. To avoid this issue, use the dashboard's original template variables for the report, or make a copy of the dashboard, select the new set of template variables, and generate a report based on the copied dashboard.
|
||||
- Rendering of the repeating panels inside collapsed rows in reports is not supported.
|
||||
|
||||
### Report time range
|
||||
|
||||
> Setting custom report time range is available in Grafana Enterprise v7.2+.
|
||||
|
||||
By default, reports use the saved time range of the dashboard. Changing the time range of the report can be done by:
|
||||
|
||||
- Saving a modified time range to the dashboard.
|
||||
- Setting a time range via **Time range** field in the report form. If specified, then this custom time range overrides the one from the report's dashboard.
|
||||
|
||||
The page header of the report displays the time range for the dashboard's data queries. Dashboards set to use the browser's time zone will use the time zone on the Grafana server.
|
||||
|
||||
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls]({{< relref "../dashboards/time-range-controls.md/#dashboard-time-settings" >}}).
|
||||
|
||||
### Layout and orientation
|
||||
|
||||
> We're actively working on developing new report layout options. [Contact us](https://grafana.com/contact?about=grafana-enterprise&topic=design-process&value=reporting) if you would like to get involved in the design process.
|
||||
@@ -55,6 +95,18 @@ Simple | Landscape | v6.7+ | Generates an A4 page in landscape mode with a singl
|
||||
Grid | Portrait | v7.2+ | Generates an A4 page in portrait mode with panels arranged in the same way as at the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_portrait_preview.png" max-width="500px" max-height="500px" class="docs-image--no-shadow" >}}
|
||||
Grid | Landscape | v7.2+ | Generates an A4 page in landscape mode with panels arranged in the same way as at the original dashboard. | {{< figure src="/static/img/docs/enterprise/reports_grid_landscape_preview.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
### CSV export
|
||||
|
||||
> **Note:** Only available in Grafana Enterprise v8.0+, with the [Grafana image renderer plugin](https://grafana.com/grafana/plugins/grafana-image-renderer) v3.0+.
|
||||
|
||||
You can attach a CSV file to the report email for each table panel on the selected dashboard, along with the PDF report. By default, CSVs larger than 10Mb won't be sent to avoid email servers to reject the email. You can increase or decrease this limit in the [reporting configuration]({{< relref "#rendering-configuration" >}}).
|
||||
|
||||
This feature relies on the same plugin that supports the [image rendering]({{< relref "../administration/image_rendering.md" >}}) features.
|
||||
|
||||
When the CSV file is generated, it is temporarily written to the `csv` folder in the Grafana `data` folder.
|
||||
|
||||
A background job runs every 10 minutes and removes temporary CSV files. You can configure how long a CSV file should be stored before being removed by configuring the [temp-data-lifetime]({{< relref "../administration/configuration/#temp-data-lifetime" >}}) setting. This setting also affects how long a renderer PNG file should be stored.
|
||||
|
||||
### Scheduling
|
||||
|
||||
Scheduled reports can be sent on a monthly, weekly, daily, or hourly basis. You may also disable scheduling for when you either want to send it via the API.
|
||||
@@ -112,39 +164,6 @@ The last saved version of the report will be sent to selected emails. You can us
|
||||
|
||||
{{< figure src="/static/img/docs/enterprise/reports_send_test_mail.png" max-width="500px" class="docs-image--no-shadow" >}}
|
||||
|
||||
### Report time range
|
||||
|
||||
> Setting custom report time range is available in Grafana Enterprise v7.2+.
|
||||
|
||||
By default, reports use the saved time range of the dashboard. Changing the time range of the report can be done by:
|
||||
|
||||
- Saving a modified time range to the dashboard.
|
||||
- Setting a time range via **Time range** field in the report form. If specified, then this custom time range overrides the one from the report's dashboard.
|
||||
|
||||
The page header of the report displays the time range for the dashboard's data queries. Dashboards set to use the browser's time zone will use the time zone on the Grafana server.
|
||||
|
||||
If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. To avoid this, set the time zone to UTC for dashboards when using a remote renderer. Each dashboard's time zone setting is visible in the [time range controls]({{< relref "../dashboards/time-range-controls.md/#dashboard-time-settings" >}}).
|
||||
|
||||
### Choose template variables
|
||||
|
||||
> **Note:** Available in Grafana Enterprise version 7.5+ (behind `reportVariables` feature flag) and Grafana Enterprise version 8+ without a feature flag.
|
||||
|
||||
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/_index.md" >}}) section.
|
||||
|
||||
> **Note:** The query variables saved with a report might go out of date if the results of that query change. For example, if your template variable queries for a list of hostnames and a new hostname is added, then it will not be included in the report. If that happens, the selected variables will need to be manually updated in the report. If you select the `All` value for the template variable or if you keep the dashboard's original variable selection, then the report will stay up-to-date as new values are added.
|
||||
|
||||
### Render a report with panels or rows set to repeat by a variable
|
||||
|
||||
> **Note:** Available in Grafana Enterprise v8+.
|
||||
|
||||
You can include dynamic dashboards with panels or rows, set to repeat by a variable, into reports. For detailed information about setting up repeating panels or rows in dashboards, refer to the [Repeat panels or rows]({{< relref "../panels/repeat-panels-or-rows.md" >}}) section.
|
||||
|
||||
#### Caveats:
|
||||
|
||||
- Rendering repeating panels for dynamic variable types (e.g. `query` variables) with selected `All` value is currently not supported. As a workaround, it is possible to individually select all the values instead.
|
||||
- If you select different template variables in a report for a dashboard with repeating rows, you might see empty space or missing values at the bottom of the report. This is because the dimensions of the panels from the dashboard are used to generate the report. To avoid this issue, use the dashboard's original template variables for the report, or make a copy of the dashboard, select the new set of template variables, and generate a report based on the copied dashboard.
|
||||
- Rendering of the repeating panels inside collapsed rows in reports is not supported.
|
||||
|
||||
## Pause report
|
||||
|
||||
> **Note:** Available in Grafana Enterprise v8+.
|
||||
@@ -174,6 +193,8 @@ concurrent_render_limit = 4
|
||||
# Set the scale factor for rendering images. 2 is enough for monitor resolutions
|
||||
# 4 would be better for printed material. Setting a higher value affects performance and memory
|
||||
image_scale_factor = 2
|
||||
# Set the maximum file size in megabytes for the CSV attachments
|
||||
max_attachment_size_mb = 10
|
||||
# Path to the directory containing font files
|
||||
fonts_path =
|
||||
# Name of the TrueType font file with regular style
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Request security"
|
||||
description = "Grafana Enterprise request security"
|
||||
keywords = ["grafana", "security", "enterprise"]
|
||||
weight = 110
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Request security
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "SAML Authentication"
|
||||
description = "Grafana SAML Authentication"
|
||||
keywords = ["grafana", "saml", "documentation", "saml-auth"]
|
||||
aliases = ["/docs/grafana/latest/auth/saml/"]
|
||||
weight = 500
|
||||
weight = 900
|
||||
+++
|
||||
|
||||
# SAML authentication
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "Team sync"
|
||||
description = "Grafana Team Sync"
|
||||
keywords = ["grafana", "auth", "documentation"]
|
||||
aliases = ["/docs/grafana/latest/auth/saml/"]
|
||||
weight = 600
|
||||
weight = 1000
|
||||
+++
|
||||
|
||||
# Team sync
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "Usage insights"
|
||||
description = "Understand how your Grafana instance is used"
|
||||
keywords = ["grafana", "usage-insights", "enterprise"]
|
||||
aliases = ["/docs/grafana/latest/enterprise/usage-insights/"]
|
||||
weight = 100
|
||||
weight = 200
|
||||
+++
|
||||
|
||||
# Usage insights
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title = "Vault"
|
||||
description = ""
|
||||
keywords = ["grafana", "vault", "configuration"]
|
||||
weight = 700
|
||||
weight = 1200
|
||||
+++
|
||||
|
||||
# Vault integration
|
||||
|
||||
@@ -3,7 +3,7 @@ title = "White labeling"
|
||||
description = "Change the look of Grafana to match your corporate brand"
|
||||
keywords = ["grafana", "white-labeling", "enterprise"]
|
||||
aliases = ["/docs/grafana/latest/enterprise/white-labeling/"]
|
||||
weight = 700
|
||||
weight = 1300
|
||||
+++
|
||||
|
||||
# White labeling
|
||||
|
||||
@@ -18,7 +18,7 @@ Supported data sources are:
|
||||
|
||||
For information on how to configure queries for the data sources listed above, refer to the documentation for specific data source.
|
||||
|
||||
{{< figure src="/static/img/docs/v70/explore-trace-view-full.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot 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" >}}
|
||||
|
||||
##### Header
|
||||
|
||||
@@ -57,11 +57,17 @@ Clicking anywhere on the span row shows span details.
|
||||
- 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 map based on the current trace.
|
||||
|
||||
|
||||
|
||||
##### Trace to logs
|
||||
|
||||
> **Note:** Available in Grafana 7.4 and later versions.
|
||||
|
||||
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 source at this moment. their relevant documentation for instruction how to configure this feature.
|
||||
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.
|
||||
|
||||
{{< 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" >}}
|
||||
|
||||
@@ -77,24 +83,24 @@ Data source needs to return data frame and set `frame.meta.preferredVisualisatio
|
||||
|
||||
Required fields:
|
||||
|
||||
| Field name | Type | Description |
|
||||
|------------|---------|-------------|
|
||||
| traceID | string | Identifier for the entire trace. There should be only one trace in the data frame. |
|
||||
| spanID | string | Identifier for the current span. SpanIDs should be unique per trace. |
|
||||
| parentSpanID | string | SpanID of the parent span to create child parent relationship in the trace view. Can be `undefined` for root span without parent. |
|
||||
| serviceName | string | Name of the service this span is part of. |
|
||||
| serviceTags | TraceKeyValuePair[] | List of tags relevant for the service. |
|
||||
| startTime | number | Start time of the span in millisecond epoch time. |
|
||||
| duration | number | Duration of the span in milliseconds. |
|
||||
| Field name | Type | Description |
|
||||
| ------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| traceID | string | Identifier for the entire trace. There should be only one trace in the data frame. |
|
||||
| spanID | string | Identifier for the current span. SpanIDs should be unique per trace. |
|
||||
| parentSpanID | string | SpanID of the parent span to create child parent relationship in the trace view. Can be `undefined` for root span without a parent. |
|
||||
| serviceName | string | Name of the service this span is part of. |
|
||||
| serviceTags | TraceKeyValuePair[] | List of tags relevant for the service. |
|
||||
| startTime | number | Start time of the span in millisecond epoch time. |
|
||||
| duration | number | Duration of the span in milliseconds. |
|
||||
|
||||
Optional fields:
|
||||
|
||||
| Field name | Type | Description |
|
||||
|------------|---------|-------------|
|
||||
| logs | TraceLog[] | List of logs associated with the current span. |
|
||||
| tags | TraceKeyValuePair[] | List of tags associated with the current span. |
|
||||
| warnings | string[] | List of warnings associated with the current span. |
|
||||
| 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`. |
|
||||
| Field name | Type | Description |
|
||||
| -------------- | ------------------- | ------------------------------------------------------------------ |
|
||||
| logs | TraceLog[] | List of logs associated with the current span. |
|
||||
| tags | TraceKeyValuePair[] | List of tags associated with the current span. |
|
||||
| warnings | string[] | List of warnings associated with the current span. |
|
||||
| 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://grafana.com/docs/grafana/latest/packages_api/data/tracespanrow/), [TraceKeyValuePair](https://grafana.com/docs/grafana/latest/packages_api/data/tracekeyvaluepair/) and [TraceLog](https://grafana.com/docs/grafana/latest/packages_api/data/tracelog/)
|
||||
|
||||
@@ -24,7 +24,7 @@ Refer to [Explore]({{< relref "../explore/_index.md" >}}) for more information.
|
||||
|
||||
## Alerts
|
||||
|
||||
If you're using Grafana alerting, then you can have alerts sent through a number of different [alert notifiers]({{< relref "../alerting/notifications.md" >}}), including PagerDuty, SMS, email, VictorOps, OpsGenie, or Slack.
|
||||
If you're using Grafana alerting, then you can have alerts sent through a number of different [alert notifiers]({{< relref "../alerting/old-alerting/notifications.md" >}}), including PagerDuty, SMS, email, VictorOps, OpsGenie, or Slack.
|
||||
|
||||
Alert hooks allow you to create different notifiers with a bit of code if you prefer some other channels of communication. Visually define [alert rules]({{< relref "../alerting/_index.md" >}}) for your most important metrics.
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ If you chose to use InfluxDB Cloud, then you should [download and install the In
|
||||
|
||||
## Step 4. Get data into InfluxDB
|
||||
|
||||
If you downloaded and installed InfluxDB on your local machine, then use the [Quick Start][https://docs.influxdata.com/influxdb/v2.0/write-data/#quick-start-for-influxdb-oss] feature to visualize InfluxDB metrics.
|
||||
If you downloaded and installed InfluxDB on your local machine, then use the [Quick Start](https://docs.influxdata.com/influxdb/v2.0/write-data/#quick-start-for-influxdb-oss) feature to visualize InfluxDB metrics.
|
||||
|
||||
If you are using the cloud account, then the wizards will guide you through the initial process. For more information, refer to [Configure Telegraf](https://docs.influxdata.com/influxdb/cloud/write-data/no-code/use-telegraf/#configure-telegraf).
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ To log in to Grafana for the first time:
|
||||
|
||||
1. Open your web browser and go to http://localhost:3000/. The default HTTP port that Grafana listens to is `3000` unless you have configured a different port.
|
||||
1. On the login page, enter `admin` for username and password.
|
||||
1. Click **Log In**. If login is successful, then you will see a prompt to change the password.
|
||||
1. Click **Log in**. If login is successful, then you will see a prompt to change the password.
|
||||
1. Click **OK** on the prompt, then change your password.
|
||||
|
||||
> **Note:** We strongly recommend that you follow Grafana's best practices and change the default administrator password. Don't forget to record your credentials!
|
||||
@@ -31,8 +31,9 @@ To log in to Grafana for the first time:
|
||||
|
||||
To create your first dashboard:
|
||||
|
||||
1. Click the **+** icon on the left panel, select **Create Dashboard**, and then click **Add an empty panel**.
|
||||
1. In the New Dashboard/Edit Panel view, go to the **Query** tab.
|
||||
1. Click the **+** icon on the side menu.
|
||||
1. On the dashboard, click **Add an empty panel**.
|
||||
1. In the New dashboard/Edit panel view, go to the **Query** tab.
|
||||
1. Configure your [query]({{< relref "../panels/queries.md" >}}) by selecting ``-- Grafana --`` from the [data source selector]({{< relref "../panels/queries.md/#data-source-selector" >}}). This generates the Random Walk dashboard.
|
||||
1. Click the **Save** icon in the top right corner of your screen to save the dashboard.
|
||||
1. Add a descriptive name, and then click **Save**.
|
||||
|
||||
@@ -11,8 +11,7 @@ weight = 170
|
||||
The Grafana backend exposes an HTTP API, the same API is used by the frontend to do everything from saving
|
||||
dashboards, creating users and updating data sources.
|
||||
|
||||
## Supported HTTP APIs
|
||||
|
||||
## HTTP APIs
|
||||
|
||||
- [Authentication API]({{< relref "auth.md" >}})
|
||||
- [Dashboard API]({{< relref "dashboard.md" >}})
|
||||
@@ -34,11 +33,13 @@ dashboards, creating users and updating data sources.
|
||||
- [Preferences API]({{< relref "preferences.md" >}})
|
||||
- [Other API]({{< relref "other.md" >}})
|
||||
|
||||
### Grafana Enterprise HTTP APIs
|
||||
## Grafana Enterprise HTTP APIs
|
||||
|
||||
Grafana Enterprise includes all of the Grafana OSS APIs as well as those that follow:
|
||||
|
||||
- [Fine-Grained Access Control API]({{< relref "access_control.md" >}})
|
||||
- [Data Source Permissions API]({{< relref "datasource_permissions.md" >}})
|
||||
- [External Group Sync API]({{< relref "external_group_sync.md" >}})
|
||||
- [License API]({{< relref "licensing.md" >}})
|
||||
- [Reporting API]({{< relref "reporting.md" >}})
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,584 @@
|
||||
+++
|
||||
title = "Fine-grained access control HTTP API "
|
||||
description = "Fine-grained access control API"
|
||||
keywords = ["grafana", "http", "documentation", "api", "fine-grained-access-control", "acl", "enterprise"]
|
||||
aliases = ["/docs/grafana/latest/http_api/accesscontrol/"]
|
||||
+++
|
||||
|
||||
# Fine-grained access control API
|
||||
|
||||
> Fine-grained access control API is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
The API can be used to create, update, get and list roles, and create or remove built-in role assignments.
|
||||
To use the API, you would need to [enable fine-grained access control]({{< relref "../enterprise/access-control/_index.md#enable-fine-grained-access-control" >}}).
|
||||
|
||||
The API does not currently work with an API Token. So in order to use these API endpoints you will have to use [Basic auth]({{< relref "./auth/#basic-auth" >}}).
|
||||
|
||||
## Get status
|
||||
|
||||
`GET /api/access-control/status`
|
||||
|
||||
Returns an indicator to check if fine-grained access control is enabled or not.
|
||||
|
||||
### Required permissions
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
status:accesscontrol | services:accesscontrol
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
GET /api/access-control/check
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Returned a flag indicating if the fine-grained access control is enabled or no.
|
||||
403 | Access denied
|
||||
404 | Not found, an indication that fine-grained access control is not available at all.
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
## Create and manage custom roles
|
||||
|
||||
### Get all roles
|
||||
|
||||
`GET /api/access-control/roles`
|
||||
|
||||
Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.
|
||||
Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles:list | roles:*
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
GET /api/access-control/roles
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
[
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "Kz9m_YjGz",
|
||||
"name": "fixed:reporting:admin:edit",
|
||||
"description": "Gives access to edit any report or the organization's general reporting settings.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 5,
|
||||
"uid": "vi9mlLjGz",
|
||||
"name": "fixed:permissions:admin:read",
|
||||
"description": "Gives access to read and list roles and permissions, as well as built-in role assignments.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T22:41:49+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Global and organization local roles are returned.
|
||||
403 | Access denied
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
### Get a role
|
||||
|
||||
`GET /api/access-control/roles/:uid`
|
||||
|
||||
Get a role for the given UID.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles:read | roles:*
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
GET /api/access-control/roles/PYnDO3rMk
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "jZrmlLCGk",
|
||||
"name": "fixed:permissions:admin:edit",
|
||||
"description": "Gives access to create, update and delete roles, as well as manage built-in role assignments.",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "roles:delete",
|
||||
"scope": "permissions:delegate",
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"action": "roles:list",
|
||||
"scope": "roles:*",
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
],
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Role is returned.
|
||||
403 | Access denied
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
### Create a new custom role
|
||||
|
||||
`POST /api/access-control/roles`
|
||||
|
||||
Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as [Fixed Roles]({{< relref "../enterprise/access-control/roles.md" >}}) can't be created.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permission:delegate` scope ensures that users can only create custom roles with the same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to create a custom role which allows to do that. This is done to prevent escalation of privileges.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles:write | permissions:delegate
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
POST /api/access-control/roles
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "jZrmlLCGka",
|
||||
"name": "custom:delete:roles",
|
||||
"description": "My custom role which gives users permissions to delete roles",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "roles:delete",
|
||||
"scope": "permissions:delegate"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON body schema
|
||||
|
||||
Field Name | Date Type | Required | Description
|
||||
--- | --- | --- | ---
|
||||
uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
|
||||
global | boolean | No | A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#role-scopes" >}}) for more information.
|
||||
version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
|
||||
name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
|
||||
description | string | No | Description of the role.
|
||||
permissions | Permission | No | If not present, the role will be created without any permissions.
|
||||
|
||||
**Permission**
|
||||
|
||||
Field Name | Data Type | Required | Description
|
||||
--- | --- | --- | ---
|
||||
action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions.
|
||||
scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes.
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "jZrmlLCGka",
|
||||
"name": "custom:delete:create:roles",
|
||||
"description": "My custom role which gives users permissions to delete and create roles",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "roles:delete",
|
||||
"scope": "permissions:delegate",
|
||||
"updated": "2021-05-13T23:19:46+02:00",
|
||||
"created": "2021-05-13T23:19:46+02:00"
|
||||
}
|
||||
],
|
||||
"updated": "2021-05-13T23:20:51.416518+02:00",
|
||||
"created": "2021-05-13T23:19:46+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Role is updated.
|
||||
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
|
||||
403 | Access denied
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
### Update a custom role
|
||||
|
||||
`PUT /api/access-control/roles/:uid`
|
||||
|
||||
Update the role with the given UID, and it's permissions with the given UID. The operation is idempotent and all permissions of the role will be replaced with what is in the request. You would need to increment the version of the role with each update, otherwise the request will fail.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permission:delegate` scope ensures that users can only update custom roles with the same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to update a custom role which allows to do that. This is done to prevent escalation of privileges.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles:write | permissions:delegate
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
PUT /api/access-control/roles/jZrmlLCGka
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"version": 2,
|
||||
"name": "custom:delete:create:roles",
|
||||
"description": "My custom role which gives users permissions to delete and create roles",
|
||||
"permissions": [
|
||||
{
|
||||
"action": "roles:delete",
|
||||
"scope": "permissions:delegate"
|
||||
},
|
||||
{
|
||||
"action": "roles:create",
|
||||
"scope": "permissions:delegate"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON body schema
|
||||
|
||||
Field Name | Data Type | Required | Description
|
||||
--- | --- | --- | ---
|
||||
version | number | Yes | Version of the role. Must be incremented for update to work.
|
||||
name | string | Yes | Name of the role.
|
||||
description | string | No | Description of the role.
|
||||
permissions | List of Permissions | No | The full list of permissions the role should have after the update.
|
||||
|
||||
**Permission**
|
||||
|
||||
Field Name | Data Type | Required | Description
|
||||
--- | --- | --- | ---
|
||||
action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions.
|
||||
scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes.
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"version": 3,
|
||||
"name": "custom:delete:create:roles",
|
||||
"description": "My custom role which gives users permissions to delete and create roles",
|
||||
"permissions": [
|
||||
{
|
||||
"action": "roles:delete",
|
||||
"scope": "permissions:delegate",
|
||||
"updated": "2021-05-13T23:19:46.546146+02:00",
|
||||
"created": "2021-05-13T23:19:46.546146+02:00"
|
||||
},
|
||||
{
|
||||
"action": "roles:create",
|
||||
"scope": "permissions:delegate",
|
||||
"updated": "2021-05-13T23:19:46.546146+02:00",
|
||||
"created": "2021-05-13T23:19:46.546146+02:00"
|
||||
}
|
||||
],
|
||||
"updated": "2021-05-13T23:19:46.540987+02:00",
|
||||
"created": "2021-05-13T23:19:46.540986+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Role is updated.
|
||||
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
|
||||
403 | Access denied
|
||||
404 | Role was not found to update.
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
### Delete a custom role
|
||||
|
||||
`DELETE /api/access-control/roles/:uid?force=false`
|
||||
|
||||
Delete a role with the given UID, and it's permissions. If the role is assigned to a built-in role, the deletion operation will fail, unless `force` query param is set to `true`, and in that case all assignments will also be deleted.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permission:delegate` scope ensures that users can only delete a custom role with the same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to delete a custom role which allows to do that.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles:delete | permissions:delegate
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
DELETE /api/access-control/roles/jZrmlLCGka?force=true
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
#### Query parameters
|
||||
|
||||
Param | Type | Required | Description
|
||||
--- | --- | --- | ---
|
||||
force | boolean | No | When set to `true`, the role will be deleted with all it's assignments.
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"message": "Role deleted"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Role is deleted.
|
||||
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
|
||||
403 | Access denied
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
## Create and remove built-in role assignments
|
||||
|
||||
API set allows to create or remove [built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) and list current assignments.
|
||||
|
||||
### Get all built-in role assignments
|
||||
|
||||
`GET /api/access-control/builtin-roles`
|
||||
|
||||
Gets all built-in role assignments.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles.builtin:list | roles:*
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
GET /api/access-control/builtin-roles
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"Admin": [
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "PeXmlYjMk",
|
||||
"name": "fixed:users:org:read",
|
||||
"description": "",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
],
|
||||
"Grafana Admin": [
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Built-in role assignments are returned.
|
||||
403 | Access denied
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
### Create a built-in role assignment
|
||||
|
||||
`POST /api/access-control/builtin-roles`
|
||||
|
||||
Creates a new built-in role assignment.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permission:delegate` scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles.builtin:add | permissions:delegate
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
POST /api/access-control/builtin-roles
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"roleUid": "LPMGN99Mk",
|
||||
"builtinRole": "Grafana Admin",
|
||||
"global": false
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON body schema
|
||||
|
||||
Field Name | Date Type | Required | Description
|
||||
--- | --- | --- | ---
|
||||
roleUid | string | Yes | UID of the role.
|
||||
builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`.
|
||||
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"message": "Built-in role grant added"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Role was assigned to built-in role.
|
||||
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
|
||||
403 | Access denied
|
||||
404 | Role not found
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
|
||||
### Remove a built-in role assignment
|
||||
|
||||
`DELETE /api/access-control/builtin-roles/:builtinRole/roles/:roleUID`
|
||||
|
||||
Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _Grafana Admin_) to the role with the provided UID.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
`permission:delegate` scope ensures that users can only remove built-in role assignments with the roles which have same, or a subset of permissions which the user has.
|
||||
For example, if a user does not have required permissions for creating users, they won't be able to remove a built-in role assignment which allows to do that.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
roles.builtin:remove | permissions:delegate
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
#### Query parameters
|
||||
|
||||
Param | Type | Required | Description
|
||||
--- | --- | --- | ---
|
||||
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
|
||||
|
||||
#### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"message": "Built-in role grant removed"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
Code | Description
|
||||
--- | --- |
|
||||
200 | Role was unassigned from built-in role.
|
||||
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
|
||||
403 | Access denied
|
||||
404 | Role not found.
|
||||
500 | Unexpected error. Refer to body and/or server logs for more details.
|
||||
@@ -11,6 +11,9 @@ The Admin HTTP API does not currently work with an API Token. API Tokens are cur
|
||||
the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user
|
||||
must have the Grafana Admin permission. (The default admin user is called `admin` and has permission to use this API.)
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Fetch settings
|
||||
|
||||
`GET /api/admin/settings`
|
||||
@@ -260,6 +263,14 @@ Content-Type: application/json
|
||||
|
||||
Create new user. Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:create | n/a
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -294,6 +305,14 @@ Content-Type: application/json
|
||||
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
Change password for a specific user.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users.password:update | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -319,6 +338,14 @@ Content-Type: application/json
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users.permissions:update | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -344,6 +371,14 @@ Content-Type: application/json
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:delete | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -404,6 +439,14 @@ Return a list of all auth tokens (devices) that the user currently have logged i
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users.authtoken:list | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -455,6 +498,14 @@ and will be required to authenticate again upon next activity.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users.authtoken:update | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -487,6 +538,14 @@ and will be required to authenticate again upon next activity.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users.logout | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -516,12 +575,22 @@ Content-Type: application/json
|
||||
|
||||
`POST /api/admin/provisioning/notifications/reload`
|
||||
|
||||
`POST /api/admin/provisioning/accesscontrol/reload`
|
||||
|
||||
Reloads the provisioning config files for specified type and provision entities again. It won't return
|
||||
until the new provisioned entities are already stored in the database. In case of dashboards, it will stop
|
||||
polling for changes in dashboard files and then restart it with new configurations after returning.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope | Provision entity
|
||||
--- | --- | ---
|
||||
provisioning:reload | service:accesscontrol | accesscontrol
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
|
||||
@@ -176,7 +176,7 @@ Content-Type: application/json
|
||||
|
||||
## Create notification channel
|
||||
|
||||
You can find the full list of [supported notifiers]({{< relref "../alerting/notifications/#list-of-supported-notifiers" >}}) on the alert notifiers page.
|
||||
You can find the full list of [supported notifiers]({{< relref "../alerting/old-alerting/notifications/#list-of-supported-notifiers" >}}) on the alert notifiers page.
|
||||
|
||||
`POST /api/alert-notifications`
|
||||
|
||||
|
||||
@@ -5,13 +5,15 @@ keywords = ["grafana", "http", "documentation", "api", "organization"]
|
||||
aliases = ["/docs/grafana/latest/http_api/organization/"]
|
||||
+++
|
||||
|
||||
|
||||
# Organization API
|
||||
|
||||
The Organization HTTP API is divided in two resources, `/api/org` (current organization)
|
||||
and `/api/orgs` (admin organizations). One big difference between these are that
|
||||
the admin of all organizations API only works with basic authentication, see [Admin Organizations API](#admin-organizations-api) for more information.
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Current Organization API
|
||||
|
||||
### Get current Organization
|
||||
@@ -46,6 +48,14 @@ Content-Type: application/json
|
||||
Returns all org users within the current organization.
|
||||
Accessible to users with org admin role.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users:read | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -112,6 +122,14 @@ Content-Type: application/json
|
||||
|
||||
`PATCH /api/org/users/:userId`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users.role:update | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -138,6 +156,14 @@ Content-Type: application/json
|
||||
|
||||
`DELETE /api/org/users/:userId`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users:remove | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -188,6 +214,14 @@ Content-Type: application/json
|
||||
|
||||
Adds a global user to the current organization.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users:add | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -407,6 +441,14 @@ Content-Type: application/json
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users:read | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -440,6 +482,14 @@ Content-Type: application/json
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users:add | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -468,6 +518,14 @@ Content-Type: application/json
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users.role:update | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -495,6 +553,14 @@ Content-Type: application/json
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
org.users:remove | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
|
||||
@@ -11,7 +11,9 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
|
||||
|
||||
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
|
||||
> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Send a report
|
||||
|
||||
> Only available in Grafana Enterprise v7.0+.
|
||||
@@ -22,6 +24,14 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
|
||||
|
||||
Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client's timeout to at least 60 seconds.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#reporting-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
reports:send | n/a
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
@@ -63,4 +73,4 @@ Code | Description
|
||||
401 | Authentication failed, refer to [Authentication API]({{< relref "../http_api/auth.md" >}}).
|
||||
403 | User is authenticated but is not authorized to generate the report.
|
||||
404 | Report not found.
|
||||
500 | Unexpected error or server misconfiguration. Refer to body and/or server logs for more details.
|
||||
500 | Unexpected error or server misconfiguration. Refer to server logs for more details.
|
||||
|
||||
@@ -5,12 +5,23 @@ keywords = ["grafana", "http", "documentation", "api", "user"]
|
||||
aliases = ["/docs/grafana/latest/http_api/user/"]
|
||||
+++
|
||||
|
||||
# User HTTP resources / actions
|
||||
# User API
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Search Users
|
||||
|
||||
`GET /api/users?perpage=10&page=1`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:read | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -58,6 +69,14 @@ Content-Type: application/json
|
||||
|
||||
`GET /api/users/search?perpage=10&page=1&query=mygraf`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:read | global:users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -111,6 +130,14 @@ Content-Type: application/json
|
||||
|
||||
`GET /api/users/:id`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:read | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -148,6 +175,14 @@ Content-Type: application/json
|
||||
|
||||
`GET /api/users/lookup?loginOrEmail=user@mygraf.com`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:read | global:users:*
|
||||
|
||||
**Example Request using the email as option**:
|
||||
|
||||
```http
|
||||
@@ -195,6 +230,14 @@ Content-Type: application/json
|
||||
|
||||
`PUT /api/users/:id`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:write | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -226,6 +269,14 @@ Content-Type: application/json
|
||||
|
||||
`GET /api/users/:id/orgs`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users:read | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
@@ -256,6 +307,14 @@ Content-Type: application/json
|
||||
|
||||
`GET /api/users/:id/teams`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
|
||||
|
||||
Action | Scope
|
||||
--- | --- |
|
||||
users.teams:read | users:*
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
|
||||
@@ -8,7 +8,7 @@ weight = 300
|
||||
|
||||
# Panel links
|
||||
|
||||
Each panel can have its own set of links that are shown in the upper left corner of the panel. You can link to any available URL, including dashboards, panels, or external sites. You can even control the time range to ensure the user is zoomed in on the right data in Grafana.
|
||||
{{< docs/shared "panels/panel-links-intro.md" >}}
|
||||
|
||||
Click the icon on the top left corner of a panel to see available panel links.
|
||||
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
+++
|
||||
title = "Grafana Live"
|
||||
aliases = []
|
||||
weight = 115
|
||||
+++
|
||||
|
||||
# Grafana Live overview
|
||||
|
||||
Grafana Live is a real-time messaging engine introduced in Grafana v8.0.
|
||||
|
||||
With Grafana Live, you can push event data to a frontend as soon as an event occurs.
|
||||
|
||||
This could be notifications about dashboard changes, new frames for rendered data, and so on. Live features can help eliminate a page reload or polling in many places, it can stream Internet of things (IOT) sensors or any other real-time data to panels.
|
||||
|
||||
> **Note:** By `real-time`, we indicate a soft real-time. Due to network latencies, garbage collection cycles, and so on, the delay of a delivered message can be up to several hundred milliseconds or higher.
|
||||
@@ -0,0 +1,101 @@
|
||||
+++
|
||||
title = "Configure Grafana Live"
|
||||
description = "Grafana Live configuration guide"
|
||||
keywords = ["Grafana", "live", "guide", "websocket"]
|
||||
weight = 120
|
||||
+++
|
||||
|
||||
# Configure Grafana Live
|
||||
|
||||
Grafana Live is enabled by default. In Grafana v8.0, it has a strict default for a maximum number of connections per Grafana server instance.
|
||||
|
||||
## Max number of connections
|
||||
|
||||
Grafana Live uses persistent connections (WebSocket at the moment) to deliver real-time updates to clients.
|
||||
|
||||
WebSocket is a persistent connection that starts with an HTTP Upgrade request (using the same HTTP port as the rest of Grafana) and then switches to a TCP mode where WebSocket frames can travel in both directions between a client and a server. Each logged-in user opens a WebSocket connection – one per browser tab.
|
||||
|
||||
The number of maximum WebSocket connections users can establish with Grafana is limited to 100 by default. See [max_connections]({{< relref "../administration/configuration.md#max_connections" >}}) option.
|
||||
|
||||
In case you want to increase this limit, ensure that your server and infrastructure allow handling more connections. The following sections discuss several common problems which could happen when managing persistent connections, in particular WebSocket connections.
|
||||
|
||||
### Resource usage
|
||||
|
||||
Each persistent connection costs some memory on a server. Typically, this should be about 50 KB per connection at this moment. Thus a server with 1 GB RAM is expected to handle about 20k connections max. Each active connection consumes additional CPU resources since the client and server send PING/PONG frames to each other to maintain a connection.
|
||||
|
||||
Using the streaming functionality results in additional CPU usage. The exact CPU resource utilization can be hard to estimate as it heavily depends on the Grafana Live usage pattern.
|
||||
|
||||
### Open file limit
|
||||
|
||||
Each WebSocket connection costs a file descriptor on a server machine where Grafana runs. Most operating systems have a quite low default limit for the maximum number of descriptors that process can open.
|
||||
|
||||
To look at the current limit on Unix run:
|
||||
|
||||
```
|
||||
ulimit -n
|
||||
```
|
||||
|
||||
On a Linux system, you can also check out the current limits for a running process with:
|
||||
|
||||
```
|
||||
cat /proc/<PROCESS_PID>/limits
|
||||
```
|
||||
|
||||
The open files limit shows approximately how many user connections your server can currently handle.
|
||||
|
||||
|
||||
To increase this limit, refer to [these instructions](https://docs.riak.com/riak/kv/2.2.3/using/performance/open-files-limit.1.html)for popular operating systems.
|
||||
|
||||
### Ephemeral port exhaustion
|
||||
|
||||
Ephemeral port exhaustion problem can happen between your load balancer (or reverse proxy) software and Grafana server. For example, when you load balance requests/connections between different Grafana instances. If you connect directly to a single Grafana server instance, then you should not come across this issue.
|
||||
|
||||
The problem arises because each TCP connection uniquely identified in the OS by the 4-part-tuple:
|
||||
|
||||
```
|
||||
source ip | source port | destination ip | destination port
|
||||
```
|
||||
|
||||
By default, on load balancer/server boundary you are limited to 65535 possible variants. But actually, due to some OS limits (for example on Unix available ports defined in `ip_local_port_range` sysctl parameter) and sockets in TIME_WAIT state, the number is even less.
|
||||
|
||||
In order to eliminate a problem you can:
|
||||
|
||||
- Increase the ephemeral port range by tuning `ip_local_port_range` kernel option.
|
||||
- Deploy more Grafana server instances to load balance across.
|
||||
- Deploy more load balancer instances.
|
||||
- Use virtual network interfaces.
|
||||
|
||||
### WebSocket and proxies
|
||||
|
||||
Not all proxies can transparently proxy WebSocket connections by default. For example, if you are using Nginx before Grafana you need to configure WebSocket proxy like this:
|
||||
|
||||
```
|
||||
http {
|
||||
map $http_upgrade $connection_upgrade {
|
||||
default upgrade;
|
||||
'' close;
|
||||
}
|
||||
|
||||
upstream grafana {
|
||||
server 127.0.0.1:3000;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 8000;
|
||||
|
||||
location / {
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $http_host;
|
||||
proxy_pass http://grafana;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See the [Nginx blog on their website](https://www.nginx.com/blog/websocket-nginx/) for more information. Also, refer to your load balancer/reverse proxy documentation to find out more information on dealing with WebSocket connections.
|
||||
|
||||
Some corporate proxies can remove headers required to properly establish a WebSocket connection. In this case, you should tune intermediate proxies to not remove required headers. However, the better option is to use Grafana with TLS. Now WebSocket connection will inherit TLS and thus must be handled transparently by proxies.
|
||||
|
||||
Proxies like Nginx and Envoy have default limits on maximum number of connections which can be established. Make sure you have a reasonable limit for max number of incoming and outgoing connections in your proxy configuration.
|
||||
@@ -0,0 +1,36 @@
|
||||
+++
|
||||
title = "Live Channel"
|
||||
description = "Grafana Live channel guide"
|
||||
keywords = ["Grafana", "live", "guide", "channel"]
|
||||
weight = 110
|
||||
+++
|
||||
|
||||
# Grafana Live Channel guide
|
||||
|
||||
Grafana Live is a PUB/SUB server, clients subscribe to channels to receive real-time updates published to those channels.
|
||||
|
||||
## Channel structure
|
||||
|
||||
Channel is a string identifier. In Grafana channel consists of 3 parts delimited by `/`:
|
||||
|
||||
- Scope
|
||||
- Namespace
|
||||
- Path
|
||||
|
||||
For example, the channel `grafana/dashboard/xyz` has the scope `grafana`, namespace `dashboard`, and path `xyz`.
|
||||
|
||||
Scope, namespace and path can only have ASCII alphanumeric symbols (A-Z, a-z, 0-9), `_` (underscore) and `-` (dash) at the moment. The path part can additionally have `/`, `.` and `=` symbols. The meaning of scope, namespace and path is context-specific.
|
||||
|
||||
The maximum length of a channel is 160 symbols.
|
||||
|
||||
Scope determines the purpose of a channel in Grafana. For example, for data source plugin channels Grafana uses `ds` scope. For built-in features like dashboard edit notifications Grafana uses `grafana` scope.
|
||||
|
||||
Namespace has a different meaning depending on scope. For example, for `grafana` scope this could be a name of built-in real-time feature like `dashboard` (i.e. dashboards events).
|
||||
|
||||
The path, which is the final part of a channel, usually contains the identifier of some concrete resource such as the ID of a dashboard that a user is currently looking at. But a path can be anything.
|
||||
|
||||
Channels are lightweight and ephemeral - they are created automatically on user subscription and removed as soon as last user left a channel.
|
||||
|
||||
## Data format
|
||||
|
||||
All data travelling over Live channels must be JSON-encoded.
|
||||
@@ -0,0 +1,32 @@
|
||||
+++
|
||||
title = "Live feature overview"
|
||||
description = "Grafana Live feature overview"
|
||||
keywords = ["Grafana", "live", "guide"]
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Grafana Live feature overview
|
||||
|
||||
This topic explains the current Grafana Live capabilities.
|
||||
|
||||
## Dashboard change notifications
|
||||
|
||||
As soon as there is a change to the dashboard layout, it is automatically reflected on other devices connected to Grafana Live.
|
||||
|
||||
## Data streaming from plugins
|
||||
|
||||
With Grafana Live data source, plugins can stream data updates in the form of Grafana data frames to a frontend.
|
||||
|
||||
For data source plugin channels Grafana uses `ds` scope. Namespace in the case of data source channels is a data source unique ID (UID) which is issued by Grafana at the moment of data source creation. The path is a custom string that plugin authors free to choose themselves (just make sure it consists of allowed symbols).
|
||||
|
||||
For example, a data source channel looks like this: `ds/<DATASOURCE_UID>/<CUSTOM_PATH>`.
|
||||
|
||||
Refer to the tutorial about [building a streaming data source backend plugin](https://grafana.com/tutorials/build-a-streaming-data-source-plugin/) for more details.
|
||||
|
||||
The basic streaming example included in Grafana core streams frames with some generated data to a panel. To look at it create a new panel and point it to the `-- Grafana --` data source. Next, choose `Live Measurements` and select the `plugin/testdata/random-20Hz-stream` channel.
|
||||
|
||||
## Data streaming from Telegraf
|
||||
|
||||
A new API endpoint `/api/live/push/:streamId` allows accepting metrics data in Influx format from Telegraf. These metrics are transformed into Grafana data frames and published to channels.
|
||||
|
||||
Refer to the tutorial about [streaming metrics from Telegraf to Grafana](https://grafana.com/tutorials/stream-metrics-from-telegraf-to-grafana/) for more information.
|
||||
@@ -0,0 +1,16 @@
|
||||
+++
|
||||
title = "Live HA setup"
|
||||
description = "Grafana Live HA setup guide"
|
||||
keywords = ["Grafana", "live", "guide", "ha"]
|
||||
weight = 130
|
||||
+++
|
||||
|
||||
# Configure Grafana Live HA setup
|
||||
|
||||
Live features in Grafana v8.0 are designed to work with a single Grafana server instance only. We will add the option for HA configuration in future Grafana releases to eliminate the current limitations.
|
||||
|
||||
Currently, if you have several Grafana server instances behind a load balancer, you may come across the following limitations:
|
||||
|
||||
- Built-in features like dashboard change notifications will only be broadcasted to users connected to the same Grafana server process instance.
|
||||
- Streaming from Telegraf will deliver data only to clients connected to the same instance which received Telegraf data, active stream cache is not shared between different Grafana instances.
|
||||
- A separate unidirectional stream between Grafana and backend data source may be opened on different Grafana servers for the same channel.
|
||||
@@ -9,6 +9,8 @@ Grafana offers several options for grouping users. Each level has different tool
|
||||
|
||||
One of the most important user management tasks is assigning roles, which govern what [permissions]({{< relref "../permissions/_index.md" >}}) a user has. The correct permissions ensure that users have access to only the resources they need.
|
||||
|
||||
> Refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can manage users with fine-grained permissions.
|
||||
|
||||
## Server
|
||||
|
||||
The highest and broadest level of user group in Grafana is the server. Every user with an account in a Grafana instance is a member of the server group.
|
||||
|
||||
@@ -16,30 +16,34 @@ Panels allow you to show your data in visual form. This topic walks you through
|
||||
|
||||
1. Click **Add an empty panel**.
|
||||
|
||||
Grafana creates an empty graph panel with your default data source selected.
|
||||
Grafana creates an empty time series panel with your default data source selected.
|
||||
|
||||
## 2. Edit panel settings
|
||||
|
||||
While not required, we recommend that you add a helpful title and description to your panel. You can use [variables you have defined]({{< relref "../variables/_index.md" >}}) in either field, but not [global variables]({{< relref "../variables/variable-types/global-variables.md" >}}).
|
||||
|
||||
|
||||
|
||||
**Panel title -** Text entered in this field is displayed at the top of your panel in the panel editor and in the dashboard.
|
||||
|
||||
**Description -** Text entered in this field is displayed in a tooltip in the upper left corner of the panel. Write a description of the panel and the data you are displaying. Pretend you are explaining it to a new user six months from now, when it is no longer fresh in your mind. Future editors (possibly yourself) will thank you.
|
||||
|
||||
## 3. Write a query
|
||||
## 2. Write a query
|
||||
|
||||
Each panel needs at least one query to display a visualization. You write queries in the Query tab of the panel editor. For more information about the Query tab, refer to [Queries]({{< relref "queries.md" >}}).
|
||||
|
||||
1. Choose a data source. In the first line of the Query tab, click the drop-down list to see all available data sources. This list includes all data sources you added. Refer to [Add a data source]({{< relref "../datasources/add-a-data-source.md" >}}) if you need instructions.
|
||||
1. Write or construct a query in the query language of your data source. Options will vary. Refer to your specific [data source documentation]({{< relref "../datasources/_index.md" >}}) for specific guidelines.
|
||||
|
||||
## 4. Choose a visualization type
|
||||
## 3. Choose a visualization type
|
||||
|
||||
In the Visualization section of the Panel tab, click a visualization type. Grafana displays a preview of your query results with that visualization applied.
|
||||
In the Visualization list, click a visualization type. Grafana displays a preview of your query results with that visualization applied.
|
||||
|
||||
For more information about individual visualizations, refer to [Visualizations]({{< relref "visualizations/_index.md" >}}).
|
||||
|
||||
|
||||
For more information about individual visualizations, refer to [Visualizations options]({{< relref "visualizations/_index.md" >}}).
|
||||
|
||||
## 4. (Optional) Edit panel settings
|
||||
|
||||
While not required, most visualizations need some adjustment before they properly display the information that you need. Options are defined in the linked topics below.
|
||||
|
||||
- [Panel options]({{< relref "./panel-options.md" >}})
|
||||
- [Visualization-specific options]({{< relref "./visualizations/_index.md" >}})
|
||||
- [Standard options]({{< relref "./standard-options.md" >}})
|
||||
- [Thresholds]({{< relref "./thresholds.md" >}})
|
||||
- [Value mappings]({{< relref "./value-mappings.md" >}})
|
||||
- [Data links]({{< relref "../linking/data-links.md" >}})
|
||||
- [Field overrides]({{< relref "./field-overrides.md" >}})
|
||||
|
||||
## 5. Apply changes and save
|
||||
|
||||
@@ -54,7 +58,5 @@ Our Grafana Fundamentals tutorial is a great place to start, or you can learn mo
|
||||
- Learn more about [panel editor]({{< relref "panel-editor.md" >}}) options.
|
||||
- Add more [queries]({{< relref "queries.md" >}}).
|
||||
- [Transform]({{< relref "transformations/_index.md" >}}) your data.
|
||||
- [Configure]({{< relref "field-options/_index.md" >}}) how your results are displayed in the visualization.
|
||||
|
||||
- If you made a graph panel, set up an [alert]({{< relref "../alerting/_index.md" >}}).
|
||||
- Set up an [alert]({{< relref "../alerting/_index.md" >}}).
|
||||
- Create [templates and variables]({{< relref "../variables/_index.md" >}}).
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
+++
|
||||
title = "Field overrides"
|
||||
keywords = ["grafana", "field options", "documentation", "format fields", "overrides", "override fields"]
|
||||
aliases = ["/docs/grafana/latest/panels/field-options/", "/docs/grafana/latest/panels/field-options/configure-specific-fields/"]
|
||||
weight = 700
|
||||
+++
|
||||
|
||||
# Field overrides
|
||||
|
||||
Overrides allow you to change the settings for one or more fields. Field options for overrides are exactly the same as the field options available in a particular visualization. The only difference is that you choose which fields to apply them to.
|
||||
|
||||
For example, you could change the number of decimal places shown in all numeric fields or columns by changing the **Decimals** option for **Fields with type** that matches **Numeric**.
|
||||
|
||||
## View existing field overrides
|
||||
|
||||
1. Navigate to the panel you want to edit, click the panel title, and then click **Edit**.
|
||||
1. In the side pane, click **Overrides**.
|
||||
|
||||
Grafana displays a list of field overrides, if any have been created for this panel.
|
||||
|
||||
|
||||
|
||||
## Add a field override
|
||||
|
||||
You can override as many fields and add as many field options to each override as you want to.
|
||||
|
||||
1. Navigate to the panel you want to edit, click the panel title, and then click **Edit**.
|
||||
1. In the side pane, click **Overrides**.
|
||||
1. Click **Add field override**.
|
||||
1. Select which fields an override rule will be applied to:
|
||||
- **Fields with name -** Select a field from the list of all available fields. Properties you add to a rule with this selector are only applied to this single field.
|
||||
- **Fields with name matching regex -** Specify fields to override with a regular expression. Properties you add to a rule with this selector are applied to all fields where the field name match the regex.
|
||||
- **Fields with type -** Select fields by type, such as string, numeric, and so on. Properties you add to a rule with this selector are applied to all fields that match the selected type.
|
||||
- **Fields returned by query -** Select all fields returned by a specific query, such as A, B, or C. Properties you add to a rule with this selector are applied to all fields returned by the selected query.
|
||||
1. Click **Add override property**.
|
||||
1. Select the field option that you want to apply.
|
||||
1. Enter options by adding values in the fields. To return options to default values, delete the white text in the fields.
|
||||
1. Continue to add overrides to this field by clicking **Add override property**, or you can click **Add override** and select a different field to add overrides to.
|
||||
1. When finished, click **Save** to save all panel edits to the dashboard.
|
||||
|
||||
## Edit a field override
|
||||
|
||||
1. Navigate to the panel you want to edit, click the panel title, and then click **Edit**.
|
||||
1. In the side pane, click **Overrides**.
|
||||
1. Locate the override that you want to change. You can:
|
||||
- Edit settings on existing overrides or field selection parameters.
|
||||
- Delete existing override properties by clicking the **X** next to the property.
|
||||
- Add additional override properties by clicking **Add override property**.
|
||||
|
||||
## Delete a field override
|
||||
|
||||
1. Navigate to the panel you want to edit, click the panel title, and then click **Edit**.
|
||||
1. In the side pane, click **Overrides**.
|
||||
1. Click the trash can icon next to the override that you want to delete.
|
||||
|
||||
## Example use case for field options and overrides
|
||||
|
||||
The following examples show how you might use field options and overrides.
|
||||
|
||||
## Field option example
|
||||
|
||||
Let’s assume that our result set is a data frame that consists of two fields: time and temperature.
|
||||
|
||||
| time | temperature |
|
||||
| :-----------------: | :---------: |
|
||||
| 2020-01-02 03:04:00 | 45.0 |
|
||||
| 2020-01-02 03:05:00 | 47.0 |
|
||||
| 2020-01-02 03:06:00 | 48.0 |
|
||||
|
||||
Each field (column) of this structure can have field options applied that alter the way its values are displayed. This means that you can, for example, set the Unit to Temperature > Celsius, resulting in the following table:
|
||||
|
||||
| time | temperature |
|
||||
| :-----------------: | :---------: |
|
||||
| 2020-01-02 03:04:00 | 45.0 °C |
|
||||
| 2020-01-02 03:05:00 | 47.0 °C |
|
||||
| 2020-01-02 03:06:00 | 48.0 °C |
|
||||
|
||||
While we're at it, the decimal place doesn't add anything to this display. You can change the Decimals from `auto` to zero (`0`), resulting in the following table:
|
||||
|
||||
| time | temperature |
|
||||
| :-----------------: | :---------: |
|
||||
| 2020-01-02 03:04:00 | 45 °C |
|
||||
| 2020-01-02 03:05:00 | 47 °C |
|
||||
| 2020-01-02 03:06:00 | 48 °C |
|
||||
|
||||
## Field override example
|
||||
|
||||
Let’s assume that our result set is a data frame that consists of four fields: time, high temp, low temp, and humidity.
|
||||
|
||||
| time | high temp | low temp | humidity |
|
||||
| ------------------- | --------- | -------- | -------- |
|
||||
| 2020-01-02 03:04:00 | 45.0 | 30.0 | 67 |
|
||||
| 2020-01-02 03:05:00 | 47.0 | 34.0 | 68 |
|
||||
| 2020-01-02 03:06:00 | 48.0 | 31.0 | 68 |
|
||||
|
||||
Let's apply the field options from the [field option example](#field-option-example) to apply the Celsius unit and get rid of the decimal place. This results in the following table:
|
||||
|
||||
| time | high temp | low temp | humidity |
|
||||
| ------------------- | --------- | -------- | -------- |
|
||||
| 2020-01-02 03:04:00 | 45 °C | 30 °C | 67 °C |
|
||||
| 2020-01-02 03:05:00 | 47 °C | 34 °C | 68 °C |
|
||||
| 2020-01-02 03:06:00 | 48 °C | 31 °C | 68 °C |
|
||||
|
||||
The temperature fields look good, but the humidity is nonsensical. We can fix this by applying a field option override to the humidity field and change the unit to Misc > percent (0-100). This results in a table that makes a lot more sense:
|
||||
|
||||
| time | high temp | low temp | humidity |
|
||||
| ------------------- | --------- | -------- | -------- |
|
||||
| 2020-01-02 03:04:00 | 45 °C | 30 °C | 67% |
|
||||
| 2020-01-02 03:05:00 | 47 °C | 34 °C | 68% |
|
||||
| 2020-01-02 03:06:00 | 48 °C | 31 °C | 68% |
|
||||
@@ -1,7 +1,7 @@
|
||||
+++
|
||||
title = "Legend options"
|
||||
aliases = ["/docs/grafana/latest/panels/visualizations/panel-legend/"]
|
||||
weight = 500
|
||||
weight = 950
|
||||
+++
|
||||
|
||||
# Legend options
|
||||
|
||||
@@ -7,9 +7,11 @@ weight = 200
|
||||
|
||||
This page describes the parts of the Grafana panel editor and links to where you can find more information.
|
||||
|
||||
{{< figure src="/static/img/docs/panel-editor/panel-editor-7-0.png" class="docs-image--no-shadow" max-width="1500px" >}}
|
||||
{{< figure src="/static/img/docs/panel-editor/panel-editor-8-0.png" class="docs-image--no-shadow" max-width="1500px" >}}
|
||||
|
||||
## Open the Panel editor
|
||||
If your user account is assigned the appropriate [organization role]({{< relref "../permissions/organization_roles.md" >}}) or [permissions]({{< relref "../permissions/_index.md" >}}), then you can edit or update a panel at any point after it is created. For more information about creating panels, refer to [Add a panel]({{< relref "./add-a-panel.md" >}}).
|
||||
|
||||
## Open the panel editor
|
||||
|
||||
There are several ways to access the panel editor, also called the **Edit Panel** screen, _edit mode_, or _panel edit mode_:
|
||||
|
||||
@@ -17,12 +19,6 @@ There are several ways to access the panel editor, also called the **Edit Panel*
|
||||
- Click the title of an existing panel and then click **Edit**. The panel opens in edit mode.
|
||||
- Click anywhere on an existing panel and then press **e** on your keyboard. The panel opens in edit mode.
|
||||
|
||||
## Resize panel editor sections
|
||||
|
||||
Drag to resize sections of the panel editor. If the side pane becomes too narrow, then the Panel, Field, and Overrides tabs change to a dropdown list.
|
||||
|
||||
{{< figure src="/static/img/docs/panel-editor/resize-panel-editor-panels-7-0.gif" class="docs-image--no-shadow" max-width="600px" >}}
|
||||
|
||||
## Parts of the panel editor
|
||||
|
||||
This section describes the parts of the panel editor screen and a bit about fields, options, or tasks associated with each part. Some sections in this page link to pages where sections or tasks are documented more fully.
|
||||
@@ -44,8 +40,9 @@ On the right side of the header are the following options:
|
||||
|
||||
The visualization preview section contains viewing options, time range controls, the visualization preview, and (if applicable) the panel title, axes, and legend.
|
||||
|
||||
{{< figure src="/static/img/docs/panel-editor/visualization-preview-7-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
{{< figure src="/static/img/docs/panel-editor/visualization-preview-8-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
|
||||
- **Table view -** Convert any visualization to a table so that you can see the data. Useful for troubleshooting.
|
||||
- **Fill -** The visualization preview will fill the available space in the preview part. If you change the width of the side pane or height of the bottom pane the visualization will adapt to fill whatever space is available.
|
||||
- **Fit -** The visualization preview will fill the available space in but preserve the aspect ratio of the panel.
|
||||
- **Exact -** The visualization preview will have the exact size as the size on the dashboard. If not enough space is available, the visualization will scale down preserving the aspect ratio.
|
||||
@@ -55,20 +52,35 @@ The visualization preview section contains viewing options, time range controls,
|
||||
|
||||
The section contains tabs where you enter queries, transform your data, and create alert rules (if applicable).
|
||||
|
||||
{{< figure src="/static/img/docs/panel-editor/data-section-7-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
{{< figure src="/static/img/docs/panel-editor/data-section-8-0.png" class="docs-image--no-shadow" max-width="1200px" >}}
|
||||
|
||||
- **Query tab -** Select your data source and enter queries here. For more information, refer to [Queries]({{< relref "queries.md" >}}).
|
||||
- **Transform tab -** Apply data transformations. For more information, refer to [Transformations]({{< relref "transformations/_index.md" >}}).
|
||||
- **Alert tab -** Write alert rules. For more information, refer to [Create alerts]({{< relref "../alerting/create-alerts.md" >}}).
|
||||
- **Alert tab -** Write alert rules. For more information, refer to [Create alerts]({{< relref "../alerting/old-alerting/create-alerts.md" >}}).
|
||||
|
||||
### Panel and field options (side pane)
|
||||
### Panel display options (side pane)
|
||||
|
||||
The section contains tabs where you control almost every aspect of how your data is visualized. Not all tabs are available for each visualization.
|
||||
The section contains tabs where you configure almost every aspect of your data Visualization. Not all options are available for each visualization.
|
||||
|
||||
Features in these tabs are documented in the following topics:
|
||||
The data model used in Grafana, namely the [data frame]({{< relref "../developers/plugins/data-frames.md" >}}), is a columnar-oriented table structure that unifies both time series and table query results. Each column within this structure is called a _field_. A field can represent a single time series or table column.
|
||||
|
||||
- [Add a panel]({{< relref "add-a-panel.md" >}}) describes basic panel settings.
|
||||
- [Visualizations]({{< relref "visualizations/_index.md" >}}) display options vary widely. They are described in the individual visualization topic.
|
||||
- [Field options and overrides]({{< relref "field-options/_index.md" >}}) allow you to control almost every aspect of your visualization, including units, value mappings, and [Thresholds]({{< relref "thresholds.md" >}}).
|
||||
Field options allow you to change how the data is displayed in your visualizations. Options and overrides that you apply do not change the data, however they change how Grafana displays the data.
|
||||
|
||||
#### Field options
|
||||
|
||||
When you change an option, it is applied to all fields, meaning all series or columns. For example, if you change the unit to percentage, then all fields with numeric values are displayed in percentages.
|
||||
|
||||
## Field overrides
|
||||
|
||||
_Field overrides_ can be added or viewed in the Overrides tab in the panel editor side menu. You can apply options to specific fields (series or columns) rather than all fields. Learn how to apply an override in [Field overrides]({{< relref "./field-overrides.md" >}}).
|
||||
|
||||
Options are documented in the following topics:
|
||||
|
||||
- [Add a panel]({{< relref "./add-a-panel.md" >}}) describes how to add a panel to a dashboard.
|
||||
- [Panel options]({{< relref "./panel-options.md" >}})
|
||||
- [Visualization options]({{< relref "visualizations/_index.md" >}}) vary widely. They are described in the individual visualization topic.
|
||||
- [Standard options]({{< relref "./standard-options.md" >}})
|
||||
- [Thresholds]({{< relref "./thresholds.md" >}})
|
||||
- [Value mappings]({{< relref "./value-mappings.md" >}})
|
||||
- [Panel links]({{< relref "../linking/panel-links.md" >}}) and [Data links]({{< relref "../linking/data-links.md" >}}) help you connect your visualization to other resources.
|
||||
|
||||
- [Overrides]({{< relref "./field-overrides.md" >}})
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
+++
|
||||
title = "Library panels"
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Library panels
|
||||
|
||||
Library panels allow users to create reusable panels where any changes made to one instance of the library panel is reflected on every dashboard
|
||||
affecting all other instances where the panel is used. These panels can be saved in folders alongside Dashboards and streamline reuse of panels
|
||||
across multiple dashboards.
|
||||
|
||||
## Create a library panel
|
||||
|
||||
Before you can use library panels, you have to create them.
|
||||
|
||||
> **Note:** When you create library panels, the panel on the source dashboard is converted to a library panel as well. You will need to save the original dashboard once a panel is converted.
|
||||
|
||||
|
||||
To create a library panel:
|
||||
|
||||
1. Create a Grafana panel as you normally would, following instructions in [Add a panel]({{< relref "./add-a-panel.md" >}}). You an also use an existing panel.
|
||||
1. Click the title of the panel and then click **Edit**. The panel opens in edit mode.
|
||||
1. In the panel display options (side pane), click the down arrow option to bring changes to the visualization.
|
||||
{{< figure src="/static/img/docs/library-panels/create-lib-panel-from-edit-8-0.png" class="docs-image--no-shadow" max-width= "800px" caption="Screenshot of the edit panel" >}}
|
||||
1. Click the **Library panels** option, and then click **Create new library panel** to open the create dialog.
|
||||
{{< figure src="/static/img/docs/library-panels/create-lib-panel-8-0.png" class="docs-image--no-shadow" max-width= "500px" caption="Screenshot of the create library panel dialog" >}}
|
||||
1. In **Library panel name**, enter the name.
|
||||
1. In **Save in folder**, select the folder to save the library panel. By default, the General folder is selected.
|
||||
1. Click **Create library panel** to save your changes.
|
||||
1. Save the dashboard.
|
||||
|
||||
Optionally, you can click title of the panel and then click **More > Create Library panel**. Next, follow the instructions Step 5 in the procedure above.
|
||||
|
||||
{{< figure src="/static/img/docs/library-panels/create-from-more-8-0.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the edit panel" >}}
|
||||
|
||||
Also, library panels can also be created using the “Share” option for any panel.
|
||||
|
||||
Once created, you can modify the library panel using any dashboard on which it appears. Once the library panel changes are saved, all instances of the library panel will reflect these modifications.
|
||||
|
||||
|
||||
## Add a library panel
|
||||
|
||||
To add a library panel to a dashboard:
|
||||
|
||||
1. Hover over the **+** option on the left menu, then select **Create** from the drop down options. The Add panel dialog opens.
|
||||
{{< figure src="/static/img/docs/library-panels/add-library-panel-8-0.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the edit panel" >}}
|
||||
1. Click the **Add a panel from the panel library** option. You will see a list of your library panels.
|
||||
1. Filter the list or search to find the panel you want to add.
|
||||
1. Click your desired panel and add it to the dashboard.
|
||||
|
||||
## Manage library panels
|
||||
|
||||
To view and manage existing library panels:
|
||||
|
||||
1. Hover over the **Dashboard** option on the left menu, then click **Library panels**. You can see a list of previously defined library panels.
|
||||
{{< figure src="/static/img/docs/library-panels/library-panel-list-8-0.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the edit panel" >}}
|
||||
1. Search for a specific library panel if you know its name. You can also filter the panels by folder or type.
|
||||
|
||||
|
||||
## Unlink a library panel
|
||||
|
||||
In case you have a library panel on your dashboard that want to modify it without affecting all other instances of the library panel, you can unlink the library panel.
|
||||
|
||||
To unlink a library panel from a dashboard:
|
||||
|
||||
1. Hover over **Dashboard** on the left menu, and then click **Library panels**.
|
||||
1. Select a library panel that is being used in different dashboards. You will see a list of all the dashboards where the library panel is used.
|
||||
{{< figure src="/static/img/docs/library-panels/unlink-8-0.png" class="docs-image--no-shadow" max-width= "900px" caption="Screenshot of the edit panel" >}}
|
||||
1. Select the panel you want to unlink and update.
|
||||
1. Click the title of the panel and then click **Edit**. The panel opens in edit mode.
|
||||
1. Click the **Unlink** option on the top right corner of the UI.
|
||||
|
||||
## Delete a library panel
|
||||
|
||||
Before you delete a library panel, verify that it is no longer in use on any dashboard.
|
||||
|
||||
To delete a library panel:
|
||||
|
||||
1. Hover over **Dashboard** on the left menu, and select Library panels from the drop down options.
|
||||
1. Select a library panel that is being used in different dashboards. You will see a list of all the dashboards.
|
||||
1. Select the panel you want to delete.
|
||||
1. Click the delete icon next to the library panel name.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
+++
|
||||
title = "Panel options"
|
||||
weight = 900
|
||||
+++
|
||||
|
||||
# Panel options
|
||||
|
||||
Panel options are common to all panels. They are basic options to add information and clarity to your panels. Fields are described below.
|
||||
|
||||
While not required, we recommend that you add a helpful title and description to all panels.
|
||||
|
||||
|
||||
|
||||
## Title
|
||||
|
||||
Text entered in this field is displayed at the top of your panel in the panel editor and in the dashboard. You can use [variables you have defined]({{< relref "../variables/_index.md" >}}) in either field, but not [global variables]({{< relref "../variables/variable-types/global-variables.md" >}}).
|
||||
|
||||
## Description
|
||||
|
||||
Text entered in this field is displayed in a tooltip in the upper left corner of the panel. Write a description of the panel and the data you are displaying. Pretend you are explaining it to a new user six months from now, when it is no longer fresh in your mind. Future editors (possibly yourself) will thank you.
|
||||
|
||||
You can use [variables you have defined]({{< relref "../variables/_index.md" >}}) in either field, but not [global variables]({{< relref "../variables/variable-types/global-variables.md" >}}).
|
||||
|
||||
## Transparent background
|
||||
|
||||
Toggle the transparent background option on your panel display.
|
||||
|
||||
## Panel links
|
||||
|
||||
{{< docs/shared "panels/panel-links-intro.md" >}}
|
||||
|
||||
For more information, refer to [Panel links]({{< relref "../linking/panel-links.md" >}}).
|
||||
|
||||
## Repeat options
|
||||
|
||||
{{< docs/shared "panels/repeat-panels-intro.md" >}}
|
||||
|
||||
For more information, refer to [Repeat panels or rows]({{< relref "./repeat-panels-or-rows.md" >}}).
|
||||
@@ -0,0 +1,51 @@
|
||||
+++
|
||||
title = "Repeat panels or rows"
|
||||
keywords = ["grafana", "templating", "documentation", "guide", "template", "variable", "repeat"]
|
||||
aliases = ["/docs/grafana/latest/variables/repeat-panels-or-rows/"]
|
||||
weight = 800
|
||||
+++
|
||||
|
||||
# Repeat panels or rows
|
||||
|
||||
{{< docs/shared "panels/repeat-panels-intro.md" >}}
|
||||
|
||||
Template variables can be very useful to dynamically change your queries across a whole dashboard. If you want
|
||||
Grafana to dynamically create new panels or rows based on what values you have selected, you can use the _Repeat_ feature.
|
||||
|
||||
## Grafana Play examples
|
||||
|
||||
You can see examples in the following dashboards:
|
||||
|
||||
- [Prometheus repeat](https://play.grafana.org/d/000000036/prometheus-repeat)
|
||||
- [Repeated Rows Dashboard](https://play.grafana.org/d/000000153/repeat-rows)
|
||||
|
||||
## Repeating panels
|
||||
|
||||
If you have a variable with `Multi-value` or `Include all value` options enabled you can choose one panel and have Grafana repeat that panel
|
||||
for every selected value. You find the _Repeat_ feature under the _General tab_ in panel edit mode.
|
||||
|
||||
The `direction` controls how the panels will be arranged.
|
||||
|
||||
By choosing `horizontal` the panels will be arranged side-by-side. Grafana will automatically adjust the width
|
||||
of each repeated panel so that the whole row is filled. Currently, you cannot mix other panels on a row with a repeated
|
||||
panel.
|
||||
|
||||
Set `Max per row` to tell grafana how many panels per row you want at most. It defaults to _4_ if you don't set anything.
|
||||
|
||||
By choosing `vertical` the panels will be arranged from top to bottom in a column. The width of the repeated panels will be the same as of the first panel (the original template) being repeated.
|
||||
|
||||
Only make changes to the first panel (the original template). To have the changes take effect on all panels you need to trigger a dynamic dashboard re-build.
|
||||
You can do this by either changing the variable value (that is the basis for the repeat) or reload the dashboard.
|
||||
|
||||
> **Note:** Repeating panels require variables to have one or more items selected; you cannot repeat a panel zero times to hide it.
|
||||
|
||||
## Repeating rows
|
||||
|
||||
As seen above with the panels you can also repeat rows if you have variables set with `Multi-value` or
|
||||
`Include all value` selection option.
|
||||
|
||||
To enable this feature you need to first add a new _Row_ using the _Add Panel_ menu. Then by hovering the row title and
|
||||
clicking on the cog button, you will access the `Row Options` configuration panel. You can then select the variable
|
||||
you want to repeat the row for.
|
||||
|
||||
It may be a good idea to use a variable in the row title as well.
|
||||
@@ -1,6 +1,6 @@
|
||||
+++
|
||||
title = "Transformations"
|
||||
weight = 300
|
||||
weight = 350
|
||||
+++
|
||||
|
||||
# Transformations
|
||||
|
||||
@@ -3,14 +3,138 @@ title = "Value mappings"
|
||||
weight = 600
|
||||
+++
|
||||
|
||||
## Value mappings
|
||||
# Value mappings
|
||||
|
||||
Value mappings come in different types.
|
||||
Value mapping concept allow you to replace values or ranges in your visualizations with words or emojis.
|
||||
|
||||
* **Range** maps numerical ranges to a display text and color.
|
||||
* **Value** maps text values to a color or different display text.
|
||||
* **Special** maps special values like `Null`, `NaN` and boolean values like `true` and `false` to a display text and color.
|
||||
Values mapped via value mappings will skip the unit formatting. This means that a text value mapped to a numerical value will not be formatted using the configured unit.
|
||||
|
||||
The display text and color are both optional. If you only want to assign colors to text values you can leave the display text empty and the original value will be used for display.
|
||||
|
||||
|
||||
Values mapped via value mappings will skip the unit formatting. This means that a text value mapped to a numerical value will not be formatted using the configured unit.
|
||||
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.
|
||||
|
||||
## Value mapping examples
|
||||
|
||||
Value mappings are displayed differently in different visualizations.
|
||||
|
||||
### Time series example
|
||||
|
||||
Here's an example showing a Time series visualization with value mappings. Value mapping colors are not applied to this visualization, but the display text is shown on the axis.
|
||||
|
||||
|
||||
|
||||
### Stat example
|
||||
|
||||
Here's an example showing a Stat visualization with value mappings. You might want to hide the sparkline so it doesn't interfere with the values. Value mapping text colors are applied.
|
||||
|
||||
|
||||
|
||||
### Bar gauge example
|
||||
|
||||
Here's an example showing a Bar gauge visualization with value mappings. The value mapping colors are applied to the text but not the gauges.
|
||||
|
||||
|
||||
|
||||
### Table example
|
||||
|
||||
Here's an example showing a Table visualization with value mappings. If you want value mapping colors displayed on the table, then set the cell display mode to **Color text** or **Color background**.
|
||||
|
||||
|
||||
|
||||
## Value mappings fields
|
||||
|
||||
This section describes options in the Value mappings user interface.
|
||||
|
||||
> **Note:** Display text and Color are both optional. If you want to only assign colors to the text values, then you can leave the display text empty and the original value is displayed.
|
||||
|
||||
### Condition
|
||||
|
||||
This column lists the type of condition a value mapping is triggered by and the values.
|
||||
|
||||
You can map values to three different conditions:
|
||||
|
||||
- **Value** maps text values to a color or different display text. For example, if a value is `10`, I want Grafana to display **Perfection!** rather than the number.
|
||||
- **Range** maps numerical ranges to a display text and color. For example, if a value is within a certain range, I want Grafana to display **Low** or **High** rather than the number.
|
||||
- **Special** maps special values like `Null`, `NaN` (not a number), and boolean values like `true` and `false` to a display text and color. For example, if Grafana encounters a `null`, I want Grafana to display **N/A**.
|
||||
|
||||
You can also use the dots on the left as a "handle" to drag and reorder value mappings in the list.
|
||||
|
||||
### Display text
|
||||
|
||||
The _display text_ is what Grafana displays instead of a number when the listed condition is met.
|
||||
|
||||
You can enter any Ascii character or emoji in this field.
|
||||
|
||||
### Color
|
||||
|
||||
You can select a color to for Grafana to display the value mapping text in.
|
||||
|
||||
- **Set color -** Click **Set color** to see a range of recommended colors. Click **Custom** to choose your own color.
|
||||
- **Text color -** The primary text color for the current theme, i.e. white in dark theme and black in light theme.
|
||||
- **Transparent -** Makes the color transparent so that the value mapping color shows whatever color is behind it, such as a panel background color.
|
||||
|
||||
|
||||
|
||||
### Copy icon
|
||||
|
||||
Click the copy icon in the value mapping row that you want to copy.
|
||||
|
||||
### Trash icon
|
||||
|
||||
Click the trash can icon to delete a value mapping. Once deleted, you cannot recover it.
|
||||
|
||||
## Map a value
|
||||
|
||||
Create a mapping for a single value.
|
||||
|
||||
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Add value mappings**.
|
||||
1. Click **Add a new mapping** and then select **Value**.
|
||||
1. Enter the exact value for Grafana to match.
|
||||
1. (Optional) Enter display text.
|
||||
1. (Optional) Set the color.
|
||||
1. Click **Update** to save the value mapping.
|
||||
|
||||
## Map a range
|
||||
|
||||
Create a mapping for a range of values.
|
||||
|
||||
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Add value mappings**.
|
||||
1. Click **Add a new mapping** and then select **Range**.
|
||||
1. Enter the beginning and ending values in the range for Grafana to match.
|
||||
1. (Optional) Enter display text.
|
||||
1. (Optional) Set the color.
|
||||
1. Click **Update** to save the value mapping.
|
||||
|
||||
## Map a special value
|
||||
|
||||
Create a mapping for a special value.
|
||||
|
||||
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Add value mappings**.
|
||||
1. Click **Add a new mapping** and then select **Special**.
|
||||
1. Select the special value for Grafana to match. Options include:
|
||||
- Null
|
||||
- NaN (Not a Number)
|
||||
- Null + NaN
|
||||
- True
|
||||
- False
|
||||
- Empty
|
||||
1. (Optional) Enter display text.
|
||||
1. (Optional) Set the color.
|
||||
1. Click **Update** to save the value mapping.
|
||||
|
||||
## Edit a value mapping
|
||||
|
||||
1. [Open the panel editor]({{< relref "./panel-editor.md#open-the-panel-editor" >}}).
|
||||
1. In the Value mappings section of the side pane, click **Edit value mappings**.
|
||||
1. Make any necessary changes in the fields and then click **Update**.
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
+++
|
||||
title = "Visualizations"
|
||||
weight = 300
|
||||
title = "Visualization options"
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Visualizations
|
||||
# Visualization options
|
||||
|
||||
Grafana offers a variety of visualizations to suit different use cases. This section of the documentation lists the different visualizations available in Grafana and their unique display settings.
|
||||
|
||||
The default options and their unique display options are described in the pages in this section.
|
||||
Grafana offers a variety of visualizations to suit different use cases. This section of the documentation lists the different visualizations available in Grafana and their unique options.
|
||||
|
||||
You can add more panel types with [plugins]({{< relref "../../plugins/_index.md" >}}).
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
+++
|
||||
title = "Alert list panel"
|
||||
title = "Alert list"
|
||||
keywords = ["grafana", "alert list", "documentation", "panel", "alertlist"]
|
||||
aliases = ["/docs/grafana/latest/reference/alertlist/", "/docs/grafana/latest/features/panels/alertlist/"]
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Alert list panel
|
||||
# Alert list
|
||||
|
||||
The Alert list panel allows you to display your dashboards alerts. You can configure the list to show current state or recent state changes. You can read more about alerts in [Alerts overview]({{< relref "../../alerting/_index.md" >}}).
|
||||
The Alert list allows you to display your dashboards alerts. You can configure the list to show current state or recent state changes. You can read more about alerts in [Alerts overview]({{< relref "../../alerting/_index.md" >}}).
|
||||
|
||||
{{< figure src="/static/img/docs/v45/alert-list-panel.png" max-width="850px" >}}
|
||||
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
+++
|
||||
title = "Bar chart"
|
||||
description = "Bar chart visualization"
|
||||
keywords = ["grafana", "docs", "bar chart", "panel", "barchart"]
|
||||
weight = 170
|
||||
+++
|
||||
|
||||
# Bar chart
|
||||
|
||||
This panel visualization allows you to graph categorical data.
|
||||
|
||||
{{< figure src="/static/img/docs/bar-chart-panel/bar-chart-example-v8-0.png" max-width="1025px" caption="Bar chart example" >}}
|
||||
|
||||
## Supported data formats
|
||||
|
||||
Only one data frame is supported and it needs to have at least one string field that will be used as the category for an X or Y axis and one or more numerical fields.
|
||||
|
||||
Example:
|
||||
|
||||
| Browser | Market share |
|
||||
| ------- | ------------ |
|
||||
| Chrome | 50 |
|
||||
| IE | 17.5 |
|
||||
|
||||
If you have more than one numerical field the panel will show grouped bars.
|
||||
|
||||
### Visualizing time series or multiple result sets
|
||||
|
||||
If you have multiple time series or tables you first need to join them using a join or reduce transform. For example if you
|
||||
have multiple time series and you want to compare their last and max value add the **Reduce** transform and specify **Max** and **Last** as options under **Calculations**.
|
||||
|
||||
{{< figure src="/static/img/docs/bar-chart-panel/bar-chart-time-series-v8-0.png" max-width="1025px" caption="Bar chart time series example" >}}
|
||||
|
||||
## Bar chart options
|
||||
|
||||
Use these options to refine your visualization.
|
||||
|
||||
### Orientation
|
||||
|
||||
- **Auto** - Grafana decides the bar orientation based on what the panel dimensions.
|
||||
- **Horizontal** - Will make the X axis the category axis.
|
||||
- **Vertical** - Will make the Y axis the category axis.
|
||||
|
||||
### Show values
|
||||
|
||||
This controls whether values are shown on top or to the left of bars.
|
||||
|
||||
- **Auto** Values will be shown if there is space
|
||||
- **Always** Always show values.
|
||||
- **Never** Never show values.
|
||||
|
||||
### Group width
|
||||
|
||||
Controls the width of groups. 1 = max with, 0 = min width.
|
||||
|
||||
### Bar width
|
||||
|
||||
Controls the width of bars. 1 = Max width, 0 = Min width.
|
||||
|
||||
### Line width
|
||||
|
||||
Controls line width of the bars.
|
||||
|
||||
### Fill opacity
|
||||
|
||||
Controls the fill opacity bars.
|
||||
|
||||
### Gradient mode
|
||||
|
||||
Set the mode of the gradient fill. Fill gradient is based on the line color. To change the color, use the standard [color scheme]({{< relref "../standard-options.md#color-scheme" >}}) field option.
|
||||
|
||||
Gradient appearance is influenced by the **Fill opacity** setting.
|
||||
|
||||
#### None
|
||||
|
||||
No gradient fill. This is the default setting.
|
||||
|
||||
#### Opacity
|
||||
|
||||
Transparency of the gradient is calculated based on the values on the y-axis. Opacity of the fill is increasing with the values on the Y-axis.
|
||||
|
||||
#### Hue
|
||||
|
||||
Gradient color is generated based on the hue of the line color.
|
||||
|
||||
{{< docs/shared "visualizations/tooltip-mode.md" >}}
|
||||
|
||||
{{< docs/shared "visualizations/legend-mode.md" >}}
|
||||
|
||||
### Legend calculations
|
||||
|
||||
Choose which of the [standard calculations]({{< relref "../calculations-list.md">}}) to show in the legend. You can have more than one.
|
||||
|
||||
## Text size
|
||||
|
||||
Enter a **Value** to change the size of the text on your bar chart.
|
||||
|
||||
## Axis
|
||||
|
||||
Use the following field settings to refine how your axes display.
|
||||
|
||||
Some field options will not affect the visualization until you click outside of the field option box you are editing or press Enter.
|
||||
|
||||
### Placement
|
||||
|
||||
Select the placement of the Y-axis.
|
||||
|
||||
#### Auto
|
||||
|
||||
Grafana automatically assigns Y-axis to the series. When there are two or more series with different units, then Grafana assigns the left axis to the first unit and right to the following units.
|
||||
|
||||
#### Left
|
||||
|
||||
Display all Y-axes on the left side.
|
||||
|
||||
#### Right
|
||||
|
||||
Display all Y-axes on the right side.
|
||||
|
||||
#### Hidden
|
||||
|
||||
Hide the Y-axes.
|
||||
|
||||
### Label
|
||||
|
||||
Set a Y-axis text label.
|
||||
|
||||
If you have more than one Y-axis, then you can give assign different labels with an override.
|
||||
|
||||
### Width
|
||||
|
||||
Set a fixed width of the axis. By default, Grafana dynamically calculates the width of an axis.
|
||||
|
||||
By setting the width of the axis, data whose axes types are different can share the same display proportions. This makes it easier to compare more than one graph’s worth of data because the axes are not shifted or stretched within visual proximity of each other.
|
||||
|
||||
### Soft min and soft max
|
||||
|
||||
Set a **Soft min** or **soft max** option for better control of Y-axis limits. By default, Grafana sets the range for the Y-axis automatically based on the dataset.
|
||||
|
||||
**Soft min** and **soft max** settings can prevent blips from turning into mountains when the data is mostly flat, and hard min or max derived from standard min and max field options can prevent intermittent spikes from flattening useful detail by clipping the spikes past a defined point.
|
||||
|
||||
You can set standard min/max options to define hard limits of the Y-axis. For more information, refer to [Standard field options]({{< relref "../standard-options.md#max" >}}).
|
||||
@@ -1,12 +1,12 @@
|
||||
+++
|
||||
title = "Bar gauge panel"
|
||||
description = "Bar gauge panel docs"
|
||||
title = "Bar gauge"
|
||||
description = "Bar gauge panel options"
|
||||
keywords = ["grafana", "bar", "bar gauge"]
|
||||
aliases =["/docs/grafana/latest/features/panels/bar_gauge/"]
|
||||
weight = 200
|
||||
+++
|
||||
|
||||
# Bar gauge panel
|
||||
# Bar gauge
|
||||
|
||||
The bar gauge simplifies your data by reducing every field to a single value. You choose how Grafana calculates the reduction.
|
||||
|
||||
@@ -14,28 +14,48 @@ This panel can show one or more bar gauges depending on how many series, rows, o
|
||||
|
||||
{{< figure src="/static/img/docs/v66/bar_gauge_cover.png" max-width="1025px" caption="Stat panel" >}}
|
||||
|
||||
## Data and field options
|
||||
## Value options
|
||||
|
||||
Bar gauge visualizations allow you to apply:
|
||||
Use the following options to refine how your visualization displays the value:
|
||||
|
||||
- [Data transformations]({{< relref "../transformations/_index.md" >}})
|
||||
- [Field options and overrides]({{< relref "../field-options/_index.md" >}})
|
||||
- [Thresholds]({{< relref "../thresholds.md" >}})
|
||||
### Show
|
||||
|
||||
## Display options
|
||||
Choose how Grafana displays your data.
|
||||
|
||||
#### Calculate
|
||||
|
||||
Use the following options to refine your visualization:
|
||||
Show a calculated value based on all rows.
|
||||
|
||||
- **Show -** Choose how Grafana displays your data.
|
||||
- **Calculate -** Show a calculated value based on all rows. For a list of available calculations, refer to [List of calculations]({{< relref "../calculations-list.md" >}}).
|
||||
- **All values -** Show a separate stat for every row. If you select this option, then you can also select a **Limit**, or the maximum number of rows to display.
|
||||
- **Value -** Select a reducer function that Grafana will use to reduce many fields to a single value. Click the **Value** list to see functions and brief descriptions.
|
||||
- **Orientation -** Choose a stacking direction.
|
||||
- **Auto -** Grafana selects what it thinks is the best orientation.
|
||||
- **Horizontal -** Bars stretch horizontally, left to right.
|
||||
- **Vertical -** Bars stretch vertically, top to bottom.
|
||||
- **Display mode -** Choose a display mode.
|
||||
- **Gradient -** Threshold levels define a gradient.
|
||||
- **Retro LCD -** The gauge is split into small cells that are lit or unlit.
|
||||
- **Basic -** Single color based on the matching threshold.
|
||||
- **Show unfilled area -** Select this if you want to render the unfilled region of the bars as dark gray. Not applicable to Retro LCD display mode.
|
||||
- **Calculation -** Select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to [List of calculations]({{< relref "../calculations-list.md" >}}).
|
||||
- **Fields -** Select the fields display in the panel.
|
||||
|
||||
#### All values
|
||||
|
||||
Show a separate stat for every row. If you select this option, then you can also limit the number of rows to display.
|
||||
|
||||
- **Limit -** The maximum number of rows to display. Default is 5,000.
|
||||
- **Fields -** Select the fields display in the panel.
|
||||
|
||||
## Bar gauge options
|
||||
|
||||
Adjust how the bar gauge is displayed.
|
||||
|
||||
### Orientation
|
||||
|
||||
Choose a stacking direction.
|
||||
|
||||
- **Auto -** Grafana selects what it thinks is the best orientation.
|
||||
- **Horizontal -** Bars stretch horizontally, left to right.
|
||||
- **Vertical -** Bars stretch vertically, top to bottom.
|
||||
|
||||
### Display mode
|
||||
|
||||
Choose a display mode.
|
||||
|
||||
- **Gradient -** Threshold levels define a gradient.
|
||||
- **Retro LCD -** The gauge is split into small cells that are lit or unlit.
|
||||
- **Basic -** Single color based on the matching threshold.
|
||||
|
||||
### Show unfilled area
|
||||
|
||||
Select this if you want to render the unfilled region of the bars as dark gray. Not applicable to Retro LCD display mode.
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
+++
|
||||
title = "Dashboard list panel"
|
||||
title = "Dashboard list"
|
||||
keywords = ["grafana", "dashboard list", "documentation", "panel", "dashlist"]
|
||||
aliases = ["/docs/grafana/latest/reference/dashlist/", "/docs/grafana/latest/features/panels/dashlist/"]
|
||||
weight = 300
|
||||
+++
|
||||
|
||||
# Dashboard list panel
|
||||
# Dashboard list
|
||||
|
||||
The dashboard list panel allows you to display dynamic links to other dashboards. The list can be configured to use starred dashboards, recently viewed dashboards, a search query, and dashboard tags.
|
||||
The dashboard list visualization allows you to display dynamic links to other dashboards. The list can be configured to use starred dashboards, recently viewed dashboards, a search query, and dashboard tags.
|
||||
|
||||
{{< figure src="/static/img/docs/v45/dashboard-list-panels.png" max-width="850px">}}
|
||||
|
||||
@@ -17,15 +17,13 @@ On each dashboard load, this panel queries the dashboard list, always providing
|
||||
|
||||
Use these options to refine your visualization.
|
||||
|
||||
### Options
|
||||
|
||||
- **Starred -** Display starred dashboards in alphabetical order.
|
||||
- **Recently viewed -** Display recently viewed dashboards in alphabetical order.
|
||||
- **Search -** Display dashboards by search query or tags. You must enter at least one value in **Query** or **Tags**. For the **Query** and **Tags** fields. Variable interpolation is supported, for example,`$my_var` or `${my_var}`.
|
||||
- **Show headings -** The chosen list selection (Starred, Recently viewed, Search) is shown as a heading.
|
||||
- **Max items -** Sets the maximum number of items to list per section. For example, if you left this at the default value of 10 and displayed Starred and Recently viewed dashboards, then the panel would display up to 20 total dashboards, ten in each section.
|
||||
|
||||
### Search
|
||||
## Search
|
||||
|
||||
These options only apply if the **Search** option is selected.
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user