Monitoramento

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

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, none
export OTEL_LOGS_EXPORTER=otlp          # Opções: otlp, console, none

# 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

​

Autenticação mTLS

​

Controle de cardinalidade de métricas

​

Rastreamentos (beta)

​

Hierarquia de span

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requer rastreamento beta detalhado)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (ferramenta Task) spans claude_code.llm_request / claude_code.tool do subagente

​

Atributos de span

​

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
• start_type: Como a sessão foi iniciada. Um de "fresh", "resume" ou "continue"

​

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”)
• query_source: Categoria do subsistema que emitiu a solicitação. Um de "main", "subagent" ou "auxiliary"
• speed: "fast" quando a solicitação usou modo rápido. Ausente caso contrário
• effort: Nível de esforço aplicado à solicitação: "low", "medium", "high", "xhigh" ou "max". Ausente quando o modelo não suporta esforço.
• agent.name: Tipo de subagente que emitiu a solicitação. Nomes de agente integrados e agentes de plugins do marketplace oficial aparecem verbatim. Outros nomes de agente definidos pelo usuário são substituídos por "custom". Ausente quando a solicitação não foi emitida por um tipo de subagente nomeado.
• skill.name: Skill ativa para a solicitação, definida pela ferramenta Skill, um comando / ou herdada por um subagente gerado. Nomes de skill integrados, agrupados, definidos pelo usuário e de plugins do marketplace oficial aparecem verbatim. Nomes de skill de plugin de terceiros são substituídos por "third-party". Ausente quando nenhuma skill está ativa.
• plugin.name: Plugin proprietário quando a skill ativa ou subagente é fornecido por um plugin. Nomes de plugin do marketplace oficial aparecem verbatim. Nomes de plugin de terceiros são substituídos por "third-party". Ausente quando nem a skill nem o subagente têm um plugin proprietário.
• marketplace.name: Marketplace do qual o plugin proprietário foi instalado. Emitido apenas para plugins do marketplace oficial. Ausente caso contrário.

​

Contador de token

• Todos os atributos padrão
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Identificador do modelo (por exemplo, “claude-sonnet-4-6”)
• query_source: Categoria do subsistema que emitiu a solicitação. Um de "main", "subagent" ou "auxiliary"
• speed: "fast" quando a solicitação usou modo rápido. Ausente caso contrário
• effort: Nível de esforço aplicado à solicitação. Veja Contador de custo para detalhes.
• agent.name, skill.name, plugin.name, marketplace.name: Atribuição de skill, plugin e agente para a solicitação. Veja Contador de custo para definições e comportamento de redação.

​

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: Onde a decisão veio. Um de "config", "hook", "user_permanent", "user_temporary", "user_abort" ou "user_reject". Veja o Evento de decisão da ferramenta para o que cada valor significa.
• 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)
• command_name: Nome do comando quando o prompt invoca um. Nomes de comando integrados e agrupados como compact ou debug são emitidos como estão; aliases como reset emitem como digitados em vez do nome canônico. Nomes de comando customizado, plugin e MCP colapsam para custom ou mcp a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido
• command_source: Origem do comando quando presente: builtin, custom ou mcp. Comandos fornecidos por plugin relatam como custom

​

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
• tool_use_id: Identificador único para esta invocação de ferramenta. Corresponde ao tool_use_id passado para hooks, permitindo correlação entre eventos OTel e dados capturados por hook.
• success: "true" ou "false"
• duration_ms: Tempo de execução em milissegundos
• error_type: String de categoria de erro quando a ferramenta falhou, como "Error:ENOENT" ou "ShellError"
• error (quando OTEL_LOG_TOOL_DETAILS=1): Mensagem de erro completa quando a ferramenta falhou
• decision_type: Ou "accept" ou "reject"
• decision_source: Onde a decisão veio. Um de "config", "hook", "user_permanent", "user_temporary", "user_abort" ou "user_reject". Veja o Evento de decisão da ferramenta para o que cada valor significa.
• tool_input_size_bytes: Tamanho da entrada da ferramenta serializada em JSON em bytes
• 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 (quando OTEL_LOG_TOOL_DETAILS=1): String JSON contendo parâmetros específicos da ferramenta:
  • 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: inclui mcp_server_name, mcp_tool_name
  • Para ferramenta Skill: inclui skill_name
  • Para ferramenta Task: inclui subagent_type
