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, 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 Agent) 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)\"}"

• Saída de /status
• O log de depuração, ao executar com --debug ou após executar /debug na sessão
• stderr, em sessões não-interativas iniciadas com -p

​

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

export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

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
• workflow.run_id: identificador de execução, prefixado com wf_, nos eventos de API e ferramenta emitidos por agentes que pertencem a uma execução de ferramenta Workflow. Filtrando eventos por um workflow.run_id reconstrói as solicitações de API e resultados de ferramentas dessa execução. O identificador cobre os agentes que o script de workflow gera e quaisquer agentes que esses gerem por sua vez, como invocações de skill. Ele corresponde ao identificador de execução relatado no resultado da ferramenta Workflow. Ausente em todos os outros eventos. Requer Claude Code v2.1.202 ou posterior
• workflow.name: nome do workflow, o meta.name do seu script, emitido junto com workflow.run_id. Nomes de workflow integrados aparecem verbatim quando a execução executa o script integrado não modificado. Nomes criados pelo usuário, incluindo cópias editadas de scripts integrados, são substituídos por custom a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido. Requer Claude Code v2.1.202 ou posterior

​

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", "continue" ou "agents_view". O valor "agents_view" identifica o processo do painel claude agents, uma UI local lançada pelo usuário em vez de uma sessão conversacional. Filtre neste valor para separar lançamentos de processo de UI de sessões conversacionais em seus painéis.

​

Contador de linhas de código

• Todos os atributos padrão
• type: ("added", "removed")
• model: Identificador do modelo para o modelo que fez a alteração (por exemplo, “claude-sonnet-5”)

​

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-5”)
• 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.
• mcp_server.name: Servidor MCP cuja ferramenta foi executada na rodada que produziu esta solicitação. Nomes de servidor integrados, proxied por claude.ai e do registro oficial aparecem verbatim. Nomes de servidor configurados pelo usuário são substituídos por "custom". Ausente quando nenhuma ferramenta MCP foi executada.
• mcp_tool.name: Ferramenta MCP que foi executada na rodada que produziu esta solicitação, com a mesma redação que mcp_server.name. Ausente quando nenhuma ferramenta MCP foi executada.

​

Contador de token

• Todos os atributos padrão
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Identificador do modelo (por exemplo, “claude-sonnet-5”)
• 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, mcp_server.name, mcp_tool.name: Atribuição de skill, plugin, agente e MCP 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. Defina OTEL_LOG_USER_PROMPTS=1 para incluí-lo
• 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 resposta do assistente

• Todos os atributos padrão
• event.name: "assistant_response"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• response_length: Comprimento do texto de resposta em caracteres
• response: Texto de resposta, truncado em 60 KB. Reduzido para <REDACTED> por padrão. Defina OTEL_LOG_ASSISTANT_RESPONSES=1 para incluí-lo. Quando OTEL_LOG_ASSISTANT_RESPONSES não está definido, OTEL_LOG_USER_PROMPTS controla isso em vez disso, então defina OTEL_LOG_ASSISTANT_RESPONSES=0 para manter respostas reduzidas enquanto o registro de prompt está ativado
• model: Identificador do modelo (por exemplo, “claude-sonnet-5”)
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta. Presente apenas quando a API retorna um
• query_source: Subsistema que emitiu a solicitação, como "repl_main_thread", "compact" ou um nome de subagente

​

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: Sempre "accept", já que este evento é emitido apenas após a ferramenta ser executada. Chamadas rejeitadas não produzem um resultado de ferramenta
• decision_source: Onde a decisão de permissão veio. Um de "config", "hook", "user_permanent" ou "user_temporary". Veja o Evento de decisão da ferramenta para o que cada valor significa. As fontes apenas de rejeição "user_abort" e "user_reject" nunca aparecem neste evento.
• 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 ferramenta WorkspaceBash: inclui bash_command, full_command, timeout
  • Para ferramentas MCP: inclui mcp_server_name, mcp_tool_name
  • Para ferramenta Skill: inclui skill_name
  • Para ferramenta Agent ou ferramenta Task legada: 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-5”)
• 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.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja Contador de custo para definições e comportamento de redaçã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-5”)
• 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.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja Contador de custo para definições e comportamento de redação.

​

Evento de recusa de API

