diff --git a/docs/sources/alerting/_index.md b/docs/sources/alerting/_index.md index 12e9bfd4bc5..84142ce7014 100644 --- a/docs/sources/alerting/_index.md +++ b/docs/sources/alerting/_index.md @@ -1,5 +1,5 @@ +++ -aliases = ["/docs/grafana/latest/alerting/", "/docs/grafana/latest/alerting/unified-alerting/difference-old-new/"] +aliases = ["/docs/grafana/latest/alerting/", "/docs/grafana/latest/alerting/unified-alerting/alerting/"] title = "Alerting" weight = 114 +++ @@ -18,12 +18,14 @@ For new installations or existing installs without alerting configured, Grafana | ----------- | ------------- | ------------- | ------------- | | Grafana 9.0 | On by default | On by default | On by default | -- For existing OSS installations with legacy dashboard alerting, you can [opt-in]({{< relref "./opt-in.md" >}}) to Grafana alerting. -- For Grafana Cloud instances using legacy cloud alerting, contact customer support to migrate to Grafana alerting. +Existing installations that upgrade to v9.0 will have Grafana alerting enabled by default. For more information on migrating from legacy or the cloud alerting plugin, see [Migrating to Grafana alerting]({{< relref "./migrating-alerts/_index.md" >}}). Before you begin, we recommend that you familiarize yourself with some of the [fundamental concepts]({{< relref "./fundamentals/_index.md" >}}) of Grafana alerting. Refer to [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to learn more about controlling access to alerts using role-based permissions. -- [About alert rules]({{< relref "./fundamentals/alert-rules/_index.md" >}}) +<<<<<<< HEAD + +- # [About alert rules]({{< relref "./fundamentals/alert-rules/_index.md" >}}) + > > > > > > > b5d48d217a (Docs: Created separate section for migration under alerting (#49616)) - [Migrating legacy alerts]({{< relref "./migrating-alerts/_index.md" >}}) - [Disable Grafana alerting in OSS]({{< relref "./migrating-alerts/opt-out.md" >}}) - [Create Grafana managed alerting rules]({{< relref "alerting-rules/create-grafana-managed-rule.md" >}}) diff --git a/docs/sources/alerting/migrating-alerts/_index.md b/docs/sources/alerting/migrating-alerts/_index.md new file mode 100644 index 00000000000..fad45c086e7 --- /dev/null +++ b/docs/sources/alerting/migrating-alerts/_index.md @@ -0,0 +1,26 @@ ++++ +aliases = ["/docs/grafana/latest/alerting/migrating-alerts/"] +description = "Migrate Grafana alerts" +title = "Migrate to Grafana alerting" +weight = 113 ++++ + +# Migrate to Grafana alerting + +Grafana alerting is the default for new Cloud, Enterprise, and OSS installations. The new installations will only show the Grafana alerting icon in the left navigation panel. + +Existing installations that upgrade to v9.0 will have Grafana alerting enabled by default. + +| Grafana instance upgraded to v 90 | | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Cloud | Existing Cloud installations with legacy dashboard alerting will have two alerting icons in the left navigation panel - the old alerting plugin icon and the new Grafana alerting icon. During upgrade, existing alerts from the Cloud alerting plugin are migrated to Grafana alerting. Once migration is complete, you can access aman manage the older alerts from the new alerting Grafana alerting icon in the navigation panel. The (older) Cloud alerting plugin is uninstalled from your cloud instance. Contact customer support if you **do not wish** to migrate to Grafana alerting for your Cloud stack. If you choose to use legacy alerting, use the You will see the new Grafana alerting icon as well as the old Cloud alerting plugin in the left navigation panel. | +| Enterprise | Existing Enterprise instances using legacy alerting will have both the old (marked as legacy) and the new alerting icons in the navigation panel. During upgrade, existing legacy alerts are migrated to Grafana alerting. If you wish, you can [opt-out]({{< relref "./opt-out.md" >}}) of Grafana alerting and roll back to legacy alerting. In that case, you can manage your legacy alerts from the alerting icon marked as legacy. | +| OSS | Existing OSS installations with legacy dashboard alerting will have two alerting icons in the left navigation panel - the old alerting icon (marked as legacy) and the new Grafana alerting icon. During upgrade, existing legacy alerts are migrated to Grafana alerting. If you wish, you can [opt-out]({{< relref "./opt-out.md" >}}) of Grafana alerting and roll back to legacy alerting. In that case, you can manage your legacy alerts from the alerting icon marked as legacy. | + +During migration from legacy alerting to unified alerting, the legacy alerts are updated to the new alerts type, as a result, the user does not lose alerts or alerting data. However, if a user rolls back to legacy alerting after having migrated to unified alerting, they will only get the legacy alerts they had right before migration. + +## Roll back to legacy alerting + +Although we encourage you to use Grafana alerting, roll back to legacy alerting is supported in Grafana 9. Rolling back can result in data loss (you will loose all alerts that you created using Grafana alerting). This is applicable to the fresh installation as well as upgraded setups. + +> **Note:** Legacy alerting will be deprecated in a future release (v10). diff --git a/docs/sources/alerting/migrating-legacy-alerts.md b/docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md similarity index 62% rename from docs/sources/alerting/migrating-legacy-alerts.md rename to docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md index 51dfd5ffac7..ee404f55a01 100644 --- a/docs/sources/alerting/migrating-legacy-alerts.md +++ b/docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md @@ -7,7 +7,9 @@ weight = 114 # Migrating legacy dashboard alerts -When Grafana alerting is enabled or Grafana is upgraded to the latest version, existing legacy dashboard alerts migrate in a format compatible with the Grafana alerting. In the Alerting page of your Grafana instance, you can view the migrated alerts alongside new alerts. +When Grafana alerting is enabled or Grafana is upgraded to the latest version, existing legacy dashboard alerts migrate in a format compatible with the Grafana alerting. In the Alerting page of your Grafana instance, you can view the migrated alerts alongside any new alerts. This topic explains how legacy dashboard alerts are migrated and some limitations. + +> **Note:** This topic is only relevant for OSS and Enterprise customers. Contact customer support to enable or disable Grafana alerting for your Cloud stack. Read and write access to legacy dashboard alerts and Grafana alerts are governed by the permissions of the folders storing them. During migration, legacy dashboard alert permissions are matched to the new rules permissions as follows: @@ -15,20 +17,9 @@ Read and write access to legacy dashboard alerts and Grafana alerts are governed - If there are no dashboard permissions and the dashboard is under a folder, then the rule is linked to this folder and inherits its permissions. - If there are no dashboard permissions and the dashboard is under the General folder, then the rule is linked to the `General Alerting` folder, and the rule inherits the default permissions. -> **Note:** Since there is no `Keep Last State` option for [`No Data`]({{< relref "./alerting-rules/create-grafana-managed-rule/#no-data--error-handling" >}}) in Grafana alerting, this option becomes `NoData` during the legacy rules migration. Option "Keep Last State" for [`Error handling`]({{< relref "./alerting-rules/create-grafana-managed-rule/#no-data--error-handling" >}}) is migrated to a new option `Error`. To match the behavior of the `Keep Last State`, in both cases, during the migration Grafana automatically creates a [silence]({{< relref "./silences/_index.md" >}}) for each alert rule with a duration of 1 year. +> **Note:** Since there is no `Keep Last State` option for [`No Data`]({{< relref "../alerting-rules/create-grafana-managed-rule/#no-data--error-handling" >}}) in Grafana alerting, this option becomes `NoData` during the legacy rules migration. Option "Keep Last State" for [`Error handling`]({{< relref "../alerting-rules/create-grafana-managed-rule/#no-data--error-handling" >}}) is migrated to a new option `Error`. To match the behavior of the `Keep Last State`, in both cases, during the migration Grafana automatically creates a [silence]({{< relref "../silences/_index.md" >}}) for each alert rule with a duration of 1 year. 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 Dashboard alert go to the `autogen-unlinked-channel-recv` route. Since `Hipchat` and `Sensu` notification channels are no longer supported, legacy alerts associated with these channels are not automatically migrated to Grafana alerting. Assign the legacy alerts to a supported notification channel so that you continue to receive notifications for those alerts. Silences (expiring after one year) are created for all paused dashboard alerts. - -## Disable Grafana alerts - -To disable Grafana alerts and enable legacy dashboard alerts: - -1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [Grafana alerting]({{< relref "../administration/configuration.md#unified_alerting" >}}) section. -1. Set the `enabled` property to `false`. -1. For [legacy dashboard alerting]({{< relref "../administration/configuration.md#alerting" >}}), set the `enabled` flag to `true`. -1. Restart Grafana for the configuration changes to take effect. - -> **Note:** Switching from one flavor of alerting to another can result in data loss. This is applicable to the fresh installation as well as upgraded setups. diff --git a/docs/sources/alerting/migrating-alerts/opt-out.md b/docs/sources/alerting/migrating-alerts/opt-out.md index b7756b6b1ff..e300e4b9e79 100644 --- a/docs/sources/alerting/migrating-alerts/opt-out.md +++ b/docs/sources/alerting/migrating-alerts/opt-out.md @@ -30,7 +30,12 @@ To opt-out of Grafana alerts and roll back to legacy dashboard alerting: When you are ready to make the switch, the following procedure will help you migrate to Grafana alerting. +<<<<<<< HEAD To opt-in to Grafana alerts: +======= +To opt-in Grafana alerts: + +> > > > > > > b5d48d217a (Docs: Created separate section for migration under alerting (#49616)) 1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [unified alerts]({{< relref "../../administration/configuration.md#unified_alerting" >}}) section. 1. Set the `enabled` property to `true`. diff --git a/docs/sources/alerting/opt-in.md b/docs/sources/alerting/opt-in.md deleted file mode 100644 index ca31f27b927..00000000000 --- a/docs/sources/alerting/opt-in.md +++ /dev/null @@ -1,41 +0,0 @@ -+++ -aliases = ["/docs/grafana/latest/alerting/opt-in/", "/docs/grafana/latest/alerting/unified-alerting/opt-in/"] -description = "Enable Grafana alerts" -title = "Opt-in to Grafana alerting" -weight = 113 -+++ - -# Opt-in to Grafana alerting in OSS - -Grafana alerting is enabled by default for new Cloud and OSS installations. - -- For existing OSS installations that use legacy dashboard alerts, unified alerting is still an opt-in feature. -- For existing Grafana Cloud users, contact customer support to enable Grafana alerting for your Cloud stack. - -## Before you begin - -We recommend that you backup Grafana's database. If you are using PostgreSQL as the backend database, then the minimum required version is 9.5. - -## Enable Grafana alerting - -To enable Grafana alerts: - -1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [unified alerts]({{< relref "../administration/configuration.md#unified_alerting" >}}) section. -2. Set the `enabled` property to `true`. -3. Next, for [legacy dashboard alerting]({{< relref "../administration/configuration.md#alerting" >}}), set the `enabled` flag to `false`. -4. Restart Grafana for the configuration changes to take effect. - -> **Note:** The `ngalert` toggle previously used to enable or disable Grafana alerting is no longer available. - -Before v8.2, notification logs and silences were stored on a disk. If you did not use persistent disks, you would have lost any configured silences and logs on a restart, resulting in unwanted or duplicate notifications. We no longer require the use of a persistent disk. Instead, the notification logs and silences are stored regularly (every 15 minutes). If you used the file-based approach, Grafana reads the existing file and persists it eventually. - -## Disable Grafana alerts - -To disable Grafana alerts and roll back to legacy dashboard alerting: - -1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [Grafana alerting]({{< relref "../administration/configuration.md#unified_alerting" >}}) section. -1. Set the `enabled` property to `false`. -1. For [legacy dashboard alerting]({{< relref "../administration/configuration.md#alerting" >}}), set the `enabled` flag to `true`. -1. Restart Grafana for the configuration changes to take effect. - -> **Note:** Switching from one flavor of alerting to another can result in data loss. This is applicable to the fresh installation as well as upgraded setups. diff --git a/docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md b/docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md index 71d56c6528b..70b9a852f15 100644 --- a/docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md +++ b/docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md @@ -80,7 +80,7 @@ The following tables list permissions associated with basic and fixed roles. ### Alerting roles -If alerting is [enabled]({{< relref "../../alerting/opt-in.md" >}}), you can use predefined roles to manage user access to alert rules, alert instances, and alert notification settings and create custom roles to limit user access to alert rules in a folder. +If alerting is [enabled]({{< relref "../../alerting/migrating-alerts/opt-in.md" >}}), you can use predefined roles to manage user access to alert rules, alert instances, and alert notification settings and create custom roles to limit user access to alert rules in a folder. Access to Grafana alert rules is an intersection of many permissions: diff --git a/docs/sources/whatsnew/whats-new-in-v9-0.md b/docs/sources/whatsnew/whats-new-in-v9-0.md index 58411e37263..abe9118b8ef 100644 --- a/docs/sources/whatsnew/whats-new-in-v9-0.md +++ b/docs/sources/whatsnew/whats-new-in-v9-0.md @@ -72,7 +72,7 @@ New new heatmap panel has a number enhancements compared to the old version. - For unbucketed data, it performs smarter auto bucket sizing - Supports filtering out bucket values close to but not exactly zero -The new heatmap by default assumes that the data is pre-bucked. So if your query returns time series each series is seen as separate bucket (y axis tick). The panel is so much faster than the old one so it can render many time series with thousands of data points each without issue. +The new heatmap by default assumes that the data is pre-bucketed. So if your query returns time series each series is seen as separate bucket (y axis tick). The panel is so much faster than the old one so it can render many time series with thousands of data points each without issue. {{< figure src="/static/img/docs/heatmap-panel/heatmap_with_time_series_light_theme.png" max-width="500px" caption="Heatmap panel with time series" >}} @@ -80,7 +80,7 @@ The new heatmap by default assumes that the data is pre-bucked. So if your query Unified alerting is now on by default if you upgrade from an earlier version of Grafana. If you have been using legacy alerting in an earlier version of Grafana and you upgrade to Grafana 9 your alert rules will be automatically migrated and the legacy alerting interface will be replaced by the unified alerting interface. -Unified alerting has been available since June, 2021, it now provides feature parity with legacy alerting and many additional benefits. To find out more on the process to revert back to legacy alerts if needed, click [here]({{< relref "../alerting/opt-in.md#disable-grafana-alertsd#" >}}). Note that if you do revert back (by setting the Grafana config flag GF_UNIFIED_ALERTING_ENABLED to false), that we expect to remove legacy alerting in the next major Grafana release, Grafana 10. +Unified alerting has been available since June, 2021, it now provides feature parity with legacy alerting and many additional benefits. To find out more on the process to revert back to legacy alerts if needed, click [here]({{< relref "../alerting/migrating-alerts/opt-out.md" >}}). Note that if you do revert back (by setting the Grafana config flag GF_UNIFIED_ALERTING_ENABLED to false), that we expect to remove legacy alerting in the next major Grafana release, Grafana 10. ### Alert state history for Grafana managed alerts