Métricas de Prometheus

OpenClaw puede exponer métricas de diagnóstico a través del complemento oficial diagnostics-prometheus. Escucha los diagnósticos internos de confianza y representa un punto final 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 de exposición estándar de Prometheus.

Warning

La ruta utiliza la autenticación de Gateway (ámbito de operador). No la exponga como un punto final

/metrics

público sin autenticar. Extráigala a través de la misma ruta de autenticación que utiliza para otras API de operador.

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

Inicio rápido

1. Instalar el complemento

   openclaw plugins install clawhub:@openclaw/diagnostics-prometheus

2. Habilitar el complemento

   ConfigCLI

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

   openclaw plugins enable diagnostics-prometheus

3. Reiniciar el Gateway

   La ruta HTTP se registra al inicio del complemento, por lo que debe recargar después de habilitarlo.

4. Extraer la ruta protegida

   Envíe la misma autenticación de puerta de enlace que utilizan sus clientes de operador:

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

5. 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"]

Note

diagnostics.enabled: true

es obligatorio. Sin él, el complemento sigue registrando la ruta HTTP, pero ningún evento de diagnóstico fluye hacia el 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, outcome, provider, transport
openclaw_model_call_duration_seconds	histograma	api, error_category, model, outcome, provider, transport
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_tool_execution_total	contador	error_category, outcome, params_kind, tool
openclaw_tool_execution_duration_seconds	histograma	error_category, outcome, params_kind, tool
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_message_processed_total	contador	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	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	gauge	lane
openclaw_queue_lane_wait_seconds	histogram	lane
openclaw_session_state_total	counter	reason, state
openclaw_session_queue_depth	indicador	state
openclaw_session_recovery_total	counter	action, active_work_kind, state, status
openclaw_session_recovery_age_seconds	histograma	action, active_work_kind, state, status
openclaw_memory_bytes	indicador	kind
openclaw_memory_rss_bytes	histogram	ninguno
openclaw_memory_pressure_total	contador	level, reason
openclaw_telemetry_exporter_total	contador	exporter, reason, signal, status
openclaw_prometheus_series_dropped_total	contador	ninguno

Política de etiquetas

Etiquetas delimitadas y de baja cardinalidad

Las etiquetas de Prometheus se mantienen delimitadas y de baja cardinalidad. El exportador no emite identificadores de diagnóstico sin procesar, como runId, sessionKey, sessionId, callId, toolCallId, IDs de mensaje, IDs de chat o IDs de solicitud del proveedor.

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

Límite de series y contabilidad de desbordamiento

El exportador limita las series temporales retenidas en memoria a 2048 series en total entre contadores, indicadores e histogramas. Las series nuevas que superen ese límite se descartan y openclaw_prometheus_series_dropped_total se incrementa en una cada vez.

Vigile este contador como una señal fuerte de que un atributo aguas arriba está filtrando valores de alta cardinalidad. El exportador nunca elimina el límite automáticamente; si aumenta, solucione el origen en lugar de deshabilitar el límite.

Lo que nunca aparece en la salida de Prometheus

• texto del prompt, texto de respuesta, entradas de herramientas, salidas de herramientas, prompts del sistema
• transcripciones de Talk, cargas de audio, IDs de llamada, IDs de sala, tokens de transferencia, IDs de turno e IDs de sesión sin procesar
• IDs de solicitud de proveedor sin procesar (solo hash delimitados, cuando corresponda, en spans: nunca en métricas)
• claves de sesión e IDs 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

Tip

Se recomienda

gen_ai_client_token_usage

para paneles entre proveedores: sigue las convenciones semánticas de OpenTelemetry GenAI y es coherente con las métricas de servicios GenAI que no son de 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-prometheusdiagnostics-otel

• Modelo de extracción (Pull): Prometheus extrae /api/diagnostics/prometheus.
• No se requiere un recopilador externo.
• Autenticado a través de la autenticación normal de Gateway.
• La superficie es solo métricas (sin trazas ni registros).
• Lo mejor para pilas ya estandarizadas en Prometheus + Grafana.

• Modelo de inserción (Push): OpenClaw envía OTLP/HTTP a un recopilador o backend compatible con OTLP.
• La superficie incluye métricas, trazas y registros.
• Actúa como puente hacia Prometheus a través de un OpenTelemetry Collector (exportador prometheus o prometheusremotewrite) cuando necesita ambos.
• Consulte Exportación de OpenTelemetry para obtener el catálogo completo.

Solución de problemas

Cuerpo de respuesta vacío

• Compruebe diagnostics.enabled: true en la configuración.
• Confirme que el complemento esté habilitado y cargado con openclaw plugins list --enabled.
• Genere algo de tráfico; los contadores e histogramas solo emiten líneas después de al menos un evento.

401 / no autorizado

El punto final requiere el ámbito de operador de Gateway (auth: "gateway" con gatewayRuntimeScopeSurface: "trusted-operator"). Use el mismo token o contraseña que Prometheus usa para cualquier otra ruta de operador de Gateway. No existe un modo público no autenticado.

`openclaw_prometheus_series_dropped_total` está aumentando

Un nuevo atributo está superando el límite de 2048 series. Inspeccione las métricas recientes para encontrar una etiqueta de cardinalidad inesperadamente alta y corríjala en la fuente. El exportador descarta intencionalmente las nuevas series en lugar de reescribir las etiquetas silenciosamente.

Prometheus muestra series obsoletas después de un reinicio

El complemento mantiene el estado solo en la memoria. Después de reiniciar el Gateway, los contadores se restablecen a cero y los medidores se reinician en su siguiente valor informado. Use PromQL rate() y increase() para manejar los reinicios de manera limpia.

Relacionado

• Exportación de diagnósticos — archivo 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