🙄

gRPC 版 Chrome DevTools を作った — grpc-tap

に公開

つくったもの

grpc-tap — gRPC トラフィックをリアルタイムで観察できるターミナル UI ツールです。

リバースプロキシとして動作し、通過する全ての gRPC コールをキャプチャしてターミナルに表示します。アプリケーション側のコード変更は不要です。

https://github.com/mickamy/grpc-tap

モチベーション

Web 開発では Chrome DevTools の Network タブで HTTP リクエストを簡単に確認できます。しかしバックエンド間の gRPC 通信ではそうはいきません。

既存ツールとの違い:

  • grpcurl / grpcui — リクエストを手動で送る「能動的」なツール。流れているトラフィックの観察には使えない
  • Wireshark — パケットレベルの解析は可能だが、gRPC のセマンティクスでの表示はできない
  • サービスメッシュの Observability — 本番環境向け。ローカル開発で使うには大げさ

grpc-tap は「接続先を変えるだけで、流れている gRPC トラフィックを全部見られる」ことをゴールにしています。

アーキテクチャ

┌─────────────┐      ┌───────────────────────┐      ┌─────────────────┐
│ Application │─────▶│  grpc-tapd (proxy)    │─────▶│ gRPC Server     │
└─────────────┘      │                       │      └─────────────────┘
                     │  captures calls       │
                     │  via HTTP/2 proxy     │
                     └───────────┬───────────┘
                                 │ gRPC stream
                     ┌───────────▼───────────┐
                     │  grpc-tap (TUI)       │
                     └───────────────────────┘

2つのバイナリで構成されています。

  • grpc-tapd — HTTP/2 リバースプロキシ。トラフィックを upstream に転送しつつ、リクエスト/レスポンスをキャプチャ
  • grpc-tap — TUI クライアント。grpc-tapd に gRPC で接続し、イベントをリアルタイム表示

使い方

インストール

# Homebrew
brew install --cask mickamy/tap/grpc-tap

# Go
go install github.com/mickamy/grpc-tap@latest
go install github.com/mickamy/grpc-tap/cmd/grpc-tapd@latest

起動

# 1. プロキシを起動(:8080 で listen、upstream の :9000 に転送)
grpc-tapd -listen=:8080 -upstream=http://localhost:9000

# 2. アプリの接続先をプロキシに向ける(localhost:9000 → localhost:8080)

# 3. TUI を起動
grpc-tap localhost:9090

これだけで、アプリと gRPC サーバー間の全通信がターミナルに表示されます。

機能

リスト表示

キャプチャした gRPC コールの一覧です。メソッド名、ステータス、レイテンシ、プロトコルが表示されます。

  • / でインクリメンタルサーチ
  • s でソート切り替え(時系列 / レイテンシ順)
  • e でエラーのみフィルタ

インスペクタ

Enter で個別のコールを詳細表示します。

  • リクエスト/レスポンスヘッダー
  • リクエスト/レスポンスボディ(protobuf wire format をスキーマなしでデコード)
  • c / C でリクエスト/レスポンスボディをクリップボードにコピー

Edit & Resend

インスペクタで e を押すと、キャプチャしたリクエストボディを $EDITOR で編集できます。

protobuf wire format をフィールド番号ベースの JSON に変換して表示します:

{
  "1": "hello",
  "2": 42
}

編集して保存すると、JSON → protobuf に戻して upstream に再送信します。結果はイベントストリームに流れるので、そのままインスペクタで確認できます。

.proto ファイルやスキーマ情報は不要です。

アナリティクス

a でメソッドごとの統計を表示します。

  • コール回数
  • 平均レイテンシ
  • 合計時間
  • エラー率

s でソート切り替え(total / count / avg / error rate)。

対応プロトコル

  • gRPC (HTTP/2, application/grpc)
  • gRPC-Web (application/grpc-web)
  • Connect (application/connect+proto, application/connect+json)

Content-Type ヘッダーからプロトコルを自動判別します。

技術的な話

スキーマなし protobuf デコード

grpc-tap の大きな特徴は、.proto ファイルなしで protobuf のボディを人間が読める形で表示できることです。

protobuf wire format にはフィールド番号と型情報(varint, fixed32, fixed64, bytes)が含まれているので、フィールド名はわからなくてもフィールド番号と値は復元できます。

// wire format → JSON
// field 1 (bytes/string) = "hello", field 2 (varint) = 42
// → {"1": "hello", "2": 42}

bytes 型のフィールドは以下のヒューリスティクスで表示方法を決めています:

  1. ネストされた protobuf メッセージとしてパースを試みる
  2. 有効な UTF-8 かつ printable ならば文字列として表示
  3. それ以外は hex 文字列

gRPC フレームカウント

gRPC の各メッセージは [1-byte flags][4-byte length][payload] のフレームで送られます。リクエストとレスポンスそれぞれのフレーム数をカウントすることで、コールタイプ(Unary / Server Stream / Client Stream / Bidi Stream)を自動判別しています。

技術スタック

  • Go — プロキシ、サーバー、TUI 全て Go
  • Bubble Tea — TUI フレームワーク
  • gRPC — プロキシと TUI 間の通信
  • HTTP/2 (h2c) — リバースプロキシ

まとめ

gRPC のデバッグで困っている方はぜひ試してみてください。

https://github.com/mickamy/grpc-tap

Issue / PR / Star 歓迎です。

Discussion