Registro em log e diagnóstico no gRPC no .NET

Por James Newton-King

Este artigo fornece diretrizes para coletar diagnósticos de um aplicativo gRPC para ajudar a solucionar problemas. Os tópicos abordados incluem:

• Registro em log – logs estruturados gravados no log do .NET Core. ILogger é usado por estruturas de aplicativos para gravar logs e por usuários para seus próprios logs em um aplicativo.
• Rastreamento – eventos relacionados a uma operação escrita usando DiaganosticSource e Activity. Os rastreamentos da fonte de diagnóstico são comumente usados para coletar telemetria de aplicativo por bibliotecas como o Application Insights e OpenTelemetry.
• Métricas – representação de medidas de dados em intervalos de tempo como, por exemplo, solicitações por segundo. As métricas são emitidas usando o EventCounter e podem ser observadas usando a ferramenta de linha de comando dotnet-counters ou o Application Insights.

Log

Os serviços gRPC e os logs de gravação do cliente gRPC usando o log do .NET Core. Os logs são um bom lugar para começar ao depurar comportamentos inesperados em aplicativos cliente e de serviço.

Registro em log de serviços gRPC

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 os serviços gRPC são hospedados no ASP.NET Core, ele usa o sistema de registro em log do ASP.NET Core. Na configuração padrão, o gRPC registra informações mínimas, mas o log 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.

O gRPC adiciona logs na categoria Grpc. Para habilitar logs detalhados do gRPC, configure os prefixos Grpc para o nível de Debug no arquivo appsettings.json adicionando os seguintes itens à subseção LogLevel em Logging:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information",
      "Grpc": "Debug"
    }
  }
}

O registro em log também pode ser configurado em Program.cs com ConfigureLogging:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.AddFilter("Grpc", LogLevel.Debug);
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Ao não usar a configuração baseada em JSON, defina o seguinte valor de configuração no sistema de configuração:

• Logging:LogLevel:Grpc = 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__Grpc).

É recomendável usar o nível de Debug ao coletar diagnósticos detalhados para um aplicativo. O nível de Trace produz diagnóstico de baixo nível e raramente é necessário para diagnosticar problemas.

Exemplo de saída de registro em log

Aqui está um exemplo de saída do console no nível de Debug de um serviço gRPC:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 POST https://localhost:5001/Greet.Greeter/SayHello application/grpc
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /Greet.Greeter/SayHello'
dbug: Grpc.AspNetCore.Server.ServerCallHandler[1]
      Reading message.
info: GrpcService.GreeterService[0]
      Hello World
dbug: Grpc.AspNetCore.Server.ServerCallHandler[6]
      Sending message.
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /Greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 1.4113ms 200 application/grpc

Acessar logs do lado do servidor

A forma como os logs do lado do servidor são acessados depende do ambiente do aplicativo.

Como um aplicativo de console

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

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.

Registro em log do cliente gRPC

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 logs do cliente .NET, defina a propriedade GrpcChannelOptions.LoggerFactory quando o canal do cliente for criado. Ao chamar um serviço gRPC de um aplicativo ASP.NET Core,o alocador de agentes pode ser resolvido com base na DI (injeção de dependência):

[ApiController]
[Route("[controller]")]
public class GreetingController : ControllerBase
{
    private ILoggerFactory _loggerFactory;

    public GreetingController(ILoggerFactory loggerFactory)
    {
        _loggerFactory = loggerFactory;
    }

    [HttpGet]
    public async Task<ActionResult<string>> Get(string name)
    {
        var channel = GrpcChannel.ForAddress("https://localhost:5001",
            new GrpcChannelOptions { LoggerFactory = _loggerFactory });
        var client = new Greeter.GreeterClient(channel);

        var reply = await client.SayHelloAsync(new HelloRequest { Name = name });
        return Ok(reply.Message);
    }
}

Uma maneira alternativa de habilitar o log do cliente é usar o alocador de clientes gRPC para criar o cliente. Um cliente gRPC registrado no alocador de clientes e resolvido na DI usará automaticamente o log configurado do aplicativo.

Se o aplicativo não estiver usando a DI, crie uma nova instância ILoggerFactory com LoggerFactory.Create. Para acessar esse método, adicione o pacote Microsoft.Extensions.Logging ao seu aplicativo.

var loggerFactory = LoggerFactory.Create(logging =>
{
    logging.AddConsole();
    logging.SetMinimumLevel(LogLevel.Debug);
});

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { LoggerFactory = loggerFactory });

var client = Greeter.GreeterClient(channel);

Escopos de log do cliente gRPC

O cliente gRPC adiciona um escopo de registro em log para logs criados durante a chamada gRPC. O escopo tem metadados relacionados à chamada gRPC:

• GrpcMethodType – o tipo de método gRPC. Os valores possíveis são nomes da enumeração Grpc.Core.MethodType. Por exemplo, Unary.
• GrpcUri – o URI relativo do método gRPC. Por exemplo, /greet.Greeter/SayHellos.

Exemplo de saída de registro em log

Aqui está um exemplo de saída do console no nível de Debug de um cliente gRPC:

dbug: Grpc.Net.Client.Internal.GrpcCall[1]
      Starting gRPC call. Method type: 'Unary', URI: 'https://localhost:5001/Greet.Greeter/SayHello'.
dbug: Grpc.Net.Client.Internal.GrpcCall[6]
      Sending message.
dbug: Grpc.Net.Client.Internal.GrpcCall[1]
      Reading message.
