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 e redefini-los para uso em produçã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"
  }
}

​

Como as configurações gerenciadas bloqueiam o destino OTLP

• Endpoints: quando você define OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code remove todos os endpoints por sinal definidos pelo desenvolvedor. Os desenvolvedores não podem apontar um sinal para um coletor diferente, portanto você não precisa também definir as variáveis de endpoint por sinal nas configurações gerenciadas.
• Protocolos: quando você define OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code remove todos os protocolos por sinal definidos pelo desenvolvedor.
• Credenciais: quando você define OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY ou OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, Claude Code remove as versões por sinal definidas pelo desenvolvedor dessa variável, além de todas as variáveis de endpoint definidas pelo desenvolvedor, genéricas ou por sinal, já que essas credenciais de outra forma alcançariam um coletor que as configurações gerenciadas não escolheram.
• Seletores de exportador: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER e o OTEL_TRACES_EXPORTER beta seguem a precedência normal por chave. Uma configuração do desenvolvedor ainda pode desabilitar um sinal ou alterá-lo para o exportador de console, portanto defina os seletores nas configurações gerenciadas também se você precisar que eles sejam bloqueados. Através de fontes de administrador, OTEL_LOGS_EXPORTER segue a unidade de telemetria enquanto os outros dois seletores se mesclam por chave. Requer Claude Code v2.1.223 ou posterior.
• Endpoints de rastreamento beta: com rastreamento beta detalhado ativo, Claude Code exporta logs e rastreamentos para BETA_TRACING_ENDPOINT em vez de através dos exportadores de logs e rastreamentos. Claude Code portanto remove um BETA_TRACING_ENDPOINT definido pelo desenvolvedor sempre que qualquer uma dessas configurações gerenciadas decide o destino de qualquer sinal:
  • Um endpoint genérico ou de logs/rastreamentos ou credencial
  • Um otelHeadersHelper
  • Um seletor de exportador de logs ou rastreamentos definido como none, console ou vazio, valores que mantêm o sinal fora de um coletor
  • CLAUDE_CODE_ENABLE_TELEMETRY desativado
  Um endpoint ou credencial apenas de métricas não o remove. Antes da v2.1.251, um BETA_TRACING_ENDPOINT definido pelo desenvolvedor redirecionava os logs e rastreamentos que o rastreamento beta detalhado exporta mesmo quando as configurações gerenciadas fixavam o coletor.

​

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

• Uma chamada para qualquer ferramenta que não seja Read, Edit, Write, Bash, WebFetch, WebSearch e ferramentas MCP
• Um Read que retorna qualquer coisa que não seja texto de arquivo, como uma imagem, um PDF ou uma releitura de um arquivo cujo conteúdo não mudou
• Uma chamada Edit ou Write, a menos que você também defina OTEL_LOG_TOOL_DETAILS=1
• Uma chamada WebFetch ou WebSearch que Claude Code moveu para o background porque você interrompeu o turno para enviar suas mensagens enfileiradas imediatamente enquanto a chamada era executada. Claude recebe esse resultado mais tarde, após o span da ferramenta ter terminado

​

Cabeçalhos dinâmicos

​

Configuração de configurações