• 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
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta, como "req_011...". Presente apenas quando a API retorna um.
• speed: "fast" ou "normal", indicando se o modo rápido estava ativo
• query_source: Subsistema que emitiu a solicitação, como "repl_main_thread", "compact" ou um nome de subagente
• effort: Nível de esforço aplicado à solicitação: "low", "medium", "high", "xhigh" ou "max". Ausente quando o modelo não suporta esforço.

​

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 número. Ausente para erros não-HTTP, como falhas de conexão.
• duration_ms: Duração da solicitação em milissegundos
• attempt: Número total de tentativas feitas, incluindo a solicitação inicial (1 significa que nenhuma tentativa ocorreu)
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta, como "req_011...". Presente apenas quando a API retorna um.
• speed: "fast" ou "normal", indicando se o modo rápido estava ativo
• query_source: Subsistema que emitiu a solicitação, como "repl_main_thread", "compact" ou um nome de subagente
• effort: Nível de esforço aplicado à solicitação. Ausente quando o modelo não suporta esforço.

​

Evento de corpo de solicitação de API

• Todos os atributos padrão
• event.name: "api_request_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• body: Parâmetros de solicitação da API Messages serializados em JSON (prompt do sistema, mensagens, ferramentas, etc.), truncados em 60 KB. Conteúdo de pensamento estendido em turnos anteriores do assistente é reduzido. Emitido apenas em modo inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Caminho absoluto para um arquivo <dir>/<uuid>.request.json contendo o corpo não truncado. Emitido apenas em modo arquivo (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Comprimento do corpo não truncado. Bytes UTF-8 quando OTEL_LOG_RAW_API_BODIES=file:<dir>, ou unidades de código UTF-16 quando =1
• body_truncated: "true" quando truncamento inline ocorreu. Ausente em modo arquivo e quando nenhum truncamento ocorreu.
• model: Identificador do modelo dos parâmetros de solicitação
• query_source: Subsistema que emitiu a solicitação (por exemplo, "compact")

​

Evento de corpo de resposta de API

• Todos os atributos padrão
• event.name: "api_response_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• body: Resposta da API Messages serializada em JSON (id, blocos de conteúdo, uso, razão de parada), truncada em 60 KB. Conteúdo de pensamento estendido é reduzido. Emitido apenas em modo inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Caminho absoluto para um arquivo <dir>/<request_id>.response.json contendo o corpo não truncado. Emitido apenas em modo arquivo (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Comprimento do corpo não truncado. Bytes UTF-8 quando OTEL_LOG_RAW_API_BODIES=file:<dir>, ou unidades de código UTF-16 quando =1
• body_truncated: "true" quando truncamento inline ocorreu. Ausente em modo arquivo e quando nenhum truncamento ocorreu.
• model: Identificador do modelo
• query_source: Subsistema que emitiu a solicitação
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta, como "req_011...". Presente apenas quando a API retorna um.

​

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”)
• tool_use_id: Identificador único para esta invocação de ferramenta. Corresponde ao tool_use_id passado para hooks, permitindo correlação entre eventos OTel e dados capturados por hook.
• decision: Ou "accept" ou "reject"
• source: Onde a decisão veio:
  • "config": Decidido automaticamente sem avisar, baseado em configurações de projeto, regras de permissão nas configurações pessoais do usuário, política gerenciada corporativa, sinalizadores --allowedTools ou --disallowedTools, o modo de permissão ativo, uma concessão com escopo de sessão de um prompt anterior na mesma sessão CLI interativa, ou porque a ferramenta é inerentemente segura. O evento não indica qual dessas fontes correspondeu.
  • "hook": Um hook PreToolUse ou PermissionRequest retornou a decisão.
  • "user_permanent": Emitido quando o usuário escolheu “Sim, e não pergunte novamente para …” em um aviso de permissão, que salva uma regra de permissão em suas configurações pessoais. Na CLI interativa isso é emitido apenas para essa escolha em si; chamadas posteriores que correspondem à regra salva emitem "config" em vez disso. No Agent SDK ou sessões não-interativas -p, tanto a escolha inicial quanto correspondências de regra posteriores emitem "user_permanent". Tratado como uma aceitação.
  • "user_temporary": Emitido quando o usuário escolheu “Sim” em um aviso de permissão para uma aprovação única, ou escolheu uma das opções ”… durante esta sessão” em um aviso de edição ou leitura de arquivo. Na CLI interativa isso é emitido apenas para a escolha em si; chamadas posteriores permitidas por essa concessão com escopo de sessão emitem "config" em vez disso. No Agent SDK ou sessões não-interativas -p, tanto a escolha quanto correspondências posteriores emitem "user_temporary". Tratado como uma aceitação.
  • "user_abort": Emitido quando o usuário descartou o aviso de permissão sem responder. Tratado como uma rejeição.
  • "user_reject": Emitido quando o usuário escolheu “Não” quando solicitado, ou uma chamada correspondeu a uma regra de negação em suas configurações pessoais. Tratado como uma rejeição.

