Correlacionar latencia y errores con despliegues de código
Cuando la latencia de las llamadas a Claude, la tasa de errores o la tasa de negativas se disparan, el camino más rápido a una causa raíz es comprobar si coincide con su último despliegue, en lugar de empezar de cero.
Esta lista de verificación le guía a través de la confirmación de esa correlación, la exclusión del culpable equivocado y el cierre del ciclo para que el próximo incidente sea más rápido de diagnosticar.
Cómo usar esta lista de verificación
- Trabaje a través de los elementos en orden; cada paso confirma o descarta la correlación del despliegue antes de pasar al siguiente.
- Mantenga una nota provisional de lo que comprobó y lo que encontró, ya que esa nota se convierte en su informe de incidente.
- No todos los elementos se aplican a todos los incidentes; omita los pasos que no se ajusten a su configuración (por ejemplo, si aún no tiene marcadores de despliegue, el elemento 3 se convierte en su primera solución, no en una comprobación que se pueda omitir).
- Vuelva a visitar esta lista de verificación después de cada incidente real y añada cualquier cosa que haya tenido que improvisar, para que se mantenga actualizada con la forma en que su equipo despliega realmente.
Triaje inmediato (1-5)
- Anote la hora exacta en que comenzó la anomalía: Obtenga la primera marca de tiempo en la que la latencia, la tasa de errores o la tasa de negativas cruzaron su rango normal desde su panel o alerta, no la hora en que la notó.
- Obtenga su registro de despliegue para la misma ventana: Enumere cada despliegue (código, configuración, prompt o infraestructura) en la hora anterior y posterior a la hora de inicio de la anomalía.
- Compruebe si hay un marcador de despliegue en el mismo panel: Si sus gráficos de latencia/errores ya muestran marcadores de despliegue como líneas verticales, confirme visualmente si el pico comienza justo después de uno.
- Confirme que la anomalía es específica de Claude, no de toda la infraestructura: Compruebe si otros servicios (base de datos, APIs no relacionadas) muestran el mismo pico al mismo tiempo; una causa compartida apunta lejos de su ruta de llamada a Claude específicamente.
- Compruebe la página de estado de Anthropic para la misma ventana: Descarte un incidente del lado del proveedor antes de dedicar más tiempo a su propio historial de despliegues.
Reducción de la causa (6-13)
- Compare el despliegue con el anterior: Obtenga la diferencia real de código del despliegue más probable, no solo su mensaje de commit, ya que el mensaje puede subestimar lo que cambió.
- Compruebe específicamente los cambios en el prompt o prompt del sistema: Una edición del prompt es una causa común, fácil de pasar por alto, de cambios en la latencia (prompts más largos, formato diferente) o nuevos patrones de negativa.
- Compruebe si hay un cambio en la versión del modelo o en el nombre del modelo: Confirme que el despliegue no cambió de modelo (por ejemplo, de Claude Haiku 4.5 a Claude Sonnet 5) como parte de un cambio de enrutamiento o configuración, ya que eso solo explica los cambios tanto en latencia como en comportamiento.
- Compruebe si hay un cambio en
max_tokenso en la temperatura/parámetros: Un valor demax_tokenselevado o un ajuste de parámetros pueden modificar mediblemente la latencia y, de forma menos obvia, el carácter de la respuesta. - Compruebe si hay definiciones de herramientas nuevas o modificadas: Una herramienta añadida, o un esquema de herramienta modificado, puede alterar la frecuencia con la que el modelo elige
tool_use, cambiando el número de viajes de ida y vuelta por solicitud. - Compruebe si hay cambios en la lógica de reintentos o tiempos de espera: Un tiempo de espera acortado o una nueva ruta de reintento ante fallos pueden parecer un pico de latencia en las métricas agregadas, incluso si la latencia por llamada no cambió.
- Compruebe si hay un cambio en el patrón de tráfico que coincide con el despliegue: Una campaña de marketing, el lanzamiento de una nueva función o un bot/scraper que accede a su endpoint al mismo tiempo que un despliegue pueden enmascararse como una regresión causada por el despliegue.
- Compruebe la tasa de fallos de caché específicamente si el gasto o la latencia se movieron: Un despliegue que cambió la estructura del prompt (incluso reordenando algunas líneas) puede invalidar la elegibilidad de la caché del prompt, aumentando tanto la latencia como el coste simultáneamente.
Confirmación y cierre del ciclo (14-18)
- Cruzar referencias de los tramos de rastreo de la ventana afectada: Obtenga un puñado de rastreos de justo después del despliegue y compare la latencia a nivel de tramo (llamada al modelo frente a llamada a herramienta) con un rastreo de referencia de antes del despliegue, para localizar dónde se está yendo el tiempo extra.
- Cruzar referencias de los registros estructurados para las mismas solicitudes: Compruebe si la longitud del prompt, el número de tokens o las razones de parada cambiaron para las llamadas justo después del despliegue en comparación con antes.
- Pruebe una reversión en staging, no en producción, primero si la causa aún no está clara: Revertir el despliegue sospechoso en un entorno de staging y reproducir el mismo patrón de tráfico confirma la atribución sin el riesgo de una reversión de producción.
- Si se confirma, revierta o aplique un hotfix, y luego verifique que la métrica vuelve a la línea base: No cierre el incidente hasta que el panel muestre que la latencia/tasa de errores ha vuelto a su rango normal, no solo que ha enviado una solución.
- Anote lo que encontró, incluyendo las pistas falsas: Una nota corta del incidente que liste lo que comprobó y descartó ahorra a la siguiente persona el tener que volver a recorrer cada callejón sin salida.
Preguntas frecuentes
¿Qué es lo primero que hay que comprobar cuando la latencia se dispara inesperadamente?
- La marca de tiempo exacta en que comenzó la anomalía.
- Su registro de despliegue para esa misma ventana.
- La página de estado de Anthropic, para descartar una causa del lado del proveedor antes de profundizar en sus propios cambios.
¿Cómo sé si un pico de latencia es causado por mi despliegue en lugar de un problema del lado de Anthropic?
Compruebe la página de estado de Anthropic para la misma ventana de tiempo primero. Si no muestra ningún incidente, y otros servicios no relacionados en su pila no se ven afectados al mismo tiempo, la correlación apunta a su propio despliegue reciente en lugar de una causa del lado del proveedor.
¿Por qué comprobar específicamente los cambios en el prompt, y no solo los cambios en el código?
Las ediciones de prompts son fáciles de incluir en un despliegue de otro modo no relacionado y fáciles de pasar por alto al escanear una diferencia en busca de cambios de código "reales". Un prompt más largo o reestructurado puede cambiar la latencia y, por separado, puede cambiar el comportamiento de negativa o salida de formas que una diferencia de código pura no sugeriría.
¿Qué pasa si el registro de despliegue muestra varios despliegues en la misma ventana?
Compare cada despliegue candidato individualmente en lugar de asumir que el más reciente es el responsable. Cruce referencias de tramos de rastreo y registros estructurados de justo después de la marca de tiempo de cada despliegue para reducir cuál de ellos se correlaciona realmente con el cambio de métrica.
¿Por qué un despliegue aumentaría tanto la latencia como el gasto al mismo tiempo?
Una causa común es un cambio que invalida la elegibilidad de la caché del prompt, por ejemplo, reordenando o editando el inicio de un prompt. Eso obliga a un procesamiento completo con coste y latencia completos en cada llamada en lugar de la ruta de caché más barata y rápida, lo que se manifiesta como un pico conjunto en las métricas de tasa de fallos de caché y latencia.
¿Debo revertir inmediatamente o investigar primero?
Si la causa ya está clara y confirmada, revierta o aplique un hotfix de inmediato y verifique que la métrica vuelve a la línea base. Si todavía no está claro, pruebe la reversión en staging primero para confirmar la atribución antes de revertir la producción, para no perder la oportunidad de diagnosticar la causa real bajo un despliegue revertido.
¿Cómo ayudan los tramos de rastreo a reducir de dónde proviene la latencia adicional?
Comparar la latencia a nivel de tramo (tramos de llamada al modelo frente a tramos de llamada a herramienta) entre un rastreo de justo después del despliegue y un rastreo de referencia de antes de él le muestra exactamente qué parte de la solicitud se volvió más lenta, en lugar de solo saber que toda la solicitud lo hizo.
¿Qué pasa si el patrón de tráfico cambió al mismo tiempo que el despliegue?
Compruebe si hay un cambio de tráfico coincidente (un impulso de marketing, el lanzamiento de una función, tráfico de bots inesperado) antes de concluir que el despliegue en sí es la causa. Un pico de tráfico puede producir un pico de latencia por sí solo, independientemente de cualquier cambio de código.
¿Necesito marcadores de despliegue en mi panel para que esta lista de verificación funcione?
Hacen que el paso 3 sea casi instantáneo, pero no son obligatorios; sin ellos, recurre a la referencia manual de las marcas de tiempo de su registro de despliegue frente a la hora de inicio de la anomalía de la métrica. Añadir marcadores de despliegue a sus paneles de latencia/errores es un seguimiento valioso después de su primer incidente sin ellos.
¿Por qué escribir una nota de incidente incluso después de que el problema se haya resuelto?
Una nota corta que liste lo que comprobó, incluyendo los callejones sin salida, ahorra a la siguiente persona (posiblemente a usted) el tener que volver a recorrer la misma investigación desde cero durante un incidente futuro. También es la materia prima para ajustar esta lista de verificación si se encuentra con un paso que le faltaba.
¿Qué papel juegan los registros estructurados más allá de confirmar la correlación del despliegue?
Comparar la longitud del prompt, el número de tokens y las razones de parada en los registros de antes y después del despliegue puede revelar el mecanismo específico, por ejemplo, un prompt más largo (aumentando los recuentos de tokens y la latencia juntos) o una nueva herramienta que causa más razones de parada de tool_use y viajes de ida y vuelta adicionales.
¿Es necesario comprobar un cambio de versión del modelo si no tenía la intención de cambiar de modelo?
Sí, porque los cambios de enrutamiento o configuración del modelo a veces se envían como un efecto secundario no intencionado de un despliegue no relacionado, especialmente si el nombre del modelo se establece a través de un archivo de configuración o variable de entorno que se tocó incidentalmente. Confirmar el modelo real utilizado en las solicitudes afectadas lo descarta rápidamente a través de sus registros estructurados.
Relacionado
- Cómo funciona la observabilidad para aplicaciones LLM - el modelo mental detrás de por qué la correlación de despliegues es importante.
- Instrumentación de bucles de agente con OpenTelemetry Tracing - los tramos de rastreo a los que se hace referencia en los pasos 14-15.
- Integración de paneles de uso y costes de Claude con Datadog - donde los marcadores de despliegue suelen vivir junto a los gráficos de latencia.
- Alertas sobre picos de gasto y aumento de las tasas de fallos de caché - la alerta que a menudo desencadena esta lista de verificación en primer lugar.
- Plantilla ADR: Definición del esquema de tramos OTel para llamadas a herramientas - documentación del esquema de tramos en el que se basa el paso 14.
- Mejores prácticas de observabilidad - una lista de verificación consolidada en esta sección.
Versiones de la 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
anthropicde Python (última versión 0.x). Los nombres de los modelos, los precios y las versiones del SDK cambian rápidamente: verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.