Blank white background with no objects or features visible.

Olá, EMEA! A TrueFoundry está expandindo sua presença pela Europa, Oriente Médio e África. Leia mais. →

Observabilidade do Claude Code: Acompanhe Tokens, Custo e Uso por Desenvolvedor

Published: novembro 20, 2026

TL;DR:

Observabilidade para um agente de codificação não se trata de uptime. Trata-se de responder a uma pergunta por desenvolvedor: quanto isso custou e por quê.

  • A unidade de observabilidade é o token, dividido em quatro categorias — entrada, saída, leitura de cache e gravação de cache — porque sua fatura depende inteiramente dessa combinação.
  • A visualização nativa /usage é local para uma máquina e uma sessão, de modo que pode dizer a um desenvolvedor quanto custou sua última sessão, mas não pode fornecer um número consolidado da frota.
  • A exportação via OpenTelemetry é a forma nativa de extrair métricas por usuário de cada máquina para a sua própria stack — funciona em qualquer configuração, incluindo provedores de nuvem.
  • O uso em provedores de nuvem nunca chega aos painéis da Anthropic, portanto, no Amazon Bedrock, Google Vertex ou Microsoft Foundry, você só obtém atribuição por meio de OpenTelemetry ou de um gateway.
  • Um AI gateway torna o rastro inevitável: cada requisição cruza um único ponto, portanto, rastreamentos, gastos e uso de modelos por desenvolvedor existem independentemente de cada laptop estar instrumentado ou não.

O que significa observabilidade para um agente de codificação

A observabilidade tradicional pergunta se um serviço está no ar. Um agente de codificação está sempre "no ar" — ele roda em um laptop e se comunica com um provedor de modelos. A questão que importa é econômica e comportamental: qual desenvolvedor gastou quanto, em qual modelo, fazendo o quê, e por que uma sessão custou dez vezes mais do que outra. Isso é contabilidade de tokens, não verificação de integridade, e é a perspectiva adotada por este guia. Para o outro lado dessa mesma moeda relativo ao faturamento, consulte Preços do Claude Code Explicados.

Os riscos são concretos. Um único desenvolvedor ativo consome aproximadamente $13 por dia ativo e $150–250 por mês, com cerca de 90% dos usuários abaixo de $30/dia — portanto, as exceções importam enormemente. Sem uma visão por desenvolvedor, você não consegue encontrar as três pessoas em uma equipe de trinta que geram a maior parte da fatura, nem dizer se elas estão realizando um trabalho complexo ou simplesmente deixando o Opus ativado por padrão. A observabilidade transforma um total surpreendente em uma lista de causas corrigíveis.

O que realmente rastrear

Sete sinais carregam quase todo o valor. Todo o restante é derivado deles.

SinalPor que importaDe onde vem
Tokens de entrada / saídaA base de cada valor de custo; a saída é muito mais cara que a entradaCada resposta da API
Tokens de leitura / gravação de cacheLeituras em cache são ~10x mais baratas que entradas novas — essa divisão explica sua faturaOs campos de cache em cada resposta
Custo por desenvolvedorEncontra os dois ou três casos discrepantes que impulsionam a maior parte dos gastosTokens precificados por modelo, atribuídos a um usuário
Custo por modeloRevela o desperdício de deixar o Opus como padrãoO modelo servido em cada requisição
Custo por repositório ou equipeChargebacks, orçamentos por equipe e linhas de tendênciaMetadados da requisição ou a chave de roteamento
Latência (ms)Chamadas lentas, degradação do provedor e padrões de timeoutO tempo de duração do span da requisição
Chamadas de ferramentas e decisões de ediçãoQuanto do trabalho do agente é aceito vs descartadoOs eventos de uso de ferramentas em cada sessão

Dois destes — a combinação de modelos e a taxa de cache — são também suas maiores alavancas de custo, razão pela qual observá-los se paga. O lado do roteamento é abordado em Opus vs Sonnet vs Haiku: um guia de roteamento de custo vs capacidade, e o lado do cache em Cache de prompt do Claude: o cálculo real de custo.

