Перейти до основного вмісту

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

​
Швидкий старт

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

Надішліть ту саму автентифікацію 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_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_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_tool_execution_totalcountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
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_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_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramнемає
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounterнемає

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

Мітки Prometheus залишаються обмеженими та з низькою кардинальністю. Експортер не видає сирі діагностичні ідентифікатори, як-от runId, sessionKey, sessionId, callId, toolCallId, ідентифікатори повідомлень, ідентифікатори чатів або ідентифікатори запитів провайдера.Значення міток редагуються та мають відповідати політиці OpenClaw щодо символів із низькою кардинальністю. Значення, які не відповідають політиці, замінюються на unknown, other або none, залежно від метрики.
Експортер обмежує збережені часові ряди в пам’яті 2048 рядами сукупно для лічильників, вимірювачів і гістограм. Нові ряди понад це обмеження відкидаються, а openclaw_prometheus_series_dropped_total збільшується на одиницю щоразу.Відстежуйте цей лічильник як чіткий сигнал, що атрибут вище за потоком пропускає значення з високою кардинальністю. Експортер ніколи не підвищує обмеження автоматично; якщо лічильник зростає, виправте джерело, а не вимикайте обмеження.
  • текст промпта, текст відповіді, вхідні дані інструментів, вихідні дані інструментів, системні промпти
  • стенограми розмов, аудіо payloads, ідентифікатори викликів, ідентифікатори кімнат, токени передавання, ідентифікатори ходів і необроблені ідентифікатори сеансів
  • необроблені ідентифікатори запитів провайдера (лише обмежені хеші, де застосовно, на 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

# 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.
  • Зовнішній колектор не потрібен.
  • Автентифікація через звичайну автентифікацію Gateway.
  • Поверхня містить лише метрики (без трасувань або логів).
  • Найкраще підходить для стеків, уже стандартизованих на Prometheus + Grafana.

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

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

​
Пов’язане