Biblioteca de clientes de consulta do Azure Monitor para .NET – versão 1.2.0

A biblioteca de clientes de Consulta do Azure Monitor é usada para executar consultas somente leitura nas duas plataformas de dados do Azure Monitor:

• Logs – coleta e organiza dados de log e desempenho de recursos monitorados. Dados de diferentes fontes, como logs de plataforma de serviços do Azure, dados de log e desempenho de agentes de máquinas virtuais, e dados de uso e desempenho de aplicativos podem ser consolidados em um único workspace do Azure Log Analytics. Os vários tipos de dados podem ser analisados juntos usando o Linguagem de Consulta Kusto.
• Métricas – coleta dados numéricos de recursos monitorados em um banco de dados de série temporal. Métricas são valores numéricos que são coletados a intervalos regulares e descrevem algum aspecto de um sistema em um determinado momento. As métricas são leves e capazes de dar suporte a cenários quase em tempo real, tornando-as úteis para alertas e detecção rápida de problemas.

Recursos:

• Código-fonte
• Pacote NuGet
• Documentação de referência da API
• Documentação do serviço
• Log de alterações
• Guia de migração do Application Insights
• Guia de migração do Operational Insights

Introdução

Pré-requisitos

• Uma assinatura do Azure
• Uma implementação de TokenCredential, como um tipo de credencial de biblioteca de identidade do Azure.
• Para consultar logs, você precisa de uma das seguintes coisas:
  • Um workspace do Azure Log Analytics
  • Um recurso do Azure de qualquer tipo (Conta de Armazenamento, Key Vault, Cosmos DB etc.)
• Para consultar Métricas, você precisa de um recurso do Azure de qualquer tipo (Conta de Armazenamento, Key Vault, Cosmos DB etc.).

Instalar o pacote

Instale a biblioteca de clientes de Consulta do Azure Monitor para .NET com o NuGet:

dotnet add package Azure.Monitor.Query

Autenticar o cliente

Um cliente autenticado é necessário para consultar Logs ou Métricas. Para autenticar, crie uma instância de uma TokenCredential classe . Passe-o para o construtor da LogsQueryClient classe ou MetricsQueryClient .

Para autenticar, os seguintes exemplos usam DefaultAzureCredential do Azure.Identity pacote:

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

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

Executar a consulta

Para obter exemplos de consultas de Logs e Métricas, consulte a seção Exemplos .

Principais conceitos

Limites e limitação da taxa de consulta de logs

O serviço Log Analytics aplica limitação quando a taxa de solicitação é muito alta. Limites, como o número máximo de linhas retornadas, também são aplicados às consultas Kusto. Para obter mais informações, consulte API de Consulta.

Estrutura de dados de métricas

Cada conjunto de valores de métrica é uma série temporal com as seguintes características:

• A hora em que o valor foi coletado
• O recurso associado ao valor
• Um namespace que funciona como uma categoria para a métrica
• Um nome de métrica
• O valor em si
• Algumas métricas podem ter várias dimensões, conforme descrito em métricas multidimensionais. As métricas personalizadas podem ter até 10 dimensões.

Acesso thread-safe

Todos os métodos de instância do cliente são thread-safe e independentes uns dos outros (diretriz). Esse design garante que a recomendação de reutilizações de instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | cliente Acessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

• Consulta de logs
  • Manipular a resposta da consulta de logs
  • Mapear os resultados da consulta de logs para um modelo
  • Mapear os resultados da consulta de logs para um primitivo
  • Imprimir resultados da consulta de logs como uma tabela
• Consulta de logs do Lote
• Cenários de consulta de logs avançados
  • Definir tempo limite de consulta de logs
  • Consultar vários workspaces
  • Incluir estatísticas
  • Incluir visualização
• Consulta de métricas
  • Manipular a resposta da consulta de métricas
  • Métricas de consulta com opções
  • Dividir uma métrica por dimensão
• Registrar o cliente com injeção de dependência

Consulta de logs

Você pode consultar logs por ID do workspace ou ID do recurso. O resultado é retornado como uma tabela com uma coleção de linhas.

Consulta de logs centrada no workspace

Para consultar por ID do workspace, use o método 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"]}");
}

Consulta de logs centrada em recursos

Para consultar por ID de recurso, use o método LogsQueryClient.QueryResourceAsync .

Para localizar a ID do recurso:

1. Navegue até a página do recurso no portal do Azure.
2. Na folha Visão geral , selecione o link Modo de Exibição JSON .
3. No JSON resultante, copie o valor da id propriedade .

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

Manipular a resposta da consulta de logs

O QueryWorkspace método retorna o LogsQueryResult, enquanto o QueryBatch método retorna o LogsBatchQueryResult. Aqui está uma hierarquia da resposta:

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

Mapear os resultados da consulta de logs para um modelo

Você pode mapear os resultados da consulta de logs para um modelo usando o LogsQueryClient.QueryWorkspaceAsync<T> método :

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

Mapear os resultados da consulta de logs para um primitivo

Se a consulta retornar uma única coluna (ou um único valor) de um tipo primitivo, use a LogsQueryClient.QueryWorkspaceAsync<T> sobrecarga para desserializá-la:

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

