Use o OpenTelemetry com a Claude API

Com o OpenTelemetry, a Claude API pode emitir um span (intervalo) para cada requisição ao modelo e para cada uso de ferramenta que ela executa. Você pode visualizar esses spans na sua plataforma de observabilidade sem alterar o seu código.

A API emite spans para as suas requisições à Messages API e para as sessões do Managed Agents. Para recebê-los, adicione um destination (destino) no Claude Console. Um destino informa à API o endpoint OTLP da sua plataforma de observabilidade e como se autenticar nele.

O que você precisa

• A função de administrador em uma organização do Claude Console, para adicionar e alterar destinos. Com a função de desenvolvedor, você pode visualizá-los. Se a sua organização estiver no Claude Platform on AWS, faça login no Console pelo AWS Console, conforme descrito em Fazendo login.
• Um endpoint OTLP/HTTP que aceite codificação protobuf em uma URL HTTPS na porta 443. Se você executa seu próprio OpenTelemetry Collector, o receptor OTLP/HTTP dele escuta na porta 4318 por padrão. Configure o receptor para aceitar HTTPS na porta 443 ou coloque um balanceador de carga ou proxy reverso na frente do Collector.
• Credenciais para o endpoint, como uma chave de API.

1. Adicione um destino

1. No Console, abra a página de configurações do OpenTelemetry da sua organização e clique em Add destination.

2. Configure o destino:

   Campo	O que inserir
   Provider	A sua plataforma de observabilidade, ou Custom se ela não estiver listada. Se escolher uma plataforma listada, o Console solicita os detalhes dela, como uma chave de API, em vez de OTLP endpoint URL, Request headers e OTLP traces endpoint URL.
   Name	Opcional. Por exemplo, "Plataforma de observabilidade da Acme."
   OTLP endpoint URL	A URL HTTPS base do endpoint OTLP/HTTP da sua plataforma de observabilidade, com um nome de host, não um endereço IP. Ela pode ter um prefixo de caminho, por exemplo https://gateway.example.com/otlp. Não adicione /v1/traces, pois a API o adiciona. Se você definir uma OTLP traces endpoint URL, a API usará essa URL em vez disso.
   Request headers	Os cabeçalhos que a API envia com cada requisição, por exemplo o cabeçalho de chave de API da sua plataforma de observabilidade. Coloque credenciais somente nos valores dos cabeçalhos. Depois que você salva, o Console não mostra os valores novamente.
   Content mode	Metadata only ou Full content. Veja como os modos de conteúdo diferem.
   Workspaces	Os workspaces cujos spans o destino recebe: All, Selected ou All except. Consulte Escolha os workspaces de um destino.
   OTLP traces endpoint URL	Opcional, em Advanced settings. A URL completa do endpoint de traces da sua plataforma de observabilidade, por exemplo https://gateway.example.com/custom/traces. Defina-a quando a plataforma receber traces em uma URL diferente da OTLP endpoint URL acrescida de /v1/traces. Ela deve ter o mesmo host que a OTLP endpoint URL.
   Maximum content size in MB	Opcional, em Advanced settings quando o modo de conteúdo é Full content. A quantidade máxima de conteúdo que a API envia em cada span. O Console o preenche com base no Provider que você escolher. Altere-o para se adequar ao que a sua plataforma de observabilidade aceita. Deixe-o vazio para enviar o máximo que a API permite. Consulte Limites de conteúdo.

3. Clique em Add destination para salvar.

4. Clique em Test no menu More actions do destino. Você verá uma mensagem informando que o span de teste foi entregue ao seu coletor ou como a entrega falhou (consulte Erros de entrega).

5. Verifique se o span anthropic.test chegou à sua plataforma de observabilidade.

Admin API e CLI

Você também pode adicionar um destino com a Admin API em vez do Console. Faça login na CLI como administrador ou use uma chave da Admin API em ANTHROPIC_API_KEY. No Claude Platform on AWS, envie as requisições para https://aws-external-anthropic.{region}.api.aws em vez disso, assinadas com as suas credenciais da AWS, como em Fazendo requisições. Nesse caso, a sua política do IAM decide quem pode gerenciar destinos. Uma requisição pode incluir somente os workspaces da sua conta da AWS nessa Região.

client = anthropic.Anthropic()

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)

Uma solicitação de criação aceita as configurações do Console, exceto Provider, então insira você mesmo a URL do endpoint e os cabeçalhos da sua plataforma de observabilidade. Defina traces.max_content_bytes, em bytes, para se adequar ao que a sua plataforma de observabilidade aceita (veja Limites de conteúdo). Para listar, alterar ou excluir destinos, ou para adicionar ou remover um workspace, use os outros métodos da API de destinos de telemetria.

2. Escolha os workspaces de um destino

Um destino recebe os spans dos workspaces que ele abrange. Escolha-os ao adicionar o destino. Em Workspaces, selecione uma das seguintes opções:

• All: Todos os workspaces da organização, incluindo o Default Workspace e os workspaces criados posteriormente.
• Selected: Somente os workspaces que você selecionar.
• All except: Como All, mas sem os workspaces que você selecionar.

Para Selected ou All except, selecione os workspaces na caixa de pesquisa que aparece abaixo das opções. Para alterar os workspaces de um destino posteriormente, abra o menu More actions dele na página de configurações do OpenTelemetry enquanto o filtro Workspace mostra All. Clique em Edit e, em seguida, escolha outra opção de Workspaces ou altere os workspaces na caixa de pesquisa.