{
  "otelHeadersHelper": "/path/to/generate-otel-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)\"}"

• Uma notificação de aviso em sessões interativas, otelHeadersHelper failed; telemetry is not being exported, mostrada uma vez por sessão quando o auxiliar falha pela primeira vez
• 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

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

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

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

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

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

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 eventos.
• workspace.host_paths: diretórios do workspace do host selecionados no aplicativo desktop, como um array de strings
• 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. Filtrar eventos por um workflow.run_id reconstrói as requisiçõ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 skills. 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. Os nomes de workflow integrados aparecem literalmente quando a execução executa o script integrado não modificado. Nomes de autoria do 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

​

Atributos de repositório

​

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 dashboard claude agents, uma UI local iniciada pelo usuário em vez de uma sessão conversacional. Filtre neste valor para separar inicializações de processo de UI de sessões conversacionais em seus dashboards.

​

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 requisição. Um de "main", "subagent", ou "auxiliary"
• speed: "fast" quando a requisição usou modo rápido. Ausente caso contrário
• effort: Nível de esforço aplicado à requisição: "low", "medium", "high", "xhigh", ou "max". Ausente quando Claude Code não envia nível de esforço, por exemplo em um modelo que não suporta esforço.
• agent.name: Tipo de subagente que emitiu a requisição. Nomes de agentes integrados e agentes de plugins do marketplace oficial aparecem literalmente. Outros nomes de agentes definidos pelo usuário são substituídos por "custom". Ausente quando a requisição não foi emitida por um tipo de subagente nomeado.
• skill.name: Skill ativa para a requisição, definida pela ferramenta Skill, um comando /, ou herdada por um subagente gerado. Nomes de skills integrados, agrupados, definidos pelo usuário e de plugins do marketplace oficial aparecem literalmente. Nomes de skills de plugins 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 plugins do marketplace oficial aparecem literalmente. Nomes de plugins de terceiros são substituídos por "third-party". Ausente quando nem a skill nem o subagente tem um plugin proprietário.
• marketplace.name: Marketplace do qual o plugin proprietário foi instalado. Emitido apenas para plugins do marketplace oficial, mesmo com OTEL_LOG_TOOL_DETAILS=1 definido. Ausente caso contrário.
• mcp_server.name: Servidor MCP cujo resultado de ferramenta esta requisição consumiu. Nomes de servidores integrados, proxied por claude.ai e do registro oficial aparecem literalmente. Nomes de servidores configurados pelo usuário são substituídos por "custom". Ausente quando a requisição não consumiu resultado de ferramenta MCP. Antes da v2.1.222, Claude Code definia este atributo em cada requisição após uma chamada de ferramenta MCP, não apenas em requisições que consumiram um resultado de ferramenta, então dashboards que o agregam mostram uma queda após você atualizar.
• mcp_tool.name: Ferramenta MCP cujo resultado esta requisição consumiu, com o mesmo comportamento de redação e versão que mcp_server.name. Ausente quando a requisição não consumiu resultado de ferramenta MCP.

​

Contador de tokens

• 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 requisição. Um de "main", "subagent", ou "auxiliary"
• speed: "fast" quando a requisição usou modo rápido. Ausente caso contrário
• effort: Nível de esforço aplicado à requisiçã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 requisiçã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: De onde a decisão veio. Um de "config", "hook", "user_permanent", "user_temporary", "user_abort", ou "user_reject". Veja o evento de decisão de 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 eventos

• message.uuid em user_prompt, assistant_response, e api_response_body
• request_id nos eventos de API, persistido como requestId nas entradas de assistente da transcrição
• tool_use_id em eventos tool_result e tool_decision

​

Evento de prompt do usuário

• Todos os atributos padrão
• event.name: "user_prompt"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• prompt_length: Comprimento do prompt
• prompt: Conteúdo do prompt. Redatado por padrão. Defina OTEL_LOG_USER_PROMPTS=1 para incluí-lo
• message.uuid: UUID da mensagem do usuário resultante, correspondendo à entrada da transcrição persistida. Ausente em dispatches de comando, que podem produzir zero ou muitas mensagens. Requer Claude Code v2.1.214 ou posterior
• 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 conforme digitado em vez do nome canônico. Nomes de comando personalizados, de 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• response_length: Comprimento do texto de resposta em caracteres
• response: Texto de resposta, truncado no limite de conteúdo (60 KB por padrão). Redatado 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 o controla em vez disso, então defina OTEL_LOG_ASSISTANT_RESPONSES=0 para manter respostas redatadas enquanto o log de prompt está ativado
• model: Identificador do modelo (por exemplo, “claude-sonnet-5”)
• request_id: ID de requisição de API, descrito em Atributos de correlação de eventos
• message.uuid: UUID da entrada final da transcrição da resposta. Uma resposta de API é persistida como uma entrada de transcrição por bloco de conteúdo; esta é a última, da qual o parentUuid do próximo turno se encadeia. Requer Claude Code v2.1.214 ou posterior
• query_source: Subsistema que emitiu a requisição, como "repl_main_thread", "compact", ou um nome de subagente

​

Evento de resultado de ferramenta

• Todos os atributos padrão
• event.name: "tool_result"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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: De onde a decisão de permissão veio. Um de "config", "hook", "user_permanent", ou "user_temporary". Veja o evento de decisão de 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 de 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)
• vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (quando OTEL_LOG_TOOL_DETAILS=1): a identidade do commit de uma execução bem-sucedida de git commit executada pela ferramenta Bash ou PowerShell. vcs.ref.head.revision é o SHA do commit, vcs.ref.head.name é o branch no qual foi feito o commit, e vcs.ref.head.type é branch. O nome e tipo são omitidos quando o commit foi feito em um HEAD desanexado. Requer Claude Code v2.1.269 ou posterior
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): String JSON contendo parâmetros específicos da ferramenta. Para servidores integrados do Claude Desktop, em sessões que Claude Desktop possui, o par mcp_server_name/mcp_tool_name é incluído mesmo com a flag desativada, a mesma exceção de autoria do host que o evento de decisão de ferramenta, requerendo Claude Code v2.1.214 ou posterior. Os parâmetros variam por ferramenta:
  • Para ferramenta Bash: inclui bash_command, full_command, timeout, description, e dangerouslyDisableSandbox, mais git_commit_id e git_branch quando um comando git commit é bem-sucedido. git_commit_id é o SHA completo do commit quando o commit é o HEAD do diretório de trabalho da sessão, e o SHA abreviado do git caso contrário. git_branch é o branch no qual foi feito o commit, omitido em um HEAD desanexado
  • Para a ferramenta Bash do workspace do aplicativo desktop, que também relata tool_name como Bash: inclui apenas bash_command, full_command, e 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 acima de 512 caracteres são truncados, e o payload completo é limitado a ~4 K caracteres. Aplica-se a todas as ferramentas incluindo ferramentas MCP.

