Phase 14 - Lesson 23

Convenções Semânticas GenAI do OpenTelemetry

O GenAI SIG do OpenTelemetry (lançado em abril de 2024) define o esquema padrão para telemetria de agentes. Nomes de spans, atributos e regras de captura de conteúdo convergem entre diferentes fornecedores para que os rastreamentos (traces) de agentes signifiquem a mesma coisa no Datadog, Grafana, Jaeger e Honeycomb.

Tipo: Learn + Build Idiomas: Python (stdlib) Pré-requisitos: Fase 14 · 13 (LangGraph), Fase 14 · 24 (Observability Platforms) Tempo: ~60 minutos

Objetivos de Aprendizado

• Nomear as categorias de span de GenAI: model/client, agent, tool.
• Distinguir spans invoke_agent do tipo CLIENT vs INTERNAL e quando cada um se aplica.
• Listar os atributos de GenAI de nível superior: nome do provedor, modelo de requisição, ID da fonte de dados.
• Explicar o contrato de captura de conteúdo: opt-in, OTEL_SEMCONV_STABILITY_OPT_IN, recomendação de referência externa.

O Problema

Cada fornecedor inventa seus próprios nomes de span. As equipes de operações acabam criando painéis por framework. O GenAI SIG do OpenTelemetry resolve isso definindo um padrão que todo o ecossistema segue.

O Conceito

Categorias de span

1. Spans de modelo / cliente (model / client). Cobrem chamadas brutas de LLM. São emitidos por SDKs de provedores (Anthropic, OpenAI, Bedrock) e adaptadores de modelo de frameworks.
2. Spans de agente (agent). create_agent (quando o agente é construído) e invoke_agent (quando ele é executado).
3. Spans de ferramenta (tool). Um por invocação de ferramenta; conectado ao span do agente por uma relação pai-filho.

Nomeação de spans de agente

• Nome do span: invoke_agent {gen_ai.agent.name} se nomeado; fallback para invoke_agent.
• Tipo de span (span kind):
  • CLIENT — para serviços de agente remotos (OpenAI Assistants API, Bedrock Agents).
  • INTERNAL — para frameworks de agente em processo (LangChain, CrewAI, ReAct local).

Atributos principais

• gen_ai.provider.name — anthropic, openai, aws.bedrock, google.vertex.
• gen_ai.request.model — o ID do modelo.
• gen_ai.response.model — o modelo resolvido (pode diferir da requisição devido ao roteamento).
• gen_ai.agent.name — identificador do agente.
• gen_ai.operation.name — chat, completion, invoke_agent, tool_call.
• gen_ai.data_source.id — para RAG: qual corpus ou repositório foi consultado.

Existem convenções específicas de tecnologia para Anthropic, Azure AI Inference, AWS Bedrock e OpenAI.

Captura de conteúdo

A regra padrão: as instrumentações NÃO DEVEM capturar entradas/saídas por padrão. A captura é opt-in via:

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

Padrão de produção recomendado: armazene o conteúdo externamente (S3, seu repositório de logs), registre referências nos spans (IDs de ponteiro, não prosa). Esta é a defesa contra envenenamento de conteúdo da Lição 27 integrada à observabilidade.

Estabilidade

A maioria das convenções é experimental em março de 2026. Ative a visualização estável (stable preview) com:

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

O Datadog v1.37+ mapeia atributos de GenAI nativamente em seu esquema de LLM Observability. Outros backends (Grafana, Honeycomb, Jaeger) oferecem suporte aos atributos brutos.

Onde este padrão falha

• Capturar prompts completos em spans. PII (informações pessoalmente identificáveis), segredos, dados de clientes em traces que a equipe de operações pode ler. Armazene externamente.
• Sem gen_ai.provider.name. Painéis de múltiplos provedores quebram quando a atribuição está ausente.
• Spans sem links pai. Spans de ferramentas órfãos. Sempre propague o contexto.
• Não configurar o opt-in de estabilidade. Seus atributos podem ser renomeados em uma atualização de backend.

Construa

O arquivo code/main.py implementa um emissor de span da stdlib compatível com as convenções de GenAI:

• Span com o esquema de atributos de GenAI.
• Tracer com start_span, contextos aninhados.
• Uma execução de agente roteirizada que emite: create_agent, invoke_agent (INTERNAL), spans por ferramenta e spans chat para chamadas de LLM.
• Um modo de captura de conteúdo que armazene prompts externamente e registre IDs nos spans.

Execute-o:

python3 code/main.py

Saída: uma árvore de spans com todos os atributos de GenAI necessários e um "armazenamento externo" mostrando as referências de conteúdo opt-in.

Como Usar

• Datadog LLM Observability (v1.37+) mapeia atributos nativamente.
• Langfuse / Phoenix / Opik (Lição 24) — autoinstrumentam o ecossistema.
• Jaeger / Honeycomb / Grafana Tempo — traces do OTel puros; crie painéis a partir dos atributos de GenAI.
• Self-hosted — execute o OTel Collector com um processador GenAI.

Coloque em Produção

O arquivo outputs/skill-otel-genai.md conecta os spans OTel GenAI a um agente existente com padrões de captura de conteúdo e armazenamento de referências externas.

Exercícios

1. Instrumente seu loop ReAct da Lição 01 com invoke_agent (INTERNAL) + spans por ferramenta. Envie para uma instância do Jaeger.
2. Adicione captura de conteúdo no modo "apenas referências": prompts no SQLite, atributos de span contendo apenas os IDs das linhas.
3. Leia a especificação para gen_ai.data_source.id. Conecte-o à sua busca da Mem0 na Lição 09.
4. Configure OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental e verifique se seus atributos não são renomeados pelo coletor.
5. Crie um painel: "quais erros de ferramentas se correlacionam com quais modelos" usando apenas atributos de GenAI.

Termos-Chave

Leitura Adicional

• OpenTelemetry GenAI semantic conventions — a especificação
• OpenAI Agents SDK — spans de GenAI por padrão
• AutoGen v0.4 (Microsoft Research) — spans do OTel integrados
• Claude Agent SDK — propagação de contexto de rastreamento do W3C