Azure.Monitor.Query 1.4.0

适用于 .NET 的 Azure Monitor 查询客户端库

Azure Monitor 查询客户端库用于对 Azure Monitor 的两个数据平台执行只读查询

• 日志 - 从受监控的资源收集和整理日志和性能数据。来自不同来源的数据，例如 Azure 服务的平台日志、虚拟机代理的日志和性能数据、以及应用程序的使用和性能数据，可以整合到单个 Azure Log Analytics 工作区 中。可以使用 Kusto 查询语言 对各种数据类型一起进行分析。

资源

• 源代码
• NuGet 包
• API 参考文档
• 服务文档
• 变更日志
• 从 Application Insights 迁移指南
• 从 Operational Insights 迁移指南

入门

先决条件

• 一个 Azure 订阅
• 一个 TokenCredential 实现，例如一个 Azure Identity 库凭证类型。
• 要查询日志，您需要以下其中一项
  • 一个 Azure Log Analytics 工作区
  • 任何类型的 Azure 资源（存储帐户、密钥保管库、Cosmos DB 等）
• 要查询指标，您需要一个任何类型的 Azure 资源（存储帐户、密钥保管库、Cosmos DB 等）。

安装包

使用 NuGet 安装 Azure Monitor 查询客户端库 (.NET)

dotnet add package Azure.Monitor.Query

验证客户端

查询日志或指标需要一个经过验证的客户端。要验证，请创建 TokenCredential 类的一个实例。将其传递给 LogsQueryClient、MetricsClient 或 MetricsQueryClient 类的构造函数。为了满足 TokenCredential 的要求，以下示例使用来自 Azure.Identity 包的 DefaultAzureCredential。

日志查询客户端

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

指标查询客户端

要对单个 Azure 资源进行指标查询，请使用以下客户端

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

要跨多个 Azure 资源进行指标查询，请使用以下客户端

var client = new MetricsClient(
    new Uri("https://<region>.metrics.monitor.azure.com"),
    new DefaultAzureCredential());

配置针对 Azure 主权云的客户端

默认情况下，LogsQueryClient、MetricsQueryClient 和 MetricsClient 已配置为使用 Azure 公共云。要使用主权云代替，请设置适当 Options-suffixed 类的 Audience 属性。例如

// MetricsClient
var metricsClientOptions = new MetricsClientOptions
{
    Audience = MetricsClientAudience.AzureGovernment
};
var metricsClient = new MetricsClient(
    new Uri("https://usgovvirginia.metrics.monitor.azure.us"),
    new DefaultAzureCredential(),
    metricsClientOptions);

// MetricsQueryClient
var metricsQueryClientOptions = new MetricsQueryClientOptions
{
    Audience = MetricsQueryAudience.AzureGovernment
};
var metricsQueryClient = new MetricsQueryClient(
    new DefaultAzureCredential(),
    metricsQueryClientOptions);

// LogsQueryClient
var logsQueryClientOptions = new LogsQueryClientOptions
{
    Audience = LogsQueryAudience.AzureChina
};
var logsQueryClient = new LogsQueryClient(
    new DefaultAzureCredential(),
    logsQueryClientOptions);

执行查询

有关日志和指标查询的示例，请参阅示例部分。

关键概念

日志查询速率限制和节流

当请求速率过高时，日志分析服务将应用节流。Kusto 查询上还应用了诸如返回的最大行数之类的限制。有关更多信息，请参阅查询 API。

指标数据结构

每套指标值是一个具有以下特征的时间序列

• 收集值时的时间
• 与值关联的资源
• 一个类似于指标的类别的命名空间
• 指标名称
• 值本身
• 一些指标具有多维度，如多维指标中所述。自定义指标可以有最多 10 个维度。

线程安全

所有客户端实例方法都是线程安全的，彼此独立（指南）。此设计确保了重用客户端实例的建议始终是安全的，即使在跨线程的情况下。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

• 日志查询
  • 以工作区为中心的日志查询
  • 以资源为中心的日志查询
  • 处理日志查询响应
  • 将日志查询结果映射到模型
  • 将日志查询结果映射到原始类型
  • 将日志查询结果打印为表格
• 批量日志查询
• 高级日志查询场景
  • 设置日志查询超时
  • 查询多个工作区
  • 包含统计信息
  • 包含可视化
• 指标查询
  • 处理指标查询响应
  • 使用选项查询指标
  • 获取指标命名空间
  • 按维度拆分指标
  • 查询多个资源的指标