O token não é um único número — são quatro

“Tokens utilizados” é um agregado inútil porque as quatro categorias são precificadas de formas muito diferentes. No Opus 5.5 a diferença é gritante: a saída custa cinco vezes o preço da entrada nova, as gravações em cache custam mais do que a entrada nova, e as leituras de cache custam uma fração dela. Agrupá-los oculta exatamente a informação necessária para reduzir a fatura.

Tipo de tokenO que éCusto relativo (Opus 5.5)O que um valor alto indica
EntradaPrompt novo enviado ao modelo$4 / M (linha de base)Contexto grande ou repetido sendo reenviado
SaídaTokens que o modelo gera$20 / M (~5x a entrada)Gerações verbosas ou tarefas sobredimensionadas
Gravação de cacheContexto gravado no cache$5 / M (acima da entrada)Normal no primeiro turno; desperdício se houver alta rotatividade
Leitura de cacheContexto servido a partir do cache$0,20 / M (~10x mais barato)Saudável — o cache está funcionando como esperado

Uma alta taxa de leitura de cache é o sinal desejado: contexto de longa duração reutilizado em vez de cobrado novamente pelo preço integral de entrada. Em uma assinatura, o cache de prompt dura cerca de uma hora; na API ou em um provedor de nuvem, cerca de cinco minutos, portanto, a taxa esperada varia de acordo com a configuração. Se as leituras de cache despencarem e a entrada nova subir, algo quebrou o cache — e você só percebe se os quatro números forem rastreados separadamente.

As opções nativas e onde cada uma para

O Claude Code já vem com visibilidade real — apenas limitada ao escopo individual.

  • /usage na CLI mostra os tokens e o custo estimado da sessão atual, calculados localmente a preço de tabela. É preciso para um desenvolvedor em uma máquina e é redefinido quando a sessão é limpa. Não consegue agregar uma equipe.
  • /insights resume as sessões recentes naquela máquina — útil para um desenvolvedor refletir sobre seus próprios padrões, mas ainda não é uma visão global da frota.
  • Análises de assinatura (Teams e Enterprise) fornecem um relatório de gastos em nível de organização por usuário e por modelo, atualizado diariamente — bom para o financeiro, mas não é uma visão ao vivo e por requisição.
  • O uso em provedores de nuvem é invisível para os painéis da Anthropic. Execute o Claude Code no Amazon Bedrock, Google Vertex ou Microsoft Foundry e as análises nativas simplesmente não o enxergarão, porque os tokens são cobrados diretamente na sua conta de nuvem.

O padrão é consistente: as ferramentas nativas respondem "quanto eu acabei de gastar", não "o que a frota está fazendo agora". Para isso, você precisa que as métricas saiam da máquina.

OpenTelemetry: extraindo métricas da máquina

A maneira nativa de fechar essa lacuna é o OpenTelemetry. O Claude Code pode exportar métricas de tokens e custos por usuário via OTLP para sua própria stack de observabilidade, e funciona em qualquer configuração — assinatura, Console API ou qualquer provedor de nuvem. Isso o torna a única opção nativa que fornece números por desenvolvedor em tempo quase real, independentemente de como os desenvolvedores se autenticam.

Como ativar

A exportação vem desativada por padrão e é controlada inteiramente por variáveis de ambiente, configuradas no perfil do shell ou em um arquivo de configurações gerenciadas distribuído para cada máquina. Uma configuração mínima de métricas e logs:

As métricas são enviadas em intervalos — o padrão é 60000 ms para métricas e 5000 ms para logs —, portanto "tempo quase real" significa granularidade por minuto, não por requisição. Traces são um sinal beta separado, controlado por CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 e OTEL_TRACES_EXPORTER=otlp; ative-os apenas com um collector pronto para receber spans.

O que cada sinal carrega

O OpenTelemetry emite três tipos de sinais: métricas (os contadores sobre os quais você constrói painéis), logs (eventos discretos) e traces (spans beta para uma única interação). As métricas são onde reside a história dos custos:

MétricaO que carregaAtributos-chave
claude_code.token.usageTokens consumidos, divididos por categoriatype (input / output / cacheRead / cacheCreation), model
claude_code.cost.usageGasto estimado a preço de tabela (USD)model, user.email
claude_code.session.countSessões iniciadassession.id, user.email
claude_code.lines_of_code.countLinhas alteradas pelo agentetype (added / removed)
claude_code.code_edit_tool.decisionSe uma edição foi mantidatool_name, decision (accept / reject)
claude_code.active_time.totalSegundos de uso ativotype (user / cli)
claude_code.commit.count / pull_request.countAtividade do Git realizada por meio do agenteatributos padrão

A atribuição por usuário depende dos atributos user.email e account-identifier, incluídos por padrão. Note que o session.id aumenta bruscamente a cardinalidade — uma série por sessão —, portanto, se o seu backend cobra por série, mantenha-o desativado nos painéis da frota e faça a atribuição por usuário. Os logs de eventos (claude_code.user_prompt, claude_code.tool_result, claude_code.api_request) adicionam detalhes por ação que as métricas não conseguem capturar e podem opcionalmente carregar o conteúdo do prompt ou da ferramenta — uma decisão de privacidade a ser tomada antes da ativação.

A desvantagem é operacional: você precisa instrumentar cada máquina, manter as variáveis configuradas mesmo após a substituição de laptops e contratações, e gerenciar o collector e os painéis por conta própria. Ele faz o streaming de métricas de forma eficiente, mas um fluxo de métricas não é uma trilha de auditoria no nível da requisição e não faz nada para impor um orçamento — apenas relata. Para uma análise mais aprofundada da contabilidade de tokens em si, consulte Observabilidade para Claude em produção: contabilidade de tokens e tracing.

Nativo vs OpenTelemetry vs Gateway

Capacidade/usage (nativo)Exportação OpenTelemetryAI gateway
EscopoUma máquina, uma sessãoPor desenvolvedor, em toda a frotaPor desenvolvedor, em toda a frota
Atribuição por usuárioNãoSimSim
Funciona em provedores de nuvemApenas localSimSim
Traces no nível da requisiçãoNãoParcial (beta)Sim
Latência por requisição (ms)NãoParcialSim
Limites de gastos / aplicaçãoNãoNãoSim
Multiferramenta (Cursor, Codex)NãoApenas por ferramentaSim, visão unificada
Custo de configuraçãoIntegradoInstrumentar cada máquinaApontar o cliente para um endpoint

OpenTelemetry e um gateway não são mutuamente exclusivos — um bom gateway é compatível com OpenTelemetry e pode alimentar a mesma stack. A diferença é que o gateway também se posiciona no caminho da requisição, de modo que pode rastrear e impor limites, não apenas contar. O OTel é a resposta certa quando você é proprietário da frota, confia que todas as máquinas permanecerão instrumentadas e precisa apenas de relatórios. Um gateway é a resposta certa quando máquinas entram e saem, quando parte do tráfego roda em um provedor de nuvem e quando "visualizar" precisa se transformar em "bloquear".

Observabilidade no TrueFoundry AI Gateway

Roteie o Claude Code através do TrueFoundry AI Gateway e cada conclusão passará por um único ponto sob seu controle. Isso transforma a observabilidade de algo em que cada desenvolvedor precisa optar em seu laptop em algo que simplesmente existe:

  • Traces de requisição — cada requisição com o usuário resolvido, o modelo servido, contagem de tokens e latência, para que você possa responder "quem enviou isso e quanto custou" após o ocorrido.
  • Painéis de métricas que agregam a frota por usuário, equipe e modelo — a imagem por desenvolvedor detalhada no guia de rastreamento de custos para o Claude Code.
  • Visão unificada entre ferramentas — Claude Code, Cursor e Codex chegam ao mesmo lugar em vez de três separados, como em centralizando o controle de custos para IDEs de codificação com IA.
  • Exportação compatível com OpenTelemetry com aproximadamente 3–4 ms de overhead adicional, permitindo que os mesmos números fluam para o Grafana, Datadog ou Prometheus se você já os utiliza.
