メインコンテンツへスキップ
OpenClaw は、公式の diagnostics-prometheus Plugin を通じて診断メトリクスを公開できます。信頼済み診断に加えて、内部でタグ付けされたディスパッチャー所有の診断イベント（キュー、メモリ、セッションリカバリ信号）をリッスンし、次の場所で Prometheus テキストエンドポイントをレンダリングします。 
GET /api/diagnostics/prometheus
コンテンツタイプは text/plain; version=0.0.4; charset=utf-8 で、標準の Prometheus 公開形式です。
このルートは Gateway 認証（オペレータースコープ、信頼済みオペレーターサーフェス）を使用します。公開の未認証 /metrics エンドポイントとして公開しないでください。他のオペレーター API で使用しているものと同じ認証パスを通じてスクレイプしてください。
トレース、ログ、OTLP プッシュ、OpenTelemetry GenAI セマンティック属性については、OpenTelemetry エクスポートを参照してください。

​
クイックスタート

1

Plugin をインストールする

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
2

Plugin を有効化する

{
  plugins: {
    allow: ["diagnostics-prometheus"],
    entries: {
      "diagnostics-prometheus": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
  },
}
3

Gateway を再起動する

HTTP ルートは Plugin 起動時に登録されるため、有効化後に再読み込みしてください。
4

保護されたルートをスクレイプする

オペレータークライアントが使用するものと同じ Gateway 認証を送信します:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Prometheus を接続する

# prometheus.yml
scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]
diagnostics.enabled のデフォルトは true です。厳しく制約された環境でのみ false に設定してください。false の場合でも、Plugin は HTTP ルートを登録しますが、診断イベントは exporter に流れないため、レスポンスは空になります。

​
エクスポートされるメトリクス

メトリクス種類ラベル
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalcounterfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_model_usage_duration_secondshistogramagent, channel, model, provider
openclaw_skill_used_totalcounteractivation, agent, skill, source
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcounterdenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalcounterchannel, webhook
openclaw_webhook_error_totalcounterchannel, webhook
openclaw_webhook_duration_secondshistogramchannel, webhook
openclaw_message_received_totalcounterchannel, source
openclaw_message_dispatch_started_totalcounterchannel, source
openclaw_message_dispatch_completed_totalcounterchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramchannel, outcome, reason, source
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totalcounterchannel, delivery_kind
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcounterbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_turn_created_totalcounteragent, channel, trigger
openclaw_session_stuck_totalcounterreason, state
openclaw_session_stuck_age_secondshistogramreason, state
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_liveness_warning_totalcounterreason
openclaw_liveness_sessionsgaugestate
openclaw_liveness_event_loop_delay_p99_secondshistogramreason
openclaw_liveness_event_loop_delay_max_secondshistogramreason
openclaw_liveness_event_loop_utilization_ratiohistogramreason
openclaw_liveness_cpu_core_ratiohistogramreason
openclaw_payload_large_totalcounteraction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaction, channel, plugin, reason, surface
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramなし
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounterなし
openclaw_diagnostic_async_queue_dropped_totalcounterdrop_class
openclaw_diagnostic_async_queue_lengthgaugeなし

​
ラベルポリシー

Prometheus のラベルは境界があり、低カーディナリティに保たれます。exporter は runId、sessionKey、sessionId、callId、toolCallId、メッセージ ID、チャット ID、プロバイダーリクエスト ID などの生の診断識別子を出力しません。ラベル値は秘匿化され、OpenClaw の低カーディナリティ文字ポリシーに一致する必要があります。ポリシーに失敗した値は、メトリクスに応じて unknown、other、または none に置き換えられます。スコープ付きエージェントセッションキーのように見えるラベルも unknown に置き換えられます。
エクスポーターは、カウンター、ゲージ、ヒストグラムを合わせて、メモリ内に保持する時系列を 2048 シリーズに制限します。その上限を超える新しいシリーズは破棄され、そのたびに openclaw_prometheus_series_dropped_total が 1 増加します。このカウンターは、上流の属性が高カーディナリティ値を漏らしていることを示す明確なシグナルとして監視してください。エクスポーターが上限を自動的に引き上げることはありません。増加する場合は、上限を無効にするのではなく発生元を修正してください。
  • プロンプト本文、応答本文、ツール入力、ツール出力、システムプロンプト
  • Talk の文字起こし、音声ペイロード、通話 ID、ルーム ID、ハンドオフトークン、ターン ID、生のセッション ID
  • 生のプロバイダーリクエスト ID（該当する場合はスパン上の境界付きハッシュのみ。メトリクス上には決して出ません）
  • セッションキーとセッション ID
  • ホスト名、ファイルパス、シークレット値

​
PromQL レシピ

# Tokens per minute, split by provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spend (USD) over the last hour, by model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95th percentile model run duration
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Queue wait time SLO (95p under 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Skill usage, split by bounded source
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
クロスプロバイダーダッシュボードには gen_ai_client_token_usage を推奨します。これは OpenTelemetry GenAI セマンティック規約に従い、OpenClaw 以外の GenAI サービスのメトリクスとも一貫しています。

​
Prometheus エクスポートと OpenTelemetry エクスポートの選択

OpenClaw は両方のサーフェスを独立してサポートします。どちらか一方、両方、またはどちらも使わない構成で実行できます。
  • プルモデル: Prometheus が /api/diagnostics/prometheus をスクレイプします。
  • 外部コレクターは不要です。
  • 通常の Gateway 認証を通じて認証されます。
  • サーフェスはメトリクスのみです（トレースやログはありません）。
  • すでに Prometheus + Grafana で標準化されているスタックに最適です。

​
トラブルシューティング

  • config で diagnostics.enabled が false に設定されていないことを確認してください（デフォルトは true です）。
  • Plugin が有効化され、openclaw plugins list --enabled で読み込まれていることを確認してください。
  • いくらかのトラフィックを生成してください。カウンターとヒストグラムは、少なくとも 1 件のイベントが発生した後にのみ行を出力します。
エンドポイントには Gateway オペレータースコープ（gatewayRuntimeScopeSurface: "trusted-operator" を伴う auth: "gateway"）が必要です。他の Gateway オペレータールートで Prometheus が使用するものと同じトークンまたはパスワードを使用してください。公開の未認証モードはありません。
新しい属性が 2048 シリーズの上限を超えています。最近のメトリクスを調べて、想定外に高カーディナリティなラベルを見つけ、発生元で修正してください。エクスポーターは、ラベルを黙って書き換えるのではなく、意図的に新しいシリーズを破棄します。
Plugin はメモリ内にのみ状態を保持します。Gateway の再起動後、カウンターはゼロにリセットされ、ゲージは次に報告された値から再開します。リセットをきれいに扱うには、PromQL の rate() と increase() を使用してください。

​
関連