• 使用依赖注入注册客户端

日志查询

您可以通过 Log Analytics 工作区 ID 或 Azure 资源 ID 查询日志。结果以表格的形式，返回一列数据集合。

以工作区为中心的日志查询

要使用工作区 ID 查询，请使用 LogsQueryClient.QueryWorkspaceAsync 方法

string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());

Response<LogsQueryResult> result = await client.QueryWorkspaceAsync(
    workspaceId,
    "AzureActivity | top 10 by TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(1)));

LogsTable table = result.Value.Table;

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

以资源为中心的日志查询

要使用资源 ID 查询，请使用 LogsQueryClient.QueryResourceAsync 方法。

要找到资源 ID

1. 导航到 Azure 门户中您的资源页面。
2. 在 概述 选项卡，选择 JSON 视图 链接。
3. 在生成的 JSON 中，复制 id 属性的值。

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

string resourceId = "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/<resource_provider>/<resource>";
string tableName = "<table_name>";
Response<LogsQueryResult> results = await client.QueryResourceAsync(
    new ResourceIdentifier(resourceId),
    $"{tableName} | distinct * | project TimeGenerated",
    new QueryTimeRange(TimeSpan.FromDays(7)));

LogsTable resultTable = results.Value.Table;
foreach (LogsTableRow row in resultTable.Rows)
{
    Console.WriteLine($"{row["OperationName"]} {row["ResourceGroup"]}");
}

foreach (LogsTableColumn columns in resultTable.Columns)
{
    Console.WriteLine("Name: " + columns.Name + " Type: " + columns.Type);
}

处理日志查询响应

QueryWorkspace 方法返回 LogsQueryResult，而 QueryBatch 方法返回 LogsBatchQueryResult。以下是响应的层次结构

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

将日志查询结果映射到模型

您可以使用 LogsQueryClient.QueryWorkspaceAsync<T> 方法将日志查询结果映射到模型

public class MyLogEntryModel
{
    public string ResourceGroup { get; set; }
    public int Count { get; set; }
}

var client = new LogsQueryClient(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");
}

将日志查询结果映射到原始类型

如果您的查询返回的是单个原始类型的单列（或单个值），请使用 LogsQueryClient.QueryWorkspaceAsync<T> 重载进行反序列化

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

将日志查询结果打印为表格

您还可以动态检查列列表。以下示例将查询结果打印为表格

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

批量日志查询

您可以使用 LogsQueryClient.QueryBatchAsync 方法在一个请求中执行多个日志查询

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

高级日志查询场景

设置日志查询超时

一些日志查询的执行时间可能超过 3 分钟。默认服务器超时时间是 3 分钟。您可以将服务器超时时间增加到最多 10 分钟。在以下示例中，使用 LogsQueryOptions 对象的 ServerTimeout 属性将服务器超时设置为 10 分钟

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)),
    new LogsQueryOptions
    {
        ServerTimeout = TimeSpan.FromMinutes(10)
    });

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

查询多个工作区

要对多个工作区运行相同的日志查询，请使用 LogsQueryOptions.AdditionalWorkspaces 属性

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<string>> response = await client.QueryWorkspaceAsync<string>(
    workspaceId,
    @"AzureActivity
        | summarize Count = count() by ResourceGroup
        | top 10 by Count
        | project ResourceGroup",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    new LogsQueryOptions
    {
        AdditionalWorkspaces = { additionalWorkspaceId }
    });

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

包含统计信息

为了获取日志查询执行统计信息，例如 CPU 和内存消耗

1. 将 LogsQueryOptions.IncludeStatistics 属性设置为 true。
2. 在 LogsQueryResult 对象上调用 GetStatistics 方法。

以下示例打印查询执行时间

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)),
    new LogsQueryOptions
    {
        IncludeStatistics = true,
    });

BinaryData stats = response.Value.GetStatistics();
using var statsDoc = JsonDocument.Parse(stats);
var queryStats = statsDoc.RootElement.GetProperty("query");
Console.WriteLine(queryStats.GetProperty("executionTime").GetDouble());

因为统计信息负载的结构因查询而异，所以使用 BinaryData 返回类型。它包含原始 JSON 响应。统计信息位于 JSON 的 query 属性中。例如

{
  "query": {
    "executionTime": 0.0156478,
    "resourceUsage": {...},
    "inputDatasetStatistics": {...},
    "datasetStatistics": [{...}]
  }
}

包含可视化

要通过渲染操作符获取日志查询的可视化数据，请访问渲染操作符

