Logboekregistratie en diagnose in ASP.NET Core SignalR

Door Andrew Stanton-Nurse

Dit artikel bevat richtlijnen voor het verzamelen van diagnostische gegevens van uw ASP.NET Core-app SignalR om problemen op te lossen.

Server-side logging

Omdat SignalR het onderdeel is van ASP.NET Core, wordt het ASP.NET Core-logboekregistratiesysteem gebruikt. In de standaardconfiguratie SignalR registreert u minimale informatie, maar het logboekregistratieniveau kan worden geconfigureerd. Zie de documentatie over ASP.NET Core-logboekregistratie voor meer informatie over het configureren van ASP.NET Core-logboekregistratie.

SignalR maakt gebruik van twee loggercategorieën:

• Microsoft.AspNetCore.SignalR: voor logboeken met betrekking tot hubprotocollen, het activeren van hubs, het aanroepen van methoden en andere hubgerelateerde activiteiten.
• Microsoft.AspNetCore.Http.Connections: Voor logboeken met betrekking tot transporten, zoals WebSockets, Long Polling, Server-Sent Events en infrastructuur op laag niveau SignalR .

Als u gedetailleerde logboeken wilt inschakelen, configureert u beide voorvoegsels naar het SignalR-niveau in uw Debug bestand door de volgende items toe te voegen aan de appsettings.json subsectie in LogLevel:

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

De logboekregistratieniveaus voor de SignalR logboekregistratiecategorieën kunnen ook worden geconfigureerd in code binnen de CreateWebHostBuilder methode:

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

Als u geen JSON-configuratie gebruikt, stelt u de volgende configuratiewaarden in uw configuratiesysteem in:

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

Raadpleeg de documentatie voor uw configuratiesysteem om te bepalen hoe geneste configuratiewaarden moeten worden opgegeven. Als u bijvoorbeeld omgevingsvariabelen gebruikt, worden er twee _ tekens gebruikt in plaats van de : (bijvoorbeeld Logging__LogLevel__Microsoft.AspNetCore.SignalR).

We raden u aan het Debug niveau te gebruiken voor het verzamelen van gedetailleerdere diagnostische gegevens voor uw app. Het Trace niveau produceert diagnostische gegevens op laag niveau en is zelden nodig om problemen in uw app te diagnosticeren.

Logboeken aan serverzijde openen

Hoe logboeken aan de serverzijde worden geopend, is afhankelijk van de omgeving waarin de app wordt uitgevoerd.

Als console-app buiten IIS

Als u in een console-app werkt, moet de consolelogger standaard zijn ingeschakeld. SignalR logboeken worden weergegeven in de console.

Binnen IIS Express vanuit Visual Studio

Visual Studio geeft de logboekuitvoer weer in het uitvoervenster . Selecteer de vervolgkeuzelijst ASP.NET Core Web Server .

Azure App Service

Schakel de optie Toepassingslogboeken (bestandssysteem) in de sectie Diagnostische logboeken van de Azure App Service-portal in en configureer het niveau naar Verbose. Logboeken moeten beschikbaar zijn via de logboekstreamingservice en in logboeken in het bestandssysteem van de App Service. Zie Azure-logboekstreaming voor meer informatie.

Other environments

Zie Logboekregistratie in .NET en ASP.NET Core voor meer informatie over het configureren van logboekproviders die geschikt zijn voor verschillende implementatieomgevingen, zoals Docker, Kubernetes of Windows Service.

Logboekregistratie van JavaScript-client

Wanneer u de JavaScript-client gebruikt, kunt u logboekregistratieopties configureren met behulp van de configureLogging methode op HubConnectionBuilder:

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

Schakel frameworklogging uit door signalR.LogLevel.None te specificeren in de configureLogging methode. Sommige logboekregistraties worden rechtstreeks door de browser verzonden en kunnen niet worden uitgeschakeld via het instellen van het logboekniveau.

De volgende tabel bevat logboekniveaus die beschikbaar zijn voor de JavaScript-client. Als u het logboekniveau instelt op een van deze waarden, kunt u logboekregistratie op dat niveau en alle niveaus erboven in de tabel instellen.

Zodra u de uitgebreidheid hebt geconfigureerd, worden de logboeken naar de browserconsole geschreven (of standaarduitvoer in een NodeJS-app).

Als u logboeken naar een aangepast logboekregistratiesysteem wilt verzenden, kunt u een JavaScript-object opgeven dat de ILogger interface implementeert. De enige methode die moet worden geïmplementeerd, is log, waarbij het niveau van de gebeurtenis en het bericht dat aan de gebeurtenis is gekoppeld, wordt gebruikt. For example:

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