Quer acompanhar os gastos do Claude Code por desenvolvedor sem instrumentar cada laptop?

O que um único trace de requisição registra

Um gateway responde a perguntas que as métricas do OpenTelemetry não conseguem, pois registra cada requisição como um registro discreto, e não como um contador agrupado por minuto. Um trace captura a identidade resolvida, o modelo servido, a divisão em quatro categorias de tokens, o custo na sua taxa contratada, a latência de ponta a ponta em milissegundos, o status e a decisão de roteamento. Como cada linha é pesquisável e retida, você pode reconstruir um pico: filtre para um desenvolvedor e uma hora e leia as chamadas reais que geraram aquele aumento — a trilha de auditoria que um fluxo de métricas simplifica demais.

Campo do traceO que responde
Usuário / chave resolvidaQuem enviou esta requisição
Modelo servidoFoi usado o Opus quando o Sonnet seria suficiente?
Divisão de tokens (ent. / saí. / cache)De onde veio o custo desta chamada
Custo na taxa contratadaO gasto real, não uma estimativa de preço de tabela
Latência (ms)Esta chamada foi lenta? O provedor estava degradado?
Decisão de roteamentoQual política escolheu este modelo

Sobre o que alertar e quais painéis construir

Coletar sinais é inútil se ninguém olhar até que a fatura chegue. O objetivo de extrair métricas da máquina é agir enquanto ainda importa — um pequeno conjunto de alertas e alguns painéis essenciais, em vez de um painel repleto de gráficos sem foco. Alertas valiosos se mapeiam para uma causa específica e corrigível:

  • Gasto diário por desenvolvedor ultrapassando um limite — por exemplo, mantido acima dos ~$30/dia que já cobrem cerca de 90% dos usuários. Isso identifica o desvio no dia em que ele começa, não um mês depois.
  • Participação do Opus nos tokens acima do teto — o sinal mais claro de desvio do modelo padrão, onde edições de rotina estão sendo executadas silenciosamente no modelo mais caro.
  • Queda na taxa de leitura de cache — uma queda repentina significa que o cache sofreu regressão e a entrada nova está sendo cobrada novamente pelo preço integral.
  • Latência p95/p99 em ms ultrapassando um limite — revela degradação do provedor e padrões de timeout antes que os desenvolvedores relatem que "o Claude está lento".
  • Volume de requisições fora do horário comercial — tarefas agendadas e trabalhos em segundo plano que reenviam grandes contextos em intervalos regulares aparecem como gastos sem um humano no teclado.

Os painéis que valem a pena criar são igualmente poucos: custo da frota por desenvolvedor (top-N), custo por modelo para que a combinação Opus-vs-Sonnet-vs-Haiku seja visível rapidamente, uma visualização empilhada dos quatro tipos de tokens para monitorar a taxa de cache, custo por repositório ou equipe para chargebacks, uma distribuição de latência em milissegundos e taxa de aceitação de chamadas de ferramentas. Em um gateway, eles vêm pré-construídos e alimentados automaticamente; no OpenTelemetry, você os monta no Grafana ou no seu backend a partir das métricas mencionadas acima.

Um exemplo prático

Uma equipe de plataforma tem trinta desenvolvedores usando o Claude Code, alguns na assinatura e outros no Bedrock. A fatura mensal está subindo e ninguém sabe o motivo. Eles apontam todas as instalações para o gateway e analisam o painel no dia seguinte: três desenvolvedores respondem por 60% do gasto com tokens, todos os três porque o Opus está configurado como modelo padrão, e uma tarefa agendada está reenviando um grande contexto a cada hora. Eles definem uma política de modelo que roteia edições de rotina para o Sonnet, corrigem a tarefa e a linha de tendência cai — sem pedir a ninguém que execute um comando em seu laptop. A observabilidade não alterou o comportamento diretamente; visualizá-la sim.

