Saltar al contenido principal
OpenClaw puede exponer métricas de diagnóstico mediante el plugin oficial diagnostics-prometheus. Escucha diagnósticos de confianza, además de eventos de diagnóstico etiquetados internamente y propiedad del despachador (señales de cola, memoria y recuperación de sesión), 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.
La ruta usa autenticación de Gateway (alcance de operador, superficie de operador de confianza). No la expongas como un endpoint /metrics público sin autenticación. Recopílala mediante la misma ruta de autenticación que usas para otras API de operador.
Para trazas, registros, envío OTLP y atributos semánticos GenAI de OpenTelemetry, consulta Exportación de OpenTelemetry.

​
Inicio rápido

1

Instalar el plugin

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

Habilitar el plugin

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

Reiniciar el Gateway

La ruta HTTP se registra al iniciar el plugin, así que vuelve a cargar después de habilitarlo.
4

Recopilar la ruta protegida

Envía la misma autenticación de gateway que usan tus 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"]
diagnostics.enabled tiene el valor predeterminado true; establécelo en false solo en entornos muy restringidos. Si es false, el plugin sigue registrando la ruta HTTP, pero no fluyen eventos de diagnóstico al exportador, por lo que la respuesta está vacía.

​
Métricas exportadas

MétricaTipoEtiquetas
openclaw_run_completed_totalcontadorchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramachannel, model, outcome, provider, trigger
openclaw_model_call_totalcontadorapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramaapi, error_category, model, outcome, provider, transport
openclaw_model_failover_totalcontadorfrom_model, from_provider, lane, reason, suspended, to_model, to_provider
openclaw_model_tokens_totalcontadoragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogramamodel, provider, token_type
openclaw_model_cost_usd_totalcontadoragent, channel, model, provider
openclaw_model_usage_duration_secondshistogramaagent, channel, model, provider
openclaw_skill_used_totalcontadoractivation, agent, skill, source
openclaw_tool_execution_totalcontadorerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_duration_secondshistogramaerror_category, outcome, params_kind, tool, tool_owner, tool_source
openclaw_tool_execution_blocked_totalcontadordenied_reason, params_kind, tool, tool_owner, tool_source
openclaw_harness_run_totalcontadorchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramachannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_webhook_received_totalcontadorchannel, webhook
openclaw_webhook_error_totalcontadorchannel, webhook
openclaw_webhook_duration_secondshistogramachannel, webhook
openclaw_message_received_totalcontadorchannel, source
openclaw_message_dispatch_started_totalcontadorchannel, source
openclaw_message_dispatch_completed_totalcontadorchannel, outcome, reason, source
openclaw_message_dispatch_duration_secondshistogramachannel, outcome, reason, source
openclaw_message_processed_totalcontadorchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramachannel, outcome, reason
openclaw_message_delivery_started_totalcontadorchannel, delivery_kind
openclaw_message_delivery_totalcontadorchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramachannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcontadorbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogramabrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogramabrain, event_type, mode, provider, transport
openclaw_queue_lane_sizeindicadorlane
openclaw_queue_lane_wait_secondshistogramalane
openclaw_session_state_totalcontadorreason, state
openclaw_session_queue_depthindicadorstate
openclaw_session_turn_created_totalcontadoragent, channel, trigger
openclaw_session_stuck_totalcontadorreason, state
openclaw_session_stuck_age_secondshistogramareason, state
openclaw_session_recovery_totalcontadoraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaaction, active_work_kind, state, status
openclaw_liveness_warning_totalcontadorreason
openclaw_liveness_sessionsindicadorstate
openclaw_liveness_event_loop_delay_p99_secondshistogramareason
openclaw_liveness_event_loop_delay_max_secondshistogramareason
openclaw_liveness_event_loop_utilization_ratiohistogramareason
openclaw_liveness_cpu_core_ratiohistogramareason
openclaw_payload_large_totalcontadoraction, channel, plugin, reason, surface
openclaw_payload_large_byteshistogramaaction, channel, plugin, reason, surface
openclaw_memory_bytesindicadorkind
openclaw_memory_rss_byteshistogramanone
openclaw_memory_pressure_totalcontadorlevel, reason
openclaw_telemetry_exporter_totalcontadorexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcontadornone
openclaw_diagnostic_async_queue_dropped_totalcontadordrop_class
openclaw_diagnostic_async_queue_lengthindicadornone

​
Política de etiquetas

Las etiquetas de Prometheus se mantienen limitadas y de baja cardinalidad. El exportador no emite identificadores de diagnóstico sin procesar como runId, sessionKey, sessionId, callId, toolCallId, identificadores de mensajes, identificadores de chat ni identificadores de solicitudes de proveedores.Los valores de etiquetas 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 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.
El exportador limita las series temporales retenidas en memoria a 2048 series en total entre contadores, medidores e histogramas. Las series nuevas que superen ese límite se descartan, y openclaw_prometheus_series_dropped_total aumenta en uno cada vez.Vigila este contador como una señal firme de que un atributo aguas arriba está filtrando valores de alta cardinalidad. El exportador nunca eleva el límite automáticamente; si aumenta, corrige el origen en lugar de desactivar el límite.
  • texto de prompts, texto de respuestas, entradas de herramientas, salidas de herramientas, prompts del sistema
  • transcripciones de Talk, cargas de audio, ids de llamada, ids de sala, tokens de traspaso, ids de turno e ids de sesión sin procesar
  • ids de solicitud del proveedor sin procesar (solo hashes acotados, 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

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

​
Elegir entre la exportación de Prometheus y OpenTelemetry

OpenClaw admite ambas superficies de forma independiente. Puedes ejecutar una, ambas o ninguna.
  • Modelo pull: Prometheus recopila /api/diagnostics/prometheus.
  • No requiere recopilador externo.
  • Autenticado mediante la autenticación normal del Gateway.
  • La superficie solo incluye métricas (sin trazas ni logs).
  • Ideal para stacks ya estandarizados en Prometheus + Grafana.

​
Solución de problemas

  • Comprueba que diagnostics.enabled no esté establecido en false en la configuración (su valor predeterminado es true).
  • Confirma que el plugin esté habilitado 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.
El endpoint requiere el alcance de operador del Gateway (auth: "gateway" con gatewayRuntimeScopeSurface: "trusted-operator"). Usa el mismo token o contraseña que Prometheus usa para cualquier otra ruta de operador del Gateway. No hay modo público sin autenticación.
Un atributo nuevo está superando el límite de 2048 series. Inspecciona las métricas recientes para encontrar una etiqueta con cardinalidad inesperadamente alta y corrígela en el origen. El exportador descarta intencionadamente las series nuevas en lugar de reescribir etiquetas silenciosamente.
El plugin mantiene el estado solo en memoria. Después de un reinicio del Gateway, los contadores se restablecen a cero y los medidores se reinician en el siguiente valor que reporten. Usa rate() e increase() de PromQL para manejar los reinicios limpiamente.

​
Relacionado