Saltar al contenido principal
OpenClaw puede exponer métricas de diagnóstico mediante el Plugin incluido diagnostics-prometheus. Escucha diagnósticos internos de confianza y genera 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 (alcance de operador). No la expongas como un endpoint público /metrics sin autenticación. Haz el scraping a través de la misma ruta de autenticación que usas para otras APIs de operador.
Para trazas, logs, envío OTLP y atributos semánticos GenAI de OpenTelemetry, consulta Exportación de OpenTelemetry.

​
Inicio rápido

1

Habilita el Plugin

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

Reinicia el Gateway

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

Haz scraping de la ruta protegida

Envía la misma autenticación de gateway que usan tus clientes operadores:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
4

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 él, el Plugin sigue registrando la ruta HTTP pero no fluye ningún evento de diagnóstico al exportador, por lo que la respuesta queda 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_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

​
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, IDs de mensaje, IDs de chat ni IDs de solicitud del proveedor.Los valores de las etiquetas se redactan y deben cumplir la política de caracteres de baja cardinalidad de OpenClaw. Los valores que no cumplan la política se sustituyen por unknown, other o none, según la métrica.
El exportador limita las series temporales retenidas en memoria a 2048 series entre contadores, gauges e histogramas combinados. Las nuevas series que superen ese límite se descartan, y openclaw_prometheus_series_dropped_total aumenta en uno cada vez.Supervisa este contador como una señal fuerte de que un atributo aguas arriba está filtrando valores de alta cardinalidad. El exportador nunca eleva el límite automáticamente; si sube, 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
  • IDs sin procesar de solicitudes del proveedor (solo hashes acotados, cuando corresponde, 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 por minuto, divididos 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 duración de ejecución del modelo
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO de tiempo de espera de cola (95p por debajo de 2 s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Series descartadas de Prometheus (alarma de cardinalidad)
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 ajenos a OpenClaw.

​
Elegir entre Prometheus y la exportación de OpenTelemetry

OpenClaw admite ambas superficies de forma independiente. Puedes usar una, ambas o ninguna.
  • Modelo pull: Prometheus hace scraping de /api/diagnostics/prometheus.
  • No se requiere un recopilador externo.
  • Autenticado mediante la autenticación normal del Gateway.
  • La superficie es solo de métricas (sin trazas ni logs).
  • 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á 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 use para cualquier otra ruta de operador del Gateway. No existe un modo público sin autenticación.
Un nuevo atributo está superando el límite de 2048 series. Inspecciona las métricas recientes en busca de una etiqueta con cardinalidad inesperadamente alta y corrígela en el origen. El exportador descarta intencionadamente las series nuevas en lugar de reescribir etiquetas en silencio.
El Plugin mantiene el estado solo en memoria. Tras un reinicio del Gateway, los contadores vuelven a cero y los gauges se reinician en su siguiente valor informado. Usa rate() e increase() en PromQL para manejar los reinicios limpiamente.

​
Relacionado