Logboekregistratie en diagnostische gegevens in gRPC op .NET

Door James Newton-King

Dit artikel bevat richtlijnen voor het verzamelen van diagnostische gegevens van een gRPC-app om problemen op te lossen. Onderwerpen die worden behandeld, zijn onder andere:

• Logboekregistratie : gestructureerde logboeken die naar .NET-logboekregistratie zijn geschreven. ILogger wordt gebruikt door app-frameworks voor het schrijven van logboeken en door gebruikers voor hun eigen logboekregistratie in een app.
• Tracering : gebeurtenissen met betrekking tot een bewerking die is geschreven met behulp van DiaganosticSource en Activity. Traceringen uit de diagnostische bron worden vaak gebruikt voor het verzamelen van app-telemetriegegevens door bibliotheken zoals Application Insights en OpenTelemetry.
• Metrische gegevens : weergave van gegevensmetingen met intervallen van tijd, bijvoorbeeld aanvragen per seconde. Metrieken worden uitgestraald met behulp van EventCounter en kunnen worden geobserveerd met het opdrachtregelprogramma dotnet-counters of met Application Insights.

Logging

gRPC-services en de gRPC-client schrijven logboeken met behulp van .NET-logboekregistratie. Logboeken zijn een goede plek om te beginnen bij het opsporen van fouten in onverwacht gedrag in service- en client-apps.

logboekregistratie van gRPC-services

Warning

Logboeken aan de serverzijde kunnen gevoelige informatie uit uw app bevatten. Post nooit onbewerkte logboeken van productie-apps naar openbare forums zoals GitHub.

Omdat gRPC-services worden gehost op ASP.NET Core, wordt het ASP.NET Core-logboekregistratiesysteem gebruikt. In de standaardconfiguratie kunnen gRPC-logboeken minimale informatie bevatten, maar logboekregistratie kan worden geconfigureerd. Zie de documentatie over ASP.NET Core-logboekregistratie voor meer informatie over het configureren van ASP.NET Core-logboekregistratie.

gRPC voegt logboeken toe onder de Grpc categorie. Als u gedetailleerde logboeken van gRPC wilt inschakelen, configureert u de Grpc voorvoegsels op het Debug niveau in het appsettings.json bestand door de volgende items toe te voegen aan de LogLevel subsectie in Logging:

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

Loggen kan ook worden geconfigureerd in Program.cs met ConfigureLogging:

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

Als u geen JSON-configuratie gebruikt, stelt u de volgende configuratiewaarde in het configuratiesysteem in:

• Logging:LogLevel:Grpc = Debug

Raadpleeg de documentatie voor uw configuratiesysteem om te bepalen hoe geneste configuratiewaarden moeten worden opgegeven. Als u bijvoorbeeld omgevingsvariabelen gebruikt, worden er twee _ tekens gebruikt in plaats van de : (bijvoorbeeld Logging__LogLevel__Grpc).

We raden aan het Debug-niveau te gebruiken bij het verzamelen van gedetailleerde diagnostische gegevens voor een app. Het Trace niveau produceert diagnostische gegevens op laag niveau en is zelden nodig om problemen te diagnosticeren.

Voorbeeld loguitvoer

Hier volgt een voorbeeld van console-uitvoer op het Debug niveau van een 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

Logboeken aan serverzijde openen

Hoe logboeken aan de serverzijde worden geopend, is afhankelijk van de omgeving van de app.

Als console-app

Als u in een console-app werkt, moet de consolelogger standaard zijn ingeschakeld. gRPC-logboeken worden weergegeven in de console.

Andere omgevingen

Als de app is geïmplementeerd in een andere omgeving (bijvoorbeeld Docker, Kubernetes of Windows Service), raadpleegt u Logboekregistratie in .NET en ASP.NET Core voor meer informatie over het configureren van logboekregistratieproviders die geschikt zijn voor de omgeving.

gRPC-clientlogboekregistratie

Warning

Logboeken aan de clientzijde kunnen gevoelige informatie uit uw app bevatten. Post nooit onbewerkte logboeken van productie-apps naar openbare forums zoals GitHub.

Als u logboeken van de .NET-client wilt ophalen, stelt u de GrpcChannelOptions.LoggerFactory eigenschap in wanneer het kanaal van de client wordt gemaakt. Wanneer u een gRPC-service aanroept vanuit een ASP.NET Core-app, kan de logger factory worden omgezet vanuit afhankelijkheidsinjectie (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);
    }
}

U kunt ook clientlogboekregistratie inschakelen door de gRPC-clientfactory te gebruiken om de client te maken. Een gRPC-client die is geregistreerd bij de clientfactory en opgelost vanuit DI, gebruikt automatisch de geconfigureerde logboekregistratie van de app.

Als de app geen DI gebruikt, maakt u een nieuwe ILoggerFactory instantie met LoggerFactory.Create. Als u toegang wilt krijgen tot deze methode, voegt u het pakket Microsoft.Extensions.Logging toe aan uw 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);

gRPC-clientlogboekbereiken

De gRPC-client voegt een logboekbereik toe aan logboeken die zijn gemaakt tijdens een gRPC-aanroep. De scope bevat metadata die verband houdt met de gRPC-aanroep.

• GrpcMethodType - Het type gRPC-methode. Mogelijke waarden zijn enumnamen van Grpc.Core.MethodType. Bijvoorbeeld: Unary.
• GrpcUri - De relatieve URI van de gRPC-methode. Bijvoorbeeld /greet. Greeter/SayHellos.

Voorbeeld loguitvoer

Hier volgt een voorbeeld van console-uitvoer op het Debug niveau van een 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.

