Monitoreo

Aprende cómo habilitar y configurar OpenTelemetry para Claude Code.

Rastrea el uso de Claude Code, costos y actividad de herramientas en toda tu organización exportando datos de telemetría a través de OpenTelemetry (OTel). Claude Code exporta métricas como datos de series temporales a través del protocolo estándar de métricas, eventos a través del protocolo de registros/eventos, y opcionalmente trazas distribuidas a través de OpenTelemetry.

[!NOTE]

Para la API de Claude o Managed Agents, consulta OpenTelemetry para la API de Claude.

Inicio rápido

Configura OpenTelemetry usando variables de entorno:

# 1. Habilitar telemetría
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Elegir exportadores (ambos son opcionales - configura solo lo que necesites)
export OTEL_METRICS_EXPORTER=otlp       # Opciones: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Opciones: otlp, console, none

# 3. Configurar punto final OTLP (para exportador OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Establecer autenticación (si es requerida)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Para depuración: reducir intervalos de exportación, y restablecerlos para uso en producción
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 segundos (predeterminado: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 segundos (predeterminado: 5000ms)

# 6. Ejecutar Claude Code
claude

Para verificar una configuración que exporta métricas, comprueba tu backend para la métrica claude_code.session.count, que Claude Code emite cuando se inicia una sesión. Para verificar una configuración solo de registros, envía un mensaje y comprueba el evento claude_code.user_prompt.

Si nada llega, inicia Claude Code con claude --debug-file <path> y comprueba el registro que escribe en esa ruta. Claude Code reporta fallos de los exportadores que configures como errores [3P telemetry], donde 3P significa terceros. Las líneas con prefijo [Anthropic telemetry] describen la telemetría operativa separada de Anthropic y no indican un problema con tu configuración.

Para opciones de configuración completas, consulta la especificación de OpenTelemetry.

Configuración del administrador

Los administradores pueden configurar los ajustes de OpenTelemetry para todos los usuarios a través del archivo de configuración administrada. Consulta la precedencia de configuración para obtener más información sobre cómo se aplican los ajustes.

Ejemplo de configuración de ajustes administrados:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

En la aplicación Claude Desktop, las sesiones de la pestaña Code leen estos ajustes administrados de las fuentes que llegan a cada tipo de sesión de Desktop. El formulario de OpenTelemetry para Cowork bajo Monitoring en los ajustes de Datos y privacidad de la consola de administrador se aplica solo a sesiones de Cowork, por lo que ni la CLI de terminal ni la pestaña Code exportan a un recopilador que establezca allí.

Claude Code ignora las variables del exportador de OpenTelemetry en el .claude/settings.json y .claude/settings.local.json de un repositorio, por lo que un repositorio no puede usarlas para activar la telemetría, elegir dónde va, o capturar contenido. Establécelas en los ajustes administrados, o haz que cada desarrollador las establezca en su shell o ~/.claude/settings.json. Un repositorio aún puede desactivar una señal estableciendo su selector de exportador, como OTEL_LOGS_EXPORTER, en none, a menos que los ajustes administrados, un archivo --settings, o el entorno desde el que inicias Claude Code establezca esa variable.

Claude Code no pasa variables de entorno OTEL_* a los subprocesos que genera, incluyendo la herramienta Bash, hooks, servidores MCP, y servidores de lenguaje. Una aplicación instrumentada con OpenTelemetry que ejecutes a través de la herramienta Bash no hereda el punto final del exportador de Claude Code ni los encabezados, así que establece esas variables directamente en el comando si esa aplicación necesita exportar su propia telemetría.

Cómo los ajustes administrados bloquean el destino OTLP

Cuando estableces una variable OTEL_EXPORTER_OTLP_* en los ajustes administrados, Claude Code elimina las variables conflictivas establecidas por el desarrollador al inicio y registra una advertencia en el registro de depuración. Lo que elimina depende de qué variable establezca:

• Puntos finales: cuando estableces OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code elimina todos los puntos finales por señal establecidos por el desarrollador. Los desarrolladores no pueden apuntar una señal a un recopilador diferente, así que no necesitas establecer también las variables de punto final por señal en los ajustes administrados.

• Protocolos: cuando estableces OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code elimina todos los protocolos por señal establecidos por el desarrollador.

• Credenciales: cuando estableces OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY, u OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, Claude Code elimina las versiones por señal establecidas por el desarrollador de esa variable, más todas las variables de punto final establecidas por el desarrollador, genéricas o por señal, ya que esas credenciales de otro modo llegarían a un recopilador que los ajustes administrados no eligieron.

• Selectores de exportador: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, y el OTEL_TRACES_EXPORTER beta siguen la precedencia normal por clave. Un ajuste del desarrollador aún puede desactivar una señal o cambiarla al exportador de consola, así que establece también los selectores en los ajustes administrados si necesitas que estén bloqueados. En fuentes de administrador, OTEL_LOGS_EXPORTER sigue la unidad de telemetría mientras que los otros dos selectores se fusionan por clave. Requiere Claude Code v2.1.223 o posterior.

• Puntos finales de rastreo beta: con rastreo beta detallado activo, Claude Code exporta registros y rastreos a BETA_TRACING_ENDPOINT en lugar de a través de los exportadores de registros y rastreos. Claude Code por lo tanto elimina un BETA_TRACING_ENDPOINT establecido por el desarrollador siempre que cualquiera de estos ajustes administrados decida el destino de cualquiera de las señales:

  • Un punto final genérico o de registros/rastreos o credencial
  • Un otelHeadersHelper
  • Un selector de exportador de registros o rastreos establecido en none, console, o vacío, valores que mantienen la señal fuera de un recopilador
  • CLAUDE_CODE_ENABLE_TELEMETRY desactivado

  Un punto final o credencial solo de métricas no lo elimina. Antes de v2.1.251, un BETA_TRACING_ENDPOINT establecido por el desarrollador redirigía los registros y rastreos que el rastreo beta detallado exporta incluso cuando los ajustes administrados fijaban el recopilador.

Claude Code no elimina variables por señal que estableces en los ajustes administrados en sí, así que puedes enrutar una señal a un recopilador diferente estableciendo su variable allí, como hace el ejemplo SIEM. Si estableces una credencial por señal allí, Claude Code elimina el punto final establecido por el desarrollador para esa señal.

Este comportamiento de eliminación cambia dónde se entrega la telemetría, no lo que Claude Code recopila.

Antes de v2.1.217, cada variable seguía la precedencia de ajustes por clave de forma independiente, así que un punto final específico de señal establecido en los ajustes del usuario o el shell redirigía esa señal lejos del recopilador administrado.

Cuando la aplicación de escritorio o un ejecutor de entorno autohospedado inicia Claude Code y nombra un punto final OTLP en el entorno que proporciona, Claude Code fija el destino de la misma manera: las variables de telemetría del iniciador eliminan variables establecidas por el desarrollador exactamente como lo hacen los ajustes administrados. Claude Code no elimina variables que el iniciador en sí estableció. Requiere Claude Code v2.1.251 o posterior.

Detalles de configuración

Variables de configuración comunes

Estas variables configuran exportadores, puntos finales y comportamiento de exportación para todas las implementaciones.

Si establece una variable de punto final o protocolo por señal, como OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, Claude Code la utiliza en lugar de la variable genérica para esa señal. Si establece una variable de encabezados por señal, como OTEL_EXPORTER_OTLP_METRICS_HEADERS, Claude Code la fusiona con la genérica OTEL_EXPORTER_OTLP_HEADERS para esa señal.

En máquinas con configuración administrada, consulte Cómo la configuración administrada bloquea el destino OTLP para ver qué elimina Claude Code.

Para los protocolos http/protobuf y http/json, Claude Code envía cada solicitud de exportación con un encabezado Content-Length.

Autenticación mTLS

La forma en que configura certificados de cliente para el exportador OTLP depende del protocolo OTLP en uso para esa señal, establecido mediante OTEL_EXPORTER_OTLP_PROTOCOL o la anulación específica de la señal. La misma configuración se aplica a métricas, registros y trazas.

Para grpc, el SDK de OpenTelemetry lee las variables OTLP estándar directamente, por lo que las configuraciones existentes que establecen las variables de métricas específicas de la señal continúan funcionando. En máquinas con configuración administrada, Claude Code puede eliminar credenciales y puntos finales específicos de la señal establecidos por el desarrollador al iniciar.

Control de cardinalidad de métricas

Las siguientes variables de entorno controlan qué atributos se incluyen en las métricas para gestionar la cardinalidad:

Una cardinalidad más baja generalmente significa mejor rendimiento y costos de almacenamiento más bajos, pero datos menos granulares para el análisis.

Traces (beta)

El tracing distribuido exporta tramos que vinculan cada mensaje del usuario a las solicitudes de API y ejecuciones de herramientas que desencadena, para que pueda ver una solicitud completa como un único tramo en su backend de tracing.

El tracing está deshabilitado de forma predeterminada. Para habilitarlo, establezca tanto CLAUDE_CODE_ENABLE_TELEMETRY=1 como CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, luego establezca OTEL_TRACES_EXPORTER para elegir dónde se envían los tramos. Los trazos reutilizan la configuración OTLP común para punto final, protocolo, encabezados y mTLS. En máquinas con configuración administrada, Claude Code puede eliminar credenciales y puntos finales específicos de la señal establecidos por el desarrollador al iniciar.

Los tramos redactan el texto del mensaje del usuario, los detalles de entrada de la herramienta y el contenido de la herramienta de forma predeterminada. Establezca OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 y OTEL_LOG_TOOL_CONTENT=1 para incluirlos.

Cuando el tracing está activo, los subprocesos de Bash y PowerShell heredan automáticamente una variable de entorno TRACEPARENT que contiene el contexto de traza W3C del tramo de ejecución de herramienta activo. Esto permite que cualquier subproceso que lea TRACEPARENT coloque sus propios tramos bajo el mismo tramo, habilitando el tracing distribuido de extremo a extremo a través de scripts y comandos que Claude ejecuta.

Cuando el tracing está activo y Claude Code está conectado directamente a la API de Anthropic, cada solicitud de modelo lleva un encabezado W3C traceparent establecido en el contexto del tramo claude_code.llm_request, y el encabezado traceresponse de la API se registra como un vínculo de tramo. Juntos, estos conectan los tramos del lado del cliente de Claude Code a la traza del lado del servidor a través de cualquier intermediario compatible. Las solicitudes HTTP MCP salientes llevan traceparent de la misma manera. El encabezado no se envía a proveedores de terceros.

De forma predeterminada, el encabezado traceparent en solicitudes de modelo y HTTP MCP se envía solo cuando ANTHROPIC_BASE_URL no está establecido o apunta a la API de Anthropic, ya que algunos proxies rechazan encabezados no reconocidos. La variable TRACEPARENT del subproceso se controla mediante el mismo interruptor por coherencia. Si ejecuta Claude Code a través de un proxy ANTHROPIC_BASE_URL personalizado y desea que se propague el contexto de traza, establezca CLAUDE_CODE_PROPAGATE_TRACEPARENT=1.

En sesiones del SDK de Agent y no interactivas iniciadas con -p, Claude Code también lee TRACEPARENT y TRACESTATE de su propio entorno al iniciar cada tramo de interacción. Esto permite que un proceso de incrustación pase su contexto de traza W3C activo al subproceso para que los tramos de Claude Code aparezcan como hijos de la traza distribuida del llamador. Las sesiones interactivas ignoran TRACEPARENT entrante para evitar heredar accidentalmente valores ambientes de entornos de CI o contenedores.

El contexto de traza entrante también se aplica a eventos. En sesiones de SDK de Agent y -p con TRACEPARENT establecido, cada registro de registro de evento OTLP lleva valores trace_id y span_id que lo unen a la traza de su aplicación, incluso cuando el exportador de trazas no está configurado, para que su backend de registro pueda correlacionar eventos con el resto de la traza.

Un registro emitido mientras una interacción está activa lleva los IDs del tramo de interacción, incluso cuando Claude Code lo emite fuera del contexto asíncrono del tramo, como en una devolución de llamada de una solicitud de permiso o en un registro almacenado en búfer durante el inicio y exportado más tarde. Un registro emitido sin un tramo de interacción activo lleva directamente los IDs del TRACEPARENT entrante.

Jerarquía de tramos

Cada mensaje del usuario inicia un tramo raíz claude_code.interaction. Las llamadas de API, llamadas de herramientas y ejecuciones de hooks se registran como sus hijos. Los tramos de herramientas tienen dos tramos secundarios propios: uno para el tiempo dedicado a esperar una decisión de permiso y otro para la ejecución en sí. Cuando la herramienta Agent, o la herramienta Task heredada, genera un subagente, los tramos de API y herramientas del subagente se anidan bajo el tramo claude_code.tool del padre.

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans

En sesiones del SDK de Agent y claude -p, claude_code.interaction en sí se convierte en un hijo del tramo del llamador cuando TRACEPARENT se establece en el entorno.

Cuando un hook PreToolUse difiere una llamada de herramienta, Claude Code guarda el contexto de traza del turno que lo difirió. Cuando reanuda la sesión y la herramienta se vuelve a ejecutar, los tramos de la herramienta se unen a la traza del turno anterior como hijos del tramo claude_code.interaction del turno.

Atributos de tramo

Cada tramo lleva los atributos estándar más un atributo span.type que coincide con su nombre. Las tablas a continuación enumeran los atributos adicionales establecidos en cada tramo. Los tramos llm_request, tool.execution y hook establecen el estado ERROR de OpenTelemetry cuando registran una falla; los otros tramos siempre terminan con estado UNSET.

claude_code.interaction

claude_code.llm_request

Cada intento de reintento también se registra como un evento de tramo gen_ai.request.attempt con atributos attempt e client_request_id.

claude_code.tool

Evento de tramo tool.output en claude_code.tool

Si establece OTEL_LOG_TOOL_CONTENT=1, las llamadas de Read y Bash pueden registrar un evento de tramo tool.output en el tramo claude_code.tool. Las llamadas de Edit y Write registran uno solo cuando también establece OTEL_LOG_TOOL_DETAILS=1. Esa variable no está limitada a esas dos herramientas, así que consulte su fila en la tabla de configuración para los argumentos que agrega en otros lugares.

Las herramientas MCP, WebFetch y WebSearch también registran este evento, en Claude Code v2.1.283 o posterior.

Claude Code escribe este evento desde el retorno exitoso de una llamada de herramienta, por lo que una llamada que genera un error no registra nada, sea cual sea la herramienta. Entre las llamadas que sí retornan, no registra ningún evento tool.output para:

• Una llamada a cualquier herramienta que no sea Read, Edit, Write, Bash, WebFetch, WebSearch y herramientas MCP
• Una Read que retorna algo que no sea texto de archivo, como una imagen, un PDF o una relectura de un archivo cuyo contenido no ha cambiado
• Una llamada de Edit o Write, a menos que también establezca OTEL_LOG_TOOL_DETAILS=1
• Una llamada a WebFetch o WebSearch que Claude Code movió a segundo plano mientras se ejecutaba para que un mensaje en espera pudiera llegar a Claude. El resultado que llega más tarde tampoco se registra. Para saber cuándo Claude Code mueve una llamada, consulta Cuándo Claude Code envía lo que pusiste en cola para la terminal y el campo priority para las sesiones del Agent SDK

El evento lleva estos atributos, cada uno truncado en el límite de contenido (60 KB de forma predeterminada). Controlado por nombra la variable que un atributo necesita además de OTEL_LOG_TOOL_CONTENT=1, y para Edit y Write esa variable controla el evento en sí en lugar del atributo.

El atributo tool_name del tramo padre le indica de qué herramienta provino un evento. Un atributo cortado en el límite de contenido va acompañado de <attribute>_truncated y <attribute>_original_length.

claude_code.tool.blocked_on_user

Una decisión cancelled con source user_abort significa que un mensaje que necesitaba entrega inmediata interrumpió el turno mientras la solicitud de permiso o la comprobación del modo automático estaba pendiente. Por ejemplo, durante una comprobación del modo automático, el usuario tenía un mensaje en cola y lo envió de inmediato.

claude_code.tool.execution

claude_code.hook

Este tramo aparece solo cuando el tracing beta detallado está activo, lo que requiere ENABLE_BETA_TRACING_DETAILED=1 y BETA_TRACING_ENDPOINT, un par que también cambia dónde van sus registros y trazas. Establezca el par en su shell, configuración de usuario o configuración administrada; ambas variables se ignoran en configuración de proyecto y local. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA solo no lo produce.

En sesiones de CLI interactivas, el tracing beta detallado también requiere que su organización esté en la lista de permitidos para la función. Las sesiones del SDK de Agent y no interactivas -p no requieren lista de permitidos.

Atributos de contenido con tracing beta detallado

[!NOTE]

Atributos adicionales que contienen contenido como new_context, system_reminders, system_prompt_preview, user_system_prompt, tool_input y response.model_output se emiten solo cuando el tracing beta detallado está activo. No son parte del esquema de tramo estable.

Estos atributos aparecen en los tramos siguientes, y Controlado por nombra la variable que un atributo necesita además del tracing beta detallado. Los valores más largos que el límite de contenido (60 KB de forma predeterminada) se truncan.

Con el tracing beta detallado y OTEL_LOG_USER_PROMPTS=1, Claude Code también emite un evento claude_code.system_prompt que lleva el prompt del sistema completo, truncado en el límite de contenido. Llega la primera vez que una sesión envía cada prompt del sistema distinto, y de nuevo después de la compactación.

Encabezados dinámicos

Para entornos empresariales que requieren autenticación dinámica, puede configurar un script para generar encabezados dinámicamente. Los encabezados dinámicos se aplican solo a los protocolos http/protobuf e http/json. Con el protocolo grpc, Claude Code usa solo las variables de encabezados estáticos, OTEL_EXPORTER_OTLP_HEADERS y sus variantes específicas de la señal.

Configuración de ajustes

Agregue a su .claude/settings.json, reemplazando la ruta con su propio script:

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

El valor puede ser la ruta a un archivo ejecutable, incluyendo una ruta que contiene espacios, o una línea de comando de shell con argumentos. En Windows, el valor siempre se ejecuta a través del shell, así que cite una ruta que contiene espacios dentro del valor JSON.

Requisitos del script

El script debe generar JSON válido con pares clave-valor de cadena que representen encabezados HTTP:

#!/bin/bash
# Ejemplo: Múltiples encabezados
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Si el asistente falla o imprime salida que no cumple con estos requisitos, las exportaciones fallan y su backend de telemetría no recibe nada de la sesión hasta que el asistente funcione nuevamente. Claude Code reporta la falla en:

• Una notificación de advertencia en sesiones interactivas, otelHeadersHelper failed; telemetry is not being exported, mostrada una vez por sesión cuando el asistente falla por primera vez
• Salida de /status
• El registro de depuración, cuando se ejecuta con --debug o después de ejecutar /debug en la sesión
• stderr, en sesiones no interactivas iniciadas con -p

Comportamiento de actualización

El script del asistente de encabezados se ejecuta al inicio y periódicamente después para admitir la actualización de tokens. De forma predeterminada, el script se ejecuta cada 29 minutos. Personalice el intervalo con la variable de entorno CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Soporte de organización de múltiples equipos

Las organizaciones con múltiples equipos o departamentos pueden agregar atributos personalizados para distinguir entre diferentes grupos usando la variable de entorno OTEL_RESOURCE_ATTRIBUTES:

# Agregar atributos personalizados para identificación de equipo
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Estos atributos personalizados se incluyen en todas las métricas y eventos, permitiéndole:

• Filtrar métricas por equipo o departamento
• Rastrear costos por centro de costos
• Crear paneles específicos del equipo
• Configurar alertas para equipos específicos

Claude Code adjunta estos valores como atributos en cada punto de datos de métrica y registro de evento, además de enviarlos en el bloque de recursos OTLP. Debido a que la mayoría de los backends de métricas exponen atributos de punto de datos como etiquetas consultables, puede agrupar y filtrar métricas por sus claves personalizadas directamente. Excepto por los atributos de repositorio vcs.* repository attributes, las claves personalizadas nunca anulan los atributos estándar como user.id o session.id: cuando una clave colisiona, Claude Code mantiene el valor integrado.

Cada clave personalizada se convierte en una etiqueta en cada serie de métricas, por lo que los valores de alta cardinalidad aumentan el costo de almacenamiento en su backend de métricas. Para enviar atributos personalizados en el bloque de recursos solo y omitirlos de las etiquetas de punto de datos, establezca OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. Consulte Control de cardinalidad de métricas.

[!WARNING]

La variable de entorno OTEL_RESOURCE_ATTRIBUTES utiliza pares clave=valor separados por comas con requisitos de formato estricto:

• Sin espacios permitidos: los valores no pueden contener espacios. Por ejemplo, user.organizationName=My Company es inválido
• Formato: debe ser pares clave=valor separados por comas: key1=value1,key2=value2
• Caracteres permitidos: solo caracteres ASCII de EE.UU. excluyendo caracteres de control, espacios en blanco, comillas dobles, comas, puntos y comas y barras invertidas
• Caracteres especiales: los caracteres fuera del rango permitido deben estar codificados en porcentaje

Para un valor que necesitaría un espacio, use guiones bajos o camelCase en su lugar. Los siguientes ejemplos establecen org.name con cada forma:

export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

Puede codificar en porcentaje cualquier carácter, no solo los excluidos. Este ejemplo codifica tanto el espacio como el apóstrofo:

export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Envolver valores entre comillas no escapa espacios. Por ejemplo, org.name="My Company" resulta en el valor literal "My Company" con las comillas incluidas, no My Company.

Atribuir la telemetría a las sesiones SSH de Desktop

Para ver en qué máquina remota se ejecutó una sesión SSH de Desktop, nombra cada máquina en un atributo personalizado. Las métricas y los eventos no indican en qué máquina se ejecutó una sesión.

En cada máquina remota, agrega OTEL_RESOURCE_ATTRIBUTES al bloque env que activa la telemetría, en el archivo de configuración administrada que lee la sesión. Escribe el nombre de forma literal en el archivo de cada máquina. Claude Code no expande el valor, así que host.name=$(hostname) llega tal cual, con esos mismos caracteres.

El siguiente ejemplo nombra la máquina build-7:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_RESOURCE_ATTRIBUTES": "host.name=build-7"
  }
}

