Stack de Observabilidade com Grafana
Ir para notas que citam estaUma stack de observabilidade com Grafana reúne o coletor que recebe a telemetria do agente, a base que guarda as séries e o painel que mostra custo e uso por pessoa e por projeto.
Ela é o destino dos dados que uma ferramenta agêntica emite no padrão OpenTelemetry. Sozinho, o padrão só transporta sinais; alguém precisa recebê-los, armazená-los e cruzá-los para que virem resposta. A stack é essa outra ponta. Montada como Learning Prototype sobre o Claude Code, ela permite enxergar em um só lugar números que o painel nativo do provedor mostra de forma limitada, e cruzá-los com dados de outras fontes.
As peças e o papel de cada uma
- Emissor: o Claude Code, com a telemetria ligada por variáveis de ambiente que apontam para o endpoint do coletor. Basta mudar essas variáveis para a ferramenta começar a enviar, sem código adicional.
- Coletor OpenTelemetry: recebe os sinais, e a partir do modelo chamado em cada requisição contabiliza tokens e custo.
- Base de séries temporais: guarda as métricas ao longo do tempo. Prometheus é o backend citado para esse papel.
- Grafana: lê a base e monta os painéis. É onde as perguntas são feitas.
O conjunto sobe inteiro com Docker Compose, num único comando de subida, o que torna a stack simples de reproduzir numa máquina de desenvolvimento. O Grafana pode rodar localmente, para uso em dev, ou num pod exposto na rede, para uso compartilhado. No protótipo, o layout do painel partiu de um template pronto, e os dados exibidos eram de uso real.
O que cada painel responde
- Solicitações: a lista de requisições feitas, com indicação visual quando houve erro. A mensagem de erro tende a ser genérica, porque esse tipo de telemetria ainda estava em beta.
- Custo por modelo: quanto cada modelo consumiu, útil para avaliar se a troca por um modelo mais barato compensa ou se ele gera tokens demais para chegar ao mesmo resultado.
- Custo por projeto: onde o gasto se concentra. Projetos de refatoração costumam liderar, porque trabalham sobre bases grandes e contexto extenso.
- Ferramentas utilizadas: quais tools o agente acionou, dado gerado pelo harness e não pelo modelo.
- Sessões e membros: quanto cada pessoa do time gastou, a visão que alimenta decisões de plano e de limite de uso.
Esses painéis são a leitura prática da Telemetria de Uso e Custo do Claude Code e da conversa sobre Custo de Tokens: transformam o valor da fatura em uma pergunta respondível, que é onde o gasto nasce.
Configuração individual versus configuração da organização
A stack pode ser alimentada de dois jeitos, e a diferença costuma gerar dúvida.
No modo individual, cada pessoa define as variáveis de ambiente na própria máquina e sobe a stack para ver o próprio uso. É o caminho do protótipo, bom para experimentar e para entender o que a ferramenta emite.
No modo de organização, quem administra a conta define as variáveis uma única vez, em nível de organização. Como todos os usuários estão dentro da mesma licença, a telemetria de cada desenvolvedor passa a ser enviada ao backend definido sem que ninguém precise instalar ou configurar nada na própria máquina. A analogia é a de um backend comum: as variáveis ficam no ambiente global do projeto e todos os clientes enviam para o mesmo Grafana.
Para ver custo, sessões e membros, o painel de analytics do provedor já basta e não exige configuração. A stack própria se justifica quando é preciso cruzar esses dados com outras fontes, guardar histórico no próprio ambiente ou montar visões que o painel nativo não oferece.