Blank white background with no objects or features visible.

Olá, EMEA! A TrueFoundry está expandindo sua presença pela Europa, Oriente Médio e África. Leia mais. →

OpenTelemetry GenAI Conventions: Um Vocabulário Comum para Observabilidade em IA

By Boyu Wang

Updated: novembro 3, 2026

Published: agosto 22, 2026

O OpenTelemetry está fornecendo aos sistemas de GenAI um vocabulário compartilhado de telemetria, mas ele não é um esquema universal finalizado. Em junho de 2026, o projeto moveu suas convenções semânticas de GenAI, específicas de provedores e de MCP para um repositório dedicado, permitindo que elas iterem e passem por versionamento de forma independente. Atualmente, esse repositório classifica as convenções de GenAI como Development (Em Desenvolvimento) e, até 21 de agosto de 2026, não possui um lançamento oficial. A oportunidade ainda é substancial: nomes comuns para operações de modelo, uso de tokens, etapas de agentes, chamadas de MCP, eventos de conteúdo e resultados de avaliação podem reduzir o trabalho de tradução entre a instrumentação e os backends de observabilidade. A postura de engenharia deve ser a de adoção consciente de versões—e não a suposição de que o gen_ai.* já foi congelado.

Principais Conclusões

Principais Conclusões

  • Um vocabulário comum está emergindo, não um esquema finalizado. O repositório dedicado de convenções GenAI do OpenTelemetry ainda está em Development e evolui de forma independente.
  • A telemetria de inferência vai além do campo com o nome do modelo. As convenções atuais cobrem operações de modelo, uso de tokens de entrada/saída, durações, resultados e métricas relacionadas.
  • Agentes e MCP possuem convenções de primeira classe. As operações de agentes incluem conceitos de criação/invocação/planejamento/execução de ferramentas; o MCP define spans de cliente/servidor, propagação de contexto e métricas.
  • A captura de conteúdo é sensível e baseada em opt-in. O evento de detalhes de operação de inferência é Opt-In, e o suporte de implementação ainda varia conforme a linguagem.
  • A avaliação é representada—mas não realizada—pelo OpenTelemetry. O evento gen_ai.evaluation.result fornece um suporte padrão para pontuações e explicações de avaliadores.
  • A portabilidade é direcional, não automática. A semântica compartilhada reduz a re-instrumentação e a tradução, mas o suporte do backend, as versões das convenções, os atributos personalizados e as consultas ainda importam.
  • A TrueFoundry já fornece um limite de exportação nativo em OTel. O AI Gateway exporta traces e métricas via OTLP e documenta atributos de estilo atual sob gen_ai.* junto com extensões da TrueFoundry; a compatibilidade exata com um esquema não lançado e em mudança ainda deve ser verificada.

Duas equipes podem emitir um OpenTelemetry válido e ainda assim discordar sobre o que significa uma chamada a um LLM. Interoperabilidade de transporte e interoperabilidade semântica são problemas diferentes. O OTLP pode mover telemetria entre sistemas; as convenções semânticas tornam os campos dentro dessa telemetria interpretáveis de forma mais consistente. Para GenAI, o segundo problema ainda está sendo ativamente padronizado.

Nota de Status Atual
O status atual é importante
A versão v1.42.0 das convenções semânticas core do OpenTelemetry moveu as definições de GenAI para o repositório separado semantic-conventions-genai. As definições antigas no repositório core foram descontinuadas lá porque mudaram de lugar—não porque a telemetria de GenAI em si foi descontinuada. O novo repositório atualmente rotula as convenções como Development. Trate os exemplos em artigos antigos e SDKs como artefatos versionados, não como nomes de campos atemporais.

1. Por que a GenAI Precisa de Mais do que um APM Genérico

O APM genérico continua sendo útil para vazão (throughput), latência, erros, dependências e saúde dos serviços. A GenAI adiciona semânticas que esses sinais não descrevem por si só.

