Registrazione con Azure SDK per .NET

  • Articolo

Le librerie client di Azure SDK per .NET consentono di registrare le operazioni della libreria client. Questa registrazione consente di monitorare le richieste di I/O e le risposte delle librerie client nei servizi di Azure. In genere, i log vengono usati per eseguire il debug o diagnosticare i problemi di comunicazione. Questo articolo descrive gli approcci seguenti per abilitare la registrazione con Azure SDK per .NET:

Importante

Questo articolo si applica alle librerie client che usano le versioni più recenti di Azure SDK per .NET. Per verificare se è supportata una libreria, vedere l'elenco delle versioni più recenti di Azure SDK. Se l'app usa una versione precedente di una libreria client di Azure SDK, vedere istruzioni specifiche nella documentazione del servizio applicabile.

Informazioni sui log

L'SDK registra ogni richiesta e risposta HTTP, purificando i valori di query e intestazione dei parametri per rimuovere i dati personali.

Voce del log per le richieste HTTP:

  • ID univoco
  • Metodo HTTP
  • URI
  • Intestazioni della richiesta in uscita

Voce del log per le risposte HTTP:

  • Durata dell'operazione di I/O (tempo trascorso)
  • ID richiesta
  • Codice di stato HTTP
  • Frase del motivo HTTP
  • Intestazioni della risposta
  • Informazioni sull'errore, se applicabile

Contenuto di richiesta e risposta HTTP:

  • Flusso del contenuto come testo o byte a seconda dell'intestazione Content-Type.

    Nota

    La registrazione del contenuto è disabilitata per impostazione predefinita. Per abilitarla, vedere Registrare i corpi di richiesta e risposta HTTP. Questa funzionalità si applica solo alle librerie che usano HTTP per comunicare con un servizio di Azure. Le librerie basate su protocolli alternativi, ad esempio AMQP, non supportano la registrazione del contenuto. Gli esempi non supportati includono librerie per i servizi di Azure, ad esempio Hub eventi, bus di servizio e Web PubSub.

I log eventi vengono in genere restituiti a uno dei tre livelli seguenti:

  • Informazioni per gli eventi di richiesta e risposta
  • Avviso per gli errori
  • Dettagliato per i messaggi dettagliati e la registrazione del contenuto

Abilitare la registrazione con metodi predefiniti

Le librerie client di Azure SDK per .NET registrano gli eventi in Event Trace for Windows (ETW) tramite la classe System.Diagnostics.Tracing.EventSource, tipica per .NET. Le origini eventi consentono di usare la registrazione strutturata nell'app con un sovraccarico minimo delle prestazioni. Per ottenere l'accesso ai registri eventi, è necessario registrare i listener di eventi.

L'SDK include la classe Azure.Core.Diagnostics.AzureEventSourceListener, che contiene due metodi statici che semplificano la registrazione completa per l'app .NET: CreateConsoleLogger e CreateTraceLogger. Ognuno di questi metodi accetta un parametro facoltativo che specifica un livello di log. Se il parametro non viene specificato, viene usato il livello di log Informational predefinito.

Registrare nella finestra della console

Le librerie client di Azure SDK per .NET semplificano la possibilità di visualizzare log completi in tempo reale. Il metodo CreateConsoleLogger consente di inviare i log alla finestra della console con una singola riga di codice:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Registrare nelle tracce di diagnostica

Se si implementano listener di traccia, è possibile usare il metodo CreateTraceLogger per accedere al meccanismo di traccia eventi .NET standard (System.Diagnostics.Tracing). Per altre informazioni sulla traccia di eventi in .NET, vedere Listener di traccia.

Questo esempio specifica un livello di log dettagliato:

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

Configurare la registrazione personalizzata

Come accennato in precedenza, è necessario registrare i listener di eventi per ricevere messaggi di log da Azure SDK per .NET. Se non si vuole implementare la registrazione completa usando uno dei metodi semplificati precedenti, è possibile costruire un'istanza della classe AzureEventSourceListener. Passare all'istanza di un metodo di callback scritto dall'utente. Questo metodo riceverà messaggi di log che è possibile elaborare quando necessario. Inoltre, quando si costruisce l'istanza, è possibile specificare i livelli di log da includere.

Nell'esempio seguente viene creato un listener di eventi che registra nella console con un messaggio personalizzato. I log vengono filtrati in base a tali eventi generati dalla libreria client di Azure Core con un livello dettagliato. La libreria di Azure Core usa il nome di origine evento 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);

Eseguire il mapping alla registrazione di ASP.NET Core

Il servizio AzureEventSourceLogForwarder consente di usare la configurazione di registrazione standard ASP.NET Core per la registrazione. Il servizio inoltra i messaggi di log dalle origini eventi di Azure SDK a ILoggerFactory.

La tabella seguente illustra il mapping di EventLevel in Azure SDK per .NET a LogLevel in ASP.NET Core.

EventLevel Azure SDK ASP.NET Core LogLevel
Critical Critical
Error Error
Informational Information
Warning Warning
Verbose Debug
LogAlways Information

Registrazione con registrazione client