​

Evento de modo de permissão alterado

• Todos os atributos padrão
• event.name: "permission_mode_changed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• from_mode: O modo de permissão anterior, por exemplo "default", "plan", "acceptEdits", "auto" ou "bypassPermissions"
• to_mode: O novo modo de permissão
• trigger: O que causou a mudança. Um de "shift_tab", "exit_plan_mode", "auto_gate_denied" ou "auto_opt_in". Ausente quando a transição se origina do SDK ou bridge

​

Evento de autenticação

• Todos os atributos padrão
• event.name: "auth"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• action: "login" ou "logout"
• success: "true" ou "false"
• auth_method: Método de autenticação, como "oauth"
• error_category: Tipo de erro categórico quando a ação falhou. A mensagem de erro bruta nunca é incluída
• status_code: Código de status HTTP como string quando a ação falhou com um erro HTTP

​

Evento de conexão do servidor MCP

• Todos os atributos padrão
• event.name: "mcp_server_connection"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• status: "connected", "failed" ou "disconnected"
• transport_type: Transporte do servidor, como "stdio", "sse" ou "http"
• server_scope: Escopo em que o servidor está configurado, como "user", "project" ou "local"
• duration_ms: Duração da tentativa de conexão em milissegundos
• error_code: Código de erro quando a conexão falhou
• server_name (quando OTEL_LOG_TOOL_DETAILS=1): Nome do servidor configurado
• error (quando OTEL_LOG_TOOL_DETAILS=1): Mensagem de erro completa quando a conexão falhou

​

Evento de erro interno

• Todos os atributos padrão
• event.name: "internal_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• error_name: Nome da classe de erro, como "TypeError" ou "SyntaxError"
• error_code: Código errno Node.js como "ENOENT" quando presente no erro

​

Evento de plugin instalado

• Todos os atributos padrão
• event.name: "plugin_installed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• marketplace.is_official: "true" se o marketplace é um marketplace oficial Anthropic, "false" caso contrário
• install.trigger: "cli" ou "ui"
• plugin.name: Nome do plugin instalado. Para marketplaces de terceiros isso é incluído apenas quando OTEL_LOG_TOOL_DETAILS=1
• plugin.version: Versão do plugin quando declarada na entrada do marketplace. Para marketplaces de terceiros isso é incluído apenas quando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace do qual o plugin foi instalado. Para marketplaces de terceiros isso é incluído apenas quando OTEL_LOG_TOOL_DETAILS=1

​

Evento de plugin carregado

• Todos os atributos padrão
• event.name: "plugin_loaded"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• plugin.name: nome do plugin. Para plugins fora do marketplace oficial e pacote integrado o valor é "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: marketplace do qual o plugin foi instalado, quando conhecido. Reduzido para "third-party" sob a mesma condição que plugin.name
• plugin.version: versão do manifesto do plugin. Incluído apenas quando o nome não é reduzido e o manifesto declara uma versão
• plugin.scope: categoria de proveniência para o plugin: "official", "org", "user-local" ou "default-bundle"
• enabled_via: como o plugin veio a ser ativado: "default-enable", "org-policy", "seed-mount" ou "user-install"
• plugin_id_hash: hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar quantos plugins de terceiros distintos são carregados em toda a sua frota sem registrar seus nomes
• has_hooks: se o plugin contribui hooks
• has_mcp: se o plugin contribui servidores MCP
• skill_path_count: número de diretórios de skill que o plugin declara
• command_path_count: número de diretórios de comando que o plugin declara
• agent_path_count: número de diretórios de agente que o plugin declara

