Current version is 1.0.0, click here for the index

Azure Monitor Metrics Query client library for Java

The Azure Monitor Metrics Query client library is used to execute read-only queries against Azure Monitor's metrics data platform:

Metrics - Collects numeric data from monitored resources into a time series database. Metrics are numerical values that are collected at regular intervals and describe some aspect of a system at a particular time. Metrics are lightweight and capable of supporting near real-time scenarios, making them useful for alerting and fast detection of issues.

Resources:

Getting started

Prerequisites

A Java Development Kit (JDK), version 8 or later
- Here are details about Java 8 client compatibility with Azure Certificate Authority.
An Azure subscription
A TokenCredential implementation, such as an Azure Identity library credential type.
To query Metrics, you need an Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.).

Include the package

Include the BOM file

Include the azure-sdk-bom to your project to take a dependency on the stable version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. To learn more about the BOM, see the AZURE SDK BOM README.

&lt;dependencyManagement&gt;
    &lt;dependencies&gt;
        &lt;dependency&gt;
            &lt;groupId&gt;com.azure&lt;/groupId&gt;
            &lt;artifactId&gt;azure-sdk-bom&lt;/artifactId&gt;
            &lt;version&gt;{bom_version_to_target}&lt;/version&gt;
            &lt;type&gt;pom&lt;/type&gt;
            &lt;scope&gt;import&lt;/scope&gt;
        &lt;/dependency&gt;
    &lt;/dependencies&gt;
&lt;/dependencyManagement&gt;

Then include the direct dependency in the dependencies section without the version tag:

&lt;dependencies&gt;
  &lt;dependency&gt;
    &lt;groupId&gt;com.azure&lt;/groupId&gt;
    &lt;artifactId&gt;azure-monitor-query-metrics&lt;/artifactId&gt;
  &lt;/dependency&gt;
&lt;/dependencies&gt;

Include direct dependency

If you want to take dependency on a particular version of the library that isn't present in the BOM, add the direct dependency to your project as follows.

&lt;dependency&gt;
    &lt;groupId&gt;com.azure&lt;/groupId&gt;
    &lt;artifactId&gt;azure-monitor-query-metrics&lt;/artifactId&gt;
    &lt;version&gt;1.0.0&lt;/version&gt;
&lt;/dependency&gt;

Authenticate using Microsoft Entra ID

You can authenticate with Microsoft Entra ID using the Azure Identity library. Regional endpoints don't support Microsoft Entra authentication. Create a custom subdomain for your resource to use this type of authentication.

To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure Identity library, include the azure-identity package:

&lt;dependency&gt;
    &lt;groupId&gt;com.azure&lt;/groupId&gt;
    &lt;artifactId&gt;azure-identity&lt;/artifactId&gt;
    &lt;version&gt;1.16.3&lt;/version&gt;
&lt;/dependency&gt;

Set the values of the client ID, tenant ID, and client secret of the Microsoft Entra application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Synchronous clients

MetricsClient metricsClient = new MetricsClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Asynchronous clients

MetricsAsyncClient metricsAsyncClient = new MetricsClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

Configure client for Azure sovereign cloud

By default, MetricsClient is configured to connect to the Azure Public Cloud. To use a sovereign cloud instead, set the correct endpoint in the client builders.

Creating a MetricsClient for Azure China Cloud:

MetricsClient metricsClient = new MetricsClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint(&quot;{china_cloud_endpoint}&quot;)
    .audience(MetricsAudience.AZURE_CHINA)
    .buildClient();

Execute the query

For examples of Metrics queries, see the Examples section.

Key concepts

Metrics data structure

Each set of metric values is a time series with the following characteristics:

The time the value was collected
The resource associated with the value
A namespace that acts like a category for the metric
A metric name
The value itself
Some metrics have multiple dimensions as described in multi-dimensional metrics. Custom metrics can have up to 10 dimensions.

Examples

Metrics query

A resource ID, as denoted by the {resource-uri} placeholder in the following sample, is required to query metrics. To find the resource ID:

Navigate to your resource's page in the Azure portal.
From the Overview blade, select the JSON View link.
In the resulting JSON, copy the value of the id property.

Metrics query resources

MetricsClient metricsClient = new MetricsClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