​

Evento de requisição de API

• Todos os atributos padrão
• event.name: "api_request"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• model: Modelo usado (por exemplo, “claude-sonnet-5”)
• cost_usd: Custo estimado em USD
• cost_usd_micros: Custo estimado em milionésimos de dólar americano, emitido como um inteiro
• 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
• request_id: ID de requisição de API, como "req_011...", descrito em Atributos de correlação de eventos.
• client_request_id: UUID gerado pelo cliente enviado como o header de requisição x-client-request-id; veja a tabela atributos de correlação de eventos para quando está presente. Requer Claude Code v2.1.214 ou posterior
• speed: "fast" ou "normal", indicando se o modo rápido estava ativo
• query_source: Subsistema que emitiu a requisição, como "repl_main_thread", "compact", ou um nome de subagente
• effort: Nível de esforço aplicado à requisição: "low", "medium", "high", "xhigh", ou "max". Ausente quando Claude Code não envia nível de esforço, por exemplo em um modelo que 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 requisiçã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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• model: Modelo usado (por exemplo, “claude-sonnet-5”)
• error: Mensagem de erro
• status_code: Código de status HTTP como um número. Ausente para erros não-HTTP como falhas de conexão.
• duration_ms: Duração da requisição em milissegundos
• attempt: Número total de tentativas feitas, incluindo a requisição inicial (1 significa que nenhuma retentativa ocorreu)
• request_id: ID de requisição de API, como "req_011...", descrito em Atributos de correlação de eventos.
• client_request_id: UUID gerado pelo cliente enviado como o header de requisição x-client-request-id. Disponível mesmo quando uma falha como timeout ou erro de conexão nunca produziu um request_id do servidor; veja a tabela atributos de correlação de eventos para quando está presente. Requer Claude Code v2.1.214 ou posterior
• speed: "fast" ou "normal", indicando se o modo rápido estava ativo
• query_source: Subsistema que emitiu a requisição, como "repl_main_thread", "compact", ou um nome de subagente
• effort: Nível de esforço aplicado à requisição. Ausente quando Claude Code não envia nível de esforço, por exemplo em um modelo que 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 requisiçã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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• model: Identificador do modelo da requisição
• request_id: ID de requisição de API, como "req_011...", descrito em Atributos de correlação de eventos.
• query_source: Subsistema que emitiu a requisição, como "repl_main_thread", "compact", ou um nome de subagente. Veja api_request para definições.
• speed: Ou "fast" quando Modo rápido está ativo, ou "normal"
• attempt: Número de tentativa de retentativa. A primeira tentativa é 1.
• effort: Nível de esforço aplicado à requisição. Ausente quando Claude Code não envia nível de esforço, por exemplo em um modelo que não suporta esforço.
• server_fallback_hop: true quando o fallback de modelo do lado do servidor da API já retentou esta recusa em um modelo diferente, então o usuário não viu esta recusa particular. false quando a requisição terminou em uma recusa. Um único turno pode emitir tanto um evento de 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 de 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 requisição. Veja Contador de custo para definições e comportamento de redação.

​

Evento de corpo de requisição de API

• Todos os atributos padrão
• event.name: "api_request_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• body: Parâmetros de requisição da API Messages serializados em JSON, como o prompt do sistema, mensagens e ferramentas, truncados no limite de conteúdo (60 KB por padrão). Conteúdo de pensamento estendido em turnos anteriores do assistente é redatado. 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 requisição
• query_source: Subsistema que emitiu a requisição (por exemplo, "compact")
• request_body_id: UUID que identifica o corpo de requisição desta tentativa. O evento api_response_body para a tentativa que é bem-sucedida carrega o mesmo valor, então você pode emparelhar uma resposta com a requisição exata que a produziu. Requer Claude Code v2.1.274 ou posterior

