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,  },}

CLI

bash

openclaw plugins enable diagnostics-prometheus

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

HTTP-маршрут регистрируется при запуске плагина, поэтому после включения выполните перезапуск.

Соберите метрики с защищённого маршрута

Передайте те же данные аутентификации Gateway, которые используют ваши операторские клиенты:

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`, `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_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`	датчик	нет

Политика меток

Ограниченные метки с низкой кардинальностью

Метки Prometheus остаются ограниченными и низкокардинальными. Экспортер не выводит необработанные диагностические идентификаторы, такие как runId, sessionKey, sessionId, callId, toolCallId, идентификаторы сообщений, чатов или запросов к провайдеру.

Значения меток редактируются и должны соответствовать политике OpenClaw для низкокардинальных символов. Значения, не соответствующие политике, заменяются на unknown, other или none в зависимости от метрики. Метки, похожие на ключи сеансов агентов с областью действия, также заменяются на unknown.

Ограничение рядов и учет переполнения

Экспортер ограничивает количество временных рядов, хранящихся в памяти, до 2048 суммарно для счетчиков, индикаторов и гистограмм. Новые ряды сверх этого ограничения отбрасываются, а openclaw_prometheus_series_dropped_total каждый раз увеличивается на единицу.

Отслеживайте этот счетчик как однозначный признак того, что вышестоящий атрибут пропускает значения с высокой кардинальностью. Экспортер никогда не снимает ограничение автоматически; если счетчик растет, исправьте источник, а не отключайте ограничение.

Что никогда не появляется в выводе Prometheus

текст запросов, текст ответов, входные данные инструментов, выходные данные инструментов, системные запросы
расшифровки разговоров, аудиоданные, идентификаторы вызовов, идентификаторы комнат, токены передачи, идентификаторы ходов и необработанные идентификаторы сеансов
необработанные идентификаторы запросов к провайдеру (только ограниченные хеши, где применимо, в интервалах — никогда в метриках)
ключи и идентификаторы сеансов
имена хостов, пути к файлам, значения секретов

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

diagnostics-otel

Модель отправки: OpenClaw отправляет данные по OTLP/HTTP сборщику или совместимому с OTLP серверу.
Интерфейс включает метрики, трассировки и журналы.
При необходимости использовать оба варианта обеспечивает интеграцию с Prometheus через OpenTelemetry Collector (экспортер prometheus или prometheusremotewrite).
Полный каталог см. в разделе Экспорт OpenTelemetry.

Устранение неполадок

Пустое тело ответа

Убедитесь, что в конфигурации параметр diagnostics.enabled не имеет значения false (по умолчанию используется true).
Подтвердите с помощью openclaw plugins list --enabled, что плагин включен и загружен.
Создайте некоторый трафик: счетчики и гистограммы начинают выводить строки только после хотя бы одного события.

401 / нет авторизации

Конечная точка требует область полномочий оператора Gateway (auth: "gateway" с gatewayRuntimeScopeSurface: "trusted-operator"). Используйте тот же токен или пароль, который Prometheus использует для любого другого маршрута оператора Gateway. Общедоступного режима без аутентификации нет.

`openclaw_prometheus_series_dropped_total` растет

Новый атрибут превышает ограничение в 2048 рядов. Проверьте последние метрики на наличие метки с неожиданно высокой кардинальностью и исправьте ее в источнике. Экспортер намеренно отбрасывает новые ряды вместо неявного перезаписывания меток.

После перезапуска Prometheus показывает устаревшие ряды

Плагин хранит состояние только в памяти. После перезапуска Gateway счетчики сбрасываются до нуля, а индикаторы возобновляют работу со следующего переданного значения. Используйте в PromQL rate() и increase(), чтобы корректно обрабатывать сбросы.

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

Экспорт диагностики — локальный ZIP-архив диагностики для пакетов поддержки
Работоспособность и готовность — пробы /healthz и /readyz
Ведение журналов — ведение журналов в файлах
Экспорт OpenTelemetry — отправка по OTLP трассировок, метрик и журналов

Was this useful?

Метрики Prometheus

Быстрый старт

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

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

Конфигурация

CLI

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

Соберите метрики с защищённого маршрута

Подключите Prometheus

Экспортируемые метрики

Политика меток

Рецепты PromQL

Выбор между экспортом Prometheus и OpenTelemetry

diagnostics-prometheus

diagnostics-otel

Устранение неполадок

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

On this page

Molty