Rejestrowanie i diagnostyka w programie ASP.NET Core SignalR

Przez Andrew Stanton-Nurse

Ten artykuł zawiera wskazówki dotyczące zbierania danych diagnostycznych z aplikacji ASP.NET Core SignalR , które ułatwiają rozwiązywanie problemów.

Rejestrowanie po stronie serwera

Ponieważ SignalR jest częścią ASP.NET Core, używa systemu rejestrowania ASP.NET Core. W domyślnej konfiguracji SignalR rejestruje minimalne informacje, ale można skonfigurować poziom rejestrowania. Zapoznaj się z dokumentacją dotyczącą rejestrowania ASP.NET Core, aby uzyskać szczegółowe informacje na temat konfigurowania rejestrowania ASP.NET Core.

SignalR używa dwóch kategorii rejestratora:

• Microsoft.AspNetCore.SignalR: w przypadku dzienników związanych z protokołami koncentratora aktywowanie centrów, wywoływanie metod i innych działań związanych z koncentratorem.
• Microsoft.AspNetCore.Http.Connections: w przypadku dzienników związanych z transportami, takimi jak WebSockets, Long Polling, Server-Sent Events i infrastruktura niskiego poziomu SignalR .

Aby włączyć szczegółowe dzienniki z SignalR, skonfiguruj oba poprzednie prefiksy na poziom Debug w pliku appsettings.json, dodając następujące elementy do podsekcji LogLevel w Logging.

{
    "Logging": {
        "LogLevel": {
            "Default": "Debug",
            "System": "Information",
            "Microsoft": "Information",
            "Microsoft.AspNetCore.SignalR": "Debug",
            "Microsoft.AspNetCore.Http.Connections": "Debug"
        }
    }
}

Poziomy rejestrowania dla kategorii rejestratora SignalR można również skonfigurować w kodzie w metodzie CreateWebHostBuilder :

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.AddFilter("Microsoft.AspNetCore.SignalR", LogLevel.Debug);
            logging.AddFilter("Microsoft.AspNetCore.Http.Connections", LogLevel.Debug);
        })
        .UseStartup<Startup>();

Jeśli nie używasz konfiguracji opartej na formacie JSON, ustaw następujące wartości konfiguracji w systemie konfiguracji:

• Logging:LogLevel:Microsoft.AspNetCore.SignalR = Debug
• Logging:LogLevel:Microsoft.AspNetCore.Http.Connections = Debug

Zapoznaj się z dokumentacją systemu konfiguracji, aby określić sposób określania wartości konfiguracji zagnieżdżonych. Na przykład w przypadku używania zmiennych środowiskowych używane są dwa _ znaki zamiast : (na przykład Logging__LogLevel__Microsoft.AspNetCore.SignalR).

Zalecamy użycie poziomu podczas zbierania Debug bardziej szczegółowej diagnostyki aplikacji. Poziom Trace generuje diagnostykę niskiego poziomu i rzadko jest potrzebny do diagnozowania problemów w aplikacji.

Uzyskiwanie dostępu do dzienników po stronie serwera

Sposób uzyskiwania dostępu do dzienników po stronie serwera zależy od środowiska, w którym działa aplikacja.

Jako aplikacja konsolowa poza usługami IIS

Jeśli korzystasz z aplikacji konsolowej, rejestrator konsoli powinien być domyślnie włączony. SignalR dzienniki są wyświetlane w konsoli.

W programie IIS Express z programu Visual Studio

Program Visual Studio wyświetla dane wyjściowe dziennika w oknie Dane wyjściowe . Wybierz opcję listy rozwijanej ASP.NET Podstawowy serwer sieci Web.

Azure App Service

Włącz opcję Rejestrowanie aplikacji (system plików) w sekcji Dzienniki diagnostyczne w portalu usługi aplikacja systemu Azure i skonfiguruj poziom na Verbose. Dzienniki powinny być dostępne w usłudze przesyłania strumieniowego dzienników i w dziennikach w systemie plików usługi App Service. Aby uzyskać więcej informacji, zobacz Przesyłanie strumieniowe dzienników platformy Azure.

Inne środowiska

Aby uzyskać więcej informacji na temat konfigurowania dostawców rejestrowania odpowiednich dla różnych środowisk wdrażania, takich jak Docker, Kubernetes lub Usługa systemu Windows, zobacz Rejestrowanie na platformie .NET i ASP.NET Core.

Rejestrowanie klienta w języku JavaScript