1. 将属性LogsQueryOptions.IncludeVisualization设置为true。
2. 在LogsQueryResult对象上调用GetVisualization方法。

例如

string workspaceId = "<workspace_id>";
var client = new LogsQueryClient(new DefaultAzureCredential());

Response<LogsQueryResult> response = await client.QueryWorkspaceAsync(
    workspaceId,
    @"StormEvents
        | summarize event_count = count() by State
        | where event_count > 10
        | project State, event_count
        | render columnchart",
    new QueryTimeRange(TimeSpan.FromDays(1)),
    new LogsQueryOptions
    {
        IncludeVisualization = true,
    });

BinaryData viz = response.Value.GetVisualization();
using var vizDoc = JsonDocument.Parse(viz);
var queryViz = vizDoc.RootElement.GetProperty("visualization");
Console.WriteLine(queryViz.GetString());

由于可视化负载的结构因查询而异，因此使用返回类型为BinaryData。它包含原始JSON响应。例如

{
  "visualization": "columnchart",
  "title": null,
  "accumulate": false,
  "isQuerySorted": false,
  "kind": null,
  "legend": null,
  "series": null,
  "yMin": "",
  "yMax": "",
  "xAxis": null,
  "xColumn": null,
  "xTitle": null,
  "yAxis": null,
  "yColumns": null,
  "ySplit": null,
  "yTitle": null,
  "anomalyColumns": null
}

指标查询

您可以使用MetricsQueryClient.QueryResourceAsync方法查询单一Azure资源的度量标准。对于请求的每个度量标准，在TimeSeries集合内返回一系列聚合值。

查询度量标准需要资源ID。要找到资源ID

1. 导航到 Azure 门户中您的资源页面。
2. 在 概述 选项卡，选择 JSON 视图 链接。
3. 在生成的 JSON 中，复制 id 属性的值。

string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/<resource_provider>/<resource>";
var client = new MetricsQueryClient(new DefaultAzureCredential());

Response<MetricsQueryResult> results = await client.QueryResourceAsync(
    resourceId,
    new[] { "Average_% Free Space", "Average_% Used Space" }
);

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

        foreach (MetricValue value in element.Values)
        {
            Console.WriteLine(value);
        }
    }
}

处理指标查询响应

度量标准查询API返回一个MetricsQueryResult对象。该MetricsQueryResult对象包含一些属性，如MetricResult类型的对象列表、Cost、Namespace、ResourceRegion、TimeSpan和Interval。可以使用metrics参数访问MetricResult对象列表。列表中的每个MetricResult对象都包含一个MetricTimeSeriesElement对象的列表。每个MetricTimeSeriesElement对象都包含Metadata和Values属性。

以下是响应的层次结构

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

使用选项查询指标

可以使用MetricsQueryOptions对象来支持更细粒度的度量标准查询。考虑以下示例，它查询名为TestVault的Azure Key Vault资源。请求资源中"Vault请求可用性"度量标准，如度量标准ID "Availability"所示。另外，还包括了"Avg"聚合类型。

string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.KeyVault/vaults/TestVault";
string[] metricNames = new[] { "Availability" };
var client = new MetricsQueryClient(new DefaultAzureCredential());
Response <MetricsQueryResult> result = await client.QueryResourceAsync(
    resourceId,
    metricNames,
    new MetricsQueryOptions
    {
        Aggregations =
        {
            MetricAggregationType.Average,
        }
    });

MetricResult metric = result.Value.Metrics[0];

foreach (MetricTimeSeriesElement element in metric.TimeSeries)
{
    foreach (MetricValue value in element.Values)
    {
        // Prints a line that looks like the following:
        // 6/21/2022 12:29:00 AM +00:00 : 100
        Console.WriteLine($"{value.TimeStamp} : {value.Average}");
    }
}

获取指标命名空间

要编程检索Azure资源的度量标准命名空间，请使用以下代码

string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Web/sites/TestWebApp";
var client = new MetricsQueryClient(new DefaultAzureCredential());

AsyncPageable<MetricNamespace> metricNamespaces = client.GetMetricNamespacesAsync(resourceId);

await foreach (var metricNamespace in metricNamespaces)
{
    Console.WriteLine($"Metric namespace = {metricNamespace.Name}");
}

按维度拆分指标

当过滤器值设置为星号时，可以使用MetricsQueryOptions.Filter属性来按维度拆分度量标准。以下是一个名为TestWebApp的App Service资源的示例。该代码查询资源的Http2xx度量标准，并通过Instance维度进行拆分。

