Switch API preference for Log Alerts

Note

Content stated applicable to users Azure public cloud only and not for Azure Government or Azure China cloud.

Until recently, you managed alert rules in the Microsoft Operations Management Suite portal. The new alerts experience was integrated with various services in Microsoft Azure including Log Analytics and we asked to extend your alert rules from OMS portal to Azure. But to ensure minimal disruption for customers, the process did not alter the programmatic interface for its consumption - Log Analytics Alert API based on SavedSearch.

But now you announce for Log Analytics alerting users a true Azure programmatic alternative, Azure Monitor - ScheduledQueryRules API, which is also reflective in your Azure billing - for log alerts. To learn more on how to manage your log alerts using the API, see Managing log alerts using Azure Resource Template and Managing log alerts using PowerShell.

Benefits of switching to new Azure API

There are several advantages of creating and managing alerts using scheduledQueryRules API over legacy Log Analytics Alert API; we have listed some of the major ones below:

  • Ability to cross workspace log search in alert rules and span up external resources like Log Analytics workspaces or even Application Insights apps
  • When multiple fields used to Group in query, using scheduledQueryRules API user can specify which field to aggregate-on in Azure portal
  • Log alerts created using scheduledQueryRules API can have period defined up to 48 hours and fetch data for longer period than before
  • Create alert rules in one shot as a single resource without the need to create three levels of resources as with legacy Log Analytics Alert API
  • Single programmatic interface for all variants of query-based log alerts in Azure - new scheduledQueryRules API can be used to manage rules for Log Analytics as well as Application Insights
  • Manage your log alerts using Powershell cmdlets
  • All new log alert functionality and future development will be available only via the new scheduledQueryRules API

Process of switching from legacy Log Alerts API

Users are free to use either legacy Log Analytics Alert API or the new scheduledQueryRules API. Alert rules created by either API, will be manageable by the same API only - as well as from Azure portal. By default, Azure Monitor will continue to use legacy Log Analytics Alert API for creating any new alert rule from Azure portal for existing workspaces of Log Analytics. As announced new Log workspace created on or after June 1, 2019 - will automatically use new scheduledQueryRules API by default including in Azure portal.

The impacts of the switch of preference to scheduledQueryRules API are compiled below:

The process of moving alert rules from legacy Log Analytics Alert API does not involve changing your alert definition, query, or configuration in any way. Your alert rules and monitoring are unaffected and the alerts will not stop or be stalled, during or after the switch. The only change is a change in API preference and access to your rules via a new API.

Note

Once a user opts to switch preference to the new scheduledQueryRules API, the you cannot opt back or revert to using of the older legacy Log Analytics Alert API.

Any customer who wishes to switch voluntarily to the new scheduledQueryRules and block usage from the legacy Log Analytics Alert API; can do so by performing a PUT call on the below API to switch all alert rules associated with the specific Log Analytics workspace.

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
}

The API can also be accessed from a PowerShell command line using ARMClient, an open-source command-line tool that simplifies invoking the Azure Resource Manager API. As illustrated below, in sample PUT call using ARMclient tool to switch all alert rules associated with the specific Log Analytics workspace.

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

If switch of all alert rules in the Log Analytics workspace to use new scheduledQueryRules is successful, the following response will be provided.

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

Users can also check the current status of your Log Analytics workspace and see if it has or has not been switched to use scheduledQueryRules only. To check, users can perform a GET call on the below API.

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

To execute the above in using PowerShell command line using ARMClient tool, see the sample below.

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

If the specified Log Analytics workspace has been switched to use scheduledQueryRules only; then the response JSON will be as listed below.

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

Else, if the specified Log Analytic workspace has not yet been switched to use scheduledQueryRules only; then the response JSON will be as listed below.

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

Next steps