This is a brief guide to collecting diagnostic information from SignalR, both on the client and the server. When reporting errors, it's very useful if you can use this guide to provide as much information as you can so we can help diagnose the issue.
Attaching Diagnostics files to GitHub issues
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:
Server-side Logging
On the Server, SignalR integrates with the ILogger-based logging provided in the ASP.NET Core framework, see the documentation for a complete guide.
Before filing a bug, we recommend collecting a Debug level log from SignalR. How you collect this log depends on where the issue occurs.
Locally, using Kestrel directly
We recommend trying to use Kestrel directly, if you aren't already, as a first step. If the error occurs when using Kestrel, you can collect logs straight out of the console. You can enable Debug level logging by editing the appsettings.Development.json file (if you used the template) and adding the following two items to the "LogLevel" section in "Logging":
"Microsoft.AspNetCore.SignalR": "Debug",
"Microsoft.AspNetCore.Http.Connections": "Debug"
So, assuming you have the default appsettings.Development.json configuration, it should look something like this:
{
"Logging": {
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information",
"Microsoft.AspNetCore.SignalR": "Debug",
"Microsoft.AspNetCore.Http.Connections": "Debug"
}
}
}
If you are not using the appsettings.Development.json file, you can configure this in code in your Program.cs CreateWebHostBuilder method by adding a call to .ConfigureLogging to the chain of calls on the WebHostBuilder in that function:
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>();
Locally, using IIS Express
First, make the configuration changes described above in the "Locally, using Kestrel directly" section. If you are able to reproduce the error when using Kestrel directly, please include that in any bug report (and we suggest using that to gather diagnostics). If you can only reproduce the error when running in IIS/IIS Express, you can collect the same logs from Visual Studio (since there is no Console when running in IIS). When you run the application from Visual Studio you can see the server logs in the Output Window under the "ASP.NET Core Web Server" section.
Azure App Service
If you can only reproduce the issue when running on Azure App Service, you can enable "Application Logging (Filesystem)" in the "Diagnostics logs" section of the Azure portal and configure the Level to Verbose. Then, you should be able to get detailed logs from the "Log Streaming" service. See the documentation for more details.
JavaScript client logging
To get logs from the JavaScript client, you can use the .configureLogging method on HubConnectionBuilder to set the verbosity level of logs:
let connection = new signalR.HubConnectionBuilder()
.withUrl("/my/hub/url")
.configureLogging(signalR.LogLevel.Trace)
.build();
Once you've configured the verbosity, the logs will be written to the Browser Console (or Standard Output in a NodeJS application).
.NET client logging
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. You can configure the same logging providers you use in ASP.NET Core.
Console logging
In order to enable Console logging, add the Microsoft.Extensions.Logging.Console nuget package. Then, use code like the example below to configure the console logger:
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();
Debug output window logging
You can also configure logs to go to the Output Window in Visual Studio using the Microsoft.Extensions.Logging.Debug package, like so:
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();
Other logging providers
You can also use other logging providers such as Serilog, Seq, NLog, or any other logging system that integrates with Microsoft.Extensions.Logging. If you want to integrate your own logging system, you can implement the ILoggerProvider interface from Microsoft.Extensions.Logging and register it manually using .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();
Controlling verbosity
If the debug logs are too verbose, you can set the default minimum level to Information and just increase the logging level for SignalR logs:
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();
More info
See the Logging in ASP.NET Core documentation for more information, including a list of providers and the NuGet packages required to enable them.
Network Traces
It can also be useful to collect Network Traces so we can see any network traffic. Please note that these traces will contain the complete content of any HTTP traffic, so there may be sensitive data in them. Use caution when posting them in bug reports.
From the browser
NOTE: Most browsers don't include WebSocket and Server-Sent Event messages in exported network traces. If you are using those transports, using a tool like Fiddler or TcpDump (described below) might be a better approach.
If you are seeing an issue in the browser, most browser Dev Tools have a Network tab that lets you collect and export traces.
Microsoft Edge and Internet Explorer
(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:
Google Chrome
- 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":
Mozilla Firefox
- 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"
Using a network tracing tool
If your issue is occurring in the .NET Client or the Browser traces are insufficient for illustrating the issue, you can also gather traces using a network tracing tool.
Fiddler (Windows and macOS)
Fiddler is a very powerful tool for collecting HTTP traces. Simply install it from https://www.telerik.com/fiddler, launch it, and then run your application and reproduce the issue.
If you connect using HTTPS, there are some extra steps to ensure Fiddler can decrypt the HTTPS traffic. See the Fiddler Documentation for more details.
Once you've collected the trace, you can export the trace by choosing "File" > "Save" > "All Sessions..." from the menu bar.
TcpDump (macOS and Linux)
You can collect raw TCP traces using TcpDump by running the following command from a Terminal. 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 your standard Ethernet interface) or /dev/lo0 (for localhost traffic). See the tcpdump man page for more information.