English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Prometheus メトリクス

OpenClaw は公式の diagnostics-prometheus Plugin を通じて診断メトリクスを公開できます。信頼済みの内部診断をリッスンし、Prometheus テキストエンドポイントを次でレンダリングします。

GET /api/diagnostics/prometheus

Content type は標準の Prometheus exposition format である text/plain; version=0.0.4; charset=utf-8 です。

トレース、ログ、OTLP push、OpenTelemetry GenAI semantic attributes については、OpenTelemetry export を参照してください。

クイックスタート

  • Install the plugin

    openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

  • Enable the plugin

    Config

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

    CLI

    openclaw plugins enable diagnostics-prometheus

  • Restart the Gateway

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

  • Scrape the protected route

    operator クライアントが使うものと同じ Gateway 認証を送信します。

    curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus

  • 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"]

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

    メトリクス 型 ラベル
    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 カウンター なし

    ラベルポリシー

    Bounded, low-cardinality labels

    Prometheus ラベルは、境界付きで低カーディナリティに保たれます。エクスポーターは runId、sessionKey、sessionId、callId、toolCallId、メッセージ ID、チャット ID、プロバイダーリクエスト ID などの生の診断識別子を出力しません。

    ラベル値は秘匿化され、OpenClaw の低カーディナリティ文字ポリシーに一致する必要があります。ポリシーに合わない値は、メトリクスに応じて unknown、other、または none に置き換えられます。

    時系列の上限とオーバーフロー計上

    エクスポーターは、カウンター、ゲージ、ヒストグラムを合わせてメモリ内に保持する時系列を 2048 系列に制限します。その上限を超える新しい系列は破棄され、そのたびに openclaw_prometheus_series_dropped_total が 1 増加します。

    このカウンターは、上流の属性が高カーディナリティ値を漏らしていることを示す強いシグナルとして監視してください。エクスポーターが上限を自動的に引き上げることはありません。増加している場合は、上限を無効化するのではなく原因を修正してください。

    Prometheus 出力に決して現れないもの
    • プロンプトテキスト、応答テキスト、ツール入力、ツール出力、システムプロンプト
    • 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

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

    OpenClaw は両方のサーフェスを独立してサポートしています。どちらか一方、両方、またはどちらも実行しない構成が可能です。

    diagnostics-prometheus

    • プルモデル: Prometheus が /api/diagnostics/prometheus をスクレイプします。
    • 外部コレクターは不要です。
    • 通常の Gateway 認証を通じて認証されます。
    • サーフェスはメトリクスのみです（トレースやログはありません）。
    • Prometheus + Grafana で既に標準化されているスタックに最適です。

    diagnostics-otel

    • プッシュモデル: OpenClaw が OTLP/HTTP をコレクターまたは OTLP 互換バックエンドへ送信します。
    • サーフェスにはメトリクス、トレース、ログが含まれます。
    • 両方が必要な場合は、OpenTelemetry Collector（prometheus または prometheusremotewrite エクスポーター）を通じて Prometheus にブリッジします。
    • 完全なカタログについては、OpenTelemetry エクスポートを参照してください。

    トラブルシューティング

    空のレスポンス本文
    • config で diagnostics.enabled: true を確認します。
    • Plugin が有効化され、openclaw plugins list --enabled で読み込まれていることを確認します。
    • いくらかのトラフィックを生成します。カウンターとヒストグラムは、少なくとも 1 つのイベントが発生した後にだけ行を出力します。
    401 / 未認可

    エンドポイントには Gateway オペレータースコープ（auth: "gateway" と gatewayRuntimeScopeSurface: "trusted-operator"）が必要です。他の Gateway オペレータールートで Prometheus が使用しているものと同じトークンまたはパスワードを使用してください。公開の未認証モードはありません。

    `openclaw_prometheus_series_dropped_total` が増加している

    新しい属性が 2048 系列の上限を超えています。最近のメトリクスを調べ、予期せず高カーディナリティになっているラベルを見つけ、原因を修正してください。エクスポーターは、ラベルを黙って書き換えるのではなく、意図的に新しい系列を破棄します。

    再起動後に Prometheus が古い系列を表示する

    Plugin は状態をメモリ内にのみ保持します。Gateway の再起動後、カウンターはゼロにリセットされ、ゲージは次に報告された値から再開します。リセットを適切に扱うには、PromQL の rate() と increase() を使用してください。

    関連