Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
La ruta usa autenticación del Gateway (ámbito de operador). No la expongas como un endpoint /metrics público sin autenticación. Haz scraping a través de la misma ruta de autenticación que usas para otras API de operador.
Para trazas, registros, push OTLP y atributos semánticos GenAI de OpenTelemetry, consulta exportación de OpenTelemetry.

​
Inicio rápido

1

Instala el Plugin

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

Habilita el Plugin

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

Reinicia el Gateway

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

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
5

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"]
diagnostics.enabled: true es obligatorio. Sin ello, el Plugin aún registra la ruta HTTP, pero no fluye ningún evento de diagnóstico al exportador, por lo que la respuesta está vacía.

​
Métricas exportadas

MétricaTipoEtiquetas
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_started_totalcounterchannel, delivery_kind
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcounterbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramninguna
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounterninguna

​
Política de etiquetas

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.
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.
  • 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
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 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 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.

​
Solución de problemas

  • 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.
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.
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.
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