Monitorar o Claude Code com OpenTelemetry na empresa: guia prático

Monitorar o Claude Code com OpenTelemetry na empresa: guia prático

Para monitorar o Claude Code com OpenTelemetry, ative a telemetria por variáveis de ambiente, aponte a exportação para um coletor OTLP da empresa e leia dois tipos de dado: métricas (sessões, tokens, custo, decisões de edição) e eventos (requisições à API, resultados de ferramentas). Um painel útil agrega esses dados por equipe e por projeto, responde a perguntas de gestão e deixa de fora o conteúdo dos prompts e o ranking de pessoas.

O ponto de partida não é a ferramenta de dashboard, e sim a decisão sobre o que você precisa saber e o que não precisa ver.

Principais pontos

• O Claude Code exporta telemetria no padrão OpenTelemetry, desligada por padrão, e você escolhe para onde enviar.
• Métricas servem para tendência e custo; eventos servem para investigar comportamento, falhas e uso de ferramentas.
• O conteúdo dos prompts não deve ser exportado, salvo decisão explícita e documentada.
• Agregar por equipe, projeto e centro de custo responde à maioria das perguntas de gestão sem expor indivíduos.
• Comece com um painel pequeno, revise depois de algumas semanas e corte o que ninguém usou para decidir.

O que o Claude Code consegue exportar?

A documentação oficial do Claude Code descreve a telemetria como parte do suporte a OpenTelemetry. Os nomes exatos mudam com o tempo, então trate a lista abaixo como mapa e confira a documentação de monitoramento do Claude Code antes de montar consultas.

Na família das métricas, o que costuma importar para a gestão:

• Contagem de sessões: mostra adoção, ou seja, quantas sessões acontecem ao longo do tempo.
• Uso de tokens, separado por tipo (entrada, saída, cache) e por modelo: base para entender consumo. Se o conceito ainda é novo na sua equipe, vale ler o que são tokens em IA e por que eles definem o custo.
• Custo estimado de uso: serve para tendência e comparação entre períodos, não como fatura. A cobrança real vem do seu contrato.
• Linhas de código alteradas, commits e pull requests criados com apoio da ferramenta: indicadores de atividade, não de qualidade.
• Decisões sobre edições de código (aceitas ou recusadas): dizem muito sobre confiança na ferramenta e sobre a qualidade das sugestões.
• Tempo ativo de uso: indicador grosseiro de engajamento.

Na família dos eventos, exportados como logs OpenTelemetry:

• Requisições à API do modelo, com modelo usado, duração e volume de tokens.
• Erros de API, úteis para detectar instabilidade, limite de uso ou configuração errada.
• Resultados de ferramentas: qual ferramenta rodou, se teve sucesso e quanto tempo levou.
• Decisões de permissão sobre ferramentas: se foram aprovadas, por qual mecanismo e com que resultado.
• Registro de que um prompt foi enviado. Por padrão, o texto do prompt é omitido, e existe uma opção explícita para incluí-lo.

Essa última distinção é o centro da discussão ética e jurídica. Saber que houve um prompt e quanto custou é telemetria operacional. Guardar o texto é guardar o que a pessoa pensou, perguntou e colou, incluindo trechos de código, nomes e eventualmente dados pessoais.

Como ativar a telemetria passo a passo

O caminho abaixo vale para um piloto com uma equipe. Os nomes das variáveis seguem a documentação oficial; confirme-os na versão que você usa.

• Suba um coletor OpenTelemetry (o OpenTelemetry Collector é a opção comum) em um ambiente que a empresa controla, com autenticação no endpoint.
• Escolha o destino de armazenamento: um backend de métricas e um de logs que sua equipe de infraestrutura já opere. Não crie uma pilha nova só para isso.
• Defina a variável que habilita a telemetria do Claude Code (CLAUDE_CODE_ENABLE_TELEMETRY).
• Configure os exportadores de métricas e de logs (OTEL_METRICS_EXPORTER e OTEL_LOGS_EXPORTER) para o protocolo OTLP, e informe o protocolo e o endereço do coletor (OTEL_EXPORTER_OTLP_PROTOCOL e OTEL_EXPORTER_OTLP_ENDPOINT).
• Se o coletor exigir credencial, passe-a por cabeçalho (OTEL_EXPORTER_OTLP_HEADERS) vinda de um cofre de segredos, nunca escrita em repositório.
• Marque os dados com atributos de recurso como equipe, projeto ou centro de custo (OTEL_RESOURCE_ATTRIBUTES), para agregar sem depender de identidade individual.
• Distribua a configuração de forma central, por configurações gerenciadas da organização quando o seu plano permitir, para que ninguém dependa de lembrar de exportar variáveis na máquina.
• Teste primeiro com o exportador de console em uma máquina de teste, para ver exatamente quais campos saem antes de enviar qualquer coisa ao coletor.