.NET-clientlogboekregistratie

Als u logboeken van de .NET-client wilt ophalen, kunt u de ConfigureLogging methode gebruiken op HubConnectionBuilder. Dit werkt op dezelfde manier als de ConfigureLogging methode op WebHostBuilder en HostBuilder. U kunt dezelfde providers voor logboekregistratie configureren die u gebruikt in ASP.NET Core. U moet de NuGet-pakketten echter handmatig installeren en inschakelen voor de afzonderlijke logboekregistratieproviders.

Zie Blazor WebAssembly als u .NET-clientlogging aan een Blazor app wilt toevoegen.

Console logging

Als u consolelogboekregistratie wilt inschakelen, voegt u het pakket Microsoft.Extensions.Logging.Console toe. Gebruik vervolgens de AddConsole methode om de consolelogger te configureren:

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

Logboekregistratie van debuguitvoer-venster

Logboeken kunnen worden geconfigureerd om naar het uitvoervenster in Visual Studio te gaan. Installeer het pakket Microsoft.Extensions.Logging.Debug en gebruik de AddDebug methode:

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

Andere providers voor logboekregistratie

SignalR ondersteunt andere providers voor logboekregistratie, zoals Serilog, Seq, NLog of een ander systeem voor logboekregistratie dat kan worden geïntegreerd met Microsoft.Extensions.Logging. Als uw logboekregistratiesysteem een ILoggerProvidersysteem biedt, kunt u het registreren bij 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();

Control verbosity

Wanneer u vanuit andere plaatsen in de app logt, kan het wijzigen van het standaardniveau naar Debug te gedetailleerd zijn. Een filter kan worden gebruikt om het logboekregistratieniveau voor SignalR logboeken te configureren. Dit kan in code, op ongeveer dezelfde manier als op de 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();

Tracering in SignalR

SignalR hub-server en de SignalR client bieden informatie over SignalR verbindingen en berichten door gebruik te maken van DiagnosticSource en Activity. SignalR heeft een ActivitySource voor zowel de hubserver als de client, die kan worden gestart met .NET 9.

Een ActivitySource is een onderdeel dat wordt gebruikt in gedistribueerde tracering om activiteiten (of spanten) te maken en te beheren die bewerkingen in uw toepassing vertegenwoordigen. Deze activiteiten kunnen worden gebruikt om:

• De stroom van aanvragen en bewerkingen in verschillende onderdelen en services bijhouden.
• Geef waardevolle inzichten in de prestaties en het gedrag van uw toepassing.

.NET SignalR server Activiteitsbron

De SignalR ActivitySource met de naam Microsoft.AspNetCore.SignalR.Server verzendt gebeurtenissen voor hubmethode-aanroepen:

• Elke methode is een eigen activiteit, dus alles wat een activiteit verzendt tijdens de aanroep van de hubmethode, valt onder de hubmethodeactiviteit.
• Hub-methodeactiviteiten hebben geen bovenliggende ouder. Dit betekent dat ze niet worden gebundeld onder de langlopende SignalR verbinding.

In het volgende voorbeeld worden de .NET Aspire dashboard- en de OpenTelemetry--pakketten gebruikt:

<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" />

Voeg de volgende opstartcode toe aan het Program.cs-bestand:

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

De volgende voorbeelduitvoer is afkomstig van het Aspire Dashboard:

ASP.NET Core biedt ook zijn eigen metrische gegevens over Microsoft.AspNetCore.Hosting de gebeurtenisbron.

.NET-client SignalR ActivitySource

De SignalRActivitySource benoemde Microsoft.AspNetCore.SignalR.Client verzendt gebeurtenissen voor een SignalR client:

• Hub-aanroepen maken een clientspanne. Andere SignalR clients, zoals de JavaScript-client, bieden geen ondersteuning voor tracering. Deze functie wordt in toekomstige releases toegevoegd aan meer clients.
• Hub-aanroepen op de client en server ondersteunen contextdoorgifte. Door de traceringscontext door te geven, wordt echte gedistribueerde tracering mogelijk gemaakt. Het is nu mogelijk om aanroepen van de client naar de server en terug te zien.

Deze nieuwe activiteiten zien er als volgt uit in het .NET Aspire dashboard:

gedeelde tracering

Network traces