O limite honesto: um gateway mostra o gasto e permite limitá-lo. Ele não reescreve prompts — ele torna o desperdício impossível de ser ignorado e fornece a alavanca de política para agir. O lado da aplicação é abordado em Governança do Claude Code com um AI gateway.

Pormenores importantes a saber

  • O valor em dólares no /usage é uma estimativa calculada localmente a preço de tabela. Se sua organização paga taxas contratadas, ele não corresponderá à fatura, a menos que um administrador configure a sobreposição de taxas.
  • O /usage é por máquina. Um desenvolvedor que programa em um laptop e em um desktop vê duas imagens parciais; apenas uma métrica fora da máquina (OTel ou gateway) consegue reconciliá-las.
  • Os painéis dos provedores de nuvem dividem os dados. No Bedrock, Vertex ou Foundry, seu gasto fica no console de faturamento da nuvem, e a atribuição por usuário exige o OpenTelemetry ou um gateway adicional.
  • Sessões ociosas ainda geram requisições. Tarefas agendadas e trabalhos em segundo plano reenviam o contexto completo em seus intervalos, portanto, um desenvolvedor aparentemente inativo ainda pode acumular custos — você só verá isso em um trace por requisição.
  • Contar não é limitar. O OpenTelemetry informa que um orçamento foi estourado após o fato; apenas algo no caminho da requisição pode interrompê-la antes que ela gaste.
  • O session.id é uma armadilha de cardinalidade. Se mantido ativado para painéis da frota, ele cria uma série de métricas por sessão, o que pode fazer os custos dispararem em um backend de observabilidade cobrado por uso — em vez disso, faça a atribuição por usuário.
  • Equipes de agentes multiplicam tokens. Execuções com múltiplos agentes usam aproximadamente 7x mais tokens do que uma única sessão, portanto, adotá-las pode fazer o gasto dar um salto sem que nenhum indivíduo mude seu comportamento.

Leituras relacionadas

Conclusão

A observabilidade do Claude Code é, na verdade, a observabilidade de custos detalhada ao máximo: tokens divididos em quatro categorias, atribuídos a um desenvolvedor, um modelo e uma tarefa. As ferramentas nativas resolvem isso para uma pessoa em uma máquina; o OpenTelemetry resolve para a frota se você instrumentar cada máquina; e um gateway resolve para a frota por padrão, porque cada requisição já passa por ele.

Escolha a camada correspondente ao nível de visibilidade necessário. Se a resposta for "por desenvolvedor, em todos os modelos e provedores, com a capacidade de agir sobre o que for encontrado", o caminho da requisição é o lugar ideal para estar.

Veja cada requisição, token e dólar do Claude Code em um só lugar.

Try now.

One gateway for all your models, MCP servers, and agents. No credit card needed.

Start free
Table of Contents

One Gateway for Every LLM, Agent and MCP Server

Book a 30-min with our AI expert

Book a Demo

The fastest way to build, govern and scale your AI

Book Demo
Summarize with
ChatGPT logo by OpenAI
Perplexity AI logo
Blurry red snowflake on white background, symmetrical frosty design with soft edges and abstract shape.

Discover More

No items found.
novembro 20, 2026
|
5 min read

Grok 4.3 no Amazon Bedrock: Roteamos Quatro Modelos de Fronteira por um Único Gateway e Medimos o Custo

Ferramentas de LLM
comparação
novembro 20, 2026
|
5 min read

GPT-6.1 Terra: API, Benchmarks, Preço & Como Usar

No items found.
TrueFoundry AI gateway is an enterprise alternative to Bifrost and Portkey
novembro 20, 2026
|
5 min read

Bifrost vs Portkey: Precificação, Recursos de Gateway e Adequação Enterprise Comparados

No items found.
novembro 20, 2026
|
5 min read

Evolução do Machine Learning: Um Mergulho Profundo na Jornada de Savin

True ML Talks
No items found.
Take a quick product tour
Start Product Tour
Product Tour