Emit custom metrics
APPLIES TO: All API Management tiers
The emit-metric policy sends custom metrics in the specified format to Application Insights.
Note
Set the policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.
Limits for custom metrics
Azure Monitor imposes usage limits for custom metrics that may affect your ability to emit metrics from API Management. For example, Azure Monitor currently sets a limit of 10 dimension keys per metric, and a limit of 50,000 total active time series per region in a subscription (within a 12 hour period).
These limits have the following implications for configuring custom metrics in an API Management policy such as emit-metric or azure-openai-emit-token-metric:
You can configure a maximum of 10 custom dimensions per policy.
The number of active time series generated by the policy within a 12 hour period is the product of the number of unique values of each configured dimension during the period. For example, if three custom dimensions were configured in the policy, and each dimension had 10 possible values within the period, the policy would contribute 1,000 (10 x 10 x 10) active time series.
If you configure the policy in multiple API Management instances that are in the same region in a subscription, all instances can contribute to the regional active time series limit.
Learn more about design limitations and considerations for custom metrics in Azure Monitor.
Prerequisites
- Your API Management instance must be integrated with Application insights. For more information, see How to integrate Azure API Management with Azure Application Insights.
- Enable Application Insights logging for your APIs.
- Enable custom metrics with dimensions in Application Insights. For more information, see Emit custom metrics.
Policy statement
<emit-metric name="name of custom metric" value="value of custom metric" namespace="metric namespace">
<dimension name="dimension name" value="dimension value" />
</emit-metric>
Attributes
| Attribute | Description | Required | Default value |
|---|---|---|---|
| name | A string. Name of custom metric. Policy expressions aren't allowed. | Yes | N/A |
| namespace | A string. Namespace of custom metric. Policy expressions aren't allowed. | No | API Management |
| value | Value of custom metric expressed as a double. Policy expressions are allowed. | No | 1 |
Elements
| Element | Description | Required |
|---|---|---|
| dimension | Add one or more of these elements for each dimension included in the custom metric. | Yes |
dimension attributes
| Attribute | Description | Required | Default value |
|---|---|---|---|
| name | A string or policy expression. Name of dimension. | Yes | N/A |
| value | A string or policy expression. Value of dimension. Can only be omitted if name matches one of the default dimensions. If so, value is provided as per dimension name. |
No | N/A |
Default dimension names that may be used without value
- API ID
- Operation ID
- Product ID
- User ID
- Subscription ID
- Location
- Gateway ID
Usage
- Policy sections: inbound, outbound, backend, on-error
- Policy scopes: global, workspace, product, API, operation
- Gateways: classic, v2, consumption, self-hosted, workspace
Usage notes
- You can configure at most 10 custom dimensions for this policy.
Example
The following example sends a custom metric to count the number of API requests along with API ID as a custom dimension.
<policies>
<inbound>
<emit-metric name="Request" value="1" namespace="my-metrics">
<dimension name="API ID" />
</emit-metric>
</inbound>
<outbound>
</outbound>
</policies>
Related policies
Related content
For more information about working with policies, see:
- Tutorial: Transform and protect your API
- Policy reference for a full list of policy statements and their settings
- Policy expressions
- Set or edit policies
- Reuse policy configurations
- Policy snippets repo
- Azure API Management policy toolkit
- Author policies using Microsoft Copilot in Azure