Merge pull request #235086 from AbbyMSFT/custom-properties

Add custom properties to alert payload

Author: JamesJBarnett

articles/azure-monitor/alerts/alerts-common-schema.md

@@ -12,7 +12,7 @@ ms.author: abbyweisberg
 
 The common alert schema standardizes the consumption of Azure Monitor alert notifications. Historically, activity log, metric, and log alerts each had their own email templates and webhook schemas. The common alert schema provides one standardized schema for all alert notifications. 
 
-A standardized schema can help you minimize the number of integrations, which simplifies the process of managing and maintaining your integrations.
+Using a standardized schema helps minimize the number of integrations, which simplifies the process of managing and maintaining your integrations. The common schema enables a richer alert consumption experience in both the Azure portal and the Azure mobile app.
 
 The common alert schema provides a consistent structure for:
 - **Email templates**: Use the detailed email template to diagnose issues at a glance. Embedded links to the alert instance on the portal and to the affected resource ensure that you can quickly jump into the remediation process. 
@@ -21,8 +21,6 @@ The common alert schema provides a consistent structure for:
     - Azure Functions
     - Azure Automation runbook
 
-The new schema enables a richer alert consumption experience in both the Azure portal and the Azure mobile app.
-
 > [!NOTE]
 > Alerts generated by [VM insights](../vm/vminsights-overview.md) do not support the common schema.
 
@@ -33,9 +31,10 @@ The common schema includes information about the affected resource and the cause
 
     If you want to route alert instances to specific teams based on criteria such as a resource group, you can use the fields in the **Essentials** section to provide routing logic for all alert types. The teams that receive the alert notification can then use the context fields for their investigation.
 - **Alert context**: Fields that vary depending on the type of the alert. The alert context fields describe the cause of the alert. For example, a metric alert would have fields like the metric name and metric value in the alert context. An activity log alert would have information about the event that generated the alert.
-- **Custom Properties**: A “key: value” object, defined in the alert rule and added to the webhook notifications. 
-If the custom properties are not set in the Alert rule, this field will be null.  Note: today this is only supported for Metric Alerts other alert types will contain null in this field.
+- **Custom properties**: You can add more information to the alert payload by adding custom properties if you've configured action groups for a metric alert rule. 
 
+    > [!NOTE]
+    > Custom properties are currently only supported by metric alerts. For all other alert types, the **custom properties** field is null.
 ## Sample alert payload
 
 ```json
@@ -105,7 +104,7 @@ For sample alerts that use the common schema, see [Sample alert payloads](alerts
 | monitorCondition | When an alert fires, the alert's monitor condition is set to **Fired**. When the underlying condition that caused the alert to fire clears, the monitor condition is set to **Resolved**.   |
 | monitoringService | The monitoring service or solution that generated the alert. The monitoring service determines which fields are in the alert context. |
 | alertTargetIds | The list of the Azure Resource Manager IDs that are affected targets of an alert. For a log alert defined on a Log Analytics workspace or Application Insights instance, it's the respective workspace or application. |
-| configurationItems |The list of affected resources of an alert.<br>In some cases, the configuration items can be different from the alert targets. For example, in metric-for-log or log alerts defined on a Log Analytics workspace, the configuration items are the actual resources sending the telemetry and not the workspace.<br><ul><li>In the log alerts API (Scheduled Query Rules) v2021-08-01, the `configurationItem` values are taken from explicitly defined dimensions in this priority: `Computer`, `_ResourceId`, `ResourceId`, `Resource`.</li><li>In earlier versions of the log alerts API, the `configurationItem` values are taken implicitly from the results in this priority: `Computer`, `_ResourceId`, `ResourceId`, `Resource`.</li></ul>In ITSM systems, the `configurationItems` field is used to correlate alerts to resources in a configuration management database. |
+| configurationItems |The list of affected resources of an alert.<br>In some cases, the configuration items can be different from the alert targets. For example, in metric-for-log or log alerts defined on a Log Analytics workspace, the configuration items are the actual resources sending the data, and not the workspace.<br><ul><li>In the log alerts API (Scheduled Query Rules) v2021-08-01, the `configurationItem` values are taken from explicitly defined dimensions in this priority: `Computer`, `_ResourceId`, `ResourceId`, `Resource`.</li><li>In earlier versions of the log alerts API, the `configurationItem` values are taken implicitly from the results in this priority: `Computer`, `_ResourceId`, `ResourceId`, `Resource`.</li></ul>In ITSM systems, the `configurationItems` field is used to correlate alerts to resources in a configuration management database. |
 | originAlertId | The ID of the alert instance, as generated by the monitoring service generating it. |
 | firedDateTime | The date and time when the alert instance was fired in Coordinated Universal Time (UTC). |
 | resolvedDateTime | The date and time when the monitor condition for the alert instance is set to **Resolved** in UTC. Currently only applicable for metric alerts.|
@@ -124,7 +123,7 @@ For sample alerts that use the common schema, see [Sample alert payloads](alerts
 |windowSize           |The time period analyzed by the alert rule.|
 |allOf                |Indicates that all conditions defined in the alert rule must be met to trigger an alert.|
 |alertSensitivity     |In an alert rule with a dynamic threshold, indicates how sensitive the rule is, or how much the value can deviate from the upper or lower threshold.|
-|failingPeriods       |In an alert rule with a dynamic threshold, the number of evaluation periods that don't meet the alert threshold that will trigger an alert. For example, you can indicate that an alert is triggered when 3 out of the last five evaluation periods aren't within the alert thresholds. |
+|failingPeriods       |In an alert rule with a dynamic threshold, the number of evaluation periods that don't meet the alert threshold that trigger an alert. For example, you can indicate that an alert is triggered when 3 out of the last five evaluation periods aren't within the alert thresholds. |
 |numberOfEvaluationPeriods|The total number of evaluations.         |
 |minFailingPeriodsToAlert|The minimum number of evaluations that do no meet the alert rule conditions.|
 |ignoreDataBefore     |(Optional.) In an alert rule with a dynamic threshold, the date from which the threshold is calculated. Use this value to indicate that the rule shouldn't calculate the dynamic threshold using data from before the specified date. |
@@ -140,6 +139,7 @@ For sample alerts that use the common schema, see [Sample alert payloads](alerts
 |webTestName          |If the condition type is `webtest`, the name of the webtest.         |
 |windowStartTime      |The start time of the evaluation window in which the alert fired.       |
 |windowEndTime        |The end time of the evaluation window in which the alert fired.         |
+|customProperties     ||
 
 ### Sample metric alert with a static threshold when the monitoringService = `Platform`
 
@@ -673,6 +673,16 @@ See [Azure Monitor managed service for Prometheus rule groups (preview)](../esse
   }
 }
 ```