W przypadku korzystania z klienta JavaScript można skonfigurować opcje rejestrowania configureLogging przy użyciu metody w pliku HubConnectionBuilder:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/my/hub/url")
    .configureLogging(signalR.LogLevel.Debug)
    .build();

Wyłącz rejestrowanie struktury, określając signalR.LogLevel.None w metodzie configureLogging . Należy pamiętać, że niektóre rejestrowanie jest emitowane bezpośrednio przez przeglądarkę i nie można ich wyłączyć za pomocą ustawienia poziomu dziennika.

W poniższej tabeli przedstawiono poziomy dzienników dostępne dla klienta JavaScript. Ustawienie poziomu dziennika na jedną z tych wartości umożliwia rejestrowanie na tym poziomie i na wszystkich poziomach powyżej w tabeli.

Po skonfigurowaniu szczegółowości dzienniki zostaną zapisane w konsoli przeglądarki (lub standardowe dane wyjściowe w aplikacji NodeJS).

Jeśli chcesz wysyłać dzienniki do niestandardowego systemu rejestrowania, możesz udostępnić obiekt JavaScript implementujący ILogger interfejs. Jedyną metodą, która musi zostać zaimplementowana, jest log, która przyjmuje poziom zdarzenia i komunikat skojarzony ze zdarzeniem. Przykład:

import { ILogger, LogLevel, HubConnectionBuilder } from "@microsoft/signalr";

export class MyLogger implements ILogger {
    log(logLevel: LogLevel, message: string) {
        // Use `message` and `logLevel` to record the log message to your own system
    }
}

// later on, when configuring your connection...

let connection = new HubConnectionBuilder()
    .withUrl("/my/hub/url")
    .configureLogging(new MyLogger())
    .build();

import { ILogger, LogLevel, HubConnectionBuilder } from "@aspnet/signalr";

export class MyLogger implements ILogger {
    log(logLevel: LogLevel, message: string) {
        // Use `message` and `logLevel` to record the log message to your own system
    }
}

// later on, when configuring your connection...

let connection = new HubConnectionBuilder()
    .withUrl("/my/hub/url")
    .configureLogging(new MyLogger())
    .build();

Rejestrowanie klienta platformy .NET

Aby pobrać dzienniki z klienta platformy .NET, możesz użyć ConfigureLogging metody w pliku HubConnectionBuilder. Działa to w taki sam sposób, jak ConfigureLogging metoda on WebHostBuilder i HostBuilder. Możesz skonfigurować tych samych dostawców rejestrowania, których używasz w programie ASP.NET Core. Należy jednak ręcznie zainstalować i włączyć pakiety NuGet dla poszczególnych dostawców rejestrowania.

Aby dodać rejestrowanie klienta platformy .NET do Blazor WebAssembly aplikacji, zobacz rejestrowanie ASP.NET CoreBlazor.

Rejestrowanie konsoli

Aby włączyć rejestrowanie konsoli, dodaj pakiet Microsoft.Extensions.Logging.Console . Następnie użyj AddConsole metody , aby skonfigurować rejestrator konsoli:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/my/hub/url")
    .ConfigureLogging(logging =>
    {
        // Log to the Console
        logging.AddConsole();

        // This will set ALL logging to Debug level
        logging.SetMinimumLevel(LogLevel.Debug);
    })
    .Build();

Debugowanie rejestrowania okna danych wyjściowych

Dzienniki można skonfigurować tak, aby przejść do okna Dane wyjściowe w programie Visual Studio. Zainstaluj pakiet Microsoft.Extensions.Logging.Debug i użyj AddDebug metody :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/my/hub/url")
    .ConfigureLogging(logging =>
    {
        // Log to the Output Window
        logging.AddDebug();

        // This will set ALL logging to Debug level
        logging.SetMinimumLevel(LogLevel.Debug)
    })
    .Build();

Inni dostawcy rejestrowania

SignalR obsługuje innych dostawców rejestrowania, takich jak Serilog, Seq, NLog lub dowolny inny system rejestrowania, który integruje się z Microsoft.Extensions.Loggingprogramem . Jeśli system rejestrowania udostępnia element ILoggerProvider, możesz zarejestrować go w AddProviderusłudze :

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/my/hub/url")
    .ConfigureLogging(logging =>
    {
        // Log to your custom provider
        logging.AddProvider(new MyCustomLoggingProvider());

        // This will set ALL logging to Debug level
        logging.SetMinimumLevel(LogLevel.Debug)
    })
    .Build();

