Monitoramento

Claude Code suporta métricas e eventos OpenTelemetry (OTel) para monitoramento e observabilidade.

Todas as métricas são dados de séries temporais exportados via protocolo de métricas padrão do OpenTelemetry, e eventos são exportados via protocolo de logs/eventos do OpenTelemetry. É responsabilidade do usuário garantir que seus backends de métricas e logs estejam configurados adequadamente e que a granularidade de agregação atenda aos seus requisitos de monitoramento.

​

Início Rápido

Configure OpenTelemetry usando variáveis de ambiente:

# 1. Habilitar telemetria
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Escolher exportadores (ambos são opcionais - configure apenas o que você precisa)
export OTEL_METRICS_EXPORTER=otlp       # Opções: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # Opções: otlp, console

# 3. Configurar endpoint OTLP (para exportador OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Definir autenticação (se necessário)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Para depuração: reduzir intervalos de exportação
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 segundos (padrão: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 segundos (padrão: 5000ms)

# 6. Executar Claude Code
claude

Para opções de configuração completas, consulte a especificação OpenTelemetry.

​

Configuração do Administrador

Administradores podem configurar as configurações do OpenTelemetry para todos os usuários através do arquivo de configurações gerenciadas. Isso permite controle centralizado das configurações de telemetria em toda uma organização. Consulte a precedência de configurações para mais informações sobre como as configurações são aplicadas.

O arquivo de configurações gerenciadas está localizado em:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux e WSL: /etc/claude-code/managed-settings.json
• Windows: C:\ProgramData\ClaudeCode\managed-settings.json

Exemplo de configuração de configurações gerenciadas:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

​

Detalhes de Configuração

​

Variáveis de Configuração Comuns

​

Controle de Cardinalidade de Métricas

As seguintes variáveis de ambiente controlam quais atributos são incluídos nas métricas para gerenciar cardinalidade:

Essas variáveis ajudam a controlar a cardinalidade das métricas, o que afeta os requisitos de armazenamento e desempenho de consulta no seu backend de métricas. Cardinalidade mais baixa geralmente significa melhor desempenho e custos de armazenamento menores, mas dados menos granulares para análise.

​

Cabeçalhos Dinâmicos

Para ambientes empresariais que requerem autenticação dinâmica, você pode configurar um script para gerar cabeçalhos dinamicamente:

​

Configuração de Configurações

Adicione ao seu .claude/settings.json:

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​

Requisitos do Script

O script deve produzir JSON válido com pares chave-valor de string representando cabeçalhos HTTP:

#!/bin/bash
# Exemplo: Múltiplos cabeçalhos
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​

Limitações Importantes

Cabeçalhos são buscados apenas na inicialização, não durante o tempo de execução. Isso se deve às limitações da arquitetura do exportador OpenTelemetry.

Para cenários que requerem atualização frequente de token, use um OpenTelemetry Collector como proxy que pode atualizar seus próprios cabeçalhos.

​

Suporte a Organização Multi-Equipe

Organizações com múltiplas equipes ou departamentos podem adicionar atributos personalizados para distinguir entre diferentes grupos usando a variável de ambiente OTEL_RESOURCE_ATTRIBUTES:

# Adicionar atributos personalizados para identificação de equipe
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Esses atributos personalizados serão incluídos em todas as métricas e eventos, permitindo que você:

• Filtre métricas por equipe ou departamento
• Rastreie custos por centro de custo
• Crie dashboards específicos da equipe
• Configure alertas para equipes específicas

# ❌ Inválido - contém espaços
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Válido - use sublinhados ou camelCase em vez disso
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Válido - codifique caracteres especiais em porcentagem se necessário
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

Configurações de Exemplo

# Depuração no console (intervalos de 1 segundo)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Múltiplos exportadores
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Diferentes endpoints/backends para métricas e logs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

# Apenas métricas (sem eventos/logs)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Apenas eventos/logs (sem métricas)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

​

Métricas e Eventos Disponíveis

​

Atributos Padrão

Todas as métricas e eventos compartilham estes atributos padrão:

​

Métricas

Claude Code exporta as seguintes métricas:

​

Detalhes das Métricas

​

Contador de Sessão

Incrementado no início de cada sessão.

Atributos:

• Todos os atributos padrão

​

Contador de Linhas de Código

Incrementado quando código é adicionado ou removido.

Atributos:

• Todos os atributos padrão
• type: ("added", "removed")

​

Contador de Pull Request

Incrementado ao criar pull requests via Claude Code.

Atributos:

• Todos os atributos padrão

​

Contador de Commit

Incrementado ao criar commits git via Claude Code.

Atributos:

• Todos os atributos padrão

​

Contador de Custo

Incrementado após cada solicitação de API.

Atributos:

• Todos os atributos padrão
• model: Identificador do modelo (por exemplo, “claude-3-5-sonnet-20241022”)

​

Contador de Token

Incrementado após cada solicitação de API.

Atributos:

• Todos os atributos padrão
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Identificador do modelo (por exemplo, “claude-3-5-sonnet-20241022”)

​

Contador de Decisão da Ferramenta de Edição de Código

Incrementado quando o usuário aceita ou rejeita o uso das ferramentas Edit, MultiEdit, Write ou NotebookEdit.

Atributos:

• Todos os atributos padrão
• tool: Nome da ferramenta ("Edit", "MultiEdit", "Write", "NotebookEdit")
• decision: Decisão do usuário ("accept", "reject")
• language: Linguagem de programação do arquivo editado (por exemplo, "TypeScript", "Python", "JavaScript", "Markdown"). Retorna "unknown" para extensões de arquivo não reconhecidas.

​

Contador de Tempo Ativo

Rastreia o tempo real gasto usando ativamente o Claude Code (não tempo ocioso). Esta métrica é incrementada durante interações do usuário, como digitar prompts ou receber respostas.

Atributos:

• Todos os atributos padrão

​

Eventos

Claude Code exporta os seguintes eventos via logs/eventos OpenTelemetry (quando OTEL_LOGS_EXPORTER está configurado):

​

Evento de Prompt do Usuário

Registrado quando um usuário envia um prompt.

Nome do Evento: claude_code.user_prompt

Atributos:

• Todos os atributos padrão
• event.name: "user_prompt"
• event.timestamp: Timestamp ISO 8601
• prompt_length: Comprimento do prompt
• prompt: Conteúdo do prompt (censurado por padrão, habilite com OTEL_LOG_USER_PROMPTS=1)

​

Evento de Resultado da Ferramenta

Registrado quando uma ferramenta completa a execução.

Nome do Evento: claude_code.tool_result

Atributos:

• Todos os atributos padrão
• event.name: "tool_result"
• event.timestamp: Timestamp ISO 8601
• tool_name: Nome da ferramenta
• success: "true" ou "false"
• duration_ms: Tempo de execução em milissegundos
• error: Mensagem de erro (se falhou)
• decision: Ou "accept" ou "reject"
• source: Fonte da decisão - "config", "user_permanent", "user_temporary", "user_abort", ou "user_reject"
• tool_parameters: String JSON contendo parâmetros específicos da ferramenta (quando disponível)
  • Para ferramenta Bash: inclui bash_command, full_command, timeout, description, sandbox

​

Evento de Solicitação de API

Registrado para cada solicitação de API para Claude.

Nome do Evento: claude_code.api_request

Atributos:

• Todos os atributos padrão
• event.name: "api_request"
• event.timestamp: Timestamp ISO 8601
• model: Modelo usado (por exemplo, “claude-3-5-sonnet-20241022”)
• cost_usd: Custo estimado em USD
• duration_ms: Duração da solicitação em milissegundos
• input_tokens: Número de tokens de entrada
• output_tokens: Número de tokens de saída
• cache_read_tokens: Número de tokens lidos do cache
• cache_creation_tokens: Número de tokens usados para criação de cache

​

Evento de Erro de API

Registrado quando uma solicitação de API para Claude falha.

Nome do Evento: claude_code.api_error

Atributos:

• Todos os atributos padrão
• event.name: "api_error"
• event.timestamp: Timestamp ISO 8601
• model: Modelo usado (por exemplo, “claude-3-5-sonnet-20241022”)
• error: Mensagem de erro
• status_code: Código de status HTTP (se aplicável)
• duration_ms: Duração da solicitação em milissegundos
• attempt: Número da tentativa (para solicitações repetidas)

​

Evento de Decisão da Ferramenta

Registrado quando uma decisão de permissão da ferramenta é tomada (aceitar/rejeitar).

Nome do Evento: claude_code.tool_decision

Atributos:

• Todos os atributos padrão
• event.name: "tool_decision"
• event.timestamp: Timestamp ISO 8601
• tool_name: Nome da ferramenta (por exemplo, “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit”, etc.)
• decision: Ou "accept" ou "reject"
• source: Fonte da decisão - "config", "user_permanent", "user_temporary", "user_abort", ou "user_reject"

​

Interpretando Dados de Métricas e Eventos

As métricas exportadas pelo Claude Code fornecem insights valiosos sobre padrões de uso e produtividade. Aqui estão algumas visualizações e análises comuns que você pode criar:

​

Monitoramento de Uso

​

Monitoramento de Custo

A métrica claude_code.cost.usage ajuda com:

• Rastreamento de tendências de uso entre equipes ou indivíduos
• Identificação de sessões de alto uso para otimização

​

Alertas e Segmentação

Alertas comuns a considerar:

• Picos de custo
• Consumo incomum de tokens
• Alto volume de sessões de usuários específicos

Todas as métricas podem ser segmentadas por user.account_uuid, organization.id, session.id, model e app.version.

​

Análise de Eventos

Os dados de eventos fornecem insights detalhados sobre interações do Claude Code:

Padrões de Uso de Ferramentas: Analise eventos de resultado de ferramentas para identificar:

• Ferramentas mais frequentemente usadas
• Taxas de sucesso das ferramentas
• Tempos médios de execução das ferramentas
• Padrões de erro por tipo de ferramenta

Monitoramento de Desempenho: Rastreie durações de solicitações de API e tempos de execução de ferramentas para identificar gargalos de desempenho.

​

Considerações de Backend

Sua escolha de backends de métricas e logs determinará os tipos de análises que você pode realizar:

​

Para Métricas:

• Bancos de dados de séries temporais (por exemplo, Prometheus): Cálculos de taxa, métricas agregadas
• Armazenamentos colunares (por exemplo, ClickHouse): Consultas complexas, análise de usuários únicos
• Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog): Consultas avançadas, visualização, alertas

