Azure Monitor-Abfrageclientbibliothek für .NET– Version 1.2.0

  • Artikel

Die Azure Monitor-Abfrageclientbibliothek wird verwendet, um schreibgeschützte Abfragen für die beiden Datenplattformen von Azure Monitor auszuführen:

  • Protokolle : Erfasst und organisiert Protokoll- und Leistungsdaten aus überwachten Ressourcen. Daten aus verschiedenen Quellen, z. B. Plattformprotokolle von Azure-Diensten, Protokoll- und Leistungsdaten von Agents für virtuelle Computer sowie Nutzungs- und Leistungsdaten aus Apps können in einem einzelnen Azure Log Analytics-Arbeitsbereich konsolidiert werden. Die verschiedenen Datentypen können zusammen mit dem Kusto-Abfragesprache analysiert werden.
  • Metriken : Erfasst numerische Daten aus überwachten Ressourcen in einer Zeitreihendatenbank. Metriken sind numerische Werte, die in regelmäßigen Abständen erfasst werden und einen Aspekt eines Systems zu einem bestimmten Zeitpunkt beschreiben. Metriken sind einfach und in der Lage, Szenarien nahezu in Echtzeit zu unterstützen, sodass sie für Warnungen und schnelle Erkennung von Problemen nützlich sind.

Ressourcen:

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Monitor Query-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Monitor.Query

Authentifizieren des Clients

Ein authentifizierter Client ist erforderlich, um Protokolle oder Metriken abzufragen. Erstellen Sie zum Authentifizieren eine instance einer TokenCredential Klasse. Übergeben Sie ihn an den Konstruktor der - oder MetricsQueryClient -LogsQueryClientKlasse.

Für die Authentifizierung wird in den folgenden Beispielen aus dem Azure.Identity Paket verwendetDefaultAzureCredential:

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

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

Führen Sie die Abfrage aus.

Beispiele für Protokoll- und Metrikabfragen finden Sie im Abschnitt Beispiele .

Wichtige Begriffe

Protokollieren von Grenzwerten und Drosselung der Abfragerate

Der Log Analytics-Dienst wendet eine Drosselung an, wenn die Anforderungsrate zu hoch ist. Grenzwerte, z. B. die maximale Anzahl zurückgegebener Zeilen, werden auch auf die Kusto-Abfragen angewendet. Weitere Informationen finden Sie unter Abfrage-API.

Metrikdatenstruktur

Jeder Satz von Metrikwerten ist eine Zeitreihe mit den folgenden Merkmalen:

  • Zeitpunkt, zu dem der Wert erfasst wurde
  • Die Ressource, die dem Wert zugeordnet ist
  • Namespace, der wie eine Kategorie für die Metrik fungiert
  • Metrikname
  • Eigentlicher Wert
  • Einige Metriken können mehrere Dimensionen aufweisen, wie unter Mehrdimensionale Metriken beschrieben. Benutzerdefinierte Metriken können über bis zu 10 Dimensionen verfügen.

Threadsicherheit

Alle Client-instance Methoden sind threadsicher und voneinander unabhängig (Richtlinie). Dieser Entwurf stellt sicher, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Protokollabfrage

Sie können Protokolle nach Arbeitsbereichs-ID oder Ressourcen-ID abfragen. Das Ergebnis wird als Tabelle mit einer Auflistung von Zeilen zurückgegeben.

Arbeitsbereichszentrierte Protokollabfrage

Um nach Arbeitsbereichs-ID abzufragen, verwenden Sie die LogsQueryClient.QueryWorkspaceAsync-Methode :

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

Ressourcenorientierte Protokollabfrage

Um nach Ressourcen-ID abzufragen, verwenden Sie die LogsQueryClient.QueryResourceAsync-Methode .

So suchen Sie die Ressourcen-ID:

  1. Navigieren Sie im Azure-Portal zur Seite Ihrer Ressource.
  2. Wählen Sie auf dem Blatt Übersicht den Link JSON-Ansicht aus.
  3. Kopieren Sie im resultierenden JSON-Code den Wert der id Eigenschaft.
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);
}

Behandeln von Protokollabfrageantworten

Die QueryWorkspace -Methode gibt zurück, LogsQueryResultwährend die QueryBatch -Methode den LogsBatchQueryResultzurückgibt. Hier sehen Sie eine Hierarchie der Antwort:

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

Zuordnen von Protokollabfrageergebnissen zu einem Modell

Sie können Protokollabfrageergebnisse einem Modell mit der LogsQueryClient.QueryWorkspaceAsync<T> -Methode zuordnen:

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

Zuordnen von Protokollabfrageergebnissen zu einem Grundtyp

Wenn Ihre Abfrage eine einzelne Spalte (oder einen einzelnen Wert) eines primitiven Typs zurückgibt, verwenden Sie die LogsQueryClient.QueryWorkspaceAsync<T> -Überladung, um sie zu deserialisieren:

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

Sie können die Liste der Spalten auch dynamisch überprüfen. Im folgenden Beispiel wird das Abfrageergebnis als Tabelle ausgegeben:

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

Batchprotokollabfrage

Sie können mehrere Protokollabfragen in einer einzelnen Anforderung mit der LogsQueryClient.QueryBatchAsync -Methode ausführen:

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

Szenarien für erweiterte Protokollabfragen

Festlegen des Abfragetimeouts für Protokolle

