Cómo instrumentar una aplicación de IA para investigar fallos, latencia y consumo

1. Empieza por las preguntas operativas, no por los campos

La observabilidad de una aplicación de IA consiste en poder reconstruir su comportamiento a partir de señales relacionadas: qué solicitud llegó, qué etapas se ejecutaron, qué falló y cuánto tardó cada parte. Para una aplicación que ya llama a un modelo mediante una API, instrumentar no significa copiar cada entrada y respuesta a un registro. Significa recoger contexto suficiente para responder preguntas de operación de forma repetible, con un alcance y una política de datos definidos.

Antes de elegir una biblioteca o crear un tablero, escribe las preguntas que el equipo necesita contestar durante un incidente. Por ejemplo: ¿qué versión de la aplicación y del prompt procesó esta solicitud? ¿Se llamó al modelo una vez o hubo reintentos? ¿Qué herramienta se ejecutó y cuánto duró? ¿La demora estuvo en la aplicación, la red, el modelo o una herramienta? ¿Qué uso comunicó la API? Estas preguntas delimitan el diseño; los campos que no ayudan a contestarlas no deberían incorporarse por costumbre.

Conviene separar observabilidad de evaluación del contenido. Este artículo se centra en el recorrido técnico y operativo de una solicitud: fallos, latencia, reintentos y consumo comunicado. No propone un método para decidir si una respuesta es verdadera, seleccionar un proveedor o diseñar un flujo conversacional. Esa frontera mantiene el registro pequeño y evita presentar una señal técnica como prueba de calidad.

2. Dibuja el ciclo y define cómo se correlaciona

Una solicitud que parece una sola llamada desde la interfaz puede incluir varias operaciones: validación de entrada, construcción del prompt, llamada al modelo, procesamiento de la respuesta y quizá una llamada a una herramienta. Si hay reintentos, cada intento debe quedar visible como una operación distinta. El registro debe permitir reunir esos eventos sin depender de identificadores que la API externa no garantice.

Genera un identificador propio para la solicitud cuando entra en tu aplicación y propágalo por los componentes bajo tu control. Añade identificadores hijos o números de etapa para distinguir llamadas al modelo y herramientas. Si el proveedor devuelve un identificador de solicitud, guárdalo como campo adicional para facilitar una consulta o soporte posterior, pero no lo uses como único vínculo: puede no estar disponible en todos los errores o caminos de ejecución.

Define también el límite temporal de cada medición. La duración total comienza al aceptar la solicitud en la aplicación y termina cuando se entrega la respuesta o se registra el fallo final. La duración de una llamada al modelo empieza al iniciar esa llamada y acaba al recibir respuesta o error. Una llamada a herramienta usa sus propios tiempos de inicio y fin. Registrar milisegundos sin precisar esos límites produce cifras que no se pueden comparar con seguridad.

3. Define un esquema mínimo y registra lo que la API realmente entrega

Un esquema mínimo debe separar los datos generados por tu aplicación de los campos recibidos del proveedor. Entre los campos propios suelen estar el identificador de solicitud, la etapa, el número de intento, el estado, las marcas de tiempo y las versiones del código y del prompt. El modelo solicitado, la configuración y el identificador devuelto por el proveedor pueden ayudar a reconstruir la ejecución, pero deben etiquetarse según su origen.

El uso comunicado por una API no es un dato universal. Puede variar según endpoint, modelo, modalidad, versión o tipo de respuesta; también puede faltar en errores o respuestas parciales. La documentación disponible para esta guía no especifica un proveedor concreto ni permite afirmar una lista universal de campos. Por ello, implementa un adaptador por API y consulta su documentación primaria vigente para comprobar nombres, unidades y condiciones. Guarda el resultado como “uso reportado por la API”, incluyendo qué campos estaban presentes, y no completes valores ausentes con ceros sin distinguirlos.

También separa el tiempo medido por la aplicación de cualquier duración comunicada por el proveedor. El primero mide el recorrido desde tu sistema; el segundo, si existe, tiene la definición del proveedor. Mantén las unidades explícitas —por ejemplo, milisegundos para duraciones— y define si las marcas de tiempo se guardan en UTC. Una convención constante permite comparar solicitudes y detectar cambios sin mezclar relojes o intervalos diferentes.

4. Instrumenta eventos estructurados de extremo a extremo

Los registros estructurados son más fáciles de filtrar y agrupar que mensajes escritos en prosa. Define nombres estables para los eventos, estados y campos; evita que cada componente use una etiqueta diferente para el mismo concepto. No hace falta adoptar un proveedor de observabilidad específico para comenzar: puedes emitir eventos JSON desde la aplicación y exportarlos a la plataforma que ya utiliza el equipo.

Un patrón útil es emitir un evento de inicio y otro de cierre por etapa, o un solo evento de cierre que incluya inicio, fin y resultado cuando la etapa sea corta y no requiera actualización en tiempo real. Para operaciones largas, el evento de cierre debe conservar el vínculo con la solicitud original. Si utilizas trazas distribuidas, propaga el contexto a través de servicios y colas bajo tu control; comprueba que el identificador no se pierde al pasar de una tarea síncrona a otra asíncrona.

El ejemplo siguiente es pseudocódigo esquemático, no una integración ejecutable con una API: los nombres de campos de respuesta y errores dependen del SDK y del proveedor. En la implementación real, adapta la extracción de uso y errores a la documentación vigente, y asegúrate de que el bloque de excepción no registre automáticamente cuerpos que puedan contener datos sensibles.

