Gateway

Exportación de OpenTelemetry

OpenClaw exporta diagnósticos mediante el plugin oficial diagnostics-otel con OTLP/HTTP (protobuf). Cualquier colector o backend que acepte OTLP/HTTP funciona sin cambios de código. Para los registros de archivos locales y cómo leerlos, consulta Registro.

Cómo encaja todo

Los eventos de diagnóstico son registros estructurados en proceso emitidos por el Gateway y los plugins incluidos para ejecuciones de modelo, flujo de mensajes, sesiones, colas y exec.
El plugin diagnostics-otel se suscribe a esos eventos y los exporta como métricas, trazas y registros de OpenTelemetry mediante OTLP/HTTP.
Las llamadas a proveedores reciben un encabezado W3C traceparent desde el contexto de span de llamada de modelo de confianza de OpenClaw cuando el transporte del proveedor acepta encabezados personalizados. El contexto de traza emitido por plugins no se propaga.
Los exportadores solo se adjuntan cuando tanto la superficie de diagnósticos como el plugin están habilitados, por lo que el costo en proceso se mantiene cerca de cero de forma predeterminada.

Inicio rápido

Para instalaciones empaquetadas, instala primero el plugin:

openclaw plugins install clawhub:@openclaw/diagnostics-otel

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
    },
  },
}

También puedes habilitar el plugin desde la CLI:

openclaw plugins enable diagnostics-otel

Señales exportadas

Señal	Qué contiene
Métricas	Contadores e histogramas para uso de tokens, costo, duración de ejecución, flujo de mensajes, eventos de Talk, carriles de cola, estado/recuperación de sesión, exec y presión de memoria.
Trazas	Spans para uso de modelos, llamadas de modelo, ciclo de vida del arnés, ejecución de herramientas, exec, procesamiento de webhook/mensajes, ensamblaje de contexto y bucles de herramientas.
Registros	Registros estructurados `logging.file` exportados mediante OTLP cuando `diagnostics.otel.logs` está habilitado.

Activa o desactiva traces, metrics y logs de forma independiente. Las tres están activadas de forma predeterminada cuando diagnostics.otel.enabled es true.

Referencia de configuración

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      tracesEndpoint: "http://otel-collector:4318/v1/traces",
      metricsEndpoint: "http://otel-collector:4318/v1/metrics",
      logsEndpoint: "http://otel-collector:4318/v1/logs",
      protocol: "http/protobuf", // grpc is ignored
      serviceName: "openclaw-gateway",
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },
  },
}

Variables de entorno

Variable	Propósito
`OTEL_EXPORTER_OTLP_ENDPOINT`	Sobrescribe `diagnostics.otel.endpoint`. Si el valor ya contiene `/v1/traces`, `/v1/metrics` o `/v1/logs`, se usa tal cual.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Sobrescrituras de endpoint específicas de señal usadas cuando la clave de configuración `diagnostics.otel.*Endpoint` correspondiente no está definida. La configuración específica de señal prevalece sobre la variable de entorno específica de señal, que prevalece sobre el endpoint compartido.
`OTEL_SERVICE_NAME`	Sobrescribe `diagnostics.otel.serviceName`.
`OTEL_EXPORTER_OTLP_PROTOCOL`	Sobrescribe el protocolo de cableado (hoy solo se respeta `http/protobuf`).
`OTEL_SEMCONV_STABILITY_OPT_IN`	Establécelo en `gen_ai_latest_experimental` para emitir el atributo de span experimental más reciente de GenAI (`gen_ai.provider.name`) en lugar del `gen_ai.system` heredado. Las métricas de GenAI siempre usan atributos semánticos acotados y de baja cardinalidad de todos modos.
`OPENCLAW_OTEL_PRELOADED`	Establécelo en `1` cuando otra precarga o proceso anfitrión ya haya registrado el SDK global de OpenTelemetry. Entonces el plugin omite su propio ciclo de vida de NodeSDK, pero aun así conecta escuchas de diagnóstico y respeta `traces`/`metrics`/`logs`.

Privacidad y captura de contenido

El contenido sin procesar de modelos/herramientas no se exporta de forma predeterminada. Los spans llevan identificadores acotados (canal, proveedor, modelo, categoría de error, ids de solicitud solo con hash) y nunca incluyen texto del prompt, texto de respuesta, entradas de herramienta, salidas de herramienta ni claves de sesión. Las métricas de Talk exportan solo metadatos de evento acotados, como modo, transporte, proveedor y tipo de evento. No incluyen transcripciones, cargas de audio, ids de sesión, ids de turno, ids de llamada, ids de sala ni tokens de traspaso.