Regulacja szczegółowości

Podczas logowania z innych miejsc w aplikacji zmiana domyślnego poziomu Debug może być zbyt rozbudowana. Filtr może służyć do konfigurowania poziomu rejestrowania dzienników SignalR . Można to zrobić w kodzie w taki sam sposób jak na serwerze:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/my/hub/url")
    .ConfigureLogging(logging =>
    {
        // Register your providers

        // Set the default log level to Information, but to Debug for SignalR-related loggers.
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddFilter("Microsoft.AspNetCore.SignalR", LogLevel.Debug);
        logging.AddFilter("Microsoft.AspNetCore.Http.Connections", LogLevel.Debug);
    })
    .Build();

Śledzenie w SignalR

SignalR serwer centrum i SignalR klient udostępniają informacje o SignalR połączeniach i komunikatach korzystających z usług DiagnosticSource i Activity. SignalR ma źródło aktywności zarówno dla serwera centralnego, jak i klienta, dostępne od .NET 9.

ActivitySource to składnik używany w śledzeniu rozproszonym do tworzenia działań (lub zakresów) reprezentujących operacje w aplikacji i zarządzania nimi. Te działania mogą służyć do:

• Śledzenie przepływu żądań i operacji w różnych składnikach i usługach.
• Zapewnij cenny wgląd w wydajność i zachowanie aplikacji.

Źródło aktywności serwera .NET SignalR

SignalR ActivitySource o nazwie Microsoft.AspNetCore.SignalR.Server emituje zdarzenia dla wywołań metod w hubie:

• Każda metoda jest swoją własną aktywnością, więc wszystko, co emituje aktywność podczas wywołania metody centrum, jest częścią aktywności tej metody centrum.
• Działania metody Hub nie mają elementu nadrzędnego. Oznacza to, że nie są one objęte długoterminowym SignalR połączeniem.

W poniższym przykładzie użyto pulpitu nawigacyjnego Aspire i pakietów OpenTelemetry:

<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />

Dodaj następujący kod startowy Program.cs do pliku:

using OpenTelemetry.Trace;
using SignalRChat.Hubs;

// Set OTEL_EXPORTER_OTLP_ENDPOINT environment variable depending on where your OTEL endpoint is.
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        if (builder.Environment.IsDevelopment())
        {
            // View all traces only in development environment.
            tracing.SetSampler(new AlwaysOnSampler());
        }

        tracing.AddAspNetCoreInstrumentation();
        tracing.AddSource("Microsoft.AspNetCore.SignalR.Server");
    });

builder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing.AddOtlpExporter());

var app = builder.Build();

Następujące przykładowe dane wyjściowe pochodzą z pulpitu nawigacyjnego Aspire :

SignalR Hub method call events

ASP.NET Core udostępnia również własne metryki dotyczące Microsoft.AspNetCore.Hosting źródła zdarzeń.

Klient .NET SignalR ActivitySource

SignalR ActivitySource o nazwie Microsoft.AspNetCore.SignalR.Client emituje zdarzenia dla klienta SignalR

• Wywołania hubu tworzą zakres klienta. Inni SignalR klienci, tacy jak klient JavaScript, nie obsługują śledzenia. Ta funkcja zostanie dodana do większej liczby klientów w przyszłych wersjach.
• Wywołania hubu po stronie klienta i serwera obsługują propagację kontekstu . Propagacja kontekstu śledzenia umożliwia prawdziwie rozproszone śledzenie. Teraz można zobaczyć przepływ wywołań z klienta do serwera i z powrotem.

Oto jak te nowe działania wyglądają na pulpicie nawigacyjnym Aspire:

Ślady sieci

Jeśli wystąpi problem, śledzenie sieci może czasami dostarczyć cennych informacji. Jest to szczególnie przydatne w przypadku zgłaszania problemu w naszym monitorze problemów.

Zbieranie śledzenia sieci za pomocą programu Fiddler (preferowana opcja)

Ta metoda działa dla wszystkich aplikacji.

Fiddler to zaawansowane narzędzie do zbierania śladów HTTP. Zainstaluj ją z telerik.com/fiddler, uruchom ją, a następnie uruchom aplikację i odtwórz problem. Program Fiddler jest dostępny dla systemu Windows i istnieją wersje beta dla systemów macOS i Linux.

W przypadku nawiązywania połączenia przy użyciu protokołu HTTPS należy wykonać kilka dodatkowych kroków, aby upewnić się, że program Fiddler może odszyfrować ruch HTTPS. Aby uzyskać więcej informacji, zobacz dokumentację programu Fiddler.

