Métricas de Prometheus

OpenClaw puede exponer métricas de diagnóstico mediante el plugin oficial diagnostics-prometheus. Este escucha diagnósticos de confianza, además de eventos de diagnóstico etiquetados internamente y gestionados por el despachador (señales de cola, memoria y recuperación de sesiones), y presenta un endpoint de texto de Prometheus en:

GET /api/diagnostics/prometheus

El tipo de contenido es text/plain; version=0.0.4; charset=utf-8, el formato estándar de exposición de Prometheus.

La ruta utiliza la autenticación del Gateway (ámbito de operador, superficie para operadores de confianza). No la exponga como un endpoint /metrics público sin autenticación. Recopile sus datos mediante la misma ruta de autenticación que utiliza para las demás API de operador.

Para trazas, registros, envío mediante OTLP y atributos semánticos de IA generativa de OpenTelemetry, consulte Exportación de OpenTelemetry.

Inicio rápido

Instalar el plugin

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

Habilitar el plugin

Configuración
CLI

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

openclaw plugins enable diagnostics-prometheus

Reiniciar el Gateway

La ruta HTTP se registra al iniciar el plugin, por lo que debe volver a cargarlo después de habilitarlo.

Recopilar datos de la ruta protegida

Envíe la misma autenticación del Gateway que utilizan sus clientes de operador:

curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus

Conectar 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"]

El valor predeterminado de diagnostics.enabled es true; establézcalo en false únicamente en entornos estrictamente restringidos. Si es false, el plugin continúa registrando la ruta HTTP, pero ningún evento de diagnóstico llega al exportador, por lo que la respuesta está vacía.

Métricas exportadas

Métrica	Tipo	Etiquetas
`openclaw_run_completed_total`	contador	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_run_duration_seconds`	histograma	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_model_call_total`	contador	`api`, `error_category`, `model`, `observation_unit`, `outcome`, `provider`, `transport`
`openclaw_model_call_duration_seconds`	histograma	`api`, `error_category`, `model`, `observation_unit`, `outcome`, `provider`, `transport`
`openclaw_model_failover_total`	contador	`from_model`, `from_provider`, `lane`, `reason`, `suspended`, `to_model`, `to_provider`
`openclaw_model_tokens_total`	contador	`agent`, `channel`, `model`, `provider`, `token_type`
`openclaw_gen_ai_client_token_usage`	histograma	`model`, `provider`, `token_type`
`openclaw_model_cost_usd_total`	contador	`agent`, `channel`, `model`, `provider`
`openclaw_model_usage_duration_seconds`	histograma	`agent`, `channel`, `model`, `provider`
`openclaw_skill_used_total`	contador	`activation`, `agent`, `skill`, `source`
`openclaw_tool_execution_total`	contador	`error_category`, `outcome`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_tool_execution_duration_seconds`	histograma	`error_category`, `outcome`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_tool_execution_blocked_total`	contador	`denied_reason`, `params_kind`, `tool`, `tool_owner`, `tool_source`
`openclaw_harness_run_total`	contador	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_harness_run_duration_seconds`	histograma	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_webhook_received_total`	contador	`channel`, `webhook`
`openclaw_webhook_error_total`	contador	`channel`, `webhook`
`openclaw_webhook_duration_seconds`	histograma	`channel`, `webhook`
`openclaw_message_received_total`	contador	`channel`, `source`
`openclaw_message_dispatch_started_total`	contador	`channel`, `source`
`openclaw_message_dispatch_completed_total`	contador	`channel`, `outcome`, `reason`, `source`
`openclaw_message_dispatch_duration_seconds`	histograma	`channel`, `outcome`, `reason`, `source`
`openclaw_message_processed_total`	contador	`channel`, `outcome`, `reason`
`openclaw_message_processed_duration_seconds`	histograma	`channel`, `outcome`, `reason`
`openclaw_message_delivery_started_total`	contador	`channel`, `delivery_kind`
`openclaw_message_delivery_total`	contador	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_message_delivery_duration_seconds`	histograma	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_talk_event_total`	contador	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_event_duration_seconds`	histograma	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_audio_bytes`	histograma	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_queue_lane_size`	indicador	`lane`
`openclaw_queue_lane_wait_seconds`	histograma	`lane`
`openclaw_session_state_total`	contador	`reason`, `state`
`openclaw_session_queue_depth`	indicador	`state`
`openclaw_session_turn_created_total`	contador	`agent`, `channel`, `trigger`
`openclaw_session_stuck_total`	contador	`reason`, `state`
`openclaw_session_stuck_age_seconds`	histograma	`reason`, `state`
`openclaw_session_recovery_total`	contador	`action`, `active_work_kind`, `state`, `status`
`openclaw_session_recovery_age_seconds`	histograma	`action`, `active_work_kind`, `state`, `status`
`openclaw_liveness_warning_total`	contador	`reason`
`openclaw_liveness_sessions`	indicador	`state`
`openclaw_liveness_event_loop_delay_p99_seconds`	histograma	`reason`
`openclaw_liveness_event_loop_delay_max_seconds`	histograma	`reason`
`openclaw_liveness_event_loop_utilization_ratio`	histograma	`reason`
`openclaw_liveness_cpu_core_ratio`	histograma	`reason`
`openclaw_payload_large_total`	contador	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_payload_large_bytes`	histograma	`action`, `channel`, `plugin`, `reason`, `surface`
`openclaw_memory_bytes`	indicador	`kind`
`openclaw_memory_rss_bytes`	histograma	ninguna
`openclaw_memory_pressure_total`	contador	`level`, `reason`
`openclaw_telemetry_exporter_total`	contador	`exporter`, `reason`, `signal`, `status`
`openclaw_prometheus_series_dropped_total`	contador	ninguna
`openclaw_diagnostic_async_queue_dropped_total`	contador	`drop_class`
`openclaw_diagnostic_async_queue_length`	indicador	ninguna

