Rejestrowanie i diagnostyka w usłudze gRPC na platformie .NET

Autor: James Newton-King

Ten artykuł zawiera wskazówki dotyczące zbierania danych diagnostycznych z aplikacji gRPC, które ułatwiają rozwiązywanie problemów. Omawiane tematy to m.in.:

• Rejestrowanie — dzienniki ustrukturyzowane zapisywane w rejestrowaniu platformy .NET Core. ILogger jest używany przez struktury aplikacji do pisania dzienników i przez użytkowników na potrzeby własnego logowania w aplikacji.
• Śledzenie — zdarzenia związane z operacją zapisaną przy użyciu poleceń DiaganosticSource i Activity. Ślady ze źródła diagnostycznego są często używane do zbierania danych telemetrycznych aplikacji przez biblioteki, takie jak Application Insights i OpenTelemetry.
• Metryki — reprezentacja miar danych w odstępach czasu, na przykład żądania na sekundę. Metryki są emitowane przy użyciu EventCounter narzędzia wiersza polecenia dotnet-counters i można je zaobserwować za pomocą narzędzia wiersza polecenia dotnet-counters lub usługi Application Insights.

Rejestrowanie

Usługi gRPC i dzienniki zapisu klienta gRPC przy użyciu rejestrowania platformy .NET Core. Dzienniki są dobrym miejscem do rozpoczęcia debugowania nieoczekiwanego zachowania w usługach i aplikacjach klienckich.

Rejestrowanie usług gRPC

Ostrzeżenie

Dzienniki po stronie serwera mogą zawierać poufne informacje z aplikacji. Nigdy nie publikuj nieprzetworzonych dzienników z aplikacji produkcyjnych na forach publicznych, takich jak GitHub.

Ponieważ usługi gRPC są hostowane w ASP.NET Core, korzysta z systemu rejestrowania ASP.NET Core. W konfiguracji domyślnej gRPC rejestruje minimalne informacje, ale można skonfigurować rejestrowanie. Zapoznaj się z dokumentacją dotyczącą rejestrowania ASP.NET Core, aby uzyskać szczegółowe informacje na temat konfigurowania rejestrowania ASP.NET Core.

GRPC dodaje dzienniki w Grpc kategorii. Aby włączyć szczegółowe dzienniki z gRPC, skonfiguruj Grpc prefiksy na Debug poziomie w appsettings.json pliku, dodając następujące elementy do podsekcji w pliku LogLevel :Logging

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

Rejestrowanie można również skonfigurować za Program.cs pomocą polecenia ConfigureLogging:

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

Jeśli nie używasz konfiguracji opartej na formacie JSON, ustaw następującą wartość konfiguracji w systemie konfiguracji:

• Logging:LogLevel:Grpc = Debug

Zapoznaj się z dokumentacją systemu konfiguracji, aby określić sposób określania wartości konfiguracji zagnieżdżonych. Na przykład w przypadku używania zmiennych środowiskowych używane są dwa _ znaki zamiast : (na przykład Logging__LogLevel__Grpc).

Zalecamy użycie Debug poziomu podczas zbierania szczegółowej diagnostyki dla aplikacji. Poziom Trace generuje diagnostykę niskiego poziomu i rzadko jest potrzebny do diagnozowania problemów.

Przykładowe dane wyjściowe rejestrowania

Oto przykład danych wyjściowych konsoli na Debug poziomie usługi 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

Uzyskiwanie dostępu do dzienników po stronie serwera

Sposób uzyskiwania dostępu do dzienników po stronie serwera zależy od środowiska aplikacji.

Jako aplikacja konsolowa

Jeśli korzystasz z aplikacji konsolowej, rejestrator konsoli powinien być domyślnie włączony. Dzienniki gRPC będą wyświetlane w konsoli programu .

Inne środowiska

