ASP.NET Core SignalR 中的日志记录和诊断Logging and diagnostics in ASP.NET Core SignalR

本文内容

作者： Andrew Stanton

本文介绍如何从 ASP.NET Core SignalR 应用收集诊断信息，以帮助解决问题。

服务器端日志记录Server-side logging

警告

服务器端日志可能包含应用中的敏感信息。请勿将原始日志从生产应用发布到 GitHub 等公共论坛。

由于 SignalR 是 ASP.NET Core 的一部分，因此它使用 ASP.NET Core 日志记录系统。在默认配置中，SignalR 记录的信息非常小，但这可以进行配置。有关配置 ASP.NET Core 日志记录的详细信息，请参阅有关ASP.NET Core 日志记录的文档。

SignalR 使用两个记录器类别：

• 为与集线器协议相关的日志 Microsoft.AspNetCore.SignalR –，激活集线器，调用方法，以及其他与集线器相关的活动。
• Microsoft.AspNetCore.Http.Connections 与传输相关的日志 –，如 Websocket、长轮询和服务器发送事件以及低级别 SignalR 基础结构。

若要从 SignalR 启用详细日志，请通过将以下项添加到 Logging中的 LogLevel 子部分，将上述两个前缀配置为appsettings文件中的 Debug 级别：

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

你还可以在 CreateWebHostBuilder 方法的代码中对此进行配置：

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

如果不使用基于 JSON 的配置，请在配置系统中设置以下配置值：

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

查看配置系统的文档以确定如何指定嵌套配置值。例如，使用环境变量时，将使用两个 _ 字符，而不是 : （例如 LoggingLogLevelMicrosoft.AspNetCore.SignalR）。

建议在为应用收集更详细的诊断时使用 Debug 级别。Trace 级别产生非常低级别的诊断，很少需要诊断应用程序中的问题。

访问服务器端日志Access server-side logs

访问服务器端日志的方式取决于运行的环境。

作为 IIS 外部的控制台应用As a console app outside IIS

如果在控制台应用中运行，则默认情况下应启用控制台记录器。SignalR 日志将显示在控制台中。

在 Visual Studio IIS Express 中Within IIS Express from Visual Studio

Visual Studio 会在 "输出" 窗口中显示日志输出。选择ASP.NET Core Web 服务器"下拉选项。

Azure 应用服务Azure App Service

在 Azure App Service 门户的 "诊断日志" 部分中，启用 "应用程序日志记录（文件系统） " 选项，并将级别配置为 Verbose。日志流服务和应用服务文件系统的日志中应提供日志。有关详细信息，请参阅Azure 日志流式处理。

其他环境Other environments

如果将应用部署到另一个环境（例如 Docker、Kubernetes 或 Windows 服务），请参阅 .NET Core 和 ASP.NET Core 中的日志记录，了解有关如何配置适用于环境的日志记录提供程序的详细信息。

JavaScript 客户端日志记录JavaScript client logging

警告

客户端日志可能包含应用中的敏感信息。请勿将原始日志从生产应用发布到 GitHub 等公共论坛。

使用 JavaScript 客户端时，可以使用 HubConnectionBuilder上的 configureLogging 方法配置日志记录选项：

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

若要完全禁用日志记录，请在 configureLogging 方法中指定 signalR.LogLevel.None。

下表显示了可用于 JavaScript 客户端的日志级别。将日志级别设置为这些值之一，可以在表中对该级别和其之上的所有级别进行日志记录。

配置详细级别后，日志将写入浏览器控制台（或 NodeJS 应用中的标准输出）。

如果要将日志发送到自定义日志记录系统，可以提供实现 ILogger 接口的 JavaScript 对象。需要实现的唯一方法是 log，它将使用事件的级别和与事件关联的消息。例如：

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 客户端日志记录.NET client logging

警告

客户端日志可能包含应用中的敏感信息。请勿将原始日志从生产应用发布到 GitHub 等公共论坛。

若要从 .NET 客户端获取日志，可以使用 HubConnectionBuilder上的 ConfigureLogging 方法。这与 WebHostBuilder 和 HostBuilder上的 ConfigureLogging 方法的工作方式相同。你可以配置 ASP.NET Core 中使用的相同日志记录提供程序。但是，您必须为单独的日志提供程序手动安装和启用 NuGet 包。

控制台日志记录Console logging

