Azure.Monitor.Query 1.0.0-beta.3

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
This is a prerelease version of Azure.Monitor.Query.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Azure.Monitor.Query --version 1.0.0-beta.3
NuGet\Install-Package Azure.Monitor.Query -Version 1.0.0-beta.3
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.Monitor.Query" Version="1.0.0-beta.3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Monitor.Query --version 1.0.0-beta.3
#r "nuget: Azure.Monitor.Query, 1.0.0-beta.3"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.Monitor.Query as a Cake Addin
#addin nuget:?package=Azure.Monitor.Query&version=1.0.0-beta.3&prerelease

// Install Azure.Monitor.Query as a Cake Tool
#tool nuget:?package=Azure.Monitor.Query&version=1.0.0-beta.3&prerelease

Azure Monitor Query client library for .NET

The Azure.Monitor.Query package provides the ability to query the following Azure Monitor data sources:

  • Azure Monitor Logs - Collects and organizes log and performance data from monitored resources. Data from different sources such as platform logs from Azure services, log and performance data from virtual machines agents, and usage and performance data from apps can be consolidated into a single workspace. The various data types can be analyzed together using the Kusto Query Language.
  • Azure Monitor 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 in Azure Monitor are lightweight and capable of supporting near real-time scenarios, making them particularly useful for alerting and fast detection of issues.

Source code | Package (NuGet)

Getting started

Install the package

Install the Azure Monitor Query client library for .NET with NuGet:

dotnet add package Azure.Monitor.Query --prerelease

Prerequisites

  • An Azure subscription.
  • To query logs, you need an existing Log Analytics workspace. You can create it with one of the following approaches:
  • To query metrics, all you need is an Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.).

Authenticate the client

To interact with the Azure Monitor service, create an instance of a TokenCredential class. Pass it to the constructor of your LogsQueryClient or MetricsQueryClient class.

Key concepts

  • LogsQueryClient - Client that provides methods to query logs from Azure Monitor Logs.
  • MetricsQueryClient - Client that provides methods to query metrics from Azure Monitor Metrics.

Thread safety

All client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

Query logs

You can query logs using the LogsQueryClient.QueryAsync method. The result is returned as a table with a collection of rows:

string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());
Response<LogsQueryResult> response = await client.QueryAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new DateTimeRange(TimeSpan.FromDays(1)));

LogsQueryResultTable table = response.Value.Table;

foreach (var row in table.Rows)
{
    Console.WriteLine(row["OperationName"] + " " + row["ResourceGroup"]);
}

Query logs as model

You can map query results to a model using the LogsQueryClient.QueryAsync<T> method.

public class MyLogEntryModel
{
    public string ResourceGroup { get; set; }
    public int Count { get; set; }
}
var client = new LogsQueryClient(TestEnvironment.LogsEndpoint, new DefaultAzureCredential());
string workspaceId = "<workspace_id>";

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<MyLogEntryModel>> response = await client.QueryAsync<MyLogEntryModel>(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
    new DateTimeRange(TimeSpan.FromDays(1)));

foreach (var logEntryModel in response.Value)
{
    Console.WriteLine($"{logEntryModel.ResourceGroup} had {logEntryModel.Count} events");
}

Query logs as primitive

If your query returns a single column (or a single value) of a primitive type, use the LogsQueryClient.QueryAsync<T> overload to deserialize it:

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<string>> response = await client.QueryAsync<string>(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count | project ResourceGroup",
    new DateTimeRange(TimeSpan.FromDays(1)));

foreach (var resourceGroup in response.Value)
{
    Console.WriteLine(resourceGroup);
}

Batch query

You can execute multiple queries in a single request using the LogsQueryClient.CreateBatchQuery method:

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
// And total event count
var batch = new LogsBatchQuery();

string countQueryId = batch.AddQuery(
    workspaceId,
    "AzureActivity | count",
    new DateTimeRange(TimeSpan.FromDays(1)));
string topQueryId = batch.AddQuery(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
    new DateTimeRange(TimeSpan.FromDays(1)));

Response<LogsBatchQueryResults> response = await client.QueryBatchAsync(batch);

var count = response.Value.GetResult<int>(countQueryId).Single();
var topEntries = response.Value.GetResult<MyLogEntryModel>(topQueryId);

Console.WriteLine($"AzureActivity has total {count} events");
foreach (var logEntryModel in topEntries)
{
    Console.WriteLine($"{logEntryModel.ResourceGroup} had {logEntryModel.Count} events");
}

Query dynamic table

You can also dynamically inspect the list of columns. The following example prints the query result as a table:

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());
Response<LogsQueryResult> response = await client.QueryAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new DateTimeRange(TimeSpan.FromDays(1)));

LogsQueryResultTable table = response.Value.Table;

foreach (var column in table.Columns)
{
    Console.Write(column.Name + ";");
}

Console.WriteLine();

var columnCount = table.Columns.Count;
foreach (var row in table.Rows)
{
    for (int i = 0; i < columnCount; i++)
    {
        Console.Write(row[i] + ";");
    }

    Console.WriteLine();
}

