Use o OpenTelemetry com o Claude SDK

Com o OpenTelemetry, o Claude SDK pode emitir um span (intervalo) para cada requisição que envia e para cada uso de ferramenta que o tool runner executa. Você pode visualizar esses spans na sua plataforma de observabilidade, aninhados nos seus próprios traces.

O SDK emite spans na sua aplicação. O exportador do OpenTelemetry da sua aplicação os envia para a sua plataforma de observabilidade.

1. Instale o SDK

Instale ou atualize para a versão mais recente do Claude SDK:

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. Registre um tracer provider

Um tracer provider (provedor de tracer) é o objeto do OpenTelemetry que cria spans e os repassa ao seu exportador. O SDK usa o tracer provider que a sua aplicação registra, então suas chamadas ao SDK permanecem as mesmas. Registre-o antes da primeira chamada que você deseja rastrear.

O exemplo a seguir registra um tracer provider que imprime cada span no console e, em seguida, faz uma chamada. Use-o para ver os spans antes de conectar uma plataforma de observabilidade:

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 anthropic.messages.create.

3. Envie os spans para a sua plataforma de observabilidade

Substitua o exportador de console por um exportador OTLP que aponte para a sua plataforma de observabilidade. Para a configuração na sua linguagem, consulte a documentação do OpenTelemetry sobre exportadores para Python, exportadores para TypeScript, exportadores para .NET, exportadores para Go, configuração do SDK para Java, exportadores para PHP, ou exportadores para Ruby.

4. Configure o SDK

Use as opções a seguir para decidir o que entra nos seus spans e para onde eles são enviados. Você pode definir uma opção no seu código ou, se ela tiver uma, com a variável de ambiente indicada abaixo do nome dela.

O exemplo a seguir mostra como usar cada opção:

# Use um tracer provider específico e registre o conteúdo.
# Definir open_telemetry substitui todas as variáveis de ambiente ANTHROPIC_OPEN_TELEMETRY*.
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# Desative os spans para um cliente.
quiet_client = Anthropic(open_telemetry=False)

# Defina um ID de conversa com with_options(), que retorna uma cópia do cliente.
# with_options() substitui a opção inteira, então comece a partir de client.open_telemetry.
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"}],
)

Próximos passos

Rastreamento de um stream

O span anthropic.messages.create de um stream termina quando o seu código leu o stream inteiro ou o fechou, então feche um stream que você parar de ler antes do fim. No modo de conteúdo, o span contém a resposta do modelo somente quando você lê o stream com messages.stream().

Os spans que você inicia enquanto lê um stream são irmãos do span do SDK, não filhos dele. Para agrupá-los com a requisição, inicie seu próprio span envolvendo tanto a chamada quanto o loop de leitura.

Rastreamento de um sandbox auto-hospedado do Managed Agents

Em um sandbox auto-hospedado do Managed Agents, é o seu sandbox que executa as ferramentas, então os spans das ferramentas vêm do SDK em vez da API. O worker de ambiente dos SDKs para Python, TypeScript e Go emite um span para cada ferramenta que executa e para cada requisição que envia. Ele os agrupa sob um span anthropic.environment.work para cada item de trabalho.

Para obter esses spans:

1. No processo que executa o worker, configure o rastreamento do SDK conforme as etapas 1 a 4.
2. Permita o tráfego de rede do sandbox para a sua plataforma de observabilidade ou o seu OpenTelemetry Collector.

Quando o worker envia um resultado de ferramenta, o span da API dessa requisição fica aninhado sob o span do SDK dela. Para requisições que o worker envia ao Claude Platform on AWS, os spans da API ficam em traces próprios.

Contexto de trace e baggage

Em cada requisição, o SDK usa o propagador da sua aplicação para enviar o contexto de trace para a API em cabeçalhos como traceparent. Se esse propagador também gravar baggage, o SDK envia também o seu baggage. Para enviar o contexto de trace sem baggage, registre apenas o propagador de contexto de trace W3C.

Para que o SDK não envie esses cabeçalhos, por exemplo quando a instrumentação do seu cliente HTTP já os envia, desative a propagação do SDK:

client = Anthropic(open_telemetry={"propagation": False})

Enquanto o SDK chama uma ferramenta MCP, o span da ferramenta do SDK é o span atual. Algumas bibliotecas cliente de MCP enviam o contexto de trace ao servidor MCP em _meta, de modo que um servidor que o leia pode adicionar seus spans ao seu trace sob esse span de ferramenta. O pacote mcp do Python a partir da versão 2.0 e o pacote ModelContextProtocol do C# fazem isso. Os SDKs de MCP para TypeScript, Go, Java, Ruby e PHP não fazem isso por conta própria.

Solução de problemas

Compatibility