Naplózás a .NET-hez készült Azure SDK-val

Cikk
04/09/2024

Az Azure SDK for . A NET ügyfélkódtárai közé tartozik az ügyfélkódtár műveleteinek naplózása. Ez a naplózás lehetővé teszi az ügyfélkódtárak által az Azure-szolgáltatásokra irányuló I/O-kérések és válaszok monitorozását. A naplók általában a kommunikációs problémák hibakeresésére vagy diagnosztizálására szolgálnak. Ez a cikk a .NET-hez készült Azure SDK-val történő naplózás engedélyezésének alábbi megközelítéseit ismerteti:

Naplózás engedélyezése beépített módszerekkel
Egyéni naplózás konfigurálása
A ASP.NET Core naplózásának leképezése

Fontos

Ez a cikk azokra az ügyfélkódtárakra vonatkozik, amelyek a .NET-hez készült Azure SDK legújabb verzióit használják. Ha tudni szeretné, hogy támogatott-e egy kódtár, tekintse meg az Azure SDK legújabb kiadásainak listáját. Ha az alkalmazás egy Azure SDK-ügyfélkódtár régebbi verzióját használja, tekintse meg a vonatkozó szolgáltatásdokumentáció konkrét utasításait.

Naplóadatok

Az SDK naplózza az egyes HTTP-kéréseket és -válaszokat, és megtisztítja a paraméteres lekérdezési és fejlécértékeket a személyes adatok eltávolításához.

HTTP-kérés naplóbejegyzése:

Egyedi azonosító
HTTP method
URI
Kimenő kérés fejlécei

HTTP-válasznapló-bejegyzés:

Az I/O-művelet időtartama (eltelt idő)
Kérés azonosítója
HTTP-állapotkód
HTTP-ok kifejezés
Válaszfejlécek
Hibainformációk, ha vannak

HTTP-kérések és válaszok tartalma:

Tartalomstreamelés szövegként vagy bájtként a Content-Type fejléctől függően.

Feljegyzés

A tartalomnaplózás alapértelmezés szerint le van tiltva. Ennek engedélyezéséhez tekintse meg a HTTP-kérések és választörzsek naplózását. Ez a funkció csak a HTTP-t használó kódtárakra vonatkozik az Azure-szolgáltatásokkal való kommunikációhoz. Az alternatív protokollokon (például AMQP) alapuló kódtárak nem támogatják a tartalomnaplózást. A nem támogatott példák közé tartoznak az Azure-szolgáltatások, például az Event Hubs, a Service Bus és a Web PubSub kódtárai.

Az eseménynaplók általában az alábbi három szint valamelyikén jelennek meg:

Tájékoztatás kérés- és válaszeseményekhez
Figyelmeztetés a hibákra
Részletes üzenetek és tartalomnaplózás

Naplózás engedélyezése beépített módszerekkel

Az Azure SDK for . A NET ügyfélkódtárai az osztályon keresztül naplóznak eseményeket a System.Diagnostics.Tracing.EventSource Windows eseménykövetéséhez (ETW), amely a .NET-hez jellemző. Az eseményforrások lehetővé teszik a strukturált naplózás használatát az alkalmazásban minimális teljesítményterhelés mellett. Az eseménynaplókhoz való hozzáféréshez eseményfigyelőket kell regisztrálnia.

Az SDK tartalmazza az Azure.Core.Diagnostics.AzureEventSourceListener osztályt, amely két statikus módszert tartalmaz, amelyek leegyszerűsítik a .NET-alkalmazás átfogó naplózását: CreateConsoleLogger és CreateTraceLogger. Ezek a metódusok egy opcionális paramétert fogadnak el, amely naplószintet határoz meg. Ha a paraméter nincs megadva, a rendszer az alapértelmezett naplószintet Informational használja.

Bejelentkezés a konzolablakba

A .NET-ügyfélkódtárakhoz készült Azure SDK alapvető célja az átfogó naplók valós idejű megtekintésének egyszerűsítése. A CreateConsoleLogger metódus lehetővé teszi a naplók küldését a konzolablakba egyetlen kódsor használatával:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Napló a diagnosztikai nyomkövetésekbe

