Phase 13: Tools & Protocols

OpenTelemetry GenAI Ferramenta de rastreamento ligações de ponta a ponta

Type: Build

Languages: Python (stdlib, OTel span emitter)

Prerequisites: Phase 13 · 07 (MCP server), Phase 13 · 08 (MCP client)

Time: ~75 minutes

Objetivos de aprendizagem

• Nomear os atributos OTel GenAI necessários para um período de MLL e um período de execução de ferramentas.
• Construir uma hierarquia de rastreamento que cobre o loop de agente, chamada de LLM, chamada de ferramenta e despacho de cliente MCP.
• Decidir qual conteúdo capturar (opt-in) versus editar (default).
• Emite extensões para um colecionador local (Jaeger, Langfuse) sem reescrever o código da ferramenta.

O problema

Um erro de erro de fevereiro de 2026: o usuário relata "meu agente às vezes leva 30 segundos para responder; outras vezes 3 segundos". Não há vestígios. Os registros mostram a chamada LLM, mas não o despacho de ferramenta, não a viagem de ida e volta do servidor MCP, não o sub-agente. Você adivinha. Eventualmente você descobre: um servidor MCP ocasionalmente fica pendurado em um arranque frio.

Sem rastreamento de ponta a ponta, não se consegue encontrar isto.

As convenções foram estabelecidas em 2025-2026 sob o grupo de convenções semânticas OpenTelemetry. Eles definem nomes de atributos estáveis para que Datadog, Langfuse, Phoenix, OpenLLMetry e AgentOps analisem todos os mesmos intervalos.

O conceito

Hierarquia de espa

Copyagent.invoke_agent  (top, INTERNAL span)
 ├── llm.chat       (CLIENT span)
 ├── tool.execute   (INTERNAL)
 │    └── mcp.call  (CLIENT span)
 ├── llm.chat       (CLIENT span)
 └── subagent.invoke (INTERNAL)

A coisa toda fica sob uma identificação de rastreamento.

Atributos necessários

Para o semestre 2025-2026,

• gen_ai.operation.name- Não ."chat"- Não ."text_completion"- Não ."embeddings"- Não ."execute_tool"- Não ."invoke_agent"- Não .
• gen_ai.provider.name- Não ."openai"- Não ."anthropic"- Não ."google"- Não ."azure_openai"- Não .
• gen_ai.request.model cadeia de modelos solicitada (por exemplo "gpt-4o-2024-08-06")).
• gen_ai.response.modelO modelo realmente serviu.
• gen_ai.usage.input_tokens- Não .gen_ai.usage.output_tokens- Não .
• gen_ai.response.id Identificação de resposta do prestador para correlação.

Para as extensões das ferramentas:

• gen_ai.tool.nameIdentificador de ferramenta.
• gen_ai.tool.call.id o número de chamada específico.
• gen_ai.tool.description Descrição da ferramenta (opcional).

Para os períodos de agência:

• gen_ai.agent.name- Não .gen_ai.agent.id- Não .gen_ai.agent.description- Não .

Tipos de espinha

• SpanKind.CLIENTPara chamadas que atravessam um limite de processo (provedor de MLM, servidor MCP).
• SpanKind.INTERNALpara os próprios passos do agente e a execução da ferramenta.

Captura de conteúdo de opção

Por padrão, os intervalos transportam métricas e cronometragem não pedidos ou conclusões.OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimentalA análise dos dados e os dados de conteúdo é feita com base no conteúdo de cada um dos conteúdos.

Eventos em espaços

Eventos de nível de tokens podem ser adicionados como eventos de tempo:

• gen_ai.content.prompt mensagens de entrada.
• gen_ai.content.completion mensagens de saída.
• gen_ai.content.tool_call chamada de ferramenta tal como registrada.

Eventos em ordem temporal dentro de um período para repetição detalhada.

Exportadores

A OTel abrange as exportações para:

• Jaeger / Tempo.OSS, em local.
• Langfuse.LLM-observabilidade-específico; visualiza o uso de tokens.
• Arize Phoenix.Evals + rastreamento combinado.
• Datadog.Comerciante; nativo parses gen_ai.*- Os atributos.
• Honeycomb.- A partir de uma coluna.

Todos falam OTLP, o formato de cabo.

Propagação através de MCP

Quando um cliente MCP chama um servidor, injecte o cabeçalho traceparent W3C na solicitação. Streamable HTTP suporta cabeçalhos padrão. Stdio não carrega cabeçalhos HTTP nativo; o roteiro 2026 da especificação discute adicionar um _meta.traceparentcampo em chamadas JSON-RPC.

Até que os navios: incluam o rastreador no _metaO servidor registra o rastreamento.

Metricas

Junto com os espaços, o GenAI semconv define métricas:

• gen_ai.client.token.usage Histograma.
• gen_ai.client.operation.duration Histograma.
• gen_ai.tool.execution.duration Histograma.

Use estes para painéis que não precisam de detalhes por chamada.

Equipamento de transporte

O AgentOps (fundado em 2024) é especializado em observabilidade GenAI. Envolve frameworks populares (LangGraph, Pydantic AI, CrewAI) para emitir extensões OTel automaticamente. Útil se sua pilha usa uma estrutura suportada; use instrumentação manual de outra forma.

Usá-lo

code/main.pyemite intervalos em forma de OTel para estudar (em formato OTLP-JSON) para um agente que chama um LLM, envia duas ferramentas e faz uma viagem de ida e volta de MCP. Nenhum exportador real a lição se concentra no conjunto de forma e atributos de span. Paste a saída em um visualizador compatível com OTLP ou apenas leia-o.

O que ver:

• A identificação de rastreamento é compartilhada em todos os espaços.
• Os links entre pais e filhos são codificados através de parentSpanId- Não .
• Requeridogen_ai.*Os atributos estão populados.
• A captura de conteúdo é desativada por padrão; um cenário a activa através de env var.

Envia-o

Esta lição produzoutputs/skill-otel-genai-instrumentation.md- Tendo em conta uma base de código de agentes, a competência produz um plano de instrumentação: onde adicionar os espaços, que atribui a população e quais exportadores atingir.

Exercícios

1. Corra .code/main.pyContar os intervalos e identificar qual é o CLIENTE vs. INTERNO.

1. Ativar a captura de conteúdo (env var) e confirmar gen_ai.content.promptE ...gen_ai.content.completionObserve as implicações para as PII.

1. Adicionar a métrica de execução de ferramentas gen_ai.tool.execution.durationE emitir-se como uma amostra de histograma por chamada.

1. Propagar um rastreador de um agente-mãe para um pedido de MCP _meta.traceparentVerifique se o servidor MCP veria a mesma identificação.

1. Leia a especificação OTel GenAI semconv. Identifique um atributo listado na semconv que o código desta lição NÃO emite. Adicione-o.

Termos-chave

Mais leitura

• OpenTelemetry — GenAI semconv convenções canônicas para os períodos, métricas e eventos da GenAI
• OpenTelemetry — GenAI spans Lista de atributos de MLL e de duração de execução das ferramentas
• OpenTelemetry — GenAI agent spans Nível de agente invoke_agentEspécie
• open-telemetry/semantic-conventions — GenAI spans Fonte de verdade hospedada no GitHub
• Datadog — LLM OTel semantic convention Integrar a produção

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.