Registro e diagnóstico no ASP.NET Core SignalR

Por Andrew Stanton-Nurse

Este artigo fornece orientação para coletar diagnósticos do seu aplicativo ASP.NET Core SignalR para ajudar a solucionar problemas.

Registo de logs no servidor

Warning

Os logs do lado do servidor podem conter informações confidenciais do seu aplicativo. Nunca publique logs brutos de aplicativos de produção em fóruns públicos como o GitHub.

Como SignalR faz parte do ASP.NET Core, ele usa o sistema de registro ASP.NET Core. Na configuração padrão, SignalR registra informações mínimas, mas o nível de log pode ser configurado. Consulte a documentação sobre o log do ASP.NET Core para obter detalhes sobre como configurar o log do ASP.NET Core.

SignalR usa duas categorias de logger:

• Microsoft.AspNetCore.SignalR: Para logs relacionados com Protocolos de Hub, ativação de Hubs, invocação de métodos e outras atividades relacionadas com Hubs.
• Microsoft.AspNetCore.Http.Connections: Para logs relacionados a transportes, como WebSockets, Long Polling, Server-Sent Events e infraestrutura de baixo nível SignalR .

Para habilitar registos detalhados de SignalR, configure ambos os prefixos anteriores para o nível Debug no seu ficheiro appsettings.json adicionando os seguintes elementos à subseção LogLevel em Logging:

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

Os níveis de log para as categorias do SignalR logger também podem ser configurados em código no método 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>();

Se você não estiver usando a configuração baseada em JSON, defina os seguintes valores de configuração em seu sistema de configuração:

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

Verifique a documentação do seu sistema de configuração para determinar como especificar valores de configuração aninhados. Por exemplo, ao usar variáveis de ambiente, dois _ caracteres são usados em vez do : (por exemplo, Logging__LogLevel__Microsoft.AspNetCore.SignalR).

Recomendamos usar o Debug nível ao coletar diagnósticos mais detalhados para seu aplicativo. O Trace nível produz diagnósticos de baixo nível e raramente é necessário para diagnosticar problemas em seu aplicativo.

Aceder aos logs do lado do servidor

Como os logs do lado do servidor são acessados depende do ambiente no qual o aplicativo está sendo executado.

Como um aplicativo de console fora do IIS

Se você estiver executando em um aplicativo de console, o registrador de console deverá ser habilitado por padrão. SignalR Os logs aparecem no console.

No ambiente do IIS Express do Visual Studio

O Visual Studio exibe a saída de log na janela de Saída. Selecione a opção suspensa ASP.NET Core Web Server.

Serviço de Aplicações do Azure

Habilite a opção Registo de Aplicação (sistema de ficheiros) na secção Registos de Diagnóstico no portal do Azure App Service e configure o Nível para Verbose. Os logs devem estar disponíveis no serviço de streaming de log e nos registos no sistema de arquivos do App Service. Para obter mais informações, consulte Transmissão de logs do Azure.

Outros ambientes

Para obter mais informações sobre como configurar provedores de log adequados para diferentes ambientes de implantação, como Docker, Kubernetes ou Serviço do Windows, consulte Fazendo login no .NET e no ASP.NET Core.

Registo do cliente JavaScript

Warning

Os logs do lado do cliente podem conter informações confidenciais do seu aplicativo. Nunca publique logs brutos de aplicativos de produção em fóruns públicos como o GitHub.

Ao usar o cliente JavaScript, você pode configurar as opções de log usando o configureLogging método em HubConnectionBuilder:

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

Desative o log da estrutura especificando signalR.LogLevel.None no configureLogging método. Observe que alguns registros são emitidos diretamente pelo navegador e não podem ser desativados por meio da configuração do nível de log.

A tabela a seguir mostra os níveis de log disponíveis para o cliente JavaScript. Definir o nível de registo para um destes valores permite o registo nesse nível e em todos os níveis superiores na tabela.

Level	Description
None	Nenhuma mensagem é registrada.
Critical	Mensagens que indicam uma falha em todo o aplicativo.
Error	Mensagens que indicam uma falha na operação atual.
Warning	Mensagens que indicam um problema não fatal.
Information	Mensagens informativas.
Debug	Mensagens de diagnóstico úteis para depuração.
Trace	Mensagens de diagnóstico muito detalhadas concebidas para diagnosticar problemas específicos.

Depois de configurar a verbosidade, os logs serão gravados na Consola do navegador (ou na saída standard numa aplicação NodeJS).