Para las métricas de llamadas al modelo, observation_unit="request" mide una solicitud observable al proveedor. observation_unit="turn" mide un turno sintético del agente de Claude Code o Codex CLI que puede contener varias solicitudes ocultas al proveedor. Mantenga esas series separadas al comparar la latencia.

Política de etiquetas

Etiquetas acotadas y de baja cardinalidad

Las etiquetas de Prometheus se mantienen acotadas y con baja cardinalidad. El exportador no emite identificadores de diagnóstico sin procesar, como runId, sessionKey, sessionId, callId, toolCallId, identificadores de mensajes, identificadores de chats ni identificadores de solicitudes al proveedor.Los valores de las etiquetas se ocultan y deben cumplir la política de caracteres de baja cardinalidad de OpenClaw. Los valores que no cumplen la política se sustituyen por unknown, other o none, según la métrica. Las etiquetas que parecen claves de sesión de agente con ámbito también se sustituyen por unknown.

Límite de series y contabilización del desbordamiento

El exportador limita las series temporales conservadas en memoria a 2048 en total entre contadores, indicadores e histogramas. Las nuevas series que superan ese límite se descartan y openclaw_prometheus_series_dropped_total aumenta en uno cada vez.Supervise este contador como una señal inequívoca de que algún atributo anterior está filtrando valores de alta cardinalidad. El exportador nunca eleva el límite automáticamente; si el contador aumenta, corrija el origen en lugar de desactivar el límite.

Lo que nunca aparece en la salida de Prometheus

texto de la solicitud, texto de la respuesta, entradas de herramientas, salidas de herramientas, solicitudes del sistema
transcripciones de conversaciones, cargas útiles de audio, identificadores de llamadas, identificadores de salas, tokens de transferencia, identificadores de turnos e identificadores de sesión sin procesar
identificadores de solicitudes al proveedor sin procesar (solo hashes acotados, cuando corresponda, en los intervalos; nunca en las métricas)
claves de sesión e identificadores de sesión
nombres de host, rutas de archivos, valores secretos

