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 configurações 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: /etc/claude-code/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 em seu backend de métricas. Menor cardinalidade geralmente significa melhor desempenho e menores custos de armazenamento, mas dados menos granulares para análise.

​

Suporte a Organizações 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 de equipe
• Configure alertas para equipes específicas

​

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 requisição de API.

Atributos:

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

​

Contador de Token

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

Atributos:

• Todos os atributos padrão
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Identificador do modelo (ex: “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 (ex: "TypeScript", "Python", "JavaScript", "Markdown"). Retorna "unknown" para extensões de arquivo não reconhecidas.

​

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 submete 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
• name: Nome da ferramenta
• success: "true" ou "false"
• duration_ms: Tempo de execução em milissegundos
• error: Mensagem de erro (se falhou)

​

Evento de Requisição de API

Registrado para cada requisiçã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 (ex: “claude-3-5-sonnet-20241022”)
• cost_usd: Custo estimado em USD
• duration_ms: Duração da requisiçã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 requisiçã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 (ex: “claude-3-5-sonnet-20241022”)
• error: Mensagem de erro
• status_code: Código de status HTTP (se aplicável)
• duration_ms: Duração da requisição em milissegundos
• attempt: Número da tentativa (para requisiçõ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 (ex: “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 requisiçõ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 (ex: Prometheus): Cálculos de taxa, métricas agregadas
• Armazenamentos colunares (ex: ClickHouse): Consultas complexas, análise de usuários únicos
• Plataformas de observabilidade completas (ex: Honeycomb, Datadog): Consultas avançadas, visualização, alertas

​

Para Eventos/Logs:

• Sistemas de agregação de logs (ex: Elasticsearch, Loki): Busca de texto completo, análise de logs
• Armazenamentos colunares (ex: ClickHouse): Análise de eventos estruturados
• Plataformas de observabilidade completas (ex: 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 são exportadas com:

• Nome do Serviço: claude-code
• Versão do Serviço: Versão atual do Claude Code
• Nome do Medidor: com.anthropic.claude_code

​

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 prompt do usuário é censurado por padrão - apenas o comprimento do prompt é registrado. Para habilitar o logging de prompts do usuário, defina OTEL_LOG_USER_PROMPTS=1