Biblioteca cliente de consultas de Azure Monitor para .NET: versión 1.2.0

Artículo
05/24/2023

La biblioteca cliente de consultas de Azure Monitor se usa para ejecutar consultas de solo lectura en las dos plataformas de datos de Azure Monitor:

Registros: recopila y organiza los datos de registro y rendimiento de los recursos supervisados. Los datos de diferentes orígenes, como los registros de plataforma de los servicios de Azure, los datos de registro y rendimiento de los agentes de máquinas virtuales, y los datos de uso y rendimiento de las aplicaciones se pueden consolidar en un único área de trabajo de Azure Log Analytics. Los distintos tipos de datos se pueden analizar conjuntamente mediante el Lenguaje de consulta Kusto.
Métricas : recopila datos numéricos de recursos supervisados en una base de datos de serie temporal. Las métricas son valores numéricos que se recopilan a intervalos regulares y describen algún aspecto de un sistema en un momento determinado. Las métricas son ligeras y capaces de admitir escenarios casi en tiempo real, lo que hace que sean útiles para alertar y detectar rápidamente problemas.

Recursos:

Introducción

Requisitos previos

Una suscripción de Azure
Una implementación de TokenCredential, como un tipo de credencial de la biblioteca de Azure Identity.
Para consultar los registros, necesita una de las siguientes cosas:
- Un área de trabajo de Azure Log Analytics
- Un recurso de Azure de cualquier tipo (cuenta de almacenamiento, Key Vault, Cosmos DB, etc.)
Para consultar las métricas, necesita un recurso de Azure de cualquier tipo (cuenta de almacenamiento, Key Vault, Cosmos DB, etc.).

Instalar el paquete

Instale la biblioteca cliente de consultas de Azure Monitor para .NET con NuGet:

dotnet add package Azure.Monitor.Query

Autenticar el cliente

Se requiere un cliente autenticado para consultar registros o métricas. Para autenticarse, cree una instancia de una TokenCredential clase. Páselo al constructor de la LogsQueryClient clase o MetricsQueryClient .

Para autenticarse, en los ejemplos siguientes se usa DefaultAzureCredential desde el Azure.Identity paquete:

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

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

Ejecute la consulta.

Para obtener ejemplos de consultas de registros y métricas, consulte la sección Ejemplos .

Conceptos clave

Registra los límites de frecuencia de consulta y la limitación

El servicio Log Analytics aplica la limitación cuando la tasa de solicitudes es demasiado alta. Los límites, como el número máximo de filas devueltas, también se aplican en las consultas de Kusto. Para más información, consulte Query API.

Estructura de datos de métricas

Cada conjunto de valores de métricas es una serie temporal con las siguientes características:

Hora en que se recopiló el valor.
Recurso asociado al valor
Espacio de nombres que actúa como una categoría para la métrica.
Nombre de la métrica.
El propio valor.
Algunas métricas pueden tener varias dimensiones, como se describe en métricas multidimensionales. Las métricas personalizadas pueden tener hasta 10 dimensiones.

Seguridad para subprocesos

Todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Este diseño garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Ejemplos

consulta de registros
Consulta de registros de Batch
Escenarios de consulta de registros avanzados
Consulta de métricas
Registro del cliente con inserción de dependencias

consulta de registros

Puede consultar los registros por identificador de área de trabajo o identificador de recurso. El resultado se devuelve como una tabla con una colección de filas.

Consulta de registros centrados en el área de trabajo

Para consultar por identificador de área de trabajo, use el 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 registros centrados en recursos

Para consultar por identificador de recurso, use el método LogsQueryClient.QueryResourceAsync .

Para buscar el identificador de recurso:

Vaya a la página del recurso en el Azure Portal.
En la hoja Información general , seleccione el vínculo Vista JSON .
En el JSON resultante, copie el valor de la id propiedad .

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

Control de la respuesta de consulta de registros

El QueryWorkspace método devuelve , LogsQueryResultmientras que el QueryBatch método devuelve .LogsBatchQueryResult Esta es una jerarquía de la respuesta:

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

Asignar los resultados de la consulta de registros a un modelo

Puede asignar los resultados de la consulta de registros a un modelo mediante el 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");
}

Asignar los resultados de la consulta de registros a un primitivo

Si la consulta devuelve una sola columna (o un valor único) de un tipo primitivo, use la LogsQueryClient.QueryWorkspaceAsync<T> sobrecarga para deserializarla:

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 los resultados de la consulta de registros como una tabla

También puede inspeccionar dinámicamente la lista de columnas. En el ejemplo siguiente se imprime el resultado de la consulta como una tabla:

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 registros de Batch