Se desejar enviar logs para um sistema de log personalizado, você pode fornecer um objeto JavaScript implementando a ILogger interface. O único método que precisa ser implementado é log, que leva o nível do evento e a mensagem associada ao evento. Por exemplo:

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

Log do cliente .NET

Warning

Os logs do lado do cliente podem conter informações confidenciais do seu aplicativo. Nunca publique logs brutos de aplicativos de produção em fóruns públicos como o GitHub.

Para obter logs do cliente .NET, você pode usar o ConfigureLogging método em HubConnectionBuilder. Isso funciona da mesma maneira que o ConfigureLogging método em WebHostBuilder e HostBuilder. Você pode configurar os mesmos provedores de log que usa no ASP.NET Core. No entanto, você precisa instalar e habilitar manualmente os pacotes NuGet para os provedores de log individuais.

Para adicionar o registo do cliente .NET a uma aplicação Blazor WebAssembly, consulte registo de ASP.NET Core Blazor.

Registo da consola

Para habilitar o log do console, adicione o pacote Microsoft.Extensions.Logging.Console . Em seguida, use o AddConsole método para configurar o registrador de console:

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

Registo da janela de saída de depuração

Os logs podem ser configurados para ir para a janela Saída no Visual Studio. Instale o pacote Microsoft.Extensions.Logging.Debug e use o AddDebug método:

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

Outros fornecedores de registo

SignalR suporta outros provedores de registro em log, como Serilog, Seq, NLog ou qualquer outro sistema de registro que se integre ao Microsoft.Extensions.Logging. Se o seu sistema de registo fornecer um ILoggerProvider, pode registá-lo com 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();

Controlar a verbosidade

Ao efetuar login de outros locais no aplicativo, alterar o nível padrão para Debug pode ser demasiado verboso. Um filtro pode ser usado para configurar o nível de log para SignalR logs. Isso pode ser feito em código, da mesma forma que no servidor:

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

Rastreio em SignalR

SignalR O servidor de hub e o SignalR cliente fornecem informações sobre SignalR conexões e mensagens usando DiagnosticSource e Activity. SignalR tem um ActivitySource para o servidor de hub e cliente, disponível a partir do .NET 9.

Um ActivitySource é um componente usado no rastreamento distribuído para criar e gerenciar atividades (ou spans) que representam operações em seu aplicativo. Estas atividades podem ser utilizadas para:

• Acompanhe o fluxo de solicitações e operações em diferentes componentes e serviços.
• Forneça informações valiosas sobre o desempenho e o comportamento do seu aplicativo.

Fonte de Atividade do servidor .NET SignalR

O SignalR ActivitySource chamado Microsoft.AspNetCore.SignalR.Server emite eventos para chamadas de método do hub:

• Cada método é uma atividade por si só, por isso, qualquer elemento que emita uma atividade durante a chamada do método hub está incluído na atividade do método hub.
• As atividades do método Hub não têm um pai. Isso significa que eles não são agrupados sob a conexão de longa duração SignalR .

O exemplo a seguir utiliza o painel Aspire e os pacotes de OpenTelemetry :

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

Adicione o seguinte código de inicialização ao arquivo Program.cs:

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

A saída de exemplo a seguir é do Aspire Dashboard:

ASP.NET Core também fornece suas próprias métricas sobre a origem do Microsoft.AspNetCore.Hosting evento.

Cliente .NET SignalR ActivitySource

O SignalRActivitySource nomeado Microsoft.AspNetCore.SignalR.Client emite eventos para um SignalR cliente:

• As invocações de hub criam uma extensão de cliente. Outros SignalR clientes, como o cliente JavaScript, não suportam rastreamento. Este recurso será adicionado a mais clientes em versões futuras.
• As invocações de hub no cliente e no servidor suportam propagação de contexto. A propagação do contexto de rastreamento permite o verdadeiro rastreamento distribuído. Agora é possível ver o fluxo de invocações do cliente para o servidor e vice-versa.

Veja como essas novas atividades aparecem no painel Aspire:

Rastreamentos de rede

Warning

Um rastreamento de rede contém o conteúdo completo de cada mensagem enviada pelo seu aplicativo. Nunca publique rastreamentos de rede brutos de aplicativos de produção para fóruns públicos como o GitHub.

Se você encontrar um problema, um rastreamento de rede às vezes pode fornecer informações valiosas. Isso é especialmente útil ao registrar um problema em nosso rastreador de problemas.