​

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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• body: Resposta da API Messages serializada em JSON, incluindo o id, blocos de conteúdo, uso e razão de parada, truncada no limite de conteúdo (60 KB por padrão). Conteúdo de pensamento estendido é redatado. 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 requisição
• request_id: ID de requisição de API, como "req_011...", descrito em Atributos de correlação de eventos.
• request_body_id: O request_body_id do evento api_request_body que esta resposta responde. Requer Claude Code v2.1.274 ou posterior
• message.id: ID de mensagem que a API atribuiu à resposta, o campo id do corpo da resposta. Requer Claude Code v2.1.274 ou posterior
• message.uuid: UUID da entrada final da transcrição da resposta. Junto com request_body_id, vincula uma mensagem de transcrição aos corpos de requisição e resposta atrás dela. Requer Claude Code v2.1.274 ou posterior

​

Evento de decisão de ferramenta

• Todos os atributos padrão
• event.name: "tool_decision"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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"
• tool_source: Sempre presente. A proveniência da ferramenta, como um conjunto fechado de valores de autoria da CLI. Requer Claude Code v2.1.214 ou posterior
  • "builtin": as próprias ferramentas da CLI
  • "mcp": servidores MCP em geral
  • "sdk_host_builtin_mcp": um servidor em processo integrado ao próprio Claude Desktop, em uma sessão que Claude Desktop possui. Claude Desktop possui uma sessão que iniciou de um de seus próprios pontos de entrada, claude-desktop, claude-desktop-3p, ou local-agent, quando essa sessão não é um filho aninhado; sessões aninhadas, incluindo sessões que Claude Code gera, relatam esses servidores como "mcp"
• source: De onde a decisão veio:
  • "config": Decidido automaticamente sem solicitar, baseado em configurações de projeto, regras de permissão ou negação nas configurações pessoais do usuário, política gerenciada pela empresa, flags --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. Claude Code também relata "config" quando a própria requisição de prompt de permissão falha, por exemplo quando o callback canUseTool do Agent SDK ou a ferramenta --permission-prompt-tool retorna um resultado inválido, ou quando o stream de entrada fecha enquanto a requisição está pendente. Antes da v2.1.216, Claude Code relatava essas falhas como "user_reject".
  • "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 prompt de permissão, que salva uma regra de permissão em suas configurações pessoais. Na CLI interativa isto é emitido apenas para essa escolha em si; chamadas posteriores que correspondem à regra salva emitem "config" em vez disso. Em sessões Agent SDK ou não-interativas -p, tanto a escolha inicial quanto correspondências posteriores de regra emitem "user_permanent". Tratado como uma aceitação.
  • "user_temporary": Emitido quando o usuário escolheu “Sim” em um prompt de permissão para uma aprovação única, ou escolheu uma opção que concede acesso pelo resto da sessão em um prompt de edição ou leitura de arquivo. Na CLI interativa isto é emitido apenas para a escolha em si; chamadas posteriores permitidas por essa concessão com escopo de sessão emitem "config" em vez disso. Em sessões Agent SDK ou 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 prompt de permissão sem responder. Em sessões Agent SDK e não-interativas -p, isto inclui interromper o turno enquanto uma requisição de permissão canUseTool ou --permission-prompt-tool está pendente; antes da v2.1.216, Claude Code relatava essa interrupção como "user_reject". Tratado como uma rejeição.
  • "user_reject": Emitido quando o usuário escolheu “Não” quando solicitado. Na CLI interativa isto é 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. Em sessões Agent SDK ou 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 de 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 reescreve a entrada da ferramenta via updatedInput. Use este atributo para ver qual comando foi rejeitado quando decision é "reject".
  • Para ferramentas "sdk_host_builtin_mcp": mcp_server_name e mcp_tool_name são incluídos mesmo quando OTEL_LOG_TOOL_DETAILS está desativado, porque a aplicação host define esses nomes; sem eles, uma chamada rejeitada para um desses servidores integrados seria não atribuível no stream padrão. Para servidores MCP configurados pelo usuário, o tool_name do evento é sempre o literal "mcp_tool", e os nomes do servidor e ferramenta aparecem apenas em tool_parameters com a flag ativada; conteúdo de argumento requer a flag em todos os lugares. Requer Claude Code v2.1.214 ou posterior
  • Para ferramenta Bash: inclui bash_command, full_command, timeout, description, dangerouslyDisableSandbox. A ferramenta bash do workspace do aplicativo desktop também relata tool_name como Bash, mas inclui apenas bash_command, full_command, e 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 mudança de modo de permissão

