メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw は公式の diagnostics-prometheus Plugin を通じて診断メトリクスを公開できます。信頼済みの内部診断をリッスンし、Prometheus テキストエンドポイントを次でレンダリングします。 
GET /api/diagnostics/prometheus
Content type は標準の Prometheus exposition format である text/plain; version=0.0.4; charset=utf-8 です。
このルートは Gateway 認証（operator スコープ）を使用します。公開の未認証 /metrics エンドポイントとして公開しないでください。他の operator API で使うものと同じ認証パスを通じてスクレイプしてください。
トレース、ログ、OTLP push、OpenTelemetry GenAI semantic attributes については、OpenTelemetry export を参照してください。

​
クイックスタート

1

Install the plugin

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

Enable the plugin

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

Restart the Gateway

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

Scrape the protected route

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

Wire 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 が必要です。これがない場合でも Plugin は HTTP ルートを登録しますが、診断イベントはエクスポーターに流れないため、レスポンスは空になります。

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

メトリクス型ラベル
openclaw_run_completed_totalカウンターchannel, model, outcome, provider, trigger
openclaw_run_duration_secondsヒストグラムchannel, model, outcome, provider, trigger
openclaw_model_call_totalカウンターapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondsヒストグラムapi, error_category, model, outcome, provider, transport
openclaw_model_tokens_totalカウンターagent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usageヒストグラムmodel, provider, token_type
openclaw_model_cost_usd_totalカウンターagent, channel, model, provider
openclaw_tool_execution_totalカウンターerror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondsヒストグラムerror_category, outcome, params_kind, tool
openclaw_harness_run_totalカウンターchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondsヒストグラムchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_message_processed_totalカウンターchannel, outcome, reason
openclaw_message_processed_duration_secondsヒストグラムchannel, outcome, reason
openclaw_message_delivery_started_totalカウンターchannel, delivery_kind
openclaw_message_delivery_totalカウンターchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondsヒストグラムchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalカウンターbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondsヒストグラムbrain, event_type, mode, provider, transport
openclaw_talk_audio_bytesヒストグラムbrain, event_type, mode, provider, transport
openclaw_queue_lane_sizeゲージlane
openclaw_queue_lane_wait_secondsヒストグラムlane
openclaw_session_state_totalカウンターreason, state
openclaw_session_queue_depthゲージstate
openclaw_session_recovery_totalカウンターaction, active_work_kind, state, status
openclaw_session_recovery_age_secondsヒストグラムaction, active_work_kind, state, status
openclaw_memory_bytesゲージkind
openclaw_memory_rss_bytesヒストグラムなし
openclaw_memory_pressure_totalカウンターlevel, reason
openclaw_telemetry_exporter_totalカウンターexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalカウンターなし

​
ラベルポリシー

Prometheus ラベルは、境界付きで低カーディナリティに保たれます。エクスポーターは runId、sessionKey、sessionId、callId、toolCallId、メッセージ ID、チャット ID、プロバイダーリクエスト ID などの生の診断識別子を出力しません。ラベル値は秘匿化され、OpenClaw の低カーディナリティ文字ポリシーに一致する必要があります。ポリシーに合わない値は、メトリクスに応じて unknown、other、または none に置き換えられます。
エクスポーターは、カウンター、ゲージ、ヒストグラムを合わせてメモリ内に保持する時系列を 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

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

​
関連