Recetas de PromQL

# Tokens por minuto, separados por proveedor
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Gasto (USD) durante la última hora, por modelo
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# Percentil 95 de la duración de ejecución del modelo
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO del tiempo de espera en cola (percentil 95 inferior a 2 s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Uso de Skills, separado por origen acotado
sum by (skill, source) (increase(openclaw_skill_used_total[24h]))

# Series de Prometheus descartadas (alarma de cardinalidad)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0

Prefiera gen_ai_client_token_usage para paneles entre proveedores: sigue las convenciones semánticas de GenAI de OpenTelemetry y es coherente con las métricas de servicios GenAI ajenos a OpenClaw.

Elección entre la exportación de Prometheus y OpenTelemetry

OpenClaw admite ambas superficies de forma independiente. Puede ejecutar una, ambas o ninguna.

diagnostics-prometheus
diagnostics-otel

Modelo de extracción: Prometheus consulta /api/diagnostics/prometheus.
No se requiere ningún recopilador externo.
Se autentica mediante la autenticación normal del Gateway.
La superficie incluye solo métricas (sin trazas ni registros).
La mejor opción para pilas ya estandarizadas en Prometheus + Grafana.

Modelo de envío: OpenClaw envía OTLP/HTTP a un recopilador o backend compatible con OTLP.
La superficie incluye métricas, trazas y registros.
Se integra con Prometheus mediante un OpenTelemetry Collector (exportador prometheus o prometheusremotewrite) cuando se necesitan ambos.
Consulte Exportación de OpenTelemetry para ver el catálogo completo.

Solución de problemas

Cuerpo de respuesta vacío

Compruebe que diagnostics.enabled no esté establecido en false en la configuración (el valor predeterminado es true).
Confirme que el Plugin esté habilitado y cargado con openclaw plugins list --enabled.
Genere algo de tráfico; los contadores y los histogramas solo emiten líneas después de al menos un evento.

401 / no autorizado

El endpoint requiere el ámbito de operador del Gateway (auth: "gateway" con gatewayRuntimeScopeSurface: "trusted-operator"). Utilice el mismo token o contraseña que Prometheus usa para cualquier otra ruta de operador del Gateway. No hay ningún modo público sin autenticación.

`openclaw_prometheus_series_dropped_total` está aumentando

Un atributo nuevo está superando el límite de 2048 series. Inspeccione las métricas recientes para detectar una etiqueta con una cardinalidad inesperadamente alta y corríjala en el origen. El exportador descarta intencionadamente las series nuevas en lugar de reescribir las etiquetas de forma silenciosa.

Prometheus muestra series obsoletas después de un reinicio

El Plugin mantiene el estado únicamente en memoria. Después de reiniciar el Gateway, los contadores vuelven a cero y los indicadores se reinician con su siguiente valor notificado. Utilice rate() y increase() de PromQL para gestionar correctamente los reinicios.

Contenido relacionado

Exportación de diagnósticos — archivo zip de diagnósticos locales para paquetes de soporte
Estado y disponibilidad — sondas /healthz y /readyz
Registro — registro basado en archivos
Exportación de OpenTelemetry — envío OTLP de trazas, métricas y registros

Gateway

Remote access

Security

Nodes and media

Web interfaces

Métricas de Prometheus

Inicio rápido

Métricas exportadas

Política de etiquetas

Recetas de PromQL

Elección entre la exportación de Prometheus y OpenTelemetry

Solución de problemas

Contenido relacionado

​Inicio rápido

​Métricas exportadas

​Política de etiquetas

​Recetas de PromQL

​Elección entre la exportación de Prometheus y OpenTelemetry

​Solución de problemas

​Contenido relacionado

Inicio rápido

Métricas exportadas

Política de etiquetas

Recetas de PromQL

Elección entre la exportación de Prometheus y OpenTelemetry

Solución de problemas

Contenido relacionado