Lección 4: Trazado: hilvanar una ejecución en un árbol

Objetivos de aprendizaje:

• Usar IDs de correlación para reunir registros dispersos en «todo lo que disparó un prompt», y explicar cómo se reparten el trabajo con el ID de sesión
• Leer la jerarquía de spans y trazas: span raíz, solicitudes al modelo, llamadas a herramientas, las dos fases de una herramienta (espera de permiso frente a ejecución) y cómo los subagentes se anidan bajo el span de herramienta del agente padre
• Cuando el panel esté vacío, sospechar del pipeline antes que del agente: saber por qué la exportación puede fallar en silencio, qué condiciones hacen que la exportación por lotes pierda datos y cómo verificar la instrumentación misma

Requisitos: Lecciones 1–3 (por qué el no determinismo rompe la reproducción, por qué los registros crudos son la evidencia primaria, cómo instrumentar un arnés con logs estructurados y métricas) | << Lección 3 | Lección 5 >>

400 registros: ¿cuáles 12 son esa ejecución?

Al terminar la lección anterior, tu arnés escribía registros estructurados en runs.jsonl: uno por solicitud al modelo, uno por llamada a herramienta, con duración, tokens y errores. Los logs pasaron de «un gran bloque de texto» a «un objeto JSON por línea». Quedaste satisfecho.

Entonces un usuario reporta un problema: «Ayer por la tarde le pedí que corrigiera unos textos en la página de login y también modificó un archivo de pruebas. Yo no pedí eso».

Abres los logs, filtras por fecha con grep y 400 registros te devuelven la mirada. Doscientas llamadas a herramientas, cien solicitudes al modelo y decenas de registros de subagentes mezclados. El prompt del que habla el usuario corresponde probablemente a una docena de ellos. ¿Cuál docena?

Tienes dos pistas, ninguna suficiente:

• ID de sesión. En la lección anterior sí escribiste session_id en cada registro, pero ayer por la tarde el usuario tuvo siete u ocho intercambios en la misma sesión. Filtras por sesión y 400 se convierte en 210. Rango más chico, misma naturaleza.
• Marca de tiempo. Puedes adivinar una ventana temporal y cortar ahí, pero los subagentes se ejecutaron en paralelo y sus registros se intercalan con los del bucle principal en la línea de tiempo; y «la tarde» del usuario podía ser las 2 o las 4, no se acuerda.

El problema no es que a los registros les falte detalle: es que los registros no tienen relaciones entre sí. La lección 3 convirtió cada paso en datos, pero esos datos son un montón de filas paralelas. Cuál fila causó cuál, quién es hijo de quién: ni una palabra al respecto. Cientos de objetos JSON bien formateados y sigue siendo un montón de arena, solo que esta vez la arena es más cuadrada.

Esta lección agrega esa capa que falta.

ID de correlación: la etiqueta con el nombre de un prompt

El paso más simple: darle un ID a «un evento disparador» y hacer que cada evento nacido de ese disparador copie ese ID. Eso es un ID de correlación. No necesita infraestructura de ningún tipo: es apenas un campo.

El diseño de primera mano de Claude Code hace exactamente esto. Después de que 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 con el único prompt que los disparó¹. La receta de depuración que dan los docs es igual de directa: para trazar toda la actividad disparada por un solo prompt, filtra tus eventos por un valor concreto de prompt.id¹.

Este y el ID de sesión son dos granularidades distintas, cada una con su tarea:

Volvamos a los 400 registros del inicio: si cada registro llevara prompt_id, bastaría con buscar en la transcripción de la sesión el id que corresponde a «corregir unos textos en la página de login», filtrar una vez, y 400 baja a 12. Por primera vez la arena tiene un borde.

Pero un borde no es una estructura. Esos 12 registros siguen siendo 12 filas planas. Todavía no sabes si la edición errónea del archivo de pruebas vino directamente del bucle principal o de un subagente que despachó; no sabes si esa herramienta de 40 segundos pasó 40 segundos esperando a que hicieras clic en «aprobar».

