Megosztás a következőn keresztül:

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

  • Cikk

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:

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:

  1. Telepítse a Microsoft.Extensions.Azure NuGet-csomagot:

    dotnet add package Microsoft.Extensions.Azure

  2. 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.

  3. 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:

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

  1. Telepítse a Microsoft.Extensions.Azure NuGet-csomagot:

    dotnet add package Microsoft.Extensions.Azure

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

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

  4. 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:

  1. Telepítse az Azure.Monitor.OpenTelemetry.AspNetCore NuGet csomagot:

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. 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>");

  3. 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:

  1. Á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);

  2. 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