+## Custom properties fields
+
+If you've configured action groups for a metric alert rule, you can add more information to the alert payload by adding custom properties.
+
+The custom properties section contains “key: value” objects that are added to webhook notifications. 
+
+If custom properties aren't set in the alert rule, the field is null.
+
+> [!NOTE]
+> Custom properties are currently only supported by metric alerts. For all other alert types, the **custom properties** field is null.
 ## Enable the common alert schema
 
 Use action groups in the Azure portal or use the REST API to enable the common alert schema. Schemas are defined at the action level. For example, you must separately enable the schema for an email action and a webhook action.

articles/azure-monitor/alerts/alerts-create-new-alert-rule.md

@@ -17,10 +17,11 @@ You create an alert rule by combining:
  - The signal or telemetry from the resource.
  - Conditions.
 
-Then you define these elements for the resulting alert actions by using:
+You then define these elements for the resulting alert actions by using:
  - [Alert processing rules](alerts-action-rules.md)
  - [Action groups](./action-groups.md)
 
+Alerts triggered by these alert rules contain a payload that uses the [common alert schema](alerts-common-schema.md).
 ## Create a new alert rule in the Azure portal
 
 1. In the [portal](https://portal.azure.com/), select **Monitor** > **Alerts**.

articles/azure-monitor/alerts/alerts-overview.md

@@ -18,17 +18,15 @@ This diagram shows you how alerts work.
 
 :::image type="content" source="media/alerts-overview/alerts.png"  alt-text="Diagram that explains Azure Monitor alerts." lightbox="media/alerts-overview/alerts.png":::
 
-An *alert rule* monitors your telemetry and captures a signal that indicates something is happening on the specified resource. The alert rule captures the signal and checks to see if the signal meets the criteria of the condition. If the conditions are met, an alert is triggered, which initiates the associated action group and updates the state of the alert.
+An *alert rule* monitors your data and captures a signal that indicates something is happening on the specified resource. The alert rule captures the signal and checks to see if the signal meets the criteria of the condition. If the conditions are met, an alert is triggered, which initiates the associated action group and updates the state of the alert.
 
 An alert rule combines:
  - The resources to be monitored.
- - The signal or telemetry from the resource.
+ - The signal or data from the resource.
  - Conditions.
 
 If you're monitoring more than one resource, the condition is evaluated separately for each of the resources. Alerts are fired for each resource separately.
 
-After an alert is triggered, the alert is made up of:
- - **Alert processing rules**: You can use these rules to apply processing on fired alerts. Alert processing rules modify the fired alerts as they're being fired. You can use alert processing rules to add or suppress action groups, apply filters, or have the rule processed on a predefined schedule.
  - **Action groups**: These groups can trigger notifications or an automated workflow to let users know that an alert has been triggered. Action groups can include:
      - Notification methods, such as email, SMS, and push notifications.
      - Automation runbooks.
@@ -40,9 +38,9 @@ After an alert is triggered, the alert is made up of:
      - Event hubs.
 - **Alert conditions**: These conditions are set by the system. When an alert fires, the alert's monitor condition is set to **fired**. After the underlying condition that caused the alert to fire clears, the monitor condition is set to **resolved**.
 - **User response**: The response is set by the user and doesn't change until the user changes it.
+- **Alert processing rules**: You can use alert processing rules to make modifications to triggered alerts as they're being fired. You can use alert processing rules to add or suppress action groups, apply filters, or have the rule processed on a predefined schedule.
 
 You can see all alert instances in all your Azure resources generated in the last 30 days on the [Alerts page](alerts-page.md) in the Azure portal.
-
 ## Types of alerts
 
 This table provides a brief description of each alert type. For more information about each alert type and how to choose which alert type best suits your needs, see [Types of Azure Monitor alerts](alerts-types.md).
@@ -54,15 +52,14 @@ This table provides a brief description of each alert type. For more information
 |[Activity log alerts](alerts-types.md#activity-log-alerts)|Activity log alerts are triggered when a new activity log event occurs that matches defined conditions. Resource Health alerts and Service Health alerts are activity log alerts that report on your service and resource health.|
 |[Smart detection alerts](alerts-types.md#smart-detection-alerts)|Smart detection on an Application Insights resource automatically warns you of potential performance problems and failure anomalies in your web application. You can migrate smart detection on your Application Insights resource to create alert rules for the different smart detection modules.|
 |[Prometheus alerts (preview)](alerts-types.md#prometheus-alerts-preview)|Prometheus alerts are used for alerting on the performance and health of Kubernetes clusters, including Azure Kubernetes Service (AKS). The alert rules are based on PromQL, which is an open-source query language.|
-
 ## Recommended alert rules
 
 If you don't have alert rules defined for the selected resource, you can [enable recommended out-of-the-box alert rules in the Azure portal](alerts-manage-alert-rules.md#enable-recommended-alert-rules-in-the-azure-portal).
 
 The system compiles a list of recommended alert rules based on:
 
 - The resource provider’s knowledge of important signals and thresholds for monitoring the resource.
-- Telemetry that tells us what customers commonly alert on for this resource.
+- Data that tells us what customers commonly alert on for this resource.
 
 > [!NOTE]
 > Recommended alert rules is enabled for:
@@ -102,7 +99,6 @@ You can configure whether log or metric alerts are stateful or stateless. Activi
     |Log alerts| The alert condition isn't met for a specific time range. The time range differs based on the frequency of the alert:<ul> <li>**1 minute**: The alert condition isn't met for 10 minutes.</li> <li>**5 to 15 minutes**: The alert condition isn't met for three frequency periods.</li> <li>**15 minutes to 11 hours**: The alert condition isn't met for two frequency periods.</li> <li>**11 to 12 hours**: The alert condition isn't met for one frequency period.</li></ul>|
 
 When an alert is considered resolved, the alert rule sends out a resolved notification by using webhooks or email. The monitor state in the Azure portal is set to **resolved**.
-
 ## Pricing
 For information about pricing, see [Azure Monitor pricing](https://azure.microsoft.com/pricing/details/monitor/).
 

articles/azure-monitor/alerts/alerts-payload-samples.md

@@ -19,6 +19,10 @@ The common schema includes information about the affected resource and the cause
 
     If you want to route alert instances to specific teams based on criteria such as a resource group, you can use the fields in the **Essentials** section to provide routing logic for all alert types. The teams that receive the alert notification can then use the context fields for their investigation.
 - **Alert context**: Fields that vary depending on the type of the alert. The alert context fields describe the cause of the alert. For example, a metric alert would have fields like the metric name and metric value in the alert context. An activity log alert would have information about the event that generated the alert.
+- **Custom properties**: You can add more information to the alert payload by adding custom properties if you've configured action groups for a metric alert rule. 
+
+    > [!NOTE]
+    > Custom properties are currently only supported by metric alerts. For all other alert types, the **custom properties** field is null.
 
 ## Sample alert payload
 

articles/azure-monitor/alerts/alerts-processing-rules.md

@@ -15,7 +15,7 @@ ms.reviewer: ofmanor
 > [!NOTE]
 > Alert processing rules were previously known as 'action rules'. For backward compatibility, the Azure resource type of these rules is still **Microsoft.AlertsManagement/actionRules** .
 
-Alert processing rules allow you to apply processing on fired alerts. Alert processing rules are different from alert rules. Alert rules generate new alerts, while alert processing rules  modify the fired alerts as they're being fired.
+Alert processing rules allow you to apply processing on fired alerts. Alert processing rules are different from alert rules. Alert rules generate new alerts, while alert processing rules modify the fired alerts as they're being fired.
 
 You can use alert processing rules to add [action groups](./action-groups.md) or remove (suppress) action groups from your fired alerts. You can apply alert processing rules to different resource scopes, from a single resource, or to an entire subscription. You can also use them to apply various filters or have the rule work on a predefined schedule.