La observabilidad de agentes no va de guardar todos los prompts: va de trazar decisiones, herramientas, coste y errores sin convertir tus logs en una fuga de datos.
OpenTelemetry GenAI es el intento más serio de estandarizar cómo trazamos llamadas a modelos, agentes, tools, MCP, costes, errores y eventos de entrada/salida sin casarnos con un proveedor de observabilidad.
TL;DR
La keyword principal es OpenTelemetry GenAI. La intención de búsqueda en español es práctica: entender qué atributos y spans usar para observar agentes de IA, cuándo capturar contenido y cómo evitar fugas de prompts, argumentos de tools o datos de usuario.
Mi postura: no actives captura completa de prompts por defecto. Primero captura metadata, modelos, tokens, latencia, tool names, errores y correlación de trace. El contenido sensible debe ser opt-in, filtrado y justificable.
Qué problema resuelve OpenTelemetry GenAI
Los agentes de IA rompen la observabilidad clásica porque una petición ya no es una sola llamada HTTP. Puede incluir planning, varias llamadas a modelo, tools locales, MCP remoto, retrieval, memoria, aprobaciones humanas, retries, streaming y costes por token. Si solo tienes logs de aplicación, verás el resultado final, pero no el camino.
OpenTelemetry GenAI propone un vocabulario común bajo atributos como gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.tool.name o mcp.method.name. La ventaja no es estética: si varios SDKs emiten el mismo esquema, puedes comparar proveedores, frameworks y backends sin reescribir dashboards cada trimestre.
La parte incómoda es que el estándar sigue en desarrollo. Eso no lo invalida; significa que debes adoptarlo como contrato operativo propio, con versionado y tests, no como magia que arregla toda la observabilidad del stack.
Una traza util de agentes separa metadata segura, contenido opt-in, contexto MCP y gates de operacion. No todo lo observable merece guardarse.
El modelo mental: spans de modelo, agente, tool y MCP
Empieza por cuatro capas. La primera es la llamada al modelo: chat, embeddings, respuesta, tokens, latencia, finish reason y errores. La segunda es el agente: crear agente, invocar agente, invocar workflow, planificar o ejecutar una herramienta. La tercera son las tools: nombre, tipo, id de llamada, duracion, resultado y error. La cuarta es MCP, donde importan mcp.method.name, sesion, transporte, JSON-RPC y propagacion de contexto.
La decision importante es que cada span debe responder una pregunta de depuracion. ¿Que modelo uso?, ¿Que herramienta llamo?, ¿Cuanto costo?, ¿Donde fallo?, ¿Se propago el trace hasta el servidor MCP?. Si una etiqueta no ayuda a operar, auditar o mejorar el sistema, probablemente solo aumenta ruido y riesgo.
Para equipos con agentes reales, el error habitual es trazar el LLM y olvidarse de las tools. Pero muchos incidentes no vienen del modelo, sino de un tool call mal parametrizado, un MCP server lento, un permiso demasiado amplio o una respuesta externa que el agente trato como fiable.
span manual para tool call
from opentelemetry import trace
tracer = trace.get_tracer("devai.agent")
def call_tool(tool_name: str, args: dict) -> dict:
with tracer.start_as_current_span(
f"execute_tool {tool_name}",
attributes={
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": tool_name,
"gen_ai.tool.type": "function",
"app.agent.name": "repo-reviewer",
},
) as span:
try:
result = run_tool(tool_name, args)
span.set_attribute("app.tool.success", True)
return result
except Exception as exc:
span.set_attribute("error.type", type(exc).__name__)
span.record_exception(exc)
raise
redaccion segura de atributos sensibles
SENSITIVE_KEYS = {"api_key", "token", "password", "email", "customer_id"}
def safe_tool_args(args: dict) -> dict:
return {
key: "[redacted]" if key.lower() in SENSITIVE_KEYS else value
for key, value in args.items()
}
# Solo si hay opt-in explicito y una politica de retencion clara.
span.set_attribute("gen_ai.tool.call.arguments", json.dumps(safe_tool_args(args)))
¿Te está sirviendo? Hay una dosis cada semana. Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido. Suscríbete gratis
Qué capturar siempre y qué dejar en opt-in
Captura siempre metadata de baja sensibilidad: proveedor, modelo solicitado, operacion, latencia, tokens, errores, nombre de tool, estado de aprobacion, tenant anonimizado, version del agente y commit de despliegue. Esto permite depurar coste y rendimiento sin almacenar contenido del usuario.
Lo que conviene comprobar
Deja en opt-in el contenido: gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions, definiciones de tools, argumentos y resultados. Esos campos son valiosos para incidentes y evaluacion, pero tambien pueden contener secretos, PII, codigo privado, datos de cliente o instrucciones internas.
La regla operativa es simple: si activas captura de contenido, define antes mascarado, retencion, acceso, muestreo, entornos permitidos y razon de negocio. Lo necesitamos para debug no basta si acabas guardando prompts completos de produccion durante meses.
MCP: la traza no debe morir en el transporte
MCP complica la observabilidad porque trabaja sobre JSON-RPC y puede usar stdio o Streamable HTTP. Un request de transporte no equivale necesariamente a una operacion MCP: puede haber streams, sesiones, retries y mensajes multiples. Por eso las convenciones MCP recomiendan spans propios y propagacion de contexto en params._meta.
Para tools MCP, mcp.method.name=tools/call y gen_ai.operation.name=execute_tool permiten que el backend trate la llamada como tool call GenAI y como operacion MCP a la vez. Esa doble lectura es util: el equipo de agentes ve la accion, y el equipo de plataforma ve transporte, sesion y servidor.
No metas URIs o argumentos de alta cardinalidad en nombres de span. Usa nombres estables y atributos filtrados. Si cada consulta genera un span name unico, tus dashboards se vuelven caros, lentos y poco agregables.
Coste, latencia y calidad: tres tableros distintos
Un agente puede ser correcto y demasiado caro, barato y peligroso, rapido y ciego. Por eso no mezcles todo en un unico score de agente. Necesitas tablero de coste, tablero de fiabilidad y tablero de calidad.
El tablero de coste debe mostrar tokens por operacion, cache hits, modelo, proveedor, tool calls y coste estimado por tarea. El tablero de fiabilidad debe mostrar errores por tool, timeouts, retries, spans sin parent y MCP servers lentos. El tablero de calidad debe conectarse con evaluacion: groundedness, aprobaciones humanas, feedback y regresiones.
La observabilidad GenAI no reemplaza evaluaciones, pero las hace auditables. Cuando un gate RAG falla, una traza bien hecha te enseña query, retrieval, modelo, tool calls y respuesta. Sin esa evidencia, el equipo acaba discutiendo impresiones.
Privacidad: observabilidad no es permiso para grabarlo todo
El mayor riesgo de OpenTelemetry GenAI no es tecnico, es cultural: como ahora hay atributos para mensajes, tools y system prompts, algunos equipos asumiran que deben capturarlos todos. No. Que exista un campo no significa que sea buena idea llenarlo en produccion.
Trata prompts, system instructions, tool schemas y resultados como datos sensibles. Un system prompt puede revelar politicas internas. Un tool argument puede contener email, cuenta, ruta de repo o token. Un resultado puede traer datos de cliente que nunca debian salir de la herramienta.
Mi configuracion por defecto seria conservadora: contenido off, metadata on, muestreo de errores, redaccion agresiva, retencion corta para entornos de debug y acceso limitado. Si el negocio necesita payloads completos para auditoria, eso debe pasar por una decision explicita, no por una variable de entorno olvidada.
Plan de implantacion en una semana
Dia 1: inventaria los caminos del agente: modelo, retrieval, tools locales, MCP, aprobaciones humanas y jobs asincronos.
Dia 2: define nombres de spans y atributos minimos. Incluye gen_ai.operation.name, modelo, proveedor, tokens, latencia, error y version de agente.
Dia 3: instrumenta tool calls y MCP. Verifica que el trace cruza cliente, servidor MCP y backend de observabilidad.
Dia 4: activa dashboards de coste, latencia y errores. No actives contenido completo todavia.
Dia 5: define politica de opt-in para contenido sensible: mascarado, muestreo, retencion, acceso y entornos.
Dia 6: conecta trazas con evaluaciones y feedback humano. Cada fallo importante debe tener trace id.
Dia 7: crea gates: coste por tarea, tasa de error de tool, latencia p95 y spans huerfanos.
Errores comunes
- Guardar prompts completos por defecto porque
ayuda a depurar. - Medir solo llamadas al modelo y olvidar tool calls, MCP, retrieval y aprobaciones.
- Usar nombres de span con ids, queries o rutas de usuario.
- No versionar agente, prompt, modelo ni commit en los atributos.
- Mezclar metricas de coste, calidad y fiabilidad en un unico numero.
- No probar que la propagacion de trace funciona entre cliente MCP y servidor MCP.
- Dar acceso a trazas GenAI a mas personas que a los datos de produccion equivalentes.
Conclusión
OpenTelemetry GenAI es una buena direccion porque pone nombres comunes a problemas que todos los equipos de agentes estan redescubriendo: modelo, tool, MCP, tokens, errores, contenido opt-in y propagacion de contexto. Eso reduce dependencia de dashboards propietarios y fuerza disciplina operativa.
Lo que conviene comprobar
Pero la decision madura no es capturalo todo. Es capturar lo suficiente para depurar y mejorar sin convertir observabilidad en una base de datos paralela de prompts sensibles. Si empiezas por metadata, tools, coste y errores, ya tendras mas señal que la mayoria de demos. El contenido completo puede venir despues, con politica y responsabilidad.
Preguntas frecuentes
¿Qué es OpenTelemetry GenAI?
OpenTelemetry GenAI es un conjunto de convenciones semanticas para representar telemetria de sistemas de IA generativa: llamadas a modelos, agentes, tools, MCP, eventos, metricas y errores.
¿OpenTelemetry GenAI está estable?
No del todo. Las convenciones GenAI estan marcadas como Development en varias areas, asi que conviene versionar dashboards y no asumir compatibilidad perfecta entre SDKs.
¿Debo capturar prompts completos?
No por defecto. Captura metadata primero y activa contenido solo con opt-in, redaccion, muestreo, retencion corta y control de acceso.
¿Cómo se observa una tool MCP?
Usa atributos MCP como mcp.method.name, sesion y transporte, y añade gen_ai.operation.name=execute_tool cuando la operacion sea una llamada de herramienta.
¿OpenTelemetry GenAI reemplaza LangSmith, Phoenix o Datadog LLM Observability?
No necesariamente. Es un esquema comun de telemetria; los backends siguen aportando UI, analisis, alertas, evals y almacenamiento.
¿Qué metrica miro primero en agentes?
Empieza por latencia p95, errores por tool, tokens por tarea, coste por workflow y porcentaje de trazas con contexto completo. La calidad requiere evaluaciones separadas.
Cómo instrumentar un agente con OpenTelemetry GenAI sin filtrar datos sensibles
- Mapear el flujo. Dibuja modelo, agente, tools, MCP, retrieval, memoria, aprobaciones y jobs asincronos.
- Definir spans. Usa nombres estables para chat, invoke_agent, plan, execute_tool, retrieval y llamadas MCP.
- Capturar metadata segura. Registra proveedor, modelo, operacion, tokens, latencia, error, version de agente y commit.
- Separar contenido opt-in. Mantén prompts, mensajes, argumentos y resultados fuera por defecto.
- Aplicar redaccion. Enmascara secretos, PII, ids de cliente y rutas sensibles antes de exportar atributos.
-
Propagar contexto MCP. Inyecta trace context en
params.\_metay verifica parent-child o links entre cliente y servidor. - Crear dashboards. Separa coste, fiabilidad y calidad; no escondas todo en un score unico.
- Conectar evals. Guarda trace id en fallos de evaluacion y feedback humano para depurar con evidencia.
- Revisar retencion. Trata trazas GenAI con el mismo cuidado que datos de produccion sensibles.
Regla operativa
Activa la automatización donde el comentario pueda cambiar una decisión técnica, no donde solo vaya a producir ruido revisable.
Fuentes y referencias
- OpenTelemetry GenAI semantic conventions
- OpenTelemetry GenAI systems overview
- OpenTelemetry GenAI agent spans
- OpenTelemetry MCP semantic conventions
- OpenTelemetry: GenAI observability
- OpenTelemetry: AI Agent Observability
- OpenTelemetry GenAI reference implementations
- OpenTelemetry OpenAI Agents instrumentation
También te puede interesar
OpenAI Agents SDK: MCP, guardrails y tracing
Métricas para agentes de código
Evaluación RAG en producción
LiteLLM Proxy: gateway IA, costes y modelos
MCP outputSchema y structuredContent
¿Te está sirviendo? Hay una dosis cada semana. Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido. Suscríbete gratis
Top comments (0)