Loggning och diagnostik i gRPC på .NET

Av James Newton-King

Den här artikeln innehåller vägledning för att samla in diagnostik från en gRPC-app för att felsöka problem. Ämnen som tas upp är:

• Loggning – Strukturerade loggar skrivna till .NET-loggning. ILogger används av appramverk för att skriva loggar och av användare för sin egen loggning i en app.
• Spårning – Händelser relaterade till en åtgärd som skrivits med DiaganosticSource och Activity. Spårningar från diagnostikkällan används ofta för att samla in apptelemetri av bibliotek som Application Insights och OpenTelemetry.
• Mått – Representation av datamått över tidsintervall, till exempel begäranden per sekund. Mått genereras med hjälp av EventCounter och kan observeras med hjälp av kommandoradsverktyget dotnet-counters eller med Application Insights.

Logging

gRPC-tjänster och gRPC-klienten skriver loggar med .NET-loggning. Loggar är ett bra ställe att börja med när du felsöker oväntat beteende i tjänst- och klientappar.

gRPC-tjänstloggning

Warning

Loggar på serversidan kan innehålla känslig information från din app. Publicera aldrig råloggar från produktionsappar på forum som GitHub.

Eftersom gRPC-tjänster finns på ASP.NET Core används ASP.NET Core-loggningssystemet. I standardkonfigurationen loggar gRPC minimal information, men loggning kan konfigureras. Mer information om hur du konfigurerar ASP.NET Core-loggning finns i dokumentationen om ASP.NET Core-loggning .

gRPC lägger till loggar under Grpc kategorin. Om du vill aktivera detaljerade loggar för gRPC, konfigurerar du prefixen Grpc till Debug-nivån i appsettings.json-filen genom att lägga till följande objekt i LogLevel-underavsnittet i Logging:

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

Loggning kan också konfigureras i Program.cs med ConfigureLogging:

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

När du inte använder JSON-baserad konfiguration anger du följande konfigurationsvärde i konfigurationssystemet:

• Logging:LogLevel:Grpc = Debug

Kontrollera dokumentationen för konfigurationssystemet för att avgöra hur du anger kapslade konfigurationsvärden. När du till exempel använder miljövariabler används två _ tecken i stället för : (till exempel Logging__LogLevel__Grpc).

Vi rekommenderar att du använder Debug nivån när du samlar in detaljerad diagnostik för en app. Nivån Trace genererar diagnostik på låg nivå och behövs sällan för att diagnostisera problem.

Exempelloggningsresultat

Här är ett exempel på konsolutdata på Debug nivån för en gRPC-tjänst:

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

Komma åt loggar på serversidan

Hur loggar på serversidan används beror på appens miljö.

Som en konsolapplikation

Om du kör i en konsolapp bör konsolloggaren vara aktiverad som standard. gRPC-loggar visas i konsolen.

Andra miljöer

Om appen distribueras till en annan miljö (till exempel Docker, Kubernetes eller Windows Service) kan du läsa Loggning i .NET och ASP.NET Core för mer information om hur du konfigurerar loggningsproviders som är lämpliga för miljön.

gRPC-klientloggning

Warning

Loggar på klientsidan kan innehålla känslig information från din app. Publicera aldrig råloggar från produktionsappar på forum som GitHub.

Om du vill hämta loggar från .NET-klienten anger du GrpcChannelOptions.LoggerFactory egenskapen när klientens kanal skapas. När du anropar en gRPC-tjänst från en ASP.NET Core-app kan loggfabriken lösas med beroendeinjektion (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);
    }
}

Ett annat sätt att aktivera klientloggning är att använda gRPC-klientfabriken för att skapa klienten. En gRPC-klient som är registrerad hos klientfabriken och hämtas från DI använder automatiskt appens konfigurerade loggning.

Om appen inte använder DI skapar du en ny ILoggerFactory instans med LoggerFactory.Create. Om du vill komma åt den här metoden lägger du till Microsoft.Extensions.Logging-paketet i din 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-klientloggomfattningar

GRPC-klienten lägger till ett loggningsomfång i loggar som görs under ett gRPC-anrop. Omfånget har metadata relaterade till gRPC-anropet:

• GrpcMethodType – gRPC-metodtypen. Möjliga värden är namnen i Grpc.Core.MethodType-uppräkningen. Till exempel Unary.
• GrpcUri – den relativa URI:n för gRPC-metoden. Till exempel /greet. Greeter/SayHellos.

Exempelloggningsresultat

Här är ett exempel på konsolutdata på Debug nivån för en gRPC-klient:

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-tjänster och gRPC-klienten ger information om gRPC-anrop med hjälp av DiagnosticSource och Activity.

