Protokolování pomocí sady Azure SDK pro .NET

2025-05-04

Sada Azure SDK pro .NET umožňuje klientským knihovnám protokolovat operace. Toto protokolování umožňuje monitorovat vstupně-výstupní požadavky a odpovědi, které klientské knihovny provádějí ve službách Azure. Protokoly se obvykle používají k ladění nebo diagnostice komunikačních problémů. Tento článek popisuje následující přístupy k povolení protokolování pomocí sady Azure SDK pro .NET:

Povolení protokolování pomocí předdefinovaných metod
Konfigurace vlastního protokolování
Mapování k logování v ASP.NET Core

Důležité

Tento článek se týká klientských knihoven, které používají nejnovější verze sady Azure SDK pro .NET. Pokud chcete zjistit, jestli je knihovna podporovaná, podívejte se na seznam nejnovějších verzí sady Azure SDK. Pokud vaše aplikace používá starší verzi klientské knihovny Azure SDK, projděte si konkrétní pokyny v příslušné dokumentaci ke službě.

Informace o protokolu

SDK protokoluje každý požadavek HTTP a odpověď, provádí sanitizaci hodnot parametrů dotazu a hlaviček pro odebrání osobních údajů.

Položka protokolu požadavku HTTP:

Jedinečné ID
Metoda HTTP:
Identifikátor uri
Hlavičky odchozích požadavků

Položka protokolu odpovědi HTTP:

Doba trvání vstupně-výstupní operace (uplynulý čas)
ID žádosti
Stavový kód HTTP
HTTP důvodová fráze
Hlavičky odpovědi
Informace o chybách, pokud jsou k dispozici

Obsah požadavku HTTP a odpovědi:

Proud obsahu jako text nebo byty v závislosti na záhlaví Content-Type.

Poznámka:

Protokolování obsahu je ve výchozím nastavení vypnuté. Chcete-li to povolit, viz Zaznamenání těl HTTP požadavků a odpovědí. Tato funkce se vztahuje pouze na knihovny využívající protokol HTTP ke komunikaci se službou Azure. Knihovny založené na alternativních protokolech, jako je AMQP, nepodporují protokolování obsahu. Mezi nepodporované příklady patří knihovny pro služby Azure, jako jsou Event Hubs, Service Bus a Web PubSub.

Protokoly událostí jsou obvykle výstupem na jedné z těchto tří úrovní:

Informační informace pro události požadavků a odpovědí
Upozornění na chyby
Podrobný režim pro podrobné zprávy a protokolování obsahu

Povolení protokolování pomocí předdefinovaných metod

Sada Azure SDK pro .NET. Klientské knihovny zaznamenávají události do trasování událostí pro Windows (ETW) prostřednictvím System.Diagnostics.Tracing.EventSource třídy, což je typické pro .NET. Zdroje událostí umožňují používat strukturované protokolování v aplikaci s minimální režií na výkon. Pokud chcete získat přístup k protokolům událostí, musíte zaregistrovat posluchače událostí.

Sada SDK obsahuje Azure.Core.Diagnostics.AzureEventSourceListener třídu, která obsahuje dvě statické metody, které zjednodušují komplexní protokolování pro vaši aplikaci .NET: CreateConsoleLogger a CreateTraceLogger. Každá z těchto metod přijímá volitelný parametr, který určuje úroveň protokolu. Pokud parametr není zadaný, použije se výchozí úroveň Informational protokolu.

Přihlášení do okna konzoly

Základním principem Azure SDK pro klientské knihovny .NET je zjednodušit možnost zobrazení komplexních logů v reálném čase. Metoda CreateConsoleLogger umožňuje odesílat protokoly do okna konzoly s jedním řádkem kódu:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Záznam diagnostických tras

Pokud implementujete naslouchátka trasování, můžete metodu CreateTraceLogger použít pro zápis do standardního mechanismu trasování událostí .NET (System.Diagnostics.Tracing). Další podrobnosti o trasování událostí v .NET najdete v tématu Sledovače trasování.

Tento příklad určuje úroveň podrobného protokolu:

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

Konfigurace vlastního protokolování

Jak je uvedeno výše, musíte zaregistrovat zpracovatelé událostí pro přijímání log zpráv z Azure SDK pro .NET. Pokud nechcete implementovat komplexní protokolování pomocí jedné z výše uvedených zjednodušených metod, můžete vytvořit instanci AzureEventSourceListener třídy. Tuto instanci předejte metodu zpětného volání, kterou napíšete. Tato metoda obdrží zprávy protokolu, které můžete zpracovat, jak potřebujete. Kromě toho při vytváření instance můžete zadat úrovně protokolu, které se mají zahrnout.

Následující příklad vytvoří naslouchací proces události, který se přihlásí do konzoly s vlastní zprávou. Protokoly jsou filtrovány na události emitované klientskou knihovnou Azure Core s podrobnou úrovní. Knihovna Azure Core používá název zdroje událostí 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);

Mapování na protokolování jádra ASP.NET

Služba AzureEventSourceLogForwarder umožňuje pro protokolování použít standardní konfiguraci protokolování ASP.NET Core. Služba přeposílá zprávy protokolu ze zdrojů událostí Azure SDK do ILoggerFactory.

Následující tabulka znázorňuje, jak se sada Azure SDK pro .NET EventLevel přiřazuje k ASP.NET Core LogLevel.

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

Protokolování pomocí registrace klienta

Jako příklad použijte knihovnu Azure Service Bus a proveďte následující kroky:

Nainstalujte balíček Microsoft.Extensions.Azure NuGet:
```
dotnet add package Microsoft.Extensions.Azure
```
V Program.cs zaregistrujte klienta knihovny Azure SDK prostřednictvím volání AddAzureClients metody rozšíření:
```
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());
});
```
V předchozím příkladu metoda AddAzureClients:
- Zaregistruje následující objekty v kontejneru injekce závislostí (DI):
  - Služba předávání protokolů
  - Klient služby Azure Service Bus
- Nastaví výchozí přihlašovací údaje tokenu, které se použijí pro všechny registrované klienty.
V appsettings.jsonzměňte výchozí úroveň protokolu knihovny služby Service Bus. Například ho přepněte na Debug nastavením klíče Logging:LogLevel:Azure.Messaging.ServiceBus takto:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Vzhledem k tomu, že Logging:LogLevel:Azure.Messaging.ServiceBus klíč je nastaven na Debug, budou protokolovány klientské události služby Service Bus až do EventLevel.Verbose.

Zaznamenávání bez registrace klienta

Existují scénáře, kdy registrace klienta knihovny Azure SDK v kontejneru DI není možná nebo není nutná:

Knihovna Azure SDK neobsahuje metodu IServiceCollection rozšíření pro registraci klienta v kontejneru DI.
Vaše aplikace používá knihovny rozšíření Azure, které závisí na dalších knihovnách sady Azure SDK. Mezi příklady takových knihoven rozšíření Azure patří:

V těchto scénářích proveďte následující kroky:

Nainstalujte balíček Microsoft.Extensions.Azure NuGet:
```
dotnet add package Microsoft.Extensions.Azure
```

V Program.cs zaregistrujte službu předávání protokolů jako singleton v kontejneru 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());

Načtěte službu předávání protokolů z kontejneru DI a vyvolejte její Start metodu. Například použití injektáže konstruktoru ve třídě modelu stránky ASP.NET Core Razor Pages.

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

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

V appsettings.jsonzměňte výchozí úroveň protokolu knihovny Azure Core. Například ho přepněte na Debug nastavením klíče Logging:LogLevel:Azure.Core takto:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Vzhledem k tomu, že klíč Logging:LogLevel:Azure.Core je nastaven na Debug, budou až do EventLevel.Verbose protokolovány události knihovny Azure Core.

Další informace najdete v článku o protokolování v .NET Core a ASP.NET Core.

Protokolování pomocí Azure.Monitor.OpenTelemetry.AspNetCore

Distribuce OpenTelemetry služby Azure Monitor počínaje verzí 1.2.0podporuje zachytávání protokolů pocházejících z klientských knihoven Azure. Protokolování můžete řídit pomocí některé z možností konfigurace, které jsou popsány v protokolování v .NET Core a ASP.NET Core.

Jako příklad použijte knihovnu Azure Service Bus a proveďte následující kroky:

Nainstalujte balíček NuGet Azure.Monitor.OpenTelemetry.AspNetCore :
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
Vytvořte nebo zaregistrujte klienta knihovny. Distribuce podporuje oba případy.
```
await using var client = new ServiceBusClient("<connection_string>");
```
V appsettings.jsonzměňte výchozí úroveň protokolu knihovny služby Service Bus. Například ho přepněte na Debug nastavením klíče Logging:LogLevel:Azure.Messaging.ServiceBus takto:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Vzhledem k tomu, že Logging:LogLevel:Azure.Messaging.ServiceBus klíč je nastaven na Debug, budou protokolovány klientské události služby Service Bus až do EventLevel.Verbose.

Protokolovat těla požadavků a odpovědí HTTP

Poznámka:

Tato funkce se vztahuje pouze na knihovny využívající protokol HTTP ke komunikaci se službou Azure. Knihovny založené na alternativních protokolech, jako je AMQP, nepodporují protokolování obsahu. Mezi nepodporované příklady patří knihovny pro služby Azure, jako jsou Event Hubs, Service Bus a Web PubSub.

Při řešení potíží s neočekávaným chováním klientské knihovny je užitečné zkontrolovat následující položky:

Text požadavku HTTP odeslaný do základního rozhraní REST API služby Azure.
Text odpovědi HTTP přijatý z rozhraní REST API služby Azure.

Ve výchozím nastavení je protokolování výše uvedeného obsahu zakázané. Pokud chcete povolit protokolování těla požadavků HTTP a odpovědí, proveďte následující kroky:

Nastavte vlastnost objektu možností klienta IsLoggingContentEnabled na hodnotu true a předejte objekt s možnostmi konstruktoru klienta. Pokud například chcete protokolovat požadavky HTTP a odpovědi pro knihovnu tajných kódů služby Azure Key Vault:

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

Použijte preferovaný přístup k protokolování s úrovní událostí nebo protokolu podrobný/ladič nebo vyšší. Najděte svůj přístup v následující tabulce pro konkrétní pokyny.

Přístup	Instrukce
Povolení protokolování pomocí předdefinovaných metod	Předat `EventLevel.Verbose` nebo `EventLevel.LogAlways` na `AzureEventSourceListener.CreateConsoleLogger` nebo `AzureEventSourceListener.CreateTraceLogger`
Konfigurace vlastního protokolování	Nastavení parametru konstruktoru `AzureEventSourceListener` třídy `level` na `EventLevel.Verbose` nebo `EventLevel.LogAlways`
Mapování k logování v ASP.NET Core	Přidat `"Azure.Core": "Debug"` do appsettings.json

Další kroky

Povolení protokolování diagnostiky aplikací ve službě Azure App Service
Kontrola možností protokolování a auditování zabezpečení Azure
Naučte se pracovat s protokoly platformy Azure.
Další informace o .NET protokolování a trasování

Sdílet prostřednictvím