Bibliothèque cliente de requête Azure Monitor pour .NET - version 1.2.0

  • Article

La bibliothèque cliente de requête Azure Monitor est utilisée pour exécuter des requêtes en lecture seule sur les deux plateformes de données d’Azure Monitor :

  • Journaux : collecte et organise les données de journal et de performances à partir des ressources supervisées. Les données provenant de différentes sources telles que les journaux de plateforme des services Azure, les données de journal et de performances des agents de machines virtuelles, ainsi que les données d’utilisation et de performances des applications peuvent être consolidées dans un seul espace de travail Azure Log Analytics. Les différents types de données peuvent être analysés ensemble à l’aide de la Langage de requête Kusto.
  • Métriques : collecte des données numériques à partir des ressources surveillées dans une base de données de séries chronologiques. Les métriques sont des valeurs numériques collectées à intervalles réguliers et qui décrivent un certain aspect d’un système à un moment donné. Les métriques sont légères et capables de prendre en charge des scénarios en quasi-temps réel, ce qui les rend utiles pour les alertes et la détection rapide des problèmes.

Ressources :

Prise en main

Prérequis

Installer le package

Installez la bibliothèque de client de requête Azure Monitor pour .NET avec NuGet :

dotnet add package Azure.Monitor.Query

Authentifier le client

Un client authentifié est nécessaire pour interroger les journaux ou les métriques. Pour vous authentifier, créez un instance d’une TokenCredential classe. Passez-le au constructeur de la LogsQueryClient classe ou MetricsQueryClient .

Pour l’authentification, les exemples suivants utilisent DefaultAzureCredential à partir du Azure.Identity package :

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

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

exécuter la requête.

Pour obtenir des exemples de requêtes de journaux et de métriques, consultez la section Exemples .

Concepts clés

Limites et limitation du taux de requête des journaux

Le service Log Analytics applique une limitation lorsque le taux de requêtes est trop élevé. Des limites, telles que le nombre maximal de lignes retournées, sont également appliquées aux requêtes Kusto. Pour plus d’informations, consultez API de requête.

Structure des données des métriques

Chaque ensemble de valeurs de métriques est une série chronologique avec les caractéristiques suivantes :

  • L’heure à laquelle la valeur a été collectée
  • Ressource associée à la valeur
  • Un espace de noms qui agit comme une catégorie pour la métrique
  • Un nom de métrique
  • La valeur elle-même
  • Certaines métriques peuvent avoir plusieurs dimensions, comme décrit dans Métriques multidimensionnelles. Les métriques personnalisées peuvent avoir jusqu’à 10 dimensions.

Sécurité des threads

Toutes les méthodes de instance client sont thread-safe et indépendantes les unes des autres (instructions). Cette conception garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options | du client Accès à la réponse | Opérations | de longue duréeGestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Requête Logs

Vous pouvez interroger les journaux par ID d’espace de travail ou ID de ressource. Le résultat est retourné sous la forme d’une table avec une collection de lignes.

Requête de journaux centrés sur l’espace de travail

Pour interroger par ID d’espace de travail, utilisez la méthode 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"]}");
}

Requête de journaux centrés sur les ressources

Pour interroger par ID de ressource, utilisez la méthode LogsQueryClient.QueryResourceAsync .

Pour rechercher l’ID de ressource :

  1. Accédez à la page de votre ressource dans le Portail Azure.
  2. Dans le panneau Vue d’ensemble , sélectionnez le lien Vue JSON .
  3. Dans le json résultant, copiez la valeur de la id propriété .
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);
}

Gérer la réponse aux requêtes des journaux

La QueryWorkspace méthode retourne le LogsQueryResult, tandis que la QueryBatch méthode retourne le LogsBatchQueryResult. Voici une hiérarchie de la réponse :

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

Mapper les résultats de la requête des journaux à un modèle

Vous pouvez mapper les résultats de la requête de journaux à un modèle à l’aide de la LogsQueryClient.QueryWorkspaceAsync<T> méthode :

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

Mapper les résultats de la requête des journaux à une primitive

Si votre requête retourne une seule colonne (ou une seule valeur) d’un type primitif, utilisez la surcharge pour la LogsQueryClient.QueryWorkspaceAsync<T> désérialiser :

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

Vous pouvez également inspecter dynamiquement la liste des colonnes. L’exemple suivant imprime le résultat de la requête sous forme de 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();
}

Requête des journaux Batch

Vous pouvez exécuter plusieurs requêtes de journaux dans une même requête à l’aide de la LogsQueryClient.QueryBatchAsync méthode :

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

Scénarios de requête de journaux avancés

Définir le délai d’expiration de requête des journaux

