Condividi tramite

Registrazione con Azure SDK per .NET

L'Azure SDK per .NET include librerie client con la possibilità di registrare (log) le operazioni della libreria client. Questa registrazione consente di monitorare le richieste di I/O e le risposte eseguite nelle 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 sul log

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

Voce del log delle richieste HTTP:

  • ID univoco
  • Metodo HTTP
  • URI (Identificatore Uniforme delle Risorse)
  • Intestazioni di richiesta in uscita

Entrata del registro delle risposte HTTP:

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

Contenuto della richiesta e della risposta HTTP:

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

    Annotazioni

    La registrazione del contenuto è disabilitata per impostazione predefinita. Per abilitarlo, 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
  • Verboso per messaggi dettagliati e registrazione contenuti

Abilitare la registrazione con metodi predefiniti

Azure SDK per .NET: le librerie client registrano eventi in Event Tracing for Windows (ETW) tramite la classe System.Diagnostics.Tracing.EventSource, che è tipico per .NET. Le fonti di eventi consentono di usare la registrazione strutturata nell'app con un impatto minimo sulle prestazioni. Per ottenere l'accesso ai registri degli eventi, è necessario registrare i listener di eventi.

L'SDK include la Azure.Core.Diagnostics.AzureEventSourceListener classe , 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 predefinito di Informational .

Accedere alla finestra della console

Un principio fondamentale delle librerie client di Azure SDK per .NET è semplificare la visualizzazione dei registri completi in tempo reale. Il CreateConsoleLogger metodo consente di inviare i log alla finestra della console con una singola riga di codice:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Registra tracce di diagnostica

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

Questo esempio specifica un livello di log verboso.

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 AzureEventSourceListener classe . Passa a quell'istanza un metodo di callback che hai scritto. Questo metodo riceverà messaggi di log che puoi elaborare secondo le tue necessità. Inoltre, quando si costruisce l'istanza, è possibile specificare i livelli di log da includere.

Nell'esempio seguente viene creato un listener di eventi che accede alla 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 Core di Azure usa un nome dell'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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

Mappa ai log di ASP.NET Core.

Il AzureEventSourceLogForwarder servizio 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 mostra come l'Azure SDK per .NET EventLevel si mappa all'ASP.NET Core LogLevel.

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

Accesso con registrazione del client

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

    Nel precedente esempio, il metodo AddAzureClients:

    • Registra i seguenti oggetti nel contenitore di iniezione 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, modifica il livello di log predefinito della libreria Service Bus. Ad esempio, modifica l'impostazione a Debug configurando il tasto 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 Logging:LogLevel:Azure.Messaging.ServiceBus chiave è impostata su Debug, gli eventi client del bus di servizio fino a EventLevel.Verbose verranno registrati.

Accesso senza registrazione del client

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

In questi scenari completare i passaggi seguenti:

  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:

    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. Recupera il servizio di inoltro del log dal contenitore delle dipendenze e invoca il suo metodo Start. Ad esempio, usando l'inserimento del costruttore in una classe di 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.jsonmodificare il livello di log predefinito della libreria Azure Core. Ad esempio, modifica l'impostazione a Debug configurando il tasto Logging:LogLevel:Azure.Core come indicato di seguito:

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

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

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

Registrazione con Azure.Monitor.OpenTelemetry.AspNetCore

La distribuzione OpenTelemetry di Azure Monitor, a partire dalla versione 1.2.0, supporta la cattura 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.

Usare 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, modifica il livello di log predefinito della libreria Service Bus. Ad esempio, modifica l'impostazione a Debug configurando il tasto 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 Logging:LogLevel:Azure.Messaging.ServiceBus chiave è impostata su Debug, gli eventi client del bus di servizio fino a EventLevel.Verbose verranno registrati.

Registrare i corpi di richiesta e risposta HTTP

Annotazioni

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.

Quando si risolve 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 precedente è disabilitata. Per abilitare la registrazione dei corpi di richiesta e risposta HTTP, completare la procedura seguente:

  1. Impostare la proprietà dell'oggetto opzioni del client su IsLoggingContentEnabled, 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. Utilizza l'approccio di registrazione preferito con un livello di log verboso/debug o superiore. Trova l'approccio nella tabella seguente per istruzioni specifiche.

    Avvicinarsi Disposizioni
    Abilitare la registrazione con metodi predefiniti Passa EventLevel.Verbose o EventLevel.LogAlways a AzureEventSourceListener.CreateConsoleLogger o AzureEventSourceListener.CreateTraceLogger
    Configurare la registrazione personalizzata Impostare il parametro del costruttore della AzureEventSourceListenerlevel classe su EventLevel.Verbose o EventLevel.LogAlways
    Mappare il logging di ASP.NET Core Aggiungi "Azure.Core": "Debug" a appsettings.json

Passaggi successivi