Tracing

gRPC-services en de gRPC-client bieden informatie over gRPC-aanroepen die gebruikmaken van DiagnosticSource en Activity.

• .NET gRPC gebruikt een activiteit om een gRPC-aanroep weer te geven.
• Traceringsgebeurtenissen worden aan het begin en einde van de gRPC-aanroepactiviteit naar de diagnostische bron geschreven.
• Tracering legt geen informatie vast over wanneer berichten worden verzonden gedurende de levensduur van gRPC-streaming-aanroepen.

gRPC-servicetracering

gRPC-services worden gehost op ASP.NET Core, waarin gebeurtenissen over binnenkomende HTTP-aanvragen worden gerapporteerd. gRPC-specifieke metagegevens worden toegevoegd aan de bestaande diagnostische http-aanvraag die ASP.NET Core biedt.

• De naam van de diagnostische bron is Microsoft.AspNetCore.
• De naam van de activiteit is Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • De naam van de gRPC-methode die door de gRPC-aanroep wordt aangeroepen, wordt toegevoegd als een tag met de naam grpc.method.
  • Statuscode van de gRPC-aanroep wanneer deze is voltooid, wordt toegevoegd als een tag met de naam grpc.status_code.

gRPC-clienttracering

De .NET gRPC-client maakt gebruik HttpClient van gRPC-aanroepen. Hoewel de .NET gRPC-client diagnostische gebeurtenissen schrijft, biedt het een aangepaste diagnostische bron, activiteit en gebeurtenissen, zodat volledige informatie over een gRPC-aanroep kan worden verzameld.

• De naam van de diagnostische bron is Grpc.Net.Client.
• De naam van de activiteit is Grpc.Net.Client.GrpcOut.
  • De naam van de gRPC-methode die door de gRPC-aanroep wordt aangeroepen, wordt toegevoegd als een tag met de naam grpc.method.
  • Statuscode van de gRPC-aanroep wanneer deze is voltooid, wordt toegevoegd als een tag met de naam grpc.status_code.

Traceergegevens verzamelen

De eenvoudigste manier om te gebruiken DiagnosticSource is het configureren van een telemetriebibliotheek, zoals Application Insights of OpenTelemetry in uw app. De bibliotheek verwerkt informatie over gRPC-aanroepen naast andere app-telemetrie.

Tracering kan worden weergegeven in een beheerde service, zoals Application Insights, of worden uitgevoerd als uw eigen gedistribueerde traceringssysteem. OpenTelemetry biedt ondersteuning voor het exporteren van traceringsgegevens naar Jaeger en Zipkin.

DiagnosticSource kan traceringsevenementen in code gebruiken met behulp van DiagnosticListener. Zie de gebruikershandleiding voor DiagnosticSource voor informatie over het luisteren naar een diagnostische bron met code.

Note

Telemetriebibliotheken leggen momenteel geen specifieke gRPC-telemetrie Grpc.Net.Client.GrpcOut vast. Er wordt gewerkt aan het verbeteren van telemetriebibliotheken die deze tracering vastleggen.

Metrics

Metrische gegevens zijn een weergave van gegevensmetingen met intervallen van tijd, bijvoorbeeld aanvragen per seconde. Metrische gegevens maken observatie van de status van een app op hoog niveau mogelijk. Metrische .NET gRPC-gegevens worden verzonden met behulp van EventCounter.

Metrische gegevens van gRPC-service

gRPC-serverstatistieken worden gerapporteerd op de Grpc.AspNetCore.Server gebeurtenisbron.

Name	Description
total-calls	Totaal aantal oproepen
current-calls	Huidige oproepen
calls-failed	Totaal aantal mislukte aanroepen
calls-deadline-exceeded	Deadline voor totale oproepen overschreden
messages-sent	Totaal aantal verzonden berichten
messages-received	Totaal aantal ontvangen berichten
calls-unimplemented	Totaal aantal niet-geïmplementeerde aanroepen

ASP.NET Core biedt ook zijn eigen metrische gegevens over Microsoft.AspNetCore.Hosting de gebeurtenisbron.

metrische gegevens van gRPC-client

gRPC-clientmetriek wordt gerapporteerd bij de gebeurtenisbron Grpc.Net.Client.

Name	Description
total-calls	Totaal aantal oproepen
current-calls	Huidige oproepen
calls-failed	Totaal aantal mislukte aanroepen
calls-deadline-exceeded	Deadline voor totale oproepen overschreden
messages-sent	Totaal aantal verzonden berichten
messages-received	Totaal aantal ontvangen berichten

Metrische gegevens observeren

dotnet-counters is een hulpprogramma voor prestatiebewaking voor ad-hocstatusbewaking en prestatieonderzoek op het eerste niveau. Bewaak een .NET-app met als providernaam of Grpc.AspNetCore.Server of Grpc.Net.Client.

> dotnet-counters monitor --process-id 1902 --counters 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

Een andere manier om gRPC-metrische gegevens te observeren, is het vastleggen van tellergegevens met behulp van het Microsoft.ApplicationInsights.EventCounterCollector-pakket van Application Insights. Na het instellen verzamelt Application Insights algemene .NET-tellers tijdens de uitvoering. De tellers van gRPC worden niet standaard verzameld, maar App Insights kan worden aangepast om extra tellers op te nemen.

Geef de gRPC-tellers op voor Application Insight die moeten worden verzameld 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"));
            }
        );
    }

Aanvullende bronnen

• Aanmelden bij .NET en ASP.NET Core
• gRPC voor .NET-configuratie
• gRPC-klantfabriekintegratie in .NET