Registrazione e diagnostica in gRPC in .NET

Di James Newton-King

Questo articolo fornisce indicazioni per raccogliere la diagnostica da un'app gRPC per risolvere i problemi. Gli argomenti trattati includono:

• Registrazione: log strutturati scritti nella registrazione di .NET Core. ILogger viene usato dai framework dell'app per scrivere i log e dagli utenti per la propria registrazione in un'app.
• Traccia : eventi correlati a un'operazione scritta tramite DiaganosticSource e Activity. Le tracce provenienti dall'origine diagnostica vengono comunemente usate per raccogliere i dati di telemetria delle app da librerie come Application Insights e OpenTelemetry.
• Metriche: rappresentazione delle misure dei dati in intervalli di tempo, ad esempio richieste al secondo. Le metriche vengono generate usando EventCounter e possono essere osservate usando lo strumento da riga di comando dotnet-counters o con Application Insights.

Registrazione

I servizi gRPC e il client gRPC scrivono i log usando la registrazione di .NET Core. I log sono un buon punto di partenza quando si esegue il debug di comportamenti imprevisti nelle app client e del servizio.

Registrazione dei servizi gRPC

Avviso

I log lato server possono contenere informazioni riservate dall'app. Non pubblicare mai log non elaborati dalle app di produzione a forum pubblici come GitHub.

Poiché i servizi gRPC sono ospitati in ASP.NET Core, usa il sistema di registrazione ASP.NET Core. Nella configurazione predefinita gRPC registra informazioni minime, ma è possibile configurare la registrazione. Per informazioni dettagliate sulla configurazione della registrazione ASP.NET Core, vedere la documentazione relativa alla registrazione di ASP.NET Core.

gRPC aggiunge i log nella Grpc categoria . Per abilitare i log dettagliati da gRPC, configurare i prefissi al Debug livello nel appsettings.json file aggiungendo gli elementi seguenti alla LogLevel sottosezione in Logging:Grpc

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

La registrazione può essere configurata anche in Program.cs con ConfigureLogging:

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

Quando non si usa la configurazione basata su JSON, impostare il valore di configurazione seguente nel sistema di configurazione:

• Logging:LogLevel:Grpc = Debug

Controllare la documentazione relativa al sistema di configurazione per determinare come specificare i valori di configurazione annidati. Ad esempio, quando si usano variabili di : ambiente, vengono usati due _ caratteri anziché ( ad esempio , Logging__LogLevel__Grpc).

È consigliabile usare il livello durante la Debug raccolta di diagnostica dettagliata per un'app. Il Trace livello produce diagnostica di basso livello ed è raramente necessario per diagnosticare i problemi.

Esempio di output di registrazione

Di seguito è riportato un esempio di output della console a Debug livello di un servizio 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

Accedere ai log lato server

Il modo in cui si accede ai log sul lato server dipende dall'ambiente dell'app.

Come app console

Se si esegue in un'app console, il logger console deve essere abilitato per impostazione predefinita. I log gRPC verranno visualizzati nella console.

Altri ambienti

Se l'app viene distribuita in un altro ambiente ,ad esempio Docker, Kubernetes o Servizio Windows, vedere Registrazione in .NET Core e ASP.NET Core per altre informazioni su come configurare i provider di registrazione adatti per l'ambiente.

Registrazione client gRPC

Avviso

I log lato client possono contenere informazioni riservate dall'app. Non pubblicare mai log non elaborati dalle app di produzione a forum pubblici come GitHub.

Per ottenere i log dal client .NET, impostare la GrpcChannelOptions.LoggerFactory proprietà quando viene creato il canale del client. Quando si chiama un servizio gRPC da un'app ASP.NET Core, la factory del logger può essere risolta dall'inserimento delle dipendenze:When calling a gRPC service from an ASP.NET Core app, 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);
    }
}

Un modo alternativo per abilitare la registrazione client consiste nell'usare la factory client gRPC per creare il client. Un client gRPC registrato con la factory client e risolto dall'inserimento delle dipendenze userà automaticamente la registrazione configurata dell'app.

Se l'app non usa l'inserimento delle dipendenze, creare una nuova ILoggerFactory istanza con LoggerFactory.Create. Per accedere a questo metodo, aggiungere il pacchetto Microsoft.Extensions.Logging all'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);

Ambiti di log del client gRPC

Il client gRPC aggiunge un ambito di registrazione ai log effettuati durante una chiamata gRPC. L'ambito include metadati correlati alla chiamata gRPC:

• GrpcMethodType : tipo di metodo gRPC. I valori possibili sono nomi di Grpc.Core.MethodType enumerazione. Ad esempio: Unary.
• GrpcUri : URI relativo del metodo gRPC. Ad esempio, /greet. Greeter/SayHellos.

Esempio di output di registrazione

Di seguito è riportato un esempio di output della console a Debug livello di un client 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.

Traccia

I servizi gRPC e il client gRPC forniscono informazioni sulle chiamate gRPC tramite DiagnosticSource e Activity.