Die Ausführung einiger Protokollabfragen dauert länger als 3 Minuten. Das Standardmäßige Servertimeout beträgt 3 Minuten. Sie können das Servertimeout auf maximal 10 Minuten erhöhen. Im folgenden Beispiel wird die LogsQueryOptions -Eigenschaft des ServerTimeout Objekts verwendet, um das Servertimeout auf 10 Minuten festzulegen:

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

Abfragen mehrerer Arbeitsbereiche

Verwenden Sie LogsQueryOptions.AdditionalWorkspaces die -Eigenschaft, um dieselbe Protokollabfrage für mehrere Arbeitsbereiche auszuführen:

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

Statistiken einschließen

So rufen Sie Protokollabfrageausführungsstatistiken ab, z. B. CPU- und Arbeitsspeicherverbrauch:

  1. Setzen Sie die LogsQueryOptions.IncludeStatistics-Eigenschaft auf true.
  2. Rufen Sie die GetStatistics -Methode für das LogsQueryResult -Objekt auf.

Im folgenden Beispiel wird die Abfrageausführungszeit ausgegeben:

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

Da die Struktur der Statistiknutzlast je nach Abfrage variiert, wird ein BinaryData Rückgabetyp verwendet. Sie enthält die unformatierte JSON-Antwort. Die Statistiken befinden sich in der query Eigenschaft des JSON-Objekts. Beispiel:

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

Visualisierung einschließen

So rufen Sie Visualisierungsdaten für Protokollabfragen mithilfe des Renderoperators ab:

  1. Setzen Sie die LogsQueryOptions.IncludeVisualization-Eigenschaft auf true.
  2. Rufen Sie die GetVisualization -Methode für das LogsQueryResult -Objekt auf.

Beispiel:

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

Da die Struktur der Visualisierungsnutzlast je nach Abfrage variiert, wird ein BinaryData Rückgabetyp verwendet. Sie enthält die unformatierte JSON-Antwort. Beispiel:

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

Metrikabfrage

Sie können Metriken für eine Azure-Ressource mit der MetricsQueryClient.QueryResourceAsync -Methode abfragen. Für jede angeforderte Metrik wird ein Satz aggregierter Werte innerhalb der TimeSeries Auflistung zurückgegeben.

Zum Abfragen von Metriken ist eine Ressourcen-ID erforderlich. So suchen Sie die Ressourcen-ID:

  1. Navigieren Sie im Azure-Portal zur Seite Ihrer Ressource.
  2. Wählen Sie auf dem Blatt Übersicht den Link JSON-Ansicht aus.
  3. Kopieren Sie im resultierenden JSON-Code den Wert der id -Eigenschaft.
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);
        }
    }
}

Verarbeiten von Metrikabfrageantworten

Die Metrikabfrage-API gibt ein MetricsQueryResult Objekt zurück. Das MetricsQueryResult -Objekt enthält Eigenschaften wie eine Liste von MetricResult-typisierten Objekten, Cost, Namespace, ResourceRegion, TimeSpanund Interval. Auf die MetricResult Objektliste kann über den metrics Param zugegriffen werden. Jedes MetricResult Objekt in dieser Liste enthält eine Liste von MetricTimeSeriesElement Objekten. Jedes MetricTimeSeriesElement Objekt enthält Metadata Eigenschaften und Values .

Hier sehen Sie eine Hierarchie der Antwort:

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

Abfragemetriken mit Optionen

Ein MetricsQueryOptions -Objekt kann verwendet werden, um präzisere Metrikabfragen zu unterstützen. Betrachten Sie das folgende Beispiel, das eine Azure Key Vault-Ressource mit dem Namen TestVault abfragt. Die Metrik "Vault requests availability" der Ressource wird angefordert, wie in der Metrik-ID "Verfügbarkeit" angegeben. Darüber hinaus ist der Aggregationstyp "Avg" enthalten.

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

Aufteilen einer Metrik nach Dimension

Die MetricsQueryOptions.Filter-Eigenschaft kann zum Aufteilen einer Metrik durch eine Dimension verwendet werden, wenn ihr Filterwert auf ein Sternchen festgelegt ist. Betrachten Sie das folgende Beispiel für eine App Service Ressource namens TestWebApp. Der Code fragt die Metrik der Ressource Http2xx ab und teilt sie nach der Instance Dimension auf.

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

Einen Bestand an Metriken und Dimensionen, die für jeden Azure-Ressourcentyp verfügbar sind, finden Sie unter Unterstützte Metriken mit Azure Monitor.

Registrieren des Clients mit Abhängigkeitsinjektion

Rufen AddLogsQueryClient Sie die -Methode auf, um sich beim Container Dependency Injection (DI) zu registrierenLogsQueryClient. Rufen AddMetricsQueryClient Sie die -Methode auf, um sich beim Container Dependency Injection (DI) zu registrierenMetricsQueryClient. Weitere Informationen finden Sie unter Registrieren des Clients.

Problembehandlung

Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie im Leitfaden zur Problembehandlung.

Nächste Schritte

Weitere Informationen zu Azure Monitor finden Sie in der Dokumentation zum Azure Monitor-Dienst.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. 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. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request übermitteln, ermittelt ein CLA-Bot automatisch, ob Sie eine CLA bereitstellen müssen, und dekoriert den PR entsprechend mit Bezeichnungen und Kommentaren. Folgen Sie den Anweisungen des Bots. Sie müssen die CLA nur einmal für alle Microsoft-Repositorys signieren.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex , oder wenden Sie sich bei opencode@microsoft.com Fragen oder Kommentaren an.

Aufrufe