Prepare your logic apps and runbooks for migration of classic alert rules
Note
As previously announced, classic alerts in Azure Monitor are retired for public cloud users, though still in limited use until 31 May 2021. Classic alerts for Azure Government cloud and Microsoft Azure operated by 21Vianet will retire on 29 February 2024.
If you choose to voluntarily migrate your classic alert rules to new alert rules, there are some differences between the two systems. This article explains those differences and how you can prepare for the change.
API changes
The APIs that create and manage classic alert rules (microsoft.insights/alertrules) are different from the APIs that create and manage new metric alerts (microsoft.insights/metricalerts). If you programmatically create and manage classic alert rules today, update your deployment scripts to work with the new APIs.
The following table is a reference to the programmatic interfaces for both classic and new alerts:
| Deployment script type | Classic alerts | New metric alerts |
|---|---|---|
| REST API | microsoft.insights/alertrules | microsoft.insights/metricalerts |
| Azure CLI | az monitor alert |
az monitor metrics alert |
| PowerShell | Reference | Reference |
| Azure Resource Manager template | For classic alerts | For new metric alerts |
Notification payload changes
The notification payload format is slightly different between classic alert rules and new metric alerts. If you have classic alert rules with webhook, logic app, or runbook actions, you must update the targets to accept the new payload format.
Use the following table to map the webhook payload fields from the classic format to the new format:
| Notification endpoint type | Classic alerts | New metric alerts |
|---|---|---|
| Was the alert activated or resolved? | status | data.status |
| Contextual information about the alert | context | data.context |
| Time stamp at which the alert was activated or resolved | context.timestamp | data.context.timestamp |
| Alert rule ID | context.id | data.context.id |
| Alert rule name | context.name | data.context.name |
| Description of the alert rule | context.description | data.context.description |
| Alert rule condition | context.condition | data.context.condition |
| Metric name | context.condition.metricName | data.context.condition.allOf[0].metricName |
| Time aggregation (how the metric is aggregated over the evaluation window) | context.condition.timeAggregation | context.condition.timeAggregation |
| Evaluation period | context.condition.windowSize | data.context.condition.windowSize |
| Operator (how the aggregated metric value is compared against the threshold) | context.condition.operator | data.context.condition.operator |
| Threshold | context.condition.threshold | data.context.condition.allOf[0].threshold |
| Metric value | context.condition.metricValue | data.context.condition.allOf[0].metricValue |
| Subscription ID | context.subscriptionId | data.context.subscriptionId |
| Resource group of the affected resource | context.resourceGroup | data.context.resourceGroup |
| Name of the affected resource | context.resourceName | data.context.resourceName |
| Type of the affected resource | context.resourceType | data.context.resourceType |
| Resource ID of the affected resource | context.resourceId | data.context.resourceId |
| Direct link to the portal resource summary page | context.portalLink | data.context.portalLink |
| Custom payload fields to be passed to the webhook or logic app | properties | data.properties |
The payloads are similar, as you can see. The following section offers:
- Details about modifying logic apps to work with the new format.
- A runbook example that parses the notification payload for new alerts.
Modify a logic app to receive a metric alert notification
If you're using logic apps with classic alerts, you must modify your logic-app code to parse the new metric alerts payload. Follow these steps:
Create a new logic app.
Use the template "Azure Monitor - Metrics Alert Handler". This template has an HTTP request trigger with the appropriate schema defined.
Add an action to host your processing logic.
Use an automation runbook that receives a metric alert notification
The following example provides PowerShell code to use in your runbook. This code can parse the payloads for both classic metric alert rules and new metric alert rules.
## Example PowerShell code to use in a runbook to handle parsing of both classic and new metric alerts.
[OutputType("PSAzureOperationResponse")]
param
(
[Parameter (Mandatory=$false)]
[object] $WebhookData
)
$ErrorActionPreference = "stop"
if ($WebhookData)
{
# Get the data object from WebhookData.
$WebhookBody = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)
# Determine whether the alert triggering the runbook is a classic metric alert or a new metric alert (depends on the payload schema).
$schemaId = $WebhookBody.schemaId
Write-Verbose "schemaId: $schemaId" -Verbose
if ($schemaId -eq "AzureMonitorMetricAlert") {
# This is the new metric alert schema.
$AlertContext = [object] ($WebhookBody.data).context
$status = ($WebhookBody.data).status
# Parse fields related to alert rule condition.
$metricName = $AlertContext.condition.allOf[0].metricName
$metricValue = $AlertContext.condition.allOf[0].metricValue
$threshold = $AlertContext.condition.allOf[0].threshold
$timeAggregation = $AlertContext.condition.allOf[0].timeAggregation
}
elseif ($schemaId -eq $null) {
# This is the classic metric alert schema.
$AlertContext = [object] $WebhookBody.context
$status = $WebhookBody.status
# Parse fields related to alert rule condition.
$metricName = $AlertContext.condition.metricName
$metricValue = $AlertContext.condition.metricValue
$threshold = $AlertContext.condition.threshold
$timeAggregation = $AlertContext.condition.timeAggregation
}
else {
# The schema is neither a classic metric alert nor a new metric alert.
Write-Error "The alert data schema - $schemaId - is not supported."
}
# Parse fields related to resource affected.
$ResourceName = $AlertContext.resourceName
$ResourceType = $AlertContext.resourceType
$ResourceGroupName = $AlertContext.resourceGroupName
$ResourceId = $AlertContext.resourceId
$SubId = $AlertContext.subscriptionId
## Your logic to handle the alert here.
}
else {
# Error
Write-Error "This runbook is meant to be started from an Azure alert webhook only."
}
For a full example of a runbook that stops a virtual machine when an alert is triggered, see the Azure Automation documenation.
Partner integration via webhooks
Most of our partners that integrate with classic alerts already support newer metric alerts through their integrations. Known integrations that already work with new metric alerts include:
If you're using a partner integration that's not listed here, confirm with the provider that they work with new metric alerts.