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:

• An Azure Log Analytics workspace. That resource’s workspace ID will be used for all query operations.
• Basic knowledge of the Kusto Query Language.

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:

• .NET
• Java
• JavaScript/TypeScript
• Python

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

• .NET
• Java
• JavaScript / TypeScript
• Python

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:

• .NET
• Java
• JavaScript
• Python

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.

• Azure SDK Website: aka.ms/azsdk
• Azure SDK Intro (3-minute video): aka.ms/azsdk/intro
• Azure SDK Intro Deck (PowerPoint deck): aka.ms/azsdk/intro/deck
• Azure SDK Releases: aka.ms/azsdk/releases
• Azure SDK Blog: aka.ms/azsdk/blog
• Azure SDK Twitter: twitter.com/AzureSDK
• Azure SDK Design Guidelines: aka.ms/azsdk/guide
• Azure SDKs & Tools: azure.microsoft.com/downloads
• Azure SDK Central Repository: github.com/azure/azure-sdk
• Azure SDK for .NET: github.com/azure/azure-sdk-for-net
• Azure SDK for Java: github.com/azure/azure-sdk-for-java
• Azure SDK for Python: github.com/azure/azure-sdk-for-python
• Azure SDK for JavaScript/TypeScript: github.com/azure/azure-sdk-for-js
• Azure SDK for Android: github.com/Azure/azure-sdk-for-android
• Azure SDK for iOS: github.com/Azure/azure-sdk-for-ios
• Azure SDK for Go: github.com/Azure/azure-sdk-for-go
• Azure SDK for C: github.com/Azure/azure-sdk-for-c
• Azure SDK for C++: github.com/Azure/azure-sdk-for-cpp