Send custom metrics for an Azure resource to the Azure Monitor metrics store by using a REST API

Article
04/09/2023

This article shows you how to send custom metrics for Azure resources to the Azure Monitor metrics store via a REST API. When the metrics are in Azure Monitor, you can do all the things with them that you do with standard metrics. For example, you can generate charts and alerts and route the metrics to other external tools.

Note

The REST API only permits sending custom metrics for Azure resources. To send metrics for resources in other environments or on-premises, use Application Insights.

Create and authorize a service principal to emit metrics

A service principal is an application whose tokens can be used to authenticate and grant access to specific Azure resources by using Azure Active Directory. Resources include user apps, services, or automation tools.

Register an application with Azure Active Directory to create a service principal.
Save the tenant ID, new client ID, and client secret value for your app to use when it requests a token.
Give the app that was created as part of the previous step Monitoring Metrics Publisher permissions to the resource you want to emit metrics against. If you plan to use the app to emit custom metrics against many resources, you can grant these permissions at the resource group or subscription level.
On your resource's overview page, select Access control (IAM).
Select Add and select Add role assignment from the dropdown list.
Search for Monitoring Metrics in the search field.
Select Monitoring Metrics Publisher from the list.
Select Members.
Search for your app in the Select field.
Select your app from the list.
Click Select.
Select Review + assign.

Get an authorization token

Send the following request in the command prompt or by using a client like Postman.

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitor.azure.com'

The response body appears:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Save the access token from the response for use in the following HTTP requests.

Send a metric via the REST API

Paste the following JSON into a file. Save it as custommetric.json on your local computer. Update the time parameter so that it's within the last 20 minutes. You can't put a metric into the store that's more than 20 minutes old. The metrics store is optimized for alerting and real-time charting.

{ 
    "time": "2023-01-03T11:00:20", 
    "data": { 
        "baseData": { 
            "metric": "QueueDepth", 
            "namespace": "QueueProcessing", 
            "dimNames": [ 
              "QueueName", 
              "MessageType" 
            ], 
            "series": [ 
              { 
                "dimValues": [ 
                  "ImagesToProcess", 
                  "JPEG" 
                ], 
                "min": 3, 
                "max": 20, 
                "sum": 28, 
                "count": 3 
              } 
            ] 
        } 
    } 
}

Submit the following HTTP POST request by using the following variables:
- location: Deployment region of the resource you're emitting metrics for.
- resourceId: Resource ID of the Azure resource you're tracking the metric against.
- accessToken: The authorization token acquired from the previous step.
```
curl -X POST 'https://<location>/.monitoring.azure.com<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json 
```
Change the timestamp and values in the JSON file. Note that the 'time' value in the JSON file is expected to be in UTC.
Repeat the previous two steps a few times to create data for several minutes.

Troubleshooting

If you receive an error message with some part of the process, consider the following troubleshooting information:

If you can't issue metrics against a subscription or resource group, or resource, check that your application or service principal has the Monitoring Metrics Publisher role assigned in Access control (IAM).
Check that the number of dimension names matches the number of values.
Check that you aren't emitting metrics against a region that doesn't support custom metrics. See supported regions.

View your metrics

Sign in to the Azure portal.
In the menu on the left, select Monitor.
On the Monitor page, select Metrics.
Change the aggregation period to Last hour.
In the Scope dropdown list, select the resource you send the metric for.
In the Metric Namespace dropdown list, select queueprocessing.
In the Metric dropdown list, select QueueDepth.

Next steps

Learn more about custom metrics.