Rastreamento GenAI com OpenTelemetry: um playbook prático para observabilidade de LLMs e agentes

Por que o rastreamento GenAI com OpenTelemetry importa agora

O rastreamento GenAI com OpenTelemetry oferece às equipes de engenharia uma forma de inspecionar fluxos de trabalho de LLMs e agentes sem tratar a chamada ao modelo como uma caixa-preta. Isso parece seco até algo quebrar. A API retorna 200. O app não trava. O usuário recebe uma resposta. Ainda assim, a resposta pode ser superficial, cara demais para a tarefa, construída a partir do contexto recuperado errado ou moldada por uma chamada de ferramenta que ninguém percebeu na revisão.

Essa é a parte incômoda do trabalho de IA em produção. Logs padrão podem provar que uma solicitação aconteceu. Eles raramente explicam por que um fluxo de trabalho de IA se comportou daquele jeito.

OpenTelemetry GenAI não é outro produto de monitoramento para comprar. É um conjunto de convenções semânticas para descrever operações de IA generativa em um formato consistente. A orientação oficial do OpenTelemetry cobre solicitações de modelo, respostas, eventos, métricas, exceções, spans de agentes e telemetria relacionada. Se as equipes descrevem provedores, modelos, prompts, conclusões, uso de tokens, ferramentas e etapas de agentes com convenções compartilhadas, os traces ficam mais fáceis de consultar, comparar e mover entre backends de observabilidade.

Minha visão: a maioria das equipes de IA espera tempo demais para padronizar isso. Elas adicionam rastreamento depois do primeiro incidente doloroso, quando versões de prompts, regras de roteamento e comportamento de ferramentas já estão espalhados por logs, notebooks e capturas de tela de dashboards. O melhor momento é antes de um fluxo de trabalho se tornar importante.

De logs de aplicação a traces de modelo, ferramenta e agente

A maioria das equipes de produção já monitora o básico: latência HTTP, códigos de status, chamadas de banco de dados, profundidade de filas, falhas de dependências e taxas de erro. Sistemas de LLM falham de formas mais silenciosas. Uma resposta gerada pode ser ruim porque um template de prompt mudou, a recuperação selecionou fontes fracas, o modelo foi roteado para outro provedor, uma ferramenta retornou dados parciais, o streaming parou cedo, uma nova tentativa alterou o contexto final ou a validação permitiu uma resposta que deveria ter sido bloqueada.

O rastreamento dá forma a essas etapas. Em vez de uma operação opaca chamada gerar resposta, um trace pode mostrar montagem do prompt, recuperação, invocação do modelo, seleção de ferramenta, execução de ferramenta, validação e montagem da resposta como spans relacionados. Isso importa quando um protótipo vira um fluxo de trabalho gerenciado. Depuração, revisão de incidentes, controles de privacidade e revisão de custos precisam de mais do que capturas de tela e logs JSON improvisados.

O que as convenções semânticas de GenAI acrescentam

As convenções GenAI do OpenTelemetry dão às equipes um vocabulário compartilhado para operações de modelo. Uma chamada de modelo pode ficar dentro do mesmo trace distribuído que a solicitação web, o serviço de recuperação, a consulta de banco de dados e a ferramenta downstream. Em alto nível, as convenções cobrem o sistema ou provedor GenAI, nomes de operações, modelos de solicitação e resposta, uso de tokens, prompts e conclusões como eventos quando capturados, exceções, métricas e spans relacionados a agentes.

O limite é tão importante quanto o benefício. O rastreamento ajuda equipes a reconstruir o que aconteceu durante uma solicitação. Ele não prova que a resposta final estava correta, segura ou útil. Você ainda precisa de avaliações, red teaming quando apropriado, controles de acesso, logs específicos de provedores, revisão de privacidade e julgamento de produto.

A lacuna de observabilidade em aplicações de LLM e agentes

O monitoramento tradicional de desempenho de aplicações é forte em saúde de serviço. Ele pode mostrar que um endpoint estava lento, uma dependência expirou ou uma consulta de banco de dados falhou. Para aplicações de LLM, esses sinais são necessários, mas incompletos. Um trace normal de serviço muitas vezes não mostra construção de prompt, versão do template de prompt, identificadores de documentos recuperados, escolha de modelo, configurações de amostragem, motivo de parada, roteamento de ferramentas, comportamento de novas tentativas, decisões de segurança e resultados de avaliação.

Agentes ampliam a lacuna. Eles podem planejar, chamar ferramentas, inspecionar resultados, chamar o modelo novamente, recuperar memória, transferir para outro fluxo de trabalho, executar validações e parar sob uma regra de término. Algumas etapas podem falhar enquanto o usuário ainda recebe uma resposta final. Equipes que trabalham em sistemas agênticos também devem ler de forma mais ampla sobre confiabilidade e supervisão de agentes de IA, porque o rastreamento mostra o caminho que um agente tomou enquanto a supervisão decide se esse caminho foi aceitável.