dbug: Grpc.Net.Client.Internal.GrpcCall[4]
      Finished gRPC call.

Rastreamento

Os serviços gRPC e o cliente gRPC fornecem informações sobre chamadas gRPC usando DiagnosticSource e Activity.

• O gRPC do .NET usa uma atividade para representar uma chamada gRPC.
• Os eventos de rastreamento são gravados na fonte de diagnóstico no início e na parada da atividade de chamada gRPC.
• O rastreamento não captura informações sobre quando as mensagens são enviadas ao longo do tempo de vida das chamadas de fluxo de dados gRPC.

Rastreamento de serviço gRPC

Os serviços gRPC são hospedados no ASP.NET Core, que relata eventos sobre solicitações HTTP de entrada. Os metadados específicos do gRPC são adicionados ao diagnóstico de solicitação HTTP existente que o ASP.NET Core fornece.

• O nome da fonte de diagnóstico é Microsoft.AspNetCore.
• O nome da atividade é Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • O nome do método gRPC invocado pela chamada gRPC é adicionado como uma marca com o nome grpc.method.
  • O código de status da chamada gRPC quando ela for concluída é adicionado como uma marca com o nome grpc.status_code.

Rastreamento de cliente gRPC

O cliente gRPC do .NET usa HttpClient para fazer chamadas gRPC. Embora HttpClient grave eventos de diagnóstico, o cliente gRPC do .NET fornece uma fonte de diagnóstico, atividade e eventos personalizados para que informações completas sobre uma chamada gRPC possam ser coletadas.

• O nome da fonte de diagnóstico é Grpc.Net.Client.
• O nome da atividade é Grpc.Net.Client.GrpcOut.
  • O nome do método gRPC invocado pela chamada gRPC é adicionado como uma marca com o nome grpc.method.
  • O código de status da chamada gRPC quando ela for concluída é adicionado como uma marca com o nome grpc.status_code.

Coletando rastreamento

A maneira mais fácil de usar DiagnosticSource é configurar uma biblioteca de telemetria, como o Application Insights ou o OpenTelemetry em seu aplicativo. A biblioteca processará informações sobre chamadas gRPC junto com outras telemetrias de aplicativo.

O rastreamento pode ser exibido em um serviço gerenciado, como o Application Insights, ou executado como seu próprio sistema de rastreamento distribuído. O OpenTelemetry dá suporte à exportação de dados de rastreamento para Jaeger e Zipkin.

DiagnosticSource pode consumir eventos de rastreamento no código usando DiagnosticListener. Para obter informações sobre como ouvir uma fonte de diagnóstico com código, confira o Guia do usuário do DiagnosticSource.

Observação

Atualmente, as bibliotecas de telemetria não capturam a telemetria específica Grpc.Net.Client.GrpcOut do gRPC. Estão sendo realizados trabalhos para melhorar as bibliotecas de telemetria que capturam esse rastreamento.

Métricas

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.

Métricas do serviço gRPC

As métricas do servidor gRPC são relatadas na origem do evento Grpc.AspNetCore.Server.

Nome	Descrição
total-calls	Total de Chamadas
current-calls	Chamadas atuais
calls-failed	Total de chamadas com falha
calls-deadline-exceeded	Prazo total de chamadas excedido
messages-sent	Total de Mensagens Enviadas
messages-received	Total de mensagens recebidas
calls-unimplemented	Total de chamadas não implementadas

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

Métricas do cliente gRPC

As métricas do cliente gRPC são relatadas na origem do evento Grpc.Net.Client.

Nome	Descrição
total-calls	Total de Chamadas
current-calls	Chamadas atuais
calls-failed	Total de chamadas com falha
calls-deadline-exceeded	Prazo total de chamadas excedido
messages-sent	Total de Mensagens Enviadas
messages-received	Total de mensagens recebidas

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 Grpc.AspNetCore.Server ou Grpc.Net.Client como o nome do provedor.

> dotnet-counters monitor --process-id 1902 Grpc.AspNetCore.Server

Press p to pause, r to resume, q to quit.
    Status: Running
[Grpc.AspNetCore.Server]
    Total Calls                                 300
    Current Calls                               5
    Total Calls Failed                          0
    Total Calls Deadline Exceeded               0
    Total Messages Sent                         295
    Total Messages Received                     300
    Total Calls Unimplemented                   0

Outra maneira de observar as métricas gRPC é capturar dados de contador usando o pacote Microsoft.ApplicationInsights.EventCounterCollector do Application Insights. Após a instalação, o Application Insights coleta contadores .NET comuns no runtime. Os contadores do gRPC não são coletados por padrão, mas o App Insights pode ser personalizado para incluir contadores adicionais.

Especifique os contadores gRPC para o Application Insight coletar em Startup.cs:

    using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        //... other code...

        services.ConfigureTelemetryModule<EventCounterCollectionModule>(
            (module, o) =>
            {
                // Configure App Insights to collect gRPC counters gRPC services hosted in an ASP.NET Core app
                module.Counters.Add(new EventCounterCollectionRequest("Grpc.AspNetCore.Server", "current-calls"));
                module.Counters.Add(new EventCounterCollectionRequest("Grpc.AspNetCore.Server", "total-calls"));
                module.Counters.Add(new EventCounterCollectionRequest("Grpc.AspNetCore.Server", "calls-failed"));
            }
        );
    }

Recursos adicionais

• Log no .NET Core e no ASP.NET Core
• gRPC para configuração do .NET
• Integração de fábrica do cliente gRPC no .NET