Prácticas recomendadas de observabilidad

Instrumentar una aplicación Claude de manera adecuada significa que un pico de costos, una regresión de latencia o una regresión de caché aparezcan en un panel o una página dentro de la hora, no en la factura del próximo mes.

Esta lista de verificación consolida las prácticas cubiertas en esta sección en reglas contra las cuales puedes verificar tu propia instrumentación.

Cómo usar esta lista de verificación

• Trata la sección A como la base innegociable para cualquier integración de Claude más allá de un script desechable.
• Las secciones B y C valen el esfuerzo una vez que tengas bucles de agente de varios pasos o tráfico de producción para observar.
• Revisa esta lista después de tu primer incidente real y anota qué regla lo habría detectado antes.
• Usa las casillas de verificación como una auditoría literal de tu instrumentación actual, no solo como un ejercicio de lectura.

A - Fundamentos de registro

• Registra cada llamada a Claude en un esquema estructurado consistente. Captura el prompt, la respuesta, el modelo, los recuentos de tokens, la latencia y un ID de solicitud para cada llamada, no solo para las que fallan.
• Usa logging.Logger, no print. La salida estructurada a través de un marco de registro real se integra con el filtrado por nivel de registro y la mayoría de los agentes de agregación de registros de forma predeterminada.
• Registra los errores en el mismo esquema que los éxitos. Una forma compartida con un campo status permite que una consulta cubra ambos resultados en lugar de mantener registros de errores separados.
• Genera el ID de solicitud antes de la llamada, no después. Esto garantiza que tengas un identificador incluso cuando la llamada genera una excepción.
• Centraliza la construcción de registros en una sola función o adaptador. Construir el diccionario de registro en línea en cada sitio de llamada es la forma en que los esquemas se desvían silenciosamente en una base de código.
• Captura campos de tokens relacionados con la caché de forma defensiva. Accede a cache_read_input_tokens y campos similares con getattr(..., None) ya que solo se rellenan una vez que se aplica el almacenamiento en caché de prompts.

B - Visibilidad de rastreo y costos

• Emite un span raíz por ejecución de agente, con un span hijo por llamada al modelo e invocación de herramienta. Esto es lo que preserva la forma de una ejecución de varios pasos, que los registros planos por sí solos no pueden mostrar.
• Sigue la convención de nomenclatura de atributos gen_ai.* en los spans. La nomenclatura consistente mantiene los rastreos consultables de la misma manera independientemente de qué servicio o proveedor de modelos los produjo.
• Establece explícitamente el estado del span en caso de error, no solo record_exception. Un span sin un estado de error explícito aún puede renderizarse como exitoso en algunos visores de rastreo.
• Mantén el texto completo del prompt/respuesta fuera de los atributos del span. Los spans son para metadatos cortos y estructurados; pon el texto completo en registros estructurados en su lugar, unidos por el ID de solicitud.
• Calcula y envía el costo por llamada, no solo los recuentos de tokens. Los recuentos de tokens por sí solos no responden a "¿cuánto costó esto?"; multiplica por el precio actual por modelo y trata esa tabla de precios como configuración.
• Coloca los costos de Claude y las métricas de latencia en el mismo panel que tus otras métricas de infraestructura. Un panel separado solo para LLM se revisa con mucha menos frecuencia que el que tu equipo observa diariamente.
• Etiqueta cada métrica con al menos el modelo y la característica/endpoint. Las métricas de costos sin etiquetar no pueden decirte qué modelo o qué parte de tu producto está impulsando el gasto.

C - Alertas y respuesta a incidentes

• Alerta sobre el gasto en relación con una línea base móvil, no solo con una cantidad fija en dólares. Un umbral fijo que se ajusta a tu tráfico actual se vuelve obsoleto a medida que aumenta el uso.
• Requiere un piso absoluto mínimo junto con cualquier alerta basada en ratios. Una verificación solo de ratio puede alertar sobre fluctuaciones estadísticamente grandes pero prácticamente insignificantes cuando la línea base es pequeña.
• Alerta sobre la tasa de fallos de caché de forma independiente del gasto. Es un indicador principal que a menudo se mueve antes de que el gráfico de costos se doble visiblemente.
• Ejecuta las verificaciones de alerta según un horario, no en línea en la ruta de solicitud. La lógica de evaluación de alertas no debe agregar latencia o un nuevo modo de fallo al código que ya está en la ruta crítica para los usuarios.
• Usa la deduplicación de tu herramienta de paginación, no lógica de deduplicación personalizada. Reimplementar la escalada y la deduplicación en la propia verificación generalmente produce un peor comportamiento que el manejo incorporado de la herramienta de paginación.
• Verifica la correlación de despliegue antes de asumir un problema del lado del proveedor. La mayoría de los picos de latencia o errores se remontan a un despliegue reciente, una edición de prompt o un cambio de configuración más rápido de lo que se remontan a un incidente del lado de Anthropic.
• Anota lo que verificaste después de cada incidente, incluidos los callejones sin salida. Una nota corta de incidente ahorra a la próxima investigación el tener que recorrer el mismo camino.

D - Consistencia del equipo

• Documenta tu esquema de nombres de spans y atributos en un ADR antes de que un segundo servicio adopte el rastreo. Sin una decisión documentada, cada servicio inventa su propia nomenclatura, y las consultas de rastreo entre servicios se vuelven imposibles.
• Documenta explícitamente tu política de muestreo, incluida la excepción de spans de error. "Muestrear apropiadamente" no es lo suficientemente preciso para que cada servicio lo implemente de la misma manera.
• Reemplaza los ADR en lugar de editarlos en su lugar cuando el esquema cambie. Editar en su lugar destruye el registro histórico de por qué se tomó la decisión original.
• Asigna a los servicios existentes una fecha límite de migración concreta cuando cambie el esquema. Un ADR sin un plan de implementación deja a los servicios ya instrumentados permanentemente fuera de sincronización con los nuevos.

Aplicando la lista de verificación en orden

• Sección A primero, siempre. El registro estructurado casi no cuesta nada de añadir y es la base sobre la que se construye toda otra práctica en esta lista.
• Sección B una vez que tengas un bucle de agente de varios pasos o tráfico de producción que valga la pena observar. El rastreo y los paneles agregan un esfuerzo de ingeniería real, por lo que ganan su lugar una vez que el registro por sí solo deja de responder a tus preguntas.
• Sección C una vez que B esté en su lugar. Alertar sobre métricas que aún no existen no es posible; haz que las señales fluyan antes de establecer umbrales sobre ellas.
• Sección D tan pronto como un segundo equipo o servicio comience a instrumentar. Esperar hasta que tres servicios ya se hayan desviado convierte esto de una decisión proactiva en un proyecto de limpieza.

Preguntas frecuentes

Relacionado

• Cómo funciona la observabilidad para aplicaciones LLM - el modelo mental sobre el que se construye esta lista de verificación.
• Fundamentos de observabilidad - el punto de partida mínimo para la sección A.
• Instrumentación de bucles de agente con rastreo OpenTelemetry - las prácticas de rastreo en la sección B.
• Integración de paneles de uso y costos de Claude con Datadog - las prácticas de panel en la sección B.
• Alertas sobre picos de gasto y tasas crecientes de fallos de caché - las prácticas de alerta en la sección C.
• Correlación de latencia y errores con despliegues de código - la lista de verificación de correlación de despliegues referenciada en la sección C.
• Plantilla ADR: Definición de tu esquema de spans OTel para llamadas a herramientas - las prácticas ADR en la sección D.

Versiones de pila: Escrito contra la línea de modelos 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 anthropic de Python (ú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.