--- read_when: - Quiere enviar el uso del modelo de OpenClaw, el flujo de mensajes o las métricas de sesión a un colector de OpenTelemetry - Estás conectando trazas, métricas o registros a Grafana, Datadog, Honeycomb, New Relic, Tempo u otro destino OTLP - Necesitas los nombres exactos de las métricas, los nombres de los intervalos o las estructuras de atributos para crear paneles o alertas summary: Exporta los diagnósticos de OpenClaw a cualquier colector de OpenTelemetry mediante el Plugin diagnostics-otel (OTLP/HTTP) title: Exportación de OpenTelemetry x-i18n: generated_at: "2026-05-06T17:56:32Z" model: gpt-5.5 provider: openai source_hash: b09453a4a1592d2698de6340e5f006ef16edfd8e86132285c48865d468d20ab6 source_path: gateway/opentelemetry.md workflow: 16 --- 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](/es/logging). ## 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: ```bash openclaw plugins install clawhub:@openclaw/diagnostics-otel ``` ```json5 { 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: ```bash openclaw plugins enable diagnostics-otel ``` Actualmente `protocol` solo admite `http/protobuf`. `grpc` se ignora. ## 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 ```json5 { 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](/es/gateway/configuration-reference#diagnostics). ### 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`: ```json5 { 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 `*`): ```json5 { diagnostics: { flags: ["telegram.http"] }, } ``` O como una anulación de env puntual: ```bash 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](/es/diagnostics/flags). ## Deshabilitar ```json5 { diagnostics: { otel: { enabled: false } }, } ``` También puedes dejar `diagnostics-otel` fuera de `plugins.allow`, o ejecutar `openclaw plugins disable diagnostics-otel`. ## Relacionado - [Registro](/es/logging) - registros en archivo, salida de consola, seguimiento desde CLI y la pestaña Registros de Control UI - [Elementos internos del registro de Gateway](/es/gateway/logging) - estilos de registro de WS, prefijos de subsistema y captura de consola - [Indicadores de diagnóstico](/es/diagnostics/flags) - indicadores de registro de depuración dirigida - [Exportación de diagnóstico](/es/gateway/diagnostics) - herramienta de paquete de soporte para operadores (separada de la exportación OTEL) - [Referencia de configuración](/es/gateway/configuration-reference#diagnostics) - referencia completa de campos `diagnostics.*`