CCDV-P · Observabilidad y monitoreo en producción
Qué instrumentar en un sistema con Claude, y qué no guardar
Un cliente reporta que “el agente a veces tarda un minuto y da una respuesta rara”. Los logs del equipo tienen una línea por pedido: hora, usuario, “ok”. No hay forma de saber cuántos turnos dio el agente, qué herramientas llamó, cuánto costó ni si el caché funcionó. Sin instrumentación no se puede depurar, y con instrumentación mal pensada se filtran datos que no se debían guardar.
Trazas del loop del agente
Un agente no es una llamada, es un árbol de llamadas. La traza distribuida (distributed trace) representa una ejecución completa, con un span (span) por cada unidad de trabajo:
- el span raíz: la solicitud del usuario o la tarea;
- un span por cada llamada al modelo, con modelo, versión del prompt, tokens de entrada y salida, motivo de detención y latencia;
- un span por cada llamada a una herramienta, con nombre, duración, estado y tamaño del resultado;
- spans de subagentes, hijos del span que los lanzó, para que la traza siga la delegación entre agentes.
El identificador de traza se propaga entre servicios (incluido un servidor MCP remoto) para unir todo. OpenTelemetry es el estándar abierto habitual para esto, con convenciones de atributos para IA generativa; Claude Code también puede exportar telemetría por OpenTelemetry.
Métricas de tokens, costo y caché
Las métricas de tokens y costo (token and cost metrics) se toman del campo usage de cada respuesta: tokens de entrada, de salida, y los de caché (cache_creation_input_tokens y cache_read_input_tokens). Con eso se calculan:
- costo por solicitud, por tenant, por función y por versión de prompt;
- diagnóstico de caché: la tasa de aciertos (lecturas sobre lecturas más escrituras). Una tasa baja con un prefijo que “debería” cachearse apunta a un prefijo que cambia (una fecha en el system prompt, herramientas reordenadas) o a un TTL que vence entre llamadas;
- relación entrada/salida y distribución por turno, para ver agentes que se disparan.
Trazabilidad de grounding y razonamiento
Para auditar una respuesta, guardá qué fragmentos se recuperaron, con qué puntaje, de qué fuente y versión, y cuáles se citaron. Del razonamiento, guardá las decisiones observables (qué herramienta eligió y con qué argumentos) y la salida; el texto de pensamiento del modelo puede ser un resumen y no es una explicación garantizada fiel, así que no se usa como registro de auditoría.
Logs estructurados
Un log estructurado (structured log) es un evento con campos fijos (JSON): identificador de traza, tenant, versión del prompt, modelo, motivo de detención, herramienta, resultado, error clasificado. Se pueden agregar, filtrar y contar; una línea de texto libre no.
Captura de contenido y privacidad
Guardar prompts y respuestas completos ayuda a depurar, pero choca con privacidad, y con acuerdos de retención cero de datos (zero-data-retention, ZDR) en los que el proveedor no guarda el contenido. Esa política manda sobre la comodidad. Lo que conviene:
- Metadatos siempre, contenido por decisión: tokens, latencias, identificadores, motivos de detención y clasificación del error se guardan siempre; el contenido es configurable.
- Redacción antes de guardar de datos personales y secretos, y control de acceso y retención propios en tu almacén de trazas.
- Muestreo del contenido y captura completa solo para casos marcados (errores, reportes), con consentimiento y plazos.
- Con ZDR, instrumentá con identificadores y métricas, y reproducí los problemas con casos sintéticos o con contenido que la persona dueña acepte compartir.
Las trampas típicas
- Una línea de log por solicitud, sin turnos ni herramientas.
- Trazas que no cruzan el servidor MCP o los subagentes.
- Guardar contenido completo en un sistema de logs sin redacción ni retención.
- Mirar solo el costo total y no por tenant o versión de prompt.
- Usar el texto de pensamiento como registro de auditoría.
En el examen
Si necesitás depurar y hay restricción de privacidad, elegí metadatos y trazas estructuradas, no apagar la instrumentación ni guardar todo. Si el costo sube, buscá la métrica por función, tenant y caché que lo explique.
Pregunta rápida
Una pregunta del simulacro sobre este dominio. Cuenta para tu progreso.
A support agent handles each user request in a loop of model calls and tool calls (order lookup, refund policy search, ticket update). When users report wrong answers, the on-call engineer has only one log line per request with the final answer and the total duration. Finding which step went wrong requires re-running the conversation by hand.
The team already uses a standard distributed-tracing backend for its other services and wants the agent to be debuggable in the same way. The assistant serves about two thousand customers a day, and slow or wrong answers are the main source of escalations.
How should the agent be instrumented?