Sobre esse último item: ver o dado bruto antes de armazenar é o passo mais barato de privacidade que existe. Se algum campo surpreender, é melhor descobrir antes de ele estar em um banco com retenção de meses.

Quais perguntas o painel deve responder?

Um painel começa por perguntas, não por gráficos disponíveis. Estas são as que costumam sustentar decisões reais:

• A adoção está crescendo, estável ou caindo em cada equipe? Isso mostra onde falta treinamento ou onde a ferramenta não encaixa.
• O consumo de tokens e o custo estimado por projeto estão dentro do esperado? Isso sustenta a conversa de orçamento.
• Qual proporção das edições sugeridas é aceita? Uma taxa de recusa alta pode indicar contexto ruim, instruções de projeto fracas ou tarefas inadequadas.
• Quais ferramentas falham mais? Falhas repetidas costumam apontar problema de configuração, permissão ou integração.
• Os erros de API estão concentrados em algum horário ou modelo? Isso separa problema da ferramenta de problema de rede ou de limite de uso.
• As decisões de permissão mostram aprovação automática demais em ações sensíveis? Isso conecta o monitoramento com a segurança no Claude Code: permissões, sandbox e segredos.

Um layout enxuto cabe em três blocos: adoção e custo no topo, qualidade da interação (aceitação de edições, falhas de ferramenta) no meio e saúde operacional (erros de API, latência) embaixo. Se uma pergunta não leva a uma ação possível, o gráfico correspondente provavelmente não precisa existir.

Como evitar que o painel vire vigilância individual?

O risco não vem do OpenTelemetry, vem das escolhas de configuração e de uso. Um painel que mostra quem usou menos, quem aceitou menos sugestões ou quem gastou mais tende a gerar comportamento defensivo: gente que usa a ferramenta para parecer produtiva, esconde dúvidas ou evita tarefas complexas porque custam mais. Isso destrói o próprio dado que você queria. O texto sobre como medir produtividade com IA sem virar vigilância aprofunda esse raciocínio.

Um guia de decisão prático, em forma de regras:

• Não exporte o texto dos prompts. Mantenha a opção de registro de conteúdo desligada, e trate qualquer exceção como um projeto à parte, com finalidade, prazo e aprovação.
• Prefira atributos de equipe e projeto a identificadores de pessoa. Quando a ferramenta incluir e-mail ou identificador de conta nos dados, avalie se o seu backend precisa guardá-los; se não precisa, remova ou pseudonimize no coletor.
• Evite atributos de alta cardinalidade nas métricas, como identificador de sessão, a menos que haja necessidade clara. Além de custo de armazenamento, eles facilitam reconstruir o comportamento de uma pessoa.
• Defina um tamanho mínimo de grupo para exibição. Se uma equipe tem duas pessoas, o agregado é praticamente individual.
• Restrinja o acesso ao painel e aos logs brutos. Quem vê o gráfico de tendência não precisa ver o evento detalhado.
• Defina retenção curta para eventos detalhados e mais longa para agregados.
• Escreva, antes de ligar, para que o dado será usado e para que não será. Por exemplo: nunca para avaliação de desempenho individual.
• Comunique à equipe o que é coletado. Transparência reduz a desconfiança e é coerente com os princípios da LGPD, como finalidade, necessidade e transparência.

Sobre LGPD: dados de uso ligados a uma pessoa identificável podem ser dados pessoais. Isso não significa que o monitoramento seja proibido, significa que ele precisa de finalidade clara, minimização e acesso controlado. Para orientação oficial, consulte a ANPD e valide o desenho com o jurídico da empresa.

