Phase 14 - Lesson 23

Convenciones Semánticas de GenAI de OpenTelemetry

El GenAI SIG de OpenTelemetry (lanzado en abril de 2024) define el esquema estándar para la telemetría de agentes. Los nombres de span, atributos y reglas de captura de contenido convergen entre proveedores para que las trazas de agentes signifiquen lo mismo en Datadog, Grafana, Jaeger y Honeycomb.

Tipo: Learn + Build Idiomas: Python (stdlib) Prerrequisitos: Fase 14 · 13 (LangGraph), Fase 14 · 24 (Observability Platforms) Tiempo: ~60 minutos

Objetivos de Aprendizaje

• Nombrar las categorías de span de GenAI: model/client, agent, tool.
• Distinguir spans invoke_agent de tipo CLIENT vs INTERNAL y cuándo se aplica cada uno.
• Listar los atributos de GenAI de nivel superior: nombre del proveedor, modelo de solicitud, ID de la fuente de datos.
• Explicar el contrato de captura de contenido: opt-in, OTEL_SEMCONV_STABILITY_OPT_IN, recomendación de referencia externa.

El Problema

Cada proveedor inventa sus propios nombres de span. Los equipos de operaciones terminan creando paneles por framework. El GenAI SIG de OpenTelemetry resuelve esto al definir un estándar al que se dirige todo el ecosistema.

El Concepto

Categorías de span

1. Spans de modelo / cliente (model / client). Cubren llamadas directas de LLM. Son emitidos por SDKs de proveedores (Anthropic, OpenAI, Bedrock) y adaptadores de modelos de frameworks.
2. Spans de agente (agent). create_agent (cuando se construye el agente) y invoke_agent (cuando se ejecuta).
3. Spans de herramienta (tool). Uno por invocación de herramienta; conectado al span del agente por una relación padre-hijo.

Nomenclatura de spans de agente

• Nombre del span: invoke_agent {gen_ai.agent.name} si tiene nombre; fallback a invoke_agent.
• Tipo de span (span kind):
  • CLIENT — para servicios de agentes remotos (OpenAI Assistants API, Bedrock Agents).
  • INTERNAL — para frameworks de agentes en proceso (LangChain, CrewAI, ReAct local).

Atributos clave

• gen_ai.provider.name — anthropic, openai, aws.bedrock, google.vertex.
• gen_ai.request.model — el ID del modelo.
• gen_ai.response.model — el modelo resuelto (puede diferir de la solicitud debido al enrutamiento).
• gen_ai.agent.name — identificador del agente.
• gen_ai.operation.name — chat, completion, invoke_agent, tool_call.
• gen_ai.data_source.id — para RAG: qué corpus o almacenamiento fue consultado.

Existen convenciones específicas de tecnología para Anthropic, Azure AI Inference, AWS Bedrock, OpenAI.

Captura de contenido

La regla predeterminada: las instrumentaciones NO DEBEN capturar entradas/salidas de forma predeterminada. La captura es opt-in a través de:

• gen_ai.system_instructions
• gen_ai.input.messages
• gen_ai.output.messages

Patrón de producción recomendado: almacene el contenido externamente (S3, su almacén de registros), registre las referencias en los spans (IDs de puntero, no texto descriptivo). Esta es la defensa contra envenenamiento de contenido de la Lección 27 integrada en la observabilidad.

Estabilidad

La mayoría de las convenciones son experimentales a partir de marzo de 2026. Active la vista previa estable con:

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

Datadog v1.37+ mapea los atributos de GenAI de forma nativa en su esquema de LLM Observability. Otros backends (Grafana, Honeycomb, Jaeger) admiten los atributos brutos.

Dónde falla este patrón

• Capturar prompts completos en spans. PII (información de identificación personal), secretos y datos de clientes en trazas que el equipo de operaciones puede leer. Almacene externamente.
• Falta de gen_ai.provider.name. Los paneles multiproveedor fallan cuando falta la atribución.
• Spans sin enlaces principales. Spans de herramientas huérfanos. Propague siempre el contexto.
• No configurar el opt-in de estabilidad. Sus atributos podrían renombrarse al actualizar el backend.

Construcción

El archivo code/main.py implementa un emisor de spans de la biblioteca estándar (stdlib) compatible con las convenciones de GenAI:

• Span con el esquema de atributos de GenAI.
• Tracer con start_span, contextos anidados.
• Una ejecución de agente programada que emite: create_agent, invoke_agent (INTERNAL), spans por herramienta y spans chat para llamadas de LLM.
• Un modo de captura de contenido que almacena prompts externamente y registra IDs en los spans.

Ejecútelo:

python3 code/main.py

Salida: un árbol de spans con todos los atributos de GenAI requeridos y un "almacén externo" que muestra las referencias de contenido opt-in.

Cómo Usar

• Datadog LLM Observability (v1.37+) mapea los atributos de forma nativa.
• Langfuse / Phoenix / Opik (Lección 24) — autoinstrumentan el ecosistema.
• Jaeger / Honeycomb / Grafana Tempo — trazas de OTel puras; cree paneles a partir de los atributos de GenAI.
• Self-hosted — ejecute el OTel Collector con un procesador de GenAI.

Implementación

El archivo outputs/skill-otel-genai.md conecta los spans de OTel GenAI a un agente existente con valores predeterminados de captura de contenido y almacenamiento de referencias externas.

Ejercicios

1. Instrumente su ciclo ReAct de la Lección 01 con invoke_agent (INTERNAL) + spans por herramienta. Envíelos a una instancia de Jaeger.
2. Agregue la captura de contenido en modo "solo referencias": prompts en SQLite, los atributos de span solo contienen IDs de fila.
3. Lea la especificación de gen_ai.data_source.id. Conéctelo a su búsqueda de Mem0 de la Lección 09.
4. Configure OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental y verifique que el recolector no renombre sus atributos.
5. Cree un panel: "qué errores de herramientas se correlacionan con qué modelos" basándose únicamente en los atributos de GenAI.

Términos Clave

Lectura Adicional

• OpenTelemetry GenAI semantic conventions — la especificación
• OpenAI Agents SDK — spans de GenAI por defecto
• AutoGen v0.4 (Microsoft Research) — spans de OTel integrados
• Claude Agent SDK — propagación del contexto de traza de W3C