Registrazione e diagnostica in ASP.NET Core SignalR

Di Andrew Stanton-Nurse

Questo articolo fornisce indicazioni per raccogliere la diagnostica dall'app ASP.NET Core SignalR per risolvere i problemi.

Registrazione lato server

Warning

I log lato server possono contenere informazioni riservate dall'app. Non pubblicare mai log non elaborati dalle app di produzione a forum pubblici come GitHub.

Poiché SignalR fa parte di ASP.NET Core, usa il sistema di registrazione ASP.NET Core. Nella configurazione predefinita registra SignalR informazioni minime, ma è possibile configurare il livello di registrazione. Per informazioni dettagliate sulla configurazione della registrazione ASP.NET Core, vedere la documentazione relativa alla registrazione di ASP.NET Core.

SignalR usa due categorie di logger:

• Microsoft.AspNetCore.SignalR: per i log correlati ai protocolli hub, l'attivazione di Hub, la chiamata di metodi e altre attività correlate all'hub.
• Microsoft.AspNetCore.Http.Connections: per i log relativi ai trasporti, ad esempio WebSocket, Long Polling, Eventi inviati dal server e infrastruttura di basso livello SignalR .

Per abilitare i log dettagliati da SignalR, configurare entrambi i prefissi precedenti al Debug livello nel appsettings.json file aggiungendo gli elementi seguenti alla LogLevel sottosezione in Logging:

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

I livelli di registrazione per le categorie di SignalR logger possono essere configurati anche nel codice all'interno del CreateWebHostBuilder metodo :

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

Se non si usa la configurazione basata su JSON, impostare i valori di configurazione seguenti nel sistema di configurazione:

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

Controllare la documentazione relativa al sistema di configurazione per determinare come specificare i valori di configurazione annidati. Ad esempio, quando si usano variabili di _ ambiente, vengono usati due : caratteri anziché ( ad esempio , Logging__LogLevel__Microsoft.AspNetCore.SignalR).

È consigliabile usare il livello durante la Debug raccolta di diagnostica più dettagliate per l'app. Il Trace livello produce diagnostica di basso livello ed è raramente necessario per diagnosticare i problemi nell'app.

Accedere ai log lato server

La modalità di accesso ai log lato server dipende dall'ambiente in cui è in esecuzione l'app.

Come app console all'esterno di IIS

Se si esegue in un'app console, il logger console deve essere abilitato per impostazione predefinita. SignalR I log vengono visualizzati nella console.

In IIS Express da Visual Studio

Visual Studio visualizza l'output del log nella finestra Output . Selezionare l'opzione a discesa ASP.NET Server Web Core.

Servizio app di Azure

Abilitare l'opzione Registrazione applicazioni (file system) nella sezione Log di diagnostica del portale del servizio app Azure e configurare Il livello su Verbose. I log devono essere disponibili dal servizio di streaming dei log e nei log nel file system del servizio app. Per altre informazioni, vedere Flusso di log di Azure.

Altri ambienti

Per altre informazioni sulla configurazione dei provider di registrazione adatti per ambienti di distribuzione diversi, ad esempio Docker, Kubernetes o Servizio Windows, vedere Registrazione in .NET e ASP.NET Core.

Registrazione client JavaScript

Warning

I log lato client possono contenere informazioni riservate dall'app. Non pubblicare mai log non elaborati dalle app di produzione a forum pubblici come GitHub.

Quando si usa il client JavaScript, è possibile configurare le opzioni di registrazione usando il configureLogging metodo in HubConnectionBuilder:

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

Disabilitare la registrazione del framework specificando signalR.LogLevel.None nel metodo configureLogging. Si noti che alcune registrazioni vengono generate direttamente dal browser e non possono essere disabilitate impostando il livello di log.

La tabella seguente mostra i livelli di log disponibili per il client JavaScript. L'impostazione del livello di log su uno di questi valori consente la registrazione a tale livello e a tutti i livelli sopra di esso nella tabella.

Level	Description
None	Non vengono registrati messaggi.
Critical	Messaggi che indicano un errore nell'intera app.
Error	Messaggi che indicano un errore nell'operazione corrente.
Warning	Messaggi che indicano un problema non irreversibile.
Information	Messaggi informativi.
Debug	Messaggi di diagnostica utili per il debug.
Trace	Messaggi di diagnostica molto dettagliati progettati per la diagnosi di problemi specifici.