Uma primeira versão prática de observabilidade de LLM geralmente registra modelo e provedor, nome da operação, modelo solicitado, modelo de resposta quando disponível, parâmetros da solicitação, latência, contagens de tokens quando disponíveis, motivo de parada, nome da ferramenta, status do resultado da ferramenta, identificadores de fontes de recuperação, categorias de erro, sinalizadores de segurança e resultados de avaliação. A captura de conteúdo precisa de política mais rígida. Prompts e conclusões podem conter dados de usuários, documentos privados, segredos, contratos, código-fonte, informações de saúde, dados financeiros ou estratégia interna. Muitas equipes devem começar com metadados, IDs, hashes e trechos redigidos em vez de conteúdo completo.

O que o OpenTelemetry GenAI padroniza

As convenções semânticas do OpenTelemetry definem uma linguagem comum para telemetria. Na área GenAI, elas descrevem atributos e eventos que tornam operações de modelo reconhecíveis entre serviços e ferramentas. Um span de invocação de modelo pode identificar o provedor GenAI, nome da operação, modelo solicitado, modelo de resposta, parâmetros da solicitação, uso de tokens e metadados da resposta. Os nomes exatos dos atributos devem ser verificados no repositório atual de GenAI do OpenTelemetry antes da implementação, porque as convenções ainda estão mudando.

Eventos são úteis porque uma solicitação de modelo nem sempre é bem representada como atributos estáticos de span. Uma interação de chat pode conter várias mensagens. Uma resposta em streaming pode produzir pedaços ao longo do tempo. Uma chamada de ferramenta pode estar associada a uma mensagem do assistente e a um resultado de ferramenta posterior. A segurança ainda vem primeiro. Eventos podem carregar texto sensível se a captura de conteúdo estiver habilitada. Equipes que constroem fluxos de trabalho com documentos podem achar útil o guia da Optijara sobre pipelines de IA para documentos, já que sistemas de documentos muitas vezes combinam recuperação, extração, geração e restrições de privacidade.

O OpenTelemetry Protocol, geralmente abreviado como OTLP, dá às equipes uma rota para enviar telemetria a backends de observabilidade compatíveis. O suporte de backend varia. Algumas ferramentas exibem traces GenAI claramente. Outras os tratam como spans comuns com atributos. Antes de chamar isso de pronto para produção, verifique a consultabilidade, a visualização de traces, o comportamento de retenção e o controle de acesso no backend que sua equipe realmente usa.

O Optijara GenAI Trace Map

O Optijara GenAI Trace Map é um framework orientado a decisões para projetar observabilidade de LLMs e agentes. Ele transforma o rastreamento de um hábito de coleta de dados em uma atividade de design de produção. A pergunta não é o que podemos registrar em log. A pergunta melhor é qual decisão este trace deve nos ajudar a tomar, quais spans expõem essa decisão e qual conteúdo deve ficar fora da telemetria.

Comece com decisões, não com dashboards. Perguntas úteis para traces incluem qual chamada de modelo foi lenta, qual provedor atendeu à solicitação, qual versão do template de prompt foi usada, quais documentos foram recuperados, qual ferramenta falhou, se novas tentativas alteraram a resposta final, se a validação passou e qual fluxo de trabalho produziu uso incomum.

Uma política compacta legível por máquina pode ajudar equipes de engenharia e governança a se alinharem antes que a instrumentação se espalhe:

{
  "framework": "Optijara GenAI Trace Map",
  "trace_goal": "debug and evaluate one production AI workflow",
  "required_spans": ["entry", "prompt_assembly", "retrieval", "model_call", "tool_call", "validation", "evaluation"],
  "content_policy": {
    "forbidden": ["secrets", "credentials", "unredacted private documents"],
    "redacted": ["user text", "tool output"],
    "sampled": ["prompt events", "completion events"],
    "retained": ["metadata", "trace ids", "template versions", "document ids"]
  }
}

Padrões de implementação, de uma chamada de LLM a agentes

A implementação mais simples rastreia uma solicitação de modelo dentro de um trace de aplicação existente. O span pai é a solicitação do usuário ou job em segundo plano. O span filho é a operação GenAI. Ele deve capturar o provedor ou sistema, modelo solicitado, nome da operação, parâmetros relevantes, latência, status, uso de tokens quando disponível, modelo de resposta quando disponível e detalhes de exceção se a chamada falhar.

Geração aumentada por recuperação precisa de mais do que um span de modelo. Um trace RAG útil geralmente inclui reescrita da consulta, busca por embeddings, reranking, IDs dos documentos selecionados, montagem de contexto, geração final, validação de citações e montagem da resposta. IDs de documentos importam porque permitem que as equipes auditem quais fontes influenciaram a resposta sem colocar documentos confidenciais completos na telemetria.

