Pengelogan dan diagnostik di gRPC pada .NET

Oleh James Newton-King

Artikel ini menyediakan panduan untuk mengumpulkan diagnostik dari aplikasi gRPC untuk membantu memecahkan masalah. Topik yang dibahas meliputi:

• Pengelogan - Log terstruktur yang ditulis ke pengelogan .NET Core. ILogger digunakan oleh kerangka kerja aplikasi untuk menulis log, dan oleh pengguna untuk pengelogan mereka sendiri di aplikasi.
• Pelacakan - Peristiwa yang terkait dengan operasi yang ditulis menggunakan DiaganosticSource dan Activity. Jejak dari sumber diagnostik umumnya digunakan untuk mengumpulkan telemetri aplikasi oleh pustaka seperti Application Insights dan OpenTelemetry.
• Metrik - Representasi pengukuran data selama interval waktu, misalnya, permintaan per detik. Metrik dipancarkan menggunakan EventCounter dan dapat diamati menggunakan alat baris perintah penghitung dotnet atau dengan Application Insights.

Pencatatan

Layanan gRPC dan log tulis klien gRPC menggunakan pengelogan .NET Core. Log adalah tempat yang baik untuk memulai saat men-debug perilaku tak terduga di aplikasi layanan dan klien.

Pengelogan layanan gRPC

Peringatan

Log sisi server mungkin berisi informasi sensitif dari aplikasi Anda. Jangan pernah memposting log mentah dari aplikasi produksi ke forum publik seperti GitHub.

Karena layanan gRPC dihosting di ASP.NET Core, layanan ini menggunakan sistem pengelogan ASP.NET Core. Dalam konfigurasi default, gRPC mencatat informasi minimal, tetapi pengelogan dapat dikonfigurasi. Lihat dokumentasi tentang pengelogan ASP.NET Core untuk detail tentang mengonfigurasi pengelogan ASP.NET Core.

gRPC menambahkan log di Grpc bawah kategori . Untuk mengaktifkan log terperinci dari gRPC, konfigurasikan Grpc awalan ke Debug tingkat dalam appsettings.json file dengan menambahkan item berikut ke LogLevel subbagian di Logging:

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

Pengelogan juga dapat dikonfigurasi dengan Program.cs ConfigureLogging:

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

Saat tidak menggunakan konfigurasi berbasis JSON, atur nilai konfigurasi berikut dalam sistem konfigurasi:

• Logging:LogLevel:Grpc = Debug

Periksa dokumentasi untuk sistem konfigurasi Anda untuk menentukan cara menentukan nilai konfigurasi berlapis. Misalnya, saat menggunakan variabel lingkungan, dua _ karakter digunakan alih-alih : (misalnya, Logging__LogLevel__Grpc).

Sebaiknya gunakan Debug tingkat saat mengumpulkan diagnostik terperinci untuk aplikasi. Tingkat ini Trace menghasilkan diagnostik tingkat rendah dan jarang diperlukan untuk mendiagnosis masalah.

Contoh output pengelogan

Berikut adalah contoh output konsol pada Debug tingkat layanan 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

Mengakses log sisi server

Bagaimana log sisi server diakses tergantung pada lingkungan aplikasi.

Sebagai aplikasi konsol

Jika Anda berjalan di aplikasi konsol, pencatat Konsol harus diaktifkan secara default. Log gRPC akan muncul di konsol.

Lingkungan lainnya

Jika aplikasi disebarkan ke lingkungan lain (misalnya, Docker, Kubernetes, atau Windows Service), lihat Pengelogan di .NET Core dan ASP.NET Core untuk informasi selengkapnya tentang cara mengonfigurasi penyedia pengelogan yang cocok untuk lingkungan.

pengelogan klien gRPC

Peringatan

Log sisi klien mungkin berisi informasi sensitif dari aplikasi Anda. Jangan pernah memposting log mentah dari aplikasi produksi ke forum publik seperti GitHub.

Untuk mendapatkan log dari klien .NET, atur GrpcChannelOptions.LoggerFactory properti saat saluran klien dibuat. Saat memanggil layanan gRPC dari aplikasi ASP.NET Core, pabrik pencatat dapat diselesaikan dari injeksi dependensi (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);
    }
}

Cara alternatif untuk mengaktifkan pengelogan klien adalah dengan menggunakan pabrik klien gRPC untuk membuat klien. Klien gRPC yang terdaftar di pabrik klien dan diselesaikan dari DI akan secara otomatis menggunakan pengelogan aplikasi yang dikonfigurasi.

Jika aplikasi tidak menggunakan DI, buat instans baru ILoggerFactory dengan LoggerFactory.Create. Untuk mengakses metode ini, tambahkan paket Microsoft.Extensions.Logging ke aplikasi Anda.

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

Cakupan log klien gRPC

Klien gRPC menambahkan cakupan pengelogan ke log yang dilakukan selama panggilan gRPC. Cakupan memiliki metadata yang terkait dengan panggilan gRPC:

• GrpcMethodType - Jenis metode gRPC. Nilai yang mungkin adalah nama dari Grpc.Core.MethodType enum. Contohnya,Unary.
• GrpcUri - URI relatif dari metode gRPC. Misalnya, /greet. Greeter/SayHellos.

Contoh output pengelogan

Berikut adalah contoh output konsol pada Debug tingkat klien 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.

Menelusuri

