OpenClaw ゲートウェイ Prometheus 指標：/metrics スクレイプ設計、ヒストグラム対サマリー、カーディナリティのガードレール、クラウド Mac mini 上の macOS LaunchAgent リハーサル

エージェント用ゲートウェイはコントロールプレーンです。ツールを認証し、モデル呼び出しを扇状に広げ、予算を強制します。ログはインシデント後の物語ですが、Prometheus の指標は誰もページを鳴らす前にレイテンシがゆっくり漂っていたかを示します。2026 年の成熟した OpenClaw では /metrics（または兄弟の管理ポート）にテキスト指標を出し、SRE が予測可能なカーディナリティと一貫した命名でスクレイプし、トレースが有効なときだけ exemplar を付けます。本文はスクレイプトポロジー、ヒストグラムとサマリーのトレードオフ、ラベル衛生、既存のヘルスチェックやログ管線との組み合わせ、そして LaunchAgent のタイマーで本番と同じ間隔を Mac mini に再現する方法を扱います。導入部でリンクする ゲートウェイのヘルス監視と稼働プローブ、ログのマスキングと logrotate の規律、アップグレードと移行チェックリスト、nginx を使ったローリング切替のトラフィックドレインと併読すると、デプロイ中にアラート・ログ・指標の三本線が揃います。

価格の文脈：MacHTML のクラウド Apple Silicon はおよそ $16.9/日 で、デザイナーのノートを借りずに本番と同じスクレイプ設定を常時回せる専用リハーサル機を維持できます。

ゲートウェイに第一級 Prometheus が要る理由

モノリスのWebアプリと違い、ゲートウェイは多数の非同期ストリームを多重化します。WebSocket のツール呼び出し、HTTP バッチ、プロバイダ再試行、ファイル副作用が同時に走ります。p99 のスパイクは集約CPUチャートでは見えないことも、作業がワーカー間で移っただけだからです。注意深く計装すれば Prometheus のカウンタとヒストグラムはリクエスト量・エラーコード・キュー深さ・プロバイダ固有のバックオフ窓を低オーバーヘッドで捉えます。無いとオペレーターは尾部サンプリング頼みで、請求が来るまで高コストなツール起動を見逃します。

OpenClaw のアーキテクチャは部分故障も前提です。あるプロバイダが劣化しても他は健康かもしれません。指標はルート別成功率を出したいが数千のラベル組合せは作りたくない——可観測性とカーディナリティのバランスが以下の各節の主題です。

静的ホスティングやエッジ配信と併走する場合でも、CDN 層にフルAPMを置けなくてもゲートウェイ内にキューとエラーの最小セットを残せば、後からマスキング済みログへアンカーを打てます。

/metrics リスナーのスクレイプ設計

mTLS と厳格ACLが保証されない限り、顧客トラフィックと同じソケットで指標を出さないでください。典型はゲートウェイホストの 127.0.0.1:9108 にバインドし、node_exporter サイドカーや Prometheus エージェントが SSH トンネルや VPC ピアリングで引きます。遠隔公開が必要なら nginx で TLS を終端し内部PKIのクライアント証明書を要求します。

scrape_configs:
  - job_name: openclaw-gateway
    scrape_interval: 15s
    metrics_path: /metrics
    static_configs:
      - targets: ['gateway-prod.internal:9108']

Prometheus のステール意味論を尊重し、デプロイでスクレイプが失敗したらグラフは嘘をつかず空白になるべきです。スクレイプ間隔を systemd や LaunchAgent の再起動予算と揃え、初回ブート直後のスクレイプが冷えたJITスパイクと重なってオートスケーラを誤魔化さないようにします。

サービスディスカバリで複数インスタンスを登録するなら instance と job を一貫させ、relabel で環境秘密を剥がします。多リージョンなら region のような低基数次元で分面し、FQDN を指標名に複製しない方が安全です。

2026年のヒストグラムとサマリー

ネイティブヒストグラムは構造化された桶をサーバが出し、Prometheus がレプリカ間で一貫して分位数を計算します。クライアント側サマリーは事前計算された分位数を出しますが Pod 間で安全に平均できません。OpenClaw ゲートウェイでは遅延とツール所要時間にヒストグラムを優先し、桶境界をSLO閾値に合わせます（例 250ms,500ms,1s,2s,5s）。制御できないSDKならサマリーも許容されますが同一メトリクス名に両方を混ぜないでください。

Exemplar はトレースへ橋を架けますが尾部サンプリングが許すときだけ trace id を付け、顧客識別子はエクスポート前に剥がします。macOS リハーサルホストでは既定で exemplar を切りローカルTSDBを小さく保ちます。

Grafana のヒートマップとアラート閾値を文書化し、運用チームと開発チームで同じSLO辞書を共有するとレビューが速くなります。

カーディナリティのガードレール

一意なラベル集合ごとに時系列が増えます。ゲートウェイはAPIキー・モデル名・テナントUUID・ファイルパスでラベルしたくなりますがやめてください。代わりに provider="anthropic" のような有界ラベルを出し、高基数はすでにログ記事で述べたマスキング規律に従う構造化ログへ送ります。カスタム指標はプロセスあたりアクティブ200系列未満（Goランタイム既定除く）のような硬い予算を置きます。

記録ルールでツール呼び出しをコホートに畳みます：sum by (route)(rate(openclaw_tool_calls_total[5m])) は、コンパイル時に閉じた列挙でない限りツールIDごとのエクスポートより安全です。