若要启用控制台日志记录，请添加""。然后，使用 AddConsole 方法配置控制台记录器：

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

还可以配置日志，以便在 Visual Studio 中切换到 "输出" 窗口。安装 " "，然后使用 AddDebug 方法：

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

SignalR 支持其他日志记录提供程序，如 Serilog、Seq、NLog 或与 Microsoft.Extensions.Logging集成的任何其他日志记录系统。如果日志记录系统提供 ILoggerProvider，则可以将其注册 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

如果要从应用中的其他位置进行日志记录，则将默认级别更改为 Debug 可能会过于详细。您可以使用筛选器来配置 SignalR 日志的日志记录级别。可以在代码中完成此操作，其方式与在服务器上的操作大致相同：

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

网络跟踪Network traces

警告

网络跟踪包含应用发送的每个消息的全部内容。切勿将原始网络跟踪从生产应用发布到 GitHub 等公共论坛。

如果遇到问题，网络跟踪有时可以提供很多有用的信息。如果要在我们的问题跟踪程序上发布问题，此方法特别有用。

使用 Fiddler 收集网络跟踪（首选选项）Collect a network trace with Fiddler (preferred option)

此方法适用于所有应用。

Fiddler 是一个非常强大的工具，用于收集 HTTP 跟踪。从telerik.com/fiddler安装它，启动它，然后运行你的应用程序并重现此问题。Fiddler 适用于 Windows，并且有适用于 macOS 和 Linux 的 beta 版本。

如果使用 HTTPS 进行连接，则需要执行一些额外的步骤来确保 Fiddler 可以解密 HTTPS 流量。有关更多详细信息，请参阅Fiddler 文档。

收集跟踪后，可以通过从菜单栏中选择 "文件" "文件" > "保存" > 所有会话"来导出跟踪。

使用 tcpdump 收集网络跟踪（仅限 macOS 和 Linux）Collect a network trace with tcpdump (macOS and Linux only)

此方法适用于所有应用。

可以通过在命令行界面中运行以下命令，使用 tcpdump 收集原始 TCP 跟踪。如果出现权限错误，你可能需要 root，或在命令前面加上前缀 sudo：

tcpdump -i [interface] -w trace.pcap

将 [interface] 替换为要捕获的网络接口。通常，这与 /dev/eth0 （适用于标准以太网接口）或 /dev/lo0 （对于 localhost 流量）类似。有关详细信息，请参阅主机系统上的 tcpdump 手册页。

在浏览器中收集网络跟踪Collect a network trace in the browser

此方法仅适用于基于浏览器的应用。

大多数浏览器开发人员工具都有一个 "网络" 选项卡，该选项卡允许您捕获浏览器和服务器之间的网络活动。但是，这些跟踪不包括 WebSocket 和服务器发送的事件消息。如果正在使用这些传输，则使用 Fiddler 或 TcpDump 等工具（如下所述）是更好的方法。

Microsoft Edge 和 Internet ExplorerMicrosoft Edge and Internet Explorer

（对于边缘和 Internet Explorer，说明是相同的）

• 按 F12 打开开发工具
• 单击 "网络" 选项卡
• 刷新页面（如果需要）并重现问题
• 单击工具栏中的 "保存" 图标，将跟踪作为 "HAR" 文件导出：
  

Google ChromeGoogle Chrome

• 按 F12 打开开发工具
• 单击 "网络" 选项卡
• 刷新页面（如果需要）并重现问题
• 右键单击请求列表中的任意位置，然后选择 "另存为包含内容的 HAR"：
  

Mozilla FirefoxMozilla Firefox

• 按 F12 打开开发工具
• 单击 "网络" 选项卡
• 刷新页面（如果需要）并重现问题
• 右键单击请求列表中的任意位置，然后选择 "全部保存为 HAR"
  

将诊断文件附加到 GitHub 问题Attach diagnostics files to GitHub issues

可以通过对其进行重命名，将诊断文件附加到 GitHub 问题，以便它们具有 .txt 扩展，然后将其拖放到问题上。

备注

请不要将日志文件或网络跟踪的内容粘贴到 GitHub 问题中。这些日志和跟踪可能会很大，GitHub 通常会将其截断。

其他资源Additional resources

• ASP.NET Core SignalR 配置
• ASP.NET Core SignalR JavaScript 客户端
• .NET 客户端 SignalR ASP.NET Core