Protokollieren mit dem Azure SDK für .NETLogging with the Azure SDK for .NET

Mit dem Azure SDK- für .NET-Clientbibliotheken können Sie die Vorgänge in Clientbibliotheken protokollieren.The Azure SDK for .NET client libraries includes the ability to log client library operations. Dies ermöglicht es Ihnen, E/A-Anforderungen und -Antworten zu überwachen, die Clientbibliotheken an Azure-Dienste senden.This allows you to monitor I/O requests and responses that client libraries are making to Azure services. In der Regel werden die Protokolle verwendet, um Kommunikationsprobleme zu debuggen oder zu diagnostizieren.Typically, the logs are used to debug or diagnose communication issues. In diesem Artikel werden drei Ansätze beschrieben, mit denen sich die Protokollierung mit dem Azure SDK für .NET konfigurieren lässt:This article describes three approaches to enable logging with the Azure SDK for .NET:

  • Protokollieren im KonsolenfensterLog to the console window
  • Protokollieren in .NET- DiagnoseablaufverfolgungenLog to .NET diagnostics traces
  • Konfigurieren einer benutzerdefinierten ProtokollierungConfigure custom logging

Wichtig

Dieser Artikel bezieht sich auf die Clientbibliotheken, die die neuesten Versionen des Azure SDK für .NET verwenden.This article applies to client libraries that use the most recent versions of the Azure SDK for .NET. Informationen dazu, ob eine Bibliothek unterstützt wird, finden Sie in der Liste mit den neuesten Azure SDK-Releases.To see if a library is supported, refer to the list of Azure SDK latest releases. Wenn Ihre Anwendung eine ältere Version der Azure SDK-Clientbibliotheken verwendet, finden Sie entsprechende Anweisungen in der jeweiligen Dienstdokumentation.If your application is using an older version of the Azure SDK client libraries, refer to specific instructions in the applicable service documentation.

Protokollieren von InformationenLog information

Das SDK protokolliert die folgenden Informationen und bereinigt die Abfrage- und Headerwerte der Parameter, um personenbezogene Daten zu entfernen.The SDK logs the following information, sanitizing parameter query and header values to remove personal data.

Protokolleintrag der HTTP-Anforderung:HTTP request log entry:

  • Eindeutige IDUnique ID
  • HTTP-MethodeHTTP method
  • URIURI
  • Ausgehende AnforderungsheaderOutgoing request headers

Protokolleintrag der HTTP-Antwort:HTTP response log entry:

  • Dauer des E/A-Vorgangs (verstrichene Zeit)Duration of I/O operation (time elapsed)
  • Anfrage-IDRequest ID
  • HTTP-StatuscodeHTTP status code
  • HTTP-UrsachentextHTTP reason phrase
  • AntwortheaderResponse headers
  • Fehlerinformationen, falls verfügbarError information, when applicable

Bezüglich des Anforderung- und Antwortinhalts:For request and response content:

  • Ob im Inhaltsdatenstrom Text oder Byte übertragen werden, ist abhängig vom Header „Content-Type“.Content stream as text or bytes depending on the Content-Type header.

    [!HINWEIS] Die Inhaltsprotokollierung ist standardmäßig deaktiviert.[!NOTE} Content logging is disabled by default. Legen Sie Diagnostics.IsLoggingContentEnabled in ClientOptions auf true fest, um diese zu aktivieren.To enable it, set Diagnostics.IsLoggingContentEnabled to true in ClientOptions.

Ereignisprotokolle werden in der Regel auf einer der folgenden drei Ebenen ausgegeben:Event logs are output usually at one of these three levels:

  • Informationell, für Anforderungs- und AntwortereignisseInformational for request and response events
  • Warnungen, für FehlerWarning for errors
  • Ausführlich, für detaillierte Meldungen und die InhaltsprotokollierungVerbose for detailed messages and content logging

Aktivieren der Protokollierung mit integrierten MethodenEnable logging with built-in methods