• Todos os atributos padrão
• event.name: "permission_mode_changed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 uma 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• status: "connected", "failed", ou "disconnected"
• transport_type: Transporte do servidor, como "stdio", "sse", ou "http"
• server_scope: Escopo no qual 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. Claude Code o computa conforme descrito no evento de plugin carregado
• plugin.name (quando is_plugin é true): Nome do plugin que fornece o servidor. Para plugins de terceiros isto é a string literal "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1; isto protege nomes de plugins de terceiros de aparecerem em logs por padrão. Plugins de fontes oficiais da 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 a 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• error_name: Nome da classe de erro, como "TypeError" ou "SyntaxError"
• error_code: Código errno do 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• marketplace.is_official: "true" se o marketplace é um marketplace oficial da Anthropic, "false" caso contrário
• install.trigger: "cli" ou "ui"
• plugin.name: Nome do plugin instalado. Para marketplaces de terceiros isto é 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 isto é incluído apenas quando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace do qual o plugin foi instalado. Para marketplaces de terceiros isto é 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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. Redatado 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 é redatado e o manifesto declara uma versão
• plugin.scope: categoria de proveniência para o plugin: "official", "community", "org", "user-local", ou "default-bundle"
• enabled_via: como o plugin veio a ser habilitado: "default-enable", "org-policy", "admin-install", "seed-mount", ou "user-install". O valor "admin-install" significa que o plugin está definido como obrigatório ou auto-instalação para sua organização em Configurações da Organização > Plugins & skills. Antes da v2.1.246, Claude Code relatava esses plugins como "user-install" ou "seed-mount"
• plugin_id_hash: hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar os plugins de terceiros distintos carregados em sua frota sem registrar seus nomes. Para plugins sincronizados de claude.ai, Claude Code faz hash do nome do plugin com o nome do marketplace que claude.ai relata para o plugin, ou com synced caso contrário. Antes da v2.1.246, Claude Code não usava o nome do marketplace que claude.ai relata no hash
• 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 ativada

• Todos os atributos padrão
• event.name: "skill_activated"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• skill.name: Nome da skill. Para skills definidas pelo usuário e de plugins 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• mention_type: Tipo de menção ("file", "directory", "agent", "mcp_resource", "peer"). O valor "peer" significa que você mencionou uma de suas outras sessões Claude Code. Requer Claude Code v2.1.232 ou posterior
• success: Se a menção foi resolvida com sucesso ("true" ou "false")

​

Evento de retentativas de API esgotadas

• Todos os atributos padrão
• event.name: "api_retries_exhausted"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• model: Modelo usado
• error: Mensagem de erro final
• status_code: Código de status HTTP como um número. Ausente para erros não-HTTP.
• total_attempts: Número total de tentativas feitas
• total_retry_duration_ms: Tempo total de wall-clock 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 de 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. Claude Code o computa conforme descrito no evento de plugin carregado

​

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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 habilitados

​

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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 wall-clock de todos os hooks correspondentes
• stdout_chars: Total de caracteres de stdout em todos os hooks correspondentes que tiveram sucesso. Requer Claude Code v2.1.280 ou posterior
• additional_context_chars: Total de caracteres de additionalContext retornados pelos hooks correspondentes. Requer Claude Code v2.1.280 ou posterior
• system_message_chars: Total de caracteres de systemMessage retornados pelos hooks correspondentes. Requer Claude Code v2.1.280 ou posterior
• initial_user_message_chars: Total de caracteres de initialUserMessage retornados pelos hooks correspondentes. Requer Claude Code v2.1.280 ou posterior
• num_outputs_persisted: Número de saídas de hook acima do limite de 10.000 caracteres que Claude Code salvou em um arquivo. Requer Claude Code v2.1.280 ou posterior
• 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 habilitados

​

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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 booleano ou número.

​

Evento de compactação

• Todos os atributos padrão
• event.name: "compaction"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 background antes da janela de contexto ficar cheia, 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 conclusão de subagente

• Todos os atributos padrão
• event.name: "subagent_completed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• agent_type: O tipo de subagente. Nomes de agentes integrados e agentes de plugins do marketplace oficial aparecem literalmente; outros nomes de agente são substituídos por "custom" a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido
• agent.source: De onde a definição do agente veio: built-in, plugin, ou a fonte de configurações que definiu um agente personalizado, como userSettings ou projectSettings
• is_built_in: Se o subagente é um tipo de agente integrado
• is_async: Se o subagente executou em background
• total_tokens: A pegada de token da requisição final de API do subagente: tokens de entrada, criação de cache, leitura de cache e saída dessa única requisição, aproximadamente o tamanho do contexto do subagente na conclusão. Não uma soma em toda a execução
• total_tool_uses: Número de chamadas de ferramenta que o subagente fez em toda a execução
• duration_ms: Tempo de execução em milissegundos
• model: O modelo que o subagente foi resolvido para executar
• final_model: O modelo que produziu a resposta final do subagente, que difere de model após uma mudança no meio da execução como um fallback. Requer Claude Code v2.1.212 ou posterior
• model_swapped: Se mais de um modelo serviu as requisições do subagente. Requer Claude Code v2.1.212 ou posterior
• plugin_id_hash, plugin.name: Presente para agentes fornecidos por plugin. Nomes de plugins do marketplace oficial aparecem literalmente; outros nomes de plugin são substituídos por "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido

