.NET での gRPC のログ記録と診断

作成者: James Newton-King

この記事では、問題のトラブルシューティングに役立つ診断情報を gRPC アプリから収集するためのガイダンスを提供します。 取り上げるトピックは次のとおりです。

• ログ - .NET Core ログに書き込まれる構造化ログ。 ILogger は、ログを書き込むためにアプリケーション フレームワークによって使用され、アプリで独自のログ記録を行うためユーザーによって使用されます。
• トレース - DiaganosticSource と Activity を使用して記述される操作に関連するイベント。 診断ソースからのトレースは、通常、Application Insights や OpenTelemetry などのライブラリによって、アプリのテレメトリを収集するために使用されます。
• メトリック - 1 秒あたりの要求数など、一定期間にわたるデータ測定値を表します。 メトリックは 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 サブセクションに次の項目を追加して、 appsettings.json ファイルの Debug レベルに Grpc プレフィックスを構成します。

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

ログは、Program.cs で ConfigureLogging を使用して構成することもできます。

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

構成システムのドキュメントを調べて、入れ子になった構成値を指定する方法を確認してください。 たとえば、環境変数の使用時には、: の代わりに 2 つの _ 文字を使用します (例: 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 サービスは、受信 HTTP 要求に関するイベントを報告する ASP.NET Core でホストされます。 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 で診断イベントが書き込まれますが、gRPC 呼び出しに関する完全な情報を収集できるように、.NET 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 のユーザー ガイドを参照してください。

Note

現在のところ、テレメトリ ライブラリでは gRPC 固有の Grpc.Net.Client.GrpcOut テレメトリはキャプチャされません。 このトレースをキャプチャするテレメトリ ライブラリの改善の取り組みが進行中です。

メトリック

メトリックは、1 秒あたりの要求数など、一定期間にわたるデータ測定値を表します。 メトリック データを使用すると、アプリの状態を高レベルで監視できます。 .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 をカスタマイズできます。

Startup.cs で収集するように、Application insights の gRPC カウンターを指定します。

    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 クライアント ファクトリの統合