Announcing the new Azure Monitor Query client libraries

Scott Addie

In February of this year, the Azure SDK team embarked on a project to modernize and enhance developers’ data retrieval experience for Azure Monitor. The logs and metrics pillars of observability were identified as the focus areas. After analyzing previous generations of the query libraries, several shortcomings were identified. Most notably, the libraries:

  • Felt unnatural to .NET, Java, JavaScript/TypeScript, and Python developers.
  • Lacked production support for Java, JavaScript/TypeScript, and Python.
  • Lacked Azure Active Directory (Azure AD) authentication support.
  • Required separate packages for querying Azure Monitor’s two fundamental data platforms: Logs and Metrics.

Each of these problems would need to be addressed in the new product. But this project was also an opportune time to incorporate customer feedback from each ecosystem. For example, .NET and Java customers wanted to deserialize Logs query results to models. With support for such a feature, much less code would be required in their apps.

The journey to GA

The initial preview release of the Azure Monitor Query client libraries was announced in June. Since that release, the Azure SDK team has conducted extensive research with both existing and prospective customers. Public API surface design assumptions were both validated and invalidated. Learnings from each moderated UX study were incorporated into the product along the way. The team iterated on the libraries until consistently receiving encouraging feedback like “It’s easy to use. I didn’t need documentation to make progress.”

Today, we’re thrilled to unveil the result of that iterative, customer-driven work. The Azure Monitor Query client libraries for .NET, Java, JavaScript/TypeScript, and Python have reached general availability (GA)! These open-source GA libraries:

  • Execute read-only queries in Azure Monitor’s Logs and Metrics data platforms.
  • Combine Logs and Metrics query APIs into a single package for each language.
  • Follow the Azure SDK guidelines, resulting in an idiomatic, consistent, approachable, diagnosable, and dependable design.
  • Introduce new features and enhancements, such as:
    • Azure AD authentication support
    • Asynchronous API calls support via Reactor (Java)
    • Deserialize Logs query results to models (.NET and Java)
    • Configurable server timeout for Logs queries
    • Include performance statistics and visualization data in Logs query results
    • Retrieve Logs query result column values by name
    • Execute a batch of Logs queries in a single request
    • Retrieve metric values by name
    • List metric namespaces and definitions

From creating custom dashboards to configuring pager-style alerts, these libraries are sure to meet your needs. Wield the power of logs and metrics to increase confidence in your root cause analysis. Identify bottlenecks in your infrastructure and optimize app performance.

Get started

Before using the Azure Monitor Query libraries, ensure that you have an Azure subscription. Then complete the following steps:

  1. Install the dependencies.
  2. Create and authenticate a query client.
  3. Execute a query.

1. Install the dependencies

You’ll need to install two packages:

  1. Install one of the four Azure Monitor Query libraries using the command/instructions provided in the following table.
    Language Package Installation
    .NET Azure.Monitor.Query dotnet add package Azure.Monitor.Query
    Java azure-monitor-query Add to pom.xml file
    JavaScript/TypeScript @azure/monitor-query npm install @azure/monitor-query
    Python azure-monitor-query pip install azure-monitor-query
  2. Install the Azure Identity library. This library provides a variety of credential types for Azure AD authentication.
    Language Package Installation
    .NET Azure.Identity dotnet add package Azure.Identity
    Java azure-identity Add to pom.xml file
    JavaScript/TypeScript @azure/identity npm install @azure/identity
    Python azure-identity pip install azure-identity

2. Create and authenticate a query client

An authenticated client object is required to execute a query. LogsQueryClient and MetricsQueryClient are the client objects for querying Logs and Metrics, respectively. The Azure Identity library’s DefaultAzureCredential type is the easiest way to authenticate a client with Azure AD.

.NET

//using Azure.Identity;
//using Azure.Monitor.Query;

var credential = new DefaultAzureCredential();

var logsQueryClient = new LogsQueryClient(credential);
// or
var metricsQueryClient = new MetricsQueryClient(credential);

Java

//import com.azure.identity.DefaultAzureCredential;
//import com.azure.identity.DefaultAzureCredentialBuilder;
//import com.azure.monitor.query.LogsQueryClient;
//import com.azure.monitor.query.LogsQueryClientBuilder;
//import com.azure.monitor.query.MetricsQueryClient;
//import com.azure.monitor.query.MetricsQueryClientBuilder;

DefaultAzureCredential credential =
    new DefaultAzureCredentialBuilder().build();

LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
    .credential(credential)
    .buildClient();
// or
MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
    .credential(credential)
    .buildClient();

JavaScript/TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, MetricsQueryClient } from "@azure/monitor-query";

const credential = new DefaultAzureCredential();