L’exécution de certaines requêtes de journaux prend plus de 3 minutes. Le délai d’expiration du serveur par défaut est de 3 minutes. Vous pouvez augmenter le délai d’attente du serveur à un maximum de 10 minutes. Dans l’exemple suivant, la propriété de ServerTimeout l’objet LogsQueryOptions est utilisée pour définir le délai d’expiration du serveur sur 10 minutes :

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

Interroger plusieurs espaces de travail

Pour exécuter la même requête de journaux sur plusieurs espaces de travail, utilisez la LogsQueryOptions.AdditionalWorkspaces propriété :

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

Inclure des statistiques

Pour obtenir les statistiques d’exécution des requêtes des journaux, telles que la consommation de processeur et de mémoire :

  1. Définissez la propriété LogsQueryOptions.IncludeStatistics sur true.
  2. Appelez la GetStatistics méthode sur l’objet LogsQueryResult .

L’exemple suivant imprime l’heure d’exécution de la requête :

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

Étant donné que la structure de la charge utile des statistiques varie selon la requête, un BinaryData type de retour est utilisé. Il contient la réponse JSON brute. Les statistiques se trouvent dans la query propriété du JSON. Par exemple :

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

Inclure la visualisation

Pour obtenir des données de visualisation pour les requêtes de journaux à l’aide de l’opérateur de rendu :

  1. Définissez la propriété LogsQueryOptions.IncludeVisualization sur true.
  2. Appelez la GetVisualization méthode sur l’objet LogsQueryResult .

Par exemple :

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

Étant donné que la structure de la charge utile de visualisation varie selon la requête, un BinaryData type de retour est utilisé. Il contient la réponse JSON brute. Par exemple :

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

Requête de métriques

Vous pouvez interroger des métriques sur une ressource Azure à l’aide de la MetricsQueryClient.QueryResourceAsync méthode . Pour chaque métrique demandée, un ensemble de valeurs agrégées est retourné à l’intérieur de la TimeSeries collection.

Un ID de ressource est requis pour interroger les métriques. Pour rechercher l’ID de ressource :

  1. Accédez à la page de votre ressource dans le Portail Azure.
  2. Dans le panneau Vue d’ensemble , sélectionnez le lien Affichage JSON .
  3. Dans le json résultant, copiez la valeur de la id propriété .
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);
        }
    }
}

Gérer la réponse de requête des métriques

L’API de requête de métriques retourne un MetricsQueryResult objet. L’objet MetricsQueryResult contient des propriétés telles qu’une liste d’objets CostMetricResultde type , , Namespace, ResourceRegion, TimeSpanet Interval. La MetricResult liste d’objets est accessible à l’aide du metrics param. Chaque MetricResult objet de cette liste contient une liste d’objets MetricTimeSeriesElement . Chaque MetricTimeSeriesElement objet contient des Metadata propriétés et Values .

Voici une hiérarchie de la réponse :

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

Interroger des métriques avec des options

Un MetricsQueryOptions objet peut être utilisé pour prendre en charge des requêtes de métriques plus granulaires. Prenons l’exemple suivant, qui interroge une ressource Azure Key Vault nommée TestVault. La métrique « Disponibilité des demandes de coffre » de la ressource est demandée, comme indiqué par l’ID de métrique « Disponibilité ». En outre, le type d’agrégation « Avg » est inclus.

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

Fractionner une métrique par dimension

La propriété MetricsQueryOptions.Filter peut être utilisée pour fractionner une métrique par dimension lorsque sa valeur de filtre est définie sur un astérisque. Considérez l’exemple suivant pour une ressource App Service nommée TestWebApp. Le code interroge la métrique de la ressource et la Http2xx divise par dimension 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}");
        }
    }
}

Pour obtenir un inventaire des métriques et dimensions disponibles pour chaque type de ressource Azure, consultez Métriques prises en charge avec Azure Monitor.

Inscrire le client avec l’injection de dépendances

Pour vous inscrire LogsQueryClient auprès du conteneur d’injection de dépendances (DI), appelez la AddLogsQueryClient méthode . Pour vous inscrire MetricsQueryClient auprès du conteneur d’injection de dépendances (DI), appelez la AddMetricsQueryClient méthode . Pour plus d’informations, consultez Inscrire un client.

Dépannage

Pour diagnostiquer différents scénarios d’échec, consultez le guide de résolution des problèmes.

Étapes suivantes

Pour en savoir plus sur Azure Monitor, consultez la documentation du service Azure Monitor.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Lorsque vous envoyez une demande de tirage, un cla-bot détermine automatiquement si vous devez fournir un cla cla et décorer la demande de tirage de manière appropriée avec des étiquettes et des commentaires. Suivez les instructions fournies par le bot. Vous n’aurez besoin de signer le CLA qu’une seule fois sur tous les dépôts Microsoft.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez la FAQ sur le code de conduite ou contactez-nous opencode@microsoft.com pour toute question ou commentaire.

Impressions