OpenTelemetry no Claude: o custo certo de cada pedido

O que mudou

Em 14 de outubro de 2026, a Anthropic lançou em beta a exportação OpenTelemetry da plataforma Claude, segundo as notas de versão oficiais. Com ela, você acompanha as requisições da Messages API e as sessões do Claude Managed Agents na ferramenta de observabilidade que já usa.

Há dois caminhos, e dá para usar os dois juntos:

O modo padrão é só metadados: identificadores, tempo, status e contagem de tokens. O modo conteúdo completo também manda prompts e respostas. Para a conta de custo, os metadados bastam.

A documentação avisa que os nomes de spans e atributos podem mudar durante o beta. Confira antes de travar o seu painel.

Os campos que entram na conta

Os spans trazem a contagem de tokens nos atributos abaixo, segundo a referência oficial de spans:

O ponto central está na primeira linha. Na resposta comum da API, o campo input_tokens traz só a entrada sem cache. No span, gen_ai.usage.input_tokens traz tudo somado. Quem copia a fórmula antiga erra a conta.

Nas requisições da Messages API, os spans trazem tokens, não preço. O valor você calcula com a tabela de preços.

A conta certa, passo a passo

Primeiro separe a entrada em três partes:

1. Entrada sem cache = input_tokens − cache_read − cache_write.
2. Leitura de cache = cache_read.
3. Gravação de cache = ephemeral_5m e ephemeral_1h, cada uma com seu preço.

Depois multiplique cada parte pelo seu preço e some a saída. No Sonnet 5.5, pela tabela do site atualizada em outubro de 2026:

Na requisição que grava o cache, os mesmos 30.000 tokens entram pelo preço de gravação de 5 minutos, US$ 2,50 por milhão. Essa requisição custa US$ 0,0870.

Os três erros que inflam o painel

O volume de 60.000 requisições e a taxa de 90% de acerto no cache são exemplo. O tamanho do erro cresce com o cache: quanto mais você economiza com ele, mais o painel errado exagera.

Erro 1: tratar tudo como entrada cheia. É o caso da abertura. O painel ignora que 30.000 dos 32.000 tokens saíram do cache.

Erro 2: somar o cache em cima da entrada. A documentação diz com todas as letras: input_tokens já inclui leituras e gravações. Não some de novo.

Erro 3: contar a mesma requisição duas vezes. Quando você liga o SDK e a API, cada requisição gera um span anthropic.messages.create do tipo CLIENT (SDK) e outro do tipo SERVER (API). A orientação oficial é somar só os spans da API. Dentro dos spans da API, some os anthropic.messages.create ou os anthropic.model_request, nunca os dois.

Outros detalhes que mudam o total

• Spans repetidos. A entrega é "pelo menos uma vez": o mesmo span pode chegar duas vezes. Se a sua plataforma não remove duplicados, conte cada span uma vez pelo ID do trace e do span.
• Compactação. No span do SDK, os tokens de compactação ficam fora de gen_ai.usage.*, em anthropic.usage.compaction.input_tokens e output_tokens. Some à parte. Nos spans da API, some os spans anthropic.compaction.
• Residência de dados. Se você usa inference_geo: "us", a tabela oficial aplica um multiplicador de 1,1 em todas as categorias de token. No caso, a requisição certa iria de US$ 0,0150 para US$ 0,0165.
• Modelo que respondeu. O atributo gen_ai.response.model mostra o modelo que de fato atendeu, que pode ser diferente do pedido quando há modelo de reserva. Use esse campo para escolher o preço.
• Agentes gerenciados. Para sessões do Managed Agents, some os spans anthropic.model_request e anthropic.session.outcome_evaluation.

O mesmo erro em outros modelos

A mesma requisição de exemplo, com 30.000 tokens lidos do cache, em três modelos:

O exagero muda de um modelo para outro porque a relação entre o preço da leitura de cache e o da entrada não é a mesma em todos. Confira a tabela de cada modelo antes de montar a fórmula.

Span não é fatura

A própria documentação avisa: os spans exportados não são um registro completo do uso. A entrega é de melhor esforço, então um span pode se perder e não volta. Um cliente também pode desligar o rastreamento de uma requisição pelo cabeçalho traceparent. E a API não gera spans para o endpoint compatível com o SDK da OpenAI.

Use os spans para ver custo por funcionalidade, por cliente ou por agente. Para conferir a conta do mês e acompanhar cada chave de API, a orientação oficial é usar a Usage API.

Checklist antes de confiar no painel

• Separe entrada sem cache, leitura e gravação antes de multiplicar.
• Some só uma fonte por requisição (spans da API, se tiver os dois).
• Remova spans duplicados pelo ID do trace e do span.
• Some a compactação à parte quando ela aparece.
• Aplique 1,1 se a requisição usa inference_geo: "us".
• Compare o total do mês com a Usage API.

Perguntas frequentes

O input_tokens do span é igual ao da resposta da API?

Não. No span, gen_ai.usage.input_tokens já inclui leituras e gravações de cache. No caso, ele mostra 32.000, dos quais só 2.000 pagam o preço cheio de entrada.

Quanto o erro mais comum exagera a conta?

No caso de exemplo no Sonnet 5.5, o painel com entrada cheia mostra US$ 4.320,00 por mês, contra US$ 1.332,00 do custo certo: 3,2 vezes mais.

Posso usar os spans no lugar da fatura?

Não. A entrega é de melhor esforço e alguns pedidos não geram span. Use os spans para dividir o custo por funcionalidade e a Usage API para fechar o mês.

Preciso ser admin para ligar?

Para o destino na API, sim: só o papel de admin adiciona ou muda destinos no Console. O rastreamento pelo SDK não pede permissão especial.

E com residência de dados nos EUA?

A requisição do caso sai por US$ 0,0165 em vez de US$ 0,0150, pelo multiplicador oficial de 1,1. No mês de exemplo, US$ 1.465,20.

Quer ver quanto o cache economiza no seu caso? Use a calculadora de cache de prompt com o tamanho do seu prefixo e a taxa de acerto.