const logsQueryClient = new LogsQueryClient(credential);
// or
const metricsQueryClient = new MetricsQueryClient(credential);

Python

from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, MetricsQueryClient

credential = DefaultAzureCredential()

logs_query_client = LogsQueryClient(credential)
# or
metrics_query_client = MetricsQueryClient(credential)

3. Execute a query

To query Logs, you’ll need:

To query Metrics, you’ll need an Azure resource of any kind. For example, an Azure Storage account. That resource’s resource ID/URI will be used for all query operations.

Retrieve logs

Consider the following code snippets, which demonstrate querying an Azure Log Analytics workspace in the four supported languages. A Kusto query is executed on the AzureActivity table to examine write operations on the Azure subscription’s resources. The table’s first 10 rows are retrieved after sorting the TimeGenerated column in descending order. Only logs produced in the last day are considered.

.NET
//using System.Threading.Tasks;

Response<LogsQueryResult> response =
    await logsQueryClient.QueryWorkspaceAsync(
        workspaceId,
        "AzureActivity | top 10 by TimeGenerated",
        new QueryTimeRange(TimeSpan.FromDays(1)));
Java
LogsQueryResult response =
    logsQueryClient.queryWorkspace(
        workspaceId,
        "AzureActivity | top 10 by TimeGenerated",
        new QueryTimeInterval(Duration.ofDays(1)));
JavaScript/TypeScript
const response = await logsQueryClient.queryWorkspace(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    {
        duration: Durations.oneDay
    });
Python
response = logs_query_client.query_workspace(
    workspace_id,
    query = "AzureActivity | top 10 by TimeGenerated",
    timespan = timedelta(days=1))

Retrieve metrics

Consider the following code snippets, which demonstrate querying an Azure Storage account in the four supported languages. Specifically, the snippets demonstrate querying the Ingress metric and including the Average and Maximum aggregations. Notice that unlike Logs queries, Kusto isn’t used for querying Metrics.

.NET
//using Azure.Monitor.Query.Models;
//using System.Threading.Tasks;

var response = await metricsQueryClient.QueryResourceAsync(
    resourceId,
    metrics: new[] { "Ingress" },
    options: new MetricsQueryOptions
    {
        Aggregations = {
            MetricAggregationType.Average,
            MetricAggregationType.Maximum
        }
    });
Java
Response<MetricsQueryResult> response =
    metricsQueryClient.queryResourceWithResponse(
        resourceId,
        Arrays.asList("Ingress"),
        new MetricsQueryOptions().setAggregations(Arrays.asList(
            AggregationType.AVERAGE, AggregationType.MAXIMUM)),
        Context.NONE);
JavaScript/TypeScript
const response = await metricsQueryClient.queryResource(
    resourceId,
    metricNames: ["Ingress"],
    {
        aggregations: [AggregationType.Average, AggregationType.Maximum]
    });
Python
response = metrics_query_client.query_resource(
    resource_id,
    metric_names = ["Ingress"],
    aggregations = [
        MetricAggregationType.AVERAGE,
        MetricAggregationType.MAXIMUM
    ])

Summary

The complexities of your mission-critical apps demand robust performance and availability monitoring solutions. The Azure SDK team has invested heavily in that monitoring space with the Azure Monitor Query libraries. The libraries offer developers a modern, idiomatic, and secure solution for retrieving Logs and Metrics data. To learn more about the libraries, see the following language-specific README files:

For language-specific examples, see the following code samples:

As you use the library, you’re encouraged to provide feedback. Whether good or bad, the Azure SDK team wants to hear your thoughts. To report issues or send feedback to the Azure SDK engineering team, use the following language-specific links:

Azure SDK Blog Contributions

Thanks for reading this Azure SDK blog post. We hope you learned something new, and we welcome you to share the post. We’re open to Azure SDK blog contributions from our readers. To get started, contact us at azsdkblog@microsoft.com with your idea, and we’ll set you up as a guest blogger.

5 comments

Discussion is closed. Login to edit/delete existing comments.

  • Anand B 0

    Hi Scott, does fetching the metrics by using Azure client libraries incurs charges? If so, is there a detailed guide/documentation available on the same?

    • Scott AddieMicrosoft employee 0

      Thank you for the question, Anand! Currently, all Metrics queries are free of charge. In the future, however, there are plans to charge for certain types of Metrics queries. This pricing page will be updated once the pricing model is determined.

  • Ayan Mullick 0

    Will there be an Azure Monitor query SDK for PowerShell?

    • Maciej Porebski 0

      I believe this functionality is already part of the Az PowerShell module:

      Query Logs: Invoke-AzOperationalInsightsQuery

      Query Metrics: Get-AzMetric

Feedback usabilla icon