Se você tiver a função de desenvolvedor na organização e a função Workspace Admin em um workspace, poderá adicionar esse workspace a um destino Selected ou removê-lo desse destino. Defina o filtro Workspace para esse workspace e, em seguida, abra o menu More actions do destino. No Claude Platform on AWS, o Console não tem a função Workspace Admin. Nele, é a sua política do IAM que determina quem pode adicionar um workspace a um destino ou removê-lo dele.

A API envia spans para todos os destinos habilitados que cobrem o workspace em que a requisição ou sessão é executada.

3. Verifique se os spans chegam

1. No Console, selecione um workspace coberto pelo destino e envie uma requisição à Messages API no playground. Você também pode enviar uma requisição à Messages API a partir da sua aplicação ou iniciar uma sessão do Managed Agents nesse workspace. Para iniciar uma sessão, você pode seguir as etapas em Primeiros passos com o Claude Managed Agents.
2. No Console, na página de configurações do OpenTelemetry, verifique se a coluna Delivery do destino mostra Healthy. Isso pode levar cerca de um minuto.
3. Na sua plataforma de observabilidade, filtre por service.name = claude-platform para encontrar os spans da requisição.

Se a coluna mostrar Failing, passe o ponteiro sobre ela para ver o último erro. Para encontrar a causa provável, consulte Erros de entrega.

4. Conecte os spans da API aos seus próprios traces

Por padrão, os spans da API de uma requisição à Messages API ou de uma sessão do Managed Agents ficam em traces próprios. Conecte-os aos traces da sua aplicação para que fiquem aninhados sob os seus próprios spans.

A API lê o contexto de trace de cada requisição a partir do cabeçalho traceparent do W3C. Se a flag de amostragem no cabeçalho estiver desativada, a API não emite o span da requisição nem os spans abaixo dele. O Claude Platform on AWS ainda não oferece suporte a esse cabeçalho. Os spans das requisições que você envia a ele sempre iniciam traces próprios, mesmo quando a flag de amostragem está desativada.

from opentelemetry import trace

tracer = trace.get_tracer("my-service")

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"}],
            },
        ],
    )

import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "managed-agents-2026-04-01",
    "content-type": "application/json",
}
# Copia o contexto de trace do span ativo para os cabeçalhos da requisição.
TraceContextTextMapPropagator().inject(headers)

httpx2.post(
    f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
    headers=headers,
    json={
        "events": [
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    },
)

A Messages API também repassa o trace para o seu servidor MCP quando você o conecta com o conector MCP, para que ele possa colocar os seus próprios spans sob os spans da API. Cada requisição e notificação que a API envia ao seu servidor MCP tem um traceparent do W3C em params._meta. Em uma requisição tools/call, ele referencia o span anthropic.mcp_tool_use desse uso de ferramentas. Nas outras mensagens, ele referencia o span anthropic.messages.create. Para uma requisição que a API não rastreia, como uma cujo cabeçalho traceparent tem o sinalizador de amostragem desativado, a API não envia nenhum traceparent.

Próximos passos

Entrega e integridade

As regras a seguir se aplicam aos spans que a API envia para os seus destinos.

• Pelo menos uma vez: Um destino pode receber o mesmo span mais de uma vez. Para remover duplicatas, use o ID do trace e o ID do span.
• Melhor esforço: Um span pode ser perdido antes da entrega. A API não consegue enviar novamente um span perdido.
• Compressão: A API comprime a primeira requisição de cada entrega com gzip e define o cabeçalho Content-Encoding: gzip. Se o seu endpoint responder a essa requisição com uma resposta 400 ou 415, a API envia os mesmos spans novamente de imediato, sem compressão.
• Novas tentativas: A API tenta a entrega novamente mais tarde, um número limitado de vezes, após um timeout, uma falha de conexão, TLS ou DNS, ou uma resposta 408, 429 ou 5xx. Ela não tenta novamente em outras falhas.
• Timeouts: Para cada requisição, o seu endpoint deve concluir o handshake TLS em até 5 segundos e enviar os cabeçalhos de resposta em até 5 segundos. Cada entrega expira após 10 segundos no total, incluindo o reenvio sem compressão.
• User agent: Cada requisição tem o cabeçalho User-Agent: Claude-Platform.

A coluna Delivery mostra o estado de cada destino. O estado pode ter até um minuto de atraso.

A API desabilita um destino quando:

• O endpoint envia um redirecionamento 3xx.
• O nome de host do endpoint é resolvido para um endereço IP que não é público.
• Todas as entregas falham por 24 horas.

A API não envia spans para um destino desativado. Para retomar a exportação, corrija a causa. Em seguida, com o filtro Workspace na página de configurações do OpenTelemetry mostrando All, clique em Enable no menu More actions do destino. A exportação recomeça em cerca de um minuto.

Para alterar um destino, abra seu menu More actions enquanto o filtro Workspace mostra All. Em seguida, clique em Edit, Disable, Enable ou Delete. Se você alterar o host da OTLP endpoint URL, insira os valores dos cabeçalhos novamente. Se o destino tiver uma OTLP traces endpoint URL, atribua a ela o mesmo novo host ou limpe-a.

Limites

Solução de problemas

Erros de entrega

Quando uma entrega falha, a coluna Delivery mostra Failing. Passe o ponteiro sobre esse estado para ver o erro e, em seguida, identifique a causa provável:

Compatibility