2026年、OpenClaw ゲートウェイの相関 ID と構造化トレース：ツール呼び出し単位の JSON、traceparent 伝播、Prometheus との突合、タイムアウト解析、クラウド Mac mini 上の LaunchAgent リハーサル

OpenClaw ゲートウェイが複数のモデルとツール先に同時に届く構成では、「遅い」と言われても、どのホップで証拠を置くべきかが揃わないまま問い合わせが増えます。本稿では リクエスト単位の識別子 の付け方、W3C traceparent の伝播、ツール呼び出しごとに 1 行の JSON、そして既に Prometheus スクラップ設計（OpenClaw） で描いたメトリクスと突き合わせる手順を整理します。読み取り停滞の切り分けは 読み取りタイムアウト診断 と同じ運用線に乗せると、pager から JSON 行まで一本の線で辿れます。

目標は単純です。運用者が request_id を一つ貼り付けるだけで、ツールチェーン・上流ステータス・キュー深度のスナップショット・スパンの順序が再現でき、ユーザーへ見えていた遅延を再実行しなくても説明できる状態にすることです。数値の出発点としては UUIDv4 の十分なエントロピー、レイテンシは 90〜95 パーセンタイル を SLO に据える考え方、そして実機検証は 1 日あたりおおよそ 16.9 ドル 前後のクラウド Mac mini という演習予算感です。

request_id、trace_id、span_id の役割

層が混ざると運用が壊れます。request_id は「ユーザーから見えるチケット番号」に相当し、インバウンドの HTTP／WebSocket セッションにつき一つです。エッジで UUIDv4（122 ビットのランダム性）を発行するか、すでに X-Request-ID が信頼できる経路ならそれを正とします。クライアント任意の長い文字列はそのまま信用せず、128 文字より長い識別子は拒否 してログ注入を防ぎます。

W3C のトレースコンテキストはサービス間の縫い目用です。trace-id はワークフロー全体で不変、子スパンは新しい span-id を切りつつ trace-id を引き継ぎます。ゲートウェイプロセス内では MCP 呼び出しごとに軽量な tool_span_id を切ると、非同期完了時に標準出力が混ざってもソート可能な順序が残ります。

識別子	スコープ	カーディナリティ上の注意
request_id	単一のインバウンド対話	高い。生の UUID を Prometheus ラベルにしない
trace_id	分散グラフ全体	ログでは中程度。ラベル濫用は避ける
tool.name と結果	集約	低い。RED メトリクス向き

ヘッダ、プロキシ、衝突ルール

TLS 終端はリバースプロキシに任せ、欠けている場合はそこで X-Request-ID を注入します。traceparent は OpenTelemetry を理解する上流 LLM ゲートウェイへそのまま転送し、クライアントが重複ヘッダを誤送信したときは一方を落として衝突を避けます。CDN 背面に OpenClaw を置く場合、ストリーミング応答には エッジ側の最小アイドル 120 秒 など、表向きタイムアウトを余裕持たせつつ、ゲートウェイ側のアイドルは短めに維持すると、CDN が止めたのかプロバイダが止めたのかログで分かれます。

WebSocket では、再接続の嵐でスパンが孤児にならないよう、最初のサーバフレームに request_id をエコーする運用が堅実です。

ゲートウェイとツール向け構造化 JSON

改行区切り JSON に一本化し、イベントは一行に一つ、整形はしない、UTF-8 で BOM なし。最低限の列として ts（UTC の ISO8601）、level、service=openclaw-gateway、host、request_id、trace_id、span_id、event（tool.start／tool.end など）、tool、latency_ms、upstream_status、retry_count を揃えます。

{
  "ts": "2026-04-28T01:17:41.332Z",
  "level": "info",
  "service": "openclaw-gateway",
  "request_id": "f6c2...9aa1",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "event": "tool.end",
  "tool": "filesystem.read",
  "latency_ms": 184,
  "upstream_status": 200,
  "arg_fingerprint": "sha256:7c2a...",
  "retry_count": 0
}