Nyomkövetési figyelők implementálása esetén a CreateTraceLogger metódus használatával bejelentkezhet a standard .NET-eseménykövetési mechanizmusba (System.Diagnostics.Tracing). A .NET-ben az eseménykövetésről további információt a Nyomkövetési figyelők című témakörben talál.

Ez a példa részletes naplószintet határoz meg:

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

Egyéni naplózás konfigurálása

Ahogy fentebb említettük, eseményfigyelőket kell regisztrálnia a naplóüzenetek fogadásához az Azure SDK for .NET-ből. Ha nem szeretne átfogó naplózást implementálni a fenti egyszerűsített módszerek egyikével, létrehozhatja az osztály egy példányát AzureEventSourceListener . Adja át az adott példánynak az Ön által írt visszahívási metódust. Ez a módszer minden szükséges módon megkapja a feldolgozható naplóüzeneteket. Emellett a példány létrehozásakor megadhatja a belefoglalandó naplószinteket.

Az alábbi példa egy eseményfigyelőt hoz létre, amely egyéni üzenettel jelentkezik be a konzolra. A naplók olyan eseményekre lesznek szűrve, amelyeket az Azure Core-ügyfélkódtárból bocsátanak ki részletességgel. Az Azure Core-kódtár a következő eseményforrás nevét Azure-Corehasználja: .

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

A ASP.NET Core naplózásának leképezése

A AzureEventSourceLogForwarder szolgáltatás lehetővé teszi, hogy a naplózáshoz a standard ASP.NET Core naplózási konfigurációt használja. A szolgáltatás naplóüzeneteket továbbít az Azure SDK eseményforrásaiból a következőre ILoggerFactory: .

Az alábbi táblázat azt mutatja be, hogy a .NET-hez EventLevel készült Azure SDK hogyan képezi le a ASP.NET Core-t LogLevel.

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

Naplózás ügyfélregisztrációval

Példaként az Azure Service Bus-kódtárat használva hajtsa végre a következő lépéseket:

Telepítse a Microsoft.Extensions.Azure NuGet-csomagot:
```
dotnet add package Microsoft.Extensions.Azure
```
Az Program.cs regisztrálja az Azure SDK-kódtár ügyfélalkalmazását a AddAzureClients bővítménymetódus hívásával:
```
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());
});
```
Az előző példában a AddAzureClients módszer:
- A következő objektumokat regisztrálja a függőséginjektálási (DI) tárolóval:
  - Naplótovábbító szolgáltatás
  - Azure Service Bus-ügyfél
- Beállítja az összes regisztrált ügyfélhez használandó alapértelmezett jogkivonat-hitelesítő adatokat.
A appsettings.json módosítsa a Service Bus-kódtár alapértelmezett naplószintjét. Például állítsa be úgy, hogy Debug a kulcsot az Logging:LogLevel:Azure.Messaging.ServiceBus alábbiak szerint állítja be:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Mivel a kulcs be van állítvaDebug, a Logging:LogLevel:Azure.Messaging.ServiceBus Service Bus-ügyfélesemények naplózva lesznekEventLevel.Verbose.

Naplózás ügyfélregisztráció nélkül

Vannak olyan forgatókönyvek, amelyekben az Azure SDK-kódtár ügyfélének a DI-tárolóval való regisztrálása lehetetlen vagy szükségtelen:

Az Azure SDK-kódtár nem tartalmaz bővítménymetódust IServiceCollection az ügyfél di-tárolóban való regisztrálásához.
Az alkalmazás más Azure SDK-kódtáraktól függő Azure-bővítménytárakat használ. Ilyen Azure-bővítménytárak például a következők:

Ezekben a forgatókönyvekben hajtsa végre a következő lépéseket:

Telepítse a Microsoft.Extensions.Azure NuGet-csomagot:
```
dotnet add package Microsoft.Extensions.Azure
```

A Program.cs regisztrálja a naplótovábbító szolgáltatást egyetlentonként a DI-tárolóban:

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

Kérje le a naplótovábbító szolgáltatást a DI-tárolóból, és hívja meg annak metódusát Start . Konstruktorinjektálás használata például egy ASP.NET Core Razor Pages oldalmodell-osztályban:

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

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