​

Para Eventos/Logs:

• Sistemas de agregação de logs (por exemplo, Elasticsearch, Loki): Busca de texto completo, análise de logs
• Armazenamentos colunares (por exemplo, ClickHouse): Análise de eventos estruturados
• Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog): Correlação entre métricas e eventos

Para organizações que requerem métricas de Usuários Ativos Diários/Semanais/Mensais (DAU/WAU/MAU), considere backends que suportam consultas eficientes de valores únicos.

​

Informações do Serviço

Todas as métricas e eventos são exportados com os seguintes atributos de recurso:

• service.name: claude-code
• service.version: Versão atual do Claude Code
• os.type: Tipo do sistema operacional (por exemplo, linux, darwin, windows)
• os.version: String da versão do sistema operacional
• host.arch: Arquitetura do host (por exemplo, amd64, arm64)
• wsl.version: Número da versão WSL (presente apenas quando executando no Windows Subsystem for Linux)
• Nome do Medidor: com.anthropic.claude_code

​

Recursos de Medição de ROI

Para um guia abrangente sobre medição de retorno sobre investimento para Claude Code, incluindo configuração de telemetria, análise de custos, métricas de produtividade e relatórios automatizados, consulte o Guia de Medição de ROI do Claude Code. Este repositório fornece configurações Docker Compose prontas para uso, configurações Prometheus e OpenTelemetry, e modelos para gerar relatórios de produtividade integrados com ferramentas como Linear.

​

Considerações de Segurança/Privacidade

• Telemetria é opt-in e requer configuração explícita
• Informações sensíveis como chaves de API ou conteúdos de arquivos nunca são incluídas em métricas ou eventos
• Conteúdo de prompt do usuário é censurado por padrão - apenas o comprimento do prompt é registrado. Para habilitar o log de prompts do usuário, defina OTEL_LOG_USER_PROMPTS=1