Po zebraniu śladu wyeksportuj go, wybierając pozycję Plik>Zapisz>wszystkie sesje na pasku menu

Zbieranie śledzenia sieci za pomocą protokołu tcpdump (tylko systemy macOS i Linux)

Ta metoda działa dla wszystkich aplikacji.

Nieprzetworzone ślady TCP można zbierać przy użyciu narzędzia tcpdump, uruchamiając następujące polecenie z linii poleceń. Jeśli wystąpi błąd uprawnień, może być konieczne root użycie polecenia sudo lub jego prefiks:

tcpdump -i [interface] -w trace.pcap

Zastąp [interface] element interfejsem sieciowym, którego chcesz przechwycić. Zazwyczaj jest to coś takiego jak /dev/eth0 (dla standardowego interfejsu Ethernet) lub /dev/lo0 (dla ruchu localhost). Aby uzyskać więcej informacji, zobacz stronę ręczną tcpdump w systemie hosta.

Zbieranie śledzenia sieci w przeglądarce

Ta metoda działa tylko w przypadku aplikacji opartych na przeglądarce.

Większość konsol narzędzi deweloperskich przeglądarki ma kartę "Sieć", która umożliwia przechwytywanie działań sieciowych między przeglądarką a serwerem. Jednak te ślady nie obejmują komunikatów protokołu WebSocket i zdarzeń wysłanych przez serwer. W przypadku korzystania z tych transportów użycie narzędzia takiego jak Fiddler lub TcpDump jest lepszym podejściem, jak opisano w dalszej części tego artykułu.

Microsoft Edge i Internet Explorer

(Instrukcje są takie same zarówno w przeglądarce Microsoft Edge, jak i w programie Internet Explorer)

1. Otwórz narzędzia deweloperskie, naciskając F12
2. Wybierz kartę Sieć
3. Odśwież stronę (w razie potrzeby) i odtwórz problem
4. Wybierz ikonę Zapisz na pasku narzędzi, aby wyeksportować ślad jako plik "HAR":

Google Chrome

1. Otwórz narzędzia deweloperskie, naciskając F12
2. Wybierz kartę Sieć
3. Odśwież stronę (w razie potrzeby) i odtwórz problem
4. Kliknij prawym przyciskiem myszy dowolne miejsce na liście żądań i wybierz pozycję "Zapisz jako PLIK HAR z zawartością":

Mozilla Firefox

1. Otwórz narzędzia deweloperskie, naciskając F12
2. Wybierz kartę Sieć
3. Odśwież stronę (w razie potrzeby) i odtwórz problem
4. Kliknij prawym przyciskiem myszy dowolne miejsce na liście żądań i wybierz pozycję "Zapisz wszystko jako HAR"

Dołączanie plików diagnostycznych do problemów z usługą GitHub

Pliki diagnostyczne można dołączać do zgłoszeń w .txt GitHub, zmieniając ich nazwy tak, aby miały odpowiednie rozszerzenie, a następnie przeciągając je i upuszczając na zgłoszenie.

Metrics

Metryki to reprezentacja miar danych w odstępach czasu. Na przykład żądania na sekundę. Dane metryk umożliwiają obserwację stanu aplikacji na wysokim poziomie. Metryki gRPC platformy .NET są emitowane przy użyciu polecenia EventCounter.

SignalR Metryki serwera

SignalR Metryki serwera są raportowane w źródle Microsoft.AspNetCore.Http.Connections zdarzeń.

Obserwowanie metryk

dotnet-counters to narzędzie do monitorowania wydajności na potrzeby monitorowania kondycji ad hoc i badania wydajności pierwszego poziomu. Monitoruj aplikację platformy .NET przy użyciu Microsoft.AspNetCore.Http.Connections jako nazwę dostawcy. Przykład:

> dotnet-counters monitor --process-id 37016 --counters Microsoft.AspNetCore.Http.Connections

Press p to pause, r to resume, q to quit.
    Status: Running
[Microsoft.AspNetCore.Http.Connections]
    Average Connection Duration (ms)       16,040.56
    Current Connections                         1
    Total Connections Started                   8
    Total Connections Stopped                   7
    Total Connections Timed Out                 0

Dodatkowe zasoby

• Konfiguracja SignalR na platformie ASP.NET Core
• ASP.NET Core SignalR JavaScript client
• klient platformy .NET platformy ASP.NET Core SignalR