Usando la libreria del bus di servizio di Azure come esempio, completare la procedura seguente:

  1. Installare il pacchetto NuGet Microsoft.Extensions.Azure:

    dotnet add package Microsoft.Extensions.Azure

  2. In Program.cs registrare il client della libreria Azure SDK tramite una chiamata al metodo di estensione 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());
});

    Nell'esempio precedente il metodo AddAzureClients:

    • Registra gli oggetti seguenti con il contenitore di inserimento delle dipendenze:
      • Servizio di inoltro dei log
      • Client del bus di servizio di Azure
    • Imposta le credenziali del token predefinite da usare per tutti i client registrati.

  3. In appsettings.json modificare il livello di log predefinito della libreria del bus di servizio. Ad esempio, attivarlo su Debug impostando la chiave Logging:LogLevel:Azure.Messaging.ServiceBus come indicato di seguito:

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

    Poiché la chiave Logging:LogLevel:Azure.Messaging.ServiceBus è impostata su Debug, verranno registrati gli eventi del client del bus di servizio fino a EventLevel.Verbose.

Registrazione senza registrazione client

Esistono scenari in cui la registrazione del client di una libreria di Azure SDK con il contenitore di inserimento delle dipendenze è impossibile o non necessaria:

In questi scenari procedere come segue:

  1. Installare il pacchetto NuGet Microsoft.Extensions.Azure:

    dotnet add package Microsoft.Extensions.Azure

  2. In Program.cs registrare il servizio di inoltro dei log come singleton nel contenitore di inserimento delle dipendenze:

    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. Recuperare il servizio di inoltro del log dal contenitore di inserimento delle dipendenze e richiamarne il metodo Start. Ad esempio, usando l'inserimento del costruttore in una classe del modello di pagina 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. In appsettings.json modificare il livello di log predefinito della libreria di Azure Core. Ad esempio, attivarlo su Debug impostando la chiave Logging:LogLevel:Azure.Core come indicato di seguito:

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

    Poiché la chiave Logging:LogLevel:Azure.Core è impostata su Debug, verranno registrati gli eventi della libreria di Azure Core fino a EventLevel.Verbose.

Per altre informazioni, vedere Registrazione in .NET Core e ASP.NET Core.

Registrazione con Azure.Monitor.OpenTelemetry.AspNetCore

La distribuzione OpenTelemetry di Monitoraggio di Azure, a partire dalla versione 1.2.0, supporta l'acquisizione dei log provenienti dalle librerie client di Azure. È possibile controllare la registrazione usando una delle opzioni di configurazione descritte in Registrazione in .NET Core e ASP.NET Core.

Usando la libreria del bus di servizio di Azure come esempio, completare la procedura seguente:

  1. Installare il pacchetto NuGet Azure.Monitor.OpenTelemetry.AspNetCore :

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Creare o registrare il client della libreria. La distribuzione supporta entrambi i casi.

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

  3. In appsettings.json modificare il livello di log predefinito della libreria del bus di servizio. Ad esempio, attivarlo su Debug impostando la chiave Logging:LogLevel:Azure.Messaging.ServiceBus come indicato di seguito:

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

    Poiché la chiave Logging:LogLevel:Azure.Messaging.ServiceBus è impostata su Debug, verranno registrati gli eventi del client del bus di servizio fino a EventLevel.Verbose.

Registrare i corpi di richiesta e risposta HTTP

Nota

Questa funzionalità si applica solo alle librerie che usano HTTP per comunicare con un servizio di Azure. Le librerie basate su protocolli alternativi, ad esempio AMQP, non supportano la registrazione del contenuto. Gli esempi non supportati includono librerie per i servizi di Azure, ad esempio Hub eventi, bus di servizio e Web PubSub.

Durante la risoluzione dei problemi relativi a un comportamento imprevisto con una libreria client, è utile esaminare gli elementi seguenti:

  • Corpo della richiesta HTTP inviato all'API REST del servizio di Azure sottostante.
  • Corpo della risposta HTTP ricevuto dall'API REST del servizio di Azure.

Per impostazione predefinita, la registrazione del contenuto indicato in precedenza è disabilitata. Per abilitare la registrazione dei corpi di richiesta e risposta HTTP, seguire questa procedura:

  1. Impostare la proprietà IsLoggingContentEnabled dell'oggetto opzioni client su true e passare l'oggetto opzioni al costruttore del client. Ad esempio, per registrare richieste HTTP e risposte per la libreria dei segreti di 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. Usare l'approccio di registrazione preferito con un livello di eventi/log dettagliato/debug o superiore. Individuare l'approccio nella tabella seguente per visualizzare le istruzioni specifiche.

    Approccio Istruzioni
    Abilitare la registrazione con metodi predefiniti Passare EventLevel.Verbose o EventLevel.LogAlways a AzureEventSourceListener.CreateConsoleLogger o AzureEventSourceListener.CreateTraceLogger
    Configurare la registrazione personalizzata Impostare il parametro del costruttore level della classe AzureEventSourceListener su EventLevel.Verbose o EventLevel.LogAlways
    Eseguire il mapping alla registrazione di ASP.NET Core Aggiungere "Azure.Core": "Debug" a appsettings.json

Passaggi successivi