Protokolování a diagnostika v ASP.NET Core SignalR

Andrew Stanton-Nurse

Tento článek obsahuje pokyny ke shromažďování diagnostiky z aplikace ASP.NET Core SignalR , které vám pomůžou s řešením problémů.

Protokolování na straně serveru

Upozorňující

Protokoly na straně serveru můžou obsahovat citlivé informace z vaší aplikace. Nikdy nezpracované protokoly z produkčních aplikací neposílejte na veřejná fóra, jako je GitHub.

Vzhledem k tomu SignalR , že je součástí ASP.NET Core, používá systém protokolování ASP.NET Core. Ve výchozí konfiguraci SignalR protokoluje minimální informace, ale úroveň protokolování je možné nakonfigurovat. Podrobnosti o konfiguraci protokolování ASP.NET Core najdete v dokumentaci k protokolování ASP.NET Core.

SignalR používá dvě kategorie protokolovacího nástroje:

• Microsoft.AspNetCore.SignalR: Pro protokoly související s protokoly centra, aktivaci Hubs, vyvolání metod a dalších aktivit souvisejících s centrem.
• Microsoft.AspNetCore.Http.Connections: Protokoly související s přenosy, jako jsou WebSockets, Long Polling, Server-Sent Events a low-level SignalR infrastructure.

Pokud chcete povolit podrobné logy z SignalR, nastavte obě předchozí předpony na úroveň Debug ve vašem souboru appsettings.json přidáním následujících položek do podkapitoly LogLevel v Logging:

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

Úrovně protokolování pro SignalR kategorie protokolovacího modulu lze také nakonfigurovat v kódu v rámci CreateWebHostBuilder metody:

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

Pokud nepoužíváte konfiguraci založenou na formátu JSON, nastavte v konfiguračním systému následující hodnoty konfigurace:

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

Projděte si dokumentaci ke konfiguračnímu systému a zjistěte, jak zadat vnořené hodnoty konfigurace. Například při použití proměnných prostředí se místo znaku _ (například:) použijí dva Logging__LogLevel__Microsoft.AspNetCore.SignalR znaky.

Při shromažďování podrobnější diagnostiky pro vaši aplikaci doporučujeme použít Debug úroveň. Úroveň Trace vytváří diagnostiku nízké úrovně a zřídka se vyžaduje k diagnostice problémů ve vaší aplikaci.

Přístup k protokolům na straně serveru

Způsob přístupu k protokolům na straně serveru závisí na prostředí, ve kterém je aplikace spuštěná.

Jako konzolová aplikace mimo službu IIS

Pokud používáte konzolovou aplikaci, protokolovací nástroj konzoly by měl být ve výchozím nastavení povolený. SignalR protokoly se zobrazí v konzole.

V rámci služby IIS Express ze sady Visual Studio

Visual Studio zobrazí výstup protokolu v okně Výstup . Vyberte možnost rozevíracího seznamu ASP.NET Základní komponenty webového serveru.

Azure App Service

V části Diagnostické protokoly portálu služby Aplikace Azure Service portal povolte možnost Protokolování aplikace (Systém souborů) a nakonfigurujte úroveňVerbosena . Protokoly by měly být dostupné ze služby streamování protokolů a v protokolech v systému souborů služby App Service. Další informace najdete v tématu Streamování protokolů Azure.

Ostatní prostředí

Další informace o konfiguraci zprostředkovatelů protokolování vhodných pro různá prostředí nasazení, jako je Docker, Kubernetes nebo Služba Windows, najdete v tématu Protokolování v .NET Core a ASP.NET Core.

Protokolování klienta JavaScriptu

Upozorňující

Protokoly na straně klienta můžou obsahovat citlivé informace z vaší aplikace. Nikdy nezpracované protokoly z produkčních aplikací neposílejte na veřejná fóra, jako je GitHub.

Při použití javascriptového klienta můžete nakonfigurovat možnosti protokolování pomocí metody v configureLoggingHubConnectionBuilder:

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

Zakažte protokolování architektury zadáním signalR.LogLevel.None v configureLogging metodě. Upozorňujeme, že některé protokolování se vygeneruje přímo v prohlížeči a není možné ho zakázat nastavením úrovně protokolu.

Následující tabulka uvádí úrovně protokolů dostupné pro javascriptového klienta. Nastavení úrovně protokolu na jednu z těchto hodnot umožňuje protokolování na této úrovni a všechny úrovně nad ní v tabulce.

Úroveň	Popis
None	Nejsou zaprotokolovány žádné zprávy.
Critical	Zprávy, které označují selhání v celé aplikaci
Error	Zprávy, které označují selhání v aktuální operaci
Warning	Zprávy, které značí problém, který není závažná.
Information	Informační zprávy.
Debug	Diagnostické zprávy užitečné pro ladění.
Trace	Velmi podrobné diagnostické zprávy navržené pro diagnostiku konkrétních problémů.

