Перейти до основного вмісту
OpenClaw може надавати діагностичні метрики через офіційний Plugin diagnostics-prometheus. Він прослуховує довірену діагностику, а також події стабільності gateway, які генерує ядро, а потім віддає текстову кінцеву точку Prometheus за адресою: 
GET /api/diagnostics/prometheus
Тип вмісту — text/plain; version=0.0.4; charset=utf-8, стандартний формат експозиції Prometheus.
Маршрут використовує автентифікацію Gateway (область оператора). Не відкривайте його як публічну неавтентифіковану кінцеву точку /metrics. Збирайте метрики через той самий шлях автентифікації, який ви використовуєте для інших API оператора.
Для трасувань, журналів, OTLP push і семантичних атрибутів 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. Без цього 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_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_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лічильникнемає

​
Політика міток

Мітки Prometheus залишаються обмеженими й низькокардинальними. Експортер не видає необроблені діагностичні ідентифікатори, як-от runId, sessionKey, sessionId, callId, toolCallId, ідентифікатори повідомлень, ідентифікатори чатів або ідентифікатори запитів провайдера.Значення міток редагуються й мають відповідати політиці OpenClaw щодо символів із низькою кардинальністю. Значення, що не проходять цю політику, замінюються на unknown, other або none, залежно від метрики. Мітки, схожі на ключі scoped agent session, також замінюються на unknown.
Експортер обмежує збережені часові ряди в пам’яті до 2048 серій загалом для лічильників, вимірювачів і гістограм. Нові серії понад це обмеження відкидаються, а openclaw_prometheus_series_dropped_total збільшується на одиницю щоразу.Відстежуйте цей лічильник як жорсткий сигнал, що атрибут вище за потоком пропускає висококардинальні значення. Експортер ніколи не знімає обмеження автоматично; якщо значення зростає, виправте джерело замість вимикання обмеження.
  • текст prompt, текст відповіді, вхідні дані інструментів, вихідні дані інструментів, системні prompt
  • транскрипти Talk, аудіонавантаження, ідентифікатори викликів, ідентифікатори кімнат, токени передавання, ідентифікатори ходів і необроблені ідентифікатори сеансів
  • необроблені ідентифікатори запитів провайдера (лише обмежені хеші, де застосовно, у spans — ніколи в метриках)
  • ключі сеансів та ідентифікатори сеансів
  • імена хостів, шляхи до файлів, секретні значення

​
Рецепти 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 і узгоджується з метриками від GenAI-сервісів поза OpenClaw.

​
Вибір між експортом Prometheus і OpenTelemetry

OpenClaw підтримує обидві поверхні незалежно. Ви можете запускати будь-яку з них, обидві або жодну.
  • Модель Pull: Prometheus збирає /api/diagnostics/prometheus.
  • Зовнішній collector не потрібен.
  • Автентифікація через звичайну автентифікацію Gateway.
  • Поверхня містить лише метрики (без трас або журналів).
  • Найкраще для стеків, уже стандартизованих на Prometheus + Grafana.

​
Усунення несправностей

  • Перевірте diagnostics.enabled: true у конфігурації.
  • Переконайтеся, що Plugin увімкнено й завантажено за допомогою openclaw plugins list --enabled.
  • Згенеруйте трохи трафіку; лічильники та гістограми виводять рядки лише після принаймні однієї події.
Кінцева точка потребує області оператора Gateway (auth: "gateway" із gatewayRuntimeScopeSurface: "trusted-operator"). Використовуйте той самий токен або пароль, який Prometheus використовує для будь-якого іншого маршруту оператора Gateway. Публічного режиму без автентифікації немає.
Новий атрибут перевищує обмеження у 2048 серій. Перевірте нещодавні метрики на наявність мітки з неочікувано високою кардинальністю та виправте це в джерелі. Експортер навмисно відкидає нові серії замість тихого переписування міток.
Plugin зберігає стан лише в пам’яті. Після перезапуску Gateway лічильники скидаються до нуля, а gauges перезапускаються з наступного повідомленого значення. Використовуйте PromQL rate() і increase(), щоб коректно обробляти скидання.

​
Пов’язане