Protokollieren mit dem Azure SDK für .NET

  • Artikel

Die Clientbibliotheken des Azure SDK für .NET umfassen die Möglichkeit, Vorgänge von Clientbibliotheken zu protokollieren. Diese Protokollierung ermöglicht es Ihnen, E/A-Anforderungen und -Antworten zu überwachen, die Clientbibliotheken an Azure-Dienste senden. In der Regel werden die Protokolle verwendet, um Kommunikationsprobleme zu debuggen oder zu diagnostizieren. In diesem Artikel werden die folgenden Ansätze beschrieben, mit denen sich die Protokollierung mit dem Azure SDK für .NET konfigurieren lässt:

Wichtig

Dieser Artikel bezieht sich auf die Clientbibliotheken, die die neuesten Versionen des Azure SDK für .NET verwenden. Informationen dazu, ob eine Bibliothek unterstützt wird, finden Sie in der Liste mit den neuesten Azure SDK-Releases. Wenn Ihre App eine ältere Version einer Azure SDK-Clientbibliothek verwendet, finden Sie spezifische Anweisungen in der entsprechenden Dienstdokumentation.

Protokollieren von Informationen

Das SDK protokolliert jede HTTP-Anforderung und -Antwort und bereinigt die Abfrage- und Headerwerte der Parameter, um personenbezogene Daten zu entfernen.

Protokolleintrag der HTTP-Anforderung:

  • Eindeutige ID
  • HTTP-Methode
  • URI
  • Ausgehende Anforderungsheader

Protokolleintrag der HTTP-Antwort:

  • Dauer des E/A-Vorgangs (verstrichene Zeit)
  • Anfrage-ID
  • HTTP-Statuscode
  • HTTP-Ursachentext
  • Antwortheader
  • Fehlerinformationen, falls verfügbar

HTTP-Anforderung- und -Antwortinhalt:

  • Ob im Inhaltsdatenstrom Text oder Byte übertragen werden, ist abhängig vom Content-Type-Header.

    Hinweis

    Die Inhaltsprotokollierung ist standardmäßig deaktiviert. Informationen zum Aktivieren finden Sie unter Protokollieren von HTTP-Anforderungs- und -Antworttexten. Diese Funktion gilt nur für Bibliotheken, die HTTP für die Kommunikation mit einem Azure-Dienst verwenden. Bibliotheken, die auf alternativen Protokollen wie AMQP basieren, unterstützen die Inhaltsprotokollierung nicht. Nicht unterstützte Beispiele umfassen Bibliotheken für Azure-Dienste wie Event Hubs, Service Bus und Web PubSub.

Ereignisprotokolle werden in der Regel auf einer der folgenden drei Ebenen ausgegeben:

  • Informationell, für Anforderungs- und Antwortereignisse
  • Warnungen, für Fehler
  • Ausführlich, für detaillierte Meldungen und die Inhaltsprotokollierung

Aktivieren der Protokollierung mit integrierten Methoden

Die Clientbibliotheken des Azure SDK für .NET protokollieren Ereignisse in der Ereignisablaufverfolgung für Windows (ETW) über die System.Diagnostics.Tracing.EventSource-Klasse, was typisch für .NET ist. Mit Ereignisquellen können Sie die strukturierte Protokollierung in Ihrer App mit minimalem Leistungsmehraufwand verwenden. Sie müssen nur die Ereignislistener registrieren, um Zugriff auf diese Ereignisprotokolle zu erhalten.

Das SDK enthält die Klasse Azure.Core.Diagnostics.AzureEventSourceListener, die zwei statische Methoden enthält, die die umfassende Protokollierung für Ihre .NET-App vereinfachen: CreateConsoleLogger und CreateTraceLogger. Jede dieser Methoden akzeptiert einen optionalen Parameter, der einen Protokolliergrad angibt. Wenn der Parameter nicht angegeben wird, wird der Standardprotokolliergrad von Informational verwendet.

Protokollieren im Konsolenfenster

Eine der Hauptfunktionen des Azure SDK für .NET-Clientbibliotheken besteht darin, die Anzeige von umfassenden Protokollen in Echtzeit zu vereinfachen. Mit der Methode CreateConsoleLogger können Sie Protokolle mit einer einzelnen Codezeile an das Konsolenfenster senden:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Protokollieren in Diagnoseablaufverfolgungen

Wenn Sie Ablaufverfolgungslistener implementieren, können Sie mit der Methode CreateTraceLogger in der standardmäßigen .NET-Ereignisablaufverfolgung (System.Diagnostics.Tracing) protokollieren. Weitere Informationen zur Ereignisablaufverfolgung in .NET finden Sie unter Ablaufverfolgungslistener.

In diesem Beispiel wird die Protokollebene „Ausführlich“ dargestellt:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateTraceLogger(EventLevel.Verbose);

Konfigurieren der benutzerdefinierten Protokollierung