Spans y trazas: ordenar los eventos en un árbol

Primero traduzcamos algunos términos a lenguaje llano, porque los vamos a usar de aquí en adelante:

• span: el registro de «un trabajo con un principio y un final». Tiene un nombre (como llm_request), una hora de inicio, una hora de fin y varios atributos colgando de él (nombre del modelo, nombre de la herramienta, cantidad de tokens). Un span puede identificar a su span padre.
• traza: todo un árbol de spans conectados por relaciones padre-hijo. Todo lo que ocurrió durante una solicitud completa, de principio a fin, leído como árbol.
• exportador: el código dentro del proceso encargado de empaquetar los spans y mandarlos afuera.
• colector: la estación de relevo o servicio backend que recibe esos spans. El exportador le manda los datos; tú ves el árbol en su panel.

El trazado distribuido de Claude Code exporta spans que vinculan cada prompt del usuario con las solicitudes a la API y las ejecuciones de herramientas que dispara, de modo que puedes ver una solicitud completa como una sola traza en tu backend de trazado¹. La jerarquía concreta es esta: cada prompt del usuario abre un span raíz claude_code.interaction; las llamadas a la API, las llamadas a herramientas y las ejecuciones de hooks se registran como hijos suyos; los spans de herramienta tienen a su vez dos spans hijos: uno para el tiempo que se pasó esperando una decisión de permiso y otro para la ejecución en sí¹.

Vale la pena detenerse en esos dos spans hijos bajo una herramienta. En la lección anterior registraste duration_ms: una herramienta se ejecutó durante 40 segundos. Pero «40 segundos donde 38 fueron esperando a que alguien hiciera clic en aprobar» y «40 segundos donde 38 fueron ejecutando el comando» son dos problemas completamente distintos. El primero significa arreglar la configuración de permisos o cambiar el patrón de interacción; el segundo significa arreglar la implementación de la herramienta. Los mismos 40 segundos, partidos en dos segmentos, te dan dos arreglos distintos. Eso es lo que la estructura de árbol te da por encima de los campos planos.

El Agent SDK lo dice más directo: las trazas son la vista más detallada que puedes obtener de una ejecución de agente; con CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 activado, cada paso del bucle del agente se convierte en un span que puedes inspeccionar en tu backend de trazado². La CLI trae instrumentación de OpenTelemetry incorporada: registra spans alrededor de cada solicitud al modelo y cada ejecución de herramienta, emite métricas para los contadores de tokens y costo, y emite eventos de log estructurados para prompts y resultados de herramientas².

Compara eso con el arnés que escribiste en el curso 7 de esta serie («Fundamentos del arnés de agentes: bucles y control»): tu bucle ya tiene posiciones claras —«enviar solicitud / recibir tool_use / ejecutar herramienta / devolver tool_result»— y cada posición mapea naturalmente a un span. No te faltan posiciones, te faltan relaciones padre-hijo.

Propagación entre fronteras: subagentes, tu aplicación, subprocesos de Bash

Un árbol se ve lindo, pero una ejecución real cruza varias fronteras de proceso. ¿Puede el árbol seguir conectado después de cruzarlas? Sí, pasando «quién es mi padre» hacia abajo todo el camino.

Una capa hacia abajo: los subagentes. Cuando el agente lanza un subagente a través de la herramienta Agent, los spans llm_request y tool del subagente se anidan bajo el span claude_code.tool del agente padre, de modo que toda la cadena de delegación aparece como una sola traza². Esto resuelve una pregunta que sin el árbol no tiene respuesta: ¿de quién son los tokens del subagente? Están anidados bajo esa llamada a herramienta, que está anidada bajo ese prompt, así que pertenecen a ese prompt. No hace falta ningún pegado adicional.

