Azure.Monitor.Query 1.0.0

Azure Monitor Query client library for .NET

The Azure Monitor Query client library is used to execute read-only queries against Azure Monitor's two data platforms:

• 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 Azure Log Analytics workspace. The various data types can be analyzed together using the Kusto Query Language.
• 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 particularly useful for alerting and fast detection of issues.

Resources:

• Source code
• Package (NuGet)
• Service documentation
• Change log

Getting started

Prerequisites

• An Azure subscription
• To query Logs, you need an Azure Log Analytics workspace.
• To query Metrics, you need an Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.).

Install the package

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

dotnet add package Azure.Monitor.Query

Authenticate the client

An authenticated client is required to query Logs or Metrics. To authenticate, create an instance of a TokenCredential class. Pass it to the constructor of your LogsQueryClient or MetricsQueryClient class.

To authenticate, the following examples use DefaultAzureCredential from the Azure.Identity package:

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

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

Execute the query

For examples of Logs and Metrics queries, see the Examples section.

Key concepts

Logs query rate limits and throttling

The Log Analytics service applies throttling when the request rate is too high. Limits, such as the maximum number of rows returned, are also applied on the Kusto queries. For more information, see Rate and query limits.

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 may have multiple dimensions as described in multi-dimensional metrics. Custom metrics can have up to 10 dimensions.

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

• Logs query
  • Handle logs query response
  • Map logs query results to a model
  • Map logs query results to a primitive
  • Print logs query results as a table
• Batch logs query
• Advanced logs query scenarios
  • Set logs query timeout
  • Query multiple workspaces
• Metrics query
  • Handle metrics query response

Logs query

You can query logs using the LogsQueryClient.QueryWorkspaceAsync 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.QueryWorkspaceAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(1)));

LogsTable table = response.Value.Table;

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

Handle logs query response

The QueryWorkspace method returns the LogsQueryResult, while the QueryBatch method returns the LogsBatchQueryResult. Here's a hierarchy of the response:

LogsQueryResult
|---Error
|---Status
|---Table
    |---Name
    |---Columns (list of `LogsTableColumn` objects)
        |---Name
        |---Type
    |---Rows (list of `LogsTableRows` objects)
        |---Count
|---AllTables (list of `LogsTable` objects)    

Map logs query results to a model

You can map logs query results to a model using the LogsQueryClient.QueryWorkspaceAsync<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.QueryWorkspaceAsync<MyLogEntryModel>(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
    new QueryTimeRange(TimeSpan.FromDays(1)));

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

Map logs query results to a primitive

If your query returns a single column (or a single value) of a primitive type, use the LogsQueryClient.QueryWorkspaceAsync<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.QueryWorkspaceAsync<string>(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count | project ResourceGroup",
    new QueryTimeRange(TimeSpan.FromDays(1)));

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

Print logs query results as a 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.QueryWorkspaceAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(1)));

LogsTable 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();
}

Batch logs query

You can execute multiple logs queries in a single request using the LogsQueryClient.QueryBatchAsync 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.AddWorkspaceQuery(
    workspaceId,
    "AzureActivity | count",
    new QueryTimeRange(TimeSpan.FromDays(1)));
string topQueryId = batch.AddWorkspaceQuery(
    workspaceId,
    "AzureActivity | summarize Count = count() by ResourceGroup | top 10 by Count",
    new QueryTimeRange(TimeSpan.FromDays(1)));

Response<LogsBatchQueryResultCollection> 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");
}

Advanced logs query scenarios

Set logs 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.QueryWorkspaceAsync<int>(
    workspaceId,
    "AzureActivity | summarize count()",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    options: new LogsQueryOptions
    {
        ServerTimeout = TimeSpan.FromMinutes(10)
    });

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

Query multiple workspaces

To run the same logs 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.QueryWorkspaceAsync<int>(
    workspaceId,
    "AzureActivity | summarize count()",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    options: new LogsQueryOptions
    {
        AdditionalWorkspaces = { additionalWorkspaceId }
    });

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

Metrics query

You can query metrics using the MetricsQueryClient.QueryResourceAsync 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.QueryResourceAsync(
    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.Values)
        {
            Console.WriteLine(metricValue);
        }
    }
}

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, Cost, Namespace, ResourceRegion, TimeSpan, and Interval. The MetricResult objects list can be accessed using the metrics param. Each MetricResult object in this list contains a list of MetricTimeSeriesElement objects. Each MetricTimeSeriesElement object contains Metadata and Values properties.

Here's a hierarchy of the response:

MetricsQueryResult
|---Cost
|---Granularity
|---Namespace
|---ResourceRegion
|---TimeSpan
|---Metrics (list of `MetricResult` objects)
    |---Id
    |---ResourceType
    |---Name
    |---Description
    |---Error
    |---Unit
    |---TimeSeries (list of `MetricTimeSeriesElement` objects)
        |---Metadata
        |---Values

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.QueryWorkspaceAsync(
        workspaceId, "My Not So Valid Query", new QueryTimeRange(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"}}}}

Set 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

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. 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.