Wie bereits erwähnt, müssen Sie Ereignislistener registrieren, um vom Azure SDK für .NET Protokollmeldungen zu empfangen. Wenn Sie die umfassende Protokollierung nicht mithilfe der oben genannten vereinfachten Methoden implementieren möchten, können Sie eine Instanz der AzureEventSourceListener-Klasse erstellen. Übergeben Sie eine Rückrufmethode, die Sie schreiben, an diese Instanz. Diese Methode empfängt Protokollmeldungen, die Sie nach Bedarf verarbeiten lassen können. Wenn Sie die Instanz erstellen, können Sie außerdem die zu berücksichtigenden Protokollebenen angeben.

Im folgenden Beispiel wird ein Ereignislistener erstellt, der mit einer benutzerdefinierten Meldung in die Konsole protokolliert. Die Protokolle werden nach diesen Ereignissen gefiltert, die von der Azure Core-Clientbibliothek mit dem Grad „Ausführlich“ ausgegeben werden. Die Azure Core-Bibliothek verwendet den Ereignisquellennamen Azure-Core.

using Azure.Core.Diagnostics;
using System.Diagnostics.Tracing;

// code omitted for brevity

using var listener = new AzureEventSourceListener((e, message) =>
    {
        // Only log messages from "Azure-Core" event source
        if (e.EventSource.Name == "Azure-Core")
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

Zuordnen zur ASP.NET Core-Protokollierung

Mit dem Dienst AzureEventSourceLogForwarder können Sie die ASP.NET Core-Standardprotokollierungskonfiguration für die Protokollierung verwenden. Der Dienst leitet Protokollmeldungen von Azure SDK-Ereignisquellen an ILoggerFactory weiter.

Die folgende Tabelle zeigt, wie EventLevel (Azure SDK für .NET) LogLevel (ASP.NET Core) zugeordnet wird.

Azure SDK EventLevel ASP.NET Core LogLevel
Critical Critical
Error Error
Informational Information
Warning Warning
Verbose Debug
LogAlways Information

Protokollierung mit Clientregistrierung

Führen Sie mit der Azure Service Bus-Bibliothek als Beispiel die folgenden Schritte aus:

  1. Installieren Sie das NuGet-Paket Microsoft.Extensions.Azure:

    dotnet add package Microsoft.Extensions.Azure

  2. Registrieren Sie in der Datei Program.cs den Client der Azure SDK-Bibliothek über einen Aufruf der AddAzureClients-Erweiterungsmethode:

    using Azure.Identity;
using Microsoft.Extensions.Azure;

// code omitted for brevity

builder.Services.AddAzureClients(azureBuilder =>
{
    azureBuilder.AddServiceBusClient(
        builder.Configuration.GetConnectionString("ServiceBus"));
    azureBuilder.UseCredential(new DefaultAzureCredential());
});

    Im vorangehenden Beispiel erledigt die AddAzureClients-Methode Folgendes:

    • Registrieren der folgenden Objekte mit dem Container für die Abhängigkeitsinjektion:
      • Protokollweiterleitungsdienst
      • Azure Service Bus-Client
    • Festlegen der Anmeldeinformationen des Standardtokens, die für alle registrierten Clients verwendet werden sollen.

  3. Ändern Sie in appsettings.json den Standardprotokolliergrad der Service Bus-Bibliothek. Ändern Sie sie beispielsweise in Debug, indem Sie den Logging:LogLevel:Azure.Messaging.ServiceBus-Schlüssel wie folgt festlegen:

    {
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}

    Da der Schlüssel Logging:LogLevel:Azure.Messaging.ServiceBus auf Debug festgelegt ist, werden Service Bus-Clientereignisse bis EventLevel.Verbose protokolliert.

Protokollierung ohne Clientregistrierung

Es gibt Szenarien, in denen die Registrierung des Clients einer Azure SDK-Bibliothek beim Container für die Abhängigkeitsinjektion entweder unmöglich oder unnötig ist:

Führen Sie in diesen Szenarien die folgenden Schritte aus:

  1. Installieren Sie das NuGet-Paket Microsoft.Extensions.Azure:

    dotnet add package Microsoft.Extensions.Azure

  2. Registrieren Sie in Program.cs den Protokollweiterleitungsdienst als Singleton im Container für die Abhängigkeitsinjektion:

    using Azure.Identity;
using Microsoft.AspNetCore.DataProtection;
using Microsoft.Extensions.Azure;
using Microsoft.Extensions.DependencyInjection.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.TryAddSingleton<AzureEventSourceLogForwarder>();

builder.Services.AddDataProtection()
    .PersistKeysToAzureBlobStorage("<connection_string>", "<container_name>", "keys.xml")
    .ProtectKeysWithAzureKeyVault(new Uri("<uri>"), new DefaultAzureCredential());

  3. Rufen Sie den Protokollweiterleitungsdienst aus dem Container für die Abhängigkeitsinjektion ab, und rufen Sie seine Start-Methode auf. Beispiel: Verwenden der Konstruktorinjektion in einer ASP.NET Core Razor Pages-Seitenmodellklasse:

    using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Azure;

public class IndexModel : PageModel
{
    public IndexModel(AzureEventSourceLogForwarder logForwarder) =>
        logForwarder.Start();

  4. Ändern Sie in appsettings.json den Standardprotokolliergrad der Azure Core-Bibliothek. Ändern Sie sie beispielsweise in Debug, indem Sie den Logging:LogLevel:Azure.Core-Schlüssel wie folgt festlegen:

    {
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}

    Da der Logging:LogLevel:Azure.Core-Schlüssel auf Debug festgelegt ist, werden Azure Core-Bibliotheksereignisse bis zum Grad EventLevel.Verbose protokolliert.

Weitere Informationen finden Sie unter Protokollieren in .NET Core und ASP.NET Core.

Protokollieren mit Azure.Monitor.OpenTelemetry.AspNetCore

Die Azure Monitor OpenTelemetry-Distribution, beginnend mit Version 1.2.0, unterstützt das Erfassen von Protokollen aus Azure-Clientbibliotheken. Sie können die Protokollierung mithilfe einer der Konfigurationsoptionen steuern, die in Protokollierung in .NET Core und ASP.NET Core erläutert werden.

Führen Sie mit der Azure Service Bus-Bibliothek als Beispiel die folgenden Schritte aus:

  1. Installieren Sie das NuGet Paket Azure.Monitor.OpenTelemetry.AspNetCore:

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Erstellen oder registrieren Sie den Client der Bibliothek. Die Distribution unterstützt beide Fälle.

    await using var client = new ServiceBusClient("<connection_string>");

  3. Ändern Sie in appsettings.json den Standardprotokolliergrad der Service Bus-Bibliothek. Ändern Sie sie beispielsweise in Debug, indem Sie den Logging:LogLevel:Azure.Messaging.ServiceBus-Schlüssel wie folgt festlegen:

    {
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}

    Da der Schlüssel Logging:LogLevel:Azure.Messaging.ServiceBus auf Debug festgelegt ist, werden Service Bus-Clientereignisse bis EventLevel.Verbose protokolliert.

Protokollieren von HTTP-Anforderungs- und -Antworttexten

Hinweis

Diese Funktion gilt nur für Bibliotheken, die HTTP für die Kommunikation mit einem Azure-Dienst verwenden. Bibliotheken, die auf alternativen Protokollen wie AMQP basieren, unterstützen die Inhaltsprotokollierung nicht. Nicht unterstützte Beispiele umfassen Bibliotheken für Azure-Dienste wie Event Hubs, Service Bus und Web PubSub.

Bei der Problembehandlung von unerwartetem Verhalten einer Clientbibliothek ist es hilfreich, die folgenden Elemente zu untersuchen:

  • Den HTTP-Anforderungstext, der an die zugrunde liegende REST-API des Azure-Diensts gesendet wurde.
  • Den HTTP-Antworttext, der von der REST-API des Azure-Diensts empfangen wurde.

Die Protokollierung der oben genannten Inhalte ist standardmäßig deaktiviert. Um die Protokollierung der HTTP-Anforderungs- und -Antworttexte zu aktivieren, führen Sie die folgenden Schritte aus:

  1. Legen Sie die IsLoggingContentEnabled-Eigenschaft des Objekts für Clientoptionen auf true fest, und übergeben Sie das Objekt für Optionen an den Konstruktor des Clients. Um beispielsweise HTTP-Anforderungen und -Antworten für die Bibliothek der Azure Key Vault-Geheimnisse zu protokollieren:

    var clientOptions = new SecretClientOptions
{
    Diagnostics = 
    {
        IsLoggingContentEnabled = true,
    }
};
var client = new SecretClient(
    new Uri("https://<keyvaultname>.vault.azure.net/"),
    new DefaultAzureCredential(),
    clientOptions);

  2. Verwenden Sie Ihren bevorzugten Protokollierungsansatz mit einem Ereignis-/Protokolliergrad von „ausführlich/debuggen“ oder höher. Spezifische Anweisungen finden Sie in der folgenden Tabelle unter Ihrem Ansatz.

    Vorgehensweise Instructions
    Aktivieren der Protokollierung mit integrierten Methoden Übergeben von EventLevel.Verbose oder EventLevel.LogAlways an AzureEventSourceListener.CreateConsoleLogger oder AzureEventSourceListener.CreateTraceLogger
    Konfigurieren der benutzerdefinierten Protokollierung Festlegen des Konstruktorparameters level der AzureEventSourceListener-Klasse auf EventLevel.Verbose oder EventLevel.LogAlways
    Zuordnen zur ASP.NET Core-Protokollierung Hinzufügen von "Azure.Core": "Debug" zu appsettings.json

Nächste Schritte