Las solicitudes salientes a modelos pueden incluir un encabezado W3C traceparent. Ese encabezado se genera solo desde el contexto de traza de diagnóstico propiedad de OpenClaw para la llamada de modelo activa. Los encabezados traceparent proporcionados por el llamador se reemplazan, de modo que los plugins o las opciones personalizadas de proveedor no puedan suplantar la ascendencia de trazas entre servicios.

Establece diagnostics.otel.captureContent.* en true solo cuando tu colector y política de retención estén aprobados para texto de prompts, respuestas, herramientas o prompts del sistema. Cada subclave es opt-in de forma independiente:

inputMessages - contenido del prompt del usuario.
outputMessages - contenido de la respuesta del modelo.
toolInputs - cargas de argumentos de herramientas.
toolOutputs - cargas de resultados de herramientas.
systemPrompt - prompt de sistema/desarrollador ensamblado.

Cuando cualquier subclave está habilitada, los spans de modelo y herramienta reciben atributos openclaw.content.* acotados y redactados solo para esa clase.

Muestreo y vaciado

Trazas: diagnostics.otel.sampleRate (solo span raíz; 0.0 descarta todo, 1.0 conserva todo).
Métricas: diagnostics.otel.flushIntervalMs (mínimo 1000).
Registros: los registros OTLP respetan logging.level (nivel de registro de archivo). Usan la ruta de redacción de registros de diagnóstico, no el formato de consola. Las instalaciones de alto volumen deberían preferir el muestreo/filtrado del colector OTLP sobre el muestreo local.
Correlación de registros de archivo: los registros de archivo JSONL incluyen traceId, spanId, parentSpanId y traceFlags de nivel superior cuando la llamada de registro lleva un contexto de traza de diagnóstico válido, lo que permite que los procesadores de registros unan líneas de registro locales con spans exportados.
Correlación de solicitudes: las solicitudes HTTP del Gateway y los frames WebSocket crean un ámbito interno de traza de solicitud. Los registros y eventos de diagnóstico dentro de ese ámbito heredan la traza de solicitud de forma predeterminada, mientras que los spans de ejecución de agente y llamada de modelo se crean como hijos para que los encabezados traceparent del proveedor permanezcan en la misma traza.

Métricas exportadas

Uso de modelos