Imprimir resultados da consulta de logs como uma tabela

Você também pode inspecionar dinamicamente a lista de colunas. O exemplo a seguir imprime o resultado da consulta como uma tabela:

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

Consulta de logs do Lote

Você pode executar várias consultas de logs em uma única solicitação usando o LogsQueryClient.QueryBatchAsync método :

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

Cenários de consulta de logs avançados

Definir tempo limite de consulta de logs

Algumas consultas de logs levam mais de 3 minutos para serem executadas. O tempo limite padrão do servidor é de 3 minutos. Você pode aumentar o tempo limite do servidor para um máximo de 10 minutos. No exemplo a seguir, a LogsQueryOptions propriedade do objeto é usada para definir o tempo limite do ServerTimeout servidor como 10 minutos:

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

Consultar vários workspaces

Para executar a mesma consulta de logs em vários workspaces, use a LogsQueryOptions.AdditionalWorkspaces propriedade :

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

Incluir estatísticas

Para obter estatísticas de execução de consulta de logs, como consumo de CPU e memória:

1. Defina a propriedade LogsQueryOptions.IncludeStatistics como true.
2. Invoque o GetStatistics método no LogsQueryResult objeto .

O exemplo a seguir imprime o tempo de execução da consulta:

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

Como a estrutura do conteúdo de estatísticas varia de acordo com a consulta, um BinaryData tipo de retorno é usado. Ele contém a resposta JSON bruta. As estatísticas são encontradas dentro da query propriedade do JSON. Por exemplo:

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

Incluir visualização

Para obter dados de visualização para consultas de logs usando o operador de renderização:

1. Defina a propriedade LogsQueryOptions.IncludeVisualization como true.
2. Invoque o GetVisualization método no LogsQueryResult objeto .

Por exemplo:

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

Como a estrutura da carga de visualização varia de acordo com a consulta, um BinaryData tipo de retorno é usado. Ele contém a resposta JSON bruta. Por exemplo:

{
  "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
}

Consulta de métricas

Você pode consultar métricas em um recurso do Azure usando o MetricsQueryClient.QueryResourceAsync método . Para cada métrica solicitada, um conjunto de valores agregados é retornado dentro da TimeSeries coleção.

Uma ID de recurso é necessária para consultar métricas. Para localizar a ID do recurso:

1. Navegue até a página do recurso no portal do Azure.
2. Na folha Visão geral , selecione o link Modo de Exibição JSON .
3. No JSON resultante, copie o valor da id propriedade .

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[] { "Query Success Rate", "Query Count" }
);

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

Manipular a resposta da consulta de métricas

A API de consulta de métricas retorna um MetricsQueryResult objeto . O MetricsQueryResult objeto contém propriedades como uma lista de MetricResultobjetos tipado, Cost, Namespace, ResourceRegion, TimeSpane Interval. A MetricResult lista de objetos pode ser acessada usando o metrics parâmetro . Cada MetricResult objeto nesta lista contém uma lista de MetricTimeSeriesElement objetos. Cada MetricTimeSeriesElement objeto contém Metadata as propriedades e Values .

Aqui está uma hierarquia da resposta:

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

Métricas de consulta com opções

Um MetricsQueryOptions objeto pode ser usado para dar suporte a consultas de métricas mais granulares. Considere o exemplo a seguir, que consulta um recurso de Key Vault do Azure chamado TestVault. A métrica "Disponibilidade de solicitações do cofre" do recurso é solicitada, conforme indicado pela ID de métrica "Disponibilidade". Além disso, o tipo de agregação "Média" está incluído.

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

Dividir uma métrica por dimensão

A propriedade MetricsQueryOptions.Filter pode ser usada para dividir uma métrica por uma dimensão quando seu valor de filtro é definido como um asterisco. Considere o exemplo a seguir para um recurso de Serviço de Aplicativo chamado TestWebApp. O código consulta a métrica do Http2xx recurso e a divide pela Instance dimensão.

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

Para obter um inventário de métricas e dimensões disponíveis para cada tipo de recurso do Azure, consulte Métricas com suporte com o Azure Monitor.

Registrar o cliente com injeção de dependência

Para registrar-se LogsQueryClient com o contêiner de DI (injeção de dependência), invoque o AddLogsQueryClient método . Para registrar-se MetricsQueryClient com o contêiner de DI (injeção de dependência), invoque o AddMetricsQueryClient método . Para obter mais informações, consulte Registrar cliente.

Solução de problemas

Para diagnosticar vários cenários de falha, consulte o guia de solução de problemas.

Próximas etapas

Para saber mais sobre o Azure Monitor, confira a documentação do serviço Azure Monitor.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um CLA-bot determina automaticamente se você precisa fornecer um CLA e decorar a PR adequadamente com rótulos e comentários. Basta seguir as instruções fornecidas pelo bot. Você só precisará assinar o CLA uma vez em todos os repositórios da Microsoft.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as Perguntas frequentes sobre o Código de Conduta ou entre em contato opencode@microsoft.com com perguntas ou comentários.