OpenTelemetry no Claude: como rastrear agentes de IA
O OpenTelemetry no Claude permite enviar traces de agentes, chamadas de modelo e uso de ferramentas para qualquer plataforma de observabilidade compatível. Com isso, você acompanha cada passo que um agente executa, desde o primeiro prompt até a resposta final.
A novidade chegou em beta pública em outubro de 2026 e cobre o Claude Managed Agents, a Messages API e os SDKs do Claude. Além disso, quem já envia traces do Claude Code ou do Cowork para uma ferramenta de observabilidade pode reunir tudo no mesmo lugar.
Neste artigo, você entende como o recurso funciona, quais são as duas formas de configurar o rastreamento e como ler os traces gerados. Por fim, vemos os cuidados com conteúdo sensível, contagem de tokens e limites de entrega.
O que é o OpenTelemetry no Claude
O OpenTelemetry é um padrão aberto e neutro para coletar traces, métricas e logs de aplicações. Na prática, ele define como os dados de telemetria são descritos e transportados, sem amarrar você a um fornecedor específico.
O OpenTelemetry no Claude aplica esse padrão às requisições que você faz para a plataforma da Anthropic. Assim, cada turno de agente, cada chamada de modelo e cada uso de ferramenta vira um trace padrão, com latência, tokens e identificadores.
Antes desse recurso, quem queria observar um agente precisava instrumentar tudo manualmente. Por isso, era comum ver equipes criando wrappers próprios em volta das chamadas da API, cada uma com nomes e atributos diferentes.
Agora a própria plataforma emite os spans. Dessa forma, você ganha uma visão consistente do comportamento do agente sem escrever código de instrumentação para cada chamada.
Por que rastrear agentes de IA
Um agente de IA não faz uma única chamada HTTP e termina. Ele raciocina, chama ferramentas, consulta servidores MCP e volta ao modelo várias vezes até concluir a tarefa.
Quando algo dá errado nesse fluxo, um log solto no terminal não ajuda muito. Afinal, você precisa saber qual passo falhou, quanto tempo cada etapa levou e quantos tokens foram gastos em cada chamada.
A Anthropic resume bem a ideia: confiar mais em um agente começa por rastrear suas chamadas de modelo, ferramentas e servidores MCP. Em seguida, você revisa os traces e amplia o acesso do agente à medida que ele prova ser confiável.
Esse raciocínio conversa diretamente com a ideia de agent experience e como medir a eficácia de agentes. Ou seja, sem dados reais de execução, qualquer melhoria vira palpite.
Na prática, os traces resolvem três problemas comuns:
- Encontrar o passo lento ou com falha dentro de uma execução longa.
- Acompanhar o gasto de tokens e a latência ao longo do tempo.
- Transformar execuções reais de produção em avaliações, as famosas evals.
Traces, spans e as convenções GenAI
Antes de configurar qualquer coisa, vale alinhar dois conceitos. Um trace é o registro completo de uma requisição passando pelo seu sistema.
Já um span representa um passo dentro desse trace, como uma requisição ao modelo ou o uso de uma ferramenta. Os spans se aninham, então um span pai pode conter vários spans filhos.
Os traces do OpenTelemetry no Claude seguem as convenções semânticas GenAI do OpenTelemetry. Essas convenções padronizam nomes de atributos como gen_ai.usage.input_tokens, gen_ai.conversation.id e gen_ai.tool.name.
Por causa disso, dados do Claude e de outros provedores funcionam nos mesmos dashboards. Então, se a sua empresa usa mais de um modelo, você consegue comparar latência e custo lado a lado.
Além dos atributos gen_ai.*, a plataforma acrescenta atributos próprios com o prefixo anthropic.*. Por exemplo, anthropic.session.id agrupa todos os spans de uma sessão do Managed Agents.
Duas formas de usar o OpenTelemetry no Claude
Existem dois caminhos para ativar o OpenTelemetry no Claude, e eles se complementam. O primeiro é o tracing pelo SDK, e o segundo é o tracing pela API, configurado no Claude Console.
Você pode usar só um deles ou os dois juntos. Quando combina os dois, o span do SDK e o span da API de uma mesma requisição aparecem no mesmo trace.
Tracing pelo SDK do Claude
No tracing pelo SDK, a sua aplicação emite os spans e o exportador OpenTelemetry da própria aplicação envia esses dados para a plataforma de observabilidade. Portanto, não há nenhuma configuração no Console.
Esse modo não exige permissão de administrador e funciona em qualquer nuvem. Além disso, ele captura algo que a API não vê: as ferramentas customizadas que o tool runner executa dentro da sua aplicação.
Os SDKs de Python, TypeScript, C#, Go, Java, PHP e Ruby já emitem spans. Basta registrar um tracer provider antes da primeira chamada, porque o SDK usa o provider que a aplicação registrou.
Tracing pela API com um destino no Console
No tracing pela API, a própria Claude Platform emite os spans e os envia para um destino que você cadastra no Console. Assim, você não precisa mudar uma linha do código da aplicação.
Esse modo cobre qualquer cliente, inclusive chamadas feitas com cURL ou bibliotecas HTTP genéricas. Por outro lado, ele exige o papel de administrador na organização do Console para criar destinos.
O tracing pela API também mostra detalhes internos que o SDK não enxerga. Por exemplo, ele registra cada rodada do modelo dentro de uma requisição, as ferramentas de servidor e os turnos do Managed Agents.
Como configurar o OpenTelemetry no Claude passo a passo
Agora vamos colocar o OpenTelemetry no Claude para funcionar. Os exemplos usam Python, mas a documentação oficial traz o mesmo fluxo para as outras linguagens suportadas.
Registrar o tracer provider
Primeiro, atualize o SDK do Claude e instale o SDK do OpenTelemetry. O exportador de console ajuda a ver os spans antes de conectar uma plataforma real.
pip install --upgrade anthropic
pip install opentelemetry-sdk
Em seguida, registre um tracer provider e faça uma chamada comum. O código da chamada não muda, porque o SDK detecta o provider registrado.
from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
# Registra um tracer provider que imprime cada span no console
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
client = Anthropic()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)
O console mostra um span chamado anthropic.messages.create. Depois, troque o exportador de console por um exportador OTLP que aponte para a sua plataforma de observabilidade.
Também dá para ajustar o comportamento do SDK com opções no código ou variáveis de ambiente. Veja um exemplo que liga o conteúdo completo e agrupa chamadas em uma conversa:
# Usa um tracer provider específico e registra o conteúdo dos prompts
client = Anthropic(
open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)
# Desliga os spans para um cliente específico
quiet_client = Anthropic(open_telemetry=False)
# Agrupa várias chamadas em uma mesma conversa
message = client.with_options(
open_telemetry={**client.open_telemetry, "conversation_id": "conv_42"}
).messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
O conversation_id vai para o atributo gen_ai.conversation.id nos dois modos de conteúdo. Por isso, nunca coloque dados pessoais ou segredos nesse identificador.
Adicionar um destino no Claude Console
Para o tracing pela API, você precisa de um endpoint OTLP/HTTP com codificação protobuf, em HTTPS na porta 443. Também precisa das credenciais desse endpoint, como uma API key.
No Console, abra a página de configurações de OpenTelemetry da organização e clique em Add destination. Depois, preencha os campos principais:
- Provider: a sua plataforma ou Custom, caso ela não esteja na lista.
- OTLP endpoint URL: a URL base do endpoint, sem o sufixo
/v1/traces. - Request headers: os cabeçalhos de autenticação, como a API key da plataforma.
- Content mode: metadados apenas ou conteúdo completo.
- Workspaces: todos, apenas os selecionados ou todos exceto alguns.
Em seguida, use a opção Test do destino e confira se o span anthropic.test chegou. Na sua plataforma, filtre por service.name igual a claude-platform para encontrar os spans da API.
Quem prefere automação também pode criar o destino pela Admin API:
import anthropic
client = anthropic.Anthropic()
# Cria um destino de telemetria para todos os workspaces
destination = client.beta.organization.telemetry_destinations.create(
endpoint_url="https://gateway.example.com/otlp",
headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
traces={"content_mode": "metadata_only"},
workspaces={"type": "all"},
)
print(destination.id)
Conectar os spans da API aos seus traces
Por padrão, os spans da API ficam em traces próprios. Para aninhá-los nos traces da sua aplicação, chame o SDK de dentro de um span seu.
from opentelemetry import trace
tracer = trace.get_tracer("my-service")
# O span da aplicação passa a conter o span do SDK e o span da API
with tracer.start_as_current_span("summarize_issues"):
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}],
},
],
)
A API lê o contexto do cabeçalho W3C traceparent. Quando o sampled flag desse cabeçalho está desligado, a API não emite os spans daquela requisição.
Além disso, a Messages API repassa o traceparent para o seu servidor MCP no campo params._meta. Dessa forma, o servidor pode pendurar os próprios spans debaixo dos spans da API.
Content modes do OpenTelemetry no Claude
Cada destino e cada cliente do SDK têm um content mode. Ele define se os spans incluem ou não os prompts e as respostas do modelo.
O modo padrão é Metadata only, ou metadata_only no SDK. Nesse caso, os spans trazem identificadores, tempos, status e contagem de tokens, mas não o texto das conversas.
Já o modo Full content, ou content no SDK, inclui prompts e respostas completos. Com ele, você lê conversas inteiras, entende por que uma execução falhou e cria evals a partir de tráfego real.
Contudo, esse modo exige cuidado com privacidade. A plataforma de observabilidade guarda o conteúdo sob as próprias regras de acesso e retenção, então revise essas regras antes de ativar.
O OpenTelemetry no Claude também respeita restrições contratuais. Organizações com restrições de HIPAA, FERPA ou K-12 exportam apenas metadados pelos destinos, mesmo com Full content configurado.
Cada span guarda até 0,75 MB de conteúdo por padrão. Quando o conteúdo passa do limite, a plataforma corta o excesso e marca o atributo anthropic.content.truncated como verdadeiro.
Como ler um trace do OpenTelemetry no Claude
Configurar é só metade do trabalho. Na outra metade, você precisa entender a hierarquia dos spans para encontrar a informação certa.
Uma requisição na Messages API
Imagine uma aplicação que chama o tool runner dentro de um span answer_question. O tool runner gera o span anthropic.messages.tool_runner, que contém as requisições ao modelo.
Cada requisição aparece duas vezes com o mesmo nome, anthropic.messages.create. O span do SDK tem o kind CLIENT, enquanto o span da API tem o kind SERVER.
Dentro do span da API surgem os spans anthropic.model_request, um para cada rodada do modelo. Quando a API executa uma ferramenta de servidor, como a busca na web, aparece também um span anthropic.tool_use.
Se o modelo pede uma ferramenta customizada, o SDK executa essa ferramenta e cria o span anthropic.custom_tool_use. Logo depois, uma nova requisição leva o resultado de volta ao modelo.
Com Full content, o prompt de sistema fica em gen_ai.system_instructions. As mensagens de entrada ficam em gen_ai.input.messages, e a resposta fica em gen_ai.output.messages.
Uma sessão do Managed Agents
No Managed Agents, cada requisição à Sessions API gera um span, e cada turno do agente gera um span anthropic.session.turn. Dentro do turno ficam as requisições ao modelo e as ferramentas que a API executa, como o bash.
Quando o agente pede uma ferramenta customizada, o turno termina com o stop reason requires_action. Em seguida, a sua aplicação executa a ferramenta e envia o resultado, o que abre um novo turno.
Se você ainda não conhece esse serviço, vale ler o artigo sobre como criar automações confiáveis com Claude Managed Agents. Ele explica sessões, memória e limites de gasto, que se conectam bem com os traces.
Os spans de uma sessão podem se espalhar por vários traces. Para reunir uma thread, agrupe os spans por gen_ai.conversation.id e ordene por horário de início.
Já para ver a sessão inteira, com todas as threads, agrupe por anthropic.session.id. Assim, você lê o histórico completo do agente como uma transcrição.
Contagem de tokens sem duplicidade
Um erro comum ao montar dashboards de custo é somar tokens duas vezes. Isso acontece porque alguns atributos de uso se repetem em mais de um nível de span.
A regra é simples: some os spans de apenas uma origem por requisição. Quando existem span do SDK e span da API, prefira os spans da API.
Para requisições da Messages API, some os spans anthropic.messages.create do lado SERVER ou os spans anthropic.model_request, nunca os dois. Já em sessões do Managed Agents, some os spans anthropic.model_request e anthropic.session.outcome_evaluation.
Lembre também que gen_ai.usage.input_tokens já inclui os tokens lidos e gravados no cache de prompt. Portanto, não some os atributos de cache a esse valor.
Por fim, os spans podem chegar mais de uma vez, por exemplo em uma nova tentativa de entrega. Então, remova duplicidades usando o trace ID e o span ID.
Ferramentas compatíveis com o OpenTelemetry no Claude
O OpenTelemetry no Claude funciona com qualquer ferramenta que aceite um endpoint OTLP padrão. Mesmo assim, a Anthropic destaca parceiros com integração já documentada.
Para depurar agentes junto ao resto da stack, Grafana Cloud, Honeycomb, Sentry e Splunk colocam os traces ao lado dos seus logs e métricas. Dessa forma, você descobre de qual serviço veio um passo lento ou com falha.
Para melhorar agentes com dados de produção, Arize AI, Braintrust, Datadog, Langfuse, LangSmith, New Relic e PostHog transformam traces reais em evals. Assim, fica mais fácil detectar problemas de qualidade e medir se uma mudança ajudou.
Já para acompanhar o uso na organização inteira, o Databricks Unity Gateway mostra o consumo de tokens por equipe. Com isso, os times de plataforma e segurança conseguem sinalizar atividades fora do padrão.
Se você trabalha com .NET, também pode usar um OpenTelemetry Collector próprio e encaminhar os dados para o backend que já usa. Nesse caso, configure o receiver para aceitar HTTPS na porta 443 ou coloque um proxy reverso na frente.
Limites e boas práticas do OpenTelemetry no Claude
A entrega dos spans pela API é do tipo best effort e at least once. Ou seja, um span pode se perder e outro pode chegar duplicado.
Por isso, os traces não substituem o controle oficial de consumo. Para auditar o uso de cada API key, a documentação recomenda a Usage API, que conta inclusive requisições sem spans.
O endpoint precisa responder rápido, porque cada entrega expira após 10 segundos no total. Além disso, a API desativa um destino que responde com redirecionamento ou que falha por 24 horas seguidas.
Cada organização pode ter até 10 destinos, contando os desativados. Cada destino aceita até 20 cabeçalhos e até 1.000 workspaces selecionados.
Durante a beta, nomes de spans, atributos e opções do SDK podem mudar. Então, fixe a versão do SDK nas dependências para decidir quando adotar as mudanças.
Algumas práticas ajudam a tirar mais proveito do recurso:
- Comece com Metadata only e só ative Full content depois de revisar a retenção da plataforma.
- Separe workspaces de desenvolvimento e produção com destinos diferentes.
- Envolva cada fluxo de negócio em um span próprio para ligar o agente à funcionalidade.
- Monte dashboards de custo somando apenas uma origem de spans por requisição.
Conclusão
O OpenTelemetry no Claude tira a observabilidade de agentes do improviso e a coloca em um padrão aberto. Com ele, cada turno, chamada de modelo e ferramenta vira um span que qualquer plataforma compatível entende.
O caminho mais completo combina os dois modos. O SDK mostra o que acontece dentro da aplicação, enquanto a API revela o que acontece dentro da Claude Platform.
Na prática, comece pelo exportador de console, conecte um destino de teste e evolua para dashboards de custo e latência. Depois, use os traces reais para criar evals e ampliar o acesso dos seus agentes com segurança.
Como o recurso está em beta, acompanhe a documentação oficial de OpenTelemetry da Claude Platform. Assim, você evita surpresas quando nomes de spans ou opções mudarem.
FAQ
O OpenTelemetry no Claude é pago?
A documentação não cita custo extra para exportar traces. Você paga normalmente pelo uso da API e pela plataforma de observabilidade que recebe os dados.
Preciso mudar meu código para usar o tracing pela API?
Não. Basta um administrador cadastrar um destino no Claude Console, e a plataforma passa a enviar os spans das requisições.
O SDK de C# também emite spans?
Sim. A documentação lista C# entre os SDKs com suporte, ao lado de Python, TypeScript, Go, Java, PHP e Ruby.
Os prompts aparecem nos traces por padrão?
Não. O modo padrão é Metadata only, e os prompts só aparecem quando você ativa o modo Full content.
Funciona com Claude Platform on AWS?
Sim, os dois modos funcionam. Porém, nesse ambiente os spans da API sempre começam traces próprios, porque o cabeçalho traceparent ainda não é suportado.