Create query-based metric alerts (Preview)

This article explains how to create query-based metric alert rules in Azure Monitor using PromQL, covering prerequisites, rule configuration options, managed identity requirements, deployment methods, and how to view and manage alerts in the Azure portal.

Prerequisites

Read the query based metric alerts overview.
A system-assigned or user-assigned managed identity. To use a user-assigned managed identity with your query-based metric alert rules, create the managed identity in advance and configure it with Monitoring Reader role (or equivalent permissions) on the rule scope. For more information about creating and using managed identities, see Azure managed identities.
A resource emitting Prometheus or OTel-based metrics to an Azure Monitor Workspace (AMW). The resources currently supported are Azure Kubernetes Service (AKS), Azure virtual machines, Arc-enabled servers or Arc-enabled clusters. Custom OTel metrics emitted directly to AMW by your workload are also supported. For more information, see:
- Enable Azure Monitor managed service for Prometheus.
- Enable Prometheus and Grafana for details.
To create resource-centric alert rules, your Azure Monitor Workspace must be enabled for resource-centric stamping and access.

Enable workspace resource-centric stamping and access

Enable resource-centric stamping and access for a workspace by using one of the following methods:

The following Azure CLI example uses az rest to call the Azure Monitor Workspaces - Create Or Update REST API operation.

# Set variables
resourceGroupName="<ResourceGroupName>"
accountName="<AccountName>"
apiVersion="<ApiVersion>"
payloadFile="./enable-stamping.json"

# Get the subscription ID from the current Azure CLI context
subscriptionId=$(az account show --query id --output tsv)

# Build the full resource ID for the Azure Monitor workspace
path="/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName"
provider="Microsoft.Monitor/accounts/$accountName"
url="$path/providers/$provider"

# Enable resource-centric stamping and access
az rest --method put --url "$url?api-version=$apiVersion" --body "@$payloadFile"

Payload file (enable-stamping.json):

{
  "location": "<Location>",
  "properties": {
    "metrics": {
      "enableAccessUsingResourcePermissions": true
    }
  }
}

The following Azure PowerShell example uses Invoke-AzRestMethod to call the Azure Monitor Workspaces - Create Or Update REST API operation.

# Set variables
$resourceGroupName = "<ResourceGroupName>"
$accountName = "<AccountName>"
$apiVersion = "<ApiVersion>"
$payloadFile = "./enable-stamping.json"

# Get the subscription ID from the current Azure PowerShell context
$subscriptionId = (Get-AzContext).Subscription.Id

# Build request URL
$apiEndpoint = "https://management.azure.com"
$path = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName"
$provider = "Microsoft.Monitor/accounts/$accountName"
$queryString = "?api-version=$apiVersion"
$url = "$apiEndpoint$path/providers/$provider$queryString"

# Send request
$invokeAzRestMethodParams = @{
    Method  = "PUT"
    Uri     = $url
    Payload = Get-Content -Raw -Path $payloadFile
}

Invoke-AzRestMethod @invokeAzRestMethodParams

Payload file (enable-stamping.json):

{
  "location": "<Location>",
  "properties": {
    "metrics": {
      "enableAccessUsingResourcePermissions": true
    }
  }
}

The following REST example uses the Azure Monitor Workspaces - Create Or Update REST API operation.

PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.Monitor/accounts/{AccountName}?api-version={apiVersion}
Authorization: Bearer {AccessToken}
Content-Type: application/json

{
  "location": "<Location>",
  "properties": {
    "metrics": {
      "enableAccessUsingResourcePermissions": true
    }
  }
}

Note

Template deployments are create-or-update operations. Deploying this template updates the existing Azure Monitor Workspace rather than applying a partial change.

The following Bicep example uses the Microsoft.Monitor accounts resource type.

param accountName string = '<AccountName>'
param location string = '<Location>'

resource monitorWorkspace 'Microsoft.Monitor/accounts@<ApiVersion>' = {
  name: accountName
  location: location
  properties: {
    metrics: {
      enableAccessUsingResourcePermissions: true
    }
  }
}

Note

Template deployments are create-or-update operations. Deploying this template updates the existing Azure Monitor Workspace rather than applying a partial change.

The following ARM template example uses the Microsoft.Monitor accounts resource type.

Enable resource-centric stamping and access on an Azure Monitor workspace

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "accountName": {
      "type": "string",
      "defaultValue": "<AccountName>"
    },
    "location": {
      "type": "string",
      "defaultValue": "<Location>"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Monitor/accounts",
      "apiVersion": "<ApiVersion>",
      "name": "[parameters('accountName')]",
      "location": "[parameters('location')]",
      "properties": {
        "metrics": {
          "enableAccessUsingResourcePermissions": true
        }
      }
    }
  ]
}

Deploy a query-based metric alert

Create and configure query-based metric alert rules by using the Azure portal or one of the programmatic approaches in this section. The REST, Azure CLI, and Azure PowerShell examples use direct REST requests to create or update the alert rule, while the Bicep and ARM template examples use deployment templates.

The examples in this section create a resource-centric, query-based metric alert rule that uses an Azure Kubernetes Service (AKS) cluster as its scope and a user-assigned managed identity. The following sections describe some of the required properties and configuration options. Edit the examples to use your own scope, location, query, action groups, and other values.

Note

In the Azure portal, select only one resource type at a time. For example, you can't select virtual machines and Kubernetes services.

From the Create an alert rule page:

Select Select scope. The Select a resource screen appears.
From the Subscription dropdown list, select one or more subscriptions checkboxes. All resource groups within that chosen subscription appear.
From the Resource types dropdown list, filter for Virtual machines, Azure Monitor Workspaces, Kubernetes services or choose an entire resource group or subscription.
Select the checkbox next to the resources you want to use.
Select Apply.
Select Next: Condition or the Condition tab.
From the Signal dropdown list, either:
- See all signals to use a previously created PromQL query, then select the query you want to use. The PromQL field appears populated with the query. Then, continue to edit the query in the editor field.
- Custom PromQL query to create a new one. The PromQL field appears empty and ready for your query editing. Enter the PromQL query in the field.
Select the Alerting options:
1. From the Check every dropdown list, select the checking interval.
2. From the Wait for dropdown list, select the delay time for the alert. Default is no delay.
From here, configure the alert as you would any other alert. See the other alert creation guides in the documentation.

The following Azure CLI example uses az rest to call the Metric Alerts - Create Or Update REST API operation.

# Set variables
resourceGroupName="<ResourceGroupName>"
ruleName="<RuleName>"
apiVersion="<ApiVersion>"
payloadFile="./query-based-metric-alert.json"

# Get the subscription ID from the current Azure CLI context
subscriptionId=$(az account show --query id --output tsv)

# Build the full resource ID for the metric alert rule
path="/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName"
provider="Microsoft.Insights/metricAlerts/$ruleName"
url="$path/providers/$provider"

# Create the query-based metric alert rule
az rest --method put --url "$url?api-version=$apiVersion" --body "@$payloadFile"

Payload file (query-based-metric-alert.json):