Protokollierung und Diagnosen in gRPC für .NET

Von James Newton-King

In diesem Artikel erhalten Sie eine Anleitung, wie Sie Diagnosedaten aus einer gRPC-App erhalten, die Sie beim Troubleshooting von Problemen unterstützen. Folgende Themen werden behandelt:

• Protokollierung: Strukturierte Protokolle, die in die .NET Core-Protokollierung geschrieben werden. ILogger wird von App-Frameworks verwendet, um Protokolle zu schreiben, sowie von Benutzern für die eigene Protokollierung in einer App.
• Ablaufverfolgung: Ereignisse im Zusammenhang mit einem Vorgang werden mithilfe von DiaganosticSource und Activity geschrieben. Ablaufverfolgungen aus Diagnosequellen werden in der Regel dazu verwendet, um App-Telemetriedaten von Bibliotheken wie Application Insights und OpenTelemetry zu sammeln.
• Metriken: Hierbei handelt es sich um eine Darstellung von Datenmesswerten über bestimmte Zeiträume hinweg, beispielsweise für Anforderungen pro Sekunde. Metriken werden mithilfe von EventCounter ausgegeben und können mithilfe des dotnet-counters-Befehlszeilentools oder mit Application Insights überwacht werden.

Protokollierung

gRPC-Dienste und der gRPC-Client schreiben Protokolle mithilfe der .NET Core-Protokollierung. Protokolle sind ein guter Ausgangspunkt für das Debuggen von unerwartetem Verhalten in Dienst- und Client-Apps.

Protokollierung für gRPC-Dienste

Warnung

Serverseitige Protokolle enthalten möglicherweise vertrauliche Daten aus Ihrer App. Veröffentlichten Sie deshalb niemals Protokolle von Produktions-Apps auf öffentlichen Foren wie GitHub.

Da gRPC-Dienste bei ASP.NET Core gehostet werden, wird das ASP.NET Core-Protokollierungssystem verwendet. In der Standardkonfiguration protokolliert gRPC nur minimale Informationen, wobei die Protokollierung konfiguriert werden kann. In der Dokumentation zur ASP.NET Core-Protokollierung finden Sie weitere Informationen zum Konfigurieren der ASP.NET Core-Protokollierung.

gRPC fügt Protokolle unter der Grpc-Kategorie hinzu. Wenn Sie in gRPC detaillierte Protokolle aktivieren möchten, konfigurieren Sie die Grpc-Präfixe für die Debug-Ebene in der Datei appsettings.json , indem Sie die folgenden Elemente im LogLevel-Unterbereich in Logging hinzufügen:

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

Die Protokollierung kann auch in Program.cs mit ConfigureLogging konfiguriert werden:

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

Wenn keine JSON-basierte Konfiguration verwendet wird, legen Sie den folgenden Konfigurationswert in im Konfigurationssystem fest:

• Logging:LogLevel:Grpc = Debug

Suchen Sie in der Dokumentation nach Informationen zu Ihrem Konfigurationssystem, um zu bestimmen, wie geschachtelte Konfigurationswerte angegeben werden. Bei der Verwendung von Umgebungsvariablen werden beispielsweise zwei _-Zeichen anstelle von : verwendet (z. B. Logging__LogLevel__Grpc).

Es empfiehlt sich, die Debug-Ebene zu verwenden, wenn detaillierte Diagnosedaten für eine App gesammelt werden sollen. Die Trace-Ebene bietet nur wenige Diagnoseinformationen und wird nur selten verwendet, um Probleme zu identifizieren.

Beispiel einer Protokollierungsausgabe

Hier finden Sie ein Beispiel einer Konsolenausgabe auf der Debug-Ebene eines gRPC-Diensts:

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

Zugreifen auf serverseitige Protokolle

Wie auf serverseitige Protokolle zugegriffen wird, hängt von der Umgebung der App ab.

Ausführung als Konsolen-App

Wenn die Ausführung in einer Konsolen-App stattfindet, sollte die Konsolenprotokollierung standardmäßig aktiviert sein. gRPC-Protokolle werden in der Konsole angezeigt.

Andere Umgebungen

Wenn die App in einer anderen Umgebung bereitgestellt wird (z. B. Docker, Kubernetes oder Windows-Dienst) finden Sie unter Protokollieren in .NET Core und ASP.NET Core weitere Informationen zum Konfigurieren von Protokollierungsanbietern, die für die Umgebung geeignet sind.

