Monitoramento

​

Início rápido

# 1. Ativar 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

​

Configuração do administrador

{
  "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.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

​

Detalhes de configuração

​

Variáveis de configuração comuns

​

Controle de cardinalidade de métricas

​

Cabeçalhos dinâmicos

​

Configuração de configurações

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

​

Requisitos do script

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

​

Comportamento de atualização

​

Suporte a organizações multi-equipe

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

• 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

# ❌ 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 em percentual caracteres especiais se necessário
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

Configurações de exemplo

# Depuração de 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.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.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

• prompt.id: UUID correlacionando um prompt do usuário com todos os eventos subsequentes até o próximo prompt. Veja Atributos de correlação de evento.
• workspace.host_paths: diretórios de workspace do host selecionados no aplicativo desktop, como um array de string

​

Métricas

​

Detalhes das métricas

​

Contador de sessão

• Todos os atributos padrão

​

Contador de linhas de código

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

​

Contador de pull request

• Todos os atributos padrão

​

Contador de commit

• Todos os atributos padrão

​

Contador de custo

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

​

Contador de token

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

​

Contador de decisão da ferramenta de edição de código

• Todos os atributos padrão
• tool_name: Nome da ferramenta ("Edit", "Write", "NotebookEdit")
• decision: Decisão do usuário ("accept", "reject")
• source: Fonte de decisão - "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject"
• language: Linguagem de programação do arquivo editado, como "TypeScript", "Python", "JavaScript", ou "Markdown". Retorna "unknown" para extensões de arquivo não reconhecidas.

​

Contador de tempo ativo

• Todos os atributos padrão
• type: "user" para interações de teclado, "cli" para execução de ferramentas e respostas de IA

​

Eventos

​

Atributos de correlação de evento

​

Evento de prompt do usuário

• Todos os atributos padrão
• event.name: "user_prompt"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• prompt_length: Comprimento do prompt
• prompt: Conteúdo do prompt (reduzido por padrão, ativar com OTEL_LOG_USER_PROMPTS=1)

​

Evento de resultado da ferramenta

• Todos os atributos padrão
• event.name: "tool_result"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• tool_name: Nome da ferramenta
• success: "true" ou "false"
• duration_ms: Tempo de execução em milissegundos
• error: Mensagem de erro (se falhou)
• decision_type: Ou "accept" ou "reject"
• decision_source: Fonte de decisão - "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject"
• tool_result_size_bytes: Tamanho do resultado da ferramenta em bytes
• mcp_server_scope: Identificador de escopo do servidor MCP (para ferramentas MCP)
• tool_parameters: String JSON contendo parâmetros específicos da ferramenta (quando disponível)
  • Para ferramenta Bash: inclui bash_command, full_command, timeout, description, dangerouslyDisableSandbox, e git_commit_id (o SHA do commit, quando um comando git commit é bem-sucedido)
  • Para ferramentas MCP (quando OTEL_LOG_TOOL_DETAILS=1): inclui mcp_server_name, mcp_tool_name
  • Para ferramenta Skill (quando OTEL_LOG_TOOL_DETAILS=1): inclui skill_name
• tool_input (quando OTEL_LOG_TOOL_DETAILS=1): Argumentos de ferramenta serializados em JSON. Valores individuais com mais de 512 caracteres são truncados, e a carga útil completa é limitada a ~4 K caracteres. Aplica-se a todas as ferramentas, incluindo ferramentas MCP.

​

Evento de solicitação de API

• Todos os atributos padrão
• event.name: "api_request"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• model: Modelo usado (por exemplo, “claude-sonnet-4-6”)
• 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
• speed: "fast" ou "normal", indicando se o modo rápido estava ativo

​

Evento de erro de API

• Todos os atributos padrão
• event.name: "api_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• model: Modelo usado (por exemplo, “claude-sonnet-4-6”)
• error: Mensagem de erro
• status_code: Código de status HTTP como string, ou "undefined" para erros não-HTTP
• duration_ms: Duração da solicitação em milissegundos
• attempt: Número de tentativa (para solicitações retentadas)
• speed: "fast" ou "normal", indicando se o modo rápido estava ativo

​

Evento de decisão da ferramenta

• Todos os atributos padrão
• event.name: "tool_decision"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• tool_name: Nome da ferramenta (por exemplo, “Read”, “Edit”, “Write”, “NotebookEdit”)
• decision: Ou "accept" ou "reject"
• source: Fonte de decisão - "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject"

​

Interpretar dados de métricas e eventos

​

Monitoramento de uso

​

Monitoramento de custo

• 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

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

​

Análise de eventos

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

​

Considerações de backend

​

Para métricas

• Bancos de dados de série temporal (por exemplo, Prometheus): Cálculos de taxa, métricas agregadas
• Armazenamentos colunares (por exemplo, ClickHouse): Consultas complexas, análise de usuário único
• 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

​

Informações de serviço

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

​

Recursos de medição de ROI

​

Segurança e privacidade

• A telemetria é opt-in e requer configuração explícita
• Conteúdos de arquivo brutos e trechos de código não são incluídos em métricas ou eventos. Eventos de execução de ferramentas incluem comandos bash e caminhos de arquivo no campo tool_parameters, que podem conter valores sensíveis. Se seus comandos podem incluir segredos, configure seu backend de telemetria para filtrar ou reduzir tool_parameters
• Quando autenticado via OAuth, user.email é incluído em atributos de telemetria. Se isso for uma preocupação para sua organização, trabalhe com seu backend de telemetria para filtrar ou reduzir este campo
• O conteúdo do prompt do usuário não é coletado por padrão. Apenas o comprimento do prompt é registrado. Para incluir conteúdo do prompt, defina OTEL_LOG_USER_PROMPTS=1
• Argumentos de entrada de ferramenta não são registrados por padrão. Para incluí-los, defina OTEL_LOG_TOOL_DETAILS=1. Quando ativado, eventos tool_result incluem nomes de servidor MCP/ferramenta e nomes de skill mais um atributo tool_input com caminhos de arquivo, URLs, padrões de busca e outros argumentos. Valores individuais com mais de 512 caracteres são truncados e o total é limitado a ~4 K caracteres, mas os argumentos ainda podem conter valores sensíveis. Configure seu backend de telemetria para filtrar ou reduzir tool_input conforme necessário

​

Monitorar Claude Code no Amazon Bedrock