Freigeben über

Protokollierung mit dem Azure SDK für .NET

Das Azure SDK für . Die Clientbibliotheken von NET umfassen die Möglichkeit, Clientbibliotheksvorgänge zu protokollieren. Mit dieser Protokollierung können Sie E/A-Anforderungen und -Antworten überwachen, die Clientbibliotheken an Azure-Dienste vornehmen. In der Regel werden die Protokolle zum Debuggen oder Diagnostizieren von Kommunikationsproblemen verwendet. In diesem Artikel werden die folgenden Ansätze zum Aktivieren der Protokollierung mit dem Azure SDK für .NET beschrieben:

Von Bedeutung

Dieser Artikel bezieht sich auf 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 der neuesten Versionen des Azure SDK. Wenn Ihre App eine ältere Version einer Azure SDK-Clientbibliothek verwendet, lesen Sie spezifische Anweisungen in der entsprechenden Dienstdokumentation.

Protokollieren von Informationen

Das SDK protokolliert jede HTTP-Anforderung und -Antwort, löscht Parameterabfrage- und Headerwerte, um personenbezogene Daten zu entfernen.

HTTP-Anforderungsprotokolleintrag:

  • Eindeutige Kennung
  • HTTP-Methode
  • URI (Uniform Resource Identifier)
  • Header für ausgehende Anforderungen

HTTP-Antwortprotokolleintrag:

  • Dauer des E/A-Vorgangs (verstrichene Zeit)
  • Anfrage-ID
  • HTTP-Statuscode
  • HTTP-Grundausdruck
  • Antwortkopfzeilen
  • Fehlerinformationen, falls zutreffend

HTTP-Anforderungs- und Antwortinhalte:

  • Inhaltsstream als Text oder Bytes je Content-Type nach Kopfzeile.

    Hinweis

    Die Inhaltsprotokollierung ist standardmäßig deaktiviert. Informationen zum Aktivieren finden Sie unter Protokoll-HTTP-Anforderungs- und Antworttexte. 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:

  • Informationen zu Anforderungs- und Antwortereignissen
  • Warnung bei Fehlern
  • Ausführlich für detaillierte Nachrichten und Inhaltsprotokollierung

Aktivieren der Protokollierung mit integrierten Methoden

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

Das SDK enthält die Azure.Core.Diagnostics.AzureEventSourceListener Klasse, 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 eine Protokollebene angibt. Wenn der Parameter nicht angegeben wird, wird die Standardprotokollebene Informational verwendet.

Protokollieren im Konsolenfenster

Ein Kern-Tenet des Azure SDK für .NET-Clientbibliotheken besteht darin, die Möglichkeit zu vereinfachen, umfassende Protokolle in Echtzeit anzuzeigen. Mit der CreateConsoleLogger Methode können Sie Protokolle mit einer einzigen Codezeile an das Konsolenfenster senden:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Protokollieren von Diagnoseablaufverfolgungen

Wenn Sie Ablaufverfolgungslistener implementieren, können Sie die CreateTraceLogger Methode verwenden, um sich beim standardmäßigen .NET-Ereignisablaufverfolgungsmechanismus (System.Diagnostics.Tracing) zu protokollieren. Weitere Informationen zur Ereignisablaufverfolgung in .NET finden Sie unter Trace Listeners.

In diesem Beispiel wird eine Ausführliche Protokollebene angegeben:

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

Konfigurieren der benutzerdefinierten Protokollierung

Wie bereits erwähnt, müssen Sie Ereignislistener registrieren, um Protokollnachrichten aus dem Azure SDK für .NET zu empfangen. Wenn Sie keine umfassende Protokollierung mithilfe einer der oben genannten vereinfachten Methoden implementieren möchten, können Sie eine Instanz der AzureEventSourceListener Klasse erstellen. Übergeben Sie diese Instanz eine Rückrufmethode, die Sie schreiben. Diese Methode empfängt Protokollmeldungen, die Sie verarbeiten können, aber Sie benötigen. Darüber hinaus können Sie beim Erstellen der Instanz die einzuschließden Protokollebenen angeben.

Im folgenden Beispiel wird ein Ereignislistener erstellt, der sich mit einer benutzerdefinierten Nachricht bei der Konsole anmeldet. Die Protokolle werden auf diese Ereignisse gefiltert, die aus der Azure Core-Clientbibliothek mit einer ausführlichen Ebene ausgegeben werden. Die Azure Core-Bibliothek verwendet einen Ereignisquellnamen von 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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

Zuordnung zur ASP.NET Core-Protokollierung