Una capa hacia arriba: tu aplicación. El SDK propaga automáticamente el contexto de traza W3C hacia el subproceso de la CLI. El contexto de traza W3C es apenas una cadena estandarizada que contiene el id de traza y el id del span actual: quien la reciba sabe dónde engancharse. Cuando llamas a query() mientras hay un span de OpenTelemetry activo en tu aplicación, el SDK inyecta TRACEPARENT y TRACESTATE en el entorno del proceso hijo, la CLI los lee y su span claude_code.interaction pasa a ser hijo de tu span: la ejecución del agente aparece dentro de la traza de tu aplicación en lugar de como una raíz desconectada².

Esta diferencia es muy práctica cuando investigas incidentes en producción: el usuario se queja de «hice clic en ese botón y la página se quedó girando 20 segundos». Entras a la traza de esa solicitud HTTP y puedes seguirla hasta la llamada a herramienta dentro del agente que tardó 14 segundos, sin cambiar de sistema ni alinear marcas de tiempo.

Más abajo todavía: los comandos que el propio agente ejecuta. Cuando el trazado está activo, los subprocesos de Bash y PowerShell heredan automáticamente una variable de entorno TRACEPARENT que contiene el contexto de traza W3C del span de ejecución de herramienta activo¹. Si un comando lanzado a través de la herramienta Bash emite sus propios spans de OpenTelemetry, esos spans se anidan bajo el span claude_code.tool.execution que envuelve al comando².

Conecta los tres segmentos y un árbol puede arrancar en tu solicitud web, pasar por la CLI, pasar por un subagente y crecer hasta una etapa de compilación dentro del npm run build que ejecutó el agente.

Solo estructura, nunca contenido

Quizá te estés preguntando: si cada paso que da el agente se manda a un backend externo, ¿eso incluye lo que el usuario le dijo y el contenido de los archivos que leyó y escribió?

El análisis retrospectivo de Anthropic sobre su sistema de investigación multiagente deja dos conclusiones paralelas. Una es la ganancia: después de poner en marcha el trazado completo, pudieron diagnosticar por qué fallaban los agentes y arreglar los problemas de forma sistemática³. La otra es el límite: monitorearon patrones de decisión y estructuras de interacción de los agentes sin monitorear el contenido de las conversaciones individuales, para preservar la privacidad de los usuarios; incluso esa observabilidad de alto nivel les ayudó a diagnosticar causas raíz, descubrir comportamientos inesperados y corregir fallos comunes³.

La postura por defecto de las herramientas de primera mano coincide exactamente con ese principio. La telemetría es estructural por defecto: duraciones, nombres de modelo y nombres de herramientas se registran en cada span; los conteos de tokens se registran cuando la solicitud subyacente a la API devuelve datos de uso, así que los spans de solicitudes fallidas o abortadas pueden omitirlos; el contenido que tu agente lee y escribe no se registra por defecto². El contenido de los prompts del usuario tampoco se recolecta por defecto: solo se registra la longitud del prompt; para incluir el contenido hay que activar explícitamente OTEL_LOG_USER_PROMPTS=1¹. La página del Agent SDK pone el mismo recordatorio junto a sus propios interruptores de recolección de contenido: deja estos sin definir a menos que tu pipeline de observabilidad esté aprobado para almacenar los datos que maneja tu agente².

Para muchos equipos esto es una buena noticia: no necesitas ganar una batalla de cumplimiento normativo sobre «¿podemos mandar contenido de usuarios a un backend de terceros?» antes de empezar a ver qué hace tu agente. Muchos problemas son visibles en la capa de estructura.

Cuando diseñes trazas para tu propio arnés, toma esto como valor por defecto: registra en los spans nombres, duraciones, nombres de herramientas, conteos de tokens y tipos de error; deja el contenido de parámetros y valores de retorno en los registros crudos locales (los de la lección 2) y recupéralos por id cuando los necesites.

