Journalisation avec le kit de développement logiciel (SDK) Azure pour .NETLogging with the Azure SDK for .NET

Le Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes .net offre la possibilité de journaliser les opérations de la bibliothèque cliente.The Azure SDK for .NET client libraries includes the ability to log client library operations. Cela vous permet de surveiller les demandes d’e/s et les réponses que les bibliothèques clientes effectuent aux services Azure.This allows you to monitor I/O requests and responses that client libraries are making to Azure services. En règle générale, les journaux sont utilisés pour déboguer ou diagnostiquer des problèmes de communication.Typically, the logs are used to debug or diagnose communication issues. Cet article décrit trois approches pour activer la journalisation avec le kit de développement logiciel (SDK) Azure pour .NET :This article describes three approaches to enable logging with the Azure SDK for .NET:

  • Consigner dans la fenêtre de consoleLog to the console window
  • Journalisation des traces de Diagnostics .NETLog to .NET diagnostics traces
  • Configurer la journalisation personnaliséeConfigure custom logging

Important

Cet article s’applique aux bibliothèques clientes qui utilisent les versions les plus récentes du kit de développement logiciel (SDK) Azure pour .NET.This article applies to client libraries that use the most recent versions of the Azure SDK for .NET. Pour savoir si une bibliothèque est prise en charge, reportez-vous à la liste des versions les plus récentes du SDK Azure.To see if a library is supported, refer to the list of Azure SDK latest releases. Si votre application utilise une version antérieure des bibliothèques de client du SDK Azure, reportez-vous aux instructions spécifiques de la documentation du service applicable.If your application is using an older version of the Azure SDK client libraries, refer to specific instructions in the applicable service documentation.

Enregistrement d’informationsLog information

Le kit de développement logiciel (SDK) enregistre les informations suivantes, en assainiant les valeurs d’en-tête et de requête de paramètre pour supprimer les données personnelles.The SDK logs the following information, sanitizing parameter query and header values to remove personal data.

Entrée du journal de la requête HTTP :HTTP request log entry:

  • ID uniqueUnique ID
  • HTTP methodHTTP method
  • URIURI
  • En-têtes de demande sortantsOutgoing request headers

Entrée du journal de réponse HTTP :HTTP response log entry:

  • Durée de l’opération d’e/s (temps écoulé)Duration of I/O operation (time elapsed)
  • ID de la demandeRequest ID
  • Code d'état HTTPHTTP status code
  • Phrase de raison HTTPHTTP reason phrase
  • En-têtes de réponseResponse headers
  • Informations sur l’erreur, le cas échéantError information, when applicable

Pour le contenu de la demande et de la réponse :For request and response content:

  • Flux de contenu sous forme de texte ou d’octets en fonction de l’en-tête Content-type.Content stream as text or bytes depending on the Content-Type header.

    [! Remarque} la journalisation du contenu est désactivée par défaut.[!NOTE} Content logging is disabled by default. Pour l’activer, affectez à la valeur Diagnostics.IsLoggingContentEnabled true dans ClientOptions .To enable it, set Diagnostics.IsLoggingContentEnabled to true in ClientOptions.

Les journaux des événements sont généralement générés à l’un de ces trois niveaux :Event logs are output usually at one of these three levels:

  • Informations pour les événements de demande et de réponseInformational for request and response events
  • Avertissement pour les erreursWarning for errors
  • Commentaires pour les messages détaillés et la journalisation du contenuVerbose for detailed messages and content logging

Activer la journalisation avec les méthodes intégréesEnable logging with built-in methods

Le kit de développement logiciel (SDK) Azure pour les bibliothèques clientes .NET enregistre les événements à Suivi d’v nements pour Windows (ETW) via la EventSource classe, qui est classique pour .net.The Azure SDK for .NET client libraries log events to Event Tracing for Windows (ETW) via the EventSource class, which is typical for .NET. Les sources d’événements vous permettent d’utiliser la journalisation structurée dans votre code d’application avec une surcharge de performances minimale.Event sources allow you to use structured logging in your application code with a minimal performance overhead. Pour accéder à ces journaux des événements, vous devez enregistrer les écouteurs d’événements.To gain access to these event logs, you need to register event listeners.

Le kit de développement logiciel (SDK) inclut la Azure.Core.Diagnostics.AzureEventSourceListener classe (définie dans le package NuGet Azure. Core), qui contient deux méthodes statiques qui simplifient la journalisation complète de votre application .net : CreateConsoleLogger et 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. Ces méthodes prennent un paramètre facultatif qui spécifie un niveau de journalisation.These methods take an optional parameter that specifies a log level.

Consigner dans la fenêtre de consoleLog to the console window

Un principe fondamental du kit de développement logiciel (SDK) Azure pour les bibliothèques clientes .NET est de simplifier la possibilité d’afficher des journaux complets en temps réel.A core tenet of the Azure SDK for .NET client libraries is to simplify the ability to view comprehensive logs in real time. La CreateConsoleLogger méthode vous permet d’envoyer des journaux à la fenêtre de console à l’aide d’une seule ligne de code :The CreateConsoleLogger method allows you to send logs to the console window with a single line of code:

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Consigner dans les suivis de diagnosticLog to diagnostic traces

Si vous implémentez des écouteurs de suivi, vous pouvez utiliser la CreateTraceLogger méthode pour vous connecter au mécanisme de suivi d’événements .NET standard ( System.Diagnostics.Tracing ).If you implement trace listeners, you can use the CreateTraceLogger method to log to the standard .NET event tracing mechanism (System.Diagnostics.Tracing). Pour plus d’informations sur le suivi d’événements dans .NET, consultez écouteurs de suivi.For more information on event tracing in .NET, see Trace Listeners. Cet exemple spécifie un niveau de journal détaillé :This example specifies a log level of verbose:

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

Configurer la journalisation personnaliséeConfigure custom logging

Comme indiqué ci-dessus, vous devez enregistrer les écouteurs d’événements pour recevoir des messages du journal à partir du kit de développement logiciel (SDK) Azure pour .NET.As mentioned above, you need to register event listeners to receive log messages from the Azure SDK for .NET. Si vous ne souhaitez pas implémenter une journalisation complète à l’aide d’une des méthodes simplifiées ci-dessus, vous pouvez construire une instance de la AzureEventSourceListener classe et la passer à une fonction de rappel que vous écrivez.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. Cette méthode recevra les messages du journal que vous pouvez traiter, mais vous devez le faire.This method will receive log messages that you can process however you need to. En outre, lorsque vous construisez l’instance, vous pouvez spécifier les niveaux de journalisation à inclure.In addition, when you construct the instance, you can specify the log levels to include.

L’exemple suivant crée un écouteur d’événements qui se connecte à la console à l’aide d’un message personnalisé, et est filtré en événements Azure Core de niveau détaillé.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);

Étapes suivantesNext steps