Rejestrowanie przy użyciu zestawu Azure SDK dla platformy .NET

Artykuł
04/09/2024

Zestaw Azure SDK dla programu . Biblioteki klienckie platformy NET obejmują możliwość rejestrowania operacji biblioteki klienta. To rejestrowanie umożliwia monitorowanie żądań we/wy i odpowiedzi wysyłanych przez biblioteki klienckie do usług platformy Azure. Zazwyczaj dzienniki są używane do debugowania lub diagnozowania problemów z komunikacją. W tym artykule opisano następujące podejścia umożliwiające rejestrowanie za pomocą zestawu Azure SDK dla platformy .NET:

Włączanie rejestrowania przy użyciu wbudowanych metod
Konfigurowanie rejestrowania niestandardowego
Mapowanie na rejestrowanie ASP.NET Core

Ważne

Ten artykuł dotyczy bibliotek klienckich korzystających z najnowszych wersji zestawu Azure SDK dla platformy .NET. Aby sprawdzić, czy biblioteka jest obsługiwana, zobacz listę najnowszych wersji zestawu Azure SDK. Jeśli aplikacja korzysta ze starszej wersji biblioteki klienta zestawu Azure SDK, zapoznaj się z konkretnymi instrukcjami w odpowiedniej dokumentacji usługi.

Informacje o dzienniku

Zestaw SDK rejestruje każde żądanie HTTP i odpowiedź, oczyszczanie wartości zapytania parametru i nagłówka w celu usunięcia danych osobowych.

Wpis dziennika żądań HTTP:

Unikatowy identyfikator
Metoda HTTP
Identyfikator URI
Nagłówki żądań wychodzących

Wpis dziennika odpowiedzi HTTP:

Czas trwania operacji we/wy (czas, który upłynął)
Identyfikator żądania
Kod stanu HTTP
Fraza przyczyny HTTP
Nagłówki odpowiedzi
Informacje o błędzie, jeśli ma to zastosowanie

Zawartość żądania HTTP i odpowiedzi:

Strumień zawartości jako tekst lub bajty w zależności od nagłówka Content-Type .

Uwaga

Rejestrowanie zawartości jest domyślnie wyłączone. Aby ją włączyć, zobacz Rejestrowanie żądań HTTP i treści odpowiedzi. Ta funkcja ma zastosowanie tylko do bibliotek używających protokołu HTTP do komunikowania się z usługą platformy Azure. Biblioteki oparte na alternatywnych protokołach, takich jak AMQP, nie obsługują rejestrowania zawartości. Nieobsługiwane przykłady obejmują biblioteki dla usług platformy Azure, takich jak Event Hubs, Service Bus i Web PubSub.

Dzienniki zdarzeń są zwykle danymi wyjściowymi na jednym z tych trzech poziomów:

Informacje dotyczące zdarzeń żądania i odpowiedzi
Ostrzeżenie dotyczące błędów
Pełne informacje na temat szczegółowych komunikatów i rejestrowania zawartości

Włączanie rejestrowania przy użyciu wbudowanych metod

Zestaw Azure SDK dla programu . Biblioteki klienckie platformy NET rejestrują zdarzenia śledzenia zdarzeń dla systemu Windows (ETW) za pośrednictwem System.Diagnostics.Tracing.EventSource klasy, która jest typowa dla platformy .NET. Źródła zdarzeń umożliwiają używanie rejestrowania strukturalnego w aplikacji z minimalnym obciążeniem wydajności. Aby uzyskać dostęp do dzienników zdarzeń, należy zarejestrować odbiorniki zdarzeń.

Zestaw SDK zawiera klasę zawierającą Azure.Core.Diagnostics.AzureEventSourceListener dwie metody statyczne, które upraszczają kompleksowe rejestrowanie aplikacji .NET: CreateConsoleLogger i CreateTraceLogger. Każda z tych metod akceptuje opcjonalny parametr określający poziom dziennika. Jeśli parametr nie zostanie podany, zostanie użyty domyślny poziom Informational dziennika.

Zaloguj się do okna konsoli

Podstawowym zestawem zestawu Azure SDK dla bibliotek klienckich platformy .NET jest uproszczenie możliwości wyświetlania kompleksowych dzienników w czasie rzeczywistym. Metoda CreateConsoleLogger umożliwia wysyłanie dzienników do okna konsoli przy użyciu jednego wiersza kodu:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Rejestrowanie w śladach diagnostycznych

