Observabilidade do Claude Code: Acompanhe Tokens, Custo e Uso por Desenvolvedor
.webp)
Built for Speed: ~10ms Latency, Even Under Load
Blazingly fast way to build, track and deploy your models!
- Handles 350+ RPS on just 1 vCPU — no tuning needed
- Production-ready with full enterprise support
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.
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.
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.
/usagena 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./insightsresume 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:
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
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.
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.
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
- Observabilidade para Claude em Produção: Contabilidade de Tokens e Tracing — a contabilidade de tokens em detalhes
- Rastreamento de Custos do Claude Code com o TrueFoundry AI Gateway — atribuição por desenvolvedor na prática
- Centralizando o Controle de Custos para IDEs de Codificação com IA — uma visão unificada para Claude Code, Cursor e Codex
- Preços do Claude Code Explicados — quanto realmente custam os tokens que você está observando
- Governança do Claude Code com um AI Gateway — transformando observabilidade em aplicação de regras
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.
TrueFoundry AI Gateway delivers ~3–4 ms latency, handles 350+ RPS on 1 vCPU, scales horizontally with ease, and is production-ready, while LiteLLM suffers from high latency, struggles beyond moderate RPS, lacks built-in scaling, and is best for light or prototype workloads.














.webp)