Comportamento probabilístico. A mesma requisição lógica pode produzir saídas diferentes, portanto, a depuração frequentemente precisa do modelo solicitado e servido, configurações de geração, identificadores de resposta e—onde a política permitir—contexto relevante de entrada ou saída. O conteúdo completo é uma evidência útil, mas nem sempre é apropriado ou necessário retê-lo.

Economia de tokens. A contagem de requisições ainda importa para carga e limitação de taxa (rate limiting), mas é insuficiente para análises de gastos e eficiência do modelo. Um pequeno número de chamadas com contexto longo pode custar mais do que um grande número de chamadas curtas. As métricas atuais de GenAI incluem uso de tokens e duração da operação, além de medições de tempo até o primeiro pedaço (time-to-first-chunk) e tempo por pedaço de saída (time-per-output-chunk).

Estrutura de agentes. Uma chamada de modelo é apenas uma operação dentro de muitos agentes. Planejamento, execução de ferramentas, recuperação (retrieval), fluxos de trabalho e chamadas de MCP podem determinar o resultado. A observabilidade precisa, portanto, de um vocabulário para a execução que envolve a inferência, não apenas para o limite da API do provedor.

Sensibilidade do conteúdo. Prompts e saídas frequentemente contêm dados de usuários ou de negócios. O OpenTelemetry pode descrever como registrar esse conteúdo, mas a decisão de capturar, reter, exportar, redigir ou restringir permanece sendo uma decisão de governança de dados.

2. O que as Convenções Cobrem Agora

A forma mais útil de ler o trabalho atual é por sinal e operação, em vez de presumir uma escala única de maturidade. O repositório dedicado de GenAI marca as convenções gerais como Development.

Spans de modelo e inferência. As convenções atuais definem operações de cliente GenAI, incluindo inferência, embeddings, recuperações (retrievals), busca de respostas, operações de memória e execução de ferramentas. Atributos comuns incluem gen_ai.provider.name, gen_ai.operation.name, identificadores de modelo solicitado e de resposta, e uso de tokens de entrada/saída. O tempo do span fornece a duração da operação; métricas dedicadas padronizam medições relacionadas a uso de tokens e latência.

Spans de agentes e frameworks. As convenções de agentes definem operações como create_agent, invoke_agent, invoke_workflow, plan e execute_tool. Esses spans podem tornar reconstruível um caminho de execução instrumentado. Eles não expõem o raciocínio privado de um modelo e não aparecem automaticamente, a menos que o framework ou a instrumentação relevante os emita.

Convenções MCP. O MCP possui suas próprias convenções em Development para spans de cliente e servidor, propagação de Trace Context do W3C, correlação de transporte, atributos orientados a ferramentas e métricas como mcp.client.operation.duration e mcp.server.operation.duration. O valor está na continuidade através do limite do MCP—não na promessa de que toda implementação de MCP já emite essas convenções.

Métricas e convenções específicas por provedor. O repositório define métricas de cliente, servidor, fluxo de trabalho, agente e ferramentas, além de adicionar convenções específicas para provedores em sistemas que incluem OpenAI, Anthropic, Azure AI Inference e AWS Bedrock.

OpenTelemetry GenAI conventions mapped across model inference, agent and workflow execution, MCP, content capture, evaluation results, and portability guidance.
Figura 1: As convenções atuais de GenAI cobrem operações de modelo, operações de agentes/fluxos de trabalho, spans e métricas de MCP, detalhes de conteúdo opt-in e um evento padrão para resultados de avaliadores. Elas padronizam a semântica de telemetria; elas não instrumentam automaticamente todas as camadas nem realizam a avaliação. Síntese editorial TrueFoundry; gráfico original.

3. A Captura de Conteúdo É uma Decisão de Política Opt-In

O evento atual gen_ai.client.inference.operation.details pode carregar histórico de chat, parâmetros, entradas e saídas independentemente do trace principal. Seu nível de requisito é explicitamente Opt-In, e a documentação do OpenTelemetry alerta que o suporte a eventos ainda não está disponível em todas as linguagens.

