Registro em log e diagnóstico no gRPC no .NETLogging and diagnostics in gRPC on .NET

Por James Newton – KingBy James Newton-King

Este artigo fornece diretrizes para coletar diagnósticos de um aplicativo gRPC para ajudar a solucionar problemas.This article provides guidance for gathering diagnostics from a gRPC app to help troubleshoot issues. Os tópicos abordados incluem:Topics covered include:

  • Logs estruturados em log gravados no log do .NET Core.Logging - Structured logs written to .NET Core logging. ILoggeré usado pelas estruturas de aplicativo para gravar logs e por usuários para seus próprios registros em um aplicativo.ILogger is used by app frameworks to write logs, and by users for their own logging in an app.
  • Rastreamento -eventos relacionados a uma operação escrita usando DiaganosticSource e Activity .Tracing - Events related to an operation written using DiaganosticSource and Activity. Os rastreamentos da fonte de diagnóstico são comumente usados para coletar telemetria de aplicativo por bibliotecas como Application insights e OpenTelemetry.Traces from diagnostic source are commonly used to collect app telemetry by libraries such as Application Insights and OpenTelemetry.
  • Métricas – representação de medidas de dados em intervalos de tempo, por exemplo, solicitações por segundo.Metrics - Representation of data measures over intervals of time, for example, requests per second. As métricas são emitidas usando EventCounter e podem ser observadas usando a ferramenta de linha de comando dotnet-Counters ou com Application insights.Metrics are emitted using EventCounter and can be observed using dotnet-counters command line tool or with Application Insights.

Registrando em logLogging

os serviços gRPC e o cliente gRPC gravam logs usando o log do .NET Core.gRPC services and the gRPC client write logs using .NET Core logging. Os logs são um bom lugar para começar quando você precisa depurar um comportamento inesperado em seus aplicativos.Logs are a good place to start when you need to debug unexpected behavior in your apps.

log de serviços gRPCsgRPC services logging

Aviso

Os logs do lado do servidor podem conter informações confidenciais do seu aplicativo.Server-side logs may contain sensitive information from your app. Nunca poste logs brutos de aplicativos de produção em fóruns públicos, como o github.Never post raw logs from production apps to public forums like GitHub.

Como os serviços gRPCs são hospedados em ASP.NET Core, ele usa o sistema de registro em log de ASP.NET Core.Since gRPC services are hosted on ASP.NET Core, it uses the ASP.NET Core logging system. Na configuração padrão, o gRPC registra muito pouca informação, mas isso pode ser configurado.In the default configuration, gRPC logs very little information, but this can configured. Consulte a documentação em log de ASP.NET Core para obter detalhes sobre como configurar o log de ASP.NET Core.See the documentation on ASP.NET Core logging for details on configuring ASP.NET Core logging.

gRPC adiciona logs na Grpc categoria.gRPC adds logs under the Grpc category. Para habilitar logs detalhados do gRPC, configure os Grpc prefixos para o Debug nível em seu appsettings.jsno arquivo adicionando os seguintes itens à LogLevel subseção em Logging :To enable detailed logs from gRPC, configure the Grpc prefixes to the Debug level in your appsettings.json file by adding the following items to the LogLevel sub-section in Logging:

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

Você também pode configurar isso em Startup.cs com ConfigureLogging :You can also configure this in Startup.cs with ConfigureLogging:

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

Se você não estiver usando a configuração baseada em JSON, defina o seguinte valor de configuração em seu sistema de configuração:If you aren't using JSON-based configuration, set the following configuration value in your configuration system:

  • Logging:LogLevel:Grpc = Debug

Verifique a documentação do seu sistema de configuração para determinar como especificar valores de configuração aninhados.Check the documentation for your configuration system to determine how to specify nested configuration values. Por exemplo, ao usar variáveis de ambiente, dois _ caracteres são usados em vez do : (por exemplo, Logging__LogLevel__Grpc ).For example, when using environment variables, two _ characters are used instead of the : (for example, Logging__LogLevel__Grpc).

