Cómo funciona la observabilidad para aplicaciones LLM
La observabilidad para una aplicación LLM responde a una pregunta simple bajo presión: ¿qué está haciendo realmente mi sistema basado en Claude en este momento, y por qué se ha vuelto lento, incorrecto o caro?
Esa pregunta suena a observabilidad de infraestructura clásica, y en su mayor parte lo es.
La diferencia está en lo que observas moverse a través del sistema: prompts, llamadas a herramientas, tokens y dólares, en lugar de solo solicitudes HTTP y consultas a bases de datos.
Esta página construye el modelo mental que el resto de la sección de observabilidad asume: rastrear spans de llamadas a agentes y modelos, registrar prompts y respuestas en un esquema consistente, y alertar sobre anomalías de costos o confiabilidad antes de que se conviertan en incidentes.
Resumen
- Idea Central: La observabilidad para aplicaciones LLM significa rastrear cada llamada a modelo y cada invocación de herramienta como un span, registrar el prompt/respuesta/recuento de tokens para cada llamada en un esquema estructurado, y alertar sobre anomalías de costos o confiabilidad, los mismos tres pilares utilizados para cualquier sistema distribuido, aplicados a las llamadas de Claude.
- Por qué Importa: Un bucle de agente puede llamar a un modelo cinco veces, invocar tres herramientas y fallar en el cuarto paso, y sin rastreo solo ves "la solicitud falló", no dónde ni por qué.
- Conceptos Clave: span, traza, log estructurado, uso de tokens, anomalía de costo, tasa de fallos de caché.
- Cuándo Usar: Cualquier integración de Claude más allá de un único script desechable se beneficia de esto, pero se vuelve indispensable una vez que tienes bucles de agente de varios pasos, uso de herramientas o un gasto en producción del que eres responsable.
- Limitaciones / Compensaciones: La observabilidad añade sobrecarga de latencia, volumen de logs y tiempo de ingeniería; la sobre-instrumentación de un prototipo de bajo riesgo desperdicia esfuerzos que se gastarían mejor en enviar.
- Temas Relacionados: Rastreo OpenTelemetry, esquemas de logging estructurado, dashboards de costos, alertas de gasto, correlación de despliegues.
Fundamentos
Tres ideas soportan casi todo el peso en este espacio: trazas, logs estructurados y métricas.
Una traza es la forma de una operación de extremo a extremo, compuesta por spans.
En un agente LLM, una traza típicamente cubre una solicitud de usuario, y cada span dentro de ella cubre una llamada a modelo o una invocación de herramienta, anidados para reflejar el orden real de las llamadas.
Un log estructurado es diferente de una traza, aunque a menudo se confunden.
Una entrada de log estructurado captura el contenido de una única llamada a la API de Claude: el prompt, la respuesta, los recuentos de tokens, el modelo utilizado, la latencia y un ID de solicitud, todo en un esquema consistente y analizable por máquina.
Piensa en la traza como la respuesta a "¿qué sucedió y en qué orden?", y en el log estructurado como la respuesta a "¿qué enviamos y obtuvimos exactamente?".
Necesitas ambos, porque una traza sin contenido de log te dice que una llamada a herramienta fue lenta pero no por qué, y un log sin una traza te dice qué contenía una llamada pero no cómo encajaba en la ejecución más amplia del agente.
Una analogía mental simple: si tu bucle de agente es una llamada telefónica entre departamentos, la traza es el registro de llamadas que muestra quién llamó a quién y durante cuánto tiempo, y el log estructurado es la transcripción de lo que se dijo realmente en cada llamada.
Las métricas son el tercer pilar: números agregados a lo largo del tiempo, como tokens por minuto, dólares por día o latencia p95, generalmente derivados de las trazas y logs en lugar de capturados por separado.
Mecánicas e Interacciones
Así es como estas piezas interactúan durante una ejecución real de un agente.
Llega una solicitud, y tu instrumentación abre un span raíz para ella.
Cada vez que el agente llama a Claude, abre un span hijo, registra la latencia y el resultado, y lo cierra; cada vez que invoca una herramienta, lo mismo.
Trace: handle_user_request
Span: model_call (claude-sonnet-5) 120ms
Span: tool_call (search_docs) 85ms
Span: model_call (claude-sonnet-5) 340ms
Span: tool_call (write_file) 40ms
Span: model_call (claude-sonnet-5) 95msEsa forma sola, visible en un visor de trazas OpenTelemetry, te dice que el agente hizo tres llamadas a modelo y dos llamadas a herramientas, y que la segunda llamada a modelo fue donde residió la mayor parte de la latencia.
Independientemente, cada una de esas tres llamadas a modelo debería producir también una línea de log estructurado: el prompt exacto enviado, el texto de la respuesta, input_tokens, output_tokens, y cualquier cache_read_input_tokens, etiquetado con el mismo ID de solicitud que la traza.
El ID de solicitud es la clave de unión: te permite pasar de "este span de traza fue lento" a "aquí está el prompt y la respuesta exactos que lo hicieron lento" sin adivinar.
Aquí es donde la observabilidad de LLM diverge de la observabilidad típica de servicios web: los recuentos de tokens y la identidad del modelo son tan importantes como la latencia, porque impulsan el costo directamente.
Un span que tomó 200 ms y costó 40,000 tokens de entrada es un problema muy diferente a un span que tomó 200 ms y costó 200 tokens, incluso si un dashboard solo de latencia los representaría de manera idéntica.
Las métricas luego agregan esto: gasto total por hora, tasa de aciertos de caché en todas las llamadas, tasa de error por herramienta, percentiles de latencia por modelo.
El error común al razonar sobre esto es tratar la "observabilidad" como sinónimo de "logging", y detenerse ahí.
El logging solo te da contenido sin forma; puedes ver lo que hizo una llamada pero no cómo una cadena de seis llamadas se degradó durante la ejecución de un agente, y pierdes la capacidad de alertar sobre tendencias como "la tasa de fallos de caché aumentó un 15% desde el último despliegue".
Consideraciones Avanzadas y Aplicaciones
A escala, tres cosas separan a un equipo que puede depurar un incidente en minutos de uno que pasa una tarde adivinando.
Primero, nombres de span y atributos consistentes entre servicios, para que una traza de tu pipeline de ingesta y una traza de tu runtime de agente usen el mismo vocabulario para "modelo", "herramienta" y "ID de solicitud".
Segundo, correlacionar señales específicas de LLM (gasto, tasa de fallos de caché, tasa de rechazo) con los mismos marcadores de despliegue que ya usas para regresiones regulares de servicios, para que un pico sea atribuible a "el despliegue a las 14:02" en lugar de ser tratado como ruido inexplicable.
Tercero, exportar los datos de uso y costo de Claude a los mismos dashboards que tu equipo ya observa para la infraestructura, en lugar de mantener un dashboard separado y fácilmente ignorado solo para LLM.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
Sentencias print / logging ad hoc | Rápido de añadir, configuración cero | Sin estructura, no consultable, sin visibilidad de costos | Scripts locales, experimentos rápidos |
| Logs estructurados solamente | Consultable, captura detalles de prompt/respuesta/token | Sin visibilidad del orden de llamadas de múltiples pasos o cadenas de latencia | Integraciones de llamada única, APIs simples de solicitud/respuesta |
| Rastreo OTel + logs estructurados | Visibilidad completa de forma y contenido, unibles a través del ID de solicitud | Mayor esfuerzo de instrumentación, sobrecarga añadida | Bucles de agente de múltiples pasos, agentes que usan herramientas, sistemas de producción |
| Rastreo + logs + dashboard de costos de terceros (ej. Datadog) | El costo y la confiabilidad se sientan junto a las métricas de infraestructura existentes, soporta alertas | Requiere un pipeline de exportación y mantenimiento de dashboards | Equipos que ya ejecutan herramientas de observabilidad de producción |
Un modo de fallo relacionado que vale la pena nombrar: muestrear cada span al 100% en un producto de agente de alto volumen se vuelve caro y ruidoso rápidamente.
La mayoría de los equipos se conforman con muestreo completo para errores y valores atípicos de costos, con una tasa de muestreo menor para spans exitosos de rutina, una decisión que vale la pena escribir explícitamente (ver la plantilla ADR referenciada a continuación) para que se mantenga consistente a medida que el equipo crece.
Conceptos Erróneos Comunes
- "Registrar la respuesta es suficiente." - Sin recuentos de tokens y un ID de solicitud que vincule el log a un span de traza, puedes ver qué regresó pero no por qué fue lento o caro en relación con el resto de la ejecución.
- "La observabilidad es solo para detectar interrupciones." - Una gran parte del valor es proactivo: detectar un pico de gasto o una tasa de fallos de caché creciente antes de que se convierta en un incidente, no solo diagnosticar uno después del hecho.
- "El rastreo y el logging son lo mismo." - El rastreo muestra la forma y el orden de una ejecución de múltiples pasos; el logging estructurado muestra el contenido de una llamada; necesitas ambos para depurar completamente un agente.
- "Esto solo importa a gran escala." - Incluso un proyecto secundario de un solo agente se beneficia del logging básico de prompt/respuesta/token, ya que el costo de la API de Claude y los patrones de rechazo son fáciles de juzgar erróneamente sin ningún registro.
- "El seguimiento de costos es una preocupación financiera, no de ingeniería." - Un bucle de agente descontrolado es un error de confiabilidad que resulta mostrarse primero como una anomalía de gasto, por lo que el mismo equipo que posee la latencia debe poseer las alertas de costos.
Preguntas Frecuentes
¿Es la observabilidad de LLM realmente diferente de la observabilidad de aplicaciones regulares?
- Mayormente los mismos tres pilares (trazas, logs, métricas), aplicados a un nuevo tipo de llamada.
- Las diferencias reales son lo que rastreamos: recuentos de tokens, identidad del modelo y costo por llamada, ninguno de los cuales existe en la telemetría típica de servicios web.
- La latencia sigue importando, pero una llamada rápida y cara y una llamada lenta y barata deben ser distinguibles, algo que los dashboards de solo latencia no hacen.
¿Necesito OpenTelemetry específicamente, o puedo usar mi propio formato de rastreo?
OTel no es obligatorio, pero es el estándar de facto para el rastreo basado en spans y se integra con la mayoría de los dashboards existentes y herramientas de ingesta de terceros (como Datadog). Crear tu propio formato de traza funciona para un solo servicio, pero añade fricción en el momento en que deseas correlacionar trazas entre servicios o exportar a un dashboard compartido.
¿Cuál es la configuración mínima viable de observabilidad para una pequeña integración de Claude?
- Registrar el prompt, la respuesta, el modelo, los recuentos de tokens, la latencia y un ID de solicitud para cada llamada, en un esquema consistente.
- Eso solo, sin rastreo ni dashboards, captura la mayoría de los problemas tempranos de costos y calidad.
- Añade rastreo una vez que tengas bucles de agente de múltiples pasos donde el orden de las llamadas importa.
¿Por qué el uso de tokens importa tanto como la latencia?
El uso de tokens impulsa el costo directamente, y a diferencia de la latencia, no siempre se correlaciona con el tiempo de reloj. Una llamada con un prompt grande en caché puede ser rápida pero aún así consumir una cantidad significativa de tokens de entrada, por lo que rastrear ambos de forma independiente es necesario para detectar regresiones de costos que una vista solo de latencia pasaría por alto.
¿Qué es una "tasa de fallos de caché" y por qué debería alertar sobre ella?
Es la proporción de llamadas que no logran alcanzar el caché de prompts de Anthropic, lo que significa que el prompt completo se reprocesa con el costo completo en lugar de la tarifa más barata del caché. Una tasa de fallos de caché creciente generalmente indica un cambio de código que rompió la elegibilidad del caché (por ejemplo, un prefijo de prompt inestable), y aumenta silenciosamente el gasto hasta que alguien nota el dashboard o recibe una alerta.
¿Cómo ayuda concretamente una traza a depurar una ejecución de agente lenta?
- Te muestra la lista ordenada de spans (llamadas a modelo y llamadas a herramientas) para una solicitud, con la duración por span.
- Puedes ver inmediatamente si la lentitud es un span dominante o está distribuida uniformemente entre varios.
- A partir de ahí, saltas al log estructurado para el ID de solicitud de ese span específico para ver el contenido real del prompt y la respuesta.
¿Debería cada span ser registrado y rastreado con un muestreo del 100%?
No usualmente a un volumen de producción significativo. Un patrón común es el muestreo completo para errores y valores atípicos de costos/latencia, con una tasa de muestreo menor para spans exitosos de rutina, documentado explícitamente para que todo el equipo lo aplique consistentemente.
¿Cuál es la diferencia entre un "span" y una "traza"?
Una traza es la operación completa de extremo a extremo (típicamente una solicitud de usuario); un span es una unidad de trabajo dentro de ella (una llamada a modelo o una invocación de herramienta). Una traza está compuesta por uno o más spans anidados.
¿Por qué vincular las métricas de costo de Claude al mismo dashboard que mis otras métricas de infraestructura?
- Los ingenieros ya observan ese dashboard diariamente; un dashboard separado solo para LLM se ignora.
- Las anomalías de costo y latencia en la capa del modelo a menudo se correlacionan con los mismos despliegues que afectan al resto del sistema.
- Hace que el costo sea una señal de confiabilidad de primera clase en lugar de una sorpresa mensual en la facturación.
¿Qué debería incluir en una entrada de log estructurado para una llamada a la API de Claude?
Como mínimo: el prompt, el texto de la respuesta, input_tokens, output_tokens, el nombre del modelo, la latencia y un ID de solicitud. Añade campos de tokens de caché (cache_read_input_tokens, cache_creation_input_tokens) una vez que dependas del caché de prompts, ya que esos números afectan directamente la interpretación del costo.
¿Cómo encajan los despliegues en la observabilidad para aplicaciones LLM?
Las marcas de tiempo de despliegue se convierten en una línea de referencia en tus gráficos de latencia, errores y costos. Cuando una métrica aumenta justo después de un marcador de despliegue, puedes atribuir la regresión a un cambio de código específico en lugar de investigar desde cero, lo cual es mucho más rápido que tratar cada pico como un misterio.
¿Vale la pena instrumentar un pequeño prototipo antes de que tenga usuarios reales?
El rastreo completo y los dashboards son probablemente excesivos, pero el logging estructurado básico (prompt, respuesta, tokens, ID de solicitud) es barato de añadir temprano y ahorra un tiempo de depuración significativo tan pronto como el prototipo comienza a comportarse mal o a costar más de lo esperado.
Relacionados
- Fundamentos de Observabilidad - el punto de partida mínimo: registrar un prompt, respuesta y recuento de tokens para cada llamada.
- Instrumentación de Bucles de Agente con Rastreo OpenTelemetry - cómo emitir los spans descritos en el modelo mental de esta página.
- Registro Estructurado de Prompts, Respuestas y Recuentos de Tokens - el esquema de log que se empareja con el rastreo.
- Integración de Dashboards de Uso y Costo de Claude con Datadog - colocar métricas de Claude junto a tus otros dashboards de infraestructura.
- Alertas sobre Picos de Gasto y Tasas Crecientes de Fallos de Caché - convertir estas señales en alertas proactivas.
- Correlación de Latencia y Errores con Despliegues de Código - una lista de verificación para el flujo de trabajo de correlación de despliegues.
- Plantilla ADR: Definición de tu Esquema de Spans OTel para Llamadas a Herramientas - documentación de las decisiones de nomenclatura de spans y muestreo.
- Mejores Prácticas de Observabilidad - una lista de verificación consolidada de esta sección.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de modelos, precios y versiones de SDK cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.