マルチテナントSaaSで「テナント別レイテンシ」をどうしても見たい場合は、Prometheus でテナントラベルを増やす前にクエリ層や課金ウェアハウスを検討してください。人気テナントがスクレイプコストと圧縮遅延を膨らませます。

ヘルスチェックとログとのペアリング

指標は合成プローブのトラフィックを複製すべきではなく補完します。外から「ポートが開いているか」はヘルスチェック、内側で「キューが減っているか」はカウンタが答えます。プローブが赤いときに gateway_errors_total が上がりヒストグラムが止まるようダッシュボードを配線します。リンク先の移行チェックリストに沿ったアップグレードでは、スクレイプ成功率が二間隔以上五の九を下回ったらオートスケールを一時停止します。

ログパイプラインに新しいマスキング規則を入れたら「どのラベルがどのログフィールドとJOINできるか」の対応表を残し、当直が深夜に即席クエリを発明しないようにします。

nginx ドレイン中のスクレイプ調整

ローリング切替はプロセス退出前に上流重みをずらします。サービスディスカバリが遅れると Prometheus が終了中のPodに当たる瞬間があります。ドレイン開始と同時にエンドポイントをSDから消すレディネスゲートを使い、導入部でリンクした nginx ガイダンスに合わせます。nginx 経由でスクレイプするなら専用 location とIP許可リストを追加し、無関係なローテーションで回る公開TLS証明書を流用しないでください。

二系統や複数入口ではGrafana注釈に重み変更のタイムスタンプを残し、スクレイプ失敗の窓とトラフィック曲線を事後照合しやすくします。

ローカルスクレイパ用 LaunchAgent

開発者ノートとクラウド Mac mini では LaunchAgent が cron よりタイミングが正確で unified logging に流せます。毎分 localhost へ軽い promtool check metrics curl を走らせ、CIより先に exposition の退化を捕まえます。

<key>StartInterval</key>
<integer>60</integer>

エージェントは非特権のままにし、bearer token を plist に書かないでください。適切な権限を持つ小さなヘルパーがキーチェーンから読みます。

同一ホストでカナリアと安定版を並走するなら metrics ポートを分け plist のラベルで混線を防ぎます。

クラウド Mac でのパリティ検証

クラウド Mac mini は Apple のスケジューラやファイルシステムの大小文字既定、TLSスタックの癖を再現します。保持期間を短くした本番スクレイプ設定をミラーし、負荷生成中にTSDB圧縮の遅れを観察します。およそ $16.9/日 なら共有ステージングに迷惑な多日ソークも現実的です。

スクリプトにはケーブル抜き、DNS切替、プロバイダ応答の人工遅延を入れ、桶が依然として行動可能な信号を出すか検証します。

セキュリティ：TLS と管理面の分離

指標エンドポイントは運用詳細を漏らします：キュー名、依存バージョン、サーキットブレーカー状態。ネットワークポリシー、SSHトンネル、ゼロトラストメッシュで保護します。JSONデバッグとPrometheusテキストを並べるなら content-type が衝突せず、DNS切替で誤って公開された管理ポートをクローラが拾わないようにします。

規制産業ではビジネスAPIだけでなく metrics URL にアクセスした主体も監査ログに残すべきです。

SLO：バーンレートと記録ルール

ゲートウェイ遅延とエラー率にSLIを定義し、複数窓のバーンアラートへ写像します。記録ルールで5分と1時間レートを事前計算しダッシュを軽くします。閾値は推測ではなく過去インシデントで検証し、メトリクスパネルからリクエストIDでフィルタしたログへの runbook リンクを置きます。

人間のサポート時間帯と夜間バッチで燃え方が違うならルールを分割し、夜間の正当なスパイクが昼の体験をかき消さないようにします。

マトリクス：出すものと捨てるもの

信号	出す？	メモ
リクエストUUID	いいえ	マスキングログへ。
キュー深さゲージ	はい	バックプレッシャ可視化に必須。
429カウンタ	はい	有界ラベル。Retry-Afterと相関。
ヒープサンプル	いいえ	pprof は別認証。

番号付きロールアウトチェックリスト

1. 既存指標を棚卸し予算超の系列を落とす。
2. ヒストグラム桶をSLO閾値に揃え境界を文書化する。
3. TLS・ACL・秘密を剥がすrelabel付きでスクレイプ設定を配線する。
4. ドレイン挙動を試し終了Podがスクレイプ復帰前にSDから消えることを確認する。
5. クラウドMacで合成負荷のもとプローブと指標を同時検証する。
6. デプロイ窓注釈付きのGrafanaを出荷する。
7. macOSホストでLaunchAgentカナリアを回しexpositionの漂いを早期検知する。
8. 保持戦略を見直しローカル演習Prometheusは積極的にダウンサンプルする。

よくある質問

ゲートウェイ本体に Prometheus を載せる？

通常はいいえ。集中TSDBへ遠隔スクレイプし爆発半径を小さくします。

OpenTelemetry は？

OTLPは補完。PromQL標準のチーム向けに exposition へ橋渡しできます。

CIでカーディナリティ退行をどう測る？

統合テスト後に系列数をスナップし、レビュー無しの新ラベルでビルドを落とします。

信頼できる指標は稼働チェックや構造化ログと同じ信頼性プログラムの一部です。MacHTML の専用 Mac mini（およそ $16.9/日）でスクレイプパスをリハーサルすれば、本番 Prometheus に届く前にTLS・ネットワーク・タイミング問題を捕らえられます。