gRPC 版 Chrome DevTools を作った — grpc-tap
つくったもの
grpc-tap — gRPC トラフィックをリアルタイムで観察できるターミナル UI ツールです。
リバースプロキシとして動作し、通過する全ての gRPC コールをキャプチャしてターミナルに表示します。アプリケーション側のコード変更は不要です。
モチベーション
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 型のフィールドは以下のヒューリスティクスで表示方法を決めています:
- ネストされた protobuf メッセージとしてパースを試みる
- 有効な UTF-8 かつ printable ならば文字列として表示
- それ以外は 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 のデバッグで困っている方はぜひ試してみてください。
Issue / PR / Star 歓迎です。
Discussion