.NET 上 gRPC 的記錄和診斷

作者：James Newton-King

本文提供從 gRPC 應用程式收集診斷資料的指引，以協助針對問題進行疑難排解。 涵蓋的主題包括：

• 記錄：寫入至 .NET Core 記錄的結構化記錄。 應用程式架構會使用 ILogger 來寫入記錄，而使用者則會用來在應用程式中自行記錄。
• 追蹤：與使用 DiaganosticSource 和 Activity 撰寫的作業相關的事件。 來自診斷來源的追蹤通常由 Application Insights 和 OpenTelemetry 等程式庫用來收集應用程式遙測。
• 計量：時間間隔內資料量值的表示法，例如每秒的要求數。 計量是透過 EventCounter 發出，可以使用 dotnet-counters 命令列工具或 Application Insights 來觀察。

記錄

gRPC 服務和 gRPC 用戶端使用 .NET Core 記錄寫入記錄。 對服務與用戶端應用程式中的非預期行為進行偵錯時，記錄是一個很好的起點。

gRPC 服務記錄

警告

伺服器端記錄可能包含來自您應用程式的敏感性資訊。 切勿將原始記錄從實際執行應用程式張貼至 GitHub 等公共論壇。

由於 gRPC 服務裝載於 ASP.NET Core 上，因此其會使用 ASP.NET Core 記錄系統。 在預設組態中，gRPC 記錄的資訊最少，但可以設定記錄。 如需設定 ASP.NET Core 記錄的詳細資訊，請參閱有關 ASP.NET Core 記錄的文件。

gRPC 會在 Grpc 類別下新增記錄。 若要從 gRPC 啟用詳細記錄，請將下列項目新增至 Logging 中的 LogLevel 子區段，將 Grpc 前置詞設定為 appsettings.json 檔案中的 Debug 層級：

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

也可以使用 ConfigureLogging 在 Program.cs 中設定記錄：

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

不使用 JSON 型的設定時，請在設定系統中設定下列設定值：

• Logging:LogLevel:Grpc = Debug

請檢查組態系統的文件，以確定如何指定巢狀組態值。 例如，使用環境變數時，會使用兩個 _ 字元，而不是 : (例如， Logging__LogLevel__Grpc)。

建議您在針對應用程式收集詳細的診斷資料時使用 Debug 層級。 Trace 層級產生的診斷層級很低，而且很少需要診斷問題。

範例記錄輸出

以下是 gRPC 服務 Debug 層級的主控台輸出範例：

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

存取伺服器端記錄

伺服器端記錄的存取方式取決於應用程式的環境。

作為主控台應用程式

如果您是在主控台應用程式中執行，則預設應該啟用主控台記錄器。 gRPC 記錄會出現在主控台中。

其他環境

如果應用程式部署至另一個環境 (例如，Docker、Kubernetes 或 Windows 服務)，請參閱在 .NET Core 和 ASP.NET Core 中記錄，以取得如何設定適合環境的記錄提供者詳細資訊。

gRPC 用戶端記錄

警告

用戶端記錄可能包含來自您應用程式的敏感性資訊。 切勿將原始記錄從實際執行應用程式張貼至 GitHub 等公共論壇。

若要從 .NET 用戶端取得記錄，請在建立用戶端的通道時設定 GrpcChannelOptions.LoggerFactory 屬性。 從 ASP.NET Core 應用程式呼叫 gRPC 服務時，可以從相依性插入 (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);
    }
}

啟用用戶端記錄的替代方式是使用 gRPC 用戶端處理站來建立用戶端。 向用戶端處理站註冊且從 DI 解析的 gRPC 用戶端會自動使用應用程式的已設定記錄。

如果應用程式未使用 DI，請使用 LoggerFactory.Create 建立新的 ILoggerFactory 執行個體。 若要存取此方法，請將 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);

gRPC 用戶端記錄範圍

gRPC 用戶端會將記錄範圍新增至 gRPC 呼叫期間建立的記錄。 範圍具有與 gRPC 呼叫相關的中繼資料：

• GrpcMethodType：gRPC 方法類型。 可能的值為來自 Grpc.Core.MethodType 列舉的名稱。 例如： Unary 。
• GrpcUri：gRPC 方法的相對 URI。 例如，/greet.Greeter/SayHellos。

範例記錄輸出

以下是 gRPC 用戶端 Debug 層級的主控台輸出範例：

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.

追蹤

gRPC 服務和 gRPC 用戶端會使用 DiagnosticSource 和 Activity 提供 gRPC 呼叫的相關資訊。