É recomendável usar o Debug nível ao coletar diagnósticos mais detalhados para seu aplicativo.We recommend using the Debug level when gathering more detailed diagnostics for your app. O Trace nível produz diagnósticos de nível muito baixo e raramente é necessário para diagnosticar problemas em seu aplicativo.The Trace level produces very low-level diagnostics and is rarely needed to diagnose issues in your app.

Exemplo de saída de registro em logSample logging output

Aqui está um exemplo de saída do console no Debug nível de um serviço gRPC:Here is an example of console output at the Debug level of a gRPC service:

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 servidorAccess server-side logs

A maneira como você acessa os logs do lado do servidor depende do ambiente no qual você está executando o.How you access server-side logs depends on the environment in which you're running.

Como um aplicativo de consoleAs a console app

Se você estiver executando o em um aplicativo de console, o agente de log do console deverá ser habilitado por padrão.If you're running in a console app, the Console logger should be enabled by default. os logs do gRPC serão exibidos no console do.gRPC logs will appear in the console.

Outros ambientesOther environments

Se o aplicativo for implantado em outro ambiente (por exemplo, Docker, kubernetes ou serviço do Windows), consulte Como fazer registro em log no .NET Core e no ASP.NET Core para obter mais informações sobre como configurar provedores de log adequados para o ambiente.If the app is deployed to another environment (for example, Docker, Kubernetes, or Windows Service), see Como fazer registro em log no .NET Core e no ASP.NET Core for more information on how to configure logging providers suitable for the environment.

log de cliente do gRPCgRPC client logging

Aviso

Os logs do lado do cliente podem conter informações confidenciais do seu aplicativo.Client-side logs may contain sensitive information from your app. Nunca poste logs brutos de aplicativos de produção em fóruns públicos, como o github.Never post raw logs from production apps to public forums like GitHub.

Para obter logs do cliente .NET, você pode definir a GrpcChannelOptions.LoggerFactory propriedade quando o canal do cliente é criado.To get logs from the .NET client, you can set the GrpcChannelOptions.LoggerFactory property when the client's channel is created. Se você estiver chamando um serviço gRPC de um aplicativo ASP.NET Core, a fábrica do agente poderá ser resolvida da injeção de dependência (DI):If you are calling a gRPC service from an ASP.NET Core app then the logger factory can be resolved from dependency injection (DI):

