OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Prometheus 指標

OpenClaw 可透過官方 diagnostics-prometheus 外掛公開診斷指標。它會接收受信任的診斷事件，以及 內部加上標記、由分派器管理的診斷事件（佇列、記憶體和 工作階段復原訊號），並於以下位置呈現 Prometheus 文字端點：

text
GET /api/diagnostics/prometheus

內容類型為 text/plain; version=0.0.4; charset=utf-8，即標準的 Prometheus 公開格式。

關於追蹤、日誌、OTLP 推送和 OpenTelemetry GenAI 語意屬性，請參閱 OpenTelemetry 匯出。

快速開始

  • 安裝外掛

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

  • 啟用外掛

    設定

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

    命令列介面

    bash
    openclaw plugins enable diagnostics-prometheus

  • 重新啟動閘道

    HTTP 路由會在外掛啟動時註冊，因此啟用後請重新載入。

  • 擷取受保護的路由

    傳送操作員用戶端所使用的相同閘道驗證資訊：

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

  • 連接 Prometheus

    yaml
    # prometheus.ymlscrape_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, observation_unit, outcome, provider, transport
    openclaw_model_call_duration_seconds 直方圖 api, error_category, model, observation_unit, outcome, provider, transport
    openclaw_model_failover_total 計數器 from_model, from_provider, lane, reason, suspended, to_model, to_provider
    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_model_usage_duration_seconds 直方圖 agent, channel, model, provider
    openclaw_skill_used_total 計數器 activation, agent, skill, source
    openclaw_tool_execution_total 計數器 error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_duration_seconds 直方圖 error_category, outcome, params_kind, tool, tool_owner, tool_source
    openclaw_tool_execution_blocked_total 計數器 denied_reason, params_kind, tool, tool_owner, tool_source
    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_webhook_received_total 計數器 channel, webhook
    openclaw_webhook_error_total 計數器 channel, webhook
    openclaw_webhook_duration_seconds 直方圖 channel, webhook
    openclaw_message_received_total 計數器 channel, source
    openclaw_message_dispatch_started_total 計數器 channel, source
    openclaw_message_dispatch_completed_total 計數器 channel, outcome, reason, source
    openclaw_message_dispatch_duration_seconds 直方圖 channel, outcome, reason, source
    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_turn_created_total 計數器 agent, channel, trigger
    openclaw_session_stuck_total 計數器 reason, state
    openclaw_session_stuck_age_seconds 直方圖 reason, state
    openclaw_session_recovery_total 計數器 action, active_work_kind, state, status
    openclaw_session_recovery_age_seconds 直方圖 action, active_work_kind, state, status
    openclaw_liveness_warning_total 計數器 reason
    openclaw_liveness_sessions 儀表 state
    openclaw_liveness_event_loop_delay_p99_seconds 直方圖 reason
    openclaw_liveness_event_loop_delay_max_seconds 直方圖 reason
    openclaw_liveness_event_loop_utilization_ratio 直方圖 reason
    openclaw_liveness_cpu_core_ratio 直方圖 reason
    openclaw_payload_large_total 計數器 action, channel, plugin, reason, surface
    openclaw_payload_large_bytes 直方圖 action, channel, plugin, reason, surface
    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 計數器 無
    openclaw_diagnostic_async_queue_dropped_total 計數器 drop_class
    openclaw_diagnostic_async_queue_length 儀表 無

    對於模型呼叫指標，observation_unit="request" 會測量一次可觀察的 供應商請求。observation_unit="turn" 會測量一個合成的 Claude Code 或 Codex 命令列介面代理程式回合，其中可能包含多個隱藏的供應商請求。 比較延遲時，請將這些時間序列分開。

    標籤政策

    有界、低基數標籤

    Prometheus 標籤會維持有界且低基數。匯出器不會發出原始診斷識別碼，例如 runId、sessionKey、sessionId、callId、toolCallId、訊息 ID、聊天 ID 或供應商請求 ID。

    標籤值會經過遮蔽，且必須符合 OpenClaw 的低基數字元政策。不符合政策的值會依指標替換為 unknown、other 或 none。看似具範圍限定的代理程式工作階段金鑰之標籤，也會替換為 unknown。

    時間序列上限與溢位計數

    匯出器在記憶體中保留的時間序列上限為 2048 個，合併計算計數器、儀表與直方圖。超出此上限的新時間序列會遭捨棄，且每次都會讓 openclaw_prometheus_series_dropped_total 增加一。

    請監看此計數器，將它視為上游某個屬性正在洩漏高基數值的明確訊號。匯出器絕不會自動提高上限；如果計數持續上升，請修正來源，而不是停用上限。

    絕不會出現在 Prometheus 輸出中的內容
    • 提示文字、回應文字、工具輸入、工具輸出、系統提示
    • Talk 逐字稿、音訊承載資料、通話 ID、房間 ID、移交權杖、回合 ID，以及原始工作階段 ID
    • 原始供應商請求 ID（僅在適用時於跨度中使用有界雜湊值，絕不會用於指標）
    • 工作階段金鑰與工作階段 ID
    • 主機名稱、檔案路徑、秘密值

    PromQL 配方

    promql
    # 每分鐘權杖數，依供應商分組sum by (provider) (rate(openclaw_model_tokens_total[1m])) # 過去一小時的花費（USD），依模型分組sum by (model) (increase(openclaw_model_cost_usd_total[1h])) # 模型執行持續時間的第 95 百分位數histogram_quantile(  0.95,  sum by (le, provider, model)    (rate(openclaw_run_duration_seconds_bucket[5m]))) # 佇列等待時間 SLO（第 95 百分位數低於 2 秒）histogram_quantile(  0.95,  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))) < 2 # Skill 使用情形，依有界來源分組sum by (skill, source) (increase(openclaw_skill_used_total[24h])) # 遭捨棄的 Prometheus 時間序列（基數警報）increase(openclaw_prometheus_series_dropped_total[15m]) > 0

    在 Prometheus 與 OpenTelemetry 匯出之間選擇

    OpenClaw 獨立支援這兩種介面。你可以執行其中任一種、兩種都執行，或兩種都不執行。

    diagnostics-prometheus

    • 拉取模型：Prometheus 會抓取 /api/diagnostics/prometheus。
    • 不需要外部收集器。
    • 透過一般的閘道驗證進行身分驗證。
    • 此介面僅提供指標（不含追蹤或日誌）。
    • 最適合已標準化採用 Prometheus + Grafana 的技術堆疊。

    diagnostics-otel

    • 推送模型：OpenClaw 會透過 OTLP/HTTP 傳送至收集器或 OTLP 相容的後端。
    • 此介面包含指標、追蹤與日誌。
    • 需要同時使用兩者時，可透過 OpenTelemetry Collector（prometheus 或 prometheusremotewrite 匯出器）橋接至 Prometheus。
    • 完整目錄請參閱 OpenTelemetry 匯出。

    疑難排解

    回應本文為空
    • 檢查設定中的 diagnostics.enabled 是否未設為 false（預設為 true）。
    • 使用 openclaw plugins list --enabled 確認外掛已啟用並載入。
    • 產生一些流量；計數器與直方圖只有在至少發生一次事件後才會輸出資料列。
    401／未授權

    此端點需要閘道操作員範圍（auth: "gateway" 搭配 gatewayRuntimeScopeSurface: "trusted-operator"）。請使用 Prometheus 存取任何其他閘道操作員路由時所用的相同權杖或密碼。不提供公開且無須驗證的模式。

    `openclaw_prometheus_series_dropped_total` 持續上升

    有新的屬性超出 2048 個時間序列的上限。檢查近期指標中是否有基數異常偏高的標籤，並從來源修正。匯出器會刻意捨棄新的時間序列，而不是在未告知的情況下改寫標籤。

    Prometheus 在重新啟動後顯示過時的時間序列

    外掛只會將狀態保存在記憶體中。閘道重新啟動後，計數器會重設為零，儀表則會從下一個回報值重新開始。使用 PromQL 的 rate() 與 increase()，即可妥善處理重設。

    相關內容

    Was this useful?
    On this page

    On this page