Protokolování a diagnostika v gRPC v .NET

Autor: James Newton-King

Tento článek obsahuje pokyny ke shromažďování diagnostiky z aplikace gRPC, která vám pomůže s řešením problémů. Probíraná témata zahrnují:

• Protokolování – strukturované protokoly zapsané do protokolování .NET Core ILogger aplikace používají architektury aplikací k zápisu protokolů a uživatelům pro vlastní protokolování v aplikaci.
• Trasování – události související s operací zapsanou pomocí DiaganosticSource a Activity. Trasování ze zdroje diagnostiky se běžně používá ke shromažďování telemetrie aplikací podle knihoven, jako jsou Application Insights a OpenTelemetry.
• Metriky – znázornění datových měr v časových intervalech, například požadavků za sekundu Metriky se generují pomocí EventCounter nástroje příkazového řádku dotnet-counters nebo application Insights.

Protokolování

Služby gRPC a protokoly zápisu klienta gRPC pomocí protokolování .NET Core Protokoly jsou dobrým místem, kde začít při ladění neočekávaného chování ve službách a klientských aplikacích.

Protokolování služeb gRPC

Upozorňující

Protokoly na straně serveru můžou obsahovat citlivé informace z vaší aplikace. Nikdy nezpracované protokoly z produkčních aplikací neposílejte na veřejná fóra, jako je GitHub.

Vzhledem k tomu, že služby gRPC jsou hostované v ASP.NET Core, používá systém protokolování ASP.NET Core. Ve výchozí konfiguraci protokoluje gRPC minimální informace, ale protokolování je možné nakonfigurovat. Podrobnosti o konfiguraci protokolování ASP.NET Core najdete v dokumentaci k protokolování ASP.NET Core.

gRPC přidá protokoly do Grpc kategorie. Pokud chcete povolit podrobné protokoly z gRPC, nakonfigurujte Grpc předpony na Debug úroveň souboru appsettings.json přidáním následujících položek do pododdílu v:LoggingLogLevel

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

Protokolování lze také nakonfigurovat Program.cs pomocí ConfigureLogging:

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

Pokud nepoužíváte konfiguraci založenou na formátu JSON, nastavte v konfiguračním systému následující hodnotu konfigurace:

• Logging:LogLevel:Grpc = Debug

Projděte si dokumentaci ke konfiguračnímu systému a zjistěte, jak zadat vnořené hodnoty konfigurace. Například při použití proměnných prostředí se místo znaku : (napříkladLogging__LogLevel__Grpc) použijí dva _ znaky.

Při shromažďování podrobných diagnostických údajů pro aplikaci doporučujeme použít Debug úroveň. Úroveň Trace vytváří diagnostiku nízké úrovně a je zřídka nutná k diagnostice problémů.

Ukázkový výstup protokolování

Tady je příklad výstupu konzoly na Debug úrovni služby 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

Přístup k protokolům na straně serveru

Způsob přístupu k protokolům na straně serveru závisí na prostředí aplikace.

Jako konzolová aplikace

Pokud používáte konzolovou aplikaci, protokolovací nástroj konzoly by měl být ve výchozím nastavení povolený. Protokoly gRPC se zobrazí v konzole.

Ostatní prostředí

Pokud je aplikace nasazená do jiného prostředí (například Docker, Kubernetes nebo Windows Service), přečtěte si další informace o konfiguraci zprostředkovatelů protokolování vhodných pro prostředí v .NET Core a ASP.NET Core .

Protokolování klienta gRPC

Upozorňující

Protokoly na straně klienta můžou obsahovat citlivé informace z vaší aplikace. Nikdy nezpracované protokoly z produkčních aplikací neposílejte na veřejná fóra, jako je GitHub.

Pokud chcete získat protokoly z klienta .NET, nastavte GrpcChannelOptions.LoggerFactory vlastnost při vytvoření kanálu klienta. Při volání služby gRPC z aplikace ASP.NET Core je možné přeložit objekt pro vytváření protokolovacích nástrojů z injektáže závislostí (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);
    }
}

Alternativním způsobem, jak povolit protokolování klienta, je použití objektu pro vytváření klienta gRPC k vytvoření klienta. Klient gRPC zaregistrovaný v objektu pro vytváření klienta a vyřešený z DI automaticky použije nakonfigurované protokolování aplikace.

Pokud aplikace nepoužívá DI, vytvořte novou ILoggerFactory instanci pomocí LoggerFactory.Createpříkazu . Pokud chcete získat přístup k této metodě, přidejte do aplikace balíček Microsoft.Extensions.Logging .

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

Obory protokolu klienta gRPC

Klient gRPC přidá rozsah protokolování do protokolů provedených během volání gRPC. Obor obsahuje metadata související s voláním gRPC:

• GrpcMethodType – typ metody gRPC. Možné hodnoty jsou názvy z Grpc.Core.MethodType výčtu. Například Unary.
• GrpcUri – relativní identifikátor URI metody gRPC. Například /greet. Greeter/SayHellos.

