Alerting: Deprecate max_annotations_to_keep and max_annotation_age in [alerting] configuration section (#83266)

* introduce new config section [unified_alerting.state_history.annotations] and deprecate settings in [alerting]

Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>

conf/defaults.ini

@@ -1299,6 +1299,17 @@ loki_basic_auth_password =
 # ex.
 # mylabelkey = mylabelvalue
 
+[unified_alerting.state_history.annotations]
+# Controls retention of annotations automatically created while evaluating alert rules. 
+# Alert state history backend must be configured to be annotations (see setting [unified_alerting.state_history].backend).
+
+# Configures how long alert annotations are stored for. Default is 0, which keeps them forever.
+# This setting should be expressed as a duration. Ex 6h (hours), 10d (days), 2w (weeks), 1M (month).
+max_age =
+
+# Configures max number of alert annotations that Grafana stores. Default value is 0, which keeps all alert annotations.
+max_annotations_to_keep =
+
 [unified_alerting.upgrade]
 # If set to true when upgrading from legacy alerting to Unified Alerting, grafana will first delete all existing
 # Unified Alerting resources, thus re-upgrading all organizations from scratch. If false or unset, organizations that
@@ -1360,9 +1371,11 @@ min_interval_seconds = 1
 
 # Configures for how long alert annotations are stored. Default is 0, which keeps them forever.
 # This setting should be expressed as an duration. Ex 6h (hours), 10d (days), 2w (weeks), 1M (month).
+# Deprecated, use [annotations.alerting].max_age instead
 max_annotation_age =
 
 # Configures max number of alert annotations that Grafana stores. Default value is 0, which keeps all alert annotations.
+# Deprecated, use [annotations.alerting].max_annotations_to_keep instead
 max_annotations_to_keep =
 
 #################################### Annotations #########################

conf/sample.ini

@@ -1194,6 +1194,17 @@
 # Any number of label key-value-pairs can be provided.
 ; mylabelkey = mylabelvalue
 
+[unified_alerting.state_history.annotations]
+# This section controls retention of annotations automatically created while evaluating alert rules
+# when alerting state history backend is configured to be annotations (a setting [unified_alerting.state_history].backend
+
+# Configures for how long alert annotations are stored. Default is 0, which keeps them forever.
+# This setting should be expressed as an duration. Ex 6h (hours), 10d (days), 2w (weeks), 1M (month).
+max_age =
+
+# Configures max number of alert annotations that Grafana stores. Default value is 0, which keeps all alert annotations.
+max_annotations_to_keep =
+
 [unified_alerting.upgrade]
 # If set to true when upgrading from legacy alerting to Unified Alerting, grafana will first delete all existing
 # Unified Alerting resources, thus re-upgrading all organizations from scratch. If false or unset, organizations that
@@ -1233,9 +1244,11 @@
 
 # Configures for how long alert annotations are stored. Default is 0, which keeps them forever.
 # This setting should be expressed as a duration. Examples: 6h (hours), 10d (days), 2w (weeks), 1M (month).
+# Deprecated, use [annotations.alerting].max_age instead
 ;max_annotation_age =
 
 # Configures max number of alert annotations that Grafana stores. Default value is 0, which keeps all alert annotations.
+# Deprecated, use [annotations.alerting].max_annotations_to_keep instead
 ;max_annotations_to_keep =
 
 #################################### Annotations #########################

docs/sources/setup-grafana/configure-grafana/_index.md

@@ -1654,6 +1654,20 @@ For example: `disabled_labels=grafana_folder`
 
 <hr>
 
+## [unified_alerting.state_history.annotations]
+
+This section controls retention of annotations automatically created while evaluating alert rules when alerting state history backend is configured to be annotations (see setting [unified_alerting.state_history].backend)
+
+### max_age
+
+Configures for how long alert annotations are stored. Default is 0, which keeps them forever. This setting should be expressed as an duration. Ex 6h (hours), 10d (days), 2w (weeks), 1M (month).
+
+### max_annotations_to_keep
+
+Configures max number of alert annotations that Grafana stores. Default value is 0, which keeps all alert annotations.
+
+<hr>
+
 ## [unified_alerting.upgrade]
 
 For more information about upgrading to Grafana Alerting, refer to [Upgrade Alerting](/docs/grafana/next/alerting/set-up/migrating-alerts/).
@@ -1713,12 +1727,20 @@ Sets the minimum interval between rule evaluations. Default value is `1`.
 
 > **Note.** This setting has precedence over each individual rule frequency. If a rule frequency is lower than this value, then this value is enforced.
 
-### max_annotation_age =
+### max_annotation_age
+
+{{% admonition type="note" %}}
+This option is deprecated - See `max_age` option in [unified_alerting.state_history.annotations]({{< relref "#unified_alertingstate_historyannotations" >}}) instead.
+{{% /admonition %}}
 
 Configures for how long alert annotations are stored. Default is 0, which keeps them forever.
 This setting should be expressed as a duration. Examples: 6h (hours), 10d (days), 2w (weeks), 1M (month).
 
-### max_annotations_to_keep =
+### max_annotations_to_keep
+
+{{% admonition type="note" %}}
+This option is deprecated - See `max_annotations_to_keep` option in [unified_alerting.state_history.annotations]({{< relref "#unified_alertingstate_historyannotations" >}}) instead.
+{{% /admonition %}}
 
 Configures max number of alert annotations that Grafana stores. Default value is 0, which keeps all alert annotations.
 

pkg/setting/setting.go

@@ -702,7 +702,6 @@ func (cfg *Cfg) readAnnotationSettings() error {
 
 	dashboardAnnotation := cfg.Raw.Section("annotations.dashboard")
 	apiIAnnotation := cfg.Raw.Section("annotations.api")
-	alertingSection := cfg.Raw.Section("alerting")
 
 	var newAnnotationCleanupSettings = func(section *ini.Section, maxAgeField string) AnnotationCleanupSettings {
 		maxAge, err := gtime.ParseDuration(section.Key(maxAgeField).MustString(""))
@@ -716,7 +715,18 @@ func (cfg *Cfg) readAnnotationSettings() error {
 		}
 	}
 
-	cfg.AlertingAnnotationCleanupSetting = newAnnotationCleanupSettings(alertingSection, "max_annotation_age")
+	alertingAnnotations := cfg.Raw.Section("unified_alerting.state_history.annotations")
+	if alertingAnnotations.Key("max_age").Value() == "" && section.Key("max_annotations_to_keep").Value() == "" {
+		alertingSection := cfg.Raw.Section("alerting")
+		cleanup := newAnnotationCleanupSettings(alertingSection, "max_annotation_age")
+		if cleanup.MaxCount > 0 || cleanup.MaxAge > 0 {
+			cfg.Logger.Warn("settings 'max_annotations_to_keep' and 'max_annotation_age' in section [alerting] are deprecated. Please use settings 'max_annotations_to_keep' and 'max_age' in section [unified_alerting.state_history.annotations]")
+		}
+		cfg.AlertingAnnotationCleanupSetting = cleanup
+	} else {
+		cfg.AlertingAnnotationCleanupSetting = newAnnotationCleanupSettings(alertingAnnotations, "max_age")
+	}
+
 	cfg.DashboardAnnotationCleanupSettings = newAnnotationCleanupSettings(dashboardAnnotation, "max_age")
 	cfg.APIAnnotationCleanupSettings = newAnnotationCleanupSettings(apiIAnnotation, "max_age")