• .NET gRPC 使用活動來表示 gRPC 呼叫。
• 追蹤事件會在 gRPC 呼叫活動開始和停止時寫入診斷來源。
• 追蹤不會擷取何時在 gRPC 串流呼叫存留期內傳送訊息的相關資訊。

gRPC 服務追蹤

gRPC 服務裝載於 ASP.NET Core 上，後者可報告傳入 HTTP 要求的相關事件。 gRPC 特定中繼資料會新增至 ASP.NET Core 提供的現有 HTTP 要求診斷。

• 診斷來源名稱為 Microsoft.AspNetCore。
• 活動名稱為 Microsoft.AspNetCore.Hosting.HttpRequestIn。
  • gRPC 呼叫所叫用的 gRPC 方法名稱會新增為具有名稱 grpc.method 的標記。
  • gRPC 呼叫在完成時的狀態碼會新增為具有名稱 grpc.status_code 的標記。

gRPC 用戶端追蹤

.NET gRPC 用戶端會使用 HttpClient 來呼叫 gRPC。 雖然 HttpClient 會寫入診斷事件，但 .NET gRPC 用戶端會提供自訂診斷來源、活動和事件，以便收集 gRPC 呼叫的完整資訊。

• 診斷來源名稱為 Grpc.Net.Client。
• 活動名稱為 Grpc.Net.Client.GrpcOut。
  • gRPC 呼叫所叫用的 gRPC 方法名稱會新增為具有名稱 grpc.method 的標記。
  • gRPC 呼叫在完成時的狀態碼會新增為具有名稱 grpc.status_code 的標記。

收集追蹤

使用 DiagnosticSource 的最簡單方式是在應用程式中設定遙測程式庫，例如 Application Insights 或 OpenTelemetry。 該程式庫會處理 gRPC 呼叫以及其他應用程式遙測的相關資訊。

您可以在 Application Insights 等受控服務中檢視追蹤，也可以執行為自己的分散式追蹤系統。 OpenTelemetry 支援將追蹤資料匯出至 Jaeger 和 Zipkin。

DiagnosticSource 可以使用 DiagnosticListener 在程式碼中取用追蹤事件。 如需使用程式碼接聽診斷來源的相關資訊，請參閱 DiagnosticSource 使用者指南。

注意

遙測程式庫目前不會擷取 gRPC 特定的 Grpc.Net.Client.GrpcOut 遙測。 改善擷取此追蹤的遙測程式庫的工作正在進行中。

度量

計量是時間間隔內資料量值的表示法，例如每秒的要求數。 計量資料允許在高層級觀察應用程式的狀態。 .NET gRPC 計量是使用 EventCounter 發出的。

gRPC 服務計量

gRPC 伺服器計量會在 Grpc.AspNetCore.Server 事件來源上報告。

名稱	描述
total-calls	呼叫總計
current-calls	目前的呼叫數
calls-failed	失敗呼叫總數
calls-deadline-exceeded	超過期限的呼叫總數
messages-sent	傳送的訊息總數
messages-received	接收的訊息總數
calls-unimplemented	未實作的呼叫總數

ASP.NET Core 也會在 Microsoft.AspNetCore.Hosting 事件來源上提供自己的計量。

gRPC 用戶端計量

gRPC 用戶端計量會在 Grpc.Net.Client 事件來源上報告。

名稱	描述
total-calls	呼叫總計
current-calls	目前的呼叫數
calls-failed	失敗呼叫總數
calls-deadline-exceeded	超過期限的呼叫總數
messages-sent	傳送的訊息總數
messages-received	接收的訊息總數

觀察計量

dotnet-counters 是效能監控工具，適用於特定的狀況監控和第一層級效能調查。 使用 Grpc.AspNetCore.Server 或 Grpc.Net.Client 作為提供者名稱來監視 .NET 應用程式。

> 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

觀察 gRPC 計量的另一種方法是使用 Application Insights 的 Microsoft.ApplicationInsights.EventCounterCollector 套件來擷取計數器資料。 設定之後，Application Insights 會在執行階段收集常見的 .NET 計數器。 預設不會收集 gRPC 的計數器，但可以自訂 App Insights 以包含其他計數器。

為 Application Insight 指定 gRPC 計數器以在 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"));
            }
        );
    }

其他資源

• .NET Core 和 ASP.NET Core 中的記錄 (機器翻譯)
• 適用於 .NET 組態的 gRPC
• .NET 中的 gRPC 用戶端處理站整合