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

Článek
04/09/2024

Sada Azure SDK pro . Klientské knihovny NET zahrnují možnost protokolování operací klientské knihovny. 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 problémů s komunikací. 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í na protokolování jádra ASP.NET

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

Sada SDK protokoluje každý požadavek HTTP a odpověď, sanitizaci hodnot dotazu na parametr a hlavičky 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 požadavku
Kód stavu HTTP
Fráze důvodu HTTP
Hlavičky odpovědi
Informace o chybách, pokud jsou k dispozici

Obsah požadavku HTTP a odpovědi:

Datový proud obsahu jako text nebo bajty v závislosti na Content-Type záhlaví

Poznámka:

Protokolování obsahu je ve výchozím nastavení zakázané. Pokud ho chcete povolit, přečtěte si téma Protokol 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é informace o podrobných zprávách a protokolování obsahu

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

Sada Azure SDK pro . Klientské knihovny NET protokoluje události trasování událostí pro Windows (ETW) prostřednictvím System.Diagnostics.Tracing.EventSource třídy, která 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 naslouchací procesy 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

Klíčovou sadou tenantů sady Azure SDK pro klientské knihovny .NET je zjednodušení možnosti zobrazení komplexních protokolů 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();

Protokolování do diagnostických trasování

Pokud implementujete naslouchací procesy trasování, můžete metodu CreateTraceLogger použít k protokolování do standardního mechanismu trasování událostí .NET (System.Diagnostics.Tracing). Další informace o trasování událostí v .NET naleznete v tématu Naslouchací procesy 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 naslouchací procesy událostí pro příjem zpráv protokolu ze sady 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, ale 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 se filtrují na tyto události generované z klientské knihovny Azure Core s úrovní podrobného. Knihovna Azure Core používá název Azure-Corezdroje událostí .

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

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ředává zprávy protokolu ze zdrojů událostí Sady Azure SDK do ILoggerFactory.

Následující tabulka znázorňuje, jak se sada Azure SDK pro .NET EventLevel mapuje na 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 vzorku AddAzureClients metoda:
- Zaregistruje následující objekty v kontejneru injektáž 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.json změňte výchozí úroveň protokolu knihovny služby Service Bus. Můžete ho Logging:LogLevel:Azure.Messaging.ServiceBus například přepnout Debug tak, že nastavíte klíč 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 události klienta služby Service Bus až do EventLevel.Verbose protokolu.

Protokolová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 jednoúčelovou službu 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 vyvoláte 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.json změňte výchozí úroveň protokolu knihovny Azure Core. Můžete ho Logging:LogLevel:Azure.Core například přepnout Debug tak, že nastavíte klíč takto:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Vzhledem k tomu, že Logging:LogLevel:Azure.Core klíč je nastavený na Debug, protokolují se události knihovny Azure Core až do EventLevel.Verbose protokolu.

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.json změňte výchozí úroveň protokolu knihovny služby Service Bus. Můžete ho Logging:LogLevel:Azure.Messaging.ServiceBus například přepnout Debug tak, že nastavíte klíč 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 události klienta služby Service Bus až do EventLevel.Verbose protokolu.

Protokolovat požadavky HTTP a těla odpovědí

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 IsLoggingContentEnabled možností klienta na truehodnotu a předejte objekt možnosti 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ého nebo ladění nebo vyšší. Konkrétní pokyny najdete v následující tabulce.

Přístup	Pokyny
Povolení protokolování pomocí předdefinovaných metod	Předání `EventLevel.Verbose` nebo předání nebo `EventLevel.LogAlways` předání `AzureEventSourceListener.CreateConsoleLoggerAzureEventSourceListener.CreateTraceLogger`
Konfigurace vlastního protokolování	Nastavení parametru konstruktoru `AzureEventSourceListener` třídy `level` na `EventLevel.Verbose` nebo `EventLevel.LogAlways`
Mapování na protokolování jádra ASP.NET	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 protokolování a trasování .NET