Esse é um padrão melhor do que tratar prompts e conclusões como texto de diagnóstico comum. O OpenTelemetry define a forma da telemetria; ele não decide seu período de retenção, armazenamento regional, política de acesso, base legal ou requisitos de redação. Essas continuam sendo responsabilidades do operador e do backend.

Para uma implantação em produção, escreva a política antes de ativar o conteúdo: quais ambientes podem capturar conteúdo completo, o que é filtrado ou truncado, para onde a telemetria exportada pode ir, por quanto tempo é retida e quem pode recuperá-la.

Nota de Avaliação
O OpenTelemetry pode registrar resultados de avaliação; ele não é o avaliador
As convenções atuais definem um evento recomendado gen_ai.evaluation.result para resultados como relevância, exatidão ou outras características definidas pelo avaliador, com campos de pontuação, rótulo, explicação e correlação de resposta. Isso não significa que o OpenTelemetry julga a resposta. Um avaliador—seja a lógica da aplicação, uma regra, um juiz baseado em modelo ou outro sistema—produz o resultado; o OpenTelemetry padroniza como esse resultado pode ser anexado à telemetria.

4. O que Isso Significa para um Gateway

Um gateway é um ponto forte de emissão para o tráfego de modelos que realmente passa por ele. Ele observa modelos solicitados e servidos, latência, resultados de provedores, uso de tokens, comportamento de roteamento e entradas de custo sem pedir que cada equipe de aplicação reconstrua essa coleta de forma independente. Ele não é, por si só, um trace de agente completo: planejamento local da aplicação, recuperação (retrieval), trabalho com ferramentas ou chamadas que ignoram o gateway exigem instrumentação nessas respectivas camadas.

A TrueFoundry já exporta via OpenTelemetry. O AI Gateway oferece suporte à exportação via OTLP para traces e métricas para plataformas de observabilidade compatíveis. O material de engenharia atual da TrueFoundry também documenta spans de provedores usando atributos contemporâneos como gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, gen_ai.response.model, gen_ai.usage.input_tokens e gen_ai.usage.output_tokens, além de extensões específicas da TrueFoundry para contexto do gateway e custo. (documentação de exportação OpenTelemetry; guia de instrumentação do gateway TrueFoundry.)

A visibilidade de MCP pode viver no mesmo plano operacional. O Metrics Dashboard da TrueFoundry rastreia tráfego de MCP, servidores, ferramentas, falhas e latência para chamadas roteadas através do AI/MCP Gateway. Isso complementa—não substitui—a instrumentação de aplicações ou frameworks para etapas locais dos agentes. (Metrics Dashboard; visão geral do MCP Gateway.)

O runtime do agente é o limite de observabilidade complementar. O TrueForge, o harness de agentes em código aberto da TrueFoundry, executa o loop de modelo/ferramenta com ferramentas MCP, skills, sandboxing, aprovações, gerenciamento de contexto e sessões persistentes. Seu modelo de SDK expõe uma hierarquia explícita de Agente → Sessão → Turno → Evento, com eventos transmitidos em streaming para inicialização de MCP, mensagens de modelo, respostas de ferramentas, aprovações e conclusão de turno. Esses eventos de runtime carregam contexto no nível do agente que um gateway não consegue inferir apenas a partir do tráfego do modelo e do MCP.

A afirmação segura para publicação é deliberadamente mais restrita do que uma afirmação de integração: este artigo não afirma que o TrueForge atualmente emite as convenções semânticas de GenAI mais recentes do OpenTelemetry. Em vez disso, o TrueForge fornece uma superfície de runtime aberta e inspecionável que pode ser instrumentada ou correlacionada com os traces OTLP que o TrueFoundry AI Gateway já exporta. Essa separação é uma arquitetura útil: o harness sabe o que o agente está fazendo; o gateway sabe o que cruzou seu limite de política; o OpenTelemetry dá a essas camadas instrumentadas um transporte comum e um vocabulário cada vez mais comum.