ツール引数は SHA-256 で指紋化し、秘密は絶対に載せません。API キー・ベアラートークン・メール本文はインデックス対象の列から除外する封筒フィールドへ回します。schema_rev を整数で持つと、リプレイジョブが無言のスキーマ崩れを検知しやすくなります。

ログと Prometheus ヒストグラムの突合

ヒストグラムは分位点を要約します。ラベルは tool、model_class、region のように低カーディナリティに留めます。生の request_id をラベルにすると時系列が爆発するので、スタックが exemplar を支援するならそこへ深いリンクを載せ、さもなければログシッパのメタデータへ request_id を付けて Loki 等から histogram_quantile(0.95,...) のスパイクを一行の JSON に降りられるようにします。

スクレイプを 15 秒、ログフラッシュを 50 ミリ秒単位で揃えるイメージを持つと、短いインシデントでも三回のスクレイプ以内にカウンタの隆起が見え、exemplar が一段遅れても調査線は途切れにくいです。

遅いツール呼び出しの端到端トレース

壁時計が 2500 ミリ秒を超えるのに CPU が遊んでいるなら、スパンへ wait_reason（tcp_connect、tls_handshake、provider_queue、disk_io など）をシステムコール境界のフックから付与します。サーキットブレーカーの状態と照らすと、バックオフが防衛ロジック由来か、本当に上流が飽和しているかが区別できます。

ストリーミング補完では部分トークンへ単調増加の chunk_seq を押すと、途中打ち切りでも事後検証が一意に並びます。

LaunchAgent、フラッシュ、ローテーションと順序

macOS の launchd は Linux の journald と標準出力のまとめ方が異なります。クリティカルイベントは明示的にフラッシュするか、バッチングの安全な構造化シッパに任せます。newsyslog や Vector 連携では、夜間ローテーション後も request_id が途切れないようオフセット確認のうえで圧縮し、クラウド上の Apple Silicon Mac mini で順序ズレを先に炙り出すのが現実的です。Linux コンテナだけの CI ではパイプのバッファ挙動が違い、問題を隠します。

本番前チェックリスト

1. 不正なトレースヘッダは JSON の Actionable な本文とともに 400 で拒否する。
2. プロセス起動イベントに gateway.version と git_sha を一度だけ刻む。
3. ホット検索を遅らせないよう、14 日経過後の構造化ログはコールド層へ。
4. サンプルしたトレースの少なくとも 99% がヒストグラムのバケットと突合できることをダッシュボードで監査する。
5. OpenClaw ワークスペース方針と並べてマスクルールを文書化する。

サンプリング、保存予算、インシデント再生

チャッティな負荷では毎ツールフルトレースが一分あたり 25 MB を超えることもあります。ゲートウェイでヘッドベースのサンプリングを採り、エラーパスは 100%、平常時の成功は 5〜10%、直近五分のエラーバジェットが 0.5% を越えたら自動で 50% に上げる、といった階段が現実的です。サンプリング判断自体に同じ request_id を載せないと、下流コレクタが半端なトレースだけ抱えます。

コールドストレージは規制顧客向けに 400 日を目安にしつつ、本文はスクラブして指紋とレイテンシだけ残す階層化も検討します。再生では ts と chunk_seq で並べ、サーキットブレーカー遷移とキュー深度を重ねると、緩和が一スクレイプ以内に効いたかが読み取れます。週次で 250 ms の人工遅延をサンドボックスツールに入れ、同じ相関キーでアラートから JSON 行まで三分以内に降りられるかを稽古してください。共有ゲートウェイではテナントラベルとワークスペース ID の対応も文書化し、トレース形式が同型でも権限境界を越えた検索が起きないようにします。

JSONL・UTC・request_id の三本柱は、ポストモーテムを二台のノートパソコンで並べて比較できる再現性を与え、ベンダ固有のバイナリキャプチャに縛られにくい観測可能性を維持します。Apple Silicon Mac mini は JSON シリアライズ負荷のワーカーを静かな熱設計で受け止めやすく、MacHTML のクラウドでは launchd と SSH・VNC の癖まで含めてリハーサルでき、およそ 16.9 ドル／日 の弾力価格でピーク検証と通常運用を切り替えやすいです。