| title | author | description | monikerRange | ms.author | ms.custom | ms.date | uid |
|---|---|---|---|---|---|---|---|
Logging and diagnostics in ASP.NET Core SignalR |
bradygaster |
Learn how to gather diagnostics from your ASP.NET Core SignalR app. |
>= aspnetcore-2.1 |
wpickett |
devx-track-csharp, signalr, linux-related-content |
11/20/2024 |
signalr/diagnostics |
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 very little information, but this can 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 sub-section in Logging:
You can also configure this in code in your 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=Debug
Check 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 very low-level diagnostics and is rarely needed to diagnose issues in your app.
SignalR has an ActivitySource for both the hub server and client, avaialble starting wtih .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 track the flow of requests and operations across different components and services, providing valuable insights into the performance and behavior of your application.
The SignalR ActivitySource named Microsoft.AspNetCore.SignalR.Server emits events for hub method calls:
- Every method is its own activity, so anything that emits an activity during the hub method call is under the hub method activity.
- Hub method activities don't have a parent. This means they are not bundled under the long-running SignalR connection.
The following example uses the .NET 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 is example output 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":::
The SignalR ActivitySource named Microsoft.AspNetCore.SignalR.Client emits events for a SignalR client:
- The .NET SignalR client has an
ActivitySourcenamedMicrosoft.AspNetCore.SignalR.Client. Hub invocations now create a client span. Note that other SignalR clients, such as the JavaScript client, don't support tracing. This feature will be added to more clients in future releases. - Hub invocations on the client and server support context propagation. Propagating the trace context enables true distributed tracing. It's now possible to see invocations flow from the client to the server and back.
Here's how these new activities look in the .NET Aspire dashboard:
How you access server-side logs depends on the environment in which you're running.
If you're running in a console app, the Console logger should be enabled by default. SignalR logs will 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.
If the app is deployed to another environment (for example, Docker, Kubernetes, or Windows Service), see xref:fundamentals/logging/index for more information on how to configure logging providers suitable for the environment.
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:
To disable framework logging, specify 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:
You can also configure logs 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:
If you are logging from other places in your app, changing the default level to Debug may be too verbose. You can use a Filter 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]
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 lot of helpful information. This is particularly useful if you're going to file an issue on our issue tracker.
This method works for all apps.
Fiddler is a very 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 details, see the Fiddler documentation.
Once you've collected the trace, you can export the trace by choosing File > Save > All Sessions from the menu bar.
This method works for all apps.
You can collect raw TCP traces 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.pcapReplace [interface] with the network interface you wish to capture on. Usually, this is something like /dev/eth0 (for your standard Ethernet interface) or /dev/lo0 (for localhost traffic). For more information, see the tcpdump man page on your host system.
This method only works for browser-based apps.
Most browser developer tools consoles have a "Network" tab that allows you to capture network activity between the browser and the server. However, these traces don't include WebSocket and Server-Sent Event messages. If you are using those transports, using a tool like Fiddler or TcpDump (described below) is a better approach.
(The instructions are the same for both Edge and Internet Explorer)
- Press F12 to open the Dev Tools
- Click the Network Tab
- Refresh the page (if needed) and reproduce the problem
- Click the Save icon in the toolbar to export the trace as a "HAR" file:
- Press F12 to open the Dev Tools
- Click the Network Tab
- Refresh the page (if needed) and reproduce the problem
- Right click anywhere in the list of requests and choose "Save as HAR with content":
- Press F12 to open the Dev Tools
- Click the Network Tab
- Refresh the page (if needed) and reproduce the problem
- Right click anywhere in the list of requests and choose "Save All As HAR"
You can attach Diagnostics files 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 quite large, and GitHub usually truncates them.
Metrics is 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 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- xref:signalr/configuration
- xref:signalr/javascript-client
- xref:signalr/dotnet-client