A exportação externa de traces possui um controle de conteúdo explícito. Os guias de integração OTel da TrueFoundry documentam uma opção Exclude Request Data (Excluir Dados da Requisição) que remove tfy.input, tfy.output e tfy.input_short_hand dos spans exportados, mantendo a telemetria estrutural, como tokens, latência e metadados do modelo. Esse é um controle de saída útil para esses campos de conteúdo da TrueFoundry; as equipes ainda devem revisar quaisquer atributos adicionais padrão ou personalizados que emitirem. (exemplo de documentação de integração.)

A avaliação continua sendo um cálculo separado. A TrueFoundry suporta fluxos de trabalho de avaliação externa sobre traces, enquanto a convenção do OpenTelemetry fornece um local padrão para representar o resultado de um avaliador. Não colapse isso em uma única afirmação: a telemetria carrega evidências; os avaliadores as interpretam. (avaliação online.)

TrueFoundry request-trace interface showing chat-completion and guardrail spans in a gateway trace tree
Figura 2: A interface de trace de requisições da TrueFoundry mostra o trabalho visível pelo gateway como uma árvore de spans—neste exemplo, atividades de chat-completion e guardrails. Isso demonstra o limite de observabilidade compartilhado; não deve ser lido como prova de que todas as etapas de um agente locais da aplicação estão presentes. Fonte: Material do produto TrueFoundry.
Tabela de Convenções do OpenTelemetry
Área O que as convenções atuais fornecem Interpretação segura para publicação
Modelo / inferência Spans, atributos de modelo/provedor, uso de tokens, métricas de operação e streaming Vocabulário comum de telemetria; suporte de implementação ainda varia
Agente / fluxo de trabalho Conceitos de spans para criação/invocação/planejamento/execução de ferramentas e métricas de agentes Pode representar a estrutura de execução instrumentada; não o raciocínio privado do modelo
MCP Spans de cliente/servidor, propagação de contexto, atributos orientados a ferramentas e métricas Preserva a semântica através de limites instrumentados de MCP
Conteúdo de prompt / resposta Evento opt-in de detalhes de operação de inferência e campos de conteúdo Política de dados sensíveis e retenção no backend continuam sendo responsabilidades do operador
Avaliação Evento gen_ai.evaluation.result Registra a saída de um avaliador; não realiza a avaliação
Portabilidade Transporte OpenTelemetry compartilhado somado à semântica de GenAI cada vez mais compartilhada Reduz o trabalho de tradução; não garante UX idêntica no backend nem trabalho zero de migração

5. Uma Postura Pronta para Implantação

Separe a portabilidade do OTLP da maturidade das convenções semânticas. É útil exportar traces e métricas via OpenTelemetry hoje mesmo enquanto os nomes dos campos de GenAI continuam evoluindo.

Fixe (pin) e teste a semântica que você realmente emite. O repositório de GenAI está em Development, definições core antigas foram movidas e o suporte a linguagens é irregular. Trate seu conjunto de atributos emitidos como uma interface versionada e teste-o contra as bibliotecas de backend e de instrumentação que você opera.

Instrumente cada limite de execução ou aplicação de regras pelo que ele pode realmente ver. Um gateway é excelente para o tráfego de modelos e de MCP roteado por ele. A instrumentação de agentes/harnesses ainda é necessária para planejamento, ferramentas locais, recuperação (retrieval), transições de estado e outros trabalhos que nunca cruzam esse gateway.

Instrumente o limite do harness quando precisar de semânticas de agente. Se você usa o TrueForge, seu modelo de sessão, turno e evento oferece identificadores explícitos de runtime e eventos de ferramentas/aprovações para correlacionar com os traces do gateway. Carregue apenas os metadados de correlação que sua política de observabilidade permitir; não copie conteúdos sensíveis de eventos para os atributos de span por padrão.

Torne a captura de conteúdo opt-in por política. Minimize e filtre o conteúdo antes de exportá-lo, em seguida defina os controles de retenção e acesso no backend de observabilidade. Não confunda um nome de campo do OpenTelemetry com uma política de governança de dados.

Mantenha a avaliação separada, mas correlacionada. Calcule a qualidade ou a segurança com o avaliador adequado para a carga de trabalho, em seguida use um evento padrão de resultado de avaliação onde houver suporte para anexar o resultado à operação que produziu a resposta.

Use atributos personalizados como extensões, não como substitutos. Campos específicos de produtos, como os metadados de gateway e custo da TrueFoundry, são úteis. Mantenha os atributos padrão ao lado deles para que as ferramentas genéricas ainda tenham uma superfície comum.

6. Onde o Padrão Termina

As convenções semânticas resolvem um problema de vocabulário, não todos os problemas de observabilidade. O repositório dedicado de GenAI do OpenTelemetry ainda está em Development; a cobertura da implementação varia por linguagem e biblioteca; e os backends podem diferir em como indexam, consultam, renderizam, retêm ou cobram pela mesma telemetria. Mesmo uma cobertura perfeita de convenções semânticas apenas descreve o que a instrumentação consegue observar—ela não expõe o raciocínio oculto do modelo nem torna visível a execução não instrumentada.

Para a TrueFoundry, a afirmação útil é concreta: o AI Gateway pode exportar traces e métricas via OTLP e documenta atributos de estilo atual sob gen_ai.* junto com extensões específicas da TrueFoundry. Isso oferece às equipes um caminho de exportação baseado em padrões sem fingir que as convenções de GenAI, que evoluem de forma independente, estão congeladas. Se uma versão específica de convenção semântica for um requisito de governança ou compras, valide o conjunto exato de atributos emitidos e o suporte de linguagem/backend dos quais você depende.

Referências

O status e os nomes de campos de GenAI do OpenTelemetry são descritos a partir do repositório dedicado de convenções semânticas de GenAI conforme verificado em 21 de agosto de 2026. O repositório está em Development e não possui lançamento oficial até essa data. As declarações sobre os produtos da TrueFoundry estão limitadas à documentação pública atual e materiais de engenharia: exportação OTLP, observabilidade de gateway, métricas de MCP, atributos gen_ai.* documentados e filtragem no momento da exportação de campos de conteúdo tfy.* especificados. Este artigo não reivindica conformidade com um commit específico e não lançado do repositório OpenTelemetry GenAI.

Try now.

One gateway for all your models, MCP servers, and agents. No credit card needed.

Start free
Table of Contents

One Gateway for Every LLM, Agent and MCP Server

Book a 30-min with our AI expert

Book a Demo

The fastest way to build, govern and scale your AI

Book Demo
Summarize with
ChatGPT logo by OpenAI
Perplexity AI logo
Blurry red snowflake on white background, symmetrical frosty design with soft edges and abstract shape.

Discover More

No items found.
A detailed guide on LiteLLM alternatives
novembro 20, 2026
|
5 min read

As 5 Melhores Alternativas ao LiteLLM em 2026

comparação
novembro 20, 2026
|
5 min read

Atualizações do Protocolo MCP: DCR, OAuth CIMD, Streamable HTTP & MCP Apps

No items found.
novembro 20, 2026
|
5 min read

Grok 4.3 no Amazon Bedrock: Roteamos Quatro Modelos de Fronteira por um Único Gateway e Medimos o Custo

Ferramentas de LLM
comparação
novembro 20, 2026
|
5 min read

GPT-6.1 Terra: API, Benchmarks, Preço & Como Usar

No items found.
No items found.

Recent Blogs

Black left pointing arrow symbol on white background, directional indicator.
Black left pointing arrow symbol on white background, directional indicator.
Take a quick product tour
Start Product Tour
Product Tour