El propio pipeline de observabilidad puede mentirte

Todo lo anterior trató sobre «qué puedes ver una vez que el árbol está construido». Esta sección trata sobre algo que ocurre antes y con lo que es más fácil quemarse: crees que estás mirando datos, pero en realidad estás mirando un panel vacío.

Lo primero que hay que recordar: el fallo de exportación es silencioso por defecto. Si el endpoint es inalcanzable o el backend rechaza los datos, el agente sigue ejecutándose con normalidad y la CLI descarta la telemetría sin que aparezca ningún error en tu aplicación². Este diseño es correcto —el pipeline de observabilidad no debería tumbar el flujo principal—, pero el costo es que un pipeline roto y todo-funcionando se ven idénticos desde tu lado.

Lo segundo: la exportación por lotes pierde datos bajo condiciones concretas. La CLI agrupa la telemetría en lotes y exporta a intervalos. En una salida limpia del proceso intenta hacer flush de los datos pendientes, pero ese flush está acotado por un timeout corto, así que todavía se pueden perder spans si el colector responde lento; y si tu proceso es matado antes de que la CLI termine su apagado, todo lo que quede en el búfer del lote se pierde². Por defecto, las métricas se exportan cada 60 segundos y las trazas y los logs cada 5 segundos². Junta esas frases: una ejecución de agente corta en CI que termina en tres a cinco segundos depende de que «el flush se complete dentro del timeout Y el proceso no sea matado antes» para conservar la telemetría de la cola, y el intervalo de exportación amplifica la cantidad que queda sentada en el búfer. Escenarios así necesitan intervalos de exportación bastante más cortos que la duración de la ejecución, y hay que asegurarse de que el proceso salga limpio.

Lo tercero, y lo que habría que hacer primero al investigar: verificar la instrumentación misma (instrumentación es solo otra palabra para las sondas que instalaste). Para verificar una configuración que exporta métricas, busca en tu backend la métrica claude_code.session.count, que Claude Code emite cuando arranca una sesión¹; si no llega nada, ejecuta claude --debug y revisa el log de depuración en busca de errores de exportación de OTel¹. El valor de estos dos pasos es que parten «¿tiene un problema el agente?» y «¿está funcionando el pipeline?» en dos preguntas que se responden por separado.

Dos trampas de configuración más en las que es fácil pisar:

• Por defecto, la CLI reporta service.name como claude-code. Si ejecutas varios agentes, o ejecutas el SDK junto a otros servicios que exportan al mismo colector, sobrescribe el nombre del servicio y agrega atributos de recurso para poder filtrar por agente en tu backend². Si no, los spans de tres agentes se mezclan bajo el mismo nombre de servicio y estás mirando una sopa.
• Cuando ejecutes a través del SDK, no pongas console como valor de exportador². Los docs no dicen por qué; por cómo se comunican el SDK y la CLI, el SDK le habla a la CLI por stdout, e imprimir spans ahí revolvería ese canal.

Tres señales, puedes activar solo las que necesitas

No hace falta encender el paquete completo de entrada. La CLI exporta tres señales independientes de OpenTelemetry —métricas, eventos de log y trazas—, cada una con su propio interruptor de activación y su propio exportador, así que puedes encender solo las que necesites².

Esto da una secuencia natural de adopción:

1. Enciende primero las métricas. El costo y el uso de tokens son las primeras preguntas que hace la gente, las métricas son lo más barato, y el intervalo de exportación por defecto de 60 segundos está bien para servicios de larga duración.
2. Después enciende los eventos de log. Resultados de herramientas y decisiones de permisos: estos eventos estructurados son la materia prima de los patrones de lectura diagnóstica de la lección 3.
3. Enciende las trazas cuando te topes con un problema que no puedas explicar. Son lo más caro y lo más detallado: las necesitas cuando de verdad tienes que «ver la forma de una ejecución».