Jeśli aplikacja jest wdrażana w innym środowisku (na przykład Docker, Kubernetes lub Windows Service), zobacz Rejestrowanie na platformie .NET Core i ASP.NET Core , aby uzyskać więcej informacji na temat konfigurowania dostawców rejestrowania odpowiednich dla środowiska.

Rejestrowanie klienta gRPC

Ostrzeżenie

Dzienniki po stronie klienta mogą zawierać poufne informacje z aplikacji. Nigdy nie publikuj nieprzetworzonych dzienników z aplikacji produkcyjnych na forach publicznych, takich jak GitHub.

Aby pobrać dzienniki z klienta platformy .NET, ustaw GrpcChannelOptions.LoggerFactory właściwość po utworzeniu kanału klienta. Podczas wywoływania usługi gRPC z aplikacji ASP.NET Core można rozpoznać fabrykę rejestratora z iniekcji zależności (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);
    }
}

Alternatywnym sposobem włączenia rejestrowania klienta jest użycie fabryki klienta gRPC do utworzenia klienta. Klient gRPC zarejestrowany w fabryce klienta i rozpoznany z di automatycznie użyje skonfigurowanego rejestrowania aplikacji.

Jeśli aplikacja nie korzysta z di, utwórz nowe ILoggerFactory wystąpienie za pomocą polecenia LoggerFactory.Create. Aby uzyskać dostęp do tej metody, dodaj pakiet Microsoft.Extensions.Logging do aplikacji.

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

Zakresy dziennika klienta gRPC

Klient gRPC dodaje zakres rejestrowania do dzienników wykonanych podczas wywołania gRPC. Zakres zawiera metadane związane z wywołaniem gRPC:

• GrpcMethodType — typ metody gRPC. Możliwe wartości to nazwy z Grpc.Core.MethodType wyliczenia. Na przykład Unary.
• GrpcUri — względny identyfikator URI metody gRPC. Na przykład /greet. Witaj/SayHellos.

Przykładowe dane wyjściowe rejestrowania

Oto przykład danych wyjściowych konsoli na Debug poziomie klienta 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.

Śledzenie

Usługi gRPC i klient gRPC udostępniają informacje o wywołaniach gRPC przy użyciu i DiagnosticSource Activity.

• GRPC platformy .NET używa działania do reprezentowania wywołania gRPC.
• Zdarzenia śledzenia są zapisywane w źródle diagnostycznym na początku i zatrzymaniu działania wywołania gRPC.
• Śledzenie nie przechwytuje informacji o tym, kiedy komunikaty są wysyłane w okresie istnienia wywołań przesyłania strumieniowego gRPC.

Śledzenie usługi gRPC

Usługi gRPC są hostowane w usłudze ASP.NET Core, które zgłaszają zdarzenia dotyczące przychodzących żądań HTTP. Metadane specyficzne dla protokołu gRPC są dodawane do istniejącej diagnostyki żądań HTTP, która zapewnia ASP.NET Core.

• Nazwa źródła diagnostycznego to Microsoft.AspNetCore.
• Nazwa działania to Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Nazwa metody gRPC wywoływanej przez wywołanie gRPC jest dodawana jako tag o nazwie grpc.method.
  • Kod stanu wywołania gRPC po jego zakończeniu jest dodawany jako tag o nazwie grpc.status_code.

Śledzenie klienta gRPC

Klient gRPC platformy .NET używa HttpClient do tworzenia wywołań gRPC. Mimo że HttpClient zapisuje zdarzenia diagnostyczne, klient gRPC platformy .NET udostępnia niestandardowe źródło diagnostyczne, działanie i zdarzenia, dzięki czemu można zebrać pełne informacje o wywołaniu gRPC.

• Nazwa źródła diagnostycznego to Grpc.Net.Client.
• Nazwa działania to Grpc.Net.Client.GrpcOut.
  • Nazwa metody gRPC wywoływanej przez wywołanie gRPC jest dodawana jako tag o nazwie grpc.method.
  • Kod stanu wywołania gRPC po jego zakończeniu jest dodawany jako tag o nazwie grpc.status_code.