Az appsettings.json módosítsa az Azure Core-kódtár alapértelmezett naplószintjét. Például állítsa be úgy, hogy Debug a kulcsot az Logging:LogLevel:Azure.Core alábbiak szerint állítja be:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Mivel a Logging:LogLevel:Azure.Core kulcs be van állítva Debug, a rendszer naplózza az Azure Core-kódtár eseményeit EventLevel.Verbose .

További információ: Naplózás a .NET Core-ban és ASP.NET Core-ban.

Naplózás az Azure.Monitor.OpenTelemetry.AspNetCore használatával

Az Azure Monitor OpenTelemetry disztribúció a verziótól 1.2.0kezdve támogatja az Azure-ügyfélkódtárakból származó naplók rögzítését. A naplózást a .NET Core-ban és a ASP.NET Core-ban ismertetett konfigurációs beállítások bármelyikével szabályozhatja.

Példaként az Azure Service Bus-kódtárat használva hajtsa végre a következő lépéseket:

Telepítse az Azure.Monitor.OpenTelemetry.AspNetCore NuGet csomagot:
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
Hozza létre vagy regisztrálja a kódtár ügyfélprogramját. A disztribúció mindkét esetet támogatja.
```
await using var client = new ServiceBusClient("<connection_string>");
```
A appsettings.json módosítsa a Service Bus-kódtár alapértelmezett naplószintjét. Például állítsa be úgy, hogy Debug a kulcsot az Logging:LogLevel:Azure.Messaging.ServiceBus alábbiak szerint állítja be:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Mivel a kulcs be van állítvaDebug, a Logging:LogLevel:Azure.Messaging.ServiceBus Service Bus-ügyfélesemények naplózva lesznekEventLevel.Verbose.

HTTP-kérés- és választörzsek naplózása

Feljegyzés

Ez a funkció csak a HTTP-t használó kódtárakra vonatkozik az Azure-szolgáltatásokkal való kommunikációhoz. Az alternatív protokollokon (például AMQP) alapuló kódtárak nem támogatják a tartalomnaplózást. A nem támogatott példák közé tartoznak az Azure-szolgáltatások, például az Event Hubs, a Service Bus és a Web PubSub kódtárai.

Az ügyfélkódtár váratlan viselkedésének hibaelhárítása során hasznos lehet a következő elemek vizsgálata:

A mögöttes Azure-szolgáltatás REST API-jának küldött HTTP-kérelem törzse.
Az Azure-szolgáltatás REST API-jából kapott HTTP-válasz törzs.

Alapértelmezés szerint a fent említett tartalom naplózása le van tiltva. A HTTP-kérések és választörzsek naplózásának engedélyezéséhez hajtsa végre a következő lépéseket:

Állítsa be az ügyfélbeállítások objektumának tulajdonságát IsLoggingContentEnabled a következőre true, és adja át a beállításobjektumot az ügyfél konstruktorának. Például az Azure Key Vault Titkos kulcstár HTTP-kéréseinek és válaszainak naplózása:
```
var clientOptions = new SecretClientOptions
{
    Diagnostics = 
    {
        IsLoggingContentEnabled = true,
    }
};
var client = new SecretClient(
    new Uri("https://<keyvaultname>.vault.azure.net/"),
    new DefaultAzureCredential(),
    clientOptions);
```

Használja az előnyben részesített naplózási módszert egy részletes/hibakeresési vagy magasabb szintű esemény-/naplószinttel. Konkrét útmutatásért keresse meg a következő táblázatban szereplő megközelítést.

Módszer	Utasítások
Naplózás engedélyezése beépített módszerekkel	Továbbítás vagy `EventLevel.LogAlways` továbbítás `AzureEventSourceListener.CreateConsoleLoggerEventLevel.VerboseAzureEventSourceListener.CreateTraceLogger`
Egyéni naplózás konfigurálása	Az osztály konstruktorparaméterének `AzureEventSourceListenerlevelEventLevel.Verbose` beállítása vagy `EventLevel.LogAlways`
A ASP.NET Core naplózásának leképezése	Hozzáadás `"Azure.Core": "Debug"` appsettings.json

Következő lépések

Alkalmazások diagnosztikai célú naplózásának engedélyezése az Azure App Service-ben
Az Azure biztonsági naplózási és naplózási beállításainak áttekintése
Útmutató az Azure-platformnaplók használatához
További információ a .NET-naplózásról és -nyomkövetésről