La respuesta final no explica el sistema
Un agente puede tardar veinte segundos y aun así devolver una respuesta correcta. Sin una traza, no sabes si el tiempo se consumió en el modelo, una consulta lenta, dos reintentos o una espera humana. Tampoco sabes qué herramienta produjo un dato incorrecto ni cuánto costó recorrer una ruta que pudo resolverse antes.
La observabilidad conecta una solicitud con los pasos que ocurrieron: invocaciones de modelo, herramientas, handoffs, validaciones y errores. Los logs siguen siendo útiles, pero una colección de líneas aisladas obliga a reconstruir manualmente la secuencia. Una traza conserva la relación entre operación padre y spans hijos.
OpenTelemetry ofrece un lenguaje común para instrumentar y exportar esa información sin amarrar el código a un único proveedor de paneles.
Qué aportan las convenciones para IA generativa
Las convenciones semánticas de OpenTelemetry para GenAI definen atributos y eventos para operaciones de modelo y agentes. Permiten registrar proveedor y modelo efectivo, conteos de tokens cuando existen, duración, resultado y relación con llamadas de herramientas. El contenido de prompts y respuestas es opcional, no un requisito.
Esa distinción importa. Puedes obtener latencia, errores y consumo sin copiar conversaciones completas al sistema de telemetría. Cuando el análisis de calidad exige contenido, actívalo de forma controlada, con consentimiento, reducción y retención definida.
Las convenciones evolucionan. Fija la versión que adopta tu instrumentación y valida cambios antes de actualizar nombres o cardinalidad de atributos.
Diseña el mapa de spans antes de instrumentar
Crea un span raíz para la ejecución del agente. Debajo, representa cada llamada de modelo, herramienta, recuperación, handoff y aprobación. Un reintento es un span nuevo enlazado a la causa, no una corrección invisible del anterior.
Incluye identificadores técnicos, duración, estado y una clasificación de error. Evita parámetros de alta cardinalidad como el texto completo de la consulta, la URL con tokens o el nombre libre de cada cliente. Los atributos deben servir para agrupar y comparar.
Un mapa coherente permite responder tres preguntas: dónde pasó el tiempo, qué camino siguió el agente y en qué paso cambió el estado. Si la traza no responde esas preguntas, tiene muchos datos pero poca observabilidad.
Separa latencia de modelo, herramientas y espera
Mide tiempo total y tiempo exclusivo por span. Una herramienta de base de datos puede quedar oculta dentro de una ejecución larga del agente; una aprobación humana puede dominar el reloj sin ser un problema técnico; un reintento puede duplicar tokens.
Construye percentiles de duración por operación y herramienta, no sólo promedios. Cuenta llamadas y reintentos por ejecución. Registra tokens de entrada y salida cuando el proveedor los entrega, y asocia la tarifa en una capa financiera fechada en vez de grabar precios cambiantes dentro de cada span.
No llames costo a tokens. El costo monetario depende de modelo, tarifa, caché y fecha. La telemetría guarda unidades verificables; el reporte aplica la tabla vigente y conserva su versión.
Captura contenido sólo cuando puedas protegerlo
Prompts, respuestas y resultados de herramientas pueden contener nombres, correos, claves, documentos o información comercial. Configura la captura de contenido como opt-in. Antes de exportar, elimina encabezados de autorización, cookies, credenciales, identificadores personales y campos de negocio que no sean necesarios.
Usa una lista permitida para atributos, no una lista interminable de cosas que esperas bloquear. Aplica límites de tamaño y muestreo. Define quién puede consultar trazas, cuánto tiempo se conservan y cómo se elimina una ejecución.
Prueba el redactor con secretos señuelo. Si un token de prueba aparece en el backend de observabilidad, el control es FAIL aunque el dashboard funcione.
Un tablero pequeño para operar
Empieza con tasa de éxito, latencia total p50 y p95, latencia por herramienta, errores por clase, reintentos por ejecución, tokens por resultado válido y porcentaje de ejecuciones que requieren intervención. Añade volumen para no confundir una tasa con una muestra mínima.
Cada panel debe llevar a una acción. Si sube la latencia de una herramienta, abre su traza y revisa dependencia, argumentos y respuesta. Si aumentan los reintentos del modelo, inspecciona casos y esquema. Si cae el éxito después de una versión, activa la compuerta de regresión.
Separa entorno y versión del agente. Una gráfica que mezcla pruebas, staging y producción puede ocultar que la degradación pertenece a un solo despliegue. Conserva la versión de contratos de herramientas para relacionar un error con el cambio que alteró los argumentos.
Evita un muro de métricas. Una métrica que nadie puede vincular con dueño, umbral y respuesta es inventario, no operación.
Alertas que incluyen el siguiente paso
Una alerta útil indica servicio, versión, ventana, magnitud, traza de ejemplo y runbook. Separa fallas duras de degradaciones. Un error de autenticación sostenido puede requerir respuesta inmediata; un aumento moderado de p95 merece investigación sin despertar a todo el equipo.
Agrupa eventos derivados de la misma causa y limita notificaciones. Cuando una dependencia externa falla, cientos de trazas pueden representar un solo incidente. Registra el vínculo entre alerta e incidente para evaluar después si el umbral fue útil.
Nunca adjuntes prompts completos a correo o chat. Entrega un identificador de traza y exige acceso autorizado al sistema que conserva el detalle.
Plan de implementación en cuatro cortes
Corte uno: span raíz, modelo y herramientas con duración y estado. Corte dos: errores estructurados, reintentos y versión del agente. Corte tres: tokens, tabla de costos separada y dashboards. Corte cuatro: muestreo de contenido excepcional con redacción y acceso restringido.
En cada corte, ejecuta casos conocidos y confirma que la traza representa la secuencia real. Prueba cancelación, timeout, error de herramienta y aprobación denegada. Verifica que no aparezcan secretos.
La meta no es coleccionar telemetría. Es reducir el tiempo entre un comportamiento inesperado y una explicación comprobable, sin convertir el sistema de observabilidad en una copia más riesgosa de los datos del usuario.