5. Minimiza datos sensibles antes de guardar o exportar

La observabilidad no exige conservar prompts completos, respuestas íntegras ni argumentos de herramientas en cada solicitud. Estos contenidos pueden incluir datos personales, secretos, información comercial o material que no es necesario para responder preguntas operativas. Empieza con metadatos y señales derivadas: identificadores opacos, versiones, longitudes, categorías de error, estados y tiempos.

Decide por campo qué acción corresponde: excluir, redactar, transformar o guardar bajo acceso restringido y retención limitada. Para correlacionar con una entidad de negocio, puede bastar una clave seudónima o una referencia interna que solo un sistema autorizado pueda resolver. Un hash no garantiza anonimato si el valor original es predecible o si puede compararse contra una lista; no lo trates automáticamente como una solución de privacidad.

Prueba la redacción antes de habilitar el registro en producción. Usa ejemplos sintéticos que incluyan casos típicos y variantes, como una dirección de correo en una entrada, un token en un encabezado o un dato confidencial dentro de una respuesta de herramienta. Comprueba tanto el evento que sale de la aplicación como el que llega al almacén: una regla aplicada solo en el panel o después de exportar deja el dato expuesto en el trayecto.

6. Construye paneles y alertas para investigar, no para acumular gráficos

Un tablero útil responde a una pregunta y deja claro qué acción puede seguir. Empieza con tres vistas: salud de solicitudes, distribución de latencia y uso reportado. Para salud, muestra solicitudes completadas, fallidas y sin resultado final, separadas por categoría de error. Para latencia, muestra duración total y por etapa, con percentiles además de promedios, porque un promedio puede ocultar una cola de solicitudes lentas. Para uso, muestra únicamente los campos disponibles y separa los datos por modelo, versión o tipo de solicitud cuando esa segmentación ayude a encontrar cambios.

Las alertas deben representar una condición que alguien pueda investigar o corregir. Una tasa de errores que supera el comportamiento habitual durante un intervalo definido puede justificar una alerta; un fallo aislado puede quedar en el registro sin despertar a un equipo. Los umbrales dependen del volumen y de las expectativas del servicio, así que no conviene fijar un valor universal sin datos. Añade la ventana de observación, el responsable y el enlace a la consulta o al procedimiento de respuesta.

No presentes una estimación de coste basada en uso reportado como importe facturado. Para una estimación interna, multiplica las unidades disponibles por los precios y reglas aplicables a la cuenta y configuración concretas, y etiqueta el resultado como estimación. Los importes reales pueden depender de condiciones que no se deducen solo del evento de respuesta; verifica cualquier reconciliación con la documentación y los datos oficiales de facturación vigentes del proveedor correspondiente.

7. Investiga una solicitud fallida de forma reproducible

Cuando llega un reporte, fija primero el ID de solicitud y confirma que corresponde al entorno y periodo correctos. Reúne los eventos ordenados por hora y etapa. Antes de interpretar el resultado, verifica que la traza esté completa: ¿hay evento de inicio y cierre? ¿faltan tramos de herramienta? ¿el registro marca un error terminal o solo un intento fallido? Una ejecución incompleta puede parecer un fallo del modelo cuando la evidencia simplemente no se guardó.

Después, reconstruye versiones y secuencia: código de aplicación, versión de prompt, modelo solicitado y cualquier modelo resuelto que se haya podido observar, número de intentos, herramientas y estados. Compara la duración total con la suma de etapas, teniendo en cuenta trabajo local, colas y tiempos que no estén instrumentados. Si la suma no coincide, anótalo como una laguna de telemetría, no como prueba de una causa.

Por último, separa hechos de hipótesis. Un timeout del proveedor puede estar documentado como el resultado de un intento; no demuestra por sí solo por qué ocurrió. Una herramienta lenta puede explicar una parte del tiempo medido, pero no necesariamente el comportamiento final. Registra qué se sabe, qué falta y qué comprobación permitiría distinguir las hipótesis. Esta disciplina evita atribuir causas que el registro no demuestra.

8. Comprueba la instrumentación y amplíala por etapas

La instrumentación también necesita pruebas: una aplicación puede funcionar mientras pierde IDs, omite el evento de cierre o registra datos que debían redactarse. Ejecuta pruebas controladas para éxito, error, timeout, reintento y llamada a herramienta. En cada caso, comprueba la secuencia completa desde el evento de entrada hasta el resultado final, así como los permisos y la redacción antes de exportar.

Empieza con una ruta de producción acotada y verifica que las consultas resuelven preguntas reales. Revisa cuánto volumen genera el registro y si el equipo puede encontrar una solicitud sin buscar manualmente en varios sistemas. Ajusta la selección de eventos y la retención antes de ampliar. La finalidad no es maximizar la cantidad de telemetría, sino mantener evidencia suficiente y consultable para operar el sistema.

Las convenciones de telemetría y los campos de uso de las APIs pueden evolucionar. Versiona tu esquema interno y valida los adaptadores cuando cambie el SDK, la API o la configuración. Si el proveedor modifica una respuesta, la capa de normalización debería poder adaptarse sin que todos los paneles y consultas dependan de nombres externos. Una práctica general de observabilidad puede orientar la organización de señales y trazas; no sustituye la documentación técnica primaria para campos o facturación de un proveedor específico.

Continúa explorando

Correcciones y transparencia

Si detectas un dato incorrecto o desactualizado, puedes enviarnos una corrección indicando la página y la fuente que debemos revisar.