openclaw.tokens (contador, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
openclaw.cost.usd (contador, attrs: openclaw.channel, openclaw.provider, openclaw.model)
openclaw.run.duration_ms (histograma, attrs: openclaw.channel, openclaw.provider, openclaw.model)
openclaw.context.tokens (histograma, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
gen_ai.client.token.usage (histograma, métrica de convenciones semánticas de GenAI, attrs: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
gen_ai.client.operation.duration (histograma, segundos, métrica de convenciones semánticas de GenAI, attrs: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, error.type opcional)
openclaw.model_call.duration_ms (histograma, attrs: openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, más openclaw.errorCategory y openclaw.failureKind en errores clasificados)
openclaw.model_call.request_bytes (histograma, tamaño en bytes UTF-8 de la carga final de solicitud al modelo; sin contenido sin procesar de la carga)
openclaw.model_call.response_bytes (histograma, tamaño en bytes UTF-8 de eventos de respuesta del modelo transmitidos; sin contenido sin procesar de respuesta)
openclaw.model_call.time_to_first_byte_ms (histograma, tiempo transcurrido antes del primer evento de respuesta transmitido)

Flujo de mensajes

openclaw.webhook.received (contador, attrs: openclaw.channel, openclaw.webhook)
openclaw.webhook.error (contador, attrs: openclaw.channel, openclaw.webhook)
openclaw.webhook.duration_ms (histograma, attrs: openclaw.channel, openclaw.webhook)
openclaw.message.queued (contador, attrs: openclaw.channel, openclaw.source)
openclaw.message.processed (contador, attrs: openclaw.channel, openclaw.outcome)
openclaw.message.duration_ms (histograma, attrs: openclaw.channel, openclaw.outcome)
openclaw.message.delivery.started (contador, attrs: openclaw.channel, openclaw.delivery.kind)
openclaw.message.delivery.duration_ms (histograma, attrs: openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory)

Talk

openclaw.talk.event (contador, attrs: openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
openclaw.talk.event.duration_ms (histograma, attrs: igual que openclaw.talk.event; se emite cuando un evento de Talk informa duración)
openclaw.talk.audio.bytes (histograma, attrs: igual que openclaw.talk.event; se emite para eventos de frames de audio de Talk que informan longitud en bytes)

Colas y sesiones

openclaw.queue.lane.enqueue (contador, attrs: openclaw.lane)
openclaw.queue.lane.dequeue (contador, attrs: openclaw.lane)
openclaw.queue.depth (histograma, attrs: openclaw.lane u openclaw.channel=heartbeat)
openclaw.queue.wait_ms (histograma, attrs: openclaw.lane)
openclaw.session.state (contador, attrs: openclaw.state, openclaw.reason)
openclaw.session.stuck (contador, attrs: openclaw.state; emitido solo para la contabilidad de sesiones obsoletas sin trabajo activo)
openclaw.session.stuck_age_ms (histograma, attrs: openclaw.state; emitido solo para la contabilidad de sesiones obsoletas sin trabajo activo)
openclaw.session.recovery.requested (contador, attrs: openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
openclaw.session.recovery.completed (contador, attrs: openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
openclaw.session.recovery.age_ms (histograma, attrs: los mismos que el contador de recuperación correspondiente)
openclaw.run.attempt (contador, attrs: openclaw.attempt)

Telemetría de actividad de sesión

diagnostics.stuckSessionWarnMs es el umbral de antigüedad sin progreso para los diagnósticos de actividad de sesión. Una sesión en processing no avanza hacia este umbral mientras OpenClaw observe progreso de respuesta, herramienta, estado, bloque o runtime ACP. Los keepalives de escritura no se cuentan como progreso, por lo que todavía se puede detectar un modelo o arnés silencioso.

OpenClaw clasifica las sesiones según el trabajo que aún puede observar:

session.long_running: el trabajo incrustado activo, las llamadas al modelo o las llamadas a herramientas siguen progresando.
session.stalled: existe trabajo activo, pero la ejecución activa no ha informado progreso reciente. Las ejecuciones incrustadas estancadas permanecen al principio solo en observación y luego pasan a abortar y drenar después de diagnostics.stuckSessionAbortMs sin progreso para que los turnos en cola detrás del carril puedan reanudarse. Cuando no se configura, el umbral de aborto usa de forma predeterminada la ventana extendida más segura de al menos 10 minutos y 5 veces diagnostics.stuckSessionWarnMs.
session.stuck: contabilidad de sesión obsoleta sin trabajo activo. Esto libera de inmediato el carril de sesión afectado.

La recuperación emite eventos estructurados session.recovery.requested y session.recovery.completed. El estado de sesión de diagnóstico se marca como inactivo solo después de un resultado de recuperación mutante (aborted o released) y solo si la misma generación de procesamiento sigue siendo la actual.

Solo session.stuck emite el contador openclaw.session.stuck, el histograma openclaw.session.stuck_age_ms y el span openclaw.session.stuck. Los diagnósticos repetidos de session.stuck hacen retroceso mientras la sesión permanezca sin cambios, por lo que los paneles deberían alertar sobre aumentos sostenidos en lugar de en cada tick de Heartbeat. Para el control de configuración y los valores predeterminados, consulta la Referencia de configuración.

Ciclo de vida del arnés

openclaw.harness.duration_ms (histograma, attrs: openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.harness.phase en errores)

Exec

openclaw.exec.duration_ms (histograma, attrs: openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

Elementos internos de diagnóstico (memoria y bucle de herramientas)

openclaw.memory.heap_used_bytes (histograma, attrs: openclaw.memory.kind)
openclaw.memory.rss_bytes (histograma)
openclaw.memory.pressure (contador, attrs: openclaw.memory.level)
openclaw.tool.loop.iterations (contador, attrs: openclaw.toolName, openclaw.outcome)
openclaw.tool.loop.duration_ms (histograma, attrs: openclaw.toolName, openclaw.outcome)

Spans exportados

openclaw.model.usage
- openclaw.channel, openclaw.provider, openclaw.model
- openclaw.tokens.* (input/output/cache_read/cache_write/total)
- gen_ai.system de forma predeterminada, o gen_ai.provider.name cuando se activan las convenciones semánticas GenAI más recientes
- gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.*
openclaw.run
- openclaw.outcome, openclaw.channel, openclaw.provider, openclaw.model, openclaw.errorCategory
openclaw.model.call
- gen_ai.system de forma predeterminada, o gen_ai.provider.name cuando se activan las convenciones semánticas GenAI más recientes
- gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
- openclaw.errorCategory y openclaw.failureKind opcional en errores
- openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
- openclaw.provider.request_id_hash (hash acotado basado en SHA del id de solicitud del proveedor ascendente; los ids sin procesar no se exportan)
openclaw.harness.run
- openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
- Al completarse: openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
- En error: openclaw.harness.phase, openclaw.errorCategory, openclaw.harness.cleanup_failed opcional
openclaw.tool.execution
- gen_ai.tool.name, openclaw.toolName, openclaw.errorCategory, openclaw.tool.params.*
openclaw.exec
- openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.timed_out
openclaw.webhook.processed
- openclaw.channel, openclaw.webhook
openclaw.webhook.error
- openclaw.channel, openclaw.webhook, openclaw.error
openclaw.message.processed
- openclaw.channel, openclaw.outcome, openclaw.reason
openclaw.message.delivery
- openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory, openclaw.delivery.result_count
openclaw.session.stuck
- openclaw.state, openclaw.ageMs, openclaw.queueDepth
openclaw.context.assembled
- openclaw.prompt.size, openclaw.history.size, openclaw.context.tokens, openclaw.errorCategory (sin contenido de prompt, historial, respuesta ni clave de sesión)
openclaw.tool.loop
- openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (sin mensajes de bucle, params ni salida de herramienta)
openclaw.memory.pressure
- openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

Cuando la captura de contenido está habilitada explícitamente, los spans de modelo y herramienta también pueden incluir atributos openclaw.content.* acotados y redactados para las clases de contenido específicas que activaste.

Catálogo de eventos de diagnóstico

Los eventos siguientes respaldan las métricas y spans anteriores. Los Plugins también pueden suscribirse a ellos directamente sin exportación OTLP.

Uso del modelo

model.usage - tokens, costo, duración, contexto, proveedor/modelo/canal, ids de sesión. usage es la contabilidad del proveedor/turno para costo y telemetría; context.used es la instantánea actual de prompt/contexto y puede ser menor que usage.total del proveedor cuando intervienen entrada en caché o llamadas de bucle de herramientas.

Flujo de mensajes

webhook.received / webhook.processed / webhook.error
message.queued / message.processed
message.delivery.started / message.delivery.completed / message.delivery.error

Cola y sesión

queue.lane.enqueue / queue.lane.dequeue
session.state / session.long_running / session.stalled / session.stuck
run.attempt / run.progress
diagnostic.heartbeat (contadores agregados: webhooks/cola/sesión)

Ciclo de vida del arnés

harness.run.started / harness.run.completed / harness.run.error - ciclo de vida por ejecución para el arnés del agente. Incluye harnessId, pluginId opcional, proveedor/modelo/canal e id de ejecución. La finalización agrega durationMs, outcome, resultClassification opcional, yieldDetected y recuentos de itemLifecycle. Los errores agregan phase (prepare/start/send/resolve/cleanup), errorCategory y cleanupFailed opcional.

Exec

exec.process.completed - resultado de terminal, duración, destino, modo, código de salida y tipo de fallo. No se incluyen el texto del comando ni los directorios de trabajo.

Sin un exportador

Puedes mantener los eventos de diagnóstico disponibles para Plugins o receptores personalizados sin ejecutar diagnostics-otel:

{
  diagnostics: { enabled: true },
}

Para salida de depuración dirigida sin elevar logging.level, usa indicadores de diagnóstico. Los indicadores no distinguen mayúsculas y minúsculas y admiten comodines (por ejemplo, telegram.* o *):

{
  diagnostics: { flags: ["telegram.http"] },
}

O como una anulación de env puntual:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

La salida de indicadores va al archivo de registro estándar (logging.file) y sigue siendo redactada por logging.redactSensitive. Guía completa: Indicadores de diagnóstico.

Deshabilitar

{
  diagnostics: { otel: { enabled: false } },
}

También puedes dejar diagnostics-otel fuera de plugins.allow, o ejecutar openclaw plugins disable diagnostics-otel.

Relacionado

Registro - registros en archivo, salida de consola, seguimiento desde CLI y la pestaña Registros de Control UI
Elementos internos del registro de Gateway - estilos de registro de WS, prefijos de subsistema y captura de consola
Indicadores de diagnóstico - indicadores de registro de depuración dirigida
Exportación de diagnóstico - herramienta de paquete de soporte para operadores (separada de la exportación OTEL)
Referencia de configuración - referencia completa de campos diagnostics.*

# Cómo encaja todo

# Inicio rápido

# Señales exportadas

# Referencia de configuración

# Variables de entorno

# Privacidad y captura de contenido

# Muestreo y vaciado

# Métricas exportadas

# Uso de modelos

# Flujo de mensajes

# Talk

# Colas y sesiones

# Telemetría de actividad de sesión

# Ciclo de vida del arnés

# Exec

# Elementos internos de diagnóstico (memoria y bucle de herramientas)

# Spans exportados

# Catálogo de eventos de diagnóstico

# Sin un exportador

# Deshabilitar

# Relacionado

Cómo encaja todo

Inicio rápido

Señales exportadas

Referencia de configuración

Variables de entorno

Privacidad y captura de contenido

Muestreo y vaciado

Métricas exportadas

Uso de modelos

Flujo de mensajes

Talk

Colas y sesiones

Telemetría de actividad de sesión

Ciclo de vida del arnés

Exec

Elementos internos de diagnóstico (memoria y bucle de herramientas)

Spans exportados

Catálogo de eventos de diagnóstico

Sin un exportador

Deshabilitar

Relacionado