MetricsQueryResourcesResult metricsQueryResult = metricsClient.queryResources(
    Arrays.asList(&quot;{resourceId}&quot;, &quot;{resourceId2}&quot;),
    Arrays.asList(&quot;{metric1}&quot;, &quot;{metric2}&quot;),
    &quot;{metricNamespace}&quot;);

for (MetricsQueryResult queryResult : metricsQueryResult.getMetricsQueryResults()) {
    System.out.println(&quot;Resource ID: &quot; + queryResult.getResourceId());
    System.out.println(&quot;Metrics: &quot; + queryResult.getMetrics().size() + &quot;\n&quot;);
    // print out the metrics for each query result
    for (MetricResult metric : queryResult.getMetrics()) {
        System.out.println(&quot;Metric Name: &quot; + metric.getMetricName());
        System.out.println(&quot;Unit: &quot; + metric.getUnit());
        System.out.println(&quot;Time Series Count: &quot; + metric.getTimeSeries().size());

        metric.getTimeSeries().forEach(timeSeries -&gt; {
            timeSeries.getValues().forEach(value -&gt; {
                System.out.println(&quot;Timestamp: &quot; + value.getTimeStamp()
                    + &quot;, Total: &quot; + value.getTotal()
                    + &quot;, Average: &quot; + value.getAverage()
                    + &quot;, Count: &quot; + value.getCount());
            });
        });
    }
}

Handle metrics query response

The metrics query API returns a MetricsQueryResult object. The MetricsQueryResult object contains properties such as a list of MetricResult-typed objects, granularity, namespace, and timeInterval. The MetricResult objects list can be accessed using the metrics param. Each MetricResult object in this list contains a list of TimeSeriesElement objects. Each TimeSeriesElement contains data and metadata_values properties. In visual form, the object hierarchy of the response resembles the following structure:

MetricsQueryResult
|---granularity
|---timeInterval
|---cost
|---namespace
|---resourceRegion
|---metrics (list of `MetricResult` objects)
    |---id
    |---type
    |---name
    |---unit
    |---timeSeries (list of `TimeSeriesElement` objects)
        |---metadata (dimensions)
        |---metricValues (list of data points represented by `MetricValue` objects)
             |--- timeStamp
             |--- count
             |--- average
             |--- total
             |--- maximum
             |--- minimum

Get average and count metrics

MetricsClient metricsClient = new MetricsClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Response&lt;MetricsQueryResourcesResult&gt; metricsResponse = metricsClient.queryResourcesWithResponse(
    Arrays.asList(&quot;{resourceId}&quot;, &quot;{resourceId2}&quot;),
    Arrays.asList(&quot;{metric1}&quot;, &quot;{metric2}&quot;),
    &quot;{metricNamespace}&quot;,
    new MetricsQueryResourcesOptions()
        .setGranularity(Duration.ofHours(1))
        .setAggregations(Arrays.asList(AggregationType.AVERAGE, AggregationType.COUNT)),
    Context.NONE);

MetricsQueryResourcesResult metricsQueryResult = metricsResponse.getValue();

for (MetricsQueryResult queryResult : metricsQueryResult.getMetricsQueryResults()) {
    System.out.println(&quot;Resource ID: &quot; + queryResult.getResourceId());
    System.out.println(&quot;Metrics: &quot; + queryResult.getMetrics().size() + &quot;\n&quot;);
    // print out the metrics for each query result
    for (MetricResult metric : queryResult.getMetrics()) {
        System.out.println(&quot;Metric Name: &quot; + metric.getMetricName());
        System.out.println(&quot;Unit: &quot; + metric.getUnit());
        System.out.println(&quot;Time Series Count: &quot; + metric.getTimeSeries().size());

        metric.getTimeSeries().forEach(timeSeries -&gt; {
            timeSeries.getValues().forEach(value -&gt; {
                System.out.println(&quot;Timestamp: &quot; + value.getTimeStamp()
                    + &quot;, Average: &quot; + value.getAverage()
                    + &quot;, Count: &quot; + value.getCount());
            });
        });
    }
}

Troubleshooting

See our troubleshooting guide for details on how to diagnose various failure scenarios.

Next steps

To learn more about Azure Monitor, see the Azure Monitor service documentation.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Packages

Package

Description

com.azure.monitor.query.metrics

Package containing the classes for MetricsQuery.

com.azure.monitor.query.metrics.models

Package containing the data models for Metrics.

Azure SDK for Java Reference Documentation