gRPC-Clientprotokollierung

Warnung

Clientseitige Protokolle enthalten möglicherweise vertrauliche Daten aus Ihrer App. Veröffentlichten Sie deshalb niemals Protokolle von Produktions-Apps auf öffentlichen Foren wie GitHub.

Wenn Sie Protokolle vom .NET-Client erhalten möchten, legen Sie die GrpcChannelOptions.LoggerFactory-Eigenschaft fest, wenn der Kanal des Clients erstellt wird. Wenn Sie einen gRPC-Dienst in einer ASP.NET Core-App aufrufen, kann die Protokollierungsfactory aus einer Abhängigkeitsinjektion (Dependency Injection, DI) aufgelöst werden:

[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);
    }
}

Eine alternative Möglichkeit, die Clientprotokollierung zu aktivieren, ist die Verwendung der gRPC-Clientfactory, um den Client zu erstellen. Ein für die Clientfactory registrierter und aus der DI aufgelöster gRPC-Client verwendet automatisch die für die App konfigurierte Protokollierung.

Wenn Ihre App nicht DI verwendet, erstellen Sie mit LoggerFactory.Create eine neue ILoggerFactory-Instanz. Fügen Sie Ihrer App das Paket Microsoft.Extensions.Logging hinzu, um auf diese Methode zuzugreifen.

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);

Protokollbereiche des gRPC-Clients

Der gRPC-Client fügt Protokollen, die während eines gRPC-Aufrufs erstellt werden, einen Protokollierungsbereich hinzu. Der Bereich verfügt über mit dem gRPC-Aufruf verbundene Metadaten:

• GrpcMethodType: Der gRPC-Methodentyp. Mögliche Werte sind Namen der Grpc.Core.MethodType-Enumeration. Beispiel: Unary.
• GrpcUri: Der relative URI der gRPC-Methode Beispiel: /greet. Greeter/SayHellos

Beispiel einer Protokollierungsausgabe

Hier finden Sie ein Beispiel einer Konsolenausgabe auf der Debug-Ebene eines gRPC-Clients:

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.

Ablaufverfolgung

gRPC-Dienste und der gRPC-Client stellen Informationen zu gRPC-Aufrufen mithilfe von DiagnosticSource und Activity zur Verfügung.

• .NET gRPC verwendet eine Activity-Klasse, um einen gRPC-Aufruf darzustellen.
• Ablaufverfolgungsereignisse werden bei Beginn und Ende der gRPC-Aufrufsaktivität in die Diagnosequelle geschrieben.
• Bei der Ablaufverfolgung werden keine Informationen dazu gesammelt, wann Nachrichten während der Lebensdauer eines gRPC-Streamingaufrufs gesendet werden.

gRPC-Dienstablaufsverfolgung

gRPC-Dienste werden bei ASP.NET Core gehostet, wo Ereignisse zu eingehenden HTTP-Anforderungen gemeldet werden. Für gRPC spezifische Metadaten werden den bestehenden HTTP-Anforderungsdiagnosedaten hinzugefügt, die von ASP.NET Core bereitgestellt werden.

• Der Name der Diagnosequelle ist Microsoft.AspNetCore.
• Der Name der Aktivität ist Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Der Name der gRPC-Methode, die vom gRPC-Aufruf aufgerufen wird, wird als Tag mit dem Namen grpc.method hinzugefügt.
  • Der Statuscode des gRPC-Aufrufs wird bei Abschluss als Tag mit dem Namen grpc.status_code hinzugefügt.

gPRC-Clientablaufverfolgung

Der .NET-gRPC-Client verwendet HttpClient, um gRPC-Aufrufe durchzuführen. Obwohl HttpClient Diagnoseereignisse schreibt, stellt der .NET-gRPC-Client eine benutzerdefinierte Diagnosequelle, eine Aktivität und Ereignisse zur Verfügung, sodass alle erforderlichen Informationen zu einem gRPC-Aufruf gesammelt werden können.

• Der Name der Diagnosequelle ist Grpc.Net.Client.
• Der Name der Aktivität ist Grpc.Net.Client.GrpcOut.
  • Der Name der gRPC-Methode, die vom gRPC-Aufruf aufgerufen wird, wird als Tag mit dem Namen grpc.method hinzugefügt.
  • Der Statuscode des gRPC-Aufrufs wird bei Abschluss als Tag mit dem Namen grpc.status_code hinzugefügt.

