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

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

1

Увімкніть Plugin

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

Перезапустіть Gateway

HTTP-маршрут реєструється під час запуску Plugin, тому після ввімкнення виконайте перезавантаження.
3

Налаштуйте скрейпінг захищеного маршруту

Передайте ту саму автентифікацію gateway, яку використовують ваші клієнти operator:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
4

Підключіть 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_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

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

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

​
Рецепти PromQL

# Токени за хвилину, з розбиттям за provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Витрати (USD) за останню годину, за model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95-й перцентиль тривалості виконання model
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO часу очікування в черзі (95p менше 2 с)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Відкинуті серії Prometheus (тривога кардинальності)
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.
  • Згенеруйте певний трафік; counter і histogram починають виводити рядки лише після принаймні однієї події.
Кінцева точка вимагає область operator Gateway (auth: "gateway" з gatewayRuntimeScopeSurface: "trusted-operator"). Використовуйте той самий токен або пароль, який Prometheus використовує для будь-якого іншого маршруту operator Gateway. Публічного неавтентифікованого режиму немає.
Новий атрибут перевищує ліміт у 2048 серій. Перевірте нещодавні метрики на наявність мітки з неочікувано високою кардинальністю та виправте це в джерелі. Експортер навмисно відкидає нові серії замість тихого переписування міток.
Plugin зберігає стан лише в пам’яті. Після перезапуску Gateway counter скидаються до нуля, а gauge починаються з наступного повідомленого значення. Використовуйте в PromQL rate() і increase(), щоб коректно обробляти скидання.

​
Пов’язане