​

Evento de pesquisa de feedback

• Todos os atributos padrão
• event.name: "feedback_survey"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• 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 uma frota

​

Evento de varredura de retenção

• Todos os atributos padrão
• event.name: "retention_sweep"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• result: "complete" quando a varredura foi executada, "skipped" quando Claude Code a pausou
• period_days: O valor cleanupPeriodDays das configurações mescladas, em dias, ou 30 quando nenhuma fonte o define. Em eventos pulados, o valor que a varredura teria usado, computado das fontes de configurações que Claude Code pôde ler
• used_default: "true" quando nenhuma fonte de configurações legível define cleanupPeriodDays, "false" caso contrário. Em eventos completos, "true" significa que o padrão de 30 dias foi aplicado
• skip_reason: Por que Claude Code pausou a varredura. Presente apenas quando result é "skipped":
  • "user_source_disabled": Configurações do usuário são excluídas, por exemplo pela flag --setting-sources ou opção settingSources do SDK, e nenhuma fonte habilitada fornece cleanupPeriodDays
  • "settings_unknowable": Um arquivo de configurações não pôde ser lido ou analisado, então cleanupPeriodDays ou desktopSessionCleanupPeriodDays pode estar definido para um valor que Claude Code não pode ver
  • "settings_invalid_key_set": Configurações têm erros de validação e cleanupPeriodDays ou desktopSessionCleanupPeriodDays está explicitamente definido, então fazer fallback para o padrão poderia deletar ou manter arquivos contra essa configuração