El destino de exportación es cualquier backend que acepte el OpenTelemetry Protocol (OTLP); los docs nombran algunos: Honeycomb, Datadog, Grafana, Langfuse o un colector autoalojado². Cuál elegir queda fuera del alcance de este curso; solo diré esto: que las tres señales sean independientes significa que puedes probar el agua con la pieza más chica primero, sin esperar a que la infraestructura completa esté lista.

De paso: ese mismo lote de eventos también es un rastro de auditoría

Los eventos estructurados tienen otro uso más, ajeno a la depuración; basta con saber que existe.

Con la identidad del usuario final adjunta, los eventos tool_decision, tool_result, mcp_server_connection y permission_mode_changed, que se exportan como registros de log nombrados con el prefijo claude_code., se convierten en un rastro de auditoría por usuario que puedes reenviar a una plataforma de Security Information and Event Management (SIEM)². Cada evento lleva atributos de identidad que vinculan llamadas a herramientas, actividad de MCP y decisiones de permisos con el usuario que las disparó¹.

El mismo lote de datos, leído de otra manera, es la materia prima de otro trabajo: al depurar cortas horizontalmente por prompt.id, al auditar cortas verticalmente por usuario. Los temas de seguridad no se amplían en este curso.

Respuestas que este curso no te va a dar

Algunas cosas necesitan límites claros para que no salgas a buscar recetas hechas en otro lado:

• Tasas de muestreo y ventanas de retención: almacenar trazas a volumen completo se pone caro, y cuánto muestrear y cuánto tiempo conservarlo son preguntas reales, pero no hay guía en el material primario, así que este curso no va a inventar números. Cuando tu volumen de datos se vuelva un problema de verdad, eso es entre tú y la factura de tu backend.
• Umbrales de alerta: lo mismo, no se dan números.
• Hooks: cómo instalar sondas en puntos de control del ciclo de vida, a qué puede acceder cada uno de PreToolUse y PostToolUse: eso es la lección 5. Dejemos plantada acá una interfaz: la entrada del hook lleva el UUID del prompt de usuario que se está procesando, y es el mismo valor que el atributo prompt.id en los eventos de telemetría, así que la salida del hook y la telemetría del mismo prompt se pueden correlacionar⁴. El ID de correlación que establece esta lección queda directamente utilizable en la siguiente.
• Tu propio arnés no necesita OTel completo. Esta lección usa el diseño de primera mano como herramienta didáctica porque expone toda la estructura que debería estar ahí. Pero lo que en realidad quieres es solo el árbol: la lección 6 va a generar un trace_id por ejecución, agregar span_id y un campo puntero al padre en cada registro, y después escribir una docena de líneas de código para imprimirlo indentado; obtendrás un árbol construido con el mismo mecanismo padre-hijo (la lección 6 explicará que eligió un padre distinto para las herramientas), sin colector, sin backend, sin dependencias. Si algún día necesitas conectar OTLP, los campos ya están ahí.

💻 Ejercicios

Resumen

