|
| 1 | +--- |
| 2 | +title: Upgrade legacy rules management to the current Azure Monitor Log Alerts API |
| 3 | +description: Learn how to switch to the log alerts management to ScheduledQueryRules API |
| 4 | +author: yanivlavi |
| 5 | +ms.author: yalavi |
| 6 | +ms.topic: conceptual |
| 7 | +ms.date: 2/23/2022 |
| 8 | +--- |
| 9 | +# Upgrade to the Log Alerts API from the legacy Log Analytics alerts API |
| 10 | + |
| 11 | +> [!IMPORTANT] |
| 12 | +> As [announced](https://azure.microsoft.com/updates/switch-api-preference-log-alerts/), the Log Analytics alert API will be retired on October 1, 2025. You must transition to using the Scheduled Query Rules API for log alerts by that date. |
| 13 | +> Log Analytics workspaces created after June 1, 2019 use the [scheduledQueryRules API](/rest/api/monitor/scheduledqueryrule-2021-08-01/scheduled-query-rules) to manage alert rules. [Switch to the current API](./alerts-log-api-switch.md) in older workspaces to take advantage of Azure Monitor scheduledQueryRules [benefits](./alerts-log-api-switch.md#benefits). |
| 14 | +> Once you migrate rules to the [scheduledQueryRules API](/rest/api/monitor/scheduledqueryrule-2021-08-01/scheduled-query-rules), you cannot revert back to the older [legacy Log Analytics Alert API](/azure/azure-monitor/alerts/api-alerts). |
| 15 | +
|
| 16 | +In the past, users used the [legacy Log Analytics Alert API](/azure/azure-monitor/alerts/api-alerts) to manage log alert rules. Currently workspaces use [ScheduledQueryRules API](/rest/api/monitor/scheduledqueryrule-2021-08-01/scheduled-query-rules) for new rules. This article describes the benefits and the process of switching legacy log alert rules management from the legacy API to the current API. |
| 17 | + |
| 18 | +## Benefits |
| 19 | + |
| 20 | +- Manage all log rules in one API. |
| 21 | +- Single template for creation of alert rules (previously needed three separate templates). |
| 22 | +- Single API for all Azure resources log alerting. |
| 23 | +- Support for stateful (preview) and 1-minute log alerts. |
| 24 | +- [PowerShell cmdlets](/azure/azure-monitor/alerts/alerts-manage-alerts-previous-version#manage-log-alerts-by-using-powershell) and [Azure CLI](/azure/azure-monitor/alerts/alerts-log#manage-log-alerts-using-cli) support for switched rules. |
| 25 | +- Alignment of severities with all other alert types and newer rules. |
| 26 | +- Ability to create a [cross workspace log alert](/azure/azure-monitor/logs/cross-workspace-query) that spans several external resources like Log Analytics workspaces or Application Insights resources for switched rules. |
| 27 | +- Users can specify dimensions to split the alerts for switched rules. |
| 28 | +- Log alerts have extended period of up to two days of data (previously limited to one day) for switched rules. |
| 29 | + |
| 30 | +## Impact |
| 31 | + |
| 32 | +- All switched rules must be created/edited with the current API. See [sample use via Azure Resource Template](/azure/azure-monitor/alerts/alerts-log-create-templates) and [sample use via PowerShell](/azure/azure-monitor/alerts/alerts-manage-alerts-previous-version#manage-log-alerts-by-using-powershell). |
| 33 | +- As rules become Azure Resource Manager tracked resources in the current API and must be unique, rules resource ID will change to this structure: `<WorkspaceName>|<savedSearchId>|<scheduleId>|<ActionId>`. Display names of the alert rule will remain unchanged. |
| 34 | + |
| 35 | +## Process |
| 36 | + |
| 37 | +View workspaces to upgrade using this [Azure Resource Graph Explorer query](https://portal.azure.com/?feature.customportal=false#blade/HubsExtension/ArgQueryBlade/query/resources%0A%7C%20where%20type%20%3D~%20%22microsoft.insights%2Fscheduledqueryrules%22%0A%7C%20where%20properties.isLegacyLogAnalyticsRule%20%3D%3D%20true%0A%7C%20distinct%20tolower%28properties.scopes%5B0%5D%29). Open the [link](https://portal.azure.com/?feature.customportal=false#blade/HubsExtension/ArgQueryBlade/query/resources%0A%7C%20where%20type%20%3D~%20%22microsoft.insights%2Fscheduledqueryrules%22%0A%7C%20where%20properties.isLegacyLogAnalyticsRule%20%3D%3D%20true%0A%7C%20distinct%20tolower%28properties.scopes%5B0%5D%29), select all available subscriptions, and run the query. |
| 38 | + |
| 39 | +The process of switching isn't interactive and doesn't require manual steps, in most cases. Your alert rules aren't stopped or stalled, during or after the switch. |
| 40 | +Do this call to switch all alert rules associated with each of the Log Analytics workspaces: |
| 41 | + |
| 42 | +``` |
| 43 | +PUT /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview |
| 44 | +``` |
| 45 | + |
| 46 | +With request body containing the below JSON: |
| 47 | + |
| 48 | +```json |
| 49 | +{ |
| 50 | + "scheduledQueryRulesEnabled" : true |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +Here is an example of using [ARMClient](https://github.com/projectkudu/ARMClient), an open-source command-line tool, that simplifies invoking the above API call: |
| 55 | + |
| 56 | +```powershell |
| 57 | +$switchJSON = '{"scheduledQueryRulesEnabled": true}' |
| 58 | +armclient PUT /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview $switchJSON |
| 59 | +``` |
| 60 | + |
| 61 | +You can also use [Azure CLI](/cli/azure/reference-index#az-rest) tool: |
| 62 | + |
| 63 | +```bash |
| 64 | +az rest --method put --url /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview --body "{\"scheduledQueryRulesEnabled\" : true}" |
| 65 | +``` |
| 66 | + |
| 67 | +If the switch is successful, the response is: |
| 68 | + |
| 69 | +```json |
| 70 | +{ |
| 71 | + "version": 2, |
| 72 | + "scheduledQueryRulesEnabled" : true |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +## Check switching status of workspace |
| 77 | + |
| 78 | +You can also use this API call to check the switch status: |
| 79 | + |
| 80 | +``` |
| 81 | +GET /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview |
| 82 | +``` |
| 83 | + |
| 84 | +You can also use [ARMClient](https://github.com/projectkudu/ARMClient) tool: |
| 85 | + |
| 86 | +```powershell |
| 87 | +armclient GET /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview |
| 88 | +``` |
| 89 | + |
| 90 | +You can also use [Azure CLI](/cli/azure/reference-index#az-rest) tool: |
| 91 | + |
| 92 | +```bash |
| 93 | +az rest --method get --url /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview |
| 94 | +``` |
| 95 | + |
| 96 | +If the Log Analytics workspace was switched to [scheduledQueryRules API](/rest/api/monitor/scheduledqueryrule-2021-08-01/scheduled-query-rules), the response is: |
| 97 | + |
| 98 | +```json |
| 99 | +{ |
| 100 | + "version": 2, |
| 101 | + "scheduledQueryRulesEnabled" : true |
| 102 | +} |
| 103 | +``` |
| 104 | +If the Log Analytics workspace wasn't switched, the response is: |
| 105 | + |
| 106 | +```json |
| 107 | +{ |
| 108 | + "version": 2, |
| 109 | + "scheduledQueryRulesEnabled" : false |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +## Next steps |
| 114 | + |
| 115 | +- Learn about the [Azure Monitor - Log Alerts](/azure/azure-monitor/alerts/alerts-unified-log). |
| 116 | +- Learn how to [manage your log alerts using the API](/azure/azure-monitor/alerts/alerts-log-create-templates). |
| 117 | +- Learn how to [manage log alerts using PowerShell](/azure/azure-monitor/alerts/alerts-manage-alerts-previous-version#manage-log-alerts-by-using-powershell). |
| 118 | +- Learn more about the [Azure Alerts experience](/azure/azure-monitor/alerts/alerts-overview). |
0 commit comments