Journalisation avec le SDK Azure pour .NET

Le kit de développement logiciel (SDK) Azure pour .NET inclut la capacité d'enregistrer les opérations de la bibliothèque cliente. Cette journalisation vous permet de surveiller les demandes et réponses d’E/S que les bibliothèques clientes effectuent aux services Azure. En règle générale, les logs 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 Kit de développement logiciel (SDK) Azure pour .NET :

Activer la journalisation avec des méthodes intégrées
Configurer la journalisation personnalisée
Mapper à la journalisation dans ASP.NET Core

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. Pour voir si une bibliothèque est prise en charge, consultez la liste des dernières versions du Kit de développement logiciel (SDK) Azure. Si votre application utilise une version antérieure d’une bibliothèque cliente du Kit de développement logiciel (SDK) Azure, reportez-vous à des instructions spécifiques dans la documentation du service applicable.

Enregistrement d’informations

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

Entrée du journal des requêtes HTTP :

ID unique
Méthode HTTP
URI
En-têtes de requête sortants

Entrée du journal de réponse HTTP :

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

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

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

Remarque

La journalisation du contenu est désactivée par défaut. Pour l'activer, consultez Activer la journalisation des corps des requêtes et réponses 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, tels que AMQP, ne prennent pas en charge la journalisation du contenu. Les exemples non pris en charge incluent des bibliothèques pour les services Azure tels que Event Hubs, Service Bus et Web PubSub.

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

Informations relatives aux événements de demande et de réponse
Avertissement concernant les erreurs
Verbosité pour la journalisation détaillée des messages et du contenu

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

Kit de développement logiciel (SDK) Azure pour .NET. Les bibliothèques clientes de .NET consignent les événements dans le suivi des é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 enregistrer des écouteurs d’événements.

Le Kit de développement logiciel (SDK) inclut la Azure.Core.Diagnostics.AzureEventSourceListener classe, 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 est utilisé Informational.

Se connecter à la fenêtre de console

Un principe fondamental du kit de développement logiciel Azure SDK pour les bibliothèques clientes .NET est de simplifier l'affichage de logs détaillés en temps réel. La méthode CreateConsoleLogger vous permet d’envoyer des logs à la fenêtre de console en une seule ligne de code :

using AzureEventSourceListener listener =
    AzureEventSourceListener.CreateConsoleLogger();

Journaliser les traces de diagnostic

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). Pour plus d’informations sur le suivi d’événements dans .NET, consultez Écouteurs de suivi.

Cet exemple spécifie un niveau de journalisation verbeux :

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 Kit de développement logiciel (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 AzureEventSourceListener classe. Transmettez cette instance à une méthode de rappel que vous écrivez. Cette méthode recevra des messages de journal que vous pouvez traiter selon vos besoins. En outre, lorsque vous construisez l’instance, vous pouvez spécifier les niveaux de journalisation à inclure.

L’exemple suivant crée un écouteur d’événements qui se connecte à la console avec un message personnalisé. Les journaux d’activité sont filtrés sur ces é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 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);

Correspondance à la journalisation de ASP.NET Core

Le AzureEventSourceLogForwarder service 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 Kit de développement logiciel (SDK) Azure vers ILoggerFactory.

Le tableau suivant montre comment le Kit de développement logiciel (SDK) Azure pour .NET EventLevel est mappé au ASP.NET Core LogLevel.

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 :

Installez le package NuGet Microsoft.Extensions.Azure :
```
dotnet add package Microsoft.Extensions.Azure
```
Dans Program.cs, inscrivez le client de la bibliothèque du Kit de développement logiciel (SDK) Azure via un appel à la AddAzureClients méthode d’extension :
```
using Azure.Identity;
using Microsoft.Extensions.Azure;

// code omitted for brevity

builder.Services.AddAzureClients(azureBuilder =>
{
    azureBuilder.AddServiceBusClient(
        builder.Configuration.GetConnectionString("ServiceBus"));
});
```
Dans l’exemple précédent, la méthode AddAzureClients :
- Inscrit les objets suivants avec le conteneur d’injection de dépendances (DI) :
  - Service de redirecteur de journal
  - Client du Bus de Service Azure
