Registro em log e diagnóstico no ASP.NET Core SignalR

Por Andrew Stanton-Nurse

Este artigo fornece diretrizes para você coletar os diagnósticos do seu aplicativo ASP.NET Core SignalR para ajudar a solucionar problemas.

Registro em log no lado do servidor

Aviso

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

Como o SignalR faz parte do ASP.NET Core, ele utiliza o sistema de logs do ASP.NET Core. Na configuração padrão, o SignalR registra muito poucas informações, mas isso pode ser configurado. Confira a documentação sobre Registro em log do ASP.NET Core para obter detalhes sobre como configurar o registro em log do ASP.NET Core.

SignalR utiliza duas categorias de registradores:

• Microsoft.AspNetCore.SignalR: Para os logs relacionados aos protocolos do hub, ativação de hubs, invocação de métodos e outras atividades relacionadas ao hub.
• Microsoft.AspNetCore.Http.Connections: Para os logs relacionados a transportes, como WebSockets, Polling longo, eventos enviados pelo servidor e infraestrutura SignalR de baixo nível.

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

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

Você também pode configurar isso no código no seu 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 utilizando 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 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 que você utilize o nível Debug ao coletar os diagnósticos mais detalhados para o seu aplicativo. O nível Trace produz diagnósticos de nível muito baixo e raramente são necessários para diagnosticar problemas no seu aplicativo.

Acessar logs do lado do servidor

A forma como você acessa os logs do lado do servidor depende do ambiente no qual você está executando.

Como um aplicativo de console fora do IIS

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

No IIS Express a partir do Visual Studio

O Visual Studio exibe a saída dos logs na janela Saída. Selecione a opção da lista suspensa Servidor Web ASP.NET Core.

Serviço de aplicativo do Azure

Habilite a opção Application Logging (Filesystem) na seção Logs de Diagnóstico do portal do Serviço de Aplicativo do Azure e configure o Nível para Verbose. Os logs devem estar disponíveis no serviço Streaming de log e nos logs do sistema de arquivos do Serviço de Aplicativo. Para obter mais informações, confira Streaming de Log do Azure.

Outros ambientes

Se o aplicativo for implantado em outro ambiente (por exemplo, Docker, Kubernetes ou Serviço Windows), confira Registro em log no .NET Core e ASP.NET Core para obter mais informações sobre como configurar provedores de log adequados para o ambiente.

Registrar em log cliente JavaScript

Aviso

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

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

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

Para desabilitar o registro em log da estrutura, especifique signalR.LogLevel.None no método configureLogging. Observe que alguns registros em log são emitidos diretamente pelo navegador e não podem ser desabilitados por meio da configuração do nível de registro.

A tabela a seguir mostra os níveis de registro em log disponíveis para o cliente JavaScript. Se você definir o nível de log para um desses valores, habilitará o registro em log nesse nível e em todos os níveis acima dele na tabela.

Nível	Descrição
None	Nenhuma mensagem está registrada em log.
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 utilizadas para depuração.
Trace	Mensagens de diagnóstico muito detalhadas projetadas para diagnosticar problemas específicos.

Depois que você configurar o detalhamento, os logs serão gravados no Console do navegador (ou na Saída Standard em um aplicativo NodeJS).

Se quiser enviar os logs para um sistema de registro personalizado, você poderá fornecer um objeto JavaScript que implemente a interface ILogger. O único método que precisa ser implementado é log, que recebe 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();

Registrar em log cliente .NET

Aviso

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

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

Para adicionar o registro em log do cliente .NET a um aplicativo Blazor WebAssembly, confira ASP.NET Core Blazor registro em log.

Log de console

Para habilitar o registro em log do Console, adicione o pacote Microsoft.Extensions.Logging.Console. Em seguida, utilize o método AddConsole para configurar o agente do 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();

Registro em log da janela de saída da depuração

Você também pode configurar os logs para serem enviados para a janela de Saída no Visual Studio. Instale o pacote Microsoft.Extensions.Logging.Debug e utilize o método 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();

Outros provedores de registro em log

O SignalR tem suporte para 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 registro em log fornecer um ILoggerProvider, você poderá registrá-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();

Controle o detalhamento

Se você estiver registrando em log em outros lugares do seu aplicativo, alterar o nível padrão para Debug pode ser muito detalhado. Você pode utilizar um filtro para configurar o nível de registro em log para os logs SignalR. Isso pode ser feito no 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();

Rastreamentos de rede

Aviso

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

Se você encontrar um problema, um rastreamento de rede às vezes pode fornecer muitas informações úteis. Isso é particularmente útil se você for registrar um problema no nosso rastreador de problemas.

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

Esse método funciona para todos os aplicativos.

O Fiddler é uma ferramenta muito eficiente para coletar rastreamentos de HTTP. Instale-o do telerik.com/fiddler, inicialize e, em seguida, execute seu aplicativo e reproduza o problema. O Fiddler está disponível para Windows e há versões beta para macOS e Linux.

Se você se conectar usando HTTPS, haverá algumas etapas adicionais para garantir que o Fiddler possa descriptografar o tráfego HTTPS. Para obter mais detalhes, confira a documentação do Fiddler.

Depois de coletar o rastreamento, você pode exportar o rastreamento escolhendo Arquivo>Salvar>Todas as Sessões na barra de menus.

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

Esse método funciona para todos os aplicativos.

Você pode coletar rastreamentos TCP brutos usando tcpdump executando o comando a seguir em um shell de comando. 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 que você deseja capturar. Normalmente, isso será semelhante a /dev/eth0 (para sua interface Ethernet padrão) ou /dev/lo0 (para o tráfego localhost). Para obter mais informações, consulte a página de manual tcpdump no sistema host.

Coletar um rastreamento de rede no navegador

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

A maioria dos consoles de ferramentas de desenvolvimento de navegador precisa de uma guia "Rede" que permite que você capture a atividade de rede entre o navegador e o servidor. No entanto, esses rastreamentos não incluem mensagens WebSocket e Server-Sent Event. Se você estiver utilizando esses transportes, usar uma ferramenta como o Fiddler ou o TcpDump (descrito abaixo) é uma abordagem melhor.

Microsoft Edge e Internet Explorer

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

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

Google Chrome

1. Pressione F12 para abrir as Ferramentas de Desenvolvimento
2. Clique na 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. Pressione F12 para abrir as Ferramentas de Desenvolvimento
2. Clique na 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 Tudo Como HAR"

Anexar os arquivos de diagnóstico aos problemas do GitHub

Você pode anexar arquivos de diagnóstico a problemas do GitHub renomeando-os para que eles tenham uma extensão .txt e, em seguida, arrastando-os e soltando-os no problema.

Observação

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

Métricas

Métrica é 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.

Métricas do servidor SignalR

As métricas do servidor SignalR são relatadas na fonte de eventos Microsoft.AspNetCore.Http.Connections.

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

Observar métricas

dotnet-counters é uma ferramenta de monitoramento de desempenho para monitoramento de integridade ad hoc e investigação de desempenho de primeiro nível. Monitore um aplicativo .NET com Microsoft.AspNetCore.Http.Connections como o nome do provedor. Por exemplo:

> 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

Recursos adicionais

• Configuração do ASP.NET Core SignalR
• Cliente ASP.NET Core JavaScriptSignalR
• ASP.NET Core SignalR Cliente .NET