Gateway

Métricas de Prometheus

OpenClaw puede exponer métricas de diagnóstico mediante el Plugin oficial diagnostics-prometheus. Escucha diagnósticos internos de confianza y representa 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.

Para trazas, registros, push OTLP y atributos semánticos GenAI de OpenTelemetry, consulta exportación de OpenTelemetry.

Inicio rápido

Instala el Plugin

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

Habilita el Plugin

Configuración

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

CLI

openclaw plugins enable diagnostics-prometheus

Reinicia el Gateway

La ruta HTTP se registra al iniciar el Plugin, así que recarga después de habilitarlo.

Haz scraping de la ruta protegida

Envía la misma autenticación del gateway que usan tus clientes de operador:

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

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

Métricas exportadas

Métrica	Tipo	Etiquetas
`openclaw_run_completed_total`	counter	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_run_duration_seconds`	histogram	`channel`, `model`, `outcome`, `provider`, `trigger`
`openclaw_model_call_total`	counter	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_call_duration_seconds`	histogram	`api`, `error_category`, `model`, `outcome`, `provider`, `transport`
`openclaw_model_tokens_total`	counter	`agent`, `channel`, `model`, `provider`, `token_type`
`openclaw_gen_ai_client_token_usage`	histogram	`model`, `provider`, `token_type`
`openclaw_model_cost_usd_total`	counter	`agent`, `channel`, `model`, `provider`
`openclaw_tool_execution_total`	counter	`error_category`, `outcome`, `params_kind`, `tool`
`openclaw_tool_execution_duration_seconds`	histogram	`error_category`, `outcome`, `params_kind`, `tool`
`openclaw_harness_run_total`	counter	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_harness_run_duration_seconds`	histogram	`channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider`
`openclaw_message_processed_total`	counter	`channel`, `outcome`, `reason`
`openclaw_message_processed_duration_seconds`	histogram	`channel`, `outcome`, `reason`
`openclaw_message_delivery_started_total`	counter	`channel`, `delivery_kind`
`openclaw_message_delivery_total`	counter	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_message_delivery_duration_seconds`	histogram	`channel`, `delivery_kind`, `error_category`, `outcome`
`openclaw_talk_event_total`	counter	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_event_duration_seconds`	histogram	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_talk_audio_bytes`	histogram	`brain`, `event_type`, `mode`, `provider`, `transport`
`openclaw_queue_lane_size`	gauge	`lane`
`openclaw_queue_lane_wait_seconds`	histogram	`lane`
`openclaw_session_state_total`	counter	`reason`, `state`
`openclaw_session_queue_depth`	gauge	`state`
`openclaw_session_recovery_total`	counter	`action`, `active_work_kind`, `state`, `status`
`openclaw_session_recovery_age_seconds`	histogram	`action`, `active_work_kind`, `state`, `status`
`openclaw_memory_bytes`	gauge	`kind`
`openclaw_memory_rss_bytes`	histogram	ninguna
`openclaw_memory_pressure_total`	counter	`level`, `reason`
`openclaw_telemetry_exporter_total`	counter	`exporter`, `reason`, `signal`, `status`
`openclaw_prometheus_series_dropped_total`	counter	ninguna

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, ID de mensajes, ID de chat o ID de solicitud del proveedor.

Los valores de etiqueta se redactan y deben coincidir con la política de caracteres de baja cardinalidad de OpenClaw. Los valores que no cumplen la política se reemplazan por unknown, other o none, según la métrica.

Límite de series y contabilización del desbordamiento

El exportador limita las series temporales retenidas en memoria a 2048 series entre contadores, medidores e histogramas combinados. Las nuevas series que superan ese límite se descartan, y openclaw_prometheus_series_dropped_total aumenta en uno cada vez.

Vigila este contador como una señal clara de que un atributo aguas arriba está filtrando valores de alta cardinalidad. El exportador nunca aumenta el límite automáticamente; si sube, corrige el origen en lugar de desactivar el límite.

Lo que nunca aparece en la salida de Prometheus

texto de prompt, texto de respuesta, entradas de herramientas, salidas de herramientas, prompts del sistema
Transcripciones de Talk, cargas de audio, id. de llamadas, id. de salas, tokens de traspaso, id. de turnos e id. de sesión sin procesar
id. de solicitud del proveedor sin procesar (solo hashes acotados, cuando corresponda, en spans; nunca en métricas)
claves de sesión e id. de sesión
nombres de host, rutas de archivo, valores secretos

Recetas de 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

Elegir entre exportación de Prometheus y OpenTelemetry

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

diagnostics-prometheus

Modelo pull: Prometheus recopila /api/diagnostics/prometheus.
No se requiere recopilador externo.
Autenticado mediante la autenticación normal de Gateway.
La superficie es solo de métricas (sin trazas ni registros).
Ideal para stacks ya estandarizados en Prometheus + Grafana.

diagnostics-otel

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

Solución de problemas

Cuerpo de respuesta vacío

Comprueba diagnostics.enabled: true en la configuración.
Confirma que el plugin esté activado y cargado con openclaw plugins list --enabled.
Genera algo de tráfico; los contadores e histogramas solo emiten líneas después de al menos un evento.

401 / no autorizado

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

`openclaw_prometheus_series_dropped_total` está subiendo

Un atributo nuevo está superando el límite de 2048 series. Inspecciona las métricas recientes en busca de una etiqueta de cardinalidad inesperadamente alta y corrígela en el origen. El exportador descarta intencionadamente las nuevas series en lugar de reescribir etiquetas silenciosamente.

Prometheus muestra series obsoletas después de un reinicio

El plugin mantiene el estado solo en memoria. Después de reiniciar Gateway, los contadores se restablecen a cero y los medidores se reinician en su siguiente valor informado. Usa rate() e increase() de PromQL para gestionar los restablecimientos correctamente.

Relacionado

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

# Inicio rápido

Instala el Plugin

Habilita el Plugin

Configuración

CLI

Reinicia el Gateway

Haz scraping de la ruta protegida

Conecta Prometheus

# Métricas exportadas

# Política de etiquetas

# Recetas de PromQL

# Elegir entre exportación de Prometheus y OpenTelemetry

diagnostics-prometheus

diagnostics-otel

# Solución de problemas

# Relacionado

Inicio rápido

Métricas exportadas

Política de etiquetas

Recetas de PromQL

Elegir entre exportación de Prometheus y OpenTelemetry

Solución de problemas

Relacionado