[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 a fábrica do cliente do gRPC para criar o cliente.An alternative way to enable client logging is to use the gRPC client factory to create the client. Um cliente gRPC registrado com a fábrica do cliente e resolvido a partir de DI usará automaticamente o log configurado do aplicativo.A gRPC client registered with the client factory and resolved from DI will automatically use the app's configured logging.

Se seu aplicativo não estiver usando DI, você poderá criar uma nova ILoggerFactory instância com LoggerFactory. Create.If your app isn't using DI then you can create a new ILoggerFactory instance with LoggerFactory.Create. Para acessar esse método, adicione o pacote Microsoft. Extensions. Logging ao seu aplicativo.To access this method add the Microsoft.Extensions.Logging package to your app.

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 gRPCgRPC client log scopes

O cliente gRPC adiciona um escopo de log aos logs feitos durante uma chamada gRPC.The gRPC client adds a logging scope to logs made during a gRPC call. O escopo tem metadados relacionados à chamada gRPC:The scope has metadata related to the gRPC call:

  • GrpcMethodType -o tipo de método gRPC.GrpcMethodType - The gRPC method type. Os valores possíveis são nomes de Grpc.Core.MethodType enum, por exemplo, unárioPossible values are names from Grpc.Core.MethodType enum, e.g. Unary
  • GrpcUri -o URI relativo do método gRPC, por exemplo,/Greet. Greeter/SayHellosGrpcUri - The relative URI of the gRPC method, e.g. /greet.Greeter/SayHellos

Exemplo de saída de registro em logSample logging output

Aqui está um exemplo de saída do console no Debug nível de um cliente gRPC:Here is an example of console output at the Debug level of a gRPC client:

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.

RastreamentoTracing

os serviços gRPC e o cliente gRPC fornecem informações sobre chamadas gRPC usando a diagnóstico e a atividade.gRPC services and the gRPC client provide information about gRPC calls using DiagnosticSource and Activity.

  • O .NET gRPC usa uma atividade para representar uma chamada gRPC..NET gRPC uses an activity to represent a gRPC call.
  • Os eventos de rastreamento são gravados na fonte de diagnóstico no início e na parada da atividade de chamada gRPC.Tracing events are written to the diagnostic source at the start and stop of the gRPC call activity.
  • O rastreamento não captura informações sobre quando as mensagens são enviadas durante o tempo de vida das chamadas de streaming gRPC.Tracing doesn't capture information about when messages are sent over the lifetime of gRPC streaming calls.

rastreamento de serviço gRPCgRPC service tracing

os serviços gRPCs são hospedados em ASP.NET Core que relata eventos sobre solicitações HTTP de entrada.gRPC services are hosted on ASP.NET Core which reports events about incoming HTTP requests. os metadados específicos do gRPC são adicionados ao diagnóstico de solicitação HTTP existente que o ASP.NET Core fornece.gRPC specific metadata is added to the existing HTTP request diagnostics that ASP.NET Core provides.

  • O nome da origem do diagnóstico é Microsoft.AspNetCore .Diagnostic source name is Microsoft.AspNetCore.
  • O nome da atividade é Microsoft.AspNetCore.Hosting.HttpRequestIn .Activity name is Microsoft.AspNetCore.Hosting.HttpRequestIn.
    • O nome do método gRPC invocado pela chamada gRPC é adicionado como uma marca com o nome grpc.method .Name of the gRPC method invoked by the gRPC call is added as a tag with the name grpc.method.
    • O código de status da chamada gRPC quando ela é concluída é adicionado como uma marca com o nome grpc.status_code .Status code of the gRPC call when it is complete is added as a tag with the name grpc.status_code.

rastreamento de cliente gRPCgRPC client tracing

O cliente .NET gRPC usa HttpClient para fazer chamadas gRPC.The .NET gRPC client uses HttpClient to make gRPC calls. Embora HttpClient o grave eventos de diagnóstico, o cliente .net gRPC fornece uma fonte de diagnóstico, atividade e eventos personalizados para que as informações completas sobre uma chamada gRPC possam ser coletadas.Although HttpClient writes diagnostic events, the .NET gRPC client provides a custom diagnostic source, activity and events so that complete information about a gRPC call can be collected.

  • O nome da origem do diagnóstico é Grpc.Net.Client .Diagnostic source name is Grpc.Net.Client.
  • O nome da atividade é Grpc.Net.Client.GrpcOut .Activity name is Grpc.Net.Client.GrpcOut.
    • O nome do método gRPC invocado pela chamada gRPC é adicionado como uma marca com o nome grpc.method .Name of the gRPC method invoked by the gRPC call is added as a tag with the name grpc.method.
    • O código de status da chamada gRPC quando ela é concluída é adicionado como uma marca com o nome grpc.status_code .Status code of the gRPC call when it is complete is added as a tag with the name grpc.status_code.

Coletando rastreamentoCollecting tracing

A maneira mais fácil de usar DiagnosticSource é configurar uma biblioteca de telemetria, como Application insights ou OpenTelemetry em seu aplicativo.The easiest way to use DiagnosticSource is to configure a telemetry library such as Application Insights or OpenTelemetry in your app. A biblioteca processará informações sobre chamadas gRPC em outras telemetrias do aplicativo.The library will process information about gRPC calls along-side other app telemetry.

O rastreamento pode ser exibido em um serviço gerenciado como Application Insights ou você pode optar por executar seu próprio sistema de rastreamento distribuído.Tracing can be viewed in a managed service like Application Insights, or you can choose to run your own distributed tracing system. O OpenTelemetry dá suporte à exportação de dados de rastreamento para Jaeger e Zipkin.OpenTelemetry supports exporting tracing data to Jaeger and Zipkin.

DiagnosticSourcepode consumir eventos de rastreamento no código usando DiagnosticListener .DiagnosticSource can consume tracing events in code using DiagnosticListener. Para obter informações sobre como escutar uma fonte de diagnóstico com código, consulte o Guia do usuário do diagnosticm.For information about listening to a diagnostic source with code, see the DiagnosticSource user's guide.

Observação

As bibliotecas de telemetria não capturam telemetria específica do gRPC Grpc.Net.Client.GrpcOut no momento.Telemetry libraries do not capture gRPC specific Grpc.Net.Client.GrpcOut telemetry currently. Trabalho para melhorar as bibliotecas de telemetria capturando esse rastreamento está em andamento.Work to improve telemetry libraries capturing this tracing is ongoing.

MétricasMetrics

Métricas é uma representação de medidas de dados em intervalos de tempo, por exemplo, solicitações por segundo.Metrics is a representation of data measures over intervals of time, for example, requests per second. Os dados de métricas permitem a observação do estado de um aplicativo em um alto nível.Metrics data allows observation of the state of an app at a high-level. As métricas do .NET gRPC são emitidas usando EventCounter ..NET gRPC metrics are emitted using EventCounter.

métricas do serviço gRPCgRPC service metrics

as métricas do servidor gRPC são relatadas na Grpc.AspNetCore.Server origem do evento.gRPC server metrics are reported on Grpc.AspNetCore.Server event source.

NameName DescriçãoDescription
total-calls Total de ChamadasTotal Calls
current-calls Chamadas atuaisCurrent Calls
calls-failed Total de chamadas com falhaTotal Calls Failed
calls-deadline-exceeded Prazo total de chamadas excedidoTotal Calls Deadline Exceeded
messages-sent Total de Mensagens EnviadasTotal Messages Sent
messages-received Total de mensagens recebidasTotal Messages Received
calls-unimplemented Total de chamadas não implementadasTotal Calls Unimplemented

ASP.NET Core também fornece suas próprias métricas na Microsoft.AspNetCore.Hosting origem do evento.ASP.NET Core also provides its own metrics on Microsoft.AspNetCore.Hosting event source.

métricas do cliente gRPCgRPC client metrics

as métricas do cliente gRPC são relatadas na Grpc.Net.Client origem do evento.gRPC client metrics are reported on Grpc.Net.Client event source.

NameName DescriçãoDescription
total-calls Total de ChamadasTotal Calls
current-calls Chamadas atuaisCurrent Calls
calls-failed Total de chamadas com falhaTotal Calls Failed
calls-deadline-exceeded Prazo total de chamadas excedidoTotal Calls Deadline Exceeded
messages-sent Total de Mensagens EnviadasTotal Messages Sent
messages-received Total de mensagens recebidasTotal Messages Received

Observar métricasObserve metrics

dotnet-os contadores são uma ferramenta de monitoramento de desempenho para monitoramento de integridade ad hoc e investigação de desempenho de primeiro nível.dotnet-counters is a performance monitoring tool for ad-hoc health monitoring and first-level performance investigation. Monitore um aplicativo .NET com Grpc.AspNetCore.Server Grpc.Net.Client o ou como o nome do provedor.Monitor a .NET app with either Grpc.AspNetCore.Server or Grpc.Net.Client as the provider name.

> 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 do gRPC é capturar dados do contador usando o pacote Microsoft. ApplicationInsights. EventCounterCollectorda Application insights.Another way to observe gRPC metrics is to capture counter data using Application Insights's Microsoft.ApplicationInsights.EventCounterCollector package. Depois da instalação, o Application Insights coleta contadores comuns do .NET em tempo de execução.Once setup, Application Insights collects common .NET counters at runtime. os contadores de gRPC não são coletados por padrão, mas o app insights pode ser personalizado para incluir contadores adicionais.gRPC's counters are not collected by default, but App Insights can be customized to include additional counters.

Especifique os contadores de gRPC para o Application insights coletar em Startup.cs:Specify the gRPC counters for Application Insight to collect in 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 adicionaisAdditional resources