Cuando nada más establece la variable, host.name llega en el bloque de recursos, tanto en las sesiones SSH de Desktop como en la CLI de esa máquina. Para ver dónde más aparecen los atributos personalizados, consulta Soporte de organización de múltiples equipos.

Si el nombre no llega, comprueba si se debe a una de estas causas:

• Lo estableciste en la computadora que ejecuta Desktop: Desktop no pasa a la sesión SSH un valor que establezcas ahí
• Lo exportaste en /etc/profile u otro archivo que solo leen los shells de inicio de sesión: el nombre llega cuando ejecutas claude desde un shell de inicio de sesión, pero no en una sesión SSH de Desktop. Desktop no inicia Claude Code a través de un shell de inicio de sesión. En su lugar, establece la variable en env en el archivo de configuración administrada de la máquina remota.
• Un valor contiene un espacio: en ese caso, Claude Code no copia ninguna de las claves en los eventos ni en los puntos de datos, y no reporta ningún error. Quita el espacio del valor.
• Algo más ya establece la variable: en una sesión que inicia la aplicación de escritorio, una variable ya establecida en el entorno de lanzamiento tiene precedencia sobre los archivos de configuración. El registro de depuración nombra cada variable ignorada. Cuando un despliegue de Desktop de terceros especifica un endpoint OTLP en el entorno que proporciona, ese entorno lleva el propio OTEL_RESOURCE_ATTRIBUTES de Desktop.

Configuraciones de ejemplo

Establezca estas variables de entorno antes de ejecutar claude. Cada escenario a continuación muestra una configuración completa, y cada variable se describe en Variables de configuración comunes. Para confirmar que una configuración surtió efecto, verifique su backend para la métrica claude_code.session.count después de iniciar una sesión; el Inicio rápido cubre la verificación solo de registros y qué verificar cuando nada llega.

Para depuración de consola con un intervalo de exportación de 1 segundo:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

Para OTLP sobre gRPC:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Para Prometheus, raspado desde http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

En un entorno autohospedado, la sesión vincula el puerto 9464 solo en la capacidad predeterminada del ejecutor de uno. A mayor capacidad, el ejecutor reexpone contadores y medidores de sesión en su propio punto final /metrics en su lugar.

Para enviar métricas a múltiples exportadores:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

Para enviar métricas y registros a diferentes puntos finales o backends:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

Para exportar solo métricas, sin eventos o registros:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Para exportar solo eventos y registros, sin métricas:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Telemetría de sesiones en la nube y Claude Tag

Las sesiones en la nube, incluidas las sesiones del canal Claude Tag, se ejecutan en entornos en la nube en lugar de en los dispositivos de sus usuarios, por lo que un archivo de configuración administrado o un perfil de shell en esos dispositivos no configura su telemetría. Para las sesiones en entornos alojados por Anthropic, esta sección cubre dónde establecer las variables de telemetría, cómo hacer que su recopilador sea accesible desde el entorno y cómo distinguir las sesiones en la nube y Claude Tag en los datos exportados.

Para exportar telemetría de esas sesiones, establezca CLAUDE_CODE_ENABLE_TELEMETRY y las variables OTEL_*, utilizando las mismas claves que el ejemplo de configuración del administrador, en uno de dos lugares:

• Configuración administrada por el servidor: agréguelas al bloque env de la configuración administrada por el servidor de su organización. Claude Code obtiene esa configuración al iniciarse dondequiera que se aplique la configuración administrada por el servidor, lo que incluye las máquinas de sus usuarios y las sesiones en la nube que no sean sesiones del canal Claude Tag. Las sesiones de Claude Tag no reciben su configuración administrada por el servidor, por lo que esta ruta no las configura.
• Las variables del entorno: agréguelas a las variables de entorno de un entorno en la nube para configurar solo las sesiones que se ejecutan en ese entorno. Esta es la ruta que llega a las sesiones de Claude Tag.

Cualquiera que use un entorno puede leer sus variables, así que no coloques una credencial allí, como un token de recopilador en OTEL_EXPORTER_OTLP_HEADERS. Un secreto de red en el entorno tampoco ayuda, porque la exportación de telemetría propia de Claude Code es una de las solicitudes que nunca obtienen el secreto. Si tu recopilador requiere una credencial, configura toda la exportación a través de la configuración administrada por el servidor en su lugar, porque cuando estableces una credencial allí, Claude Code elimina las variables de endpoint establecidas fuera de la configuración administrada.

Tenga en cuenta estas restricciones cuando configure la telemetría para sesiones en la nube:

• Permita que las sesiones lleguen al recopilador: Claude Code envía la exportación a través de la red de la sesión, por lo que si llega al host en su OTEL_EXPORTER_OTLP_ENDPOINT depende del nivel de acceso de red del entorno. Si las sesiones no pueden llegar al dominio del recopilador en el nivel que eligió, agregue el dominio a la lista de permitidos del entorno, porque ninguna configuración administrada por el servidor agrega dominios a la lista de permitidos de red de un entorno.
• Canales de Claude Tag: realiza los cambios en la lista de permitidos y en las variables de entorno en el entorno compartido establecido como predeterminado de tu organización o fijado al canal.
• Cowork se configura por separado: las sesiones de Cowork no reciben la configuración administrada por el servidor, como muestra la tabla de cobertura de superficie, por lo que el bloque env administrado por el servidor no configura su telemetría.

Atribuir telemetría a sesiones en la nube

De forma predeterminada, las métricas y eventos de una sesión en la nube llevan los atributos estándar, incluidos session.id, ccr.session.id y organization.id, por lo que puede filtrar por sesión u organización sin configuración adicional. El valor ccr.session.id es el CLAUDE_CODE_REMOTE_SESSION_ID de la sesión. Para convertirlo en la URL de transcripción de la sesión, consulte Vincular salida nuevamente a la sesión.

Para distinguir las sesiones en la nube, agrupa o filtra por ccr.session.id, no por session.id.

Para atribuir telemetría con más detalle, use estas opciones:

• Identificar sesiones de Claude Tag: establezca OTEL_METRICS_INCLUDE_ENTRYPOINT=true, como se describe en Control de cardinalidad de métricas. Las métricas entonces llevan app.entrypoint, cuyo valor es claude-in-slack para sesiones de Claude Tag.
• Agregar atributos personalizados: establezca OTEL_RESOURCE_ATTRIBUTES en el mismo lugar donde establece las otras variables OTEL_* para esas sesiones. Si lo export en el script de configuración del entorno en su lugar, el valor no llega a Claude Code: el script de configuración es un script Bash separado que se ejecuta antes de que Claude Code se inicie, y las variables que exporta terminan con él.

En las sesiones del canal Claude Tag, Claude funciona como la identidad compartida de su organización en lugar de como cualquier miembro, así que no confíe en los atributos user.* para identificar quién etiquetó a Claude.

Métricas y eventos disponibles

Atributos estándar

Todas las métricas y eventos comparten estos atributos estándar:

En las sesiones que iniciaron sesión en un gateway de aplicaciones de Claude mediante /login, la CLI marca las exportaciones con la identidad autenticada: user.id es el sujeto del IdP, user.email es el correo con el que se inició sesión y user.groups contiene la pertenencia a grupos del IdP como una cadena separada por comas. Cada exportación también incluye identity.source: gateway-oidc. La identidad del gateway se aplica al final, por lo que las claves user.* e identity.* configuradas mediante OTEL_RESOURCE_ATTRIBUTES se ignoran en esas sesiones.

[!NOTE]

Los eventos que Claude Code registra antes de que un desarrollador inicie sesión no incluyen la identidad del gateway. Cuando Claude Code abre una sesión sin haber iniciado sesión en el gateway, por ejemplo después de que el gateway finaliza el inicio de sesión, los eventos de inicio registrados antes del inicio de sesión incluyen el user.id anónimo y ningún identity.source. Entre ellos están managed_settings_resolved, plugin_loaded y mcp_server_connection.

Para los atributos de identidad en sesiones de Claude Desktop y Cowork que se conectan a través de un gateway, consulta la referencia de telemetry del gateway.

Los eventos incluyen además los siguientes atributos. Nunca se adjuntan a las métricas porque provocarían una cardinalidad ilimitada:

• prompt.id: UUID que correlaciona un prompt del usuario con todos los eventos posteriores hasta el siguiente prompt. Consulta Atributos de correlación de eventos.
• workspace.host_paths: directorios del espacio de trabajo del host seleccionados en la aplicación de escritorio, como un arreglo de cadenas
• workflow.run_id: identificador de ejecución, con el prefijo wf_, en los eventos de API y de herramientas emitidos por agentes que pertenecen a una ejecución de la herramienta Workflow. Filtrar eventos por un workflow.run_id reconstruye las solicitudes a la API y los resultados de herramientas de esa ejecución. El identificador abarca los agentes que genera el script del flujo de trabajo y cualquier agente que estos generen a su vez, como las invocaciones de skills. Coincide con el identificador de ejecución informado en el resultado de la herramienta Workflow.
• workflow.name: nombre del flujo de trabajo, el meta.name de su script, emitido junto con workflow.run_id. Los nombres de flujos de trabajo integrados aparecen textualmente cuando la ejecución usa el script integrado sin modificar. Los nombres creados por el usuario, incluidas las copias editadas de scripts integrados, se reemplazan por custom a menos que se configure OTEL_LOG_TOOL_DETAILS=1.
• agent_id: identificador del subagente que generó el evento, como a3f2c1b4d5e6f7a80. Los eventos que lo llevan incluyen los eventos de API y de herramientas de un subagente, sus eventos assistant_response y subagent_completed para el subagente finalizado. Ausente en los eventos de la sesión principal y de compañeros de equipo en proceso. El agent_id del span del subagente es el mismo valor, o agrega una etiqueta después de la a inicial, como en acompact-3f2c1b4d5e6f7a80. Requiere Claude Code v2.1.310 o posterior
• parent_agent_id: el agent_id del agente que generó o reanudó por última vez al subagente que generó el evento. Ausente cuando ese agente es la sesión principal. Requiere Claude Code v2.1.310 o posterior

Atributos del repositorio

Configura OTEL_METRICS_INCLUDE_REPOSITORY=true para etiquetar las métricas y los eventos con la identidad del repositorio de la sesión, de modo que un recolector compartido pueda atribuir el uso por repositorio. Requiere Claude Code v2.1.269 o posterior.

Claude Code deriva estos atributos una vez por sesión a partir del remoto origin del repositorio. Cuando los remotos HTTPS y SSH de un repositorio indican el mismo host y la misma ruta, como ocurre en GitHub, GitLab y Bitbucket Cloud, ambos producen valores idénticos:

Los valores se convierten a minúsculas, y las credenciales, las cadenas de consulta y los fragmentos de la URL del remoto nunca aparecen en ellos. Los atributos se omiten cuando la sesión no tiene un remoto origin, cuando el remoto no tiene forma de URL o cuando el único repositorio que la contiene es tu directorio home.

Para obtener estos atributos desde una sesión en la nube, configura las variables de telemetría, incluida OTEL_METRICS_INCLUDE_REPOSITORY, en su entorno en la nube. Permite también el dominio de tu recolector en el acceso a la red del entorno.

Una clave vcs.* que declares en OTEL_RESOURCE_ATTRIBUTES reemplaza el valor derivado para esa clave. Si declaras vcs.repository.url.full, Claude Code nunca lee el remoto e informa solo las claves que declares.

Si los clones HTTPS y SSH de un mismo repositorio informan valores diferentes, como en una instalación autoalojada cuya URL de clonación HTTPS incluye un prefijo de ruta que la URL SSH no tiene, declara vcs.repository.url.full en OTEL_RESOURCE_ATTRIBUTES junto con todas las demás claves vcs.* que quieras que se informen. Así, cada clon informa la identidad que declares.

Los atributos fluyen solo hacia tus propios exportadores; la telemetría de Anthropic descarta todas las claves vcs.*.

Métricas

Claude Code exporta las siguientes métricas. La columna Unidad muestra la cadena de unidad de OpenTelemetry adjunta a cada métrica; las métricas de conteo no llevan ninguna.

Cuando prometheus es el único exportador listado en OTEL_METRICS_EXPORTER, Claude Code omite las unidades USD, tokens y s de las métricas exportadas para que el scrape siga siendo un formato de texto de Prometheus válido. Los nombres de las métricas no cambian, y las configuraciones que combinan exportadores, como otlp,prometheus, conservan las unidades.

Detalles de las métricas

Cada métrica incluye los atributos estándar indicados arriba. Las métricas con atributos adicionales específicos del contexto se indican a continuación.

Contador de sesiones

Se incrementa al inicio de cada sesión.

Atributos:

• Todos los atributos estándar
• start_type: Cómo se inició la sesión. Uno de "fresh", "resume", "continue" o "agents_view". El valor "agents_view" identifica el proceso del panel claude agents, una interfaz local iniciada por el usuario y no una sesión conversacional. Filtra por este valor para separar los inicios de procesos de interfaz de las sesiones conversacionales en tus paneles.

Contador de líneas de código

Se incrementa cuando se agrega o elimina código.

Atributos:

• Todos los atributos estándar
• type: ("added", "removed")
• model: Identificador del modelo que hizo el cambio (por ejemplo, "claude-sonnet-5")

Contador de pull requests

Se incrementa cuando Claude Code crea un pull request o un merge request mediante un comando del shell o una herramienta MCP.

Atributos:

• Todos los atributos estándar

Contador de commits

Se incrementa al crear commits de git mediante Claude Code.

Atributos:

• Todos los atributos estándar

Contador de costos

Se incrementa después de cada solicitud a la API.

Los atributos agent.name, skill.name, plugin.name, mcp_server.name y mcp_tool.name redactan de forma predeterminada algunos nombres a un marcador "custom" o "third-party". Si configuras OTEL_LOG_TOOL_DETAILS=1, contienen los nombres reales. Antes de v2.1.273, los contadores de costos y de tokens y los eventos api_request, api_error y api_refusal contenían los valores redactados incluso con OTEL_LOG_TOOL_DETAILS=1 configurado.

Atributos:

• Todos los atributos estándar
• model: Identificador del modelo (por ejemplo, "claude-sonnet-5")
• query_source: Categoría del subsistema que emitió la solicitud. Uno de "main", "subagent" o "auxiliary"
• speed: "fast" cuando la solicitud usó el modo rápido. Ausente en caso contrario
• effort: Nivel de esfuerzo aplicado a la solicitud: "low", "medium", "high", "xhigh" o "max". Ausente cuando Claude Code no envía ningún nivel de esfuerzo, por ejemplo en un modelo que no admite esfuerzo.
• agent.name: Tipo de subagente que emitió la solicitud. Los nombres de agentes integrados y los agentes de plugins del marketplace oficial aparecen textualmente. Los demás nombres de agentes definidos por el usuario se reemplazan por "custom". Ausente cuando la solicitud no la emitió un tipo de subagente con nombre.
• skill.name: Skill activo para la solicitud, establecido por la herramienta Skill o un comando /, o heredado por un subagente generado. Los nombres de skills integrados, incluidos, definidos por el usuario y de plugins del marketplace oficial aparecen textualmente. Los nombres de skills de plugins de terceros se reemplazan por "third-party". Ausente cuando no hay ningún skill activo.
• plugin.name: Plugin propietario cuando el skill o el subagente activo lo proporciona un plugin. Los nombres de plugins del marketplace oficial aparecen textualmente. Los nombres de plugins de terceros se reemplazan por "third-party". Ausente cuando ni el skill ni el subagente tienen un plugin propietario.
• marketplace.name: Marketplace desde el que se instaló el plugin propietario. Solo se emite para plugins del marketplace oficial, incluso con OTEL_LOG_TOOL_DETAILS=1 configurado. Ausente en caso contrario.
• mcp_server.name: Servidor MCP cuyo resultado de herramienta consumió esta solicitud. Los nombres de servidores integrados, con proxy de claude.ai y del registro oficial aparecen textualmente. Los nombres de servidores configurados por el usuario se reemplazan por "custom". Ausente cuando la solicitud no consumió ningún resultado de herramienta MCP. Antes de v2.1.222, Claude Code establecía este atributo en cada solicitud posterior a una llamada a herramienta MCP, no solo en las solicitudes que consumían un resultado de herramienta, por lo que los paneles que lo agregan muestran un descenso después de actualizar.
• mcp_tool.name: Herramienta MCP cuyo resultado consumió esta solicitud, con el mismo comportamiento de redacción y de versión que mcp_server.name. Ausente cuando la solicitud no consumió ningún resultado de herramienta MCP.

Contador de tokens

Se incrementa después de cada solicitud a la API.

Atributos:

• Todos los atributos estándar
• type: ("input", "output", "cacheRead", "cacheCreation"). El tipo "input" excluye los tokens leídos de la caché de prompts o escritos en ella, que se cuentan en "cacheRead" y "cacheCreation". El tipo "cacheCreation" cuenta juntas las escrituras en caché con las duraciones de caché de cinco minutos y de una hora.
• model: Identificador del modelo (por ejemplo, "claude-sonnet-5")
• query_source: Categoría del subsistema que emitió la solicitud. Uno de "main", "subagent" o "auxiliary"
• speed: "fast" cuando la solicitud usó el modo rápido. Ausente en caso contrario
• effort: Nivel de esfuerzo aplicado a la solicitud. Consulta Contador de costos para más detalles.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribución de skill, plugin, agente y MCP para la solicitud. Consulta Contador de costos para ver las definiciones y el comportamiento de redacción.

Contador de decisiones de herramientas de edición de código

Se incrementa cuando el usuario acepta o rechaza el uso de las herramientas Edit, Write o NotebookEdit.

Atributos:

• Todos los atributos estándar
• tool_name: Nombre de la herramienta ("Edit", "Write", "NotebookEdit")
• decision: Decisión del usuario ("accept", "reject")
• source: De dónde provino la decisión. Uno de "config", "hook", "user_permanent", "user_temporary", "user_abort" o "user_reject". Consulta el Evento de decisión de herramienta para saber qué significa cada valor.
• language: Lenguaje de programación del archivo editado, como "TypeScript", "Python", "JavaScript" o "Markdown". Devuelve "unknown" para extensiones de archivo no reconocidas.

Contador de tiempo activo

Registra el tiempo real dedicado a usar activamente Claude Code, excluyendo el tiempo de inactividad. Esta métrica se incrementa durante las interacciones del usuario, como escribir y leer respuestas, y durante el procesamiento de la CLI, como la ejecución de herramientas y la generación de respuestas de IA.

Atributos:

• Todos los atributos estándar
• type: "user" para interacciones con el teclado, "cli" para la ejecución de herramientas y las respuestas de IA

Eventos

Claude Code exporta los siguientes eventos mediante logs/eventos de OpenTelemetry (cuando OTEL_LOGS_EXPORTER está configurado):

Atributos de correlación de eventos

Cuando un usuario envía un prompt, Claude Code puede hacer varias llamadas a la API y ejecutar varias herramientas. El atributo prompt.id te permite vincular todos esos eventos al prompt único que los desencadenó.

Para rastrear toda la actividad desencadenada por un único prompt, filtra tus eventos por un valor específico de prompt.id. Esto devuelve el evento user_prompt, cualquier evento api_request y cualquier evento tool_result que haya ocurrido mientras se procesaba ese prompt.

event.sequence empieza en 0 cada vez que se inicia un proceso de Claude Code y aumenta durante la vida de ese proceso. Sigue contando a través de /clear, que asigna un nuevo session.id. Si reanudas una sesión sin bifurcarla, la sesión conserva su session.id pero toma sus valores de event.sequence del proceso que la reanudó, por lo que dentro de una misma sesión un evento posterior puede tener un valor menor que uno anterior, o repetirlo. Para ordenar los eventos de una sesión, ordénalos por event.timestamp y usa event.sequence para ordenar los eventos que comparten una marca de tiempo.

Para la reconstrucción a nivel de mensaje, cada clase de evento incluye una clave que coincide con un campo de la transcripción de la sesión. El formato de las entradas de la transcripción es interno de Claude Code y cambia entre versiones, por lo que una canalización que une datos por estos campos puede romperse en cualquier versión; trata las uniones como específicas de la versión y no como un contrato estable:

• message.uuid en user_prompt, assistant_response y api_response_body
• request_id en los eventos de API, guardado como requestId en las entradas del asistente de la transcripción
• tool_use_id en los eventos tool_result y tool_decision, y en los eventos safety_event excepto los del final de un turno

Evento de prompt del usuario

Se registra cuando se envía un prompt, incluso en los turnos que Claude Code inicia por sí mismo.

Nombre del evento: claude_code.user_prompt

Atributos:

• Todos los atributos estándar
• event.name: "user_prompt"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• prompt_length: Longitud del prompt
• prompt: Contenido del prompt. Redactado de forma predeterminada. Configura OTEL_LOG_USER_PROMPTS=1 para incluirlo
• prompt_text: Mismo valor que prompt, redactado bajo la misma condición. Un backend que almacena nombres de atributos con puntos como objetos anidados lee prompt.id como id dentro de un objeto llamado prompt y puede perder la cadena del prompt. En ese caso, lee prompt_text. Requiere Claude Code v2.1.287 o posterior
• message.uuid: UUID del mensaje de usuario resultante, que coincide con la entrada guardada en la transcripción. Ausente en los despachos de comandos, que pueden producir cero o varios mensajes.
• command_name: Nombre del comando cuando el prompt invoca uno. Los nombres de comandos integrados e incluidos, como compact o debug, se emiten tal cual; los alias como reset se emiten tal como se escribieron y no con el nombre canónico. Los nombres de comandos personalizados, de plugins y de MCP se reducen a custom o mcp a menos que se configure OTEL_LOG_TOOL_DETAILS=1
• command_source: Origen del comando cuando está presente: builtin, custom o mcp. Los comandos proporcionados por plugins se informan como custom

Evento de respuesta del asistente

Se registra después de cada solicitud a la API que devuelve contenido de texto del modelo. Solo se incluyen los bloques de texto de la respuesta; los bloques de pensamiento y de uso de herramientas se excluyen.

Nombre del evento: claude_code.assistant_response

Atributos:

• Todos los atributos estándar
• event.name: "assistant_response"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• response_length: Longitud del texto de la respuesta en caracteres
• response: Texto de la respuesta, truncado en el límite de contenido (60 KB de forma predeterminada). Redactado como <REDACTED> de forma predeterminada. Configura OTEL_LOG_ASSISTANT_RESPONSES=1 para incluirlo. Cuando OTEL_LOG_ASSISTANT_RESPONSES no está configurada, lo controla OTEL_LOG_USER_PROMPTS, así que configura OTEL_LOG_ASSISTANT_RESPONSES=0 para mantener redactadas las respuestas mientras el registro de prompts está activado
• model: Identificador del modelo (por ejemplo, "claude-sonnet-5")
• request_id: ID de la solicitud a la API, descrito en Atributos de correlación de eventos
• message.uuid: UUID de la entrada final de la transcripción de la respuesta. Una respuesta de la API se guarda como una entrada de transcripción por bloque de contenido; esta es la última, desde la que se encadena el parentUuid del siguiente turno.
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact" o el nombre de un subagente

Evento de resultado de herramienta

Se registra cuando una herramienta completa su ejecución. No se emite si la llamada a herramienta fue rechazada; consulta el Evento de decisión de herramienta para los rechazos.

Nombre del evento: claude_code.tool_result

Atributos:

• Todos los atributos estándar
• event.name: "tool_result"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• tool_name: Nombre de la herramienta
• tool_use_id: Identificador único de esta invocación de la herramienta. Coincide con el tool_use_id que se pasa a los hooks, lo que permite correlacionar los eventos de OTel con los datos capturados por los hooks.
• request_id: el request_id de la respuesta de la API que contenía esta llamada a herramienta, para que puedas unir la llamada con los eventos de API de esa respuesta. Ausente cuando esa respuesta no tenía ID de solicitud o cuando ninguna respuesta de la API contenía la llamada. Requiere Claude Code v2.1.310 o posterior
• success: "true" o "false"
• duration_ms: Tiempo de ejecución en milisegundos
• error_type: Cadena de categoría de error cuando la herramienta falló, como "Error:ENOENT" o "ShellError"
• error (cuando OTEL_LOG_TOOL_DETAILS=1): Mensaje de error completo cuando la herramienta falló
• decision_type: Siempre "accept", ya que este evento solo se emite después de que la herramienta se ejecuta. Las llamadas rechazadas no producen un resultado de herramienta
• decision_source: De dónde provino la decisión de permisos. Uno de "config", "hook", "user_permanent" o "user_temporary". Consulta el Evento de decisión de herramienta para saber qué significa cada valor. Los orígenes exclusivos de rechazo "user_abort" y "user_reject" nunca aparecen en este evento.
• tool_input_size_bytes: Tamaño de la entrada de la herramienta serializada en JSON, en bytes
• tool_result_size_bytes: Tamaño del resultado de la herramienta en bytes
• mcp_server_scope: Identificador del alcance del servidor MCP (para herramientas MCP)
• vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (cuando OTEL_LOG_TOOL_DETAILS=1): la identidad del commit de un git commit exitoso ejecutado por la herramienta Bash o PowerShell. vcs.ref.head.revision es el SHA del commit, vcs.ref.head.name es la rama en la que se hizo el commit y vcs.ref.head.type es branch. El nombre y el tipo se omiten cuando el commit se hizo en un HEAD desacoplado. Requiere Claude Code v2.1.269 o posterior
• tool_parameters (cuando OTEL_LOG_TOOL_DETAILS=1): Cadena JSON que contiene parámetros específicos de la herramienta. Para los servidores integrados de Claude Desktop, en sesiones que pertenecen a Claude Desktop, el par mcp_server_name/mcp_tool_name se incluye incluso con el flag desactivado, la misma excepción definida por el host que en el Evento de decisión de herramienta. Los parámetros varían según la herramienta:
  • Para la herramienta Bash: incluye bash_command, full_command, timeout, description y dangerouslyDisableSandbox, además de git_commit_id y git_branch cuando un comando git commit tiene éxito. git_commit_id es el SHA completo del commit cuando el commit es el HEAD del directorio de trabajo de la sesión, y el SHA abreviado de git en caso contrario. git_branch es la rama en la que se hizo el commit, y se omite en un HEAD desacoplado
  • Para la herramienta Bash del espacio de trabajo de la aplicación de escritorio, que también informa tool_name como Bash: incluye solo bash_command, full_command y timeout
  • Para herramientas MCP: incluye mcp_server_name, mcp_tool_name
  • Para la herramienta Skill: incluye skill_name
  • Para la herramienta Agent o la herramienta Task heredada: incluye subagent_type
• tool_input (cuando OTEL_LOG_TOOL_DETAILS=1): Argumentos de la herramienta serializados en JSON. Los valores individuales de más de 512 caracteres se truncan, y el payload completo está limitado a ~4 K caracteres. Se aplica a todas las herramientas, incluidas las herramientas MCP.

Evento de solicitud a la API

Se registra para cada solicitud a la API de Claude.

Nombre del evento: claude_code.api_request

Atributos:

• Todos los atributos estándar
• event.name: "api_request"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• model: Modelo usado (por ejemplo, "claude-sonnet-5")
• cost_usd: Costo estimado en USD
• cost_usd_micros: Costo estimado en millonésimas de dólar estadounidense, emitido como un entero
• duration_ms: Duración de la solicitud en milisegundos
• input_tokens: Número de tokens de entrada, excluidos los tokens leídos de la caché de prompts o escritos en ella
• output_tokens: Número de tokens de salida
• cache_read_tokens: Número de tokens leídos de la caché
• cache_creation_tokens: Número de tokens usados para la creación de caché
• cache_creation_5m_tokens, cache_creation_1h_tokens: el número de tokens que la respuesta de la API informa como escritos en la caché con una duración de caché de cinco minutos y el número escrito con una duración de una hora. Ambos son 0 cuando la respuesta de la API no los informa, incluso cuando cache_creation_tokens es mayor que cero. Requiere Claude Code v2.1.300 o posterior
• request_id: ID de la solicitud a la API, como "req_011...", descrito en Atributos de correlación de eventos.
• client_request_id: UUID generado por el cliente y enviado como el encabezado de solicitud x-client-request-id; consulta la tabla de atributos de correlación de eventos para saber cuándo está presente
• speed: "fast" o "normal", que indica si el modo rápido estaba activo
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact" o el nombre de un subagente
• effort: Nivel de esfuerzo aplicado a la solicitud: "low", "medium", "high", "xhigh" o "max". Ausente cuando Claude Code no envía ningún nivel de esfuerzo, por ejemplo en un modelo que no admite esfuerzo.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribución de skill, plugin, agente y MCP para la solicitud. Consulta Contador de costos para ver las definiciones y el comportamiento de redacción.

Evento de error de la API

Se registra cuando falla una solicitud a la API de Claude.

Nombre del evento: claude_code.api_error

Atributos:

• Todos los atributos estándar
• event.name: "api_error"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• model: Modelo usado (por ejemplo, "claude-sonnet-5")
• error: Mensaje de error
• status_code: Código de estado HTTP como número. Ausente para errores que no son HTTP, como las fallas de conexión.
• duration_ms: Duración de la solicitud en milisegundos
• attempt: Número de intentos realizados, incluida la solicitud inicial. Detectar el agotamiento de reintentos indica cuándo se reinicia el conteo
• request_id: ID de la solicitud a la API, como "req_011...", descrito en Atributos de correlación de eventos.
• client_request_id: UUID generado por el cliente y enviado como el encabezado de solicitud x-client-request-id. Disponible incluso cuando una falla, como un tiempo de espera agotado o un error de conexión, nunca produjo un request_id del servidor; consulta la tabla de atributos de correlación de eventos para saber cuándo está presente.
• speed: "fast" o "normal", que indica si el modo rápido estaba activo
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact" o el nombre de un subagente
• effort: Nivel de esfuerzo aplicado a la solicitud. Ausente cuando Claude Code no envía ningún nivel de esfuerzo, por ejemplo en un modelo que no admite esfuerzo.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribución de skill, plugin, agente y MCP para la solicitud. Consulta Contador de costos para ver las definiciones y el comportamiento de redacción.

Evento de rechazo de la API

Se registra cuando una solicitud a la API devuelve stop_reason: "refusal". Los rechazos llegan en un flujo de respuesta exitoso y no como un error HTTP, por lo que el evento api_error no se activa para ellos. Este evento te permite rastrear la frecuencia de rechazos y agruparlos por los mismos atributos que api_request y api_error.

Nombre del evento: claude_code.api_refusal

Atributos:

• Todos los atributos estándar
• event.name: "api_refusal"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• model: Identificador del modelo de la solicitud
• request_id: ID de la solicitud a la API, como "req_011...", descrito en Atributos de correlación de eventos.
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact" o el nombre de un subagente. Consulta api_request para ver las definiciones.
• speed: "fast" cuando el modo rápido está activo, o "normal"
• attempt: Número de intento de reintento. El primer intento es 1.
• effort: Nivel de esfuerzo aplicado a la solicitud. Ausente cuando Claude Code no envía ningún nivel de esfuerzo, por ejemplo en un modelo que no admite esfuerzo.
• server_fallback_hop: true cuando el respaldo de modelo del lado del servidor de la API ya reintentó este rechazo en un modelo diferente, por lo que el usuario no vio este rechazo en particular. false cuando la solicitud terminó en un rechazo. Un mismo turno puede emitir tanto un evento de salto con true como un evento final posterior con false cuando el modelo de respaldo también rechaza.
• has_category: true cuando la respuesta de la API incluyó un stop_details.category de "cyber", "bio", "frontier_llm" o "reasoning_extraction". false cuando la respuesta no incluyó ninguna categoría o un valor fuera de ese conjunto. Ausente cuando server_fallback_hop es true, porque los bloques de salto no incluyen stop_details.
• has_explanation: true cuando la respuesta de la API incluyó un stop_details.explanation; en caso contrario, false. Ausente cuando server_fallback_hop es true.
• category: El valor de stop_details.category de la respuesta de la API. Uno de "cyber", "bio", "frontier_llm" o "reasoning_extraction". Solo presente cuando OTEL_LOG_TOOL_DETAILS=1 está configurado y has_category es true.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribución de skill, plugin, agente y MCP para la solicitud. Consulta Contador de costos para ver las definiciones y el comportamiento de redacción.

Evento de cuerpo de la solicitud a la API

Se registra para cada intento de solicitud a la API cuando OTEL_LOG_RAW_API_BODIES está configurada. Se emite un evento por intento, por lo que cada reintento con parámetros ajustados produce su propio evento.

Nombre del evento: claude_code.api_request_body

Atributos:

• Todos los atributos estándar
• event.name: "api_request_body"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• body: Parámetros de la solicitud a la API de Messages serializados en JSON, como el prompt del sistema, los mensajes y las herramientas, truncados en el límite de contenido (60 KB de forma predeterminada). El contenido de pensamiento extendido de turnos anteriores del asistente se redacta. Se emite solo en modo en línea (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Ruta absoluta a un archivo <dir>/<uuid>.request.json que contiene el cuerpo sin truncar. Se emite solo en modo de archivo (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Longitud del cuerpo sin truncar. Bytes UTF-8 cuando OTEL_LOG_RAW_API_BODIES=file:<dir>, o unidades de código UTF-16 cuando =1
• body_truncated: "true" cuando se produjo un truncamiento en línea. Ausente en modo de archivo y cuando no hubo truncamiento.
• model: Identificador del modelo de los parámetros de la solicitud
• query_source: Subsistema que emitió la solicitud (por ejemplo, "compact")
• request_body_id: UUID que identifica el cuerpo de la solicitud de este intento. El evento api_response_body del intento que tiene éxito incluye el mismo valor, por lo que puedes emparejar una respuesta con la solicitud exacta que la produjo. Requiere Claude Code v2.1.274 o posterior

Evento de cuerpo de la respuesta de la API

Se registra para cada respuesta exitosa de la API cuando OTEL_LOG_RAW_API_BODIES está configurada.

En modo de archivo (OTEL_LOG_RAW_API_BODIES=file:<dir>), Claude Code también agrega una línea JSON a <dir>/index.jsonl por cada respuesta exitosa, con los campos timestamp, session_id, query_source, model, request_id, message_id, message_uuid, request_file y response_file. Léelo para encontrar los archivos de solicitud y de respuesta detrás de un mensaje determinado de la transcripción sin consultar tu backend de telemetría. El archivo de índice requiere Claude Code v2.1.274 o posterior.

Nombre del evento: claude_code.api_response_body

Atributos:

• Todos los atributos estándar
• event.name: "api_response_body"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• body: Respuesta de la API de Messages serializada en JSON, incluidos el id, los bloques de contenido, el uso y el motivo de detención, truncada en el límite de contenido (60 KB de forma predeterminada). El contenido de pensamiento extendido se redacta. Se emite solo en modo en línea (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Ruta absoluta a un archivo <dir>/<request_id>.response.json que contiene el cuerpo sin truncar. Se emite solo en modo de archivo (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Longitud del cuerpo sin truncar. Bytes UTF-8 cuando OTEL_LOG_RAW_API_BODIES=file:<dir>, o unidades de código UTF-16 cuando =1
• body_truncated: "true" cuando se produjo un truncamiento en línea. Ausente en modo de archivo y cuando no hubo truncamiento.
• model: Identificador del modelo
• query_source: Subsistema que emitió la solicitud
• request_id: ID de la solicitud a la API, como "req_011...", descrito en Atributos de correlación de eventos.
• request_body_id: El request_body_id del evento api_request_body al que responde esta respuesta. Requiere Claude Code v2.1.274 o posterior
• message.id: ID del mensaje que la API asignó a la respuesta, el campo id del cuerpo de la respuesta. Requiere Claude Code v2.1.274 o posterior
• message.uuid: UUID de la entrada final de la transcripción de la respuesta. Junto con request_body_id, vincula un mensaje de la transcripción con los cuerpos de solicitud y respuesta que lo respaldan. Requiere Claude Code v2.1.274 o posterior

Evento de decisión de herramienta

Se registra cuando se toma una decisión de permisos sobre una herramienta (aceptar/rechazar).

Nombre del evento: claude_code.tool_decision

Atributos:

• Todos los atributos estándar

• event.name: "tool_decision"

• event.timestamp: Marca de tiempo ISO 8601

• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos

• tool_name: Nombre de la herramienta (por ejemplo, "Read", "Edit", "Write", "NotebookEdit")

• tool_use_id: Identificador único de esta invocación de la herramienta. Coincide con el tool_use_id que se pasa a los hooks, lo que permite correlacionar los eventos de OTel con los datos capturados por los hooks.

• request_id: el request_id de la respuesta de la API que contenía esta llamada a herramienta, para que puedas unir la llamada con los eventos de API de esa respuesta. Ausente cuando esa respuesta no tenía ID de solicitud o cuando ninguna respuesta de la API contenía la llamada. Requiere Claude Code v2.1.310 o posterior

• decision: "accept" o "reject"

• tool_source: Siempre presente. La procedencia de la herramienta, como un conjunto cerrado de valores definidos por la CLI:

  • "builtin": las herramientas propias de la CLI
  • "mcp": servidores MCP en general
  • "sdk_host_builtin_mcp": un servidor en proceso integrado en el propio Claude Desktop, en una sesión que pertenece a Claude Desktop. Una sesión pertenece a Claude Desktop cuando la inició desde uno de sus propios puntos de entrada, claude-desktop, claude-desktop-3p o local-agent, y esa sesión no es un hijo anidado; las sesiones anidadas, incluidas las que genera el propio Claude Code, informan estos servidores como "mcp"

• source: De dónde provino la decisión:

  • "config": Decidida automáticamente sin preguntar, por uno de estos orígenes:

    • Configuración del proyecto
    • Reglas de permitir o denegar en la configuración personal del usuario
    • Política administrada empresarial
    • Flags --allowedTools o --disallowedTools
    • El modo de permisos activo
    • El clasificador del modo automático, cuyo veredicto registra el mismo evento en classifier_verdict
    • Una concesión para el resto de la sesión, otorgada en una solicitud de permiso anterior en la misma sesión interactiva de la CLI
    • Que la herramienta sea intrínsecamente segura

    El valor de source no indica cuál de estas fuentes coincidió. Para averiguar cuál rechazó una llamada, busca el evento de seguridad con el mismo tool_use_id y lee sus atributos category y rule_source. Algunas llamadas rechazadas no tienen evento de seguridad.

    Claude Code también informa "config" cuando falla la propia solicitud de permiso. Por ejemplo, esa solicitud falla cuando el callback canUseTool del Agent SDK o la herramienta --permission-prompt-tool devuelven un resultado no válido, o cuando el flujo de entrada se cierra mientras la solicitud está pendiente.

  • "hook": Un hook PreToolUse o PermissionRequest devolvió la decisión.

  • "user_permanent": Se emite cuando el usuario eligió "Yes, and don't ask again for ..." en una solicitud de permiso, lo que guarda una regla de permitir en su configuración personal. En la CLI interactiva, esto se emite solo para esa elección en sí; las llamadas posteriores que coinciden con la regla guardada emiten "config" en su lugar. En sesiones del Agent SDK o sesiones no interactivas con -p, tanto la elección inicial como las coincidencias posteriores con la regla emiten "user_permanent". Se trata como una aceptación.

  • "user_temporary": Se emite cuando el usuario eligió "Yes" en una solicitud de permiso para una aprobación única, o eligió una opción que otorga acceso durante el resto de la sesión en una solicitud de edición o lectura de archivos. En la CLI interactiva, esto se emite solo para la elección en sí; las llamadas posteriores permitidas por esa autorización limitada a la sesión emiten "config" en su lugar. En sesiones del Agent SDK o sesiones no interactivas con -p, tanto la elección como las coincidencias posteriores emiten "user_temporary". Se trata como una aceptación.

  • "user_abort": Se emite cuando el usuario descartó la solicitud de permiso sin responder. En sesiones del Agent SDK y sesiones no interactivas con -p, esto incluye interrumpir el turno mientras hay una solicitud de permiso de canUseTool o --permission-prompt-tool pendiente. Se trata como un rechazo.

  • "user_reject": Se emite cuando el usuario eligió "No" al solicitársele. En la CLI interactiva, esto se emite solo para esa elección en sí; las llamadas que coinciden con una regla de denegar en la configuración personal del usuario emiten "config" en su lugar. En sesiones del Agent SDK o sesiones no interactivas con -p, las llamadas que coinciden con una regla de denegar en la configuración personal emiten "user_reject". Se trata como un rechazo.

• classifier_verdict: El veredicto del clasificador del modo automático para la llamada, o el motivo por el que Claude Code denegó la llamada cuando no llegó ninguno. Requiere Claude Code v2.1.301 o posterior

  • "allow": el clasificador aprobó la llamada
  • "block": el clasificador bloqueó la llamada. Una comprobación del clasificador que falla a mitad de camino también puede terminar como "block", por lo que una interrupción parcial del clasificador puede aparecer como más bloqueos en lugar de como "unavailable"
  • "no_verdict": la comprobación se ejecutó pero no dio ningún veredicto utilizable, por lo que Claude Code denegó la llamada. La denegación no significa que el clasificador considerara insegura la llamada
  • "unavailable": la solicitud al clasificador falló, por ejemplo por un rate limit, un tiempo de espera agotado o un error de conexión, por lo que Claude Code denegó la llamada. Con la revisión del clasificador del lado del servidor, también marca una llamada denegada porque el servidor no devolvió ningún veredicto de seguridad

  El atributo también aparece en las llamadas en modo plan cuando el clasificador revisa los comandos en modo plan. El atributo está ausente en estos casos:

  • Una regla de permisos de permitir o denegar decidió la llamada
  • Claude Code aprobó la llamada en modo automático sin consultar al clasificador
  • El usuario respondió la solicitud que Claude Code mostró después de bloqueos repetidos
  • En una ejecución con -p sin --permission-prompt-tool, Claude Code denegó la llamada después de bloqueos repetidos porque no había nadie para responder una solicitud. Ese evento informa decision como "reject" y source como "config"

• classifier_category (cuando OTEL_LOG_TOOL_DETAILS=1): El nombre de la regla integrada que el clasificador indicó al bloquear la llamada, en minúsculas con guiones bajos, como "data_exfiltration" para la regla Data Exfiltration. Requiere Claude Code v2.1.301 o posterior. El atributo está presente cuando se cumplen ambas condiciones:

  • classifier_verdict es "block"
  • El clasificador indicó exactamente una regla, y esa regla es integrada y no una que escribiste tú

  Antes de v2.1.302, el atributo también estaba ausente en cualquier bloqueo decidido por la revisión del clasificador del lado del servidor.

• permission_mode: Modo de permisos activo cuando comenzó la comprobación de permisos de esta llamada: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" o "auto". El modo manual aparece como "default". Una llamada de un subagente informa el modo de permisos del subagente y no el de la sesión. Requiere Claude Code v2.1.301 o posterior

• tool_parameters (cuando OTEL_LOG_TOOL_DETAILS=1): Cadena JSON que contiene parámetros específicos de la herramienta. Misma forma que en el Evento de resultado de herramienta, sin los campos posteriores a la ejecución como git_commit_id. Los valores pueden diferir de tool_result en una llamada aceptada si la decisión de permisos reescribe la entrada de la herramienta mediante updatedInput. Usa este atributo para ver qué comando se rechazó cuando decision es "reject".

  • Para herramientas "sdk_host_builtin_mcp": mcp_server_name y mcp_tool_name se incluyen incluso cuando OTEL_LOG_TOOL_DETAILS está desactivada, porque la aplicación host define estos nombres; sin ellos, una llamada rechazada a uno de estos servidores integrados no podría atribuirse en el flujo predeterminado. Para servidores MCP configurados por el usuario, el tool_name del evento es siempre el literal "mcp_tool", y los nombres del servidor y de la herramienta aparecen solo en tool_parameters con el flag activado; el contenido de los argumentos requiere el flag en todos los casos.
  • Para la herramienta Bash: incluye bash_command, full_command, timeout, description, dangerouslyDisableSandbox. La herramienta bash del espacio de trabajo de la aplicación de escritorio también informa tool_name como Bash, pero incluye solo bash_command, full_command y timeout
  • Para herramientas MCP: incluye mcp_server_name, mcp_tool_name
  • Para la herramienta Skill: incluye skill_name
  • Para la herramienta Agent o la herramienta Task heredada: incluye subagent_type

Si reduces el OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT del SDK de OpenTelemetry por debajo del número de atributos de un evento tool_decision, el SDK descarta los atributos que Claude Code estableció al final. El SDK los descarta antes que cualquier otro atributo, en este orden, omitiendo los que el evento no lleve:

1. parent_agent_id
2. agent_id
3. request_id
4. permission_mode
5. classifier_category
6. classifier_verdict

permission_mode, classifier_category y classifier_verdict se descartan en este orden en Claude Code v2.1.302 o posterior. parent_agent_id, agent_id y request_id requieren v2.1.310 o posterior.

Evento de seguridad

Se registra cuando una comprobación rechaza una llamada a herramienta o requiere una solicitud de permiso, excepto en las llamadas sin evento de seguridad. También se registra cuando el proxy de red del sandbox rechaza una conexión o solicitud, y cuando un hook bloquea un resultado. Requiere Claude Code v2.1.307 o posterior.

El evento se exporta con los demás eventos y no tiene un ajuste independiente. Los atributos propios del evento no contienen texto de comandos, rutas de archivos, nombres de host ni nombres de servidores y herramientas MCP. El registro también incluye los atributos estándar que tiene todo evento, que pueden incluir workspace.host_paths y los atributos del repositorio. Para ver el comando o la herramienta MCP detrás de un evento, configura OTEL_LOG_TOOL_DETAILS=1 y lee tool_parameters en el evento tool_decision correspondiente.

Nombre del evento: claude_code.safety_event

Atributos:

• Todos los atributos estándar
• event.name: "safety_event"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• category: La comprobación o el resultado, un valor de categoría
• decision: "accept", "reject" o "sent_back" cuando un hook bloqueó un resultado o el final de un turno
• decision_source: Quién o qué decidió, un valor de source de tool_decision o "other"
• reason_code: El motivo de la comprobación, como "rule:policySettings", "mode:dontAsk", "hook:PreToolUse", "classifier:auto-mode", "bashMiss:too-complex" o "unknown"
• reason_type: El tipo de motivo de la comprobación, como "rule", "subcommandResults", "mode", "hook", "classifier" o "asyncAgent"
• rule_source: Fuente de configuración de la regla involucrada, como "policySettings", "userSettings", "projectSettings", "localSettings", "flagSettings", "cliArg" o "session"
• grant_scope: "once" o "session" para una solicitud aprobada sin guardar una regla en un archivo de configuración
• circuit_breaker: La comprobación de seguridad integrada, como "dangerousRemoval", "outsideReadsBlocked" o "claudeSettingsFile"
• classifier_category: Con OTEL_LOG_TOOL_DETAILS=1, la regla integrada detrás de un bloqueo del modo automático, como "data_exfiltration"
• hook_event: "pre_tool_use" para un hook PreToolUse, o "post_tool_use", "post_tool_use_failure", "stop" o "subagent_stop" en eventos "hook_review"
• tool_class: "bash" para Bash y Monitor, "powershell", "file" para Read, Edit, Write, NotebookEdit, Glob y Grep, "web" para WebFetch y WebSearch, "mcp" u "other"
• tool_name: El nombre de la herramienta, como "Bash" para una herramienta integrada, o "mcp_tool", "skill_tool", "dynamic_tool" u "other_tool"
• tool_source: "builtin", "mcp" o "sdk_host_builtin_mcp", como en tool_decision
• permission_mode: El modo de permisos de la llamada cuando se comprobó: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" o "auto"
• tool_use_id: El ID de la llamada, como en tool_decision y tool_result
• sandbox_violation_count: Cuántas conexiones o solicitudes distintas del comando de la llamada rechazó el proxy de red del sandbox, de "0" a "20" como cadena. Los rechazos se cuentan para un comando en el sandbox que terminó en primer plano
• sandbox_enabled: "true" si el sandboxing está activado para la sesión; de lo contrario, "false"

Estos son los atributos propios del evento cuando una regla de denegar de la configuración administrada rechaza un comando Bash:

{
  "event.name": "safety_event",
  "category": "managed_policy",
  "decision": "reject",
  "decision_source": "config",
  "reason_code": "rule:policySettings",
  "rule_source": "policySettings",
  "tool_class": "bash",
  "tool_name": "Bash",
  "tool_source": "builtin",
  "permission_mode": "default",
  "tool_use_id": "toolu_01ABC123...",
  "sandbox_violation_count": "0",
  "sandbox_enabled": "false"
}

Categorías de eventos de seguridad

Para encontrar rechazos del proxy en cualquier category, filtra por un sandbox_violation_count que esté presente y no sea "0".

Llamadas sin evento de seguridad

Para encontrar llamadas rechazadas porque nadie pudo responder una solicitud sin categoría, busca eventos tool_decision que informen "reject" con source "config" y sin ningún evento de seguridad que comparta su tool_use_id. Estos rechazos ocurren en una ejecución con -p sin --permission-prompt-tool ni --permission-prompts none.

Busca un evento tool_decision para llamadas como estas, ya que no tienen evento de seguridad, excepto los eventos "sandbox_network", "sandbox_other" o "hook_review" enviados después de que se ejecutan:

• Una llamada aprobada en una solicitud sin categoría
• Una llamada que un callback canUseTool o una herramienta --permission-prompt-tool aprobó en una solicitud que solo requería un hook PreToolUse
• Una llamada a AskUserQuestion o ExitPlanMode, rechazada o no

Solicitudes sin categoría

Una solicitud no tiene categoría cuando ningún valor de category nombra su comprobación, como la solicitud del modo default para una edición dentro de tu directorio de trabajo.

Evento de cambio de modo de permisos

Se registra cuando cambia el modo de permisos, por ejemplo al alternar con Shift+Tab, al salir del modo plan o por una comprobación de acceso del modo automático.

Para agrupar las llamadas a herramientas según el modo de permisos en el que se comprobó cada una, usa permission_mode en el Evento de decisión de herramienta.

Nombre del evento: claude_code.permission_mode_changed

Atributos:

• Todos los atributos estándar
• event.name: "permission_mode_changed"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• from_mode: El modo de permisos anterior, por ejemplo "default", "plan", "acceptEdits", "auto" o "bypassPermissions"
• to_mode: El nuevo modo de permisos
• trigger: Qué causó el cambio, por ejemplo "shift_tab", "exit_plan_mode" o "auto_gate_denied". Ausente en algunos cambios, como cuando el SDK establece el modo de permisos mediante setPermissionMode()

Evento de autenticación

Se registra cuando se completa /login o /logout.

Nombre del evento: claude_code.auth

Atributos:

• Todos los atributos estándar
• event.name: "auth"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• action: "login" o "logout"
• success: "true" o "false"
• auth_method: Método de autenticación, como "oauth"
• error_category: Tipo categórico de error cuando la acción falló. El mensaje de error sin procesar nunca se incluye
• status_code: Código de estado HTTP como cadena cuando la acción falló con un error HTTP

Evento de conexión de servidor MCP

Se registra cuando un servidor MCP se conecta, se desconecta o no logra conectarse.

Nombre del evento: claude_code.mcp_server_connection

Atributos:

• Todos los atributos estándar
• event.name: "mcp_server_connection"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• status: "connected", "failed" o "disconnected"
• transport_type: Transporte del servidor, como "stdio", "sse" o "http"
• server_scope: Alcance en el que está configurado el servidor, como "user", "project" o "local"
• duration_ms: Duración del intento de conexión en milisegundos
• error_code: Código de error cuando la conexión falló
• is_plugin: true cuando el servidor lo proporciona un plugin, false en caso contrario
• plugin_id_hash (cuando is_plugin es true): Hash estable del nombre del plugin y del marketplace, para agrupar eventos por plugin sin exponer el nombre. Claude Code lo calcula como se describe en el evento de plugin cargado
• plugin.name (cuando is_plugin es true): Nombre del plugin que proporciona el servidor. Para plugins de terceros es la cadena literal "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1; esto evita que los nombres de plugins de terceros aparezcan en los registros de forma predeterminada. Los plugins de fuentes oficiales de Anthropic siempre se identifican por su nombre. Los atributos plugin_id_hash y plugin.name fluyen hacia tu propio backend de monitoreo y no se envían a Anthropic
• server_name (cuando OTEL_LOG_TOOL_DETAILS=1): Nombre configurado del servidor
• error (cuando OTEL_LOG_TOOL_DETAILS=1): Mensaje de error completo cuando la conexión falló

Evento de error interno

Se registra cuando Claude Code captura un error interno inesperado. Solo se registran el nombre de la clase del error y un código de estilo errno. El mensaje de error y el stack trace nunca se incluyen. Este evento no se emite cuando se ejecuta con Amazon Bedrock, Agent Platform de Google Cloud o Microsoft Foundry, ni cuando DISABLE_ERROR_REPORTING está configurada.

Nombre del evento: claude_code.internal_error

Atributos:

• Todos los atributos estándar
• event.name: "internal_error"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• error_name: Nombre de la clase del error, como "TypeError" o "SyntaxError"
• error_code: Código errno de Node.js, como "ENOENT", cuando está presente en el error

Evento de plugin instalado

Se registra cuando un plugin termina de instalarse, tanto desde el comando de CLI claude plugin install como desde la interfaz interactiva /plugin.

Nombre del evento: claude_code.plugin_installed

Atributos:

• Todos los atributos estándar
• event.name: "plugin_installed"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• marketplace.is_official: "true" si el marketplace es un marketplace oficial de Anthropic, "false" en caso contrario
• install.trigger: "cli" o "ui"
• plugin.name: Nombre del plugin instalado. Para marketplaces de terceros, se incluye solo cuando OTEL_LOG_TOOL_DETAILS=1
• plugin.version: Versión del plugin cuando está declarada en la entrada del marketplace. Para marketplaces de terceros, se incluye solo cuando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace desde el que se instaló el plugin. Para marketplaces de terceros, se incluye solo cuando OTEL_LOG_TOOL_DETAILS=1

Evento de plugin cargado

Se registra una vez por cada plugin habilitado al inicio de la sesión. Usa este evento para hacer un inventario de qué plugins están activos en toda tu flota, como complemento de plugin_installed, que registra la acción de instalación en sí.

Nombre del evento: claude_code.plugin_loaded

Atributos:

• Todos los atributos estándar
• event.name: "plugin_loaded"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• plugin.name: nombre del plugin. Para plugins fuera del marketplace oficial y del paquete integrado, el valor es "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: marketplace desde el que se instaló el plugin, cuando se conoce. Se redacta como "third-party" bajo la misma condición que plugin.name
• plugin.version: versión del manifiesto del plugin. Se incluye solo cuando el nombre no está redactado y el manifiesto declara una versión
• plugin.scope: categoría de procedencia del plugin: "official", "community", "org", "user-local" o "default-bundle"
• enabled_via: cómo llegó a habilitarse el plugin: "default-enable", "org-policy", "admin-install", "seed-mount" o "user-install". El valor "admin-install" significa que el plugin está configurado como obligatorio o de instalación automática para tu organización en Organization settings > Plugins & skills. Antes de v2.1.246, Claude Code informaba estos plugins como "user-install" o "seed-mount"
• plugin_id_hash: hash determinista del nombre del plugin y del marketplace, enviado solo a tu exportador configurado. Te permite contar los distintos plugins de terceros cargados en tu flota sin registrar sus nombres. Para plugins sincronizados desde claude.ai, Claude Code calcula el hash del nombre del plugin con el nombre del marketplace que claude.ai informa para el plugin, o con synced en caso contrario. Antes de v2.1.246, Claude Code no usaba en el hash el nombre del marketplace que informa claude.ai
• has_hooks: si el plugin aporta hooks, mediante configuración de hooks o como un mod
• has_mcp: si el plugin aporta servidores MCP
• host_owned_mcp: true cuando el host del SDK administra las conexiones MCP de este plugin y Claude Code omitió leer la configuración de servidores MCP del plugin, false en caso contrario
• skill_path_count: número de directorios de skills que declara el plugin
• command_path_count: número de directorios de comandos que declara el plugin
• agent_path_count: número de directorios de agentes que declara el plugin
• safe_mode: "true" cuando la sesión se inició con --safe-mode, "false" en caso contrario. En modo seguro, este evento informa solo el inventario configurado; los comandos, skills, hooks y servidores MCP del plugin no se cargan. Requiere Claude Code v2.1.169 o posterior

Evento de skill activado

Se registra cuando se invoca un skill, ya sea que Claude lo llame mediante la herramienta Skill o que tú lo ejecutes como un comando /.

Nombre del evento: claude_code.skill_activated

Atributos:

• Todos los atributos estándar
• event.name: "skill_activated"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• skill.name: Nombre del skill. Para skills definidos por el usuario y de plugins de terceros, el valor es el marcador "custom_skill" a menos que OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger: Cómo se activó el skill ("user-slash", "claude-proactive" o "nested-skill")
• skill.source: Desde dónde se cargó el skill (por ejemplo, "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind: "workflow" cuando el skill es un skill de flujo de trabajo. Ausente en caso contrario
• plugin.name (cuando OTEL_LOG_TOOL_DETAILS=1 o el plugin proviene de un marketplace oficial): Nombre del plugin propietario cuando el skill lo proporciona un plugin
• marketplace.name (cuando OTEL_LOG_TOOL_DETAILS=1 o el plugin proviene de un marketplace oficial): Marketplace desde el que se instaló el plugin propietario, cuando el skill lo proporciona un plugin

Evento de mención con @

Se registra cuando Claude Code resuelve una mención con @ en un prompt. No todas las menciones emiten un evento: las rutas de salida anticipada, como las denegaciones de permisos, los archivos demasiado grandes, los adjuntos de referencia PDF y las fallas al listar directorios, regresan sin registrar nada.

Cada vez que Claude Code lee un prompt, registra como máximo 100 eventos con un mention_type de "agent" y 100 con "mcp_resource". Las menciones que superan cualquiera de los dos límites se siguen resolviendo, pero no emiten ningún evento.

Nombre del evento: claude_code.at_mention

Atributos:

• Todos los atributos estándar
• event.name: "at_mention"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• mention_type: Tipo de mención ("file", "directory", "agent", "mcp_resource", "peer"). El valor "peer" significa que mencionaste otra de tus sesiones de Claude Code. Requiere Claude Code v2.1.232 o posterior
• success: Si la mención se resolvió correctamente ("true" o "false")

Evento de reintentos de la API agotados

Se registra una vez cuando una solicitud a la API falla después de más de un intento. Se emite junto con el evento api_error final.

Nombre del evento: claude_code.api_retries_exhausted

Atributos:

• Todos los atributos estándar
• event.name: "api_retries_exhausted"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• model: Modelo usado
• error: Mensaje de error final
• status_code: Código de estado HTTP como número. Ausente para errores que no son HTTP.
• total_attempts: Número total de intentos realizados
• total_retry_duration_ms: Tiempo real total entre todos los intentos
• speed: "fast" o "normal"

Evento de hook registrado

Se registra una vez por cada hook configurado al inicio de la sesión. Usa este evento para hacer un inventario de qué hooks están activos en toda tu flota, como complemento de los eventos por ejecución hook_execution_start y hook_execution_complete.

Nombre del evento: claude_code.hook_registered

Atributos:

• Todos los atributos estándar
• event.name: "hook_registered"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• hook_event: tipo de evento del hook, como "PreToolUse" o "PostToolUse"
• hook_type: tipo de implementación del hook: "command", "prompt", "mcp_tool", "http" o "agent"
• hook_source: dónde está definido el hook: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings" o "pluginHook"
• safe_mode: "true" cuando la sesión se inició con --safe-mode, "false" en caso contrario. Requiere Claude Code v2.1.169 o posterior
• hook_matcher (cuando OTEL_LOG_TOOL_DETAILS=1): la cadena del matcher de la configuración del hook, cuando hay uno configurado
• plugin.name (cuando hook_source es "pluginHook"): nombre del plugin que lo aporta. Para plugins fuera del marketplace oficial y del paquete integrado, el valor es "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1
• plugin_id_hash (cuando hook_source es "pluginHook"): hash determinista del nombre del plugin y del marketplace, enviado solo a tu exportador configurado. Te permite contar los distintos plugins que aportan hooks sin registrar sus nombres. Claude Code lo calcula como se describe en el evento de plugin cargado

Evento de inicio de ejecución de hook

Se registra cuando uno o más hooks comienzan a ejecutarse para un evento de hook.

Nombre del evento: claude_code.hook_execution_start

Atributos:

• Todos los atributos estándar
• event.name: "hook_execution_start"
• event.timestamp: Marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• hook_event: Tipo de evento del hook, como "PreToolUse" o "PostToolUse"
• hook_name: Nombre completo del hook, incluido el matcher, como "PreToolUse:Write"
• num_hooks: Número de comandos de hook coincidentes
• managed_only: "true" cuando solo se permiten hooks de política administrada
• hook_source: "policySettings" o "merged"
• safe_mode: "true" cuando la sesión se inició con --safe-mode, "false" en caso contrario. Requiere Claude Code v2.1.169 o posterior
• hook_definitions: Configuración del hook serializada en JSON. Se incluye solo cuando están habilitados tanto el rastreo beta detallado como OTEL_LOG_TOOL_DETAILS=1

Evento de ejecución de hooks completada

Se registra cuando todos los hooks de un evento de hook han terminado.

Nombre del evento: claude_code.hook_execution_complete

Atributos:

• Todos los atributos estándar
• event.name: "hook_execution_complete"
• event.timestamp: marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• hook_event: tipo de evento de hook
• hook_name: nombre completo del hook, incluido el matcher
• num_hooks: número de comandos de hook que coinciden
• num_success: cantidad que se completó correctamente
• num_blocking: cantidad que devolvió una decisión de bloqueo
• num_non_blocking_error: cantidad que falló sin bloquear
• num_cancelled: cantidad cancelada antes de completarse
• total_duration_ms: duración en tiempo real de todos los hooks que coinciden
• stdout_chars: total de caracteres de stdout de los hooks que coinciden y que se completaron correctamente. Requiere Claude Code v2.1.280 o posterior
• additional_context_chars: total de caracteres de additionalContext devueltos por los hooks que coinciden. Requiere Claude Code v2.1.280 o posterior
• system_message_chars: total de caracteres de systemMessage devueltos por los hooks que coinciden. Requiere Claude Code v2.1.280 o posterior
• initial_user_message_chars: total de caracteres de initialUserMessage devueltos por los hooks que coinciden. Requiere Claude Code v2.1.280 o posterior
• num_outputs_persisted: número de salidas de hooks que superan el límite de 10,000 caracteres y que Claude Code guardó en un archivo. Requiere Claude Code v2.1.280 o posterior
• managed_only: "true" cuando solo se permiten hooks de políticas administradas
• hook_source: "policySettings" o "merged"
• safe_mode: "true" cuando la sesión se inició con --safe-mode, "false" en caso contrario. Requiere Claude Code v2.1.169 o posterior
• hook_definitions: configuración de hooks serializada en JSON. Solo se incluye cuando están habilitados tanto el rastreo beta detallado como OTEL_LOG_TOOL_DETAILS=1

Evento de métricas de hooks de plugins

Se registra cuando un hook de un plugin del marketplace oficial emite métricas por invocación. Solo los plugins instalados desde un marketplace oficial de Anthropic pueden emitirlas. Los plugins de marketplaces de terceros y los hooks configurados por el usuario no emiten este evento. Usa este evento para supervisar el comportamiento de los plugins, como las tasas de hallazgos, los costos y las duraciones, desde tu propia pila de observabilidad.

Nombre del evento: claude_code.hook_plugin_metrics

Atributos:

• Todos los atributos estándar
• event.name: "hook_plugin_metrics"
• event.timestamp: marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• plugin_id: identificador del plugin con el formato <name>@<marketplace>
• hook_event: tipo de evento de hook que emitió las métricas
• Hasta 20 claves de métricas emitidas por el plugin. Los nombres coinciden con ^[a-z][a-z0-9_]{0,39}$. Los valores son booleanos o numéricos.

Evento de compactación

Se registra cuando se completa la compactación de la conversación.

Nombre del evento: claude_code.compaction

Atributos:

• Todos los atributos estándar
• event.name: "compaction"
• event.timestamp: marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• trigger: "auto" o "manual"
• success: "true" o "false"
• duration_ms: duración de la compactación
• pre_tokens: recuento aproximado de tokens antes de la compactación
• post_tokens: recuento aproximado de tokens después de la compactación
• error: mensaje de error cuando la compactación falló
• precompute_reuse: solo se establece cuando trigger es "manual", o cuando trigger es "auto" para una compactación por inactividad en una sesión interactiva de terminal. La compactación automática puede preparar un resumen en segundo plano antes de que se llene la ventana de contexto, y este atributo registra si la compactación reutilizó ese resumen preparado. "hit" significa que se reutilizó; "miss_custom_instructions", "miss_hook" y "miss_not_ready" indican el motivo por el que, en su lugar, se calculó un resumen nuevo

Evento de subagente completado

Se registra cuando un subagente termina y devuelve su resultado a la conversación que lo inició. Úsalo para agregar el uso de herramientas y el tiempo de ejecución por tipo de subagente; para agregar tokens o costos, usa el contador de tokens y el contador de costos filtrados por query_source "subagent", ya que el total_tokens de este evento solo abarca la solicitud final. La categoría "subagent" también cuenta las solicitudes de los hooks basados en agentes, que no emiten ningún evento de subagente.

Nombre del evento: claude_code.subagent_completed

Atributos:

• Todos los atributos estándar
• event.name: "subagent_completed"
• event.timestamp: marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• agent_type: el tipo de subagente. Los nombres de agentes integrados y los agentes de plugins del marketplace oficial aparecen literalmente; los demás nombres de agentes se sustituyen por "custom" a menos que se establezca OTEL_LOG_TOOL_DETAILS=1
• agent.source: de dónde proviene la definición del agente: built-in, plugin o la fuente de configuración que definió un agente personalizado, como userSettings o projectSettings
• is_built_in: si el subagente es un tipo de agente integrado
• is_async: si el subagente se ejecutó en segundo plano
• total_tokens: la huella de tokens de la solicitud final a la API del subagente: los tokens de entrada, de creación de caché, de lectura de caché y de salida de esa única solicitud, aproximadamente el tamaño del contexto del subagente al completarse. No es una suma de toda la ejecución
• total_tool_uses: número de llamadas a herramientas que el subagente realizó durante toda la ejecución
• duration_ms: tiempo de ejecución en milisegundos
• model: el modelo con el que se resolvió ejecutar el subagente
• final_model: el modelo que produjo la respuesta final del subagente, que difiere de model tras un cambio a mitad de la ejecución, como un respaldo
• model_swapped: si más de un modelo atendió las solicitudes del subagente
• plugin_id_hash, plugin.name: presentes para los agentes proporcionados por plugins. Los nombres de plugins del marketplace oficial aparecen literalmente; los demás nombres de plugins se sustituyen por "third-party" a menos que se establezca OTEL_LOG_TOOL_DETAILS=1

Evento de encuesta de comentarios

Se registra cuando se muestra o se responde una encuesta de calidad de la sesión. Consulta Encuestas de calidad de la sesión para saber qué recopilan las encuestas y cómo controlarlas.

Nombre del evento: claude_code.feedback_survey

Atributos:

• Todos los atributos estándar
• event.name: "feedback_survey"
• event.timestamp: marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• event_type: evento del ciclo de vida de la encuesta, por ejemplo "appeared", "responded" o "transcript_prompt_appeared"
• appearance_id: ID único que vincula los eventos emitidos para una instancia de encuesta
• survey_type: qué encuesta produjo el evento. "session" es el prompt de calificación "How is Claude doing?"
• response: la selección del usuario en los eventos responded
• enabled_via_override: true cuando se establece CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL. Se emite como booleano, no como cadena. Está presente en los eventos de encuesta session. Filtra por este atributo para confirmar que la sobrescritura se aplica en toda una flota

Evento de barrido de retención

Se registra una vez por cada ejecución del barrido de limpieza de retención, que elimina las transcripciones de sesiones y otros datos de la aplicación con una antigüedad mayor que el ajuste cleanupPeriodDays. Claude Code ejecuta el barrido en segundo plano como máximo una vez por sesión, y una ejecución que no elimina nada también emite el evento. Si Claude Code ejecutó el barrido en cualquier sesión en la misma máquina en las últimas 24 horas, retrasa el barrido de esta sesión al menos 10 minutos, por lo que una sesión que termina antes no emite nada. Cuando ejecutas claude -p con --bare, Claude Code no ejecuta el barrido y no emite nada.

Como todos los eventos de OTel de esta página, solo se envía al backend de telemetría que configures. Requiere Claude Code v2.1.227 o posterior.

Cuando Claude Code no puede determinar de forma segura el período de retención, pausa el barrido y emite el evento con result establecido en "skipped" y un skip_reason. Cuando la configuración administrada establece cleanupPeriodDays, el valor administrado fija el período de retención y el barrido se ejecuta incluso cuando un archivo de configuración de un alcance de menor prioridad está dañado o no es válido. Cuando no se puede leer el propio managed-settings.json, Claude Code sigue pausando el barrido a menos que el nivel administrado proporcione cleanupPeriodDays desde otro lugar, como la configuración administrada por el servidor o un archivo complementario de managed-settings.d/ junto al archivo dañado. Los atributos de contadores de eliminación solo están presentes cuando result es "complete".

Nombre del evento: claude_code.retention_sweep

Atributos:

• Todos los atributos estándar
• event.name: "retention_sweep"
• event.timestamp: marca de tiempo ISO 8601
• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos
• result: "complete" cuando el barrido se ejecutó, "skipped" cuando Claude Code lo pausó
• period_days: el valor de cleanupPeriodDays de la configuración combinada, en días, o 30 cuando ninguna fuente lo establece. En los eventos omitidos, el valor que habría usado el barrido, calculado a partir de las fuentes de configuración que Claude Code pudo leer
• used_default: "true" cuando ninguna fuente de configuración legible establece cleanupPeriodDays, "false" en caso contrario. En los eventos completados, "true" significa que se aplicó el valor predeterminado de 30 días
• skip_reason: por qué Claude Code pausó el barrido. Presente solo cuando result es "skipped":
  • "user_source_disabled": la configuración del usuario está excluida, por ejemplo mediante el flag --setting-sources o la opción settingSources del SDK, y ninguna fuente habilitada proporciona cleanupPeriodDays
  • "settings_unknowable": no se pudo leer o analizar un archivo de configuración, por lo que cleanupPeriodDays o desktopSessionCleanupPeriodDays podrían estar establecidos en un valor que Claude Code no puede ver
  • "settings_invalid_key_set": la configuración tiene errores de validación y cleanupPeriodDays o desktopSessionCleanupPeriodDays están establecidos explícitamente, por lo que recurrir al valor predeterminado podría eliminar o conservar archivos en contra de ese ajuste
  • "remote_settings_unknowable": una sesión en la pestaña Code de Claude Desktop en un despliegue de terceros solicitó la configuración administrada por el servidor. No recibió ninguna respuesta utilizable, por lo que cleanupPeriodDays podría estar establecido en un valor que Claude Code no puede ver
• transcripts_deleted: número de transcripciones de sesiones, los archivos ~/.claude/projects/*/*.jsonl de nivel superior, que eliminó el barrido
• transcripts_exempted_desktop: número de transcripciones que superan el período de retención y que el barrido conservó según la regla de Claude Desktop y Cowork. Estas no cuentan para files_past_cutoff. Requiere Claude Code v2.1.248 o posterior
• session_files_deleted: número de artefactos que eliminó el barrido de archivos de sesión: transcripciones más archivos complementarios por sesión, como archivos sidecar, grabaciones y resultados de herramientas
• artifacts_deleted: total de elementos que eliminó el barrido en los directorios de datos que abarca, incluidos los archivos de sesión. Algunos barridos cuentan un árbol de directorios eliminado completo como un solo elemento y algunas pasadas de limpieza no contribuyen al contador, así que trata el valor como un mínimo y no como un recuento exacto de archivos
• files_retained_fresh: archivos inspeccionados y conservados porque aún están dentro del período de retención. Solo los barridos por archivo los cuentan, por lo que el valor es un mínimo; un valor distinto de cero es el estado estable normal
• files_past_cutoff: archivos con una antigüedad mayor que el período de retención que el barrido no pudo eliminar, por ejemplo debido a un error de permisos o a un archivo que se mantiene abierto. El recuento también incluye cada carpeta obsoleta que el barrido encuentra en skills/synced/ o plugins/synced/, tanto si mueve la carpeta a la papelera como si no. Aparte de esas carpetas, un valor mayor que cero significa que hay archivos que sobrevivieron al período de retención configurado; cero no prueba que ninguno lo hiciera, porque una eliminación fallida de un directorio completo cuenta para error_count en su lugar
• error_count: número de errores que encontró el barrido al listar o eliminar archivos

Evento de configuración administrada resuelta

Se registra con la configuración administrada que resolvió una sesión: una vez al inicio de la sesión, de nuevo cuando cambia la configuración administrada o el estado del asistente de políticas durante la sesión, y cuando Claude Code se niega a iniciarse o finaliza la sesión por uno de los motivos que enumera el atributo error.type. Usa este evento para encontrar máquinas que se ejecutan con una fuente administrada inesperada, máquinas cuyo asistente de políticas está fallando y el motivo por el que una máquina se negó a iniciarse. Requiere Claude Code v2.1.274 o posterior.

De forma predeterminada, el evento incluye las fuentes administradas y el estado del asistente de políticas, pero no los ajustes en sí. Para agregar el atributo redactado managed_settings.settings y el resumen managed_settings.resolved_sha256, establece OTEL_LOG_MANAGED_SETTINGS=1:

• Establécelo en el bloque env de la configuración administrada, la configuración del usuario o --settings, o en el entorno con el que inicias Claude Code. Un valor en la configuración del proyecto o en la configuración local no lo activa, porque un repositorio clonado puede escribirlas.
• La configuración administrada por el servidor puede establecerlo sin mostrar el cuadro de diálogo de aprobación de seguridad, porque la variable solo agrega la propia política redactada de tu organización a un evento que tu organización ya recibe.

En una sesión interactiva en una carpeta en la que no has confiado, Claude Code no exporta el evento de rechazo.

Nombre del evento: claude_code.managed_settings_resolved

Atributos:

• Todos los atributos estándar

• event.name: "managed_settings_resolved"

• event.timestamp: marca de tiempo ISO 8601

• event.sequence: contador por proceso para ordenar eventos, descrito en Atributos de correlación de eventos

• managed_settings.trigger: "startup" para el evento de inicio de sesión, "change" cuando la configuración administrada o el estado del asistente de políticas cambió más adelante en la sesión, o "refused" cuando una política de configuración administrada detuvo la sesión. Claude Code envía un evento change solo cuando un atributo difiere del último evento que envió, y un valor de ajuste modificado cuenta incluso cuando OTEL_LOG_MANAGED_SETTINGS está desactivado

• error.type: por qué Claude Code detuvo la sesión. Solo está presente en los eventos refused:

  • "helper_failed": una ejecución del asistente de políticas falló
  • "policy_invalid": la configuración administrada contiene un error que impide que Claude Code se inicie, o una fuente de administración no se pudo cargar por un motivo distinto de una lectura denegada, por lo que Claude Code no puede comprobar el inicio de sesión de la organización ni la aplicación de proveedores
  • "provider_not_allowed": la sesión usaría un proveedor de API, o enviaría el tráfico de un proveedor a un host, que la lista administrada allowedProviders no permite. Requiere Claude Code v2.1.285 o posterior
  • "consent_rejected": el usuario rechazó el cuadro de diálogo de aprobación de seguridad de la configuración administrada por el servidor
  • "force_refresh_failed": falló la obtención de la configuración que requiere forceRemoteSettingsRefresh
  • "gateway_rejected": un gateway de Claude apps respondió a la carga de la configuración administrada con HTTP 403
  • "version_below_minimum": esta versión de Claude Code es inferior a requiredMinimumVersion o superior a requiredMaximumVersion
  • "_OTHER": la carga de la configuración administrada del gateway de Claude apps falló por otro motivo

• managed_settings.sources: cada fuente administrada que entrega al menos una clave de política, de mayor a menor prioridad, incluidas las fuentes cuyas claves no surten efecto con first-wins. Los valores son "remote", "plist" o "hklm" para la política de MDM o del sistema operativo, "file" para los archivos de configuración administrada y los archivos complementarios, "parent" cuando un host integrador proporciona la configuración, y "hkcu" para el valor del registro HKCU de Windows cuando Claude Code lo lee. Una fuente que solo contiene claves de control, o que Claude Code no pudo leer, no aparece en la lista. Se emite como un arreglo de cadenas, vacío cuando ninguna fuente administrada entrega una clave de política

• managed_settings.source_behavior: el valor de managedSourcesBehavior que leyó Claude Code, "first-wins" o "merge". "first-wins" cuando ninguna fuente establece la clave

• managed_settings.helper.state: estado del asistente de políticas que configura la fuente de MDM o de archivo seleccionada:

  • "ok": la salida del asistente sirve como configuración administrada
  • "bad_path", "not_a_file", "exit_nonzero", "timed_out", "oversize", "parse_failed", "envelope_invalid" o "schema_rejected": la última ejecución del asistente falló. Fallos del asistente describe los casos
  • "none": no hay ningún asistente configurado, o la fuente que lo configura no es una política de MDM ni un archivo de configuración administrada

• managed_settings.helper.applied: "output" mientras la propia salida del asistente sirve como configuración administrada, "none" cuando no es así

• managed_settings.helper.entry: "policyHelper" cuando Claude Code seleccionó un policyHelper. Ausente cuando no seleccionó ningún asistente

• managed_settings.helper.path: la path configurada del asistente. Está presente siempre que Claude Code seleccionó un asistente, independientemente de si OTEL_LOG_MANAGED_SETTINGS está establecido

• managed_settings.resolved_sha256 (cuando OTEL_LOG_MANAGED_SETTINGS=1): SHA-256 de la configuración administrada resuelta antes de la redacción, serializada como JSON con las claves ordenadas recursivamente y sin espacios en blanco. Las máquinas con el mismo resumen ejecutan la misma política. Claude Code envía el resumen solo con la habilitación explícita porque una política corta se puede recuperar calculando el hash de conjeturas. Ausente cuando no se resolvió ninguna configuración administrada, y en los eventos refused

• managed_settings.settings (cuando OTEL_LOG_MANAGED_SETTINGS=1): los nombres y la estructura de la configuración administrada resuelta como una cadena JSON, con los valores redactados. Ausente en los eventos refused. Claude Code lo construye a partir de su esquema de configuración:

  • Se exporta un nombre de ajuste que el esquema declara, y se omite una clave que no declara
  • Los booleanos, los números y los valores de cadena que el esquema restringe a un conjunto fijo de opciones, como permissions.defaultMode, se exportan tal cual. sandbox.network.httpProxyPort y sandbox.network.socksProxyPort se exportan como "[REDACTED]"
  • Cualquier otra cadena, como model, apiKeyHelper, cada valor de env, cada URL y cada comando, se exporta como "[REDACTED]"
  • Los nombres de las entradas de los mapas, como los nombres de variables de env y los IDs de plugins, se exportan tal cual. Un ajuste cuyas entradas el esquema no tipa, como vimInsertModeRemaps, se exporta como un único "[REDACTED]", y sandbox.ignoreViolations se exporta como una lista de sus listas de rutas sin los patrones de comandos
  • Una lista conserva su longitud, con cada entrada redactada según las mismas reglas
  • Una regla de permissions.allow, permissions.deny o permissions.ask se exporta como el nombre de su herramienta con el contenido redactado, como Read([REDACTED]), cuando la herramienta está integrada en esta versión de Claude Code o es una referencia mcp__ como mcp__jira__create_issue. Cualquier otra regla se exporta como "[REDACTED]"
  • Los hooks siguen las mismas reglas, por lo que se muestran los campos numéricos y de opciones fijas como type y timeout, mientras que cada comando, URL, matcher y condición if se exporta como "[REDACTED]"

  Por ejemplo, una configuración administrada con apiKeyHelper, dos variables de env y una regla de denegación se exporta como {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}.

  Claude Code recorta el valor a 8 KB de UTF-8, y el valor recortado no es JSON válido

• managed_settings.settings_truncated (cuando managed_settings.settings está presente): true cuando Claude Code recortó managed_settings.settings a 8 KB, false en caso contrario. Se emite como booleano, no como cadena

Interpretar datos de métricas y eventos

Las métricas y eventos exportados admiten una variedad de análisis:

Monitoreo de uso

Monitoreo de costos

La métrica claude_code.cost.usage ayuda con:

• Rastrear tendencias de uso entre equipos o individuos
• Identificar sesiones de alto uso para optimización
• Atribuir gastos a habilidades, plugins, o tipos de subagente específicos a través de los atributos skill.name, plugin.name, y agent.name

[!NOTE]

Las métricas de costo son aproximaciones. Para datos de facturación oficiales, consulte su proveedor de API (Claude Console, Amazon Bedrock, o Google Cloud's Agent Platform).

Claude Code cuenta cada respuesta en streaming para las métricas de costo y token exactamente una vez, incluso cuando un gateway o proxy detrás de ANTHROPIC_BASE_URL envía el uso en streaming de forma progresiva a lo largo de múltiples frames.

Alertas y segmentación

Alertas comunes a considerar:

• Picos de costo
• Consumo inusual de tokens
• Alto volumen de sesiones de usuarios específicos

Todas las métricas pueden segmentarse por los atributos estándar. El atributo model está disponible en claude_code.token.usage, claude_code.cost.usage y claude_code.lines_of_code.count.

Los desgloses por modelo de confirmaciones solo pueden aproximarse uniéndose contra las métricas de token o costo en session.id, ya que una sesión puede abarcar múltiples modelos. Filtre el lado de token o costo a filas donde query_source es "main" para que las solicitudes auxiliares y de subagente no atribuyan los compromisos de la sesión a un modelo que no los realizó.

Detectar agotamiento de reintentos

Claude Code reintenta solicitudes de API fallidas internamente y emite un único evento claude_code.api_error solo después de rendirse, por lo que el evento en sí es la señal terminal para esa solicitud. Los intentos de reintento intermedios no se registran como eventos separados.

El atributo attempt en el evento registra el número de intentos. CLAUDE_CODE_MAX_RETRIES tiene un valor predeterminado de 10 y está limitado a 15; con CLAUDE_CODE_RETRY_WATCHDOG establecido, el valor predeterminado es mayor y no hay límite.

Cuando la solicitud agota todos los reintentos en un error transitorio, attempt es como máximo uno más que ese límite efectivo: 11 por defecto.

Un valor más bajo aún puede significar que los reintentos se agotaron: attempt vuelve a empezar desde 1 cada vez que Claude Code vuelve a emitir la solicitud tras una falla de streaming.

Para distinguir una sesión que se recuperó de una que se estancó, agrupe eventos por session.id y verifique si existe un evento api_request posterior después del error.

Análisis de eventos

Los datos de eventos proporcionan información detallada sobre las interacciones de Claude Code:

Patrones de Uso de Herramientas: analice eventos de resultado de herramientas para identificar:

• Herramientas más utilizadas frecuentemente
• Tasas de éxito de herramientas
• Tiempos de ejecución promedio de herramientas
• Patrones de error por tipo de herramienta

Monitoreo de Rendimiento: rastree duraciones de solicitudes de API y tiempos de ejecución de herramientas para identificar cuellos de botella de rendimiento.

Asignar tokens de entrada a las convenciones semánticas GenAI de OpenTelemetry

Claude Code exporta los conteos de tokens de entrada tal como aparecen en el bloque de uso de la respuesta de la API, por lo que estos valores excluyen los tokens leídos desde o escritos en la caché de prompts:

• input_tokens en el span claude_code.llm_request y en el evento api_request
• El tipo "input" de la métrica claude_code.token.usage

Claude Code no establece atributos gen_ai.usage.*. Las convenciones semánticas GenAI de OpenTelemetry indican que gen_ai.usage.input_tokens debe incluir los tokens leídos desde y escritos en la caché. Para calcular ese total:

• Desde el span o el evento: suma input_tokens, cache_read_tokens y cache_creation_tokens
• Desde la métrica claude_code.token.usage: suma sus tipos "input", "cacheRead" y "cacheCreation"

Las convenciones también definen atributos separados para lecturas y escrituras de caché:

• cache_read_tokens corresponde a gen_ai.usage.cache_read.input_tokens
• cache_creation_tokens corresponde a gen_ai.usage.cache_write.input_tokens. Las versiones anteriores de las convenciones nombran el atributo de escritura de caché gen_ai.usage.cache_creation.input_tokens, así que usa el nombre que espera tu backend.

Auditar eventos de seguridad

Los eventos de OpenTelemetry son la fuente de datos de auditoría para la actividad de Claude Code. Cada evento lleva atributos de identidad que vinculan llamadas de herramientas, actividad MCP y decisiones de permisos al usuario que las desencadenó. El exportador de registros OTLP puede entregar estos eventos a cualquier plataforma de Gestión de Información y Eventos de Seguridad (SIEM) con un receptor OTLP, o a un Recopilador de OpenTelemetry que reenvíe a su SIEM.

Atribuir acciones a usuarios

Los atributos estándar en cada evento incluyen la identidad del usuario autenticado: user.email, user.account_uuid, user.account_id, y organization.id cuando se inicia sesión con una cuenta de Claude o, en una sesión en la nube, cuando las credenciales propias de la sesión las llevan, más user.id y el session.id por sesión. user.id es un identificador con alcance de instalación, excepto en sesiones que inician sesión en una Claude apps gateway a través de /login, donde es el asunto del IdP del token emitido por la puerta de enlace.

En una sesión que inicia un desarrollador, las llamadas de herramientas MCP, comandos Bash y ediciones de archivos se atribuyen por lo tanto al desarrollador. Claude Code no actúa bajo una cuenta de servicio separada; la identidad registrada en cada evento es la propia cuenta de Claude del desarrollador, o la identidad del IdP del desarrollador en una sesión de Claude apps gateway. En sesiones de canales de Claude Tag, Claude funciona como la identidad compartida de su organización en su lugar.

Cuando Claude Code se autentica con una clave de API directa, o contra Amazon Bedrock, Google Cloud's Agent Platform, o Microsoft Foundry, no hay cuenta de Claude en la sesión y solo user.id y session.id se rellenan. En estas implementaciones, adjunte la identidad del usuario usted mismo con OTEL_RESOURCE_ATTRIBUTES, establecido por usuario a través del archivo de configuración administrada o un contenedor de lanzamiento. Las sesiones de Claude apps gateway no necesitan nada de esto: consulte Atributos estándar para la identidad que sus exportaciones llevan.

export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

Auditar actividad MCP

Para capturar la actividad del servidor MCP con detalle completo de llamadas, habilite el exportador de registros y establezca OTEL_LOG_TOOL_DETAILS=1. Cada operación MCP produce entonces eventos estructurados que llevan el nombre del servidor, nombre de la herramienta y argumentos de llamada junto con los atributos de identidad estándar:

Sin OTEL_LOG_TOOL_DETAILS, estos eventos descartan el detalle de identificación:

• tool_result: mantiene mcp_server_scope y un tool_name redactado al literal "mcp_tool" para servidores configurados por el usuario, omite el contenido de los argumentos. Para los servidores integrados de Claude Desktop, en sesiones que Claude Desktop posee, también mantiene el par mcp_server_name/mcp_tool_name dentro de tool_parameters, la misma excepción autorizada por el host que tool_decision
• tool_decision: mantiene tool_source y un tool_name redactado al literal "mcp_tool" para servidores configurados por el usuario, omite el contenido de los argumentos. Para los servidores integrados de Claude Desktop, en sesiones que Claude Desktop posee, también mantiene el par mcp_server_name/mcp_tool_name dentro de tool_parameters
• mcp_server_connection: omite server_name y el mensaje de error, pero mantiene is_plugin, plugin_id_hash, y plugin.name, con nombres de plugins que no son de Anthropic redactados al literal "third-party", por lo que los servidores proporcionados por plugins siguen siendo distinguibles sin registro detallado

Mapear preguntas de seguridad a eventos

Al construir reglas de detección, busque la señal que desea monitorear y consulte su backend para el evento correspondiente y atributos:

Claude Code emite solo el flujo de eventos sin procesar. La detección de anomalías, establecimiento de línea base, correlación entre sesiones y alertas son responsabilidad de su SIEM o backend de observabilidad.

Mapear rutas de salida a controles administrados y eventos

La tabla empareja las rutas que pueden sacar contenido de la sesión de una máquina, además de la retención local, con las claves de configuración administrada que las restringen y los eventos que las registran. Para ver lo que el propio Claude Code envía a Anthropic, como los informes de /feedback, consulta Uso de datos. Los nombres enlazan a sus entradas de referencia, que indican los valores y los valores predeterminados.

Las entradas de allowedHttpHookUrls, managed-mcp.json y los eventos de hooks requieren más de lo que muestra la tabla:

• allowedHttpHookUrls: las entradas se combinan entre los archivos de configuración, por lo que un desarrollador puede agregar entradas a una lista administrada vacía. allowManagedHooksOnly decide qué hooks se ejecutan
• managed-mcp.json: para desactivar MCP, consulta Deshabilitar MCP por completo. Para confirmar que Claude Code lee el archivo, consulta Validar la configuración
• Eventos de hooks: Claude Code registra hook_execution_start y hook_execution_complete una vez por evento de hook, abarcando todos los hooks coincidentes. OTEL_LOG_TOOL_DETAILS=1 por sí solo no registra la URL de un hook HTTP. La configuración del hook aparece solo en hook_definitions, que además requiere el tracing beta detallado

OTEL_LOG_TOOL_DETAILS=1 agrega cadenas de comandos, nombres de servidores y herramientas, y la entrada de las herramientas a estos eventos. Ese detalle puede contener el mismo contenido sensible que la propia sesión, así que habilítalo solo cuando tu recopilador esté aprobado para almacenar ese contenido.

Verificar el barrido de retención

Para dar a todas las máquinas el mismo período de retención, establece cleanupPeriodDays en la configuración administrada. Para verificar que las máquinas ejecutan el barrido con ese valor, recopila el evento retention_sweep. period_days y los contadores son cadenas, así que conviértelos a números antes de compararlos.

Una máquina que funciona según lo previsto puede quedarse sin evento por motivos como estos:

• Nadie inicia Claude Code: no se ejecuta ningún barrido, y la máquina conserva sus datos hasta el siguiente inicio
• Una sesión permanece abierta: Claude Code ejecuta el barrido como máximo una vez por sesión
• Una sesión termina antes de tiempo: un barrido que no ha terminado cuando la sesión se cierra no emite nada, y tampoco uno que se detiene por un error inesperado

El barrido no cubre todas las rutas. Se conservan hasta que los elimines enumera lo que se conserva, y Borrar datos locales muestra cómo eliminarlo.

Enviar eventos a un SIEM

Apunte OTEL_EXPORTER_OTLP_LOGS_ENDPOINT al receptor OTLP de su SIEM, o a un Recopilador de OpenTelemetry que reenvíe a la API de ingesta nativa de su SIEM. El siguiente ejemplo de configuración de ajustes administrados exporta solo eventos, con detalle completo de herramientas habilitado para auditoría de MCP y Bash:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

Para confirmar que los eventos llegan, envíe un mensaje en una sesión que se ejecute bajo esta configuración y verifique su SIEM para el evento claude_code.user_prompt. Si nada llega, inicie Claude Code con claude --debug-file <path> y verifique ese registro para errores de exportación [3P telemetry].

Consideraciones de backend

Tu elección de backends de métricas, registros y trazas determina los tipos de análisis que puedes realizar:

Backends para métricas

• Bases de datos de series temporales: Cálculos de tasa, métricas agregadas
• Almacenes columnares: Consultas complejas, análisis de usuario único
• Plataformas de observabilidad completas: Consultas avanzadas, visualización, alertas

Backends para eventos y registros

• Sistemas de agregación de registros: Búsqueda de texto completo, análisis de registros
• Almacenes columnares: Análisis de eventos estructurados
• Plataformas de observabilidad completas: Correlación entre métricas y eventos

Backends para trazas

Elige un backend que admita almacenamiento de trazas distribuidas y correlación de spans:

• Sistemas de trazas distribuidas: Visualización de spans, cascadas de solicitudes, análisis de latencia
• Plataformas de observabilidad completas: Búsqueda de trazas y correlación con métricas y registros

Para organizaciones que requieren métricas de Usuarios Activos Diarios/Semanales/Mensuales (DAU/WAU/MAU), considera backends que admitan consultas de valores únicos eficientes.

Información del servicio

Todas las métricas y eventos se exportan con los siguientes atributos de recurso:

• service.name: claude-code para sesiones de terminal, claude-code-desktop para sesiones locales iniciadas desde la pestaña Code en la aplicación Claude Desktop
• service.version: Versión actual de Claude Code, o la versión de la aplicación Desktop para sesiones locales de la pestaña Code
• os.type: Tipo de sistema operativo (por ejemplo, linux, darwin, windows)
• os.version: Cadena de versión del sistema operativo
• host.arch: Arquitectura del host (por ejemplo, amd64, arm64)
• wsl.version: Número de versión de WSL (solo presente cuando se ejecuta en Windows Subsystem for Linux)
• Nombre del Medidor: com.anthropic.claude_code

Si tus canalizaciones de recopilador o paneles filtran por service.name = claude-code, agrega claude-code-desktop al filtro para capturar también la telemetría de sesiones locales de la pestaña Code.

Recursos de medición de ROI

Para una guía completa sobre cómo medir el retorno de inversión para Claude Code, incluyendo configuración de telemetría, análisis de costos, métricas de productividad e informes automatizados, consulta la Guía de Medición de ROI de Claude Code. Este repositorio proporciona configuraciones de Docker Compose listas para usar, configuraciones de Prometheus y OpenTelemetry, y plantillas para generar informes de productividad integrados con herramientas como Linear.

Seguridad y privacidad

• La exportación de OpenTelemetry a tu backend es opcional y requiere configuración explícita. Para la telemetría operativa separada de Anthropic y cómo deshabilitarla, consulta Uso de datos
• Los contenidos de archivos sin procesar y fragmentos de código no se incluyen en métricas o eventos. Las trazas de span son una ruta de datos separada: consulta la viñeta OTEL_LOG_TOOL_CONTENT a continuación
• Cuando está autenticado a través de OAuth, user.email se incluye en atributos de telemetría, enviados solo al punto final de OTel que configures, nunca a Anthropic. Si esto es una preocupación para tu organización, trabaja con tu backend de telemetría para filtrar o redactar este campo
• El contenido del prompt del usuario no se recopila por defecto. Solo se registra la longitud del prompt. Para incluir el contenido del prompt, establece OTEL_LOG_USER_PROMPTS=1. Cuando está habilitado:

  • Los eventos user_prompt llevan el texto del prompt en dos atributos, prompt y prompt_text. Si eliminas o enmascaras el texto del prompt del evento por nombre de atributo en tu recopilador, nombra ambos atributos en la regla

    Este procesador attributes de OpenTelemetry Collector elimina ambos atributos en los pipelines que lo incluyen:

    processors:
      attributes/drop-prompt-text:
        actions:
          - key: prompt
            action: delete
          - key: prompt_text
            action: delete
    

  • Con el rastreo activado, el span claude_code.interaction lleva el texto del prompt en su atributo user_prompt

  • Bajo el rastreo beta detallado, los spans también llevan los nuevos mensajes del usuario, resultados de herramientas y recordatorios del sistema enviados con cada solicitud, el texto del prompt del sistema y la salida del modelo. Atributos de contenido bajo el rastreo beta detallado enumera cada atributo. El evento claude_code.system_prompt lleva el prompt del sistema completo

• El texto de respuesta del asistente no se recopila por defecto. Solo se registra la longitud de la respuesta. Para incluir texto de respuesta, establece OTEL_LOG_ASSISTANT_RESPONSES=1. Como todos los datos de OpenTelemetry de Claude Code, el texto de respuesta se envía solo al endpoint de OTel que configures, nunca a Anthropic. Cuando esta variable no está establecida, OTEL_LOG_USER_PROMPTS se utiliza como respaldo, así que establece OTEL_LOG_ASSISTANT_RESPONSES=0 si deseas contenido del prompt sin contenido de respuesta en los eventos. Bajo el rastreo beta detallado, el span claude_code.llm_request sigue llevando la salida del modelo en response.model_output, que sigue a OTEL_LOG_USER_PROMPTS en lugar de a esta variable
• Los argumentos de entrada de herramientas y parámetros no se registran por defecto. Para incluirlos, establece OTEL_LOG_TOOL_DETAILS=1. Para los servidores integrados de Claude Desktop, en sesiones que Claude Desktop posee, tool_decision y tool_result llevan el par mcp_server_name/mcp_tool_name, nombres creados por el host en lugar de contenido de argumentos, incluso con el flag desactivado. Estos datos se envían solo al endpoint de OTEL que configures, nunca a Anthropic. Los argumentos aún pueden contener valores sensibles, así que configura tu backend de telemetría para filtrar o redactar estos atributos según sea necesario. Cuando está habilitado:
  • Los eventos tool_result y tool_decision incluyen un atributo tool_parameters con comandos Bash, nombres de servidor MCP y herramienta, y nombres de skills. Los campos como full_command se emiten sin truncar
  • Los eventos tool_result además incluyen un atributo tool_input con rutas de archivo, URLs, patrones de búsqueda y otros argumentos. Los valores individuales superiores a 512 caracteres se truncan y el total está limitado a aproximadamente 4 K caracteres
  • Los eventos user_prompt incluyen el command_name verbatim para comandos personalizados, de plugin y MCP
  • Los contadores de costo y token y los eventos api_request, api_error y api_refusal llevan nombres reales de agente, skill, plugin y servidor MCP y herramienta en sus atributos de atribución
  • El span claude_code.tool lleva atributos derivados de la entrada como file_path. Bajo el rastreo beta detallado también lleva un atributo tool_input
• El contenido de herramientas no se registra en spans de trazas por defecto. Para incluirlo, establece OTEL_LOG_TOOL_CONTENT=1. El span claude_code.tool entonces lleva un evento de span tool.output con contenidos de archivo sin procesar, salida de comandos Bash, y lo que devuelven herramientas MCP, WebFetch y WebSearch, truncado en el límite de contenido (60 KB por defecto) por atributo. Los resultados de herramientas MCP, WebFetch y WebSearch requieren Claude Code v2.1.283 o posterior. El contenido de herramientas también llega a los spans a través de new_context, cuya puerta difiere por span. Configura tu backend de telemetría para filtrar o redactar estos atributos según sea necesario
• Los cuerpos de solicitud y respuesta de la API de Mensajes de Anthropic sin procesar no se registran por defecto. Para incluirlos, establece OTEL_LOG_RAW_API_BODIES en tu shell, configuración de usuario o configuración administrada. Se ignora en configuración de proyecto y local. Los cuerpos contienen el historial de conversación completo, incluido el mensaje del sistema, cada turno anterior de usuario y asistente, y resultados de herramientas, así que habilitar esto implica consentimiento a todo lo que las otras banderas de contenido OTEL_LOG_* revelarían. Claude Code siempre redacta el contenido de pensamiento extendido de Claude de estos cuerpos, independientemente de otras configuraciones. El valor que estableces determina cómo Claude Code entrega los cuerpos:

  • Con =1, Claude Code emite eventos de registro api_request_body y api_response_body para cada llamada de API. El atributo body de los eventos lleva la carga útil serializada en JSON, truncada en el límite de contenido (60 KB por defecto)

  • Con =file:<dir>, Claude Code escribe cuerpos sin truncar en archivos .request.json y .response.json bajo ese directorio, y los eventos llevan una ruta body_ref en su lugar del cuerpo en línea. Envía el directorio con un recopilador de registros o sidecar en lugar de a través del flujo de telemetría.

    Para cada respuesta exitosa, Claude Code también añade una línea a index.jsonl en ese directorio, vinculando el archivo de respuesta al archivo de solicitud que lo produjo y al mensaje de transcripción en el que se convirtió. Cada línea no contiene contenido de mensaje, y la sección evento de cuerpo de respuesta de API enumera sus campos. El archivo de índice requiere Claude Code v2.1.274 o posterior

Monitorear Claude Code en Amazon Bedrock

Para orientación detallada sobre monitoreo de uso de Claude Code para Amazon Bedrock, consulta Implementación de Monitoreo de Claude Code (Amazon Bedrock).