Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Para observar um agente de IA com OpenTelemetry GenAI, represente sua trajetória como operações relacionadas: spans para invocações, chamadas ao modelo e ferramentas com duração relevante; eventos para ocorrências pontuais; atributos para contexto da operação; e métricas para acompanhar tendências em várias execuções. Não há uma API universal que transforme todos esses passos em uma única entidade de trajetória.
Como representar a trajetória de um agente
Uma trajetória observável é a composição de operações que permite reconstruir uma execução: por exemplo, invocar um agente, planejar, chamar um modelo e executar uma ferramenta. Preserve as fronteiras que existem no sistema, em vez de achatar tudo em uma chamada indistinta. A convenção GenAI define operações como invoke_agent, invoke_workflow, plan e execute_tool; convenções específicas de frameworks podem adotar formatos diferentes. Consulte a convenção de spans para agentes e frameworks antes de padronizar os nomes emitidos.
Use spans nas operações com duração relevante
Um span deve marcar o início e o fim de uma operação importante, como uma invocação remota do agente, uma inferência ou a execução de uma ferramenta externa. Uma operação mais ampla de agente ou workflow pode conter spans de modelo e de ferramenta, desde que essa hierarquia corresponda ao fluxo real. Não crie spans para cada etapa local muito curta ou para ocorrências sem duração significativa: isso adiciona ruído sem melhorar a reconstrução da execução.
| Trecho da execução | Operação ou tipo de span | Quando usar |
|---|---|---|
| Invocação remota do agente | invoke_agent, tipo CLIENT |
Quando a chamada cruza um limite de processo ou serviço. |
| Invocação no mesmo processo | invoke_agent, tipo INTERNAL |
Quando o agente é invocado dentro do próprio processo. |
| Planejamento | plan |
Quando o planejamento é uma operação significativa com duração própria. |
| Execução de ferramenta | execute_tool |
Quando uma ferramenta é executada como operação observável. |
| Workflow | invoke_workflow |
Quando há uma operação de workflow com fronteira ponta a ponta própria. |
| Inferência do modelo | Span da operação de inferência | Quando a chamada ao modelo tem fronteira e duração próprias; mantenha-a distinta da operação mais ampla do agente. |
Use eventos para ocorrências pontuais
Um evento é adequado para uma ocorrência que acontece em um instante dentro de um span, pode ocorrer zero ou várias vezes e merece horário próprio, severidade ou atributos específicos. O nome deve identificar o tipo de ocorrência, não incluir valores dinâmicos. A especificação oficial estabelece: “Events MUST have Timestamp set to the time when the event occurred.” Consulte as convenções de eventos da OpenTelemetry.
#1 Best Overall
Use atributos para descrever a operação
Atributos registram propriedades que caracterizam o span como um todo e não precisam de timestamp independente. Prefira atributos semânticos existentes; crie novos apenas quando houver benefício concreto e um uso definido. Isso ajuda a manter a instrumentação mais consistente e útil para consultas e análises.
Quais campos ajudam a correlacionar chamadas
Adicione os atributos semânticos que se aplicam e estão disponíveis na instrumentação. Eles ajudam a identificar o agente, a operação e as chamadas de modelo ou ferramenta relacionadas:
gen_ai.operation.name: ação, comoinvoke_agent,planouexecute_tool.gen_ai.agent.name,gen_ai.agent.idegen_ai.agent.version: identificação e versão do agente, quando conhecidas.gen_ai.provider.nameegen_ai.request.model: provedor que a instrumentação identifica e modelo solicitado.gen_ai.conversation.id: correlação de operações associadas à mesma conversa.gen_ai.tool.name,gen_ai.tool.typeegen_ai.tool.call.id: contexto da execução de ferramenta.error.type: tipo de falha, usando valores de baixa cardinalidade quando a operação termina em erro.
IDs de agentes hospedados podem ser persistentes; IDs de instâncias em memória podem ser transitórios. Além disso, gen_ai.provider.name representa o que a instrumentação sabe sobre o endpoint ou a configuração e pode identificar um proxy ou uma plataforma, não necessariamente o fornecedor final a montante.
Mantenha os nomes dos spans estáveis e de baixa cardinalidade. Não inclua neles IDs de conversa, usuários ou chamadas: esses valores variáveis pertencem a atributos. Quando decisões de amostragem dependem de um atributo, disponibilize-o no início do span, sempre que possível.
Como combinar traces e métricas
Traces são úteis para reconstruir uma execução individual; métricas mostram distribuições e tendências em muitas execuções. A convenção define gen_ai.client.operation.duration para a duração de operações do cliente e também descreve métricas de streaming para o tempo até o primeiro chunk e o intervalo entre chunks de saída. Os nomes e detalhes dessas métricas podem ser consultados na documentação de métricas GenAI.
| Medida | Fronteira observada | Uso |
|---|---|---|
| Duração do workflow | Execução ponta a ponta, que pode reunir vários agentes ou outras operações. | Acompanhar o tempo total percebido para concluir o workflow. |
gen_ai.client.operation.duration |
Uma operação individual do cliente voltada ao provedor. | Entender a duração das chamadas isoladas ao provedor. |
| Tempo até o primeiro chunk | Resposta em streaming, do início da operação até o primeiro chunk de saída. | Acompanhar quando a saída começa a chegar. |
| Tempo entre chunks | Intervalos entre chunks de saída em uma resposta em streaming. | Acompanhar o ritmo de entrega da saída após o primeiro chunk. |
Não compare essas medidas como se tivessem a mesma fronteira: a duração total de um workflow inclui mais do que uma única chamada ao provedor, enquanto as métricas de streaming descrevem aspectos específicos da resposta.
Uma sequência prática para instrumentar o fluxo
- Desenhe as fronteiras reais. Liste invocação, planejamento, inferência, ferramentas e workflow; identifique quais operações têm duração significativa e quais são apenas ocorrências pontuais.
- Escolha o sinal para cada parte. Use spans para operações com início e fim relevantes, eventos para ocorrências com horário próprio e atributos para contexto que descreve a operação.
- Defina nomes e contexto. Use os nomes de operação semânticos quando aplicáveis, mantenha-os estáveis e de baixa cardinalidade e inclua atributos de agente, provedor, modelo, conversa e ferramenta conforme a disponibilidade.
- Separe métricas por fronteira. Acompanhe workflow, operação do cliente e tempos de streaming como medidas distintas, sem inferir que uma representa as outras.
- Valide o que a biblioteca realmente emite. Compare nomes, tipos de span e atributos com as convenções atuais e com o backend escolhido; não presuma que uma biblioteca implemente todas as convenções.
- Revise a coleta de conteúdo. Comece com metadados operacionais e habilite payloads somente quando houver necessidade e controles apropriados de acesso e retenção.
Como evitar registrar prompts e dados sensíveis
Mensagens de entrada e saída, instruções de sistema, argumentos e resultados de ferramentas podem conter dados pessoais, segredos ou outros conteúdos sensíveis. As convenções tratam argumentos e resultados de ferramentas como conteúdo opcional em spans de agente, e a documentação de eventos alerta para riscos semelhantes em conteúdo GenAI. Algumas instrumentações oferecem filtragem ou truncamento; verifique se a opção existe e como funciona na biblioteca utilizada. As orientações gerais estão na visão geral das convenções GenAI e nas convenções de eventos GenAI.
Uma abordagem prudente é instrumentar primeiro estados e metadados operacionais, sem conteúdo completo. Se for necessário coletar prompts ou payloads para diagnóstico, limite a coleta ao caso de uso, aplique filtros ou truncamento quando disponíveis e defina controles de acesso e retenção. Isso é uma precaução de projeto, não uma garantia ou exigência jurídica das convenções.
O que verificar antes de padronizar
Em 2 de outubro de 2026, a página de convenções para agentes e frameworks indica status Development. Nomes, requisitos e atributos podem evoluir. O repositório GenAI separa convenções de agentes, clientes, MCP, provedores, eventos e métricas, e associa a documentação legível por pessoas a definições YAML; a intenção é favorecer nomes consistentes entre bibliotecas, código e plataformas, não garantir suporte universal.
Antes de comparar emissores ou fixar uma receita, confirme a página atual de spans de agente, consulte o repositório das convenções OpenTelemetry GenAI e teste a instrumentação e o backend específicos do seu ambiente. A orientação da OpenTelemetry sobre fronteiras e atributos está em como escrever convenções semânticas.
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.