Dopo aver configurato il livello di dettaglio, i log verranno scritti nella console del browser (o output standard in un'app NodeJS).

Se si desidera inviare log a un sistema di registrazione personalizzato, è possibile fornire un oggetto JavaScript che implementa l'interfaccia ILogger . L'unico metodo che deve essere implementato è log, che accetta il livello dell'evento e il messaggio associato all'evento. Per esempio:

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

Registrazione client .NET

Warning

I log lato client possono contenere informazioni riservate dall'app. Non pubblicare mai log non elaborati dalle app di produzione a forum pubblici come GitHub.

Per ottenere i log dal client .NET, è possibile usare il ConfigureLogging metodo in HubConnectionBuilder. Questa operazione funziona allo stesso modo del ConfigureLogging metodo in WebHostBuilder e HostBuilder. È possibile configurare gli stessi provider di registrazione usati in ASP.NET Core. Tuttavia, è necessario installare e abilitare manualmente i pacchetti NuGet per i singoli provider di registrazione.

Per aggiungere la registrazione client .NET a un'app, vedere Blazor WebAssemblyBlazor.

Log della console

Per abilitare la registrazione della console, aggiungere il pacchetto Microsoft.Extensions.Logging.Console . Usare quindi il AddConsole metodo per configurare il logger della console:

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

Eseguire il debug della registrazione della finestra di output

I log possono essere configurati per passare alla finestra Output in Visual Studio. Installare il pacchetto Microsoft.Extensions.Logging.Debug e usare il AddDebug metodo :

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

Altri provider di registrazione

SignalR supporta altri provider di registrazione, ad esempio Serilog, Seq, NLog o qualsiasi altro sistema di registrazione che si integra con Microsoft.Extensions.Logging. Se il sistema di registrazione fornisce un , ILoggerProviderè possibile registrarlo con 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();

Controllare la verbosità

Quando si esegue la registrazione da altre posizioni nell'app, la modifica del livello predefinito in Debug può essere troppo dettagliata. È possibile usare un filtro per configurare il livello di registrazione per SignalR log. Questa operazione può essere eseguita nel codice, nello stesso modo del server:

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

Traccia in SignalR

SignalR hub server e client SignalR forniscono informazioni sulle connessioni e i SignalR messaggi tramite DiagnosticSource e Activity. SignalR ha activitySource sia per il server hub che per il client, disponibile a partire da .NET 9.

ActivitySource è un componente usato nella traccia distribuita per creare e gestire attività (o intervalli) che rappresentano le operazioni nell'applicazione. Queste attività possono essere usate per:

• Tenere traccia del flusso di richieste e operazioni tra componenti e servizi diversi.
• Fornire informazioni dettagliate utili sulle prestazioni e sul comportamento dell'applicazione.

ActivitySource del server .NET SignalR

Il SignalR ActivitySource denominato Microsoft.AspNetCore.SignalR.Server genera eventi per le chiamate al metodo hub:

• Ogni metodo è una propria attività, quindi qualsiasi elemento che genera un'attività durante la chiamata al metodo hub si trova nell'attività del metodo hub.
• Le attività del metodo hub non hanno un elemento padre. Ciò significa che non sono raggruppati nella connessione di lunga durata SignalR.

L'esempio seguente usa il Aspire dashboard e i pacchetti 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" />

Aggiungere il codice di avvio seguente al Program.cs file:

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

L'output di esempio seguente proviene dal Aspire dashboard:

ASP.NET Core fornisce anche le proprie metriche sull'origine Microsoft.AspNetCore.Hosting evento.

Client di .NET ActivitySource SignalR

Il SignalRActivitySource denominato Microsoft.AspNetCore.SignalR.Client genera eventi per un SignalR client:

• Le chiamate all'hub creano un intervallo client. Altri SignalR client, come il client JavaScript, non supportano il tracciamento. Questa funzionalità verrà aggiunta a più client nelle versioni future.
• Le invocazioni dell'hub sul client e sul server supportano la propagazione del contesto . La propagazione del contesto di traccia abilita la traccia distribuita vera. È ora possibile visualizzare il flusso delle chiamate dal client al server e di nuovo.

Ecco come vengono esaminate queste nuove attività nel dashboard Aspire:

Tracce di rete

Warning

Una traccia di rete include il contenuto completo di ogni messaggio inviato dall'app. Non pubblicare mai tracce di rete non elaborate dalle app di produzione in forum pubblici come GitHub.

Se si verifica un problema, una traccia di rete può talvolta fornire informazioni preziose. Ciò è particolarmente utile quando si invia un problema sul nostro strumento di rilevamento dei problemi.

Raccogliere una traccia di rete con Fiddler (opzione preferita)

Questo metodo funziona per tutte le app.

Fiddler è uno strumento potente per la raccolta di tracce HTTP. Installarlo da telerik.com/fiddler, avviarlo e quindi eseguire l'app e riprodurre il problema. Fiddler è disponibile per Windows e sono disponibili versioni beta per macOS e Linux.

Se ci si connette usando HTTPS, esistono alcuni passaggi aggiuntivi per assicurarsi che Fiddler possa decrittografare il traffico HTTPS. Per altre informazioni, vedere la documentazione di Fiddler.

Dopo aver raccolto la traccia, esportarla selezionando File>Salva>tutte le sessioni dalla barra dei menu

Raccogliere una traccia di rete con tcpdump (solo macOS e Linux)

Questo metodo funziona per tutte le app.

Le tracce TCP non elaborate possono essere raccolte usando tcpdump eseguendo il comando seguente da una shell dei comandi. Potrebbe essere necessario specificare root o anteporre il comando a sudo se viene visualizzato un errore di autorizzazione:

tcpdump -i [interface] -w trace.pcap

Sostituire [interface] con l'interfaccia di rete su cui si vuole eseguire l'acquisizione. In genere, questo è simile /dev/eth0 (per un'interfaccia Ethernet standard) o /dev/lo0 (per il traffico localhost). Per altre informazioni, vedere la tcpdump pagina del manuale nel sistema host.

Raccogliere una traccia di rete nel browser

Questo metodo funziona solo per le app basate su browser.

La maggior parte delle console degli strumenti di sviluppo del browser dispone di una scheda "Rete" che consente l'acquisizione dell'attività di rete tra il browser e il server. Tuttavia, queste tracce non includono i messaggi WebSocket e Eventi inviati dal server. Quando si usano questi trasporti, l'uso di uno strumento come Fiddler o TcpDump è un approccio migliore, come descritto più avanti in questo articolo.

Microsoft Edge e Internet Explorer

(Le istruzioni sono le stesse per Microsoft Edge e Internet Explorer)

1. Apri gli strumenti di sviluppo premendo F12
2. Selezionare la scheda Rete
3. Se necessario, aggiornare la pagina e riprodurre il problema
4. Selezionare l'icona Salva sulla barra degli strumenti per esportare la traccia come file "HAR":

Google Chrome

1. Apri gli strumenti di sviluppo premendo F12
2. Selezionare la scheda Rete
3. Se necessario, aggiornare la pagina e riprodurre il problema
4. Fare clic con il pulsante destro del mouse in un punto qualsiasi dell'elenco delle richieste e scegliere "Salva come HAR con contenuto":

Mozilla Firefox

1. Apri gli strumenti di sviluppo premendo F12
2. Selezionare la scheda Rete
3. Se necessario, aggiornare la pagina e riprodurre il problema
4. Fare clic con il pulsante destro del mouse in un punto qualsiasi dell'elenco delle richieste e scegliere "Salva tutto come HAR"

Collegare i file di diagnostica a GitHub

I file di diagnostica possono essere allegati ai problemi di GitHub rinominandoli in modo che abbiano un'estensione .txt e quindi trascinandoli e rilasciandoli nel problema.

Note

Non incollare il contenuto dei file di log o delle tracce di rete in un problema di GitHub. Questi log e tracce possono essere di grandi dimensioni e GitHub li tronca in genere.

Metrics

Le metriche sono una rappresentazione delle misure dei dati in intervalli di tempo. Ad esempio, le richieste al secondo. I dati delle metriche consentono di osservare lo stato di un'app a un livello elevato. Le metriche di .NET gRPC vengono generate usando EventCounter.

SignalR metriche del server

SignalR le metriche del server vengono segnalate nell'origine Microsoft.AspNetCore.Http.Connections evento.

Name	Description
connections-started	Totale connessioni avviate
connections-stopped	Totale connessioni arrestate
connections-timed-out	Timeout totale connessioni
current-connections	Connessioni correnti
connections-duration	Durata media della connessione

Monitorare le metriche

dotnet-counters è uno strumento di monitoraggio delle prestazioni per il monitoraggio dell'integrità ad hoc e l'analisi delle prestazioni di primo livello. Monitorare un'app .NET con Microsoft.AspNetCore.Http.Connections come nome del provider. Per esempio:

> 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

Risorse aggiuntive

• Configurazione SignalR di ASP.NET Core
• client JavaScript di ASP.NET Core SignalR
• client .NET di ASP.NET Core SignalR