Para agentes, represente o fluxo de trabalho como uma árvore. O span raiz é a tarefa do usuário. Spans filhos podem incluir planejamento, chamadas de modelo, seleção de ferramenta, cada execução de ferramenta, validação de saída da ferramenta, reflexão, leituras de memória, validação de resposta e término. Se o agente chama ferramentas em paralelo, cada chamada de ferramenta deve estar visível como um span irmão com status e duração.

user_task: investigate_invoice_question
  prompt_assembly: support_agent_v4
  model_call: plan_next_step
  tool_call: search_orders status=ok
  tool_call: fetch_invoice status=timeout
  model_call: revise_plan_after_timeout
  tool_call: fetch_invoice status=ok retry=1
  validation: policy_and_schema_check status=passed
  response_assembly: final_answer

A LangSmith documenta suporte a rastreamento OpenTelemetry, o que é um exemplo útil de integração de ecossistema. Instrumentação de frameworks pode reduzir o trabalho manual com spans, especialmente quando as equipes já usam um framework para chains, ferramentas ou agentes. Trate essa instrumentação como ponto de partida e depois inspecione os traces exportados. Isso combina bem com higiene de engenharia mais ampla, como usar uv para fluxos de trabalho de projetos Python, em que ferramentas reproduzíveis e ambientes consistentes tornam a implantação de observabilidade mais fácil de manter.

Plano de adoção e avaliação

Uma implantação segura começa com um fluxo de trabalho e uma lista de testes. Verifique a continuidade do trace entre serviços. Confirme que os nomes de atributos GenAI correspondem à documentação atual do OpenTelemetry que sua equipe escolheu seguir. Verifique o comportamento de amostragem. Teste a redação de prompts. Inspecione respostas em streaming. Confirme se o uso de tokens está disponível no seu provedor e como ele é representado. Garanta que erros de ferramentas sejam capturados como erros de ferramentas, não apenas como exceções genéricas. Consulte traces no backend e confirme que engenheiros de plantão conseguem encontrar o que precisam.

Evite capturar prompts completos por padrão. Evite depender de um único dashboard como fonte da verdade. Evite tratar contagens de tokens como exatas em todos os provedores e fluxos de trabalho. Evite instrumentar toda função auxiliar. Evite ignorar política de retenção e acesso. Evite usar traces como prova de que uma resposta foi boa. As convenções do OpenTelemetry continuam a evoluir, então as equipes devem fixar versões de instrumentação, documentar suposições e revisar mudanças nas convenções antes de uma implantação ampla.

Erros comuns que equipes cometem

A forma mais rápida de criar risco de observabilidade é registrar prompts e conclusões primeiro e discutir política depois. Prompts podem conter dados pessoais, documentos confidenciais, credenciais, código-fonte, planos de negócio privados ou informações reguladas. Defina campos proibidos, redigidos, amostrados e retidos antes da instrumentação.

Rastreamento apenas do modelo é estreito demais para agentes. Muitas falhas acontecem fora do modelo: a recuperação retorna contexto fraco, uma ferramenta expira, a validação é ignorada, a memória contém informações antigas ou a montagem da resposta remove um detalhe importante. Se o trace para no span do modelo, a equipe pode culpar a camada errada.

Todo atributo deve responder a uma pergunta. Quem usará este campo, durante qual fluxo de trabalho e qual decisão ele apoiará? Se ninguém consegue responder, o campo provavelmente é ruído. Traces são evidência de processo. Avaliações são evidência de qualidade de saída, e mesmo avaliações precisam de desenho cuidadoso de rubrica.

Como escolher seu primeiro projeto de rastreamento

O melhor primeiro projeto nem sempre é o recurso de IA mais complexo. Escolha um fluxo de trabalho em que a observabilidade mudará decisões em breve.

Um primeiro marco prático é uma solicitação ponta a ponta com uma árvore de traces legível. O trace deve se conectar aos logs da aplicação por meio do ID de trace. Ele deve mostrar montagem do prompt, recuperação se presente, chamada de modelo, resultados de ferramentas se presentes, validação de resposta e um sinal de avaliação ou revisão. A redação deve ser verificada antes de qualquer implantação mais ampla.

Se sua equipe está passando de protótipos para fluxos de trabalho de IA em produção, a Optijara pode ajudar a mapear traces, avaliações e verificações de governança antes que a instrumentação fique ruidosa ou arriscada. O objetivo deve ser observabilidade neutra em relação a fornecedores, que ajude equipes a depurar, avaliar e operar sistemas de IA com limites claros.

O rastreamento GenAI com OpenTelemetry é mais útil quando as equipes padronizam antes de escalar, rastreiam decisões em vez de toda chamada possível, protegem conteúdo sensível, conectam traces a avaliações e mantêm as convenções sob revisão à medida que o ecossistema amadurece.