​

Evento de skill ativado

• Todos os atributos padrão
• event.name: "skill_activated"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• skill.name: Nome da skill. Para skills definidas pelo usuário e de plugin de terceiros o valor é o placeholder "custom_skill" a menos que OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger: Como a skill foi acionada ("user-slash", "claude-proactive" ou "nested-skill")
• skill.source: De onde a skill foi carregada (por exemplo, "bundled", "userSettings", "projectSettings", "plugin")
• plugin.name (quando OTEL_LOG_TOOL_DETAILS=1 ou o plugin é de um marketplace oficial): Nome do plugin proprietário quando a skill é fornecida por um plugin
• marketplace.name (quando OTEL_LOG_TOOL_DETAILS=1 ou o plugin é de um marketplace oficial): Marketplace do qual o plugin proprietário foi instalado, quando a skill é fornecida por um plugin

​

Evento de menção @

• Todos os atributos padrão
• event.name: "at_mention"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• mention_type: Tipo de menção ("file", "directory", "agent", "mcp_resource")
• success: Se a menção foi resolvida com sucesso ("true" ou "false")

​

Evento de tentativas de API esgotadas

• Todos os atributos padrão
• event.name: "api_retries_exhausted"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• model: Modelo usado
• error: Mensagem de erro final
• status_code: Código de status HTTP como número. Ausente para erros não-HTTP.
• total_attempts: Número total de tentativas feitas
• total_retry_duration_ms: Tempo total de parede em todas as tentativas
• speed: "fast" ou "normal"

​

Evento de hook registrado

• Todos os atributos padrão
• event.name: "hook_registered"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• hook_event: tipo de evento de hook, como "PreToolUse" ou "PostToolUse"
• hook_type: tipo de implementação de hook: "command", "prompt", "mcp_tool", "http" ou "agent"
• hook_source: onde o hook é definido: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings" ou "pluginHook"
• hook_matcher (quando OTEL_LOG_TOOL_DETAILS=1): a string matcher da configuração do hook, quando uma está definida
• plugin.name (quando hook_source é "pluginHook"): nome do plugin contribuidor. Para plugins fora do marketplace oficial e pacote integrado o valor é "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1
• plugin_id_hash (quando hook_source é "pluginHook"): hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar plugins contribuidores distintos sem registrar seus nomes

​

Evento de início de execução de hook

• Todos os atributos padrão
• event.name: "hook_execution_start"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• hook_event: Tipo de evento de hook, como "PreToolUse" ou "PostToolUse"
• hook_name: Nome completo do hook incluindo matcher, como "PreToolUse:Write"
• num_hooks: Número de comandos de hook correspondentes
• managed_only: "true" quando apenas hooks de política gerenciada são permitidos
• hook_source: "policySettings" ou "merged"
• hook_definitions: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e OTEL_LOG_TOOL_DETAILS=1 estão ambos ativados

​

Evento de conclusão de execução de hook

• Todos os atributos padrão
• event.name: "hook_execution_complete"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• hook_event: Tipo de evento de hook
• hook_name: Nome completo do hook incluindo matcher
• num_hooks: Número de comandos de hook correspondentes
• num_success: Contagem que completou com sucesso
• num_blocking: Contagem que retornou uma decisão de bloqueio
• num_non_blocking_error: Contagem que falhou sem bloquear
• num_cancelled: Contagem cancelada antes da conclusão
• total_duration_ms: Duração de parede de todos os hooks correspondentes
• managed_only: "true" quando apenas hooks de política gerenciada são permitidos
• hook_source: "policySettings" ou "merged"
• hook_definitions: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e OTEL_LOG_TOOL_DETAILS=1 estão ambos ativados

​

Evento de compactação