Sammeln von Ablaufverfolgungsdaten

Die einfachste Möglichkeit, DiagnosticSource zu verwenden, ist die Konfiguration einer Telemetriebibliothek wie Application Insights oder OpenTelemetry in Ihrer App. Die Bibliothek verarbeitet Informationen zu gRPC-Aufrufen zusammen mit weiteren App-Telemetriedaten.

Die Ablaufverfolgung kann in einem verwalteten Dienst wie Application Insights eingesehen werden. Alternativ können Sie Ihr eigenes verteiltes Ablaufverfolgungssystem ausführen. OpenTelemetry unterstützt das Exportieren von Ablaufverfolgungsdaten zu Jaeger und Zipkin.

DiagnosticSource kann Ablaufverfolgungsereignisse im Code mithilfe von DiagnosticListener verarbeiten. Weitere Informationen zum Lauschen auf einer Diagnosequelle mit Code finden Sie unter Verarbeiten von Daten mithilfe von DiagnosticListener.

Hinweis

Telemetriebibliotheken erfassen aktuell keine gRPC-spezifischen Grpc.Net.Client.GrpcOut-Telemetriedaten. Aktuell wird aber daran gearbeitet, die Telemetriebibliotheken zu optimieren, sodass diese Ablaufverfolgung erfasst wird.

Metriken

Bei Metriken handelt es sich um eine Darstellung von Datenmesswerten über bestimmte Zeiträume hinweg, beispielsweise für Anforderungen pro Sekunde. Metrikdaten ermöglichen die Überwachung des Zustands einer App auf einer hohen Ebene. .NET-gRPC-Metriken werden mithilfe von EventCounter ausgegeben.

gRPC-Dienstmetriken

gRPC-Servermetriken werden in der Grpc.AspNetCore.Server-Ereignisquelle gemeldet.

name	Beschreibung
total-calls	Aufrufe gesamt
current-calls	Aktuelle Aufrufe
calls-failed	Insgesamt fehlgeschlagene Aufrufe
calls-deadline-exceeded	Anzahl an Aufrufen, die eine Frist überschritten haben
messages-sent	Gesamtzahl der gesendeten Nachrichten
messages-received	Insgesamt empfangene Nachrichten
calls-unimplemented	Insgesamt nicht implementierte Aufrufe

In ASP.NET Core stehen auch eigene Metriken für die Microsoft.AspNetCore.Hosting-Ereignisquelle zur Verfügung.

gRPC-Clientmetriken

gRPC-Clientmetriken werden in der Grpc.Net.Client-Ereignisquelle gemeldet.

name	Beschreibung
total-calls	Aufrufe gesamt
current-calls	Aktuelle Aufrufe
calls-failed	Insgesamt fehlgeschlagene Aufrufe
calls-deadline-exceeded	Anzahl an Aufrufen, die eine Frist überschritten haben
messages-sent	Gesamtzahl der gesendeten Nachrichten
messages-received	Insgesamt empfangene Nachrichten

Überwachen von Metriken

dotnet-counters ist ein Leistungsüberwachungstool zur Ad-hoc-Überwachung der Integrität und zur Leistungsuntersuchung auf erster Ebene. Sie können eine .NET-App entweder mit Grpc.AspNetCore.Server oder Grpc.Net.Client als Anbietername überwachen.

> 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

Eine andere Möglichkeit, gRPC-Metriken zu überwachen, ist es, Indikatoren mithilfe des Microsoft.ApplicationInsights.EventCounterCollector-Pakets von Application Insights zu sammeln. Sobald Application Insights eingerichtet ist, werden allgemeine .NET-Indikatoren zur Laufzeit gesammelt. Indikatoren von gRPC werden nicht standardmäßig gesammelt, aber Application Insights kann so angepasst werden, dass zusätzliche Indikatoren eingeschlossen werden.

Geben Sie die gRPC-Indikatoren, die gesammelt werden sollen, für Application Insights 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"));
            }
        );
    }

Zusätzliche Ressourcen

• Protokollierung in .NET Core und ASP.NET Core
• gRPC für .NET-Konfiguration
• gRPC-Clientfactoryintegration in .NET