Cenário ilustrativo: painel para uma equipe de desenvolvimento

Imagine uma empresa de software com três equipes que adotaram o Claude Code há pouco tempo. A direção quer entender se vale expandir o uso, mas não quer comparar desenvolvedores. Este é um cenário ilustrativo, não um caso real.

A configuração marca cada máquina com a equipe e o projeto. O coletor remove identificadores de conta antes de gravar. O texto dos prompts fica desligado. O painel mostra, por equipe: sessões ao longo das semanas, tokens e custo estimado por projeto, taxa de aceitação de edições, ferramentas com mais falhas e erros de API.

Após algumas semanas, a leitura aponta que uma das equipes tem muitas recusas de edição e falhas repetidas de uma mesma ferramenta. A conclusão certa não é cobrar a equipe, e sim investigar: talvez falte um arquivo de instruções do projeto, ou a permissão da ferramenta esteja mal configurada. A ação é de suporte e padronização, por exemplo criar skills no Claude Code com o padrão de testes daquele projeto. Depois, o painel mostra se a aceitação melhorou.

Nesse cenário, o monitoramento serviu para melhorar o ambiente de trabalho, não para julgar pessoas. Esse é o teste de qualidade do painel: cada gráfico deve apontar para uma melhoria possível no processo.

Como a abordagem de mapear, limitar, pilotar e transferir se aplica

O método que usamos em projetos de IA cabe bem aqui. Mapear: levantar quem usa o Claude Code, em quais projetos e quais decisões o monitoramento precisa sustentar, registrando como é a situação hoje. Limitar: definir quais campos saem, quais ficam de fora, quem acessa e por quanto tempo os dados ficam guardados. Pilotar: ligar a telemetria para uma equipe, com logs conferidos e um critério de sucesso combinado, como a capacidade de responder a três perguntas de gestão sem olhar dado individual. Transferir: entregar o painel, a documentação e a rotina de revisão para quem vai operar, e decidir se expande, ajusta ou encerra. Para estruturar os critérios do piloto, o artigo sobre como medir um piloto de automação com IA traz métricas e pontos de decisão que servem também aqui.

Fundamentos de observabilidade que ajudam

Se a equipe de infraestrutura nunca trabalhou com OpenTelemetry, o primer de observabilidade do projeto explica a diferença entre métricas, logs e traces e por que o coletor fica entre a origem e o armazenamento. Esse intermediário é o que permite filtrar, remover atributos e trocar de backend sem mexer em cada máquina de desenvolvedor, e é justamente onde você aplica as regras de privacidade descritas acima.

Perguntas frequentes

O Claude Code envia telemetria para a Anthropic sem eu configurar? A telemetria de OpenTelemetry descrita aqui é opt-in: você a habilita e define o destino. Isso é diferente de outros serviços de operação e de erros que a ferramenta pode ter; consulte a documentação oficial e a política de dados do seu plano para ver o que se aplica ao seu caso.

Posso ver o que cada desenvolvedor pediu à ferramenta? Tecnicamente existe uma opção para incluir o texto dos prompts nos eventos, mas ela vem desligada por padrão por um bom motivo. Recomendamos mantê-la desligada, porque prompts podem conter código sensível, segredos e dados pessoais, e porque guardar esse conteúdo muda a natureza do monitoramento. Se houver uma necessidade específica, trate como exceção com finalidade e prazo definidos.

O custo que aparece no painel é o valor que vou pagar? Não necessariamente. O custo exportado é uma estimativa útil para tendência e comparação entre projetos, mas a cobrança depende do seu contrato e da forma de acesso. Use o painel para detectar variações e a fatura do fornecedor para o valor oficial.

Preciso de uma ferramenta paga de observabilidade para começar? Não. Como o formato é OpenTelemetry, você pode usar o backend que a empresa já opera, ou começar com o exportador de console para validar os campos. O importante no início é decidir as perguntas, as regras de privacidade e o responsável por manter o painel, e só depois escolher onde armazenar.

Fontes

• Anthropic: monitoramento de uso do Claude Code com OpenTelemetry
• OpenTelemetry: conceitos de observabilidade
• ANPD: Autoridade Nacional de Proteção de Dados