- Applique DefaultAzureCredential automatiquement pour l’authentification, sauf si des identifiants différents sont configurés explicitement.
Dans appsettings.json, modifiez le niveau de journal par défaut de la bibliothèque Service Bus. Par exemple, basculez-la en Debug définissant la Logging:LogLevel:Azure.Messaging.ServiceBus clé comme suit :
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Comme 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’enregistrement d’un client de bibliothèque Azure SDK dans le conteneur DI est impossible ou inutile :

La bibliothèque du Kit de développement logiciel (SDK) Azure n’inclut pas de méthode d’extension IServiceCollection pour inscrire un client dans le conteneur d’interface de domaine.
Votre application utilise des bibliothèques d’extensions Azure qui dépendent d’autres bibliothèques du Kit de développement logiciel (SDK) Azure. Voici quelques exemples de ces bibliothèques d’extensions Azure :

Dans ces scénarios, procédez comme suit :

Installez le package NuGet Microsoft.Extensions.Azure :
```
dotnet add package Microsoft.Extensions.Azure
```

Dans Program.cs, inscrivez le service de redirecteur de journal en tant que singleton dans le conteneur d’adresses 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());

Récupérez le service de redirecteur de journaux à partir du conteneur d’adresses di et appelez sa Start méthode. Par exemple, en utilisant l'injection de constructeur dans une classe de modèle de pages Razor Pages ASP.NET Core :
```
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Azure;

public class IndexModel : PageModel
{
    public IndexModel(AzureEventSourceLogForwarder logForwarder) =>
        logForwarder.Start();
```
Dans appsettings.json, modifiez le niveau de journal par défaut de la bibliothèque Azure Core. Par exemple, basculez-la en Debug définissant la Logging:LogLevel:Azure.Core clé comme suit :
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Étant donné que la Logging:LogLevel:Azure.Core clé est définie sur Debug, les événements de la bibliothèque Azure Core jusqu’à EventLevel.Verbose seront consignés.

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

Enregistrement des logs à l’aide d’Azure.Monitor.OpenTelemetry.AspNetCore

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

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

Installez le package NuGet Azure.Monitor.OpenTelemetry.AspNetCore :
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
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>");
```
Dans appsettings.json, modifiez le niveau de journal par défaut de la bibliothèque Service Bus. Par exemple, basculez-la en Debug définissant la Logging:LogLevel:Azure.Messaging.ServiceBus clé 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 à 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, tels que AMQP, ne prennent pas en charge la journalisation du contenu. Les exemples non pris en charge incluent des bibliothèques pour les services Azure tels que 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 mentionné ci-dessus est désactivée. Pour activer la journalisation des corps de requête et de réponse HTTP, effectuez les étapes suivantes :

Définissez la propriété IsLoggingContentEnabled de l’objet des options client sur true et transmettez cet objet au constructeur du client. Par exemple, pour consigner les requêtes ET 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);

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

Approche	Les instructions
Activer la journalisation avec des méthodes intégrées	Passer `EventLevel.Verbose` ou `EventLevel.LogAlways` à `AzureEventSourceListener.CreateConsoleLogger` ou `AzureEventSourceListener.CreateTraceLogger`
Configurer la journalisation personnalisée	Définir le paramètre de constructeur de la classe `AzureEventSourceListenerlevel` sur `EventLevel.Verbose` ou `EventLevel.LogAlways`
Cartographie vers la journalisation dans ASP.NET Core	Ajouter `"Azure.Core": "Debug"` à appsettings.json

Étapes suivantes

Activer la journalisation des diagnostics pour les applications dans Azure App Service
Passer en revue les options de journalisation et d’audit de sécurité Azure
Découvrez comment utiliser les journaux de plateforme Azure
En savoir plus sur la journalisation et le suivi .NET

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-03-31