Muokkaa

Jaa

Upgrade to the Scheduled Query Rules API from the legacy Log Analytics Alert API

  • Artikkeli

Important

As announced, the Log Analytics Alert API will be retired on October 1, 2025. You must transition to using the Scheduled Query Rules API for log search alerts by that date. Log Analytics workspaces created after June 1, 2019 use the scheduledQueryRules API to manage log search alert rules. Switch to the current API in older workspaces to take advantage of Azure Monitor scheduledQueryRules benefits. Once you migrate rules to the scheduledQueryRules API, you cannot revert back to the older legacy Log Analytics Alert API.

In the past, users used the legacy Log Analytics Alert API to manage log search alert rules. Currently workspaces use the Scheduled Query Rules API for new rules. This article describes the benefits and the process of switching legacy log search alert rules management from the legacy API to the current API.

Benefits

  • Manage all log search alert rules in one API.
  • Single template for creation of alert rules (previously needed three separate templates).
  • Single API for all Azure resources log alerting.
  • Support for stateful (preview) and 1-minute log search alerts.
  • PowerShell cmdlets and Azure CLI support for switched rules.
  • Alignment of severities with all other alert types and newer rules.
  • Ability to create a cross workspace log alert that spans several external resources like Log Analytics workspaces or Application Insights resources for switched rules.
  • Users can specify dimensions to split the alerts for switched rules.
  • Log search alerts have an extended period of up to two days of data (previously limited to one day) for switched rules.

Impact

  • All switched rules must be created/edited with the current API. See sample use via Azure Resource Template and sample use via PowerShell.
  • As rules become Azure Resource Manager tracked resources in the current API and must be unique, the resource IDs for the rules change to this structure: <WorkspaceName>|<savedSearchId>|<scheduleId>|<ActionId>. Display names for the alert rules remain unchanged.

Process

View workspaces to upgrade using this Azure Resource Graph Explorer query. Open the link, select all available subscriptions, and run the query.

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. Do this call to switch all alert rules associated with each of the Log Analytics workspaces:

PUT /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview

With request body containing the below JSON:

{
    "scheduledQueryRulesEnabled" : true
}

Here is an example of using ARMClient, an open-source command-line tool, that simplifies invoking the above API call:

$switchJSON = '{"scheduledQueryRulesEnabled": true}'
armclient PUT /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview $switchJSON

You can also use the Azure CLI tool:

az rest --method put --url /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview --body "{\"scheduledQueryRulesEnabled\" : true}"

If the switch is successful, the response is:

{
    "version": 2,
    "scheduledQueryRulesEnabled" : true
}

Check switching status of workspace

You can also use this API call to check the switch status:

GET /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview

You can also use the ARMClient tool:

armclient GET /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview

You can also use the Azure CLI tool:

az rest --method get --url /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>/alertsversion?api-version=2017-04-26-preview

If the Log Analytics workspace was switched to scheduledQueryRules API, the response is:

{
    "version": 2,
    "scheduledQueryRulesEnabled" : true
}

If the Log Analytics workspace wasn't switched, the response is:

{
    "version": 2,
    "scheduledQueryRulesEnabled" : false
}

Next steps