Merge pull request #73862 from eromanova97/OBSDOCS-158

OBSDOCS-158: Add severity and alert message in docs alerting rule exa…

Author: ousleyp

modules/monitoring-creating-alerting-rules-for-user-defined-projects.adoc

@@ -8,6 +8,13 @@
 
 You can create alerting rules for user-defined projects. Those alerting rules will trigger alerts based on the values of the chosen metrics.
 
+[NOTE]
+====
+* When you create an alerting rule, a project label is enforced on it even if a rule with the same name exists in another project.
+
+* To help users understand the impact and cause of the alert, ensure that your alerting rule contains an alert message and severity value.
+====
+
 .Prerequisites
 
 * You have enabled monitoring for user-defined projects.
@@ -18,12 +25,8 @@ You can create alerting rules for user-defined projects. Those alerting rules wi
 
 . Create a YAML file for alerting rules. In this example, it is called `example-app-alerting-rule.yaml`.
 
-. Add an alerting rule configuration to the YAML file. For example:
-+
-[NOTE]
-====
-When you create an alerting rule, a project label is enforced on it if a rule with the same name exists in another project.
-====
+. Add an alerting rule configuration to the YAML file.
+The following example creates a new alerting rule named `example-alert`. The alerting rule fires an alert when the `version` metric exposed by the sample service becomes `0`:
 +
 [source,yaml]
 ----
@@ -36,11 +39,17 @@ spec:
   groups:
   - name: example
     rules:
-    - alert: VersionAlert
-      expr: version{job="prometheus-example-app"} == 0
+    - alert: VersionAlert # <1>
+      expr: version{job="prometheus-example-app"} == 0 # <2>
+      labels:
+        severity: warning # <3>
+      annotations:
+        message: This is an example alert. # <4>
 ----
-+
-This configuration creates an alerting rule named `example-alert`. The alerting rule fires an alert when the `version` metric exposed by the sample service becomes `0`.
+<1> The name of the alerting rule you want to create.
+<2> The PromQL query expression that defines the new rule.
+<3> The severity assigned to the alert.
+<4> The message associated with the alert.
 
 . Apply the configuration file to the cluster:
 +

modules/monitoring-creating-new-alerting-rules.adoc

@@ -11,7 +11,9 @@ These alerting rules trigger alerts based on the values of chosen metrics.
 
 [NOTE]
 ====
-If you create a customized `AlertingRule` resource based on an existing platform alerting rule, silence the original alert to avoid receiving conflicting alerts.
+* If you create a customized `AlertingRule` resource based on an existing platform alerting rule, silence the original alert to avoid receiving conflicting alerts.
+
+* To help users understand the impact and cause of the alert, ensure that your alerting rule contains an alert message and severity value.
 ====
 
 .Prerequisites
@@ -24,7 +26,7 @@ If you create a customized `AlertingRule` resource based on an existing platform
 . Create a new YAML configuration file named `example-alerting-rule.yaml` in the `openshift-monitoring` namespace.
 
 . Add an `AlertingRule` resource to the YAML file.
-The following example creates a new alerting rule named `example`, similar to the default `watchdog` alert:
+The following example creates a new alerting rule named `example`, similar to the default `Watchdog` alert:
 +
 [source,yaml]
 ----
@@ -37,11 +39,17 @@ spec:
   groups:
   - name: example-rules
     rules:
-    - alert: ExampleAlert <1>
-      expr: vector(1) <2>
+    - alert: ExampleAlert # <1>
+      expr: vector(1) # <2>
+      labels:
+        severity: warning # <3>
+      annotations:
+        message: This is an example alert. # <4>
 ----
 <1> The name of the alerting rule you want to create.
 <2> The PromQL query expression that defines the new rule.
+<3> The severity assigned to the alert.
+<4> The message associated with the alert.
 
 . Apply the configuration file to the cluster:
 +