aspnetcore/signalr/diagnostics.md
This article provides guidance for gathering diagnostics from your ASP.NET Core SignalR app to help troubleshoot issues.
[!WARNING] Server-side logs may contain sensitive information from your app. Never post raw logs from production apps to public forums like GitHub.
Since SignalR is part of ASP.NET Core, it uses the ASP.NET Core logging system. In the default configuration, SignalR logs minimal information, but the logging level can be configured. See the documentation on ASP.NET Core logging for details on configuring ASP.NET Core logging.
SignalR uses two logger categories:
Microsoft.AspNetCore.SignalR: For logs related to Hub Protocols, activating Hubs, invoking methods, and other Hub-related activities.Microsoft.AspNetCore.Http.Connections: For logs related to transports, such as WebSockets, Long Polling, Server-Sent Events, and low-level SignalR infrastructure.To enable detailed logs from SignalR, configure both of the preceding prefixes to the Debug level in your appsettings.json file by adding the following items to the LogLevel subsection in Logging:
The logging levels for the SignalR logger categories can also be configured in code within the CreateWebHostBuilder method:
If you aren't using JSON-based configuration, set the following configuration values in your configuration system:
Logging:LogLevel:Microsoft.AspNetCore.SignalR = DebugLogging:LogLevel:Microsoft.AspNetCore.Http.Connections = DebugCheck the documentation for your configuration system to determine how to specify nested configuration values. For example, when using environment variables, two _ characters are used instead of the : (for example, Logging__LogLevel__Microsoft.AspNetCore.SignalR).
We recommend using the Debug level when gathering more detailed diagnostics for your app. The Trace level produces low-level diagnostics and is rarely needed to diagnose issues in your app.
How server-side logs are accessed depends on the environment in which the app is running.
If you're running in a console app, the Console logger should be enabled by default. SignalR logs appear in the console.
Visual Studio displays the log output in the Output window. Select the ASP.NET Core Web Server drop down option.
Enable the Application Logging (Filesystem) option in the Diagnostics logs section of the Azure App Service portal and configure the Level to Verbose. Logs should be available from the Log streaming service and in logs on the file system of the App Service. For more information, see Azure log streaming.
For more information on configuring logging providers suitable for different deployment environments, such as Docker, Kubernetes, or Windows Service, see xref:fundamentals/logging/index.
[!WARNING] Client-side logs may contain sensitive information from your app. Never post raw logs from production apps to public forums like GitHub.
When using the JavaScript client, you can configure logging options using the configureLogging method on HubConnectionBuilder:
Disable framework logging by specifying signalR.LogLevel.None in the configureLogging method. Note that some logging is emitted directly by the browser and can't be disabled via setting the log level.
The following table shows log levels available to the JavaScript client. Setting the log level to one of these values enables logging at that level and all levels above it in the table.
| Level | Description |
|---|---|
None | No messages are logged. |
Critical | Messages that indicate a failure in the entire app. |
Error | Messages that indicate a failure in the current operation. |
Warning | Messages that indicate a non-fatal problem. |
Information | Informational messages. |
Debug | Diagnostic messages useful for debugging. |
Trace | Very detailed diagnostic messages designed for diagnosing specific issues. |
Once you've configured the verbosity, the logs will be written to the Browser Console (or Standard Output in a NodeJS app).
If you want to send logs to a custom logging system, you can provide a JavaScript object implementing the ILogger interface. The only method that needs to be implemented is log, which takes the level of the event and the message associated with the event. For example:
:::moniker range=">= aspnetcore-3.0"
:::moniker-end
:::moniker range="< aspnetcore-3.0"
:::moniker-end
[!WARNING] Client-side logs may contain sensitive information from your app. Never post raw logs from production apps to public forums like GitHub.
To get logs from the .NET client, you can use the ConfigureLogging method on HubConnectionBuilder. This works the same way as the ConfigureLogging method on WebHostBuilder and HostBuilder. You can configure the same logging providers you use in ASP.NET Core. However, you have to manually install and enable the NuGet packages for the individual logging providers.
To add .NET client logging to a Blazor WebAssembly app, see xref:blazor/fundamentals/logging#signalr-net-client-logging.
In order to enable Console logging, add the Microsoft.Extensions.Logging.Console package. Then, use the AddConsole method to configure the console logger:
Logs can be configured to go to the Output window in Visual Studio. Install the Microsoft.Extensions.Logging.Debug package and use the AddDebug method:
SignalR supports other logging providers such as Serilog, Seq, NLog, or any other logging system that integrates with Microsoft.Extensions.Logging. If your logging system provides an ILoggerProvider, you can register it with AddProvider:
When logging from other places in the app, changing the default level to Debug may be too verbose. A Filter can be used to configure the logging level for SignalR logs. This can be done in code, in much the same way as on the server:
[!code-csharpControlling verbosity in .NET client]
SignalR hub server and the SignalR client provide information about SignalR connections and messages using xref:System.Diagnostics.DiagnosticSource and xref:System.Diagnostics.Activity. SignalR has an ActivitySource for both the hub server and client, avaialble starting with .NET 9.
An ActivitySource is a component used in distributed tracing to create and manage activities (or spans) that represent operations in your application. These activities can be used to:
The SignalR ActivitySource named Microsoft.AspNetCore.SignalR.Server emits events for hub method calls:
The following example uses the Aspire dashboard and the OpenTelemetry packages:
<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" />
Add the following startup code to the Program.cs file:
The following example output is from the Aspire Dashboard:
:::image type="content" source="~/signalr/diagnostics/_static/9.x/signalr-activities-events.png" alt-text="Activity list for SignalR Hub method call events":::
ASP.NET Core also provides its own metrics on Microsoft.AspNetCore.Hosting event source.
The SignalR ActivitySource named Microsoft.AspNetCore.SignalR.Client emits events for a SignalR client:
Here's how these new activities look in the Aspire dashboard:
[!WARNING] A network trace contains the full contents of every message sent by your app. Never post raw network traces from production apps to public forums like GitHub.
If you encounter an issue, a network trace can sometimes provide a valuable information. This is especially helpful when filing an issue on our issue tracker.
This method works for all apps.
Fiddler is a powerful tool for collecting HTTP traces. Install it from telerik.com/fiddler, launch it, and then run your app and reproduce the issue. Fiddler is available for Windows, and there are beta versions for macOS and Linux.
If you connect using HTTPS, there are some extra steps to ensure Fiddler can decrypt the HTTPS traffic. For more information, see the Fiddler documentation.
After collecting the trace, export it by selecting File > Save > All Sessions from the menu bar
This method works for all apps.
Raw TCP traces can be collected using tcpdump by running the following command from a command shell. You may need to be root or prefix the command with sudo if you get a permissions error:
tcpdump -i [interface] -w trace.pcap
Replace [interface] with the network interface you wish to capture on. Usually, this is something like /dev/eth0 (for a standard Ethernet interface) or /dev/lo0 (for localhost traffic). For more information, see the tcpdump manual page on your host system.
This method only works for browser-based apps.
Most browser developer tools consoles have a "Network" tab that allows network activity to be captured between the browser and the server. However, these traces don't include WebSocket and Server-Sent Event messages. When using those transports, using a tool like Fiddler or TcpDump is a better approach, as described later in this article.
(The instructions are the same for both Microsoft Edge and Internet Explorer)
Diagnostics files can be attached to GitHub issues by renaming them so they have a .txt extension and then dragging and dropping them on to the issue.
[!NOTE] Please don't paste the content of log files or network traces into a GitHub issue. These logs and traces can be large, and GitHub usually truncates them.
Metrics are a representation of data measures over intervals of time. For example, requests per second. Metrics data allows observation of the state of an app at a high level. .NET gRPC metrics are emitted using xref:System.Diagnostics.Tracing.EventCounter.
SignalR server metrics are reported on the xref:Microsoft.AspNetCore.Http.Connections event source.
| Name | Description |
|---|---|
connections-started | Total connections started |
connections-stopped | Total connections stopped |
connections-timed-out | Total connections timed out |
current-connections | Current connections |
connections-duration | Average connection duration |
dotnet-counters is a performance monitoring tool for ad-hoc health monitoring and first-level performance investigation. Monitor a .NET app with Microsoft.AspNetCore.Http.Connections as the provider name. 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