W przypadku implementowania odbiorników śledzenia można użyć CreateTraceLogger metody , aby zalogować się do standardowego mechanizmu śledzenia zdarzeń platformy .NET (System.Diagnostics.Tracing). Aby uzyskać więcej informacji na temat śledzenia zdarzeń na platformie .NET, zobacz Śledzenie odbiorników.

W tym przykładzie określono poziom dziennika pełnej zawartości:

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

Konfigurowanie rejestrowania niestandardowego

Jak wspomniano powyżej, należy zarejestrować odbiorniki zdarzeń w celu odbierania komunikatów dziennika z zestawu Azure SDK dla platformy .NET. Jeśli nie chcesz implementować kompleksowego rejestrowania przy użyciu jednej z uproszczonych metod powyżej, możesz utworzyć wystąpienie AzureEventSourceListener klasy. Przekaż to wystąpienie metodę wywołania zwrotnego, którą zapisujesz. Ta metoda będzie otrzymywać komunikaty dziennika, które można przetworzyć, jednak musisz. Ponadto podczas konstruowania wystąpienia można określić poziomy dziennika do uwzględnienia.

Poniższy przykład tworzy odbiornik zdarzeń, który rejestruje się w konsoli za pomocą niestandardowego komunikatu. Dzienniki są filtrowane do tych zdarzeń emitowanych z biblioteki klienta Platformy Azure Core z poziomem szczegółowości. Biblioteka Azure Core używa nazwy Azure-Coreźródła zdarzeń .

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

Mapowanie na rejestrowanie ASP.NET Core

Usługa AzureEventSourceLogForwarder umożliwia korzystanie ze standardowej konfiguracji rejestrowania ASP.NET Core na potrzeby rejestrowania. Usługa przekazuje komunikaty dziennika ze źródeł zdarzeń zestawu Azure SDK do ILoggerFactory.

W poniższej tabeli przedstawiono sposób mapowania zestawu Azure SDK dla platformy .NET EventLevel na platformę ASP.NET Core LogLevel.

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

Rejestrowanie przy użyciu rejestracji klienta

Korzystając z biblioteki usługi Azure Service Bus jako przykładu, wykonaj następujące kroki:

Zainstaluj pakiet NuGet Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```
W Program.cs zarejestruj klienta biblioteki zestawu Azure SDK za pomocą wywołania AddAzureClients metody rozszerzenia:
```
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());
});
```
W poprzednim przykładzie AddAzureClients metoda:
- Rejestruje następujące obiekty w kontenerze wstrzykiwania zależności (DI):
  - Usługa przesyłania dalej dzienników
  - Klient usługi Azure Service Bus
- Ustawia domyślne poświadczenia tokenu, które mają być używane dla wszystkich zarejestrowanych klientów.
W appsettings.json zmień domyślny poziom dziennika biblioteki usługi Service Bus. Przełącz go Debug na przykład, ustawiając Logging:LogLevel:Azure.Messaging.ServiceBus klucz w następujący sposób:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Messaging.ServiceBus Ponieważ klucz jest ustawiony na Debugwartość , zdarzenia klienta usługi Service Bus do EventLevel.Verbose będą rejestrowane.

Rejestrowanie bez rejestracji klienta

Istnieją scenariusze, w których zarejestrowanie klienta biblioteki zestawu Azure SDK w kontenerze DI jest niemożliwe lub niepotrzebne:

Biblioteka zestawu Azure SDK nie zawiera IServiceCollection metody rozszerzenia do rejestrowania klienta w kontenerze DI.
Aplikacja korzysta z bibliotek rozszerzeń platformy Azure, które zależą od innych bibliotek zestawu Azure SDK. Przykłady takich bibliotek rozszerzeń platformy Azure obejmują:

W tych scenariuszach wykonaj następujące kroki:

Zainstaluj pakiet NuGet Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```

W Program.cs zarejestruj usługę przesyłania dalej dzienników jako pojedynczą usługę w kontenerze 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());

Pobierz usługę przesyłania dalej dziennika z kontenera DI i wywołaj jego Start metodę. Na przykład użycie iniekcji konstruktora w klasie modelu strony Razor Pages platformy ASP.NET Core:

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

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

