Перейти к основному содержанию
OpenClaw может предоставлять диагностические метрики через официальный плагин 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

Установите плагин

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

Включите плагин

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

Перезапустите Gateway

HTTP-маршрут регистрируется при запуске плагина, поэтому перезагрузите Gateway после включения.
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 в зависимости от метрики. Метки, похожие на ключи сессий агентов с областью действия, также заменяются на unknown.
Экспортер ограничивает удерживаемые в памяти временные ряды суммарно 2048 рядами для счетчиков, измерителей и гистограмм. Новые ряды сверх этого лимита отбрасываются, а openclaw_prometheus_series_dropped_total каждый раз увеличивается на единицу.Отслеживайте этот счетчик как строгий сигнал о том, что какой-то вышестоящий атрибут пропускает значения с высокой кардинальностью. Экспортер никогда не снимает лимит автоматически; если счетчик растет, исправьте источник, а не отключайте лимит.
  • текст промпта, текст ответа, входные данные инструментов, выходные данные инструментов, системные промпты
  • расшифровки Talk, аудиоданные, идентификаторы звонков, идентификаторы комнат, токены передачи, идентификаторы ходов и необработанные идентификаторы сеансов
  • необработанные идентификаторы запросов провайдера (только ограниченные хэши, где применимо, в спанах — никогда в метриках)
  • ключи сеансов и идентификаторы сеансов
  • имена хостов, пути к файлам, секретные значения

​
Рецепты 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.
  • Внешний коллектор не требуется.
  • Аутентификация выполняется через обычную аутентификацию 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(), чтобы корректно обрабатывать сбросы.

​
Связанные материалы