string resourceId =
    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Web/sites/TestWebApp";
string[] metricNames = new[] { "Http2xx" };
// Use of asterisk in filter value enables splitting on Instance dimension.
string filter = "Instance eq '*'";
var client = new MetricsQueryClient(new DefaultAzureCredential());

var options = new MetricsQueryOptions
{
    Aggregations =
    {
        MetricAggregationType.Average,
    },
    Filter = filter,
    TimeRange = TimeSpan.FromDays(2),
};
Response<MetricsQueryResult> result = await client.QueryResourceAsync(
    resourceId,
    metricNames,
    options);

foreach (MetricResult metric in result.Value.Metrics)
{
    foreach (MetricTimeSeriesElement element in metric.TimeSeries)
    {
        foreach (MetricValue value in element.Values)
        {
            // Prints a line that looks like the following:
            // Thursday, May 4, 2023 9:42:00 PM, webwk000002, Http2xx, 1
            Console.WriteLine(
                $"{value.TimeStamp:F}, {element.Metadata["Instance"]}, {metric.Name}, {value.Average}");
        }
    }
}

查询多个资源的指标

要使用单个请求查询多个Azure资源的度量标准，请使用MetricsClient.QueryResources方法。此方法

• 调用与MetricsQueryClient方法不同的API。
• 创建客户端时需要区域端点。例如，"https://westus3.metrics.monitor.azure.com"。

每个Azure资源都必须位于

• 与创建客户端时指定的端点相同的区域中。
• 相同的Azure订阅中。

此外

• 用户必须有权在Azure订阅级别读取监控数据。例如，被查询的订阅上的监控读取器角色。
• 必须提供包含要查询的度量标准的度量标准命名空间。有关度量标准命名空间列表，请参阅按资源类型支持的度量标准和日志类别。

string resourceId =
    "/subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/storageAccounts/<resource-name-1>";
var client = new MetricsClient(
    new Uri("https://<region>.metrics.monitor.azure.com"),
    new DefaultAzureCredential());
Response<MetricsQueryResourcesResult> result = await client.QueryResourcesAsync(
    resourceIds: new List<ResourceIdentifier> { new ResourceIdentifier(resourceId) },
    metricNames: new List<string> { "Ingress" },
    metricNamespace: "Microsoft.Storage/storageAccounts").ConfigureAwait(false);

MetricsQueryResourcesResult metricsQueryResults = result.Value;
foreach (MetricsQueryResult value in metricsQueryResults.Values)
{
    Console.WriteLine(value.Metrics.Count);
}

要查看每个Azure资源类型可用的度量标准和维度清单，请参阅使用Azure Monitor支持的度量标准。

方法QueryResources还接受一个类型为MetricsQueryResourcesOptions的参数，用户可以在此参数中指定额外的属性以过滤结果。以下示例演示了OrderBy和Size属性

string resourceId =
    "/subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/storageAccounts/<resource-name-1>";
var client = new MetricsClient(
    new Uri("https://<region>.metrics.monitor.azure.com"),
    new DefaultAzureCredential());
var options = new MetricsQueryResourcesOptions
{
    OrderBy = "sum asc",
    Size = 10
};

Response<MetricsQueryResourcesResult> result = await client.QueryResourcesAsync(
    resourceIds: new List<ResourceIdentifier> { new ResourceIdentifier(resourceId) },
    metricNames: new List<string> { "Ingress" },
    metricNamespace: "Microsoft.Storage/storageAccounts",
    options).ConfigureAwait(false);

MetricsQueryResourcesResult metricsQueryResults = result.Value;
foreach (MetricsQueryResult value in metricsQueryResults.Values)
{
    Console.WriteLine(value.Metrics.Count);
}

使用依赖注入注册客户端

要使用依赖注入容器注册客户端，请调用相应的扩展方法。

更多信息，请参阅注册客户端。

故障排除

要诊断各种故障情况，请参阅故障排除指南。

下一步操作

要了解更多关于Azure Monitor的信息，请参阅Azure Monitor服务文档。

贡献

本工程欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议（CLA），声明您有权并且实际上确实承诺向我们授予使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定是否需要提供CLA，并用标签和评论适当装饰PR。遵循机器人提供的说明。您只需在整个Microsoft存储库中签署一次CLA。

本工程采用了Microsoft开源代码行为准则。有关更多信息，请参阅行为准则FAQ或通过[email protected]提问或发表意见。