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.
O suporte ao OpenTelemetry está atualmente em beta e os detalhes estão sujeitos a alterações.

​
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
Os intervalos de exportação padrão são 60 segundos para métricas e 5 segundos para logs. Durante a configuração, você pode querer usar intervalos mais curtos para fins de depuração. Lembre-se de redefinir estes para uso em produção.
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"
  }
}
Configurações gerenciadas podem ser distribuídas via MDM (Mobile Device Management) ou outras soluções de gerenciamento de dispositivos. Variáveis de ambiente definidas no arquivo de configurações gerenciadas têm alta precedência e não podem ser substituídas pelos usuários.

​
Detalhes da Configuração

​
Variáveis de Configuração Comuns

Variável de AmbienteDescriçãoValores de Exemplo
CLAUDE_CODE_ENABLE_TELEMETRYHabilita coleta de telemetria (obrigatório)1
OTEL_METRICS_EXPORTERTipo(s) de exportador de métricas (separados por vírgula)console, otlp, prometheus
OTEL_LOGS_EXPORTERTipo(s) de exportador de logs/eventos (separados por vírgula)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLProtocolo para exportador OTLP (todos os sinais)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint do coletor OTLP (todos os sinais)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLProtocolo para métricas (substitui geral)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTEndpoint de métricas OTLP (substitui geral)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLProtocolo para logs (substitui geral)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTEndpoint de logs OTLP (substitui geral)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSCabeçalhos de autenticação para OTLPAuthorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYChave do cliente para autenticação mTLSCaminho para arquivo de chave do cliente
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATECertificado do cliente para autenticação mTLSCaminho para arquivo de certificado do cliente
OTEL_METRIC_EXPORT_INTERVALIntervalo de exportação em milissegundos (padrão: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALIntervalo de exportação de logs em milissegundos (padrão: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSHabilitar logging do conteúdo de prompts do usuário (padrão: desabilitado)1 para habilitar

​
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:
Variável de AmbienteDescriçãoValor PadrãoExemplo para Desabilitar
OTEL_METRICS_INCLUDE_SESSION_IDIncluir atributo session.id nas métricastruefalse
OTEL_METRICS_INCLUDE_VERSIONIncluir atributo app.version nas métricasfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDIncluir atributo user.account_uuid nas métricastruefalse
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 é devido à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çõ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 da equipe
  • Configure alertas para equipes específicas
Requisitos importantes de formatação para OTEL_RESOURCE_ATTRIBUTES:A variável de ambiente OTEL_RESOURCE_ATTRIBUTES segue a especificação W3C Baggage, que tem requisitos de formatação rigorosos:
  • Espaços não são permitidos: Valores não podem conter espaços. Por exemplo, user.organizationName=My Company é inválido
  • Formato: Deve ser pares chave=valor separados por vírgula: key1=value1,key2=value2
  • Caracteres permitidos: Apenas caracteres US-ASCII excluindo caracteres de controle, espaços em branco, aspas duplas, vírgulas, ponto e vírgula e barras invertidas
  • Caracteres especiais: Caracteres fora do intervalo permitido devem ser codificados em porcentagem
Exemplos:
# ❌ 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"
Nota: Colocar aspas em todo o par chave=valor (por exemplo, "key=value with spaces") não é suportado pela especificação OpenTelemetry e resultará em atributos sendo prefixados com aspas.

​
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:
AtributoDescriçãoControlado Por
session.idIdentificador único da sessãoOTEL_METRICS_INCLUDE_SESSION_ID (padrão: true)
app.versionVersão atual do Claude CodeOTEL_METRICS_INCLUDE_VERSION (padrão: false)
organization.idUUID da organização (quando autenticado)Sempre incluído quando disponível
user.account_uuidUUID da conta (quando autenticado)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (padrão: true)
terminal.typeTipo de terminal (por exemplo, iTerm.app, vscode, cursor, tmux)Sempre incluído quando detectado

​
Métricas

Claude Code exporta as seguintes métricas:
Nome da MétricaDescriçãoUnidade
claude_code.session.countContagem de sessões CLI iniciadascount
claude_code.lines_of_code.countContagem de linhas de código modificadascount
claude_code.pull_request.countNúmero de pull requests criadoscount
claude_code.commit.countNúmero de commits git criadoscount
claude_code.cost.usageCusto da sessão Claude CodeUSD
claude_code.token.usageNúmero de tokens usadostokens
claude_code.code_edit_tool.decisionContagem de decisões de permissão da ferramenta de edição de códigocount
claude_code.active_time.totalTempo ativo total em segundoss

​
Detalhes das Métricas

​
Contador de Sessão

Incrementado no início de cada sessão. Atributos:

​
Contador de Linhas de Código

Incrementado quando código é adicionado ou removido. Atributos:

​
Contador de Pull Request

Incrementado ao criar pull requests via Claude Code. Atributos:

​
Contador de Commit

Incrementado ao criar commits git via Claude Code. Atributos:

​
Contador de Custo

Incrementado após cada requisiçã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 requisiçã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:

​
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
  • 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 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 (por exemplo, “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 (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 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 de 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

MétricaOportunidade de Análise
claude_code.token.usageDetalhar por type (entrada/saída), usuário, equipe ou modelo
claude_code.session.countRastrear adoção e engajamento ao longo do tempo
claude_code.lines_of_code.countMedir produtividade rastreando adições/remoções de código
claude_code.commit.count & claude_code.pull_request.countEntender impacto nos fluxos de trabalho de desenvolvimento

​
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
Métricas de custo são aproximações. Para dados oficiais de cobrança, consulte seu provedor de API (Anthropic Console, AWS Bedrock ou Google Cloud Vertex).

​
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 (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 logging de prompt do usuário, defina OTEL_LOG_USER_PROMPTS=1