Jakmile nakonfigurujete úroveň podrobností, protokoly se zapíšou do konzoly prohlížeče (nebo standardní výstup v aplikaci NodeJS).

Pokud chcete odesílat protokoly do vlastního systému protokolování, můžete zadat javascriptový objekt, který implementuje ILogger rozhraní. Jedinou metodou, kterou je potřeba implementovat, je log, která přebírá úroveň události a zprávy přidružené k události. Příklad:

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

Protokolování klienta .NET

Upozorňující

Protokoly na straně klienta můžou obsahovat citlivé informace z vaší aplikace. Nikdy nezpracované protokoly z produkčních aplikací neposílejte na veřejná fóra, jako je GitHub.

K získání protokolů z klienta .NET můžete použít metodu ConfigureLogging na HubConnectionBuilder. To funguje stejně jako metoda na ConfigureLoggingWebHostBuilder a HostBuilder. Můžete nakonfigurovat stejné poskytovatele protokolování, které používáte v ASP.NET Core. Musíte ale ručně nainstalovat a povolit balíčky NuGet pro jednotlivé zprostředkovatele protokolování.

Pokud chcete do Blazor WebAssembly aplikace přidat protokolování klienta .NET, přečtěte si informace Blazor ASP.NET Core.

Protokolování konzoly

Chcete-li povolit protokolování konzoly, přidejte balíček Microsoft.Extensions.Logging.Console . Pak pomocí AddConsole metody nakonfigurujte protokolovací nástroj konzoly:

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

Ladění protokolování výstupního okna

Protokoly je možné nakonfigurovat pro zobrazení v okně Výstup v sadě Visual Studio. Nainstalujte balíček Microsoft.Extensions.Logging.Debug a použijte metoduAddDebug:

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

Další zprostředkovatelé protokolování

SignalR podporuje jiné zprostředkovatele protokolování, jako jsou Serilog, Seq, NLog nebo jakýkoli jiný protokolovací systém, který se integruje s Microsoft.Extensions.Logging. Pokud váš systém protokolování poskytuje ILoggerProvider, můžete ho zaregistrovat v AddProvider:

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

Kontrola podrobností

Při protokolování z jiných míst v aplikaci může být změna výchozí úrovně Debug příliš podrobná. Filtr lze použít ke konfiguraci úrovně protokolování pro SignalR protokoly. To lze provést v kódu stejným způsobem jako na serveru:

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

Trasování v SignalR

SignalR centrální server a SignalR klient poskytují informace o SignalR připojeních a zprávách pomocí DiagnosticSource a Activity. SignalR má ActivitySource pro centrální server i klienta, dostupný od verze .NET 9.

ActivitySource je komponenta použitá v distribuovaném trasování k vytváření a správě aktivit (nebo rozsahů), které představují operace ve vaší aplikaci. Tyto aktivity se dají použít k těmto činnostem:

• Sledujte tok požadavků a operací napříč různými komponentami a službami.
• Poskytuje cenné přehledy o výkonu a chování vaší aplikace.

Zdroj aktivit serveru .NET SignalR

SignalR ActivitySource s názvem Microsoft.AspNetCore.SignalR.Server generuje události pro volání metod rozhraní:

• Každá metoda je vlastní aktivita, takže vše, co generuje aktivitu během volání metody centra, je pod aktivitou metody centra.
• Aktivity metody typu hub nemají nadřazený prvek. To znamená, že nejsou součástí dlouhotrvajícího SignalR připojení.

Následující příklad používá .NET Aspire řídicí panel a balíčky 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" />

Do Program.cs souboru přidejte následující spouštěcí kód:

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

Následující příklad výstupu je z řídicího panelu Aspire:

ASP.NET Core také poskytuje vlastní metriky ve Microsoft.AspNetCore.Hosting zdroji událostí.

Zdroj aktivit klienta .NET SignalR

SignalR ActivitySource pojmenovaný Microsoft.AspNetCore.SignalR.Client generuje události pro klienta SignalR.

• Vyvolání hubu vytvoří jeden klientský úsek. Jiní SignalR klienti, například javascriptový klient, nepodporují trasování. Tato funkce se přidá do dalších klientů v budoucích verzích.
• Volání hubu na straně klienta a serveru podporují šíření kontextu. Šíření kontextu trasování umožňuje skutečné distribuované trasování. Teď je možné vidět tok vyvolání z klienta na server a zpět.

Takhle vypadají tyto nové aktivity v řídicím panelu .NET Aspire:

Trasování sítě

Upozorňující

Trasování sítě obsahuje úplný obsah všech zpráv odesílaných vaší aplikací. Nikdy nezpracované síťové trasování z produkčních aplikací do veřejných fór, jako je GitHub.