W appsettings.json zmień domyślny poziom dziennika biblioteki Azure Core. Przełącz go Debug na przykład, ustawiając Logging:LogLevel:Azure.Core klucz w następujący sposób:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Core Ponieważ klucz jest ustawiony na Debugwartość , zdarzenia biblioteki Azure Core do EventLevel.Verbose będą rejestrowane.

Aby uzyskać więcej informacji, zobacz Rejestrowanie na platformie .NET Core i ASP.NET Core.

Rejestrowanie przy użyciu elementu Azure.Monitor.OpenTelemetry.AspNetCore

Dystrybucja OpenTelemetry usługi Azure Monitor rozpoczynająca się od wersji 1.2.0obsługuje przechwytywanie dzienników pochodzących z bibliotek klienckich platformy Azure. Rejestrowanie można kontrolować przy użyciu dowolnej z opcji konfiguracji omówionych w temacie Rejestrowanie na platformie .NET Core i ASP.NET Core.

Korzystając z biblioteki usługi Azure Service Bus jako przykładu, wykonaj następujące kroki:

Zainstaluj pakiet NuGet Azure.Monitor.OpenTelemetry.AspNetCore:
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
Utwórz lub zarejestruj klienta biblioteki. Dystrybucja obsługuje oba przypadki.
```
await using var client = new ServiceBusClient("<connection_string>");
```
W appsettings.json zmień domyślny poziom dziennika biblioteki usługi Service Bus. Przełącz go Debug na przykład, ustawiając Logging:LogLevel:Azure.Messaging.ServiceBus klucz w następujący sposób:
```
{
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}
```
Logging:LogLevel:Azure.Messaging.ServiceBus Ponieważ klucz jest ustawiony na Debugwartość , zdarzenia klienta usługi Service Bus do EventLevel.Verbose będą rejestrowane.

Rejestrowanie żądań HTTP i treści odpowiedzi

Uwaga

Ta funkcja ma zastosowanie tylko do bibliotek używających protokołu HTTP do komunikowania się z usługą platformy Azure. Biblioteki oparte na alternatywnych protokołach, takich jak AMQP, nie obsługują rejestrowania zawartości. Nieobsługiwane przykłady obejmują biblioteki dla usług platformy Azure, takich jak Event Hubs, Service Bus i Web PubSub.

Podczas rozwiązywania problemów z nieoczekiwanym zachowaniem biblioteki klienta warto sprawdzić następujące elementy:

Treść żądania HTTP wysłana do bazowego interfejsu API REST usługi platformy Azure.
Treść odpowiedzi HTTP odebrana z interfejsu API REST usługi platformy Azure.

Domyślnie rejestrowanie wyżej wymienionej zawartości jest wyłączone. Aby włączyć rejestrowanie jednostek żądania HTTP i odpowiedzi, wykonaj następujące kroki:

Ustaw właściwość obiektu IsLoggingContentEnabled opcji klienta na true, a następnie przekaż obiekt options do konstruktora klienta. Aby na przykład rejestrować żądania HTTP i odpowiedzi dla biblioteki wpisów tajnych usługi Azure Key Vault:

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

Użyj preferowanego podejścia rejestrowania z poziomem zdarzenia/dziennika pełnej/debugowania lub nowszej. Aby uzyskać szczegółowe instrukcje, znajdź swoje podejście w poniższej tabeli.

Metoda	Instrukcje
Włączanie rejestrowania przy użyciu wbudowanych metod	Przekazywanie `EventLevel.Verbose` lub do `AzureEventSourceListener.CreateConsoleLogger` lub `EventLevel.LogAlwaysAzureEventSourceListener.CreateTraceLogger`
Konfigurowanie rejestrowania niestandardowego	`AzureEventSourceListener` Ustaw parametr konstruktora `level` klasy na `EventLevel.Verbose` lub`EventLevel.LogAlways`
Mapowanie na rejestrowanie ASP.NET Core	Dodaj `"Azure.Core": "Debug"` do appsettings.json

Następne kroki

Włączanie rejestrowania diagnostyki dla aplikacji w usłudze Azure App Service
Przeglądanie opcji rejestrowania i inspekcji zabezpieczeń platformy Azure
Dowiedz się, jak pracować z dziennikami platformy Azure
Przeczytaj więcej na temat rejestrowania i śledzenia platformy .NET

Udostępnij za pośrednictwem