• Los logs estructurados resolvieron «¿son los registros lo bastante detallados?», pero no resolvieron «¿qué relación tienen entre sí los registros?». Los IDs de correlación son el primer paso para agregar relaciones: un prompt puede disparar varias llamadas a la API y varias herramientas, y prompt.id vincula todos esos eventos con el único prompt que los disparó; el movimiento inicial al depurar es filtrar por ese valor¹.
• Un span es el registro de un trabajo con un principio y un final; una traza es el árbol enhebrado por relaciones padre-hijo. El trazado distribuido vincula cada prompt del usuario con las solicitudes a la API y las ejecuciones de herramientas que dispara, como spans, de modo que la solicitud completa se lee como una sola traza en tu backend de trazado¹.
• La jerarquía es fija: cada prompt abre un span raíz claude_code.interaction, y las llamadas a la API, las llamadas a herramientas y las ejecuciones de hooks son sus hijos; los spans de herramienta tienen dos spans hijos que registran por separado el tiempo esperando el permiso y el tiempo ejecutando de verdad¹. Con la telemetría mejorada encendida, cada paso del bucle del agente se vuelve un span inspeccionable; las trazas son la vista más detallada de una ejecución².
• Los árboles pueden seguir conectados a través de fronteras de proceso: los spans del subagente se anidan bajo el span de herramienta del agente padre y toda la cadena de delegación se lee como una sola traza; el SDK inyecta TRACEPARENT y TRACESTATE en el subproceso de la CLI, así que la ejecución del agente aparece dentro de la traza de tu aplicación en lugar de como una raíz desconectada²; bajando más, los subprocesos de Bash heredan TRACEPARENT¹, y los spans que emiten los comandos se anidan bajo el span de esa ejecución de herramienta².
• Poner en marcha el trazado completo habilita el diagnóstico sistemático de los fallos³; y monitorear solamente patrones de decisión y estructuras de interacción, sin mirar el contenido de las conversaciones, alcanza para diagnosticar causas raíz y descubrir comportamientos inesperados³. El mecanismo encaja exactamente: la telemetría es estructural por defecto —duraciones, nombres de modelo y nombres de herramientas se registran en cada span; el contenido no se registra por defecto²—; el contenido de los prompts también registra solo la longitud por defecto, y para incluir contenido hay que activar un interruptor explícitamente¹.
• Métricas, eventos de log y trazas son tres señales independientes, cada una con su propio interruptor de activación y su propio exportador, así que puedes encender solo las que necesites²: adopción incremental, sin necesidad de ir con todo de una vez.
• El propio pipeline de observabilidad puede mentirte: el fallo de exportación es silencioso por defecto, el agente se ejecuta con normalidad mientras la telemetría se descarta y no aparece ningún error²; la exportación por lotes intentará hacer flush en una salida limpia, pero está acotada por un timeout corto, y si matan el proceso el búfer se pierde entero²; por defecto las métricas cada 60 segundos y las trazas y los logs cada 5 segundos², así que las ejecuciones de vida corta necesitan intervalos más cortos. Lo primero al investigar es verificar la instrumentación misma: busca en el backend esa métrica de conteo de sesiones¹ y, si no está, enciende --debug para ver los errores de exportación¹.
• Dos trampas de configuración: varios agentes compartiendo un mismo backend necesitan sobrescribir service.name y agregar atributos de recurso para poder distinguirse²; cuando ejecutes a través del SDK, no pongas console como exportador².
• Ese mismo lote de eventos estructurados, leído de otra manera, es material de auditoría: con atributos de identidad adjuntos, las decisiones de herramientas, los resultados de herramientas, las conexiones MCP y los cambios de modo de permisos se vuelven un rastro de auditoría por usuario que puedes reenviar a un SIEM², y los atributos de identidad de cada evento vinculan las llamadas a herramientas con la persona que las disparó¹.
• No hay guía primaria sobre tasas de muestreo ni ventanas de retención, así que este curso no da números. Tu propio arnés tampoco necesita OTel completo: la lección 6 usa un trace_id más campos punteros al padre más impresión indentada para obtener un árbol construido con el mismo mecanismo padre-hijo.

>> Lección 5: Sondas en las puertas: hooks y un flujo de depuración

Footnotes

1. Monitoring — Claude Code Official Documentation — https://code.claude.com/docs/en/monitoring-usage ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷

2. Observability with OpenTelemetry — Claude Agent SDK Official Documentation — https://code.claude.com/docs/en/agent-sdk/observability ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹ ↩²⁰ ↩²¹ ↩²² ↩²³ ↩²⁴ ↩²⁵ ↩²⁶

3. How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩² ↩³ ↩⁴

4. Hooks reference — Claude Code Official Documentation — https://code.claude.com/docs/en/hooks ↩