Pokud narazíte na problém, může trasování sítě někdy poskytnout cenné informace. To je obzvlášť užitečné při oznámení problému na naší platformě pro sledování problémů.

Shromažďování trasování sítě pomocí Fiddleru (upřednostňovaná možnost)

Tato metoda funguje pro všechny aplikace.

Fiddler je výkonný nástroj pro shromažďování trasování HTTP. Nainstalujte ho z telerik.com/fiddler, spusťte ji a spusťte aplikaci a reprodukujte problém. Fiddler je k dispozici pro Windows a pro macOS a Linux existují beta verze.

Pokud se připojujete pomocí protokolu HTTPS, existuje několik dalších kroků, které zajistí, že Fiddler dokáže dešifrovat provoz HTTPS. Další informace najdete v dokumentaci k Fiddleru.

Po shromáždění trasování ho exportujte výběrem možnosti Soubor>Uložit>Všechny relace na řádku nabídek.

Shromažďování trasování sítě pomocí protokolu tcpdump (jenom macOS a Linux)

Tato metoda funguje pro všechny aplikace.

Nezpracované trasování TCP lze shromažďovat pomocí příkazu tcpdump spuštěním následujícího příkazu z příkazového prostředí. Pokud se zobrazí chyba oprávnění, budete možná muset být root příkazem nebo ho předponovat sudo :

tcpdump -i [interface] -w trace.pcap

Nahraďte [interface] síťovým rozhraním, na které chcete zachytávat. Obvykle se jedná o něco podobného /dev/eth0 (pro standardní ethernetové rozhraní) nebo /dev/lo0 (pro provoz místního hostitele). Další informace najdete na tcpdump ruční stránce hostitelského systému.

Shromáždění trasování sítě v prohlížeči

Tato metoda funguje jenom pro aplikace založené na prohlížeči.

Většina konzol nástrojů pro vývojáře prohlížeče má kartu Síť, která umožňuje zaznamenání síťové aktivity mezi prohlížečem a serverem. Tyto trasování ale nezahrnují zprávy události WebSocket a Server-Sent. Při použití těchto přenosů je použití nástroje, jako je Fiddler nebo TcpDump, lepší přístup, jak je popsáno dále v tomto článku.

Microsoft Edge a Internet Explorer

(Pokyny jsou stejné pro Microsoft Edge i Internet Explorer.

1. Stisknutím klávesy F12 otevřete Dev Tools.
2. Vyberte kartu Síť.
3. Aktualizujte stránku (v případě potřeby) a reprodukujte problém.
4. Výběrem ikony Uložit na panelu nástrojů vyexportujte trasování jako soubor HAR:

Google Chrome

1. Stisknutím klávesy F12 otevřete Dev Tools.
2. Vyberte kartu Síť.
3. Aktualizujte stránku (v případě potřeby) a reprodukujte problém.
4. Klikněte pravým tlačítkem na libovolné místo v seznamu požadavků a zvolte Uložit jako HAR s obsahem:

Mozilla Firefox

1. Stisknutím klávesy F12 otevřete Dev Tools.
2. Vyberte kartu Síť.
3. Aktualizujte stránku (v případě potřeby) a reprodukujte problém.
4. Klikněte pravým tlačítkem na libovolné místo v seznamu požadavků a zvolte Uložit vše jako HAR.

Problémy s připojením diagnostických souborů k GitHubu

Diagnostické soubory lze připojit k issues na GitHubu tak, že je přejmenujete, aby měly příponu .txt, a poté je přetáhněte na problém.

Poznámka:

Do problému GitHubu nevkládejte obsah souborů protokolů ani trasování sítě. Tyto protokoly a sledování mohou být velké a GitHub je obvykle zkracuje.

Metriky

Metriky představují znázornění datových měr v časových intervalech. Například požadavky za sekundu. Data metrik umožňují sledovat stav aplikace na vysoké úrovni. Metriky .NET gRPC se generují pomocí EventCounter.

SignalR metriky serveru

SignalR Metriky serveru jsou hlášeny ve zdroji Microsoft.AspNetCore.Http.Connections událostí.

Název	Popis
connections-started	Celkový počet spuštěných připojení
connections-stopped	Celkový počet zastavených připojení
connections-timed-out	Časový limit celkového počtu připojení vypršel.
current-connections	Aktuální připojení
connections-duration	Průměrná doba trvání připojení

Sledování metrik

dotnet-counters je nástroj pro monitorování výkonu pro monitorování stavu ad hoc a prošetření výkonu na první úrovni. Monitorujte aplikaci .NET s Microsoft.AspNetCore.Http.Connections názvem zprostředkovatele. Příklad:

> 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

Další materiály

• Konfigurace SignalR pro ASP.NET Core
• ASP.NET Core SignalR JavaScript client
• klient ASP.NET Core SignalR .NET