Journalisation avec le SDK Azure pour .NET

  • Article

Les bibliothèques clientes du SDK Azure pour .NET incluent la possibilité de journaliser les opérations de bibliothèque cliente. Cette journalisation vous permet de surveiller les demandes d’E/S et les réponses que les bibliothèques clientes effectuent aux services Azure. En règle générale, les journaux sont utilisés pour déboguer ou diagnostiquer les problèmes de communication. Cet article décrit les approches suivantes pour activer la journalisation avec le SDK Azure pour .NET :

Important

Cet article s’applique aux bibliothèques de client qui utilisent les versions les plus récentes du kit SDK Azure pour .NET. Pour voir si une bibliothèque est prise en charge, consultez la liste des dernières versions d’Azure SDK. Si votre application utilise une version antérieure d’une bibliothèque de client Azure SDK, consultez les instructions spécifiques dans la documentation de service applicable.

Enregistrement d’informations

Le SDK journalise chaque requête et chaque réponse HTTP, en assainissant les valeurs d’en-tête et de requête des paramètres pour supprimer les données personnelles.

Entrée du journal des requêtes HTTP :

  • ID unique
  • HTTP method
  • URI
  • En-têtes de requête sortants

Entrée de journal des réponses HTTP :

  • Durée de l’opération d’E/S (temps écoulé)
  • ID de la demande
  • Code d’état HTTP
  • Expression de motif HTTP
  • En-têtes de réponse
  • Informations sur l’erreur, le cas échéant

Contenu de la requête et de la réponse HTTP :

  • Flux de contenu sous forme de texte ou d’octets en fonction de l’en-tête Content-Type.

    Notes

    Le journal de contenu est désactivé par défaut. Pour l’activer, consultez Consigner les corps de requête et de réponse HTTP. Cette fonctionnalité s’applique uniquement aux bibliothèques utilisant HTTP pour communiquer avec un service Azure. Les bibliothèques basées sur d’autres protocoles, comme AMQP, ne prennent pas en charge la journalisation du contenu. Les exemples non pris en charge sont notamment les bibliothèques pour les services Azure comme Event Hubs, Service Bus et Web PubSub.

Les journaux d’événements sont généralement générés à l’un des trois niveaux suivants :

  • Informations sur les événements de demande et de réponse
  • Avertissement en cas d’erreurs
  • Commentaires pour la journalisation détaillée des messages et du contenu

Activer la journalisation avec les méthodes intégrées

Les bibliothèques clientes du SDK Azure pour .NET consignent les événements dans le suivi d’événements pour Windows (ETW) via la classe System.Diagnostics.Tracing.EventSource, ce qui est typique pour .NET. Les sources d’événements vous permettent d’utiliser la journalisation structurée dans votre application avec une surcharge de performances minimale. Pour accéder aux journaux des événements, vous devez inscrire des écouteurs d’événements.

Le SDK inclut la classe Azure.Core.Diagnostics.AzureEventSourceListener, qui contient deux méthodes statiques qui simplifient la journalisation complète pour votre application .NET : CreateConsoleLogger et CreateTraceLogger. Chacune de ces méthodes accepte un paramètre facultatif qui spécifie un niveau de journalisation. Si le paramètre n’est pas fourni, le niveau de journal par défaut de Informational est utilisé.

Se connecter à la fenêtre de console

L’un des principes fondamentaux des bibliothèques clientes du SDK Azure pour .NET consiste à simplifier la possibilité d’afficher des journaux complets en temps réel. La méthode CreateConsoleLogger vous permet d’envoyer des journaux à la fenêtre de console avec une seule ligne de code :

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Journaliser les traces de diagnostic

Si vous implémentez des écouteurs de trace, vous pouvez utiliser la méthode CreateTraceLogger pour journaliser le mécanisme de suivi d’événements .NET standard (System.Diagnostics.Tracing). Pour plus d’informations sur le suivi d’événements dans .NET, consultez Écouteurs de trace.

Cet exemple spécifie un niveau de journalisation détaillé :

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

Configurer la journalisation personnalisée

Comme mentionné ci-dessus, vous devez inscrire des écouteurs d’événements pour recevoir des messages de journal du SDK Azure pour .NET. Si vous ne souhaitez pas implémenter la journalisation complète à l’aide de l’une des méthodes simplifiées ci-dessus, vous pouvez construire une instance de la classe AzureEventSourceListener. Transmettez à cette instance une méthode de rappel que vous écrivez. Cette méthode recevra des messages de journal que vous pouvez traiter comme vous le souhaitez. En outre, lorsque vous construisez l’instance, vous pouvez spécifier les niveaux de journal à inclure.

L’exemple suivant crée un écouteur d’événements qui journalise dans la console avec un message personnalisé. Les journaux sont filtrés sur les événements émis à partir de la bibliothèque cliente Azure Core avec un niveau détaillé. La bibliothèque Azure Core utilise un nom de source d’événement de 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);

Mappage sur la journalisation ASP.NET Core

Le service AzureEventSourceLogForwarder vous permet d’utiliser la configuration de journalisation standard ASP.NET Core pour la journalisation. Le service transfère les messages de journal des sources d’événements du SDK Azure à ILoggerFactory.

Le tableau suivant montre comment le EventLevel du SDK Azure pour .NET est mappé au LogLevel ASP.NET Core.

Kit de développement logiciel (SDK) Azure EventLevel ASP.NET Core LogLevel
Critical Critical
Error Error
Informational Information
Warning Warning
Verbose Debug
LogAlways Information

