Encabezados dinámicos

Para entornos empresariales que requieren autenticación dinámica, puedes 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 por señal.

Configuración de ajustes

Agrega a tu .claude/settings.json, reemplazando la ruta con la tuya propia:

{
  "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 entrecomilla 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 auxiliar falla o imprime salida que no cumple con estos requisitos, las exportaciones fallan y tu backend de telemetría no recibe nada de la sesión hasta que el auxiliar funcione nuevamente. Claude Code reporta el error en:

• Una notificación de advertencia en sesiones interactivas, otelHeadersHelper failed; telemetry is not being exported, mostrada una vez por sesión cuando el auxiliar 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 auxiliar de encabezados se ejecuta al inicio y periódicamente después para admitir la actualización de tokens. Por defecto, el script se ejecuta cada 29 minutos. Personaliza el intervalo con la variable de entorno CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Soporte de organización multi-equipo

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 incluirán en todas las métricas y eventos, permitiéndote:

• 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, puedes agrupar y filtrar métricas por tus claves personalizadas directamente. Excepto por los atributos de repositorio vcs.*, 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 tu backend de métricas. Para enviar atributos personalizados solo en el bloque de recursos y omitirlos de las etiquetas de punto de datos, establece OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. Consulta Control de cardinalidad de métricas.

Configuraciones de ejemplo

Establece estas variables de entorno antes de ejecutar claude. Cada escenario a continuación muestra una configuración completa, y cada variable se describe bajo Variables de configuración comunes. Para confirmar que una configuración tuvo efecto, verifica tu backend para la métrica claude_code.session.count después de iniciar una sesión; la Guía de inicio rápido cubre verificación solo de registros y qué verificar cuando nada llega.

Para depuración de consola con 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

Métricas y eventos disponibles

Atributos estándar

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

Cuando Claude Code está autenticado en una puerta de enlace de aplicaciones Claude, la CLI marca las exportaciones con la identidad autenticada de la sesión de la puerta de enlace: user.id es el asunto del IdP en lugar de un identificador de instalación anónimo, user.email es el correo electrónico con sesión iniciada, y user.groups lleva la pertenencia al grupo del IdP como una cadena separada por comas. Cada exportación también lleva identity.source: gateway-oidc. La identidad de la puerta de enlace se aplica en último lugar, por lo que las claves user.* e identity.* establecidas a través de OTEL_RESOURCE_ATTRIBUTES se ignoran en sesiones de puerta de enlace.

Los eventos incluyen además los siguientes atributos. Estos nunca se adjuntan a las métricas porque causarían cardinalidad ilimitada:

• prompt.id: UUID que correlaciona un mensaje del usuario con todos los eventos posteriores hasta el siguiente mensaje. Consulte Atributos de correlación de eventos.
• workspace.host_paths: directorios del espacio de trabajo del host seleccionados en la aplicación de escritorio, como una matriz de cadenas
• workflow.run_id: identificador de ejecución, con prefijo wf_, en los eventos de API y herramienta emitidos por agentes que pertenecen a una ejecución de herramienta Workflow. Filtrar eventos por un workflow.run_id reconstruye las solicitudes de API y resultados de herramientas de esa ejecución. El identificador cubre los agentes que el script del flujo de trabajo genera y cualquier agente que esos generen a su vez, como invocaciones de habilidades. Coincide con el identificador de ejecución reportado en el resultado de la herramienta Workflow. Ausente en todos los demás eventos. Requiere Claude Code v2.1.202 o posterior
• workflow.name: nombre del flujo de trabajo, el meta.name de su script, emitido junto con workflow.run_id. Los nombres de flujo de trabajo integrados aparecen literalmente cuando la ejecución ejecuta el script integrado sin modificar. Los nombres creados por el usuario, incluidas las copias editadas de scripts integrados, se reemplazan con custom a menos que se establezca OTEL_LOG_TOOL_DETAILS=1. Requiere Claude Code v2.1.202 o posterior

Atributos del repositorio

Establezca OTEL_METRICS_INCLUDE_REPOSITORY=true para etiquetar métricas y eventos con la identidad del repositorio de la sesión, de modo que un recopilador 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 desde el remoto origin del repositorio. Los remotos HTTPS y SSH de un repositorio producen valores idénticos:

Los valores se convierten a minúsculas, y las credenciales, cadenas de consulta y fragmentos de la URL remota 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 envolvente es su directorio de inicio.

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

Los atributos fluyen solo a sus propios exportadores; la telemetría de Anthropic descarta cada clave vcs.*.

Métricas

Claude Code exporta las siguientes métricas. La columna Unit 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 raspado permanezca en formato de texto Prometheus válido. Los nombres de las métricas no cambian, y las configuraciones que combinan exportadores, como otlp,prometheus, mantienen las unidades. Antes de v2.1.216, el raspado de Prometheus incluía líneas # UNIT solo de OpenMetrics que algunos raspadores rechazaban.

Detalles de métricas

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

Contador de sesión

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 de control claude agents, una interfaz de usuario local lanzada por el usuario en lugar de una sesión conversacional. Filtre en este valor para separar los lanzamientos de procesos de interfaz de usuario de las sesiones conversacionales en sus paneles de control.

Contador de líneas de código

Se incrementa cuando se agrega o se elimina código.

Atributos:

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

Contador de solicitud de extracción

Se incrementa cuando Claude Code crea una solicitud de extracción o solicitud de fusión a través de un comando de shell o una herramienta MCP.

Atributos:

• Todos los atributos estándar

Contador de confirmación

Se incrementa al crear confirmaciones de git a través de Claude Code.

Atributos:

• Todos los atributos estándar

Contador de costo

Se incrementa después de cada solicitud de API.

Atributos:

• Todos los atributos estándar
• model: Identificador de 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 utilizó modo rápido. Ausente de lo contrario
• effort: Nivel de esfuerzo aplicado a la solicitud: "low", "medium", "high", "xhigh", o "max". Ausente cuando Claude Code no envía un 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 mercado oficial aparecen literalmente. Otros nombres de agentes definidos por el usuario se reemplazan con "custom" a menos que se establezca OTEL_LOG_TOOL_DETAILS=1. Ausente cuando la solicitud no fue emitida por un tipo de subagente nombrado.
• skill.name: Habilidad activa para la solicitud, establecida por la herramienta Skill, un comando /, o heredada por un subagente generado. Los nombres de habilidades integradas, agrupadas, definidas por el usuario y del plugin del mercado oficial aparecen literalmente. Los nombres de habilidades de plugins de terceros se reemplazan con "third-party" a menos que se establezca OTEL_LOG_TOOL_DETAILS=1. Ausente cuando no hay habilidad activa.
• plugin.name: Plugin propietario cuando la habilidad activa o subagente es proporcionado por un plugin. Los nombres de plugins del mercado oficial aparecen literalmente. Los nombres de plugins de terceros se reemplazan con "third-party" a menos que se establezca OTEL_LOG_TOOL_DETAILS=1. Ausente cuando ni la habilidad ni el subagente tienen un plugin propietario.
• marketplace.name: Mercado desde el cual se instaló el plugin propietario. Solo se emite para plugins del mercado oficial. Ausente de lo contrario.
• mcp_server.name: Servidor MCP cuyo resultado de herramienta consumió esta solicitud. Los nombres de servidores integrados, proxificados por claude.ai, y del registro oficial aparecen literalmente. Los nombres de servidores configurados por el usuario se reemplazan con "custom" a menos que se establezca OTEL_LOG_TOOL_DETAILS=1. 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 después de una llamada de herramienta MCP, no solo en solicitudes que consumieron un resultado de herramienta, por lo que los paneles de control que lo agregan muestran una caída después de actualizar.
• mcp_tool.name: Herramienta MCP cuyo resultado consumió esta solicitud, con el mismo comportamiento de redacción y 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 de API.

Atributos:

• Todos los atributos estándar
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Identificador de 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 utilizó modo rápido. Ausente de lo contrario
• effort: Nivel de esfuerzo aplicado a la solicitud. Consulte Contador de costo para obtener detalles.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribución de habilidad, plugin, agente y MCP para la solicitud. Consulte Contador de costo para obtener definiciones y comportamiento de redacción.

Contador de decisión de herramienta de edición de código

Se incrementa cuando el usuario acepta o rechaza el uso de la herramienta Edit, Write, o NotebookEdit.

Atributos:

• Todos los atributos estándar
• tool_name: Nombre de herramienta ("Edit", "Write", "NotebookEdit")
• decision: Decisión del usuario ("accept", "reject")
• source: De dónde vino la decisión. Uno de "config", "hook", "user_permanent", "user_temporary", "user_abort", o "user_reject". Consulte el evento de decisión de herramienta para ver 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

Rastrea el tiempo real dedicado a usar activamente Claude Code, excluyendo el tiempo inactivo. Esta métrica se incrementa durante las interacciones del usuario, como escribir y leer respuestas, y durante el procesamiento de 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 de teclado, "cli" para ejecución de herramientas y respuestas de IA

Eventos

Claude Code exporta los siguientes eventos a través de registros/eventos de OpenTelemetry (cuando OTEL_LOGS_EXPORTER está configurado):

Atributos de correlación de eventos

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

Para rastrear toda la actividad desencadenada por un único mensaje, filtre sus 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 ocurrió mientras se procesaba ese mensaje.

event.sequence comienza en 0 cada vez que se inicia un proceso de Claude Code y cuenta hacia arriba durante la vida de ese proceso. Continúa contando a través de /clear, que asigna un nuevo session.id. Si reanuda una sesión sin bifurcar, la sesión mantiene su session.id pero toma sus valores de event.sequence del proceso que la reanudó, por lo que dentro de una sesión un evento posterior puede llevar un valor más bajo que uno anterior, o repetir uno. Para ordenar los eventos de una sesión, ordene por event.timestamp y use event.sequence para ordenar eventos que comparten una marca de tiempo.

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

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

Evento de mensaje del usuario

Se registra cuando un usuario envía un mensaje.

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 mensaje
• prompt: Contenido del mensaje. Redactado por defecto. Establezca OTEL_LOG_USER_PROMPTS=1 para incluirlo
• message.uuid: UUID del mensaje del usuario resultante, coincidiendo con la entrada de transcripción persistida. Ausente en envíos de comandos, que pueden producir cero o muchos mensajes. Requiere Claude Code v2.1.214 o posterior
• command_name: Nombre del comando cuando el mensaje invoca uno. Los nombres de comandos integrados y agrupados como compact o debug se emiten tal cual; los alias como reset se emiten tal como se escribieron en lugar del nombre canónico. Los nombres de comandos personalizados, de plugin y MCP se contraen a custom o mcp a menos que se establezca OTEL_LOG_TOOL_DETAILS=1
• command_source: Origen del comando cuando está presente: builtin, custom, o mcp. Los comandos proporcionados por plugins reportan como custom

Evento de respuesta del asistente

Se registra después de cada solicitud de API que devuelve contenido de texto del modelo. Solo se incluyen los bloques de texto de la respuesta; los bloques de pensamiento y los bloques de uso de herramientas se excluyen. Requiere Claude Code v2.1.193 o posterior.

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 respuesta en caracteres
• response: Texto de respuesta, truncado en el límite de contenido (60 KB por defecto). Redactado a <REDACTED> por defecto. Establezca OTEL_LOG_ASSISTANT_RESPONSES=1 para incluirlo. Cuando OTEL_LOG_ASSISTANT_RESPONSES no está establecido, OTEL_LOG_USER_PROMPTS lo controla en su lugar, por lo que establezca OTEL_LOG_ASSISTANT_RESPONSES=0 para mantener las respuestas redactadas mientras el registro de mensajes está activado
• model: Identificador de modelo (por ejemplo, "claude-sonnet-5")
• request_id: ID de solicitud de API de Anthropic del encabezado request-id de la respuesta. Presente solo cuando la API devuelve uno
• message.uuid: UUID de la entrada de transcripción final de la respuesta. Una respuesta de API se persiste como una entrada de transcripción por bloque de contenido; esta es la última, desde la cual el parentUuid del siguiente turno se encadena. Requiere Claude Code v2.1.214 o posterior
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact", o un nombre de subagente

Evento de resultado de herramienta

Se registra cuando una herramienta completa la ejecución. No se emite si la llamada de herramienta fue rechazada; consulte el evento de decisión de herramienta para 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 para esta invocación de herramienta. Coincide con el tool_use_id pasado a hooks, permitiendo correlación entre eventos OTel y datos capturados por hooks.
• 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 vino la decisión de permiso. Uno de "config", "hook", "user_permanent", o "user_temporary". Consulte el evento de decisión de herramienta para ver qué significa cada valor. Las fuentes solo de rechazo "user_abort" y "user_reject" nunca aparecen en este evento.
• tool_input_size_bytes: Tamaño de la entrada de herramienta serializada en JSON en bytes
• tool_result_size_bytes: Tamaño del resultado de la herramienta en bytes
• mcp_server_scope: Identificador de 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 de confirmación de una ejecución exitosa de git commit ejecutada por la herramienta Bash o PowerShell. vcs.ref.head.revision es el SHA de confirmación, vcs.ref.head.name es la rama en la que se confirmó, y vcs.ref.head.type es branch. El nombre y tipo se omiten cuando la confirmación se realizó en un HEAD desconectado. 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 Claude Desktop posee, el par mcp_server_name/mcp_tool_name se incluye incluso con la bandera desactivada, la misma excepción creada por el host que el evento de decisión de herramienta, requiriendo Claude Code v2.1.214 o posterior. Los parámetros varían según la herramienta:
  • Para herramienta Bash: incluye bash_command, full_command, timeout, description, y dangerouslyDisableSandbox, más git_commit_id y git_branch cuando un comando git commit tiene éxito. git_commit_id es el SHA de confirmación completo cuando la confirmación es el HEAD del directorio de trabajo de la sesión, y el SHA abreviado de git de lo contrario. git_branch es la rama en la que se confirmó, omitida en un HEAD desconectado
  • Para la herramienta Bash del espacio de trabajo de la aplicación de escritorio, que también reporta tool_name como Bash: incluye solo bash_command, full_command, y timeout
  • Para herramientas MCP: incluye mcp_server_name, mcp_tool_name
  • Para herramienta Skill: incluye skill_name
  • Para herramienta Agent o herramienta Task heredada: incluye subagent_type
• tool_input (cuando OTEL_LOG_TOOL_DETAILS=1): Argumentos de herramienta serializados en JSON. Los valores individuales superiores a 512 caracteres se truncan, y la carga útil completa se limita a aproximadamente 4 K caracteres. Se aplica a todas las herramientas, incluidas las herramientas MCP.

Evento de solicitud de API

Se registra para cada solicitud de API a 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 utilizado (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
• 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 utilizados para la creación de caché
• request_id: ID de solicitud de API de Anthropic del encabezado request-id de la respuesta, como "req_011...". Presente solo cuando la API devuelve uno.
• client_request_id: UUID generado por el cliente enviado como encabezado de solicitud x-client-request-id; consulte la tabla atributos de correlación de eventos para saber cuándo está presente. Requiere Claude Code v2.1.214 o posterior
• speed: "fast" o "normal", indicando si el modo rápido estaba activo
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact", o un nombre de subagente
• effort: Nivel de esfuerzo aplicado a la solicitud: "low", "medium", "high", "xhigh", o "max". Ausente cuando Claude Code no envía un 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 habilidad, plugin, agente y MCP para la solicitud. Consulte Contador de costo para obtener definiciones y comportamiento de redacción.

Evento de error de API

Se registra cuando una solicitud de API a Claude falla.

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 utilizado (por ejemplo, "claude-sonnet-5")
• error: Mensaje de error
• status_code: Código de estado HTTP como número. Ausente para errores no HTTP como fallos de conexión.
• duration_ms: Duración de la solicitud en milisegundos
• attempt: Número total de intentos realizados, incluida la solicitud inicial (1 significa que no ocurrieron reintentos)
• request_id: ID de solicitud de API de Anthropic del encabezado request-id de la respuesta, como "req_011...". Presente solo cuando la API devuelve uno.
• client_request_id: UUID generado por el cliente enviado como encabezado de solicitud x-client-request-id. Disponible incluso cuando un fallo como un tiempo de espera o error de conexión nunca produjo un request_id del servidor; consulte la tabla atributos de correlación de eventos para saber cuándo está presente. Requiere Claude Code v2.1.214 o posterior
• speed: "fast" o "normal", indicando si el modo rápido estaba activo
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact", o un nombre de subagente
• effort: Nivel de esfuerzo aplicado a la solicitud. Ausente cuando Claude Code no envía un 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 habilidad, plugin, agente y MCP para la solicitud. Consulte Contador de costo para obtener definiciones y comportamiento de redacción.

Evento de rechazo de API

Se registra cuando una solicitud de API devuelve stop_reason: "refusal". Los rechazos llegan en una transmisión de respuesta exitosa en lugar de como un error HTTP, por lo que el evento api_error no se activa para ellos. Este evento le permite rastrear la frecuencia de rechazo y agrupar rechazos 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 de modelo de la solicitud
• request_id: ID de solicitud de API de Anthropic del encabezado request-id de la respuesta, como "req_011...". Presente solo cuando la API devuelve uno.
• query_source: Subsistema que emitió la solicitud, como "repl_main_thread", "compact", o un nombre de subagente. Consulte api_request para obtener definiciones.
• speed: Ya sea "fast" cuando 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 un nivel de esfuerzo, por ejemplo en un modelo que no admite esfuerzo.
• server_fallback_hop: true cuando la alternativa 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 único turno puede emitir tanto un evento de salto true como un evento final false posterior cuando el modelo de alternativa también rechaza.
• has_category: true cuando la respuesta de la API llevaba un stop_details.category de "cyber", "bio", "frontier_llm", o "reasoning_extraction". false cuando la respuesta no llevaba categoría o un valor fuera de ese conjunto. Ausente cuando server_fallback_hop es true, porque los saltos no llevan stop_details.
• has_explanation: true cuando la respuesta de la API llevaba un stop_details.explanation, de lo contrario false. Ausente cuando server_fallback_hop es true.
• category: El valor 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á establecido y has_category es true.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribución de habilidad, plugin, agente y MCP para la solicitud. Consulte Contador de costo para obtener definiciones y comportamiento de redacción.

Evento de cuerpo de solicitud de API

Se registra para cada intento de solicitud de API cuando OTEL_LOG_RAW_API_BODIES está establecido. Se emite un evento por intento, por lo que los reintentos con parámetros ajustados producen cada uno 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 solicitud de API de Messages serializados en JSON, como el mensaje del sistema, mensajes y herramientas, truncados en el límite de contenido (60 KB por defecto). El contenido de pensamiento extendido en 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 ocurrió truncamiento en línea. Ausente en modo de archivo y cuando no ocurrió truncamiento.
• model: Identificador de modelo de los parámetros de solicitud
• query_source: Subsistema que emitió la solicitud (por ejemplo, "compact")
• request_body_id: UUID que identifica el cuerpo de solicitud de este intento. El evento api_response_body para el intento que tiene éxito lleva el mismo valor, por lo que puede emparejar una respuesta con la solicitud exacta que la produjo. Requiere Claude Code v2.1.274 o posterior

Evento de cuerpo de respuesta de API

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

En modo de archivo (OTEL_LOG_RAW_API_BODIES=file:<dir>), Claude Code también añade una línea JSON a <dir>/index.jsonl para cada respuesta exitosa, con los campos timestamp, session_id, query_source, model, request_id, message_id, message_uuid, request_file, y response_file. Léalo para encontrar los archivos de solicitud y respuesta detrás de un mensaje de transcripción dado sin consultar su 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 API de Messages serializada en JSON, incluido el id, bloques de contenido, uso y razón de parada, truncada en el límite de contenido (60 KB por defecto). 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 ocurrió truncamiento en línea. Ausente en modo de archivo y cuando no ocurrió truncamiento.
• model: Identificador de modelo
• query_source: Subsistema que emitió la solicitud
• request_id: ID de solicitud de API de Anthropic del encabezado request-id de la respuesta, como "req_011...". Presente solo cuando la API devuelve uno.
• request_body_id: El request_body_id del evento api_request_body que esta respuesta responde. Requiere Claude Code v2.1.274 o posterior
• message.id: ID de mensaje que la API asignó a la respuesta, el campo id del cuerpo de respuesta. Requiere Claude Code v2.1.274 o posterior
• message.uuid: UUID de la entrada de transcripción final de la respuesta. Junto con request_body_id, vincula un mensaje de transcripción a los cuerpos de solicitud y respuesta detrás de él. Requiere Claude Code v2.1.274 o posterior

Evento de decisión de herramienta

Se registra cuando se toma una decisión de permiso de 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 para esta invocación de herramienta. Coincide con el tool_use_id pasado a hooks, permitiendo correlación entre eventos OTel y datos capturados por hooks.
• decision: Ya sea "accept" o "reject"
• tool_source: Siempre presente. La procedencia de la herramienta, como un conjunto cerrado de valores creados por CLI. Requiere Claude Code v2.1.214 o posterior
  • "builtin": las herramientas propias de la CLI
  • "mcp": servidores MCP en general
  • "sdk_host_builtin_mcp": un servidor en proceso integrado en Claude Desktop mismo, en una sesión que Claude Desktop posee. Claude Desktop posee una sesión que inició desde uno de sus propios puntos de entrada, claude-desktop, claude-desktop-3p, o local-agent, cuando esa sesión no es un hijo anidado; las sesiones anidadas, incluidas las sesiones que Claude Code mismo genera, reportan estos servidores como "mcp"
• source: De dónde vino la decisión:
  • "config": Decidido automáticamente sin preguntar, basado en la configuración del proyecto, reglas de permitir o denegar en la configuración personal del usuario, política gestionada empresarial, banderas --allowedTools o --disallowedTools, el modo de permiso activo, una concesión con alcance de sesión de un mensaje anterior en la misma sesión de CLI interactiva, o porque la herramienta es inherentemente segura. El evento no indica cuál de estas fuentes coincidió. Claude Code también reporta "config" cuando la solicitud de mensaje de permiso en sí falla, por ejemplo cuando la devolución de llamada canUseTool del SDK de Agent o la herramienta --permission-prompt-tool devuelve un resultado inválido, o cuando el flujo de entrada se cierra mientras la solicitud está pendiente. Antes de v2.1.216, Claude Code reportaba estos fallos como "user_reject".
  • "hook": Un hook PreToolUse o PermissionRequest devolvió la decisión.
  • "user_permanent": Se emite cuando el usuario eligió "Sí, y no preguntar de nuevo para ..." en un mensaje de permiso, que guarda una regla de permitir en su configuración personal. En la CLI interactiva esto se emite solo para esa opción en sí; las llamadas posteriores que coinciden con la regla guardada emiten "config" en su lugar. En sesiones de SDK de Agent o no interactivas -p, tanto la opción inicial como las coincidencias de reglas posteriores emiten "user_permanent". Se trata como una aceptación.
  • "user_temporary": Se emite cuando el usuario eligió "Sí" en un mensaje de permiso para una aprobación única, u optó por una opción que otorga acceso para el resto de la sesión en un mensaje de edición o lectura de archivo. En la CLI interactiva esto se emite solo para la opción en sí; las llamadas posteriores permitidas por esa concesión con alcance de sesión emiten "config" en su lugar. En sesiones de SDK de Agent o no interactivas -p, tanto la opción como las coincidencias posteriores emiten "user_temporary". Se trata como una aceptación.
  • "user_abort": Se emite cuando el usuario descartó el mensaje de permiso sin responder. En sesiones de SDK de Agent y no interactivas -p, esto incluye interrumpir el turno mientras una solicitud de permiso canUseTool o --permission-prompt-tool está pendiente; antes de v2.1.216, Claude Code reportaba esa interrupción como "user_reject". Se trata como un rechazo.
  • "user_reject": Se emite cuando el usuario eligió "No" cuando se le preguntó. En la CLI interactiva esto se emite solo para esa opció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 de SDK de Agent o no interactivas -p, las llamadas que coinciden con una regla de denegar en la configuración personal emiten "user_reject". Se trata como un rechazo.
• tool_parameters (cuando OTEL_LOG_TOOL_DETAILS=1): Cadena JSON que contiene parámetros específicos de la herramienta. Misma forma que el evento de resultado de herramienta, menos campos posteriores a la ejecución como git_commit_id. Los valores pueden diferir de tool_result para una llamada aceptada si la decisión de permiso reescribe la entrada de herramienta a través de updatedInput. Use este atributo para ver qué comando fue rechazado 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á desactivado, porque la aplicación host define estos nombres; sin ellos, una llamada rechazada a uno de estos servidores integrados sería inattribuible en la transmisión predeterminada. Para servidores MCP configurados por el usuario, el tool_name del evento es siempre el literal "mcp_tool", y los nombres del servidor y herramienta aparecen solo en tool_parameters con la bandera activada; el contenido del argumento requiere la bandera en todas partes. Requiere Claude Code v2.1.214 o posterior
  • Para 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 reporta tool_name como Bash, pero incluye solo bash_command, full_command, y timeout
  • Para herramientas MCP: incluye mcp_server_name, mcp_tool_name
  • Para herramienta Skill: incluye skill_name
  • Para herramienta Agent o herramienta Task heredada: incluye subagent_type

Evento de cambio de modo de permiso

Se registra cuando el modo de permiso cambia, por ejemplo al ciclar con Shift+Tab, salir del modo de plan, o una verificación de puerta automática.

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 permiso anterior, por ejemplo "default", "plan", "acceptEdits", "auto", o "bypassPermissions"
• to_mode: El nuevo modo de permiso
• trigger: Qué causó el cambio. Uno de "shift_tab", "exit_plan_mode", "auto_gate_denied", o "auto_opt_in". Ausente cuando la transición se origina del SDK o puente

Evento de autenticación

Se registra cuando /login o /logout se completa.

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 de error categórico 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 del servidor MCP

Se registra cuando un servidor MCP se conecta, desconecta o falla al 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 es proporcionado por un plugin, false de lo contrario
• plugin_id_hash (cuando is_plugin es true): Hash estable del nombre del plugin y mercado, 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 este es el literal "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1; esto protege los nombres de plugins de terceros de aparecer en registros por defecto. Los plugins de fuentes oficiales de Anthropic siempre se identifican por nombre. Los atributos plugin_id_hash y plugin.name fluyen a su propio backend de monitoreo y no se envían a Anthropic
• server_name (cuando OTEL_LOG_TOOL_DETAILS=1): Nombre del servidor configurado
• 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 detecta un error interno inesperado. Solo se registran el nombre de la clase de error y un código de estilo errno. El mensaje de error y el rastreo de pila nunca se incluyen. Este evento no se emite cuando se ejecuta contra Amazon Bedrock, la plataforma de agentes de Google Cloud, Microsoft Foundry, o cuando DISABLE_ERROR_REPORTING está establecido.

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 de 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 CLI claude plugin install como desde la interfaz de usuario 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 mercado es un mercado oficial de Anthropic, "false" de lo contrario
• install.trigger: "cli" o "ui"
• plugin.name: Nombre del plugin instalado. Para mercados de terceros esto se incluye solo cuando OTEL_LOG_TOOL_DETAILS=1
• plugin.version: Versión del plugin cuando se declara en la entrada del mercado. Para mercados de terceros esto se incluye solo cuando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Mercado desde el cual se instaló el plugin. Para mercados de terceros esto se incluye solo cuando OTEL_LOG_TOOL_DETAILS=1

Evento de plugin cargado

Se registra una vez por plugin habilitado al inicio de la sesión. Use este evento para inventariar qué plugins están activos en su flota, como complemento a 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 mercado oficial y paquete integrado el valor es "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: mercado desde el cual se instaló el plugin, cuando se conoce. Redactado a "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 el plugin llegó a estar habilitado: "default-enable", "org-policy", "admin-install", "seed-mount", o "user-install". El valor "admin-install" significa que el plugin está configurado como requerido o instalación automática para su organización en Configuración de la organización > Plugins y habilidades. Antes de v2.1.246, Claude Code reportaba estos plugins como "user-install" o "seed-mount"
• plugin_id_hash: hash determinista del nombre del plugin y mercado, enviado solo a su exportador configurado. Le permite contar los plugins de terceros distintos cargados en su flota sin registrar sus nombres. Para plugins sincronizados desde claude.ai, Claude Code codifica el nombre del plugin con el nombre del mercado que claude.ai reporta para el plugin, o con synced de lo contrario. Antes de v2.1.246, Claude Code no usaba el nombre del mercado que claude.ai reporta en el hash
• has_hooks: si el plugin contribuye hooks
• has_mcp: si el plugin contribuye servidores MCP
• host_owned_mcp: true cuando el host del SDK gestiona las conexiones MCP de este plugin y Claude Code omitió leer la configuración del servidor MCP del plugin, false de lo contrario. Requiere Claude Code v2.1.172 o posterior
• skill_path_count: número de directorios de habilidades 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" de lo contrario. En modo seguro este evento reporta solo el inventario configurado; los comandos, habilidades, hooks y servidores MCP del plugin no se cargan. Requiere Claude Code v2.1.169 o posterior

Evento de habilidad activada

Se registra cuando se invoca una habilidad, ya sea que Claude la llame a través de la herramienta Skill o que la ejecute 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 de la habilidad. Para habilidades definidas por el usuario y de plugins de terceros el valor es el marcador de posición "custom_skill" a menos que OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger: Cómo se activó la habilidad ("user-slash", "claude-proactive", o "nested-skill")
• skill.source: De dónde se cargó la habilidad (por ejemplo, "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind: "workflow" cuando la habilidad es una habilidad de flujo de trabajo. Ausente de lo contrario
• plugin.name (cuando OTEL_LOG_TOOL_DETAILS=1 o el plugin es de un mercado oficial): Nombre del plugin propietario cuando la habilidad es proporcionada por un plugin
• marketplace.name (cuando OTEL_LOG_TOOL_DETAILS=1 o el plugin es de un mercado oficial): Mercado desde el cual se instaló el plugin propietario, cuando la habilidad es proporcionada por un plugin

Evento de mención @

Se registra cuando Claude Code resuelve una mención @ en un mensaje. No todas las menciones emiten un evento: las rutas de salida temprana como denegaciones de permiso, archivos de tamaño excesivo, adjuntos de referencia PDF y fallos de listado de directorios se devuelven sin registrar.

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 mencionó una de sus otras sesiones de Claude Code. Requiere Claude Code v2.1.232 o posterior
• success: Si la mención se resolvió exitosamente ("true" o "false")

Evento de reintentos de API agotados

Se registra una vez cuando una solicitud de 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 utilizado
• error: Mensaje de error final
• status_code: Código de estado HTTP como número. Ausente para errores no HTTP.
• total_attempts: Número total de intentos realizados
• total_retry_duration_ms: Tiempo total de reloj de pared en todos los intentos
• speed: "fast" o "normal"

Evento de hook registrado

Se registra una vez por hook configurado al inicio de la sesión. Use este evento para inventariar qué hooks están activos en su flota, como complemento a 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 de hook, como "PreToolUse" o "PostToolUse"
• hook_type: tipo de implementación de hook: "command", "prompt", "mcp_tool", "http", o "agent"
• hook_source: dónde se define el hook: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings", o "pluginHook"
• safe_mode: "true" cuando la sesión se inició con --safe-mode, "false" de lo contrario. Requiere Claude Code v2.1.169 o posterior
• hook_matcher (cuando OTEL_LOG_TOOL_DETAILS=1): la cadena de coincidencia de la configuración del hook, cuando se establece
• plugin.name (cuando hook_source es "pluginHook"): nombre del plugin contribuyente. Para plugins fuera del mercado oficial y 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 mercado, enviado solo a su exportador configurado. Le permite contar plugins contribuyentes distintos 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 de hook, como "PreToolUse" o "PostToolUse"
• hook_name: Nombre completo del hook incluida la coincidencia, como "PreToolUse:Write"
• num_hooks: Número de comandos de hook coincidentes
• managed_only: "true" cuando solo se permiten hooks de política gestionada
• hook_source: "policySettings" o "merged"
• safe_mode: "true" cuando la sesión se inició con --safe-mode, "false" de lo contrario. Requiere Claude Code v2.1.169 o posterior
• hook_definitions: Configuración de hook serializada en JSON. Se incluye solo cuando tanto el rastreo beta detallado como OTEL_LOG_TOOL_DETAILS=1 están habilitados

Evento de finalización de ejecución de hook

Se registra cuando todos los hooks para 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 incluida la coincidencia
• num_hooks: Número de comandos de hook coincidentes
• num_success: Conteo que se completó exitosamente
• num_blocking: Conteo que devolvió una decisión de bloqueo
• num_non_blocking_error: Conteo que falló sin bloquear
• num_cancelled: Conteo cancelado antes de completarse
• total_duration_ms: Duración de reloj de pared de todos los hooks coincidentes
• stdout_chars: Total de caracteres de stdout en todos los hooks coincidentes que tuvieron éxito. Requiere Claude Code v2.1.280 o posterior
• additional_context_chars: Total de caracteres de additionalContext devueltos por los hooks coincidentes. Requiere Claude Code v2.1.280 o posterior
• system_message_chars: Total de caracteres de systemMessage devueltos por los hooks coincidentes. Requiere Claude Code v2.1.280 o posterior
• initial_user_message_chars: Total de caracteres de initialUserMessage devueltos por los hooks coincidentes. Requiere Claude Code v2.1.280 o posterior
• num_outputs_persisted: Número de salidas de hook sobre el límite de 10,000 caracteres 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ítica gestionada
• hook_source: "policySettings" o "merged"
• safe_mode: "true" cuando la sesión se inició con --safe-mode, "false" de lo contrario. Requiere Claude Code v2.1.169 o posterior
• hook_definitions: Configuración de hook serializada en JSON. Se incluye solo cuando tanto el rastreo beta detallado como OTEL_LOG_TOOL_DETAILS=1 están habilitados

Evento de métricas de plugin de hook

Se registra cuando un hook de plugin del mercado oficial emite métricas por invocación. Solo los plugins instalados desde un mercado oficial de Anthropic pueden emitir estos. Los plugins de mercado de terceros y los hooks configurados por el usuario no emiten a este evento. Use este evento para monitorear el comportamiento del plugin como tasas de búsqueda, costos y duraciones desde su 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 en forma <name>@<marketplace>
• hook_event: tipo de evento de hook que emitió las métricas
• Hasta 20 claves de métrica emitidas por el plugin. Los nombres coinciden con ^[a-z][a-z0-9_]{0,39}$. Los valores son booleanos o números.

Evento de compactación

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

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: Conteo aproximado de tokens antes de la compactación
• post_tokens: Conteo 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". La compactación automática puede preparar un resumen en el fondo antes de que la ventana de contexto se llene, y este atributo registra si /compact reutilizó ese resumen preparado. "hit" significa que se reutilizó; "miss_custom_instructions", "miss_hook", y "miss_not_ready" dan la razón por la que se calculó un resumen fresco en su lugar. Requiere Claude Code v2.1.153 o posterior

Evento de subagente completado

Se registra cuando un subagente termina y devuelve su resultado a la conversación que lo inició. Úselo para acumular el uso de herramientas y tiempo de ejecución por tipo de subagente; para acumulaciones de tokens o costo, use el contador de tokens y contador de costo filtrados a query_source "subagent", ya que el total_tokens de este evento cubre solo la solicitud final. La categoría "subagent" también cuenta solicitudes de hooks basados en agentes, que no emiten 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 mercado oficial aparecen literalmente; otros nombres de agentes se reemplazan con "custom" a menos que OTEL_LOG_TOOL_DETAILS=1 esté establecido
• agent.source: De dónde vino 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 de API final del subagente: esa solicitud única de entrada, creación de caché, lectura de caché y tokens de salida, aproximadamente el tamaño de contexto del subagente al completarse. No es una suma en toda la ejecución
• total_tool_uses: Número de llamadas de herramienta que realizó el subagente en toda la ejecución
• duration_ms: Tiempo de ejecución en milisegundos
• model: El modelo en el que se resolvió el subagente para ejecutarse
• final_model: El modelo que produjo la respuesta final del subagente, que difiere de model después de un cambio a mitad de ejecución como una alternativa. Requiere Claude Code v2.1.212 o posterior
• model_swapped: Si más de un modelo sirvió las solicitudes del subagente. Requiere Claude Code v2.1.212 o posterior
• plugin_id_hash, plugin.name: Presente para agentes proporcionados por plugins. Los nombres de plugins del mercado oficial aparecen literalmente; otros nombres de plugins se reemplazan con "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1 esté establecido

Evento de encuesta de retroalimentación

Se registra cuando se muestra o se responde una encuesta de calidad de sesión. Consulte Encuestas de calidad de sesión para ver 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 mensaje de calificación "¿Cómo está Claude?"
• response: La selección del usuario en eventos responded
• enabled_via_override: true cuando CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL está establecido. Se emite como booleano, no como cadena. Presente en eventos de encuesta session. Filtre en este atributo para confirmar que la anulación se aplica en toda una flota

Evento de barrido de retención

Se registra una vez por ejecución del barrido de limpieza de retención, que elimina transcripciones de sesión y otros datos de aplicación más antiguos que la configuración cleanupPeriodDays. Claude Code ejecuta el barrido en el fondo como máximo una vez por sesión, y una ejecución que no elimina nada aú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 sale antes no emite nada. Cuando ejecuta claude -p con --bare, Claude Code no ejecuta el barrido y no emite nada.

Como todos los eventos OTel en esta página, solo va al backend de telemetría que configura. 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 configuración gestionada establece cleanupPeriodDays, el valor gestionado fija el período de retención y el barrido se ejecuta incluso cuando un archivo de configuración en un alcance de prioridad más baja está roto o es inválido. Cuando managed-settings.json en sí no se puede leer, Claude Code aún pausa el barrido a menos que el nivel gestionado suministre cleanupPeriodDays desde otro lugar, como configuración gestionada por servidor o un drop-in managed-settings.d/ junto al archivo roto. Los atributos del contador de eliminación están presentes solo 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 cleanupPeriodDays de la configuración fusionada, en días, o 30 cuando ninguna fuente lo establece. En eventos omitidos, el valor que el barrido habría utilizado, 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" de lo contrario. En eventos completos, "true" significa que se aplicó el 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 por la bandera --setting-sources o la opción settingSources del SDK, y ninguna fuente habilitada proporciona cleanupPeriodDays
  • "settings_unknowable": Un archivo de configuración no se pudo leer o analizar, por lo que cleanupPeriodDays o desktopSessionCleanupPeriodDays pueden 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á explícitamente establecido, por lo que recurrir al predeterminado podría eliminar o mantener archivos contra esa configuración
• transcripts_deleted: Número de transcripciones de sesión, los archivos de nivel superior ~/.claude/projects/*/*.jsonl, que el barrido eliminó
• transcripts_exempted_desktop: Número de transcripciones pasadas el período de retención que el barrido mantuvo bajo la regla de Claude Desktop y Cowork. Estos no cuentan hacia files_past_cutoff. Requiere Claude Code v2.1.248 o posterior
• session_files_deleted: Número de artefactos que el barrido de archivos de sesión eliminó: transcripciones más archivos complementarios por sesión como barras laterales, grabaciones y resultados de herramientas
• artifacts_deleted: Total de elementos que el barrido eliminó en todos los directorios de datos que cubre, incluidos los archivos de sesión. Algunos barridos cuentan un árbol de directorios completo eliminado como un elemento y algunos pases de limpieza no contribuyen al contador, por lo que trate el valor como un piso en lugar de un conteo exacto de archivos
• files_retained_fresh: Archivos inspeccionados y dejados en su lugar porque aún están dentro del período de retención. Solo los barridos por archivo cuentan estos, por lo que el valor es un piso; un valor distinto de cero es el estado estable normal
• files_past_cutoff: Archivos más antiguos que el período de retención que el barrido no pudo eliminar, por ejemplo debido a un error de permiso o un archivo mantenido abierto. Un valor superior a cero significa que los archivos sobrevivieron al período de retención configurado; cero no es prueba de que ninguno lo hizo, porque una eliminación fallida de un directorio completo cuenta hacia error_count en su lugar
• error_count: Número de errores que el barrido encontró mientras listaba o eliminaba archivos

Evento de configuración gestionada resuelta

Se registra con la configuración gestionada que una sesión resolvió: una vez al inicio de la sesión, nuevamente cuando la configuración gestionada o el asistente de política cambia de estado durante la sesión, y cuando Claude Code se niega a iniciar o termina la sesión por una de las razones que el atributo error.type lista. Use este evento para encontrar máquinas ejecutándose en una fuente gestionada inesperada, máquinas cuyo asistente de política está fallando, y la razón por la que una máquina se negó a iniciar. Requiere Claude Code v2.1.274 o posterior.

Por defecto, el evento lleva las fuentes gestionadas y el estado del asistente de política pero no la configuración en sí. Para agregar el atributo managed_settings.settings redactado y el resumen managed_settings.resolved_sha256, establezca OTEL_LOG_MANAGED_SETTINGS=1:

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

En una sesión interactiva en una carpeta que no ha 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 gestionada o el estado del asistente de política cambió más tarde en la sesión, o "refused" cuando una política de configuración gestionada 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 configuración cambiado cuenta incluso cuando OTEL_LOG_MANAGED_SETTINGS está desactivado

• error.type: por qué Claude Code detuvo la sesión. Presente solo en eventos refused:

  • "helper_failed": una ejecución del asistente de política falló
  • "policy_invalid": la configuración gestionada contiene un error que detiene a Claude Code de iniciar, o una fuente de administrador no se pudo cargar, por lo que Claude Code no puede verificar la aplicación de inicio de sesión de la organización
  • "consent_rejected": el usuario rechazó el diálogo de aprobación de seguridad para configuración gestionada por servidor
  • "force_refresh_failed": la búsqueda de configuración que forceRemoteSettingsRefresh requiere falló
  • "gateway_rejected": una puerta de enlace de aplicaciones Claude respondió a la carga de configuración gestionada con HTTP 403
  • "version_below_minimum": esta versión de Claude Code está por debajo de requiredMinimumVersion o por encima de requiredMaximumVersion
  • "_OTHER": la carga de configuración gestionada de la puerta de enlace de aplicaciones Claude falló por otra razón

• managed_settings.sources: cada fuente gestionada que entrega al menos una clave de política, prioridad más alta primero, incluidas fuentes cuyas claves no tienen efecto bajo first-wins. Los valores son "remote", "plist" o "hklm" para la política de MDM o nivel de SO, "file" para archivos de configuración gestionada y drop-ins, "parent" cuando un host de incrustación suministra configuración, y "hkcu" para el valor del registro HKCU de Windows cuando Claude Code lo lee. Una fuente que lleva solo claves de control, o que Claude Code no pudo leer, no está listada. Se emite como una matriz de cadenas, vacía cuando ninguna fuente gestionada entrega una clave de política

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

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

  • "ok": la salida del asistente sirve como la configuración gestionada
  • "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": ningún asistente está configurado, o la fuente que lo configura no es una política de MDM o archivo de configuración gestionada

• managed_settings.helper.applied: "output" mientras la salida propia del asistente sirve como la configuración gestionada, "none" cuando no lo hace

• 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. 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 gestionada resuelta antes de la redacción, serializada como JSON con 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 opción de participación porque una política corta se puede recuperar codificando adivinanzas. Ausente cuando no se resolvió configuración gestionada, y en eventos refused

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

  • Un nombre de configuración que el esquema declara se exporta, y una clave que no declara se deja fuera
  • Booleanos, números y 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]"
  • Cada otra cadena, como model, apiKeyHelper, cada valor env, cada URL, y cada comando, se exporta como "[REDACTED]"
  • Los nombres de entrada de mapas, como nombres de variables env e IDs de plugins, se exportan tal cual. Una configuración cuyas entradas el esquema no escribe, 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 comando
  • Una lista mantiene su longitud, con cada entrada redactada por las mismas reglas
  • Una regla permissions.allow, permissions.deny, o permissions.ask se exporta como su nombre de 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 los campos de opción fija y numéricos como type y timeout se muestran, mientras que cada comando, URL, matcher, y condición if se exporta como "[REDACTED]"

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

  Claude Code corta el valor en 8 KB de UTF-8, y el valor cortado no es JSON válido

• managed_settings.settings_truncated (cuando managed_settings.settings está presente): true cuando Claude Code cortó managed_settings.settings en 8 KB, false de lo 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

Claude Code cuenta cada respuesta de transmisión hacia las métricas de costo y token exactamente una vez, incluyendo cuando una puerta de enlace o proxy detrás de ANTHROPIC_BASE_URL transmite el uso progresivamente a través de múltiples fotogramas. Antes de v2.1.214, las transmisiones que llevaban uso en más de un fotograma inflaban claude_code.cost.usage y claude_code.token.usage aproximadamente una solicitud completa adicional por fotograma adicional.

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 a partir de v2.1.172, 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 total de intentos. CLAUDE_CODE_MAX_RETRIES tiene un valor predeterminado de 10 y está limitado a 15. A partir de v2.1.199, puede establecer CLAUDE_CODE_RETRY_WATCHDOG para aumentar el valor predeterminado y eliminar el límite.

Cuando la solicitud agota todos los reintentos en un error transitorio, attempt es igual a uno más que ese límite efectivo: 11 por defecto, y nunca más de 16 a menos que el vigilante esté configurado. Un valor más bajo indica un error no reintentable como una respuesta 400, o una causa con su propio presupuesto de reintento más pequeño. Por ejemplo, Claude Code reintenta una falla al cargar credenciales de AWS o Google Cloud como máximo dos veces.

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.

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 de Claude apps gateway, donde es el asunto del IdP del token emitido por la puerta de enlace.

Las llamadas de herramientas MCP, comandos Bash y ediciones de archivos se atribuyen por lo tanto al desarrollador que inició la sesión. 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.

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: la CLI marca la identidad del IdP automáticamente, como se describe en Atributos estándar.

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 contenido de 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, requiere Claude Code v2.1.214 o posterior
• tool_decision: mantiene tool_source y un tool_name redactado al literal "mcp_tool" para servidores configurados por el usuario, omite contenido de 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; tool_source y el par de nombres requieren Claude Code v2.1.214 o posterior
• 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.

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, ejecute claude --debug y verifique el registro de depuración 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:

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

Para eventos/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

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 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 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 sus canalizaciones de recopilador o paneles filtran por service.name = claude-code, agregue claude-code-desktop al filtro para capturar también la telemetría de sesiones 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 mensaje del usuario no se recopila por defecto. Solo se registra la longitud del mensaje. Para incluir contenido del mensaje, establece OTEL_LOG_USER_PROMPTS=1. Bajo el rastreo beta detallado, esta variable llega más lejos que el texto del mensaje: también controla el atributo de span new_context, que lleva resultados de herramientas en el span claude_code.llm_request
• 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 punto final de OTel que configures, nunca a Anthropic. Cuando esta variable no está establecida, OTEL_LOG_USER_PROMPTS se utiliza como alternativa, así que establece OTEL_LOG_ASSISTANT_RESPONSES=0 si deseas contenido de mensaje sin contenido de respuesta
• 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 la bandera desactivada. La excepción requiere Claude Code v2.1.214 o posterior. Estos datos se envían solo al punto final 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 spans de traza incluyen el mismo atributo tool_input e atributos derivados de entrada como file_path, con el mismo truncamiento que 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 y salida de comandos Bash, truncado en el límite de contenido (60 KB por defecto) por atributo. 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).