Increase query timeout

Some Logs queries take longer than 3 minutes to execute. The default server timeout is 3 minutes. You can increase the server timeout to a maximum of 10 minutes. In the following example, the LogsQueryOptions object's ServerTimeout property is used to set the server timeout to 10 minutes:

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<int>> response = await client.QueryAsync<int>(
    workspaceId,
    "AzureActivity | summarize count()",
    new DateTimeRange(TimeSpan.FromDays(1)),
    options: new LogsQueryOptions
    {
        ServerTimeout = TimeSpan.FromMinutes(10)
    });

foreach (var resourceGroup in response.Value)
{
    Console.WriteLine(resourceGroup);
}

Query additional workspaces

To run the same query against multiple workspaces, use the LogsQueryOptions.AdditionalWorkspaces property:

string workspaceId = "<workspace_id>";
string additionalWorkspaceId = "<additional_workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

// Query TOP 10 resource groups by event count
Response<IReadOnlyList<int>> response = await client.QueryAsync<int>(
    workspaceId,
    "AzureActivity | summarize count()",
    new DateTimeRange(TimeSpan.FromDays(1)),
    options: new LogsQueryOptions
    {
        AdditionalWorkspaces = { additionalWorkspaceId }
    });

foreach (var resourceGroup in response.Value)
{
    Console.WriteLine(resourceGroup);
}

Query metrics

You can query metrics using the MetricsQueryClient.QueryAsync method. For every requested metric, a set of aggregated values is returned inside the TimeSeries collection.

A resource ID is required to query metrics. To find the resource ID:

  1. Navigate to your resource's page in the Azure portal.
  2. From the Overview blade, select the JSON View link.
  3. In the resulting JSON, copy the value of the id property.
string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/<resource_provider>/<resource>";

var metricsClient = new MetricsQueryClient(new DefaultAzureCredential());

Response<MetricsQueryResult> results = await metricsClient.QueryAsync(
    resourceId,
    new[] {"Microsoft.OperationalInsights/workspaces"}
);

foreach (var metric in results.Value.Metrics)
{
    Console.WriteLine(metric.Name);
    foreach (var element in metric.TimeSeries)
    {
        Console.WriteLine("Dimensions: " + string.Join(",", element.Metadata));

        foreach (var metricValue in element.Data)
        {
            Console.WriteLine(metricValue);
        }
    }
}

Troubleshooting

General

When you interact with the Azure Monitor Query client library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.

For example, if you submit an invalid query, an HTTP 400 error is returned, indicating "Bad Request".

string workspaceId = "<workspace_id>";

var client = new LogsQueryClient(new DefaultAzureCredential());

try
{
    await client.QueryAsync(
        workspaceId, "My Not So Valid Query", new DateTimeRange(TimeSpan.FromDays(1)));
}
catch (Exception e)
{
    Console.WriteLine(e);
}

The exception also contains some additional information like the full error content.

Azure.RequestFailedException : The request had some invalid properties
Status: 400 (Bad Request)
ErrorCode: BadArgumentError

Content:
{"error":{"message":"The request had some invalid properties","code":"BadArgumentError","correlationId":"34f5f93a-6007-48a4-904f-487ca4e62a82","innererror":{"code":"SyntaxError","message":"A recognition error occurred in the query.","innererror":{"code":"SYN0002","message":"Query could not be parsed at 'Not' on line [1,3]","line":1,"pos":3,"token":"Not"}}}}

Setting up console logging

The simplest way to see the logs is to enable the console logging. To create an Azure SDK log listener that outputs messages to the console, use the AzureEventSourceListener.CreateConsoleLogger method:

// Set up a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

To learn more about other logging mechanisms, see here.

Next steps

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. For details, visit cla.microsoft.com.

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (7)

Showing the top 5 NuGet packages that depend on Azure.Monitor.Query:

Package Downloads
LogAnalytics.Client

A .NET client for Azure Log Analytics. Compatible with .NET Core, .NET 5 and .NET 6

JWMB.AzureMonitorAlertToSlack

Package Description

LijonGraph

Package Description

CasCap.Apis.Azure.LogAnalytics The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Helper library for Azure Log Analytics.

Adlib.Common.Shared

Package Description

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on Azure.Monitor.Query:

Repository Stars
tomkerkhove/promitor
Bringing Azure Monitor metrics where you need them.
Azure/Azure-Media-Services-Explorer
Azure Media Services Explorer Tool
Version Downloads Last updated
1.3.0-beta.2 2,172 12/2/2023
1.3.0-beta.1 1,572 10/18/2023
1.2.0 551,525 5/22/2023
1.2.0-beta.1 1,021 5/1/2023
1.1.0 1,095,798 1/25/2022
1.0.1 15,591 11/10/2021
1.0.0 13,796 10/7/2021
1.0.0-beta.4 8,022 9/8/2021
1.0.0-beta.3 659 8/10/2021
1.0.0-beta.2 3,155 7/8/2021
1.0.0-beta.1 279 6/7/2021