• .NET gRPC använder en aktivitet för att representera ett gRPC-anrop.
• Spårningshändelser skrivs till diagnostikkällan när gRPC-anropet börjar och slutar.
• Spårning samlar inte in information om när meddelanden skickas under livslängden för gRPC-strömningsanrop.

gRPC-tjänstspårning

gRPC-tjänster finns på ASP.NET Core, som rapporterar händelser om inkommande HTTP-begäranden. gRPC-specifika metadata läggs till i den befintliga HTTP-begärandediagnostiken som ASP.NET Core tillhandahåller.

• Diagnostikkällans namn är Microsoft.AspNetCore.
• Aktivitetsnamnet är Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Namnet på den gRPC-metod som anropas av gRPC-anropet läggs till som en tagg med namnet grpc.method.
  • Statuskoden för gRPC-anropet när det är klart läggs till som en tagg med namnet grpc.status_code.

gRPC-klientspårning

.NET gRPC-klienten använder HttpClient för att göra gRPC-anrop. Även om HttpClient skriver diagnostikhändelser, tillhandahåller .NET gRPC-klienten en anpassad källa, aktivitet och händelser för diagnostik så att fullständig information om ett gRPC-anrop kan samlas in.

• Diagnostikkällans namn är Grpc.Net.Client.
• Aktivitetsnamnet är Grpc.Net.Client.GrpcOut.
  • Namnet på den gRPC-metod som anropas av gRPC-anropet läggs till som en tagg med namnet grpc.method.
  • Statuskoden för gRPC-anropet när det är klart läggs till som en tagg med namnet grpc.status_code.

Samla in loggspårningar

Det enklaste sättet att använda DiagnosticSource är att konfigurera ett telemetribibliotek som Application Insights eller OpenTelemetry i din app. Biblioteket bearbetar information om gRPC-anrop tillsammans med annan apptelemetri.

Spårning kan visas i en hanterad tjänst som Application Insights eller köras som ett eget distribuerat spårningssystem. OpenTelemetry stöder export av spårningsdata till Jaeger och Zipkin.

DiagnosticSource kan konsumera spårningshändelser i kod med hjälp av DiagnosticListener. Information om hur du lyssnar på en diagnostikkälla med kod finns i användarhandboken för DiagnosticSource.

Note

Telemetribibliotek samlar för närvarande inte in gRPC-specifik Grpc.Net.Client.GrpcOut telemetri. Arbetet med att förbättra telemetribiblioteken som samlar in den här spårningen pågår.

Metrics

Mått är en representation av datamått över tidsintervall, till exempel begäranden per sekund. Måttdata gör det möjligt att övervaka tillståndet för en app på en hög nivå. .NET gRPC-metrik genereras med EventCounter.

gRPC-tjänstmått

gRPC-servermått rapporteras på Grpc.AspNetCore.Server händelsekällan.

Name	Description
total-calls	Totalt antal anrop
current-calls	Aktuella anrop
calls-failed	Totalt antal anrop misslyckades
calls-deadline-exceeded	Tidsgränsen för totalt antal samtal har överskridits
messages-sent	Totalt antal skickade meddelanden
messages-received	Totalt antal mottagna meddelanden
calls-unimplemented	Totalt antal anrop som inte har genomförts

ASP.NET Core tillhandahåller också egna mått för Microsoft.AspNetCore.Hosting händelsekällan.

gRPC-klientmetrik

gRPC-klientmått rapporteras på Grpc.Net.Client händelsekälla.

Name	Description
total-calls	Totalt antal anrop
current-calls	Aktuella anrop
calls-failed	Totalt antal anrop misslyckades
calls-deadline-exceeded	Tidsgränsen för totalt antal samtal har överskridits
messages-sent	Totalt antal skickade meddelanden
messages-received	Totalt antal mottagna meddelanden

Observera metrik

dotnet-counters är ett prestandaövervakningsverktyg för ad hoc-hälsoövervakning och prestandaundersökning på första nivån. Övervaka en .NET-app med antingen Grpc.AspNetCore.Server eller Grpc.Net.Client som providernamn.

> 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

Ett annat sätt att observera gRPC-mått är att samla in räknardata med Application Insights Microsoft.ApplicationInsights.EventCounterCollector-paket. När installationen har konfigurerats samlar Application Insights in vanliga .NET-räknare vid körning. gRPC:s räknare samlas inte in som standard, men App Insights kan anpassas för att inkludera ytterligare räknare.

Ange de gRPC-räknare som Application Insight ska samla in i 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"));
            }
        );
    }

Ytterligare resurser

• Loggning i .NET och ASP.NET Core
• gRPC för .NET-konfiguration
• Integrering av gRPC-klientfabrik i .NET