• transcripts_deleted: Número de transcrições de sessão, os arquivos ~/.claude/projects/*/*.jsonl de nível superior, que a varredura deletou
• transcripts_exempted_desktop: Número de transcrições passadas do período de retenção que a varredura manteve sob a regra de Claude Desktop e Cowork. Estes não contam para files_past_cutoff. Requer Claude Code v2.1.248 ou posterior
• session_files_deleted: Número de artefatos que a varredura de arquivos de sessão deletou: transcrições mais arquivos complementares por sessão como sidecars, gravações e resultados de ferramentas
• artifacts_deleted: Total de itens que a varredura deletou em todos os diretórios de dados que cobre, incluindo os arquivos de sessão. Algumas varreduras contam uma árvore de diretório removida inteira como um item e algumas passagens de limpeza não contribuem para o contador, então trate o valor como um piso em vez de uma contagem exata de arquivos
• files_retained_fresh: Arquivos inspecionados e deixados em lugar porque ainda estão dentro do período de retenção. Apenas varreduras por arquivo contam estes, então o valor é um piso; um valor diferente de zero é o estado estável normal
• files_past_cutoff: Arquivos mais antigos que o período de retenção que a varredura falhou em deletar, por exemplo por causa de um erro de permissão ou um arquivo mantido aberto. Um valor acima de zero significa que arquivos sobreviveram ao período de retenção configurado; zero não é prova de que nenhum fez, porque uma remoção falhada de um diretório inteiro conta para error_count em vez disso
• error_count: Número de erros que a varredura encontrou ao listar ou deletar arquivos

​

Evento de configurações gerenciadas resolvidas

• Defina-o no bloco env de configurações gerenciadas, configurações do usuário, ou --settings, ou no ambiente com o qual você inicia Claude Code. Um valor em configurações de projeto ou local não o ativa, porque um repositório clonado pode escrevê-los.
• Configurações gerenciadas pelo servidor podem defini-lo sem mostrar o diálogo de aprovação de segurança, porque a variável apenas adiciona sua própria política redatada da organização a um evento que sua organização já recebe.

• Todos os atributos padrão
• event.name: "managed_settings_resolved"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• managed_settings.trigger: "startup" para o evento de início de sessão, "change" quando as configurações gerenciadas ou o estado do auxiliar de política mudaram mais tarde na sessão, ou "refused" quando uma política de configurações gerenciadas parou a sessão. Claude Code envia um evento change apenas quando um atributo difere do último evento que enviou, e um valor de configuração alterado conta mesmo quando OTEL_LOG_MANAGED_SETTINGS está desativado
• error.type: por que Claude Code parou a sessão. Presente apenas em eventos refused:
  • "helper_failed": uma execução do auxiliar de política falhou
  • "policy_invalid": as configurações gerenciadas contêm um erro que impede Claude Code de iniciar, ou uma fonte de administrador falhou em carregar, então Claude Code não pode verificar a imposição de login da organização
  • "consent_rejected": o usuário rejeitou o diálogo de aprovação de segurança para configurações gerenciadas pelo servidor
  • "force_refresh_failed": a busca de configurações que forceRemoteSettingsRefresh requer falhou
  • "gateway_rejected": um gateway de aplicativos Claude respondeu ao carregamento de configurações gerenciadas com HTTP 403
  • "version_below_minimum": esta versão de Claude Code está abaixo de requiredMinimumVersion ou acima de requiredMaximumVersion
  • "_OTHER": o carregamento de configurações gerenciadas do gateway de aplicativos Claude falhou por outro motivo
• managed_settings.sources: cada fonte gerenciada que entrega pelo menos uma chave de política, prioridade mais alta primeiro, incluindo fontes cujas chaves não entram em efeito sob first-wins. Os valores são "remote", "plist" ou "hklm" para a política MDM ou nível de SO, "file" para arquivos de configurações gerenciadas e drop-ins, "parent" quando um host de incorporação fornece configurações, e "hkcu" para o valor de registro HKCU do Windows quando Claude Code o lê. Uma fonte que carrega apenas chaves de controle, ou que Claude Code não pôde ler, não está listada. Emitido como um array de strings, vazio quando nenhuma fonte gerenciada entrega uma chave de política
• managed_settings.source_behavior: o valor managedSourcesBehavior que Claude Code leu, "first-wins" ou "merge". "first-wins" quando nenhuma fonte define a chave
• managed_settings.helper.state: estado do auxiliar de política que a fonte MDM ou arquivo selecionada configura:
  • "ok": a saída do auxiliar serve como as configurações gerenciadas
  • "bad_path", "not_a_file", "exit_nonzero", "timed_out", "oversize", "parse_failed", "envelope_invalid", ou "schema_rejected": a última execução do auxiliar falhou. Falhas do auxiliar descreve os casos
  • "none": nenhum auxiliar está configurado, ou a fonte que o configura não é uma política MDM ou arquivo de configurações gerenciadas
• managed_settings.helper.applied: "output" enquanto a saída do próprio auxiliar serve como as configurações gerenciadas, "none" quando não serve
• managed_settings.helper.entry: "policyHelper" quando Claude Code selecionou um policyHelper. Ausente quando selecionou nenhum auxiliar
• managed_settings.helper.path: o path configurado do auxiliar. Presente sempre que Claude Code selecionou um auxiliar, independentemente de OTEL_LOG_MANAGED_SETTINGS estar definido
• managed_settings.resolved_sha256 (quando OTEL_LOG_MANAGED_SETTINGS=1): SHA-256 das configurações gerenciadas resolvidas antes da redação, serializadas como JSON com chaves ordenadas recursivamente e sem espaço em branco. Máquinas com o mesmo digest executam a mesma política. Claude Code envia o digest apenas com o opt-in porque uma política curta pode ser recuperada fazendo hash de suposições. Ausente quando nenhuma configuração gerenciada foi resolvida, e em eventos refused
• managed_settings.settings (quando OTEL_LOG_MANAGED_SETTINGS=1): os nomes e forma das configurações gerenciadas resolvidas como uma string JSON, com os valores redatados. Ausente em eventos refused. Claude Code o constrói a partir de seu esquema de configurações:
  • Um nome de configuração que o esquema declara é exportado, e uma chave que não declara é deixada de fora
  • Booleanos, números e valores de string que o esquema restringe a um conjunto fixo de opções, como permissions.defaultMode, são exportados como estão. sandbox.network.httpProxyPort e sandbox.network.socksProxyPort são exportados como "[REDACTED]"
  • Toda outra string, como model, apiKeyHelper, todo valor env, toda URL e todo comando, é exportado como "[REDACTED]"
  • Os nomes de entrada de mapas, como nomes de variáveis env e IDs de plugin, são exportados como estão. Uma configuração cujas entradas o esquema não digita, como vimInsertModeRemaps, é exportada como um único "[REDACTED]", e sandbox.ignoreViolations é exportado como uma lista de suas listas de caminho sem os padrões de comando
  • Uma lista mantém seu comprimento, com cada entrada redatada pelas mesmas regras
  • Uma regra permissions.allow, permissions.deny, ou permissions.ask é exportada como seu nome de ferramenta com o conteúdo redatado, como Read([REDACTED]), quando a ferramenta é integrada nesta versão de Claude Code ou é uma referência mcp__ como mcp__jira__create_issue. Qualquer outra regra é exportada como "[REDACTED]"
  • Hooks seguem as mesmas regras, então campos de opção fixa e numéricos como type e timeout mostram, enquanto cada comando, URL, matcher, e condição if é exportada como "[REDACTED]"
  Por exemplo, configurações gerenciadas com apiKeyHelper, duas variáveis env, e uma regra de negação são exportadas como {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}. Claude Code corta o valor em 8 KB de UTF-8, e o valor cortado não é JSON válido
• managed_settings.settings_truncated (quando managed_settings.settings está presente): true quando Claude Code cortou managed_settings.settings em 8 KB, false caso contrário. Emitido como um booleano, não uma string

​

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 mcp_server_scope e um tool_name reduzido ao literal "mcp_tool" para servidores configurados pelo usuário, omite conteúdo de argumentos. Para servidores integrados do Claude Desktop, em sessões que Claude Desktop possui, também mantém o par mcp_server_name/mcp_tool_name dentro de tool_parameters, a mesma exceção de autoria de host que tool_decision, exigindo Claude Code v2.1.214 ou posterior
• tool_decision: mantém tool_source e um tool_name reduzido ao literal "mcp_tool" para servidores configurados pelo usuário, omite conteúdo de argumentos. Para servidores integrados do Claude Desktop, em sessões que Claude Desktop possui, também mantém o par mcp_server_name/mcp_tool_name dentro de tool_parameters; tool_source e o par de nomes exigem Claude Code v2.1.214 ou posterior
• 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: Cálculos de taxa, métricas agregadas
• Armazenamentos colunares: Consultas complexas, análise de usuário único
• Plataformas de observabilidade completas: Consultas avançadas, visualização, alertas

​

Para eventos/logs

• Sistemas de agregação de logs: Busca de texto completo, análise de logs
• Armazenamentos colunares: Análise de eventos estruturados
• Plataformas de observabilidade completas: Correlação entre métricas e eventos

​

Para rastreamentos

• Sistemas de rastreamento distribuído: Visualização de span, waterfalls de solicitação, análise de latência
• Plataformas de observabilidade completas: Busca de rastreamento e correlação com métricas e logs

​

Informações de serviço

• service.name: claude-code para sessões de terminal, claude-code-desktop para sessões iniciadas a partir da aba Code no aplicativo Claude Desktop
• service.version: Versão atual do Claude Code, ou a versão do aplicativo Desktop para sessões da aba 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, enviado apenas para o endpoint OTel que você configura, nunca para a Anthropic. 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. Sob rastreamento beta detalhado, esta variável alcança mais do que apenas texto de prompt: ela também controla o atributo de span new_context, que carrega resultados de ferramenta no span claude_code.llm_request
• 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. Para os servidores integrados do Claude Desktop, em sessões que o Claude Desktop possui, tool_decision e tool_result carregam o par mcp_server_name/mcp_tool_name, nomes criados pelo host em vez de conteúdo de argumentos, mesmo com a flag desativada. A exceção requer Claude Code v2.1.214 ou posterior. 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 customizados, plugin e MCP
  • Os contadores de custo e token e os eventos api_request, api_error e api_refusal carregam nomes reais de agente, skill, plugin e servidor MCP e nomes de ferramenta em seus atributos de atribuição
  • 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 ferramenta não é registrado em spans de rastreamento por padrão. Para incluí-lo, defina OTEL_LOG_TOOL_CONTENT=1. O span claude_code.tool então carrega um evento de span tool.output com conteúdos de arquivo brutos, saída de comando Bash e o que ferramentas MCP, WebFetch e WebSearch retornam, truncado no limite de conteúdo (60 KB por padrão) por atributo. Resultados de ferramentas MCP, WebFetch e WebSearch requerem Claude Code v2.1.283 ou posterior. O conteúdo de ferramenta também alcança spans através de new_context, cujo controle difere por span. 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 em suas configurações de shell, usuário ou gerenciadas. É ignorado em configurações de projeto e local. Os corpos contêm o histórico de conversa completo, incluindo o prompt do sistema, cada turno anterior de usuário e assistente, e resultados de ferramenta, portanto ativar isso implica consentimento para tudo que os outros sinalizadores de conteúdo OTEL_LOG_* revelariam. O Claude Code sempre reduz o conteúdo de pensamento estendido do Claude desses corpos, independentemente de outras configurações. O valor que você define determina como o Claude Code entrega os corpos:
  • Com =1, Claude Code emite eventos de log api_request_body e api_response_body para cada chamada de API. O atributo body dos eventos carrega a carga útil serializada em JSON, truncada no limite de conteúdo (60 KB por padrão)
  • Com =file:<dir>, Claude Code escreve corpos não truncados 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. Para cada resposta bem-sucedida, Claude Code também anexa uma linha a index.jsonl nesse diretório, vinculando o arquivo de resposta ao arquivo de solicitação que o produziu e à mensagem de transcrição em que se tornou. Cada linha não contém conteúdo de mensagem, e a seção evento de corpo de resposta da API lista seus campos. O arquivo de índice requer Claude Code v2.1.274 ou posterior

​

Monitorar Claude Code no Amazon Bedrock