Mit dem AzureEventSourceLogForwarder Dienst können Sie die Standardkonfiguration ASP.NET Core-Protokollierung für die Protokollierung verwenden. Der Dienst leitet Protokollnachrichten aus Azure SDK-Ereignisquellen an ILoggerFactory.

Die folgende Tabelle zeigt, wie das Azure SDK für .NET EventLevel dem ASP.NET Core LogLevelzugeordnet ist.

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 die folgenden Schritte aus, indem Sie die Azure Service Bus-Bibliothek als Beispiel verwenden:

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

    dotnet add package Microsoft.Extensions.Azure

  2. Registrieren Sie in 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 vorherigen Beispiel:AddAzureClients

    • Registriert die folgenden Objekte mit dem Container zum Einfügen von Abhängigkeiten (Dependency Injection, DI):
      • Protokollweiterleitungsdienst
      • Azure Service Bus-Client
    • Legt die Standardtokenanmeldeinformationen fest, die für alle registrierten Clients verwendet werden sollen.

  3. Ändern Sie inappsettings.jsondie Standardprotokollebene der Dienstbusbibliothek. Schalten Sie ihn beispielsweise wie folgt ein 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 Logging:LogLevel:Azure.Messaging.ServiceBus Schlüssel auf Debug"Service Bus"-Clientereignisse festgelegt ist, werden bis zu EventLevel.Verbose diesem Ereignis protokolliert.

Protokollierung ohne Clientregistrierung

Es gibt Szenarien, in denen das Registrieren des Clients einer Azure SDK-Bibliothek mit dem DI-Container entweder unmöglich oder unnötig ist:

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

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

    dotnet add package Microsoft.Extensions.Azure

  2. Registrieren Sie in Program.cs den Protokollweiterleitungsdienst als Singleton im DI-Container:

    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 DI-Container ab, und rufen Sie dessen Start Methode auf. Beispiel: Verwenden der Konstruktoreinfügung in einer ASP.NET Core Razor Pages-Seiten-Seitenmodellklasse:

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

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

  4. Ändern Sie inappsettings.jsondie Standardprotokollebene der Azure Core-Bibliothek. Schalten Sie ihn beispielsweise wie folgt ein 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 Schlüssel auf .

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

Protokollierung mit Azure.Monitor.OpenTelemetry.AspNetCore

Die Azure Monitor OpenTelemetry-Distro, beginnend mit der 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 der Protokollierung in .NET Core und ASP.NET Core erläutert werden.

Führen Sie die folgenden Schritte aus, indem Sie die Azure Service Bus-Bibliothek als Beispiel verwenden:

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

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

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

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

  3. Ändern Sie inappsettings.jsondie Standardprotokollebene der Dienstbusbibliothek. Schalten Sie ihn beispielsweise wie folgt ein 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 Logging:LogLevel:Azure.Messaging.ServiceBus Schlüssel auf Debug"Service Bus"-Clientereignisse festgelegt ist, werden bis zu EventLevel.Verbose diesem Ereignis 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 bei unerwartetem Verhalten mit einer Clientbibliothek ist es hilfreich, die folgenden Elemente zu überprüfen:

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

Standardmäßig ist die Protokollierung der oben genannten Inhalte deaktiviert. Führen Sie die folgenden Schritte aus, um die Protokollierung der HTTP-Anforderungs- und Antworttexte zu aktivieren:

  1. Legen Sie die Eigenschaft des Clientoptionenobjekts IsLoggingContentEnabled auf true, und übergeben Sie das Optionsobjekt an den Konstruktor des Clients. Um beispielsweise HTTP-Anforderungen und -Antworten für die Azure Key Vault Secrets-Bibliothek 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 einer Ereignis-/Protokollebene von ausführlich/debug oder höher. Finden Sie Ihren Ansatz in der folgenden Tabelle, um bestimmte Anweisungen zu erhalten.

    Vorgehensweise Anweisungen
    Aktivieren der Protokollierung mit integrierten Methoden Übergeben EventLevel.Verbose oder EventLevel.LogAlways an AzureEventSourceListener.CreateConsoleLogger oder AzureEventSourceListener.CreateTraceLogger
    Konfigurieren der benutzerdefinierten Protokollierung Festlegen des Konstruktorparameters AzureEventSourceListener der level Klasse auf EventLevel.Verbose oderEventLevel.LogAlways
    Zuordnung zur ASP.NET Core-Protokollierung Zu "Azure.Core": "Debug" hinzufügen

Nächste Schritte