AdministraçãoOpenTelemetry

OpenTelemetry para a Claude API

Copy page



Rastreie suas requisições à Messages API, usos de ferramentas e sessões do Managed Agents com spans do OpenTelemetry do Claude SDK e da Claude API.

A Claude API e o SDK podem rastrear suas requisições à Messages API, usos de ferramentas e sessões do Managed Agents com o OpenTelemetry. Você pode visualizar esses traces na plataforma de observabilidade que já possui. Use-os para depurar requisições com falha ou lentas, acompanhar o gasto de tokens e a "latency" (latência) e criar evals a partir de tráfego real. Você também pode ver cada requisição dentro dos próprios traces da sua aplicação, vinculada ao usuário ou à funcionalidade que a enviou.

O OpenTelemetry é um padrão neutro em relação a fornecedores, compatível com a maioria das plataformas de observabilidade. Um trace (rastreamento) é o registro completo de uma requisição ao longo do seu sistema. Um span (intervalo) é uma etapa em um trace, como uma requisição ao modelo ou um uso de ferramenta. A API e o SDK usam atributos das convenções semânticas de GenAI, de modo que plataformas compatíveis com essas convenções conseguem reconhecer os spans sem configuração adicional.

Primeiros passos

Você pode configurar o tracing do SDK, o tracing da API ou ambos. Configure ambos para ver os spans do SDK e da API de uma requisição em um único trace, como nos traces de exemplo. Para requisições ao Claude Platform on AWS, os spans da API ficam em traces próprios.

Para o Claude Code, o Agent SDK ou o Cowork, consulte Monitoramento do Claude Code, Observabilidade do Agent SDK ou Monitoramento de atividade do Cowork.

Enviar traces para uma plataforma parceira

Envie traces para qualquer plataforma de observabilidade que aceite OTLP, incluindo estes parceiros:

Modos de conteúdo

Cada destino e cada cliente do SDK tem um modo de conteúdo, que define se os spans incluem os prompts e as respostas do modelo. Defina-o ao adicionar um destino ou ao configurar o SDK.

• Metadata only (metadata_only no SDK): O padrão. Os spans incluem identificadores, tempos, status, contagens de tokens e textos que você escolhe, como os nomes e as descrições dos seus agentes e ferramentas e os nomes dos seus servidores MCP.
• Full content (content no SDK): Maior visibilidade. Os spans incluem os prompts e as respostas do modelo, além de tudo o que está em Metadata only.

Com Full content, você também pode ver por que uma execução falhou ou foi lenta, ler conversas completas e criar evals a partir de traces reais. Na referência de spans do OpenTelemetry, os atributos que contêm prompts e respostas são marcados com Conteúdo.

Se a sua organização tem uma restrição de tratamento de dados HIPAA, FERPA ou K-12 com a Anthropic, os destinos exportam apenas metadados, qualquer que seja o modo de conteúdo deles. Os spans do SDK não são afetados.

Com a retenção zero de dados, você ainda pode usar Full content. Para requisições da Messages API, a API mantém o conteúdo exportado apenas na memória até entregá-lo ao destino. O Claude Managed Agents não é elegível para retenção zero de dados, e sua retenção de dados permanece a mesma quando você usa OpenTelemetry.

Limites de conteúdo

Com Full content, cada span contém até 0,75 MB de conteúdo por padrão. Isso comporta uma janela de contexto de 200k tokens com texto em inglês e fica abaixo do limite de requisição de 1 MB de muitas plataformas de observabilidade e proxies. Se você escolher uma plataforma parceira como Provider, o Console define um limite que a plataforma aceita.

Quando o conteúdo ultrapassa o limite, o SDK ou a API o encurta e define anthropic.content.truncated como true. Spans de requisição removem primeiro o prompt do sistema e as mensagens mais antigas, e spans de ferramenta removem blocos a partir do fim do resultado. Imagens e documentos aparecem apenas como o tipo deles.

Altere o limite nestes casos:

• Sua plataforma de observabilidade aceita payloads maiores: Aumente ou remova o limite para manter inteiros os prompts e as respostas longos. Uma janela de contexto completa de 1M tokens precisa de cerca de 4 MB.
• Sua plataforma de observabilidade ou um proxy na frente dela rejeita requisições grandes: Diminua o limite.

No SDK, defina traces.max_content_bytes. No Console, defina Content mode como Full content ao adicionar um destino e, em seguida, defina Maximum content size in MB em Advanced settings.

Traces de exemplo e como lê-los

Uma requisição à Messages API

Sob o span da API de uma requisição que cria uma mensagem, a API adiciona um span para cada requisição ao modelo e um span de ferramenta para cada uso de uma ferramenta de servidor ou de uma ferramenta de conector MCP que a API executa.

Neste exemplo, a sua aplicação chama o tool runner, o helper do SDK que executa as suas ferramentas e envia os resultados delas de volta ao Claude. Cada requisição que o tool runner envia tem um span de cliente do SDK e um span de servidor da API. Os spans aparecem na seguinte ordem:

1. A sua aplicação inicia o span answer_question e chama o tool runner da Messages dentro dele (mostrado como o span anthropic.messages.tool_runner).
2. O tool runner envia a primeira requisição (mostrada como o primeiro span de cliente anthropic.messages.create e os spans abaixo dele). Nessa requisição, a API executa a ferramenta de busca na web entre duas requisições ao modelo.
3. Na segunda requisição ao modelo, o modelo pede para usar a ferramenta personalizada get_weather, então a primeira requisição termina.
4. O tool runner executa get_weather (mostrado como o span anthropic.custom_tool_use get_weather).
5. O tool runner envia a segunda requisição com o resultado da ferramenta (mostrada como o segundo span de cliente anthropic.messages.create e os spans abaixo dele).
6. Na segunda requisição, o modelo dá a resposta final.