• Todos os atributos padrão
• event.name: "api_refusal"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• model: Identificador do modelo da 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.
• query_source: Subsistema que emitiu a solicitação, como "repl_main_thread", "compact" ou um nome de subagente. Veja api_request para definições.
• speed: Ou "fast" quando Fast mode está ativo, ou "normal"
• attempt: Número de tentativa de repetição. A primeira tentativa é 1.
• effort: Nível de esforço aplicado à solicitação. Ausente quando o modelo não suporta esforço.
• server_fallback_hop: true quando o fallback de modelo do lado do servidor da API já tentou novamente esta recusa em um modelo diferente, então o usuário não viu esta recusa particular. false quando a solicitação terminou em uma recusa. Uma única rodada pode emitir tanto um evento hop true quanto um evento final false posterior quando o modelo de fallback também recusa.
• has_category: true quando a resposta da API carregava um stop_details.category de "cyber", "bio", "frontier_llm" ou "reasoning_extraction". false quando a resposta não carregava categoria ou um valor fora desse conjunto. Ausente quando server_fallback_hop é true, porque blocos hop não carregam stop_details.
• has_explanation: true quando a resposta da API carregava um stop_details.explanation, caso contrário false. Ausente quando server_fallback_hop é true.
• category: O valor stop_details.category da resposta da API. Um de "cyber", "bio", "frontier_llm" ou "reasoning_extraction". Presente apenas quando OTEL_LOG_TOOL_DETAILS=1 está definido e has_category é true.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja Contador de custo para definições e comportamento de redaçã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. Na CLI interativa isso é emitido apenas para essa escolha em si; chamadas que correspondem a uma regra de negação nas configurações pessoais do usuário emitem "config" em vez disso. No Agent SDK ou sessões não-interativas -p, chamadas que correspondem a uma regra de negação em configurações pessoais emitem "user_reject". Tratado como uma rejeição.
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): String JSON contendo parâmetros específicos da ferramenta. Mesma forma que o Evento de resultado da ferramenta, menos campos pós-execução como git_commit_id. Os valores podem diferir de tool_result para uma chamada aceita se a decisão de permissão reescrever a entrada da ferramenta via updatedInput. Use este atributo para ver qual comando foi rejeitado quando decision é "reject".
  • Para ferramenta Bash: inclui bash_command, full_command, timeout, description, dangerouslyDisableSandbox
  • Para ferramenta WorkspaceBash: inclui bash_command, full_command, timeout
  • Para ferramentas MCP: inclui mcp_server_name, mcp_tool_name
  • Para ferramenta Skill: inclui skill_name
  • Para ferramenta Agent ou ferramenta Task legada: inclui subagent_type

​

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
• is_plugin: true quando o servidor é fornecido por um plugin, false caso contrário
• plugin_id_hash (quando is_plugin é true): Hash estável do nome do plugin e marketplace, para agrupar eventos por plugin sem expor o nome
• plugin.name (quando is_plugin é true): Nome do plugin que fornece o servidor. Para plugins de terceiros isso é a string literal "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1; isso protege nomes de plugins de terceiros de aparecerem em logs por padrão. Plugins de fontes oficiais Anthropic são sempre identificados por nome. Os atributos plugin_id_hash e plugin.name fluem para seu próprio backend de monitoramento e não são enviados para Anthropic
• 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
• host_owned_mcp: true quando o host SDK gerencia as conexões MCP deste plugin e Claude Code pulou a leitura da configuração do servidor MCP do plugin, false caso contrário. Requer Claude Code v2.1.172 ou posterior
• 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
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. Em modo seguro este evento relata apenas inventário configurado; os comandos, skills, hooks e servidores MCP do plugin não carregam. Requer Claude Code v2.1.169 ou posterior

​

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")
• skill.kind: "workflow" quando a skill é uma skill de workflow. Ausente caso contrário
• 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"
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. Requer Claude Code v2.1.169 ou posterior
• 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"
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. Requer Claude Code v2.1.169 ou posterior
• 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"
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. Requer Claude Code v2.1.169 ou posterior
• 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 métricas de plugin de hook

• Todos os atributos padrão
• event.name: "hook_plugin_metrics"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão
• plugin_id: identificador do plugin em forma <name>@<marketplace>
• hook_event: tipo de evento de hook que emitiu as métricas
• Até 20 chaves de métrica emitidas pelo plugin. Os nomes correspondem a ^[a-z][a-z0-9_]{0,39}$. Os valores são booleanos ou números.

​

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
• precompute_reuse: Definido apenas quando trigger é "manual". A compactação automática pode preparar um resumo em segundo plano antes da janela de contexto se encher, e este atributo registra se /compact reutilizou esse resumo preparado. "hit" significa que foi reutilizado; "miss_custom_instructions", "miss_hook" e "miss_not_ready" dão a razão pela qual um resumo fresco foi computado em vez disso. Requer Claude Code v2.1.153 ou posterior

​

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

​

Auditar eventos 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

• tool_result: mantém tool_name e mcp_server_scope, omite mcp_server_name, mcp_tool_name e argumentos
• tool_decision: mantém tool_name, omite tool_parameters
• mcp_server_connection: omite server_name e a mensagem de erro, mas mantém is_plugin, plugin_id_hash e plugin.name, com nomes de plugins não-Anthropic reduzidos ao literal "third-party", para que servidores fornecidos por plugins permaneçam distinguíveis sem registro detalhado

​

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, Grafana Cloud): 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, Grafana Cloud): 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, Grafana Cloud): 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
• O texto de resposta do assistente não é coletado por padrão. Apenas o comprimento da resposta é registrado. Para incluir texto de resposta, defina OTEL_LOG_ASSISTANT_RESPONSES=1. Como todos os dados OpenTelemetry do Claude Code, o texto de resposta é enviado apenas para o endpoint OTel que você configura, nunca para a Anthropic. Quando esta variável não está definida, OTEL_LOG_USER_PROMPTS é usado como fallback, portanto defina OTEL_LOG_ASSISTANT_RESPONSES=0 se você quiser conteúdo de prompt sem conteúdo de resposta
• 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. Estes dados são enviados apenas para o endpoint OTEL que você configura, nunca para a Anthropic. Os argumentos ainda podem conter valores sensíveis, portanto configure seu backend de telemetria para filtrar ou reduzir esses atributos conforme necessário. Quando ativado:
  • Eventos tool_result e tool_decision incluem um atributo tool_parameters com comandos Bash, nomes de servidor MCP e ferramenta, e nomes de skill. Campos como full_command são emitidos sem truncamento
  • Eventos tool_result adicionalmente incluem 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
  • 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, com o mesmo truncamento que tool_input
• 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