From 7e2870b7bb5c0f1be9f83429ac6c97ba896fa91d Mon Sep 17 00:00:00 2001 From: brendamuir <100768211+brendamuir@users.noreply.github.com> Date: Thu, 9 Jun 2022 20:12:41 +0200 Subject: [PATCH] Docs: Updates Grafana Alerting upgrade topics (#50533) * Updates Grafana Alerting upgrade topics * Run yarn prettier:write Co-authored-by: Armand Grillet --- docs/sources/alerting/_index.md | 2 +- .../alerting/migrating-alerts/_index.md | 32 ++++++------ .../migrating-alerts/disable-alerting.md | 23 +++++++++ .../migrating-legacy-alerts.md | 11 ++-- .../alerting/migrating-alerts/opt-in.md | 25 ++++++++++ .../alerting/migrating-alerts/opt-out.md | 50 ++++++++++--------- .../alerting/migrating-alerts/roll-back.md | 29 +++++++++++ docs/sources/alerting/performance.md | 2 +- .../setup-grafana/configure-grafana/_index.md | 2 +- 9 files changed, 132 insertions(+), 44 deletions(-) create mode 100644 docs/sources/alerting/migrating-alerts/disable-alerting.md create mode 100644 docs/sources/alerting/migrating-alerts/opt-in.md create mode 100644 docs/sources/alerting/migrating-alerts/roll-back.md diff --git a/docs/sources/alerting/_index.md b/docs/sources/alerting/_index.md index 9803ae16ed7..b8bf41fc564 100644 --- a/docs/sources/alerting/_index.md +++ b/docs/sources/alerting/_index.md @@ -8,7 +8,7 @@ weight: 114 # Grafana Alerting -Grafana alerts allow you to learn 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. It centralizes alerting information in a single, searchable view that allows you to: +Grafana Alerting allows you to learn 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. It centralizes alerting information in a single, searchable view that allows you to: - Create and manage Grafana alerts - Create and manage Grafana Mimir and Loki managed alerts diff --git a/docs/sources/alerting/migrating-alerts/_index.md b/docs/sources/alerting/migrating-alerts/_index.md index c2b1a057a0f..094038351c0 100644 --- a/docs/sources/alerting/migrating-alerts/_index.md +++ b/docs/sources/alerting/migrating-alerts/_index.md @@ -1,27 +1,31 @@ --- aliases: - /docs/grafana/latest/alerting/migrating-alerts/ -description: Migrate Grafana alerts -title: Migrate to Grafana Alerting -weight: 113 +description: Upgrade Grafana alerts +title: Upgrade to Grafana Alerting +weight: 101 --- -# Migrate to Grafana Alerting +# Upgrade 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. +Grafana Alerting is enabled by default for new installations or existing installations whether or not legacy alerting is configured. -Existing installations that upgrade to v9.0 will have Grafana Alerting enabled by default. +Existing installations that do not use legacy alerting will have Grafana Alerting enabled by default unless alerting is disabled in the configuration. -| 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/" >}}) 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/" >}}) 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. | +Likewise, existing installations that use legacy alerting will be automatically upgraded to Grafana Alerting unless you have [opted out]({{< relref "opt-out/" >}})of Grafana Alerting before migration takes place. During the upgrade, legacy alerts are migrated to the new alerts type and no alerts or alerting data are lost. -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. +Once the upgrade has taken place, you still have the option to roll back [roll back]({{< relref "roll-back/" >}}) to legacy alerting. However, we do not recommend choosing this option. If you do choose to roll back, Grafana will restore your alerts to the alerts you had at the point in time when the upgrade took place. All new alerts and changes made exclusively in Grafana Alerting will be deleted. -## Roll back to legacy alerting +> **Note**: Cloud customers, who do not want to upgrade to Grafana Alerting, should contact customer support. -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. +If you have opted out or rolled back, you can always choose to opt in [opt in]({{< relref "opt-in/" >}}) to Grafana Alerting at a later point in time. + +The following table provides details on the upgrade for Cloud, Enterprise, and OSS installations and the new Grafana Alerting UI. + +| Grafana instance upgraded to 9.0 | | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 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 and 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/" >}}) 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/" >}}) 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. | > **Note:** Legacy alerting will be deprecated in a future release (v10). diff --git a/docs/sources/alerting/migrating-alerts/disable-alerting.md b/docs/sources/alerting/migrating-alerts/disable-alerting.md new file mode 100644 index 00000000000..0f759504417 --- /dev/null +++ b/docs/sources/alerting/migrating-alerts/disable-alerting.md @@ -0,0 +1,23 @@ +--- +aliases: + - /docs/grafana/latest/alerting/migrating-alerts/disable-alerting/ + - /docs/grafana/latest/alerting/disable-alerting/ + - /docs/grafana/latest/alerting/unified-alerting/disable-alerting/ +description: Disable alerting in Grafana +title: Disable alerting in Grafana +weight: 105 +--- + +# Disable alerting in Grafana + +To disable alerting in Grafana entirely (including both legacy and Grafana Alerting), enter the following in your configuration: + +``` +[alerting] +enabled = false + +[unified_alerting] +enabled = false +``` + +If at any time you want to turn alerting back on, you can opt in. diff --git a/docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md b/docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md index e517e3e90fa..6a94dd9a459 100644 --- a/docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md +++ b/docs/sources/alerting/migrating-alerts/migrating-legacy-alerts.md @@ -4,13 +4,14 @@ aliases: - /docs/grafana/latest/alerting/migrating-legacy-alerts/ - /docs/grafana/latest/alerting/unified-alerting/opt-in/ description: Migrate legacy dashboard alerts -title: Migrating legacy dashboard alerts -weight: 114 +title: Differences and limitations +weight: 106 --- -# Migrating legacy dashboard alerts +# Differences and limitations -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. +When Grafana Alerting is enabled or upgraded to Grafana 9.0 or later, 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 of the migration. > **Note:** This topic is only relevant for OSS and Enterprise customers. Contact customer support to enable or disable Grafana Alerting for your Cloud stack. @@ -24,5 +25,7 @@ Read and write access to legacy dashboard alerts and Grafana alerts are governed 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. +## Limitations + 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. diff --git a/docs/sources/alerting/migrating-alerts/opt-in.md b/docs/sources/alerting/migrating-alerts/opt-in.md new file mode 100644 index 00000000000..00a62c2385b --- /dev/null +++ b/docs/sources/alerting/migrating-alerts/opt-in.md @@ -0,0 +1,25 @@ +--- +aliases: + - /docs/grafana/latest/alerting/migrating-alerts/opt-in/ + - /docs/grafana/latest/alerting/opt-in/ + - /docs/grafana/latest/alerting/unified-alerting/opt-in/ +description: Opt in to Grafana Alerting +title: Opt in to Grafana Alerting +weight: 104 +--- + +# Opt in to Grafana Alerting + +If you have previously disabled alerting in Grafana, or opted out of Grafana Alerting and have decided that you would now like to use Grafana Alerting, you can choose to opt in at any time. + +If you have been using legacy alerting up until now your existing alerts will be migrated to the new alerts type and no alerts or alerting data are lost. Even if you choose to opt in to Grafana Alerting, you can roll back to legacy alerting at any time. + +To opt in to Grafana Alerting, enter the following in your configuration: + +``` +[alerting] +enabled = false + +[unified_alerting] +enabled = true +``` diff --git a/docs/sources/alerting/migrating-alerts/opt-out.md b/docs/sources/alerting/migrating-alerts/opt-out.md index 72edb664d98..3c2ef5f0b1f 100644 --- a/docs/sources/alerting/migrating-alerts/opt-out.md +++ b/docs/sources/alerting/migrating-alerts/opt-out.md @@ -3,41 +3,45 @@ aliases: - /docs/grafana/latest/alerting/migrating-alerts/opt-out/ - /docs/grafana/latest/alerting/opt-in/ - /docs/grafana/latest/alerting/unified-alerting/opt-in/ -description: Disable Grafana alerts -title: Opt-out of Grafana Alerting -weight: 113 +description: Opt out of Grafana Alerting +title: Opt out of Grafana Alerting +weight: 102 --- -# Opt-out to Grafana Alerting in OSS +# Opt out of Grafana Alerting -This topic discusses how to disable Grafana Alerting and migrate to legacy dashboard alerting. It also provides guidance on how to enable Grafana Alerting once you are ready to migrate to Grafana Alerting. +If you have an existing installation, you can opt out of alerting in its entirety or opt out of Grafana Alerting in favor of using legacy alerting. -> **Note:** This topic is only relevant for OSS and Enterprise customers. Contact customer support to enable or disable Grafana Alerting for your Grafana Cloud stack. +Existing installations that do not use legacy alerting will have Grafana Alerting enabled by default unless alerting is disabled in the configuration. To keep alerting disabled: -## Before you begin +1. Go to your custom configuration file ($WORKING_DIR/conf/custom.ini). +1. Enter the following in your configuration: -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. +``` +[alerting] +enabled = false -## Opt-out of Grafana alerts +[unified_alerting] +enabled = false +``` -To opt-out of Grafana alerts and roll back to legacy dashboard alerting: +3. Restart Grafana for the configuration changes to take effect. -1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [Grafana Alerting]({{< relref "../../setup-grafana/configure-grafana/#unified_alerting" >}}) section. -1. Set the `enabled` property to `false`. -1. For [legacy dashboard alerting]({{< relref "../../setup-grafana/configure-grafana/#alerting" >}}), set the `enabled` flag to `true`. -1. Restart Grafana for the configuration changes to take effect. +If at any time you want to turn alerting back on, you can do so. -> **Note:** Rolling back from Grafana to legacy alerting can result in data loss. This is applicable to the fresh installation as well as upgraded setups. +Existing installations that use legacy alerting will automatically be upgraded to Grafana Alerting unless you have opted-out of Grafana Alerting before migration takes place. During the upgrade, legacy alerts are migrated to the new alerts type and no alerts or alerting data are lost. To keep using legacy alerting and disable Grafana Alerting: -## Opt-in to Grafana Alerting +1. Go to your custom configuration file ($WORKING_DIR/conf/custom.ini). +2. Enter the following in your configuration: -When you are ready to make the switch, the following procedure will help you migrate to Grafana Alerting. +``` +[alerting] +enabled = false -To opt-in to Grafana alerts: +[unified_alerting] +enabled = true +``` -1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [unified alerts]({{< relref "../../setup-grafana/configure-grafana/#unified_alerting" >}}) section. -1. Set the `enabled` property to `true`. -1. Next, for [legacy dashboard alerting]({{< relref "../../setup-grafana/configure-grafana/#alerting" >}}), set the `enabled` flag to `false`. -1. Restart Grafana for the configuration changes to take effect. +> **Note:** This topic is only relevant for OSS and Enterprise customers. Contact customer support to enable or disable Grafana Alerting for your Grafana Cloud stack. -> **Note:** The `ngalert` toggle previously used to enable or disable Grafana Alerting is no longer available. +The `ngalert` toggle previously used to enable or disable Grafana Alerting is no longer available. diff --git a/docs/sources/alerting/migrating-alerts/roll-back.md b/docs/sources/alerting/migrating-alerts/roll-back.md new file mode 100644 index 00000000000..319db9b3921 --- /dev/null +++ b/docs/sources/alerting/migrating-alerts/roll-back.md @@ -0,0 +1,29 @@ +--- +aliases: + - /docs/grafana/latest/alerting/migrating-alerts/roll-back/ + - /docs/grafana/latest/alerting/opt-in/ + - /docs/grafana/latest/alerting/unified-alerting/roll-back/ +description: Roll back to legacy alerting +title: Roll back to legacy alerting +weight: 103 +--- + +# Roll back to legacy alerting + +Once the upgrade has taken place, you still have the option to roll back to legacy alerting. If you choose to roll back, Grafana will restore your alerts to the alerts you had at the point in time when the upgrade took place. + +All new alerts and changes made exclusively in Grafana Alerting will be deleted. + +To roll back to legacy alerting, enter the following in your configuration: + +``` +force_migration = true + +[alerting] +enabled = true + +[unified_alerting] +enabled = false +``` + +> **Note**: We do not recommend this option. If you choose to roll back, Grafana will restore your alerts to the alerts you had at the point in time when the upgrade took place. All new alerts and changes made exclusively in Grafana Alerting will be deleted. diff --git a/docs/sources/alerting/performance.md b/docs/sources/alerting/performance.md index c4a2802e90f..3c1f4279034 100644 --- a/docs/sources/alerting/performance.md +++ b/docs/sources/alerting/performance.md @@ -2,7 +2,7 @@ title = "Performance considerations" description = "Understanding alerting performance" keywords = ["grafana", "alerting", "performance"] -weight = 100 +weight = 555 +++ # Alerting performance considerations diff --git a/docs/sources/setup-grafana/configure-grafana/_index.md b/docs/sources/setup-grafana/configure-grafana/_index.md index 55f95c700ca..ed821e6eddc 100644 --- a/docs/sources/setup-grafana/configure-grafana/_index.md +++ b/docs/sources/setup-grafana/configure-grafana/_index.md @@ -1189,7 +1189,7 @@ For more information about the Grafana alerts, refer to [About Grafana Alerting] ### enabled -Enable the Unified Alerting sub-system and interface. When enabled we'll migrate all of your alert rules and notification channels to the new system. New alert rules will be created and your notification channels will be converted into an Alertmanager configuration. Previous data is preserved to enable backwards compatibility but new data is removed. The default value is `false`. +Enable or disable Grafana Alerting. If enabled, we’ll migrate all your alert rules and notification channels to the new system as alert rules and notification channels you had previously defined will be converted into an Alertmanager configuration. Legacy alerting data is preserved to enable backwards compatibility. If disabled, all your legacy alerting data will be available again, but the data you created using Grafana Alerting will be deleted. Set force_migration=true to avoid deletion of data. The default value is `true`. Alerting Rules migrated from dashboards and panels will include a link back via the `annotations`.