• .NET gRPC usa un'attività per rappresentare una chiamata gRPC.
• Gli eventi di traccia vengono scritti nell'origine di diagnostica all'inizio e all'arresto dell'attività di chiamata gRPC.
• La traccia non acquisisce informazioni su quando i messaggi vengono inviati per tutta la durata delle chiamate di streaming gRPC.

Traccia del servizio gRPC

I servizi gRPC sono ospitati in ASP.NET Core, che segnala gli eventi relativi alle richieste HTTP in ingresso. I metadati specifici di gRPC vengono aggiunti alla diagnostica delle richieste HTTP esistente fornita da ASP.NET Core.

• Il nome dell'origine di diagnostica è Microsoft.AspNetCore.
• Il nome dell'attività è Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Il nome del metodo gRPC richiamato dalla chiamata gRPC viene aggiunto come tag con il nome grpc.method.
  • Il codice di stato della chiamata gRPC al termine viene aggiunto come tag con il nome grpc.status_code.

Traccia client gRPC

Il client gRPC .NET usa HttpClient per effettuare chiamate gRPC. Sebbene HttpClient scriva eventi di diagnostica, il client .NET gRPC fornisce un'origine diagnostica personalizzata, un'attività e eventi in modo che sia possibile raccogliere informazioni complete su una chiamata gRPC.

• Il nome dell'origine di diagnostica è Grpc.Net.Client.
• Il nome dell'attività è Grpc.Net.Client.GrpcOut.
  • Il nome del metodo gRPC richiamato dalla chiamata gRPC viene aggiunto come tag con il nome grpc.method.
  • Il codice di stato della chiamata gRPC al termine viene aggiunto come tag con il nome grpc.status_code.

Raccolta della traccia

Il modo più semplice per usare DiagnosticSource consiste nel configurare una libreria di telemetria, ad esempio Application Insights o OpenTelemetry nell'app. La libreria elabora informazioni sulle chiamate gRPC insieme ad altri dati di telemetria dell'app.

La traccia può essere visualizzata in un servizio gestito come Application Insights o eseguita come sistema di traccia distribuito. OpenTelemetry supporta l'esportazione dei dati di traccia in Jaeger e Zipkin.

DiagnosticSource può utilizzare gli eventi di traccia nel codice usando DiagnosticListener. Per informazioni sull'ascolto di un'origine diagnostica con codice, vedere la guida dell'utente di DiagnosticSource.

Nota

Le librerie di telemetria non acquisiscono attualmente dati di telemetria specifici Grpc.Net.Client.GrpcOut di gRPC. Il lavoro per migliorare le librerie di telemetria che acquisisce questa traccia è in corso.

Metrica

Le metriche sono una rappresentazione delle misure dei dati in intervalli di tempo, ad esempio le richieste al secondo. I dati delle metriche consentono di osservare lo stato di un'app a un livello elevato. Le metriche di .NET gRPC vengono generate usando EventCounter.

Metriche del servizio gRPC

Le metriche del server gRPC vengono segnalate nell'origine Grpc.AspNetCore.Server evento.

Nome	Descrizione
total-calls	Chiamate totali
current-calls	Chiamate correnti
calls-failed	Totale chiamate non riuscite
calls-deadline-exceeded	Scadenza totale chiamate superata
messages-sent	Totale messaggi inviati
messages-received	Totale messaggi ricevuti
calls-unimplemented	Totale chiamate non implementate

ASP.NET Core fornisce anche le proprie metriche sull'origine Microsoft.AspNetCore.Hosting evento.

Metriche client gRPC

Le metriche del client gRPC vengono segnalate nell'origine Grpc.Net.Client evento.

Nome	Descrizione
total-calls	Chiamate totali
current-calls	Chiamate correnti
calls-failed	Totale chiamate non riuscite
calls-deadline-exceeded	Scadenza totale chiamate superata
messages-sent	Totale messaggi inviati
messages-received	Totale messaggi ricevuti

Osservare le metriche

dotnet-counters è uno strumento di monitoraggio delle prestazioni per il monitoraggio dell'integrità ad hoc e l'analisi delle prestazioni di primo livello. Monitorare un'app .NET con Grpc.AspNetCore.Server o Grpc.Net.Client come nome del provider.

> 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

Un altro modo per osservare le metriche gRPC consiste nell'acquisire i dati dei contatori usando il pacchetto Microsoft.ApplicationInsights.EventCounterCollector di Application Insights. Dopo l'installazione, Application Insights raccoglie i contatori .NET comuni in fase di esecuzione. I contatori di gRPC non vengono raccolti per impostazione predefinita, ma App Insights può essere personalizzato per includere contatori aggiuntivi.

Specificare i contatori gRPC per Application Insight da raccogliere 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"));
            }
        );
    }

Risorse aggiuntive

• Registrazione in .NET Core e ASP.NET Core
• configurazione di gRPC per .NET
• Integrazione della factory client gRPC in .NET