Journalisation avec le Kit de développement logiciel (SDK) Azure pour .NET

Kit de développement logiciel (SDK) Azure pour . Les bibliothèques clientes de NET incluent la possibilité de journaliser les opérations de bibliothèque de client. 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 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 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 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 les corps de requête et de réponse HTTP du journal. 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 pour les erreurs
Détaillé 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 . Les bibliothèques clientes de NET consignent les événements dans le suivi des événements pour Windows (ETW) via la System.Diagnostics.Tracing.EventSource classe, 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 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 journal. Si le paramètre n’est pas fourni, le niveau de journal par défaut est Informational utilisé.

Se connecter à la fenêtre de console

L’ensemble principal du Kit de développement logiciel (SDK) Azure pour les bibliothèques clientes .NET consiste à simplifier la possibilité d’afficher des journaux complets en temps réel. La CreateConsoleLogger méthode 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 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 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 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 reçoit des messages de journal que vous pouvez traiter toutefois. 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 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);

Mapper à la journalisation 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 AddAzureClients méthode :
- Inscrit les objets suivants avec le conteneur d’injection de dépendances (DI) :
  - Service de redirecteur de journal
  - Client Azure Service Bus
- 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": "*"
}
```
Étant donné que la Logging:LogLevel:Azure.Messaging.ServiceBus clé est définie Debugsur , les événements du client Service Bus jusqu’à EventLevel.Verbose ce qu’ils soient consignés.

Journalisation sans inscription du client

Il existe des scénarios dans lesquels l’inscription d’un client de bibliothèque de sdk Azure auprès du conteneur d’adresses de messagerie 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, à l’aide de l’injection de constructeur dans une classe de modèle de page Pages Razor Core ASP.NET :
```
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 Debugsur , les événements de bibliothèque Azure Core jusqu’à EventLevel.Verbose ce qu’ils soient enregistrés.

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

Journalisation à 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 Logging:LogLevel:Azure.Messaging.ServiceBus clé est définie Debugsur , les événements du client Service Bus jusqu’à EventLevel.Verbose ce qu’ils soient 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é IsLoggingContentEnabledde l’objet true options client sur et transmettez l’objet options 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	`EventLevel.Verbose` Passer ou `EventLevel.LogAlways` à `AzureEventSourceListener.CreateConsoleLoggerAzureEventSourceListener.CreateTraceLogger`
Configurer la journalisation personnalisée	Définir le paramètre de constructeur de `AzureEventSourceListener` la `level` classe sur `EventLevel.Verbose` ou`EventLevel.LogAlways`
Mapper à la journalisation 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 2025-05-08