Para observar um agente de IA, represente cada percurso como operações relacionadas: a invocação do agente ou workflow, as chamadas ao modelo e a execução de ferramentas podem ter spans próprios; ocorrências pontuais dentro dessas operações podem ser registradas como eventos; atributos descrevem o contexto de cada operação. Essa composição ajuda a reconstruir uma execução sem tratá-la como uma entidade única garantida por uma API universal.
As convenções GenAI da OpenTelemetry oferecem nomes e campos comuns para essa instrumentação, mas as convenções de agentes e frameworks estão marcadas como Development. Confira o estado atual e o suporte da biblioteca escolhida antes de padronizar nomes ou comparar emissores.
O que é uma trajetória observável de agente?
Uma trajetória é a composição das operações que formam uma execução: por exemplo, invocar um agente, planejar uma resposta, chamar um modelo e executar uma ferramenta. Em vez de registrar tudo como uma única chamada indistinta, use spans relacionados para representar as fronteiras e durações que importam. Assim, um trace pode ajudar a reconstruir uma execução individual sem pressupor que exista um tipo universal de “trajetória”.
As convenções para agentes e frameworks descrevem operações como invoke_agent, invoke_workflow, plan e execute_tool. Elas também distinguem a invocação remota do agente, descrita como span CLIENT, da invocação dentro do mesmo processo, descrita como INTERNAL. Consulte os nomes e requisitos na convenção de spans de agentes e frameworks GenAI.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallA hierarquia deve refletir a execução real: uma operação de agente ou workflow pode conter operações de modelo e ferramentas. Isso preserva a diferença entre o escopo geral do agente e o trabalho realizado por cada dependência.
Quando usar spans, eventos ou atributos?
Escolha o sinal pelo tipo de informação: span para uma operação com duração e fronteiras relevantes; evento para uma ocorrência pontual com horário próprio; atributo para contexto da operação que não precisa de um timestamp independente.
| Sinal | Use para | Exemplo em um agente |
|---|---|---|
| Span | Operação com início, fim e duração relevantes. | Invocar um agente remoto, chamar um modelo ou executar uma ferramenta externa. |
| Evento | Ocorrência pontual que pode ocorrer zero ou várias vezes durante uma operação e merece horário próprio. | Uma ocorrência específica durante planejamento ou execução, se houver motivo para registrá-la separadamente. |
| Atributo | Propriedade que descreve a operação como um todo. | Nome do agente, modelo solicitado ou ferramenta chamada. |
Spans: duração e fronteiras
Use spans para etapas cuja duração seja útil para entender latência, falhas ou dependências. Cada span deve representar uma operação definida, com nome estável e atributos que expliquem o que ocorreu. A orientação de convenções da OpenTelemetry recomenda priorizar operações significativas com duração e evitar spans para ocorrências pontuais ou operações locais curtas sem chamadas externas. Veja a orientação para escrever convenções semânticas.
Eventos: ocorrências com horário próprio
Um evento é adequado quando a ocorrência tem importância própria dentro de um span, mas não precisa ser uma operação duradoura. A especificação de eventos determina: “Events MUST have Timestamp set to the time when the event occurred.” O nome deve identificar uma estrutura estável, não conter valores dinâmicos; detalhes variáveis podem ficar nos atributos do evento. Consulte as convenções gerais de eventos.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Atributos: contexto sem timestamp independente
Use atributos para caracterizar o span sem criar um sinal separado para cada propriedade. Reutilize atributos semânticos existentes quando aplicáveis; crie atributos novos apenas quando houver benefício e um plano claro para seu uso, conforme a orientação da OpenTelemetry para convenções semânticas.
Como organizar spans para chamadas de modelo e ferramentas?
Comece pelas fronteiras que correspondem a operações reais. Uma invocação de agente ou workflow pode abranger etapas de planejamento e, quando houver, chamadas ao modelo e ferramentas. Dê a cada operação significativa seu próprio span relacionado, em vez de achatar todo o percurso em um único span sem distinção.
- Defina a fronteira da execução. Instrumente a invocação do agente ou workflow com a operação apropriada, como
invoke_agentouinvoke_workflow. Represente corretamente se a invocação é remota (CLIENT) ou ocorre no mesmo processo (INTERNAL). - Registre planejamento quando for uma operação significativa. Use a operação
planse o planejamento tiver duração ou relevância operacional própria. Não crie spans para cada ação local breve apenas para aumentar o detalhe. - Separe a inferência do escopo do agente. Registre a operação de modelo como uma operação distinta da invocação mais ampla do agente. Preserve a relação entre elas para que a execução possa ser entendida no contexto do workflow.
- Instrumente a execução de ferramentas. Use
execute_toolpara representar a operação da ferramenta quando ela constituir uma etapa significativa, especialmente se envolver uma chamada externa. Diferencie-a da chamada ao modelo que a precedeu. - Registre estados pontuais como eventos. Quando um estado ou ocorrência tiver timestamp próprio, mas não duração relevante, avalie um evento em vez de abrir outro span.
Essa organização não exige que toda alteração interna de estado vire telemetria. O sinal deve tornar visíveis as fronteiras úteis para entender latência e falhas sem transformar ações locais muito curtas em spans desnecessários.
Quais campos ajudam a correlacionar uma execução?
Use os atributos GenAI aplicáveis para que uma pessoa consiga identificar o tipo de operação e o contexto relacionado. A convenção de agentes e frameworks lista campos como:
gen_ai.operation.namepara o tipo de ação, comoinvoke_agent,planouexecute_tool;gen_ai.agent.name,gen_ai.agent.idegen_ai.agent.versionpara identificar o agente;gen_ai.provider.nameegen_ai.request.modelpara o provedor conhecido pela instrumentação e o modelo solicitado;gen_ai.conversation.idpara relacionar atividade da mesma conversa;gen_ai.tool.name,gen_ai.tool.typeegen_ai.tool.call.idpara descrever a atividade de ferramentas;error.typepara caracterizar uma falha com um identificador de baixa cardinalidade.
Use nomes de span estáveis e de baixa cardinalidade. Não inclua IDs de conversa, usuário ou chamada no nome: mantenha valores variáveis em atributos. Quando possível, forneça cedo os atributos relevantes para decisões de amostragem. Os detalhes e aplicabilidade dos campos estão na convenção de spans de agentes.
Há duas qualificações importantes ao interpretar os identificadores. O ID persistente de um agente hospedado não é necessariamente o mesmo que o ID transitório de uma instância em memória. E gen_ai.provider.name reflete o que a instrumentação sabe sobre endpoint ou configuração; se houver um proxy ou plataforma intermediária, esse nome pode representar o intermediário, não o fornecedor final a montante.
Quais métricas complementam os traces?
Traces ajudam a entender uma execução individual; métricas ajudam a acompanhar distribuições e tendências em muitas execuções. A convenção GenAI inclui gen_ai.client.operation.duration para duração de operações do cliente e, para respostas em streaming, métricas de tempo até o primeiro chunk e de intervalo entre chunks de saída. Os detalhes estão na convenção de métricas GenAI.
Compare métricas apenas quando suas fronteiras forem equivalentes. A duração ponta a ponta de um workflow pode incluir vários agentes ou outras operações; a duração de uma operação cliente voltada ao provedor cobre uma fronteira mais estreita. O tempo até o primeiro chunk também responde a uma pergunta diferente da duração total.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches| Medida | Escopo que descreve | Pergunta operacional |
|---|---|---|
| Duração do workflow | Execução ponta a ponta, que pode compor várias operações. | Quanto tempo o percurso completo levou? |
gen_ai.client.operation.duration |
Operação individual do cliente. | Quanto tempo levou esta operação voltada ao provedor? |
| Tempo até o primeiro chunk | Início da resposta em streaming. | Quanto demorou para começar a chegar a saída? |
| Tempo entre chunks de saída | Intervalos durante a saída em streaming. | Como a saída foi chegando ao longo da resposta? |
Como evitar registrar prompts e dados sensíveis?
Mensagens de entrada e saída, instruções de sistema e dados de ferramentas podem conter informações pessoais, segredos ou outros dados sensíveis. Argumentos e resultados de ferramentas aparecem como opt-in nas convenções de spans de agentes; as convenções de eventos também alertam para o risco de conteúdo sensível. A visão geral das convenções GenAI e a especificação de eventos de entrada e saída GenAI tratam dessas áreas.
Uma abordagem prudente é começar com metadados operacionais, como duração, tipo de operação e resultado, e habilitar payloads completos apenas quando forem necessários e houver controles adequados de acesso e retenção. Se a instrumentação escolhida oferecer esses recursos, use filtragem ou truncamento para limitar o conteúdo registrado. Isso reduz exposição potencial, mas não substitui a avaliação das necessidades de privacidade, segurança e retenção do seu ambiente.
O que verificar antes de padronizar a instrumentação?
As convenções para agentes e frameworks estão em desenvolvimento, e as convenções GenAI são mantidas em áreas separadas para agentes, clientes, MCP, provedores, eventos e métricas. Nomes comuns buscam facilitar consistência entre bibliotecas, código e plataformas, mas isso não demonstra que um produto específico implemente todas as convenções. Consulte o repositório das convenções GenAI e confira o suporte real da biblioteca, do framework e do backend que você pretende usar.
- Confirme o status atual da convenção e se os nomes ou requisitos mudaram.
- Verifique quais spans, atributos, eventos e métricas a instrumentação emite de fato.
- Compare fronteiras equivalentes antes de interpretar ou agregar métricas.
- Confira como a instrumentação trata conteúdo de prompts, argumentos e resultados de ferramentas.
- Não presuma interoperabilidade completa só porque duas bibliotecas usam OpenTelemetry.
A documentação oficial consultada em 2 de outubro de 2026 identifica a convenção de agentes como Development. Como as páginas e implementações podem evoluir, considere essa data ao adotar os nomes e requisitos atuais.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