Ukázkový výstup protokolování

Tady je příklad výstupu konzoly na Debug úrovni 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.

Sledování

služby gRPC a klient gRPC poskytují informace o voláních gRPC pomocí DiagnosticSource a Activity.

• .NET gRPC používá aktivitu k reprezentaci volání gRPC.
• Události trasování se zapisují do diagnostického zdroje na začátku a zastavují aktivitu volání gRPC.
• Trasování nezachytává informace o tom, kdy se zprávy posílají v průběhu životnosti volání streamování gRPC.

Trasování služby gRPC

Služby gRPC jsou hostované na ASP.NET Core, které hlásí události o příchozích požadavcích HTTP. Do stávající diagnostiky požadavků HTTP, která ASP.NET Core poskytuje, se přidají metadata specifická pro gRPC.

• Název zdroje diagnostiky je Microsoft.AspNetCore.
• Název aktivity je Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Název metody gRPC vyvolané voláním gRPC se přidá jako značka s názvem grpc.method.
  • Stavový kód volání gRPC po dokončení je přidán jako značka s názvem grpc.status_code.

Trasování klienta gRPC

Klient .NET gRPC používá HttpClient k volání gRPC. I když HttpClient zapisuje diagnostické události, klient .NET gRPC poskytuje vlastní zdroj diagnostiky, aktivitu a události, aby bylo možné shromažďovat úplné informace o volání gRPC.

• Název zdroje diagnostiky je Grpc.Net.Client.
• Název aktivity je Grpc.Net.Client.GrpcOut.
  • Název metody gRPC vyvolané voláním gRPC se přidá jako značka s názvem grpc.method.
  • Stavový kód volání gRPC po dokončení je přidán jako značka s názvem grpc.status_code.

Shromažďování trasování

Nejjednodušší způsob, jak použít DiagnosticSource , je nakonfigurovat v aplikaci knihovnu telemetrie, jako je Application Insights nebo OpenTelemetry . Knihovna bude zpracovávat informace o voláních gRPC společně s další telemetrií aplikace.

Trasování můžete zobrazit ve spravované službě, jako je Application Insights, nebo spustit jako vlastní distribuovaný trasovací systém. OpenTelemetry podporuje export trasovacích dat do Jaegeru a Zipkinu.

DiagnosticSource může využívat trasovací události v kódu pomocí DiagnosticListener. Informace o naslouchání diagnostickému zdroji s kódem najdete v příručce uživatele DiagnosticSource.

Poznámka:

Knihovny telemetrie v současné době nezachycují telemetrická data specifická pro Grpc.Net.Client.GrpcOut gRPC. Práce na vylepšení knihoven telemetrie, které zachytávají toto trasování, probíhá.

Metriky

Metriky jsou reprezentací datových měr v intervalech času, například požadavků za sekundu. Data metrik umožňují sledovat stav aplikace na vysoké úrovni. Metriky .NET gRPC se generují pomocí EventCounter.

Metriky služby gRPC

Metriky serveru gRPC jsou hlášeny ve Grpc.AspNetCore.Server zdroji událostí.

Název	Popis
total-calls	Celkový počet hovorů
current-calls	Aktuální hovory
calls-failed	Celkový počet neúspěšných volání
calls-deadline-exceeded	Překročení konečného termínu volání celkem
messages-sent	Celkový počet odeslaných zpráv
messages-received	Celkový počet přijatých zpráv
calls-unimplemented	Total Calls Unimplemented

ASP.NET Core také poskytuje vlastní metriky ve Microsoft.AspNetCore.Hosting zdroji událostí.

Metriky klienta gRPC

Metriky klienta gRPC jsou hlášeny ve Grpc.Net.Client zdroji událostí.

Název	Popis
total-calls	Celkový počet hovorů
current-calls	Aktuální hovory
calls-failed	Celkový počet neúspěšných volání
calls-deadline-exceeded	Překročení konečného termínu volání celkem
messages-sent	Celkový počet odeslaných zpráv
messages-received	Celkový počet přijatých zpráv

Sledování metrik

dotnet-counters je nástroj pro monitorování výkonu pro monitorování stavu ad hoc a prošetření výkonu na první úrovni. Monitorujte aplikaci .NET s názvem poskytovatele Grpc.AspNetCore.Server nebo Grpc.Net.Client jako název poskytovatele.

> 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

Dalším způsobem, jak sledovat metriky gRPC, je zachytit data čítačů pomocí balíčku Microsoft.ApplicationInsights.EventCounterCollector služby Application Insights. Po nastavení application Insights shromažďuje běžné čítače .NET za běhu. Čítače gRPC se ve výchozím nastavení neshromažďují, ale App Insights je možné přizpůsobit tak, aby zahrnovaly další čítače.

Zadejte čítače gRPC pro Application Insight, které se mají shromažďovat v 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"));
            }
        );
    }

Další materiály

• Protokolování v .NET Core a ASP.NET Core
• gRPC pro konfiguraci .NET
• Integrace objektu pro vytváření klienta gRPC v .NET