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

Zestaw Azure SDK dla platformy .NET zawiera biblioteki klienckie, które umożliwiają logowanie operacji bibliotek klienckich. 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:

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 logach

Zestaw SDK rejestruje każde żądanie HTTP i odpowiedź, oczyszczając wartości zapytania parametru i wartości nagłówka, aby usunąć dane osobowe.

Wpis dziennika żądań HTTP:

  • Unikatowy identyfikator
  • metoda HTTP
  • 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:

  • Przepływ danych może być tekstem lub bajtami, zależnie od nagłówka Content-Type.

    Uwaga / Notatka

    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 zapisywane 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 .NET, biblioteki klienckie rejestrują zdarzenia do Event Tracing for Windows (ETW) za pośrednictwem klasy System.Diagnostics.Tracing.EventSource, co jest typowe 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ę Azure.Core.Diagnostics.AzureEventSourceListener, która zawiera dwie metody statyczne upraszczające kompleksowe rejestrowanie dla aplikacji .NET: CreateConsoleLogger i CreateTraceLogger. Każda z tych metod akceptuje opcjonalny parametr określający poziom logowania. Jeśli parametr nie zostanie podany, zostanie użyty domyślny poziom Informational logowania.

Zaloguj się do okna konsoli

Podstawowym założeniem zestawu Azure SDK dla bibliotek klienckich .NET jest uproszczenie możliwości wyświetlania szczegółowych logó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();

Logowanie do śladów diagnostycznych

W przypadku implementowania odbiorników śledzenia można użyć metody CreateTraceLogger, aby logować w standardowym mechanizmie ś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ć nasłuchiwacze zdarzeń w celu odbierania komunikatów dziennika z pakietu Azure SDK dla .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ż temu wystąpieniu metodę zwrotną, którą napiszesz. Ta funkcja będzie odbierać wiadomości dziennika, które można przetworzyć według własnych potrzeb. Ponadto podczas konstruowania wystąpienia można określić poziomy logowania 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ń generowanych przez bibliotekę klienta Azure Core na poziomie szczegółowym. Biblioteka Azure Core używa nazwy źródła zdarzeń 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);

Mapowanie do rejestrowania 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ń 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 logowania klienta

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

  1. Zainstaluj pakiet NuGet Microsoft.Extensions.Azure

    dotnet add package Microsoft.Extensions.Azure

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

    W poprzednim przykładzie metoda AddAzureClients:

    • Rejestruje następujące obiekty w kontenerze iniekcji zależności (DI):
      • Usługa przekazywania logów
      • Klient usługi Azure Service Bus
    • Stosuje się DefaultAzureCredential automatycznie do uwierzytelniania, chyba że jawnie skonfigurowano inne poświadczenie.

  3. W appsettings.jsonzmień domyślny poziom dziennika biblioteki usługi Service Bus. Na przykład, przełącz na Debug, ustawiając klucz Logging:LogLevel:Azure.Messaging.ServiceBus 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 wartość Debug, 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:

W tych scenariuszach wykonaj następujące kroki:

  1. Zainstaluj pakiet NuGet Microsoft.Extensions.Azure

    dotnet add package Microsoft.Extensions.Azure

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

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

  4. W appsettings.jsonzmień domyślny poziom dziennika biblioteki Azure Core. Na przykład, przełącz go na Debug, ustawiając klucz Logging:LogLevel:Azure.Core 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 Debug, 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 Azure Monitor OpenTelemetry, począwszy od wersji 1.2.0, obsł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:

  1. Zainstaluj pakiet NuGet Azure.Monitor.OpenTelemetry.AspNetCore :

    dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

  2. Utwórz lub zarejestruj klienta biblioteki. Dystrybucja obsługuje oba przypadki.

    await using var client = new ServiceBusClient("<connection_string>");

  3. W appsettings.jsonzmień domyślny poziom dziennika biblioteki usługi Service Bus. Na przykład, przełącz go na Debug ustawiając klucz Logging:LogLevel:Azure.Messaging.ServiceBus w następujący sposób:

    {
    "ConnectionStrings": {
        "ServiceBus": "<connection_string>"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning",
            "Azure.Messaging.ServiceBus": "Debug"
        }
    },
    "AllowedHosts": "*"
}

    Ponieważ klucz ma wartość Debug, zdarzenia klienta usługi Service Bus do EventLevel.Verbose będą rejestrowane.

Rejestrowanie żądań HTTP i treści odpowiedzi

Uwaga / Notatka

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:

  1. 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 Azure Key Vault Secrets:

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

  2. Użyj preferowanej metody rejestrowania z poziomem zdarzeń/dzienników: szczegółowy/debug lub wyższy. Aby uzyskać szczegółowe instrukcje, znajdź swoje podejście w poniższej tabeli.

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

Dalsze kroki

  • Last updated on