Layanan gRPC dan klien gRPC memberikan informasi tentang panggilan gRPC menggunakan DiagnosticSource dan Activity.

• .NET gRPC menggunakan aktivitas untuk mewakili panggilan gRPC.
• Peristiwa pelacakan ditulis ke sumber diagnostik di awal dan berhentinya aktivitas panggilan gRPC.
• Pelacakan tidak menangkap informasi tentang kapan pesan dikirim selama masa pakai panggilan streaming gRPC.

Pelacakan layanan gRPC

Layanan gRPC dihosting di ASP.NET Core, yang melaporkan peristiwa tentang permintaan HTTP masuk. Metadata spesifik gRPC ditambahkan ke diagnostik permintaan HTTP yang ada yang disediakan ASP.NET Core.

• Nama sumber diagnostik adalah Microsoft.AspNetCore.
• Nama aktivitas adalah Microsoft.AspNetCore.Hosting.HttpRequestIn.
  • Nama metode gRPC yang dipanggil oleh panggilan gRPC ditambahkan sebagai tag dengan nama grpc.method.
  • Kode status panggilan gRPC ketika selesai ditambahkan sebagai tag dengan nama grpc.status_code.

Pelacakan klien gRPC

Klien .NET gRPC menggunakan HttpClient untuk melakukan panggilan gRPC. Meskipun HttpClient menulis peristiwa diagnostik, klien .NET gRPC menyediakan sumber, aktivitas, dan peristiwa diagnostik kustom sehingga informasi lengkap tentang panggilan gRPC dapat dikumpulkan.

• Nama sumber diagnostik adalah Grpc.Net.Client.
• Nama aktivitas adalah Grpc.Net.Client.GrpcOut.
  • Nama metode gRPC yang dipanggil oleh panggilan gRPC ditambahkan sebagai tag dengan nama grpc.method.
  • Kode status panggilan gRPC ketika selesai ditambahkan sebagai tag dengan nama grpc.status_code.

Mengumpulkan pelacakan

Cara term mudah untuk digunakan DiagnosticSource adalah dengan mengonfigurasi pustaka telemetri seperti Application Insights atau OpenTelemetry di aplikasi Anda. Pustaka akan memproses informasi tentang panggilan gRPC bersama telemetri aplikasi lain.

Pelacakan dapat dilihat dalam layanan terkelola seperti Application Insights, atau dijalankan sebagai sistem pelacakan terdistribusi Anda sendiri. OpenTelemetry mendukung ekspor data pelacakan ke Jaeger dan Zipkin.

DiagnosticSource dapat menggunakan peristiwa pelacakan dalam kode menggunakan DiagnosticListener. Untuk informasi tentang mendengarkan sumber diagnostik dengan kode, lihat panduan pengguna DiagnosticSource.

Catatan

Pustaka telemetri saat ini tidak menangkap telemetri spesifik Grpc.Net.Client.GrpcOut gRPC. Bekerja untuk meningkatkan pustaka telemetri yang menangkap pelacakan ini sedang berlangsung.

Metrik

Metrik adalah representasi pengukuran data selama interval waktu, misalnya, permintaan per detik. Data metrik memungkinkan pengamatan status aplikasi pada tingkat tinggi. Metrik .NET gRPC dipancarkan menggunakan EventCounter.

Metrik layanan gRPC

Metrik server gRPC dilaporkan pada Grpc.AspNetCore.Server sumber peristiwa.

Nama	Deskripsi
total-calls	Total Panggilan
current-calls	Panggilan Saat Ini
calls-failed	Total Panggilan Gagal
calls-deadline-exceeded	Total Tenggat Waktu Panggilan Terlampaui
messages-sent	Total Pesan Terkirim
messages-received	Total Pesan yang Diterima
calls-unimplemented	Total Panggilan Yang Tidak Di-unimplementasi

ASP.NET Core juga menyediakan metriknya sendiri pada Microsoft.AspNetCore.Hosting sumber peristiwa.

Metrik klien gRPC

Metrik klien gRPC dilaporkan pada Grpc.Net.Client sumber peristiwa.

Nama	Deskripsi
total-calls	Total Panggilan
current-calls	Panggilan Saat Ini
calls-failed	Total Panggilan Gagal
calls-deadline-exceeded	Total Tenggat Waktu Panggilan Terlampaui
messages-sent	Total Pesan Terkirim
messages-received	Total Pesan yang Diterima

Mengamati metrik

penghitung dotnet adalah alat pemantauan performa untuk pemantauan kesehatan ad-hoc dan penyelidikan performa tingkat pertama. Pantau aplikasi .NET dengan atau Grpc.AspNetCore.Server Grpc.Net.Client sebagai nama penyedia.

> 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

Cara lain untuk mengamati metrik gRPC adalah dengan menangkap data penghitung menggunakan paket Microsoft.ApplicationInsights.EventCounterCollector Application Insights. Setelah disiapkan, Application Insights mengumpulkan penghitung .NET umum saat runtime. Penghitung gRPC tidak dikumpulkan secara default, tetapi App Insights dapat disesuaikan untuk menyertakan penghitung tambahan.

Tentukan penghitung gRPC untuk Application Insight yang akan dikumpulkan di 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"));
            }
        );
    }

Sumber Daya Tambahan:

• Pengelogan di .NET Core dan ASP.NET Core
• gRPC untuk konfigurasi .NET
• Integrasi pabrik klien gRPC di .NET