Journalisation avec inscription du client

À l’aide de la bibliothèque Azure Service Bus comme exemple, effectuez les étapes suivantes :

  1. Installez le package NuGet Microsoft.Extensions.Azure :

    dotnet add package Microsoft.Extensions.Azure

  2. Dans Program.cs, inscrivez le client de la bibliothèque SDK Azure via un appel à la méthode d’extension AddAzureClients :

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

    Dans l’exemple précédent, la méthode AddAzureClients :

    • Inscrit les objets suivants auprès du conteneur d’injection de dépendances :
      • Service de redirecteur de journaux
      • Client Azure Service Bus
    • Définit les informations d’identification de jeton par défaut à utiliser pour tous les clients inscrits.

  3. Dans appsettings.json, modifiez le niveau de journal par défaut de la bibliothèque Service Bus. Par exemple, basculez-le sur Debug en définissant la clé Logging:LogLevel:Azure.Messaging.ServiceBus comme suit :

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

    Étant donné que la clé Logging:LogLevel:Azure.Messaging.ServiceBus est définie sur Debug, les événements du client Service Bus jusqu’à EventLevel.Verbose seront consignés.

Journalisation sans inscription du client

Il existe des scénarios dans lesquels l’inscription du client d’une bibliothèque SDK Azure auprès du conteneur DI est impossible ou inutile :

Dans ces scénarios, effectuez les étapes suivantes :

  1. Installez le package NuGet Microsoft.Extensions.Azure :

    dotnet add package Microsoft.Extensions.Azure

  2. Dans Program.cs, inscrivez le service de redirecteur de journaux en tant que singleton dans le conteneur DI :

    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. Récupérez le service de redirecteur de journaux à partir du conteneur DI et appelez sa méthode Start. Par exemple, l’utilisation de l’injection de constructeur dans une classe de modèle de page Razor Pages ASP.NET Core :

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

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

  4. Dans appsettings.json, modifiez le niveau de journal par défaut de la bibliothèque Azure Core. Par exemple, basculez-le sur Debug en définissant la clé Logging:LogLevel:Azure.Core comme suit :

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

    Étant donné que la clé Logging:LogLevel:Azure.Core est définie sur Debug, les événements de bibliothèque Azure Core jusqu’à EventLevel.Verbose sont consignés.

Pour plus d’informations, consultez Journalisation dans .NET Core et ASP.NET Core.

Journaliser en utilisant Azure.Monitor.OpenTelemetry.AspNetCore

La distribution OpenTelemetry Azure Monitor, à partir de la version 1.2.0, prend en charge la capture des journaux provenant des bibliothèques de client Azure. Vous pouvez contrôler la journalisation en utilisant une des options de configuration décrites dans Journalisation dans .NET Core et ASP.NET Core.

À l’aide de la bibliothèque Azure Service Bus comme exemple, effectuez les étapes suivantes :

  1. Installez le package NuGet Azure.Monitor.OpenTelemetry.AspNetCore :

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Créez ou inscrivez le client de la bibliothèque. La distribution prend en charge les deux cas.

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

  3. Dans appsettings.json, modifiez le niveau de journal par défaut de la bibliothèque Service Bus. Par exemple, basculez-le sur Debug en définissant la clé Logging:LogLevel:Azure.Messaging.ServiceBus comme suit :

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

    Étant donné que la clé Logging:LogLevel:Azure.Messaging.ServiceBus est définie sur Debug, les événements du client Service Bus jusqu’à EventLevel.Verbose seront consignés.

Journaliser les corps de requête et de réponse HTTP

Remarque

Cette fonctionnalité s’applique uniquement aux bibliothèques utilisant HTTP pour communiquer avec un service Azure. Les bibliothèques basées sur d’autres protocoles, comme AMQP, ne prennent pas en charge la journalisation du contenu. Les exemples non pris en charge sont notamment les bibliothèques pour les services Azure comme Event Hubs, Service Bus et Web PubSub.

Lors de la résolution des problèmes de comportement inattendu avec une bibliothèque cliente, il est utile d’inspecter les éléments suivants :

  • Corps de la requête HTTP envoyé à l’API REST du service Azure sous-jacent.
  • Corps de réponse HTTP reçu de l’API REST du service Azure.

Par défaut, la journalisation du contenu susmentionné est désactivée. Pour activer la journalisation des corps de requête et de réponse HTTP, procédez comme suit :

  1. Définissez la propriété IsLoggingContentEnabled de l’objet options du client sur true et passez l’objet options au constructeur du client. Par exemple, pour journaliser les requêtes et les réponses HTTP pour la bibliothèque de secrets Azure Key Vault :

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

  2. Utilisez votre approche de journalisation préférée avec un niveau événement/journal détaillé/débogage ou supérieur. Recherchez votre approche dans le tableau suivant pour obtenir des instructions spécifiques.

    Approche Instructions
    Activer la journalisation avec les méthodes intégrées Passez EventLevel.Verbose ou EventLevel.LogAlways à AzureEventSourceListener.CreateConsoleLogger ou AzureEventSourceListener.CreateTraceLogger
    Configurer la journalisation personnalisée Définissez le paramètre de constructeur level de la classe AzureEventSourceListener sur EventLevel.Verbose ou EventLevel.LogAlways
    Mappage sur la journalisation ASP.NET Core Ajoutez "Azure.Core": "Debug" à appsettings.json

Étapes suivantes