Loggning med Azure SDK för .NET

Artikel
04/09/2024

Azure SDK för . NET:s klientbibliotek omfattar möjligheten att logga klientbiblioteksåtgärder. Med den här loggningen kan du övervaka I/O-begäranden och svar som klientbibliotek gör i Azure-tjänster. Vanligtvis används loggarna för att felsöka eller diagnostisera kommunikationsproblem. I den här artikeln beskrivs följande metoder för att aktivera loggning med Azure SDK för .NET:

Aktivera loggning med inbyggda metoder
Konfigurera anpassad loggning
Mappa till ASP.NET Core-loggning

Viktigt!

Den här artikeln gäller för klientbibliotek som använder de senaste versionerna av Azure SDK för .NET. Om du vill se om ett bibliotek stöds kan du läsa listan över de senaste versionerna av Azure SDK. Om din app använder en äldre version av ett Azure SDK-klientbibliotek läser du specifika instruktioner i tillämplig tjänstdokumentation.

Logginformation

SDK loggar varje HTTP-begäran och svar, vilket rensar parameterfrågor och huvudvärden för att ta bort personliga data.

Loggpost för HTTP-begäran:

Unikt ID
HTTP-metod
URI
Utgående begärandehuvuden

Http-svarsloggpost:

Varaktighet för I/O-åtgärden (tiden har gått)
ID för begäran
HTTP-statuskod
HTTP-orsaksfras
Svarsrubriker
Felinformation, i förekommande fall

HTTP-begäran och svarsinnehåll:

Innehållsström som text eller byte beroende på Content-Type rubriken.

Kommentar

Innehållsloggning är inaktiverad som standard. Information om hur du aktiverar det finns i Log HTTP request and response bodies (Logga HTTP-begärande- och svarsorgan). Den här funktionen gäller endast för bibliotek som använder HTTP för att kommunicera med en Azure-tjänst. Bibliotek baserade på alternativa protokoll, till exempel AMQP, stöder inte innehållsloggning. Exempel som inte stöds är bibliotek för Azure-tjänster som Event Hubs, Service Bus och Web PubSub.

Händelseloggar är vanligtvis utdata på någon av dessa tre nivåer:

Information om begärande- och svarshändelser
Varning för fel
Utförlig för detaljerade meddelanden och innehållsloggning

Aktivera loggning med inbyggda metoder

Azure SDK för . NET:s klientbibliotek loggar händelser till Händelsespårning för Windows (ETW) via System.Diagnostics.Tracing.EventSource klassen, vilket är typiskt för .NET. Med händelsekällor kan du använda strukturerad loggning i din app med minimala prestandakostnader. För att få åtkomst till händelseloggarna måste du registrera händelselyssnare.

SDK:t innehåller Azure.Core.Diagnostics.AzureEventSourceListener klassen som innehåller två statiska metoder som förenklar omfattande loggning för .NET-appen: CreateConsoleLogger och CreateTraceLogger. Var och en av dessa metoder accepterar en valfri parameter som anger en loggnivå. Om parametern inte anges används standardloggnivån Informational för.

Logga in på konsolfönstret

En grundläggande grundsats i Azure SDK för .NET-klientbibliotek är att förenkla möjligheten att visa omfattande loggar i realtid. Med CreateConsoleLogger metoden kan du skicka loggar till konsolfönstret med en enda kodrad:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Logga till diagnostikspårningar

Om du implementerar spårningslyssnare CreateTraceLogger kan du använda metoden för att logga in på standardmekanismen för .NET-händelsespårning (System.Diagnostics.Tracing). Mer information om händelsespårning i .NET finns i Spårningslyssnare.

Det här exemplet anger en loggnivå med utförliga:

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

Konfigurera anpassad loggning

Som nämnts ovan måste du registrera händelselyssnare för att ta emot loggmeddelanden från Azure SDK för .NET. Om du inte vill implementera omfattande loggning med någon av de förenklade metoderna ovan kan du skapa en instans av AzureEventSourceListener klassen. Skicka den instansen till en motringningsmetod som du skriver. Den här metoden tar emot loggmeddelanden som du kan bearbeta men som du behöver. När du skapar instansen kan du dessutom ange de loggnivåer som ska inkluderas.

I följande exempel skapas en händelselyssnare som loggar till konsolen med ett anpassat meddelande. Loggarna filtreras efter de händelser som genereras från Azure Core-klientbiblioteket med en utförlig nivå. Azure Core-biblioteket använder ett händelsekällans namn på 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);

Mappa till ASP.NET Core-loggning

Med AzureEventSourceLogForwarder tjänsten kan du använda standardkonfigurationen ASP.NET Core-loggning för loggning. Tjänsten vidarebefordrar loggmeddelanden från Azure SDK-händelsekällor till ILoggerFactory.

Följande tabell visar hur Azure SDK för .NET EventLevel mappar till ASP.NET Core LogLevel.

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

Loggning med klientregistrering

Slutför följande steg med hjälp av Azure Service Bus-biblioteket som exempel:

Installera NuGet-paketet Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```
I Program.cs registrerar du Azure SDK-bibliotekets klient via ett anrop till AddAzureClients tilläggsmetoden:
```
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());
});
```
I föregående exempel, AddAzureClients metoden:
- Registrerar följande objekt med di-containern (dependency injection):
  - Loggvidaretjänst
  - Azure Service Bus-klient
- Anger standardautentiseringsuppgifter för token som ska användas för alla registrerade klienter.
Ändra standardloggnivån för Service Bus-biblioteket i appsettings.json. Växla till exempel till genom att Debug ange nyckeln på Logging:LogLevel:Azure.Messaging.ServiceBus följande sätt:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Messaging.ServiceBus Eftersom nyckeln är inställd på Debugloggas Service Bus-klienthändelser upp tillEventLevel.Verbose.

Loggning utan klientregistrering

Det finns scenarier där det är omöjligt eller onödigt att registrera en Azure SDK-biblioteksklient med DI-containern :

Azure SDK-biblioteket innehåller inte någon IServiceCollection tilläggsmetod för att registrera en klient i DI-containern.
Din app använder Azure-tilläggsbibliotek som är beroende av andra Azure SDK-bibliotek. Exempel på sådana Azure-tilläggsbibliotek är:

I dessa scenarier utför du följande steg:

Installera NuGet-paketet Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```

I Program.cs registrerar du loggvidaretjänsten som en singleton i DI-containern:

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

Hämta loggvidaretjänsten från DI-containern och anropa dess Start metod. Du kan till exempel använda konstruktorinmatning i en ASP.NET Core Razor Pages-modellklass:

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

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

I appsettings.json ändrar du Standardloggnivån för Azure Core-biblioteket. Växla till exempel till genom att Debug ange nyckeln på Logging:LogLevel:Azure.Core följande sätt:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Core Eftersom nyckeln är inställd på Debugloggas Azure Core-bibliotekshändelser upp tillEventLevel.Verbose.

Mer information finns i Loggning i .NET Core och ASP.NET Core.

Loggning med hjälp av Azure.Monitor.OpenTelemetry.AspNetCore

Azure Monitor OpenTelemetry-distributionen, som börjar med version1.2.0, stöder insamling av loggar som kommer från Azure-klientbibliotek. Du kan styra loggning med något av de konfigurationsalternativ som beskrivs i Loggning i .NET Core och ASP.NET Core.

Slutför följande steg med hjälp av Azure Service Bus-biblioteket som exempel:

Installera NuGet-paketet Azure.Monitor.OpenTelemetry.AspNetCore:
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
Skapa eller registrera bibliotekets klient. Distributionen stöder båda fallen.
```
await using var client = new ServiceBusClient("<connection_string>");
```
Ändra standardloggnivån för Service Bus-biblioteket i appsettings.json. Växla till exempel till genom att Debug ange nyckeln på Logging:LogLevel:Azure.Messaging.ServiceBus följande sätt:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Messaging.ServiceBus Eftersom nyckeln är inställd på Debugloggas Service Bus-klienthändelser upp tillEventLevel.Verbose.

Logga HTTP-begäranden och svarsorgan

Kommentar

Den här funktionen gäller endast för bibliotek som använder HTTP för att kommunicera med en Azure-tjänst. Bibliotek baserade på alternativa protokoll, till exempel AMQP, stöder inte innehållsloggning. Exempel som inte stöds är bibliotek för Azure-tjänster som Event Hubs, Service Bus och Web PubSub.

När du felsöker oväntat beteende med ett klientbibliotek är det bra att granska följande objekt:

HTTP-begärandetexten som skickas till den underliggande Azure-tjänstens REST-API.
HTTP-svarstexten som tagits emot från Azure-tjänstens REST API.

Loggning av ovan nämnda innehåll inaktiveras som standard. Utför följande steg för att aktivera loggning av HTTP-begärande- och svarsorganen:

Ange objektets IsLoggingContentEnabled egenskap för klientalternativ till trueoch skicka alternativobjektet till klientens konstruktor. Om du till exempel vill logga HTTP-begäranden och svar för Azure Key Vault Secrets-biblioteket:

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

Använd den loggningsmetod du föredrar med en händelse-/loggnivå för utförlig/felsökning eller högre. Hitta din metod i följande tabell för specifika instruktioner.

Metod	Instruktioner
Aktivera loggning med inbyggda metoder	Skicka `EventLevel.Verbose` eller `EventLevel.LogAlways` till `AzureEventSourceListener.CreateConsoleLogger` eller `AzureEventSourceListener.CreateTraceLogger`
Konfigurera anpassad loggning	`AzureEventSourceListener` Ange klassens `level` konstruktorparameter till `EventLevel.Verbose` eller`EventLevel.LogAlways`
Mappa till ASP.NET Core-loggning	Lägg till `"Azure.Core": "Debug"` i appsettings.json

Nästa steg

Aktivera diagnostisk loggning för appar i Azure App Service
Granska alternativen för säkerhetsloggning och granskning i Azure
Lär dig hur du arbetar med Azure-plattformsloggar
Läs mer om .NET-loggning och spårning