Das Azure SDK für .NET-Clientbibliotheken protokolliert Ereignisse in der Ereignisablaufverfolgung für Windows über die Klasse EventSource, die typisch für .NET ist.The Azure SDK for .NET client libraries log events to Event Tracing for Windows (ETW) via the EventSource class, which is typical for .NET. Mit Ereignisquellen können Sie die strukturierte Protokollierung in Ihrem Anwendungscode mit minimalem Leistungsmehraufwand verwenden.Event sources allow you to use structured logging in your application code with a minimal performance overhead. Sie müssen nur die Ereignislistener registrieren, um Zugriff auf diese Ereignisprotokolle zu erhalten.To gain access to these event logs, you need to register event listeners.

Das SDK enthält die Klasse Azure.Core.Diagnostics.AzureEventSourceListener (definiert im NuGet-Paket „Azure.Core“), die zwei statische Methoden enthält, die die umfassende Protokollierung für Ihre .NET-Anwendung vereinfachen: CreateConsoleLogger und CreateTraceLogger.The SDK includes the Azure.Core.Diagnostics.AzureEventSourceListener class (defined in the Azure.Core NuGet package), which contains two static methods that simplify comprehensive logging for your .NET application: CreateConsoleLogger and CreateTraceLogger. Diese Methoden nehmen einen optionalen Parameter, der eine Protokollebene angibt.These methods take an optional parameter that specifies a log level.

Protokollieren im KonsolenfensterLog to the console window

Eine der Hauptfunktionen des Azure SDK für .NET-Clientbibliotheken besteht darin, die Anzeige von umfassenden Protokollen in Echtzeit zu vereinfachen.A core tenet of the Azure SDK for .NET client libraries is to simplify the ability to view comprehensive logs in real time. Mit der Methode CreateConsoleLogger können Sie Protokolle mit einer einzelnen Codezeile an das Konsolenfenster senden:The CreateConsoleLogger method allows you to send logs to the console window with a single line of code:

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Protokollieren in DiagnoseablaufverfolgungenLog to diagnostic traces

Wenn Sie Ablaufverfolgungslistener implementieren, können Sie mit der Methode CreateTraceLogger in der standardmäßigen .NET-Ereignisablaufverfolgung (System.Diagnostics.Tracing) protokollieren.If you implement trace listeners, you can use the CreateTraceLogger method to log to the standard .NET event tracing mechanism (System.Diagnostics.Tracing). Weitere Informationen zur Ereignisablaufverfolgung in .NET finden Sie unter Ablaufverfolgungslistener.For more information on event tracing in .NET, see Trace Listeners. In diesem Beispiel wird die Protokollebene „Ausführlich“ dargestellt:This example specifies a log level of verbose:

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

Konfigurieren der benutzerdefinierten ProtokollierungConfigure custom logging

Wie bereits erwähnt, müssen Sie Ereignislistener registrieren, um vom Azure SDK für .NET Protokollmeldungen zu empfangen.As mentioned above, you need to register event listeners to receive log messages from the Azure SDK for .NET. Wenn Sie die umfassende Protokollierung nicht mithilfe der oben genannten vereinfachten Methoden implementieren möchten, können Sie eine Instanz der Klasse AzureEventSourceListener erstellen und ihr eine Rückruffunktion übergeben, die Sie schreiben.If you don’t want to implement comprehensive logging using one the simplified methods above, you can construct an instance of the AzureEventSourceListener class and pass it a callback function that you write. Diese Methode empfängt Protokollmeldungen, die Sie nach Bedarf verarbeiten lassen können.This method will receive log messages that you can process however you need to. Wenn Sie die Instanz erstellen, können Sie außerdem die zu berücksichtigenden Protokollebenen angeben.In addition, when you construct the instance, you can specify the log levels to include.

Im folgenden Beispiel wird ein Ereignislistener erstellt, der mit einer benutzerdefinierten Meldung in der Konsole protokolliert und nach wichtigen Azure-Ereignissen der Ebene „Ausführlich“ gefiltert wird.The following example creates an event listener that logs to the console with a custom message, and is filtered to Azure core events of the level verbose.

using AzureEventSourceListener 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);

Nächste SchritteNext steps