Als u een probleem ondervindt, kan een netwerktracering soms waardevolle informatie bieden. Dit is vooral handig bij het indienen van een probleem op onze probleemtracker.

Een netwerktracering verzamelen met Fiddler (voorkeursoptie)

Deze methode werkt voor alle apps.

Fiddler is een krachtig hulpprogramma voor het verzamelen van HTTP-traceringen. Installeer het vanuit telerik.com/fiddler, start deze en voer vervolgens uw app uit en reproduceer het probleem. Fiddler is beschikbaar voor Windows en er zijn bètaversies voor macOS en Linux.

Als u verbinding maakt via HTTPS, zijn er enkele extra stappen om ervoor te zorgen dat Fiddler het HTTPS-verkeer kan ontsleutelen. Zie de Fiddler-documentatie voor meer informatie.

Nadat u de tracering hebt verzameld, exporteert u deze door Alle>sessies> te selecteren in de menubalk

Een netwerktracering verzamelen met tcpdump (alleen macOS en Linux)

Deze methode werkt voor alle apps.

Onbewerkte TCP-traceringen kunnen worden verzameld met tcpdump door de volgende opdracht uit te voeren vanuit een opdrachtshell. Mogelijk moet u root zijn of de opdracht vooraf laten gaan door sudo als u een toestemmingsfout krijgt:

tcpdump -i [interface] -w trace.pcap

Vervang door [interface] de netwerkinterface waarop u wilt vastleggen. Dit is meestal iets als /dev/eth0 (voor een standaard Ethernet-interface) of /dev/lo0 (voor localhost-verkeer). Zie de tcpdump handmatige pagina op uw hostsysteem voor meer informatie.

Een netwerktracering verzamelen in de browser

Deze methode werkt alleen voor browser-apps.

De meeste consoles voor browserontwikkelaars hebben een tabblad Netwerk waarmee netwerkactiviteit kan worden vastgelegd tussen de browser en de server. Deze traceringen bevatten echter geen WebSocket- en Server-Sent Gebeurtenisberichten. Wanneer u deze transporten gebruikt, is het gebruik van een hulpprogramma zoals Fiddler of TcpDump een betere aanpak, zoals verderop in dit artikel wordt beschreven.

Microsoft Edge en Internet Explorer

(De instructies zijn hetzelfde voor Zowel Microsoft Edge als Internet Explorer)

1. Open de Ontwikkelhulpprogramma's door op F12 te drukken
2. Selecteer het tabblad Netwerk
3. Vernieuw de pagina (indien nodig) en reproduceer het probleem
4. Selecteer het pictogram Opslaan op de werkbalk om de tracering te exporteren als een HAR-bestand:

Google Chrome

1. Open de Ontwikkelhulpprogramma's door op F12 te drukken
2. Selecteer het tabblad Netwerk
3. Vernieuw de pagina (indien nodig) en reproduceer het probleem
4. Klik met de rechtermuisknop op een willekeurige plaats in de lijst met aanvragen en kies Opslaan als HAR met inhoud:

Mozilla Firefox

1. Open de Ontwikkelhulpprogramma's door op F12 te drukken
2. Selecteer het tabblad Netwerk
3. Vernieuw de pagina (indien nodig) en reproduceer het probleem
4. Klik met de rechtermuisknop op een willekeurige plaats in de lijst met aanvragen en kies 'Alles opslaan als HAR'

Diagnostische bestanden toevoegen aan GitHub-problemen

Diagnostische bestanden kunnen worden gekoppeld aan GitHub-problemen door de naam ervan te wijzigen, zodat ze een .txt extensie hebben en ze vervolgens naar het probleem slepen en neerzetten.

Metrics

Metrische gegevens zijn een weergave van gegevensmetingen in intervallen van tijd. Bijvoorbeeld aanvragen per seconde. Metrische gegevens maken observatie van de status van een app op hoog niveau mogelijk. Metrische .NET gRPC-gegevens worden verzonden met behulp van EventCounter.

SignalR serverstatistieken

SignalR servermetriek wordt gerapporteerd via de Microsoft.AspNetCore.Http.Connections gebeurtenisbron.

Observe metrics

dotnet-counters is een hulpprogramma voor prestatiebewaking voor ad-hocstatusbewaking en prestatieonderzoek op het eerste niveau. Bewaak een .NET-app met Microsoft.AspNetCore.Http.Connections als providernaam. For example:

> 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

Additional resources

• ASP.NET Core SignalR-configuratie
• ASP.NET Core SignalR JavaScript-client
• ASP.NET Core SignalR .NET-client