• Todos os atributos padrão
• event.name: "compaction"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• trigger: "auto" ou "manual"
• success: "true" ou "false"
• duration_ms: Duração da compactação
• pre_tokens: Contagem aproximada de tokens antes da compactação
• post_tokens: Contagem aproximada de tokens após compactação
• error: Mensagem de erro quando a compactação falhou

​

Evento de pesquisa de feedback

• Todos os atributos padrão
• event.name: "feedback_survey"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• event_type: Evento do ciclo de vida da pesquisa, por exemplo "appeared", "responded" ou "transcript_prompt_appeared"
• appearance_id: ID único vinculando os eventos emitidos para uma instância de pesquisa
• survey_type: Qual pesquisa produziu o evento. "session" é o prompt de classificação “Como Claude está se saindo?”
• response: A seleção do usuário em eventos responded
• enabled_via_override: true quando CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL está definido. Emitido como um booleano, não uma string. Presente em eventos de pesquisa session. Filtre neste atributo para confirmar que a substituição é aplicada em toda a frota

​

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
• Atribuição de gastos a skills, plugins ou tipos de subagente específicos via atributos skill.name, plugin.name e agent.name

​

Alertas e segmentação

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

​

Detectar esgotamento de tentativas

​

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

​

Eventos de auditoria de segurança

​

Atribuir ações a usuários

export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

​

Auditoria de atividade MCP

​

Mapear questões de segurança para eventos

​

Enviar eventos para um SIEM

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

​

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

​

Para rastreamentos

• Sistemas de rastreamento distribuído (por exemplo, Jaeger, Zipkin, Grafana Tempo): Visualização de span, waterfalls de solicitação, análise de latência
• Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog): Busca de rastreamento e correlação com métricas e logs

​

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 exportação OpenTelemetry para seu backend é opt-in e requer configuração explícita. Para a telemetria operacional separada da Anthropic e como desabilitá-la, consulte Uso de dados
• Conteúdos de arquivo brutos e trechos de código não são incluídos em métricas ou eventos. Os spans de rastreamento são um caminho de dados separado: veja o ponto OTEL_LOG_TOOL_CONTENT abaixo
• 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 e parâmetros não são registrados por padrão. Para incluí-los, defina OTEL_LOG_TOOL_DETAILS=1. Quando ativado, eventos tool_result incluem um atributo tool_parameters com comandos Bash, nomes de servidor MCP e ferramenta, e nomes de skill, mais um atributo tool_input com caminhos de arquivo, URLs, padrões de busca e outros argumentos. Eventos user_prompt incluem o command_name verbatim para comandos customizado, plugin e MCP. Spans de rastreamento incluem o mesmo atributo tool_input e atributos derivados de entrada como file_path. 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 esses atributos conforme necessário
• O conteúdo de entrada e saída de ferramenta não é registrado em spans de rastreamento por padrão. Para incluí-lo, defina OTEL_LOG_TOOL_CONTENT=1. Quando ativado, eventos de span incluem conteúdo completo de entrada e saída de ferramenta truncado em 60 KB por span. Isso pode incluir conteúdos de arquivo brutos de resultados da ferramenta Read e saída de comando Bash. Configure seu backend de telemetria para filtrar ou reduzir esses atributos conforme necessário
• Corpos de solicitação e resposta da API Anthropic Messages brutos não são registrados por padrão. Para incluí-los, defina OTEL_LOG_RAW_API_BODIES. Com =1, cada chamada de API emite eventos de log api_request_body e api_response_body cujo atributo body é a carga útil serializada em JSON, truncada em 60 KB. Com =file:<dir>, corpos não truncados são escritos em arquivos .request.json e .response.json sob esse diretório e os eventos carregam um caminho body_ref em vez do corpo inline. Envie o diretório com um coletor de log ou sidecar em vez de através do fluxo de telemetria. Em ambos os modos, os corpos contêm o histórico de conversa completo (prompt do sistema, cada turno anterior de usuário e assistente, resultados de ferramenta), então ativar isso implica consentimento para tudo que os outros sinalizadores de conteúdo OTEL_LOG_* revelariam. O conteúdo de pensamento estendido do Claude é sempre reduzido desses corpos independentemente de outras configurações

​

Monitorar Claude Code no Amazon Bedrock