Zbieranie śledzenia

Najprostszym sposobem użycia DiagnosticSource jest skonfigurowanie biblioteki telemetrii, takiej jak Application Insights lub OpenTelemetry w aplikacji. Biblioteka będzie przetwarzać informacje o wywołaniach gRPC obok innych danych telemetrycznych aplikacji.

Śledzenie można wyświetlać w usłudze zarządzanej, takiej jak Application Insights, lub uruchamiać jako własny rozproszony system śledzenia. Funkcja OpenTelemetry obsługuje eksportowanie danych śledzenia do produktów Jaeger i Zipkin.

DiagnosticSource program może korzystać ze śledzenia zdarzeń w kodzie przy użyciu polecenia DiagnosticListener. Aby uzyskać informacje na temat nasłuchiwania źródła diagnostycznego za pomocą kodu, zobacz przewodnik użytkownika DiagnosticSource.

Uwaga

Biblioteki telemetryczne nie przechwytują obecnie telemetrii specyficznej dla Grpc.Net.Client.GrpcOut kontrolera gRPC. Trwa ulepszanie bibliotek telemetrii przechwytujących to śledzenie.

Metryki

Metryki to reprezentacja miar danych w odstępach czasu, na przykład żądania na sekundę. Dane metryk umożliwiają obserwację stanu aplikacji na wysokim poziomie. Metryki gRPC platformy .NET są emitowane przy użyciu polecenia EventCounter.

Metryki usługi gRPC

Metryki serwera gRPC są zgłaszane w Grpc.AspNetCore.Server źródle zdarzeń.

Nazwa/nazwisko	opis
total-calls	Łączna liczba rozmów telefonicznych
current-calls	Bieżące wywołania
calls-failed	Łączna liczba wywołań nie powiodła się
calls-deadline-exceeded	Przekroczono łączny termin ostatecznego wywołania
messages-sent	Łączna liczba wysłanych komunikatów
messages-received	Łączna liczba odebranych komunikatów
calls-unimplemented	Łączna liczba nieimplementowanych wywołań

ASP.NET Core udostępnia również własne metryki dotyczące Microsoft.AspNetCore.Hosting źródła zdarzeń.

Metryki klienta usługi gRPC

Metryki klienta gRPC są zgłaszane w Grpc.Net.Client źródle zdarzeń.

Nazwa/nazwisko	opis
total-calls	Łączna liczba rozmów telefonicznych
current-calls	Bieżące wywołania
calls-failed	Łączna liczba wywołań nie powiodła się
calls-deadline-exceeded	Przekroczono łączny termin ostatecznego wywołania
messages-sent	Łączna liczba wysłanych komunikatów
messages-received	Łączna liczba odebranych komunikatów

Obserwowanie metryk

dotnet-counters to narzędzie do monitorowania wydajności na potrzeby monitorowania kondycji ad hoc i badania wydajności pierwszego poziomu. Monitoruj aplikację platformy .NET przy użyciu nazwy Grpc.AspNetCore.Server dostawcy lub Grpc.Net.Client .

> 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

Innym sposobem obserwowania metryk gRPC jest przechwytywanie danych liczników przy użyciu pakietu Microsoft.ApplicationInsights.EventCounterCollector usługi Application Insights. Po skonfigurowaniu usługa Application Insights zbiera typowe liczniki platformy .NET w czasie wykonywania. Liczniki gRPC nie są domyślnie zbierane, ale można dostosować usługę App Insights w celu uwzględnienia dodatkowych liczników.

Określ liczniki gRPC dla usługi Application Insights, które mają być zbierane w programie 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"));
            }
        );
    }

Dodatkowe zasoby

• Rejestrowanie na platformie .NET Core i ASP.NET Core
• gRPC dla konfiguracji platformy .NET
• Integracja fabryki klienta gRPC na platformie .NET