​

OpenTelemetry no Claude Code

O Claude Code suporta métricas OpenTelemetry (OTel) para monitoramento e observabilidade. Este documento explica como habilitar e configurar o OTel para o Claude Code.

Todas as métricas são dados de séries temporais exportados através do protocolo padrão de métricas do OpenTelemetry. É responsabilidade do usuário garantir que seu backend de métricas esteja configurado adequadamente e que a granularidade de agregação atenda aos seus requisitos de monitoramento.

​

Início Rápido

Configure o OpenTelemetry usando variáveis de ambiente:

# 1. Habilitar telemetria
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Escolher um exportador
export OTEL_METRICS_EXPORTER=otlp       # Opções: otlp, prometheus, 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 intervalo de exportação (padrão: 600000ms/10min)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 segundos

# 6. Executar Claude Code
claude

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

​

Configuração de Administrador

Os administradores podem configurar as definições do OpenTelemetry para todos os usuários através do arquivo de configurações gerenciadas. Isso permite um controle centralizado das configurações de telemetria em toda a organização. Consulte a hierarquia de configuração 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_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 a cardinalidade:

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

​

Exemplos de Configurações

# 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

​

Métricas Disponíveis

O Claude Code exporta as seguintes métricas:

​

Detalhes das Métricas

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

• session.id: Identificador único de sessão (controlado por OTEL_METRICS_INCLUDE_SESSION_ID)
• app.version: Versão atual do Claude Code (controlado por OTEL_METRICS_INCLUDE_VERSION)
• organization.id: UUID da organização (quando autenticado)
• user.account_uuid: UUID da conta (quando autenticado, controlado por OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

​

1. Contador de Sessão

Emitido no início de cada sessão.

​

2. Contador de Linhas de Código

Emitido quando o código é adicionado ou removido.

• Atributo adicional: type ("added" ou "removed")

​

3. Contador de Pull Request

Emitido ao criar pull requests via Claude Code.

​

4. Contador de Commit

Emitido ao criar commits git via Claude Code.

​

5. Contador de Custo

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

• Atributo adicional: model

​

6. Contador de Token

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

• Atributos adicionais: type ("input", "output", "cacheRead", "cacheCreation") e model

​

Interpretando Dados de Métricas

Essas métricas fornecem insights sobre padrões de uso, produtividade e custos:

​

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.

​

Considerações sobre Backend

Para métricas DAU/WAU/MAU, escolha backends que suportem consultas eficientes de valores únicos.

​

Informações de 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

• A telemetria é opt-in e requer configuração explícita
• Informações sensíveis como chaves de API ou conteúdo de arquivos nunca são incluídas nas métricas