Puede ejecutar varias consultas de registros en una sola solicitud mediante el 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");
}

Escenarios de consulta de registros avanzados

Establecimiento del tiempo de espera de la consulta de registros

Algunas consultas de registros tardan más de 3 minutos en ejecutarse. El tiempo de espera predeterminado del servidor es de 3 minutos. Puede aumentar el tiempo de espera del servidor a un máximo de 10 minutos. En el ejemplo siguiente, la LogsQueryOptions propiedad del objeto se usa para establecer el tiempo de espera del ServerTimeout servidor en 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);
}

Consulta de varias áreas de trabajo

Para ejecutar la misma consulta de registros en varias áreas de trabajo, use la LogsQueryOptions.AdditionalWorkspaces propiedad :

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 estadísticas

Para obtener las estadísticas de ejecución de consultas de registros, como el consumo de CPU y memoria:

Establezca la propiedad LogsQueryOptions.IncludeStatistics en true.
Invoque el GetStatistics método en el LogsQueryResult objeto .

En el ejemplo siguiente se imprime el tiempo de ejecución de la 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());

Dado que la estructura de la carga de estadísticas varía según la consulta, se usa un BinaryData tipo de valor devuelto. Contiene la respuesta JSON sin formato. Las estadísticas se encuentran dentro de la query propiedad de JSON. Por ejemplo:

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

Incluir visualización

Para obtener datos de visualización de consultas de registros mediante el operador render:

Establezca la propiedad LogsQueryOptions.IncludeVisualization en true.
Invoque el GetVisualization método en el LogsQueryResult objeto .

Por ejemplo:

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

Dado que la estructura de la carga de visualización varía según la consulta, se usa un BinaryData tipo de valor devuelto. Contiene la respuesta JSON sin formato. Por ejemplo:

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

Puede consultar métricas en un recurso de Azure mediante el MetricsQueryClient.QueryResourceAsync método . Para cada métrica solicitada, se devuelve un conjunto de valores agregados dentro de la TimeSeries colección.

Se requiere un identificador de recurso para consultar las métricas. Para buscar el identificador de recurso:

Vaya a la página del recurso en el Azure Portal.
En la hoja Información general , seleccione el vínculo Vista JSON .
En el JSON resultante, copie el valor de la id propiedad .

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

Control de la respuesta de consulta de métricas

La API de consulta de métricas devuelve un MetricsQueryResult objeto . El MetricsQueryResult objeto contiene propiedades como una lista de MetricResultobjetos con tipo , Cost, NamespaceResourceRegion, TimeSpany Interval. Se MetricResult puede tener acceso a la lista de objetos mediante el metrics parámetro . Cada MetricResult objeto de esta lista contiene una lista de MetricTimeSeriesElement objetos . Cada MetricTimeSeriesElement objeto contiene Metadata propiedades y Values .

Esta es una jerarquía de la respuesta:

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

Consulta de métricas con opciones

Se puede usar un MetricsQueryOptions objeto para admitir consultas de métricas más pormenorizadas. Considere el ejemplo siguiente, que consulta un recurso de Azure Key Vault denominado TestVault. Se solicita la métrica "Disponibilidad de solicitudes de almacén" del recurso, como se indica en el identificador de métrica "Disponibilidad". Además, se incluye el tipo de agregación "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}");
    }
}

División de una métrica por dimensión

La propiedad MetricsQueryOptions.Filter se puede usar para dividir una métrica por una dimensión cuando su valor de filtro se establece en un asterisco. Considere el ejemplo siguiente para un recurso de App Service denominado TestWebApp. El código consulta la métrica del Http2xx recurso y la divide por la Instance dimensión.

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 obtener un inventario de métricas y dimensiones disponibles para cada tipo de recurso de Azure, consulte Métricas admitidas con Azure Monitor.

Registro del cliente con inserción de dependencias

Para registrarse LogsQueryClient con el contenedor de inserción de dependencias (DI), invoque el AddLogsQueryClient método . Para registrarse MetricsQueryClient con el contenedor de inserción de dependencias (DI), invoque el AddMetricsQueryClient método . Para obtener más información, vea Registrar cliente.

Solución de problemas

Para diagnosticar varios escenarios de error, consulte la guía de solución de problemas.

Pasos siguientes

Para más información sobre Azure Monitor, consulte la documentación del servicio Azure Monitor.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Al enviar una solicitud de incorporación de cambios, un bot de CLA determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios correctamente con etiquetas y comentarios. Siga las instrucciones que le dará el bot. Solo tendrá que firmar la CLA una vez en todos los repositorios de Microsoft.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com cualquier pregunta o comentario.

Impresiones

Compartir a través de