O SDK na sua aplicação emite o span anthropic.messages.tool_runner, o span anthropic.custom_tool_use e o span de cliente de cada requisição. Para obter esses spans, configure o tracing do SDK.

Cada requisição tem o seu uso de tokens registrado em vários dos seus spans. Para contar cada token uma única vez, consulte Contagem de tokens.

Com Full content, o span de servidor anthropic.messages.create contém o prompt e a resposta. O prompt do sistema fica em gen_ai.system_instructions, as mensagens da requisição em gen_ai.input.messages e a resposta em gen_ai.output.messages.

Para cada span e seus atributos, consulte a referência de spans do OpenTelemetry.

Uma sessão do Managed Agents

Uma sessão tem um span para cada requisição da Sessions API e um span de turno para cada turno do agente. Um turno iniciado por uma requisição é filho do span dessa requisição. Um turno contém um span para cada requisição ao modelo e para cada ferramenta que a API executa, exceto nos casos listados na referência de spans de ferramentas. Ele também contém um span para cada avaliação de resultado.

Este exemplo acompanha uma requisição de chat, na qual sua aplicação envia uma mensagem para uma sessão e executa uma ferramenta personalizada. O trace tem spans tanto da sua aplicação quanto da API, na seguinte ordem:

1. Sua aplicação recebe uma requisição POST /chat de um usuário.
2. Sua aplicação inicia o executor de ferramentas de sessão do SDK, que lista e faz streaming dos eventos da sessão (mostrados como os spans anthropic.sessions.events.stream e anthropic.sessions.events.list).
3. Sua aplicação envia a mensagem do usuário para a sessão chamando sessions.events.send.
4. Um turno começa e inclui requisições ao modelo, um uso da ferramenta bash e um turno em outra thread (mostrados como o primeiro span anthropic.session.turn e os spans abaixo dele).
5. O modelo pede para usar a ferramenta personalizada list_issues, então o turno termina com o motivo de parada requires_action.
6. O executor de ferramentas de sessão executa list_issues (mostrado como o span anthropic.custom_tool_use list_issues) e envia seu resultado chamando sessions.events.send.
7. Um segundo turno começa com o resultado da ferramenta (mostrado como o último span anthropic.session.turn).

O SDK na sua aplicação emite o span anthropic.custom_tool_use e o span de cliente de cada requisição. Para obter esses spans, configure o tracing do SDK.

Os spans de uma sessão podem estar em vários traces, por exemplo, quando você envia uma requisição posterior a partir de um novo trace raiz. Com multiagente ativado, uma sessão também pode ter várias threads. Para encontrar os spans de que você precisa, agrupe-os por um ID.

• Uma thread: Agrupe os spans por gen_ai.conversation.id, que contém o ID da thread da sessão. Ordene-os pelo horário de início para ler a thread como uma transcrição.
• Uma sessão inteira, com todas as suas threads: Agrupe os spans por anthropic.session.id, entre traces.

Com Conteúdo completo, você pode ler o conteúdo de uma sessão a partir de seus spans.

• Para ler o conteúdo de um turno, use seu span de turno. O prompt do sistema está em gen_ai.system_instructions no primeiro span de turno de uma thread, a entrada em gen_ai.input.messages (suas mensagens e resultados de ferramentas, eventos system.message e mensagens de outras threads), e a saída em gen_ai.output.messages (as mensagens do agente, usos de ferramentas e resultados de ferramentas).
• Para ver os argumentos e o resultado de um uso de ferramenta, leia seu span de ferramenta. Os argumentos estão em gen_ai.tool.call.arguments, e o resultado está em anthropic.tool_result.content.

Para cada span e seus atributos, consulte a referência de spans do OpenTelemetry.

Contagem de tokens

Para contar cada token uma única vez, some os spans de apenas uma origem para cada requisição. Quando uma requisição da Messages API tem tanto um span do SDK quanto um span da API, some seus spans da API. Ambos se chamam anthropic.messages.create, então diferencie-os pelo tipo: o span do SDK é CLIENT e seu filho, o span da API, é SERVER.

Para cada origem, some apenas os seguintes spans, porque alguns atributos de uso se repetem em mais de um nível dos spans da API:

• Spans do SDK: Some os spans anthropic.messages.create. Se uma requisição tiver compactações, adicione também anthropic.usage.compaction.input_tokens e anthropic.usage.compaction.output_tokens do span, porque os atributos gen_ai.usage.* não incluem tokens de compactação. Se um modelo de fallback atendeu uma requisição, seu span tem o uso apenas do modelo que atendeu a resposta.
• Spans da API de uma requisição da Messages API: Some os spans anthropic.messages.create ou seus spans anthropic.model_request, não ambos. Se uma requisição tiver compactações, adicione também seus spans anthropic.compaction. Não adicione também os atributos anthropic.usage.compaction.* do span anthropic.messages.create, porque eles contêm os mesmos tokens.
• Spans da API de uma sessão do Managed Agents: Some os spans anthropic.model_request e anthropic.session.outcome_evaluation.

Os spans podem chegar mais de uma vez, por exemplo, quando uma entrega é repetida. Se a sua plataforma de observabilidade não remover duplicatas, conte cada span uma única vez pelo seu ID de trace e ID de span.

gen_ai.usage.input_tokens já inclui os tokens lidos e gravados no cache de prompt, então não adicione os atributos de cache a ele. Para todos os atributos de uso, consulte Uso de tokens.