Coletar um rastreamento de rede com o Fiddler (opção preferencial)

Este método funciona para todas as aplicações.

O Fiddler é uma ferramenta poderosa para coletar rastreamentos HTTP. Instale-o a partir do telerik.com/fiddler, inicie-o e, em seguida, execute a sua aplicação e reproduza o problema. O Fiddler está disponível para Windows e existem versões beta para macOS e Linux.

Se você se conectar usando HTTPS, há algumas etapas extras para garantir que o Fiddler possa descriptografar o tráfego HTTPS. Para obter mais informações, consulte a documentação do Fiddler.

Depois de coletar o rastreamento, exporte-o selecionando Arquivo>salvar>todas as sessões na barra de menus

Coletar um rastreamento de rede com tcpdump (somente macOS e Linux)

Este método funciona para todas as aplicações.

Capturas TCP brutas podem ser coletadas usando o tcpdump executando o seguinte comando num shell de comandos. Talvez seja necessário ser root ou prefixar o comando com sudo se você receber um erro de permissões:

tcpdump -i [interface] -w trace.pcap

Substitua [interface] pela interface de rede na qual você deseja capturar. Normalmente, isso é algo como /dev/eth0 (para uma interface Ethernet padrão) ou /dev/lo0 (para o tráfego localhost). Para obter mais informações, consulte a página do manual no seu sistema de alojamento.

Recolher um registo de atividade de rede no navegador

Esse método só funciona para aplicativos baseados em navegador.

A maioria dos consoles de ferramentas de desenvolvedor de navegador tem uma guia "Rede" que permite que a atividade de rede seja capturada entre o navegador e o servidor. No entanto, esses rastreamentos não incluem mensagens WebSocket e Server-Sent Event. Ao usar esses transportes, usar uma ferramenta como Fiddler ou TcpDump é uma abordagem melhor, conforme descrito mais adiante neste artigo.

Microsoft Edge e Internet Explorer

(As instruções são as mesmas para o Microsoft Edge e o Internet Explorer)

1. Abra as Ferramentas de Desenvolvimento pressionando F12
2. Selecione a guia Rede
3. Atualize a página (se necessário) e reproduza o problema
4. Selecione o ícone Salvar na barra de ferramentas para exportar o rastreamento como um arquivo "HAR":

Google Chrome

1. Abra as Ferramentas de Desenvolvimento pressionando F12
2. Selecione a guia Rede
3. Atualize a página (se necessário) e reproduza o problema
4. Clique com o botão direito do mouse em qualquer lugar da lista de solicitações e escolha "Salvar como HAR com conteúdo":

Mozilla Firefox

1. Abra as Ferramentas de Desenvolvimento pressionando F12
2. Selecione a guia Rede
3. Atualize a página (se necessário) e reproduza o problema
4. Clique com o botão direito do mouse em qualquer lugar na lista de solicitações e escolha "Salvar tudo como HAR"

Anexar arquivos de diagnóstico a problemas do GitHub

Os arquivos de diagnóstico podem ser anexados aos problemas do GitHub, renomeando-os para que tenham uma .txt extensão e, em seguida, arrastando-os e soltando-os para o problema.

Note

Não cole o conteúdo de arquivos de log ou rastreamentos de rede em um problema do GitHub. Esses logs e rastreamentos podem ser grandes, e o GitHub geralmente os trunca.

Metrics

As métricas são uma representação de medidas de dados em intervalos de tempo. Por exemplo, solicitações por segundo. Os dados de métricas permitem a observação do estado de um aplicativo em um alto nível. As métricas gRPC do .NET são emitidas usando EventCounter.

SignalR métricas do servidor

SignalR As métricas do servidor são relatadas na origem do Microsoft.AspNetCore.Http.Connections evento.

Name	Description
connections-started	Total de conexões iniciadas
connections-stopped	Total de ligações interrompidas
connections-timed-out	Total de conexões com o tempo limite expirado
current-connections	Conexões atuais
connections-duration	Duração média da ligação

Observe as métricas

dotnet-counters é uma ferramenta de monitorização de desempenho para avaliação ad-hoc de integridade e investigação inicial de desempenho. Monitore uma aplicação .NET utilizando Microsoft.AspNetCore.Http.Connections como o nome do fornecedor. Por exemplo:

> 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

Recursos adicionais

• SignalR
• ASP.NET Core SignalR cliente JavaScript
• ASP.NET Core SignalR Cliente .NET