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

Built for Speed: ~10ms Latency, Even Under Load
Blazingly fast way to build, track and deploy your models!
- Handles 350+ RPS on just 1 vCPU — no tuning needed
- Production-ready with full enterprise support
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.
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.
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.

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.
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.)

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
- OpenTelemetry — Visão geral das convenções semânticas de GenAI (status atual: Development).
- OpenTelemetry — Spans de cliente GenAI, métricas e spans de agentes/frameworks.
- OpenTelemetry — Convenções semânticas de MCP para spans de cliente/servidor, propagação e métricas.
- OpenTelemetry — Eventos de GenAI, incluindo detalhes de inferência opt-in e
gen_ai.evaluation.result. - OpenTelemetry — convenções semânticas core v1.42.0, que moveram as definições de GenAI para o repositório dedicado.
- TrueFoundry — Exportação de traces e métricas OpenTelemetry; Guia de instrumentação do AI Gateway; Metrics Dashboard; Visão geral do MCP Gateway.
- TrueFoundry — Avaliação online, como um cálculo separado sobre evidências de observabilidade.
- TrueForge — Visão geral do harness de agentes e conceitos do SDK, documentando a hierarquia Agente → Sessão → Turno → Evento e eventos de runtime para atividades de modelo, MCP, ferramenta, aprovação e conclusão. Este artigo não reivindica conformidade nativa desses eventos com as convenções semânticas de GenAI mais recentes.
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.
TrueFoundry AI Gateway delivers ~3–4 ms latency, handles 350+ RPS on 1 vCPU, scales horizontally with ease, and is production-ready, while LiteLLM suffers from high latency, struggles beyond moderate RPS, lacks built-in scaling, and is best for light or prototype workloads.





















