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 definições geridas bloqueiam o destino OTLP

• Pontos finais: quando define OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code remove todos os pontos finais por sinal definidos pelo programador. Os programadores não podem apontar um sinal para um coletor diferente, portanto, não precisa de definir também as variáveis de ponto final por sinal nas definições geridas.
• Protocolos: quando define OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code remove todos os protocolos por sinal definidos pelo programador.
• Credenciais: quando 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 programador dessa variável, mais todas as variáveis de ponto final definidas pelo programador, genéricas ou por sinal, uma vez que essas credenciais chegariam de outra forma a um coletor que as definições geridas 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. A definição de um programador ainda pode desativar um sinal ou mudá-lo para o exportador de consola, portanto, defina também os seletores nas definições geridas se precisar que estejam bloqueados. Nas fontes de administração, 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.
• Pontos finais de rastreamento beta: com rastreamento beta detalhado ativo, Claude Code exporta registos e rastreamentos para BETA_TRACING_ENDPOINT em vez de através dos exportadores de registos e rastreamentos. Claude Code remove portanto um BETA_TRACING_ENDPOINT definido pelo programador sempre que qualquer uma destas definições geridas decide o destino de qualquer um dos dois sinais:
  • Um ponto final genérico ou de registos/rastreamentos ou credencial
  • Um otelHeadersHelper
  • Um seletor de exportador de registos ou rastreamentos definido para none, console, ou vazio, valores que mantêm o sinal fora de um coletor
  • CLAUDE_CODE_ENABLE_TELEMETRY desativado
  Um ponto final ou credencial apenas de métricas não o remove. Antes da v2.1.251, um BETA_TRACING_ENDPOINT definido pelo programador redirecionava os registos e rastreamentos que o rastreamento beta detalhado exporta mesmo quando as definições geridas fixavam o coletor.

​

Detalhes de configuração

​

Variáveis de configuração comuns

​

Autenticação mTLS

​

Controle de cardinalidade de métricas

​

Traces (beta)

​

Hierarquia de spans

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans

​

Atributos de span

• Uma chamada a qualquer ferramenta que não seja Read, Edit, Write, Bash, WebFetch, WebSearch e ferramentas MCP
• Um Read que retorna algo diferente de texto de arquivo, como uma imagem, um PDF ou uma releitura de um arquivo cujo conteúdo não mudou
• Uma chamada de Edit ou Write, a menos que você também defina OTEL_LOG_TOOL_DETAILS=1
• Uma chamada de WebFetch ou WebSearch que o Claude Code moveu para segundo plano enquanto era executada, para que uma mensagem em espera pudesse chegar ao Claude. O resultado que chega mais tarde também não é registrado. Para saber quando o Claude Code move uma chamada, consulte Quando o Claude Code envia o que você colocou na fila para o terminal e o campo priority para sessões do Agent SDK

​

Cabeçalhos dinâmicos

​

Configuração nas configurações

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

​

Requisitos do script

#!/bin/bash
# Example: Multiple headers
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, exibida uma vez por sessão quando o helper falha pela primeira vez
• Saída de /status
• O log de depuração, ao executar com --debug ou depois de executar /debug na sessão
• stderr, em sessões não interativas iniciadas com -p

​

Comportamento de atualização

​

Suporte a organizações com várias equipes

# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

• Filtre métricas por equipe ou departamento
• Acompanhe custos por centro de custo
• Crie painéis específicos por 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"

​

Atribuir telemetria a sessões SSH do Desktop

{
  "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_RESOURCE_ATTRIBUTES": "host.name=build-7"
  }
}

• Você o definiu no computador que executa o Desktop: o Desktop não passa para a sessão SSH um valor que você define ali
• Você o exportou em /etc/profile ou em outro arquivo que somente shells de login leem: o nome chega quando você executa claude a partir de um shell de login, mas não em uma sessão SSH do Desktop. O Desktop não inicia o Claude Code por meio de um shell de login. Em vez disso, defina a variável em env no arquivo de configurações gerenciadas na máquina remota.
• Um valor contém um espaço: nesse caso, o Claude Code não copia nenhuma das chaves para eventos ou pontos de dados e não informa nenhum erro. Remova o espaço do valor.
• Outra coisa já define a variável: em uma sessão que o aplicativo desktop inicia, uma variável já definida no ambiente de inicialização tem precedência sobre os arquivos de configurações. O log de depuração indica cada variável ignorada. Quando uma implantação do Desktop de terceiros especifica um endpoint OTLP no ambiente que ela fornece, esse ambiente carrega o próprio OTEL_RESOURCE_ATTRIBUTES do Desktop.

​

Exemplos de configuração

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

​

Telemetria de sessões em nuvem e Claude Tag

• Configurações gerenciadas pelo servidor: adicione-as ao bloco env das configurações gerenciadas pelo servidor da sua organização. Claude Code busca essas configurações na inicialização onde as configurações gerenciadas pelo servidor se aplicam, o que inclui as máquinas dos seus usuários e sessões em nuvem diferentes das sessões do canal Claude Tag. Sessões Claude Tag não recebem suas configurações gerenciadas pelo servidor, portanto esta rota não as configura.
• As variáveis do ambiente: adicione-as às variáveis de ambiente de um ambiente em nuvem para configurar apenas as sessões executadas nesse ambiente. Esta é a rota que alcança sessões Claude Tag.

• Deixe as sessões alcançarem o coletor: Claude Code envia a exportação através da rede da sessão, portanto se ela alcança o host em seu OTEL_EXPORTER_OTLP_ENDPOINT depende do nível de acesso à rede do ambiente. Se as sessões não conseguirem alcançar o domínio do coletor no nível que você escolheu, adicione o domínio à lista de permissões do ambiente, porque nenhuma configuração gerenciada pelo servidor adiciona domínios à lista de permissões de rede de um ambiente.
• Canais Claude Tag: faça as alterações na allowlist e em qualquer variável de ambiente no ambiente compartilhado definido como padrão da sua organização ou fixado ao canal.
• Cowork é configurado separadamente: sessões Cowork não recebem configurações gerenciadas pelo servidor, como a tabela de cobertura de superfície mostra, portanto o bloco env gerenciado pelo servidor não configura sua telemetria.

​

Atribuir telemetria a sessões em nuvem

• Identificar sessões Claude Tag: defina OTEL_METRICS_INCLUDE_ENTRYPOINT=true, conforme descrito em Controle de cardinalidade de métricas. As métricas então carregam app.entrypoint, cujo valor é claude-in-slack para sessões Claude Tag.
• Adicionar atributos personalizados: defina OTEL_RESOURCE_ATTRIBUTES no mesmo local onde você define as outras variáveis OTEL_* para essas sessões. Se você export no script de configuração do ambiente, o valor não alcança Claude Code: o script de configuração é um script Bash separado que é executado antes do Claude Code ser iniciado, e as variáveis que ele exporta terminam com ele.

​

Métricas e eventos disponíveis

​

Atributos padrão

• prompt.id: UUID que correlaciona um prompt do usuário com todos os eventos subsequentes até o próximo prompt. Consulte 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, com o prefixo wf_, nos eventos de API e de ferramenta emitidos por agentes que pertencem a uma execução da ferramenta Workflow. Filtrar eventos por um workflow.run_id reconstrói as requisições de API e os resultados de ferramenta dessa execução. O identificador abrange os agentes que o script do workflow cria e quaisquer agentes que esses criem por sua vez, como invocações de skills. Ele corresponde ao identificador de execução informado no resultado da ferramenta Workflow.
• workflow.name: nome do workflow, o meta.name do seu script, emitido junto com workflow.run_id. Nomes de workflows integrados aparecem literalmente quando a execução roda o script integrado sem modificações. 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.
• agent_id: identificador do subagente que gerou o evento, como a3f2c1b4d5e6f7a80. Os eventos que o carregam incluem os eventos de API e de ferramenta de um subagente, seus eventos assistant_response e subagent_completed para o subagente concluído. Ausente em eventos da sessão principal e de colegas de equipe em processo. O agent_id do span do subagente é o mesmo valor, ou adiciona um rótulo após o a inicial, como em acompact-3f2c1b4d5e6f7a80. Requer Claude Code v2.1.310 ou posterior
• parent_agent_id: o agent_id do agente que criou ou retomou por último o subagente que gerou o evento. Ausente quando esse agente é a sessão principal. Requer Claude Code v2.1.310 ou posterior

​

Atributos de repositório

​

Métricas

​

Detalhes das métricas

​

Contador de sessões

• 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 iniciada pelo usuário em vez de uma sessão conversacional. Filtre por esse valor para separar inicializações de processos de UI de sessões conversacionais nos seus painéis.

​

Contador de linhas de código

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

​

Contador de pull requests

• Todos os atributos padrão

​

Contador de commits

• 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 o modo rápido. Ausente caso contrário
• effort: Nível de esforço aplicado à requisição: "low", "medium", "high", "xhigh" ou "max". Ausente quando o Claude Code não envia nível de esforço, por exemplo em um modelo que não oferece suporte a 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 ou por um comando /, ou herdada por um subagente gerado. Nomes de skills integradas, incluídas, definidas 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 ou o subagente ativo é 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 têm um plugin proprietário.
• marketplace.name: Marketplace de onde 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, com proxy do 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 nenhum resultado de ferramenta MCP. Antes da v2.1.222, o Claude Code definia esse atributo em todas as requisições após uma chamada de ferramenta MCP, não apenas nas requisições que consumiam um resultado de ferramenta, portanto painéis que o agregam mostram uma queda após a atualização.
• mcp_tool.name: Ferramenta MCP cujo resultado esta requisição consumiu, com o mesmo comportamento de ocultação e de versão que mcp_server.name. Ausente quando a requisição não consumiu nenhum resultado de ferramenta MCP.

​

Contador de tokens

• Todos os atributos padrão
• type: ("input", "output", "cacheRead", "cacheCreation"). O tipo "input" exclui tokens lidos do cache de prompt ou gravados nele, que são contados em "cacheRead" e "cacheCreation". O tipo "cacheCreation" conta em conjunto as gravações em cache com os tempos de vida de cache de cinco minutos e de uma hora.
• 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 o modo rápido. Ausente caso contrário
• effort: Nível de esforço aplicado à requisição. Consulte Contador de custo para obter 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. Consulte Contador de custo para definições e comportamento de ocultação.

​

Contador de decisões 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 veio a decisão. Um de "config", "hook", "user_permanent", "user_temporary", "user_abort" ou "user_reject". Consulte o Evento de decisão de ferramenta para saber 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 nos eventos tool_result e tool_decision, e nos eventos safety_event, exceto os referentes ao fim de um turno

​

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. Ocultado por padrão. Defina OTEL_LOG_USER_PROMPTS=1 para incluí-lo
• prompt_text: Mesmo valor de prompt, ocultado sob a mesma condição. Um backend que armazena nomes de atributos com pontos como objetos aninhados lê prompt.id como id dentro de um objeto chamado prompt e pode perder a string do prompt. Nesse caso, leia prompt_text. Requer Claude Code v2.1.287 ou posterior
• message.uuid: UUID da mensagem do usuário resultante, correspondente à entrada persistida na transcrição. Ausente em despachos de comandos, que podem produzir zero ou várias mensagens.
• command_name: Nome do comando quando o prompt invoca um. Nomes de comandos integrados e incluídos, como compact ou debug, são emitidos como estão; aliases como reset são emitidos conforme digitados, em vez do nome canônico. Nomes de comandos personalizados, de plugins e de MCP são reduzidos a 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 plugins são informados 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 da resposta em caracteres
• response: Texto da resposta, truncado no limite de conteúdo (60 KB por padrão). Ocultado como <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; portanto, defina OTEL_LOG_ASSISTANT_RESPONSES=0 para manter as respostas ocultadas enquanto o log de prompts estiver ativado
• model: Identificador do modelo (por exemplo, “claude-sonnet-5”)
• request_id: ID da requisição de API, descrito em Atributos de correlação de eventos
• message.uuid: UUID da entrada final da resposta na transcrição. Uma resposta de API é persistida como uma entrada de transcrição por bloco de conteúdo; esta é a última, à qual o parentUuid do próximo turno se encadeia.
• 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 exclusivo desta invocação de ferramenta. Corresponde ao tool_use_id passado aos hooks, permitindo a correlação entre eventos OTel e dados capturados por hooks.
• request_id: o request_id da resposta de API que continha esta chamada de ferramenta, para que você possa unir a chamada aos eventos de API dessa resposta. Ausente quando essa resposta não tinha ID de requisição, ou quando nenhuma resposta de API continha a chamada. Requer Claude Code v2.1.310 ou posterior
• success: "true" ou "false"
• duration_ms: Tempo de execução em milissegundos
• error_type: String da 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 só é emitido após a execução da ferramenta. Chamadas rejeitadas não produzem um resultado de ferramenta
• decision_source: De onde veio a decisão de permissão. Um de "config", "hook", "user_permanent" ou "user_temporary". Consulte o Evento de decisão de ferramenta para saber o que cada valor significa. As origens exclusivas 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)
• vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (quando OTEL_LOG_TOOL_DETAILS=1): a identidade do commit de um git commit bem-sucedido executado pela ferramenta Bash ou PowerShell. vcs.ref.head.revision é o SHA do commit, vcs.ref.head.name é o branch em que o commit foi feito e vcs.ref.head.type é branch. O nome e o 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 os servidores integrados do Claude Desktop, em sessões que pertencem ao Claude Desktop, o par mcp_server_name/mcp_tool_name é incluído mesmo com a flag desativada, a mesma exceção definida pelo host que no Evento de decisão de ferramenta. Os parâmetros variam por ferramenta:
  • Para a ferramenta Bash: inclui bash_command, full_command, timeout, description e dangerouslyDisableSandbox, além de 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 em que o commit foi feito, omitido em um HEAD desanexado
  • Para a ferramenta Bash do workspace do aplicativo desktop, que também informa tool_name como Bash: inclui apenas bash_command, full_command e timeout
  • Para ferramentas MCP: inclui mcp_server_name, mcp_tool_name
  • Para a ferramenta Skill: inclui skill_name
  • Para a ferramenta Agent ou a ferramenta legada Task: inclui subagent_type
• tool_input (quando OTEL_LOG_TOOL_DETAILS=1): Argumentos da ferramenta serializados em JSON. Valores individuais com mais 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, excluindo tokens lidos do cache de prompt ou gravados nele
• 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
• cache_creation_5m_tokens, cache_creation_1h_tokens: o número de tokens que a resposta da API informa como gravados no cache com um tempo de vida de cache de cinco minutos e o número gravado com um tempo de vida de uma hora. Ambos são 0 quando a resposta da API não os informa, mesmo quando cache_creation_tokens é maior que zero. Requer Claude Code v2.1.300 ou posterior
• request_id: ID da 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 cabeçalho de requisição x-client-request-id; consulte a tabela de atributos de correlação de eventos para saber quando ele está presente
• 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 o Claude Code não envia nível de esforço, por exemplo em um modelo que não oferece suporte a 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. Consulte Contador de custo para definições e comportamento de ocultaçã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 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 de tentativas feitas, incluindo a requisição inicial. Detectar o esgotamento de novas tentativas indica quando a contagem recomeça
• request_id: ID da 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 cabeçalho de requisição x-client-request-id. Disponível mesmo quando uma falha, como um timeout ou erro de conexão, nunca produziu um request_id do servidor; consulte a tabela de atributos de correlação de eventos para saber quando ele está presente.
• 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 o Claude Code não envia nível de esforço, por exemplo em um modelo que não oferece suporte a 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. Consulte Contador de custo para definições e comportamento de ocultaçã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 da 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. Consulte api_request para definições.
• speed: "fast" quando o modo rápido está ativo, ou "normal"
• attempt: Número da tentativa. A primeira tentativa é 1.
• effort: Nível de esforço aplicado à requisição. Ausente quando o Claude Code não envia nível de esforço, por exemplo em um modelo que não oferece suporte a esforço.
• server_fallback_hop: true quando o fallback de modelo no lado do servidor da API já tentou novamente esta recusa em um modelo diferente, de modo que o usuário não viu esta recusa em particular. false quando a requisição terminou em uma recusa. Um único turno pode emitir tanto um evento de salto true quanto um evento final false posterior quando o modelo de fallback também recusa.
• has_category: true quando a resposta da API carregou um stop_details.category de "cyber", "bio", "frontier_llm" ou "reasoning_extraction". false quando a resposta não carregou nenhuma categoria ou um valor fora desse conjunto. Ausente quando server_fallback_hop é true, porque blocos de salto não carregam stop_details.
• has_explanation: true quando a resposta da API carregou um stop_details.explanation, caso contrário false. Ausente quando server_fallback_hop é true.
• category: O valor de 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. Consulte Contador de custo para definições e comportamento de ocultaçã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 Messages API serializados em JSON, como o system prompt, mensagens e ferramentas, truncados no limite de conteúdo (60 KB por padrão). O conteúdo de pensamento estendido em turnos anteriores do assistente é ocultado. Emitido apenas no 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 no modo de 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 ocorreu truncamento inline. Ausente no modo de arquivo e quando não ocorreu truncamento.
• model: Identificador do modelo dos parâmetros da requisição
• query_source: Subsistema que emitiu a requisição (por exemplo, "compact")
• request_body_id: UUID que identifica o corpo da requisição desta tentativa. O evento api_response_body da tentativa bem-sucedida carrega o mesmo valor, para que você possa 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 Messages API serializada em JSON, incluindo o id, blocos de conteúdo, uso e motivo de parada, truncada no limite de conteúdo (60 KB por padrão). O conteúdo de pensamento estendido é ocultado. Emitido apenas no 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 no modo de 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 ocorreu truncamento inline. Ausente no modo de arquivo e quando não ocorreu truncamento.
• model: Identificador do modelo
• query_source: Subsistema que emitiu a requisição
• request_id: ID da 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 ao qual esta resposta responde. Requer Claude Code v2.1.274 ou posterior
• message.id: ID da 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 resposta na transcrição. Junto com request_body_id, ele vincula uma mensagem da transcrição aos corpos de requisição e resposta por trá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 exclusivo desta invocação de ferramenta. Corresponde ao tool_use_id passado aos hooks, permitindo a correlação entre eventos OTel e dados capturados por hooks.
• request_id: o request_id da resposta de API que continha esta chamada de ferramenta, para que você possa unir a chamada aos eventos de API dessa resposta. Ausente quando essa resposta não tinha ID de requisição, ou quando nenhuma resposta de API continha a chamada. Requer Claude Code v2.1.310 ou posterior
• decision: "accept" ou "reject"
• tool_source: Sempre presente. A procedência da ferramenta, como um conjunto fechado de valores definidos pela CLI:
  • "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 pertence ao Claude Desktop. Uma sessão pertence ao Claude Desktop quando ele a iniciou a partir de um de seus próprios entrypoints, claude-desktop, claude-desktop-3p ou local-agent, e essa sessão não é filha aninhada; sessões aninhadas, incluindo sessões que o próprio Claude Code gera, informam esses servidores como "mcp"
• source: De onde veio a decisão:
  • "config": Decidido automaticamente sem solicitar confirmação, por uma destas origens:
    • Configurações do projeto
    • Regras de permissão ou negação nas configurações pessoais do usuário
    • Política gerenciada corporativa
    • Flags --allowedTools ou --disallowedTools
    • O modo de permissão ativo
    • O classificador do modo auto, cujo veredito o mesmo evento registra em classifier_verdict
    • Uma concessão para o restante da sessão, dada em um prompt de permissão anterior na mesma sessão interativa da CLI
    • A ferramenta ser inerentemente segura
    O valor de source não indica qual dessas origens correspondeu. Para descobrir qual delas recusou uma chamada, procure o Evento de segurança com o mesmo tool_use_id e leia seus atributos category e rule_source. Algumas chamadas recusadas não têm evento de segurança. O Claude Code também informa "config" quando a própria requisição do prompt de permissão falha. Por exemplo, essa requisição falha quando o callback canUseTool do Agent SDK ou a ferramenta --permission-prompt-tool retorna um resultado inválido, ou quando o stream de entrada é fechado enquanto a requisição está pendente.
  • "hook": Um hook PreToolUse ou PermissionRequest retornou a decisão.
  • "user_permanent": Emitido quando o usuário escolheu “Yes, and don’t ask again for …” em um prompt de permissão, o que salva uma regra de allow nas suas configurações pessoais. Na CLI interativa, isso é emitido apenas para essa escolha em si; chamadas posteriores que correspondem à regra salva emitem "config". Em sessões do Agent SDK ou não interativas com -p, tanto a escolha inicial quanto as correspondências posteriores com a regra emitem "user_permanent". Tratado como aceitação.
  • "user_temporary": Emitido quando o usuário escolheu “Yes” em um prompt de permissão para uma aprovação única, ou escolheu uma opção que concede acesso pelo restante da sessão em um prompt 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 sessões do Agent SDK ou não interativas com -p, tanto a escolha quanto as correspondências posteriores emitem "user_temporary". Tratado como aceitação.
  • "user_abort": Emitido quando o usuário dispensou o prompt de permissão sem responder. Em sessões do Agent SDK e não interativas com -p, isso inclui interromper o turno enquanto uma requisição de permissão de canUseTool ou --permission-prompt-tool está pendente. Tratado como rejeição.
  • "user_reject": Emitido quando o usuário escolheu “No” ao ser solicitado. Na CLI interativa, isso é emitido apenas para essa escolha em si; chamadas que correspondem a uma regra de deny nas configurações pessoais do usuário emitem "config". Em sessões do Agent SDK ou não interativas com -p, chamadas que correspondem a uma regra de deny nas configurações pessoais emitem "user_reject". Tratado como rejeição.
• classifier_verdict: O veredito do classificador do modo auto para a chamada, ou o motivo pelo qual o Claude Code negou a chamada quando nenhum veredito veio. Requer Claude Code v2.1.301 ou posterior
  • "allow": o classificador aprovou a chamada
  • "block": o classificador bloqueou a chamada. Uma verificação do classificador que falha no meio do caminho também pode terminar como "block", portanto uma indisponibilidade parcial do classificador pode aparecer como mais bloqueios em vez de como "unavailable"
  • "no_verdict": a verificação foi executada, mas não deu nenhum veredito utilizável, então o Claude Code negou a chamada. A negação não significa que o classificador considerou a chamada insegura
  • "unavailable": a requisição ao classificador falhou, por exemplo por rate limit, timeout ou erro de conexão, então o Claude Code negou a chamada. Com a revisão do classificador no lado do servidor, também marca uma chamada negada porque o servidor não retornou nenhum veredito de segurança
  O atributo também aparece em chamadas no modo de planejamento quando o classificador revisa comandos no modo de planejamento. O atributo está ausente nestes casos:
  • Uma regra de permissão de permissão ou negação decidiu a chamada
  • O Claude Code aprovou a chamada no modo auto sem consultar o classificador
  • O usuário respondeu ao prompt que o Claude Code mostrou após bloqueios repetidos
  • Em uma execução com -p sem --permission-prompt-tool, o Claude Code negou a chamada após bloqueios repetidos porque não havia ninguém para responder a um prompt. Esse evento informa decision como "reject" e source como "config"
• classifier_category (quando OTEL_LOG_TOOL_DETAILS=1): O nome da regra integrada que o classificador indicou quando bloqueou a chamada, em minúsculas com sublinhados, como "data_exfiltration" para a regra Data Exfiltration. Requer Claude Code v2.1.301 ou posterior. O atributo está presente quando ambas as condições são verdadeiras:
  • classifier_verdict é "block"
  • O classificador indicou exatamente uma regra, e essa regra é integrada, e não uma que você escreveu
  Antes da v2.1.302, o atributo também estava ausente em qualquer bloqueio decidido pela revisão do classificador do lado do servidor.
• permission_mode: Modo de permissão ativo quando a verificação de permissão desta chamada começou: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" ou "auto". O modo manual aparece como "default". Uma chamada de subagente informa o modo de permissão do subagente em vez do da sessão. Requer Claude Code v2.1.301 ou posterior
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): String JSON contendo parâmetros específicos da ferramenta. Mesmo formato que o Evento de resultado de ferramenta, sem os 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 por meio de 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 o aplicativo host define esses nomes; sem eles, uma chamada rejeitada a um desses servidores integrados não poderia ser atribuída 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 da ferramenta aparecem apenas em tool_parameters com a flag ativada; o conteúdo dos argumentos requer a flag em todos os casos.
  • Para a ferramenta Bash: inclui bash_command, full_command, timeout, description, dangerouslyDisableSandbox. A ferramenta bash do workspace do aplicativo desktop também informa tool_name como Bash, mas inclui apenas bash_command, full_command e timeout
  • Para ferramentas MCP: inclui mcp_server_name, mcp_tool_name
  • Para a ferramenta Skill: inclui skill_name
  • Para a ferramenta Agent ou a ferramenta legada Task: inclui subagent_type

1. parent_agent_id
2. agent_id
3. request_id
4. permission_mode
5. classifier_category
6. classifier_verdict

​

Evento de segurança

• Todos os atributos padrão
• event.name: "safety_event"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contador por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• category: A verificação ou o resultado, um valor de categoria
• decision: "accept", "reject" ou "sent_back" quando um hook bloqueou um resultado ou o fim de um turno
• decision_source: Quem ou o que decidiu, um valor de source de tool_decision ou "other"
• reason_code: O motivo da verificação, como "rule:policySettings", "mode:dontAsk", "hook:PreToolUse", "classifier:auto-mode", "bashMiss:too-complex" ou "unknown"
• reason_type: O tipo de motivo da verificação, como "rule", "subcommandResults", "mode", "hook", "classifier" ou "asyncAgent"
• rule_source: Origem de configuração da regra envolvida, como "policySettings", "userSettings", "projectSettings", "localSettings", "flagSettings", "cliArg" ou "session"
• grant_scope: "once" ou "session" para um prompt aprovado sem salvar uma regra em um arquivo de configurações
• circuit_breaker: A verificação de segurança integrada, como "dangerousRemoval", "outsideReadsBlocked" ou "claudeSettingsFile"
• classifier_category: Com OTEL_LOG_TOOL_DETAILS=1, a regra integrada por trás de um bloqueio do modo auto, como "data_exfiltration"
• hook_event: "pre_tool_use" para um hook PreToolUse, ou "post_tool_use", "post_tool_use_failure", "stop" ou "subagent_stop" em eventos "hook_review"
• tool_class: "bash" para Bash e Monitor, "powershell", "file" para Read, Edit, Write, NotebookEdit, Glob e Grep, "web" para WebFetch e WebSearch, "mcp" ou "other"
• tool_name: O nome da ferramenta, como "Bash" para uma ferramenta integrada, ou "mcp_tool", "skill_tool", "dynamic_tool" ou "other_tool"
• tool_source: "builtin", "mcp" ou "sdk_host_builtin_mcp", como em tool_decision
• permission_mode: O modo de permissão da chamada no momento da verificação: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" ou "auto"
• tool_use_id: O ID da chamada, como em tool_decision e tool_result
• sandbox_violation_count: Quantas conexões ou requisições distintas do comando da chamada o proxy de rede do sandbox recusou, de "0" a "20", como string. As recusas são contadas para um comando em sandbox que terminou em primeiro plano
• sandbox_enabled: "true" se o sandboxing estiver ativado para a sessão, caso contrário "false"

{
  "event.name": "safety_event",
  "category": "managed_policy",
  "decision": "reject",
  "decision_source": "config",
  "reason_code": "rule:policySettings",
  "rule_source": "policySettings",
  "tool_class": "bash",
  "tool_name": "Bash",
  "tool_source": "builtin",
  "permission_mode": "default",
  "tool_use_id": "toolu_01ABC123...",
  "sandbox_violation_count": "0",
  "sandbox_enabled": "false"
}

• Uma chamada aprovada em um prompt sem categoria
• Uma chamada que um callback canUseTool ou uma ferramenta --permission-prompt-tool aprovou em um prompt exigido apenas por um hook PreToolUse
• Uma chamada de AskUserQuestion ou ExitPlanMode, recusada ou não

​

Evento de alteração do 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 alteração, por exemplo "shift_tab", "exit_plan_mode" ou "auto_gate_denied". Ausente em algumas alterações, como quando o SDK define o modo de permissão por meio de setPermissionMode()

​

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 categórico de erro 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 de 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 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 do marketplace, para agrupar eventos por plugin sem expor o nome. O Claude Code o calcula conforme descrito no evento de plugin carregado
• plugin.name (quando is_plugin é true): Nome do plugin que fornece o servidor. Para plugins de terceiros, esta é a string literal "third-party", a menos que OTEL_LOG_TOOL_DETAILS=1; isso impede que nomes de plugins de terceiros apareçam nos logs por padrão. Plugins de fontes oficiais da Anthropic são sempre identificados pelo nome. Os atributos plugin_id_hash e plugin.name fluem para o seu próprio backend de monitoramento e não são enviados à 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 do 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 for um marketplace oficial da Anthropic, "false" caso contrário
• install.trigger: "cli" ou "ui"
• plugin.name: Nome do plugin instalado. Para marketplaces de terceiros, é 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, é incluída apenas quando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace de onde o plugin foi instalado. Para marketplaces de terceiros, é 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 do pacote integrado, o valor é "third-party", a menos que OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: marketplace de onde o plugin foi instalado, quando conhecido. Ocultado como "third-party" sob a mesma condição que plugin.name
• plugin.version: versão do manifesto do plugin. Incluída apenas quando o nome não está ocultado e o manifesto declara uma versão
• plugin.scope: categoria de procedência do plugin: "official", "community", "org", "user-local" ou "default-bundle"
• enabled_via: como o plugin passou a estar 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 de instalação automática para a sua organização em Organization settings > Plugins & skills. Antes da v2.1.246, o Claude Code informava esses plugins como "user-install" ou "seed-mount"
• plugin_id_hash: hash determinístico do nome do plugin e do marketplace, enviado apenas ao seu exportador configurado. Permite contar os plugins de terceiros distintos carregados em toda a sua frota sem registrar seus nomes. Para plugins sincronizados do claude.ai, o Claude Code calcula o hash do nome do plugin com o nome do marketplace que o claude.ai informa para o plugin, ou com synced caso contrário. Antes da v2.1.246, o Claude Code não usava no hash o nome do marketplace informado pelo claude.ai
• has_hooks: se o plugin contribui com hooks, por meio de configuração de hooks ou como um mod
• has_mcp: se o plugin contribui com servidores MCP
• host_owned_mcp: true quando o host do SDK gerencia as conexões MCP deste plugin e o Claude Code deixou de ler a configuração de servidor MCP do plugin, false caso contrário
• skill_path_count: número de diretórios de skills que o plugin declara
• command_path_count: número de diretórios de comandos que o plugin declara
• agent_path_count: número de diretórios de agentes que o plugin declara
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. No modo seguro, este evento informa apenas o inventário configurado; os comandos, skills, hooks e servidores MCP do plugin não são carregados. 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 de onde o plugin proprietário foi instalado, quando a skill é fornecida por um plugin

​

Evento de menção com @

• 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 das suas outras sessões do Claude Code. Requer Claude Code v2.1.232 ou posterior
• success: Se a menção foi resolvida com sucesso ("true" ou "false")

​

Evento de novas tentativas 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 número. Ausente para erros não HTTP.
• total_attempts: Número total de tentativas feitas
• total_retry_duration_ms: Tempo total de relógio 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 do hook, como "PreToolUse" ou "PostToolUse"
• hook_type: tipo de implementação do hook: "command", "prompt", "mcp_tool", "http" ou "agent"
• hook_source: onde o hook está 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 do matcher da configuração do hook, quando houver uma definida
• plugin.name (quando hook_source é "pluginHook"): nome do plugin contribuinte. Para plugins fora do marketplace oficial e do 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 do marketplace, enviado apenas ao seu exportador configurado. Permite contar os plugins contribuintes distintos sem registrar seus nomes. O Claude Code o calcula 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 do hook, como "PreToolUse" ou "PostToolUse"
• hook_name: Nome completo do hook incluindo o 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 do hook serializada em JSON. Incluída apenas quando o tracing beta detalhado e OTEL_LOG_TOOL_DETAILS=1 estão ambos habilitados

​

Evento de conclusão da execução de hooks

• 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 o matcher
• num_hooks: Número de comandos de hook correspondentes
• num_success: Quantidade que foi concluída com sucesso
• num_blocking: Quantidade que retornou uma decisão de bloqueio
• num_non_blocking_error: Quantidade que falhou sem bloquear
• num_cancelled: Quantidade cancelada antes da conclusão
• total_duration_ms: Duração em tempo real de todos os hooks correspondentes
• stdout_chars: Total de caracteres de stdout dos 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 hooks acima do limite de 10.000 caracteres que o 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 hooks serializada em JSON. Incluído somente quando tanto o rastreamento beta detalhado quanto OTEL_LOG_TOOL_DETAILS=1 estão 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 por processo para ordenar eventos, descrito em Atributos de correlação de eventos
• plugin_id: identificador do plugin no formato <name>@<marketplace>
• hook_event: tipo de evento de hook que emitiu as métricas
• Até 20 chaves de métricas 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 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 a compactação
• error: Mensagem de erro quando a compactação falhou
• precompute_reuse: Definido apenas quando trigger é "manual", ou quando trigger é "auto" para uma compactação por inatividade em uma sessão interativa no terminal. A compactação automática pode preparar um resumo em segundo plano antes que a janela de contexto se encha, e este atributo registra se a compactação reutilizou esse resumo preparado. "hit" significa que ele foi reutilizado; "miss_custom_instructions", "miss_hook" e "miss_not_ready" indicam o motivo pelo qual um novo resumo foi calculado em vez disso

​

Evento de subagente concluído

• 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 agentes são substituídos por "custom", a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido
• agent.source: De onde veio a definição do agente: 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 foi executado em segundo plano
• total_tokens: A quantidade de tokens da requisição final da API do subagente: os 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 ao longo da execução
• total_tool_uses: Número de chamadas de ferramenta que o subagente fez ao longo de toda a execução
• duration_ms: Tempo de execução em milissegundos
• model: O modelo com o qual o subagente foi resolvido para executar
• final_model: O modelo que produziu a resposta final do subagente, que difere de model após uma troca no meio da execução, como um fallback
• model_swapped: Se mais de um modelo atendeu às requisições do subagente
• plugin_id_hash, plugin.name: Presentes para agentes fornecidos por plugins. Nomes de plugins do marketplace oficial aparecem literalmente; outros nomes de plugins 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 exclusivo que vincula os eventos emitidos para uma instância de pesquisa
• survey_type: Qual pesquisa produziu o evento. "session" é o prompt de avaliação “How is Claude doing?”
• 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 booleano, não como string. Presente em eventos de pesquisa session. Filtre por este atributo para confirmar que a substituição está aplicada em toda 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 o Claude Code a pausou
• period_days: O valor de cleanupPeriodDays das configurações mescladas, em dias, ou 30 quando nenhuma fonte o define. Em eventos ignorados, o valor que a varredura teria usado, calculado a partir das fontes de configurações que o Claude Code conseguiu ler
• used_default: "true" quando nenhuma fonte de configurações legível define cleanupPeriodDays, "false" caso contrário. Em eventos concluídos, "true" significa que o padrão de 30 dias foi aplicado
• skip_reason: Por que o Claude Code pausou a varredura. Presente apenas quando result é "skipped":
  • "user_source_disabled": As configurações do usuário estão excluídas, por exemplo pela flag --setting-sources ou pela opção settingSources do SDK, e nenhuma origem habilitada fornece cleanupPeriodDays
  • "settings_unknowable": Um arquivo de configurações não pôde ser lido ou analisado, portanto cleanupPeriodDays ou desktopSessionCleanupPeriodDays pode estar definido com um valor que o Claude Code não consegue ver
  • "settings_invalid_key_set": As configurações têm erros de validação e cleanupPeriodDays ou desktopSessionCleanupPeriodDays está explicitamente definido, portanto recorrer ao padrão poderia excluir ou manter arquivos em desacordo com essa configuração
  • "remote_settings_unknowable": Uma sessão na aba Code do Claude Desktop em uma implantação de terceiros solicitou configurações gerenciadas pelo servidor. Ela não recebeu nenhuma resposta utilizável, portanto cleanupPeriodDays pode estar definido com um valor que o Claude Code não consegue ver
• transcripts_deleted: Número de transcrições de sessão, os arquivos de nível superior ~/.claude/projects/*/*.jsonl, que a varredura excluiu
• transcripts_exempted_desktop: Número de transcrições além do período de retenção que a varredura manteve pela regra do Claude Desktop e Cowork. Elas 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 excluiu: transcrições mais arquivos complementares por sessão, como sidecars, gravações e resultados de ferramentas
• artifacts_deleted: Total de itens que a varredura excluiu nos diretórios de dados que ela abrange, incluindo os arquivos de sessão. Algumas varreduras contam uma árvore de diretórios removida inteira como um item e algumas etapas de limpeza não contribuem para o contador, então trate o valor como um mínimo e não como uma contagem exata de arquivos
• files_retained_fresh: Arquivos inspecionados e mantidos porque ainda estão dentro do período de retenção. Somente varreduras por arquivo os contam, então o valor é um mínimo; um valor diferente de zero é o estado normal
• files_past_cutoff: Arquivos mais antigos que o período de retenção que a varredura não conseguiu excluir, por exemplo por causa de um erro de permissão ou de um arquivo mantido aberto. A contagem também inclui cada pasta obsoleta que a varredura encontra em skills/synced/ ou plugins/synced/, quer ela mova a pasta para a lixeira ou não. Além dessas pastas, um valor acima de zero significa que arquivos sobreviveram ao período de retenção configurado; zero não é prova de que nenhum sobreviveu, porque uma falha ao remover um diretório inteiro conta para error_count em vez disso
• error_count: Número de erros que a varredura encontrou ao listar ou excluir arquivos

​

Evento de configurações gerenciadas resolvidas

• Defina-o no bloco env das configurações gerenciadas, das configurações do usuário ou de --settings, ou no ambiente com o qual você inicia o Claude Code. Um valor nas configurações do projeto ou locais não o ativa, porque um repositório clonado pode gravá-las.
• As configurações gerenciadas pelo servidor podem defini-lo sem exibir a caixa de diálogo de aprovação de segurança, porque a variável apenas adiciona a própria política redigida da sua 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 da 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 interrompeu a sessão. O Claude Code envia um evento change somente quando um atributo difere do último evento enviado, e um valor de configuração alterado conta mesmo quando OTEL_LOG_MANAGED_SETTINGS está desativado
• error.type: por que o Claude Code interrompeu a sessão. Presente somente 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 o Claude Code de iniciar, ou uma fonte de administrador falhou ao carregar por um motivo diferente de leitura negada, então o Claude Code não consegue verificar o login da organização ou a imposição de provedor
  • "provider_not_allowed": a sessão usaria um provedor de API, ou enviaria o tráfego de um provedor para um host, que a lista gerenciada allowedProviders não permite. Requer Claude Code v2.1.285 ou posterior
  • "consent_rejected": o usuário rejeitou a caixa de diálogo de aprovação de segurança para configurações gerenciadas pelo servidor
  • "force_refresh_failed": a busca de configurações exigida por forceRemoteSettingsRefresh falhou
  • "gateway_rejected": um gateway de aplicativos Claude respondeu ao carregamento das configurações gerenciadas com HTTP 403
  • "version_below_minimum": esta versão do Claude Code está abaixo de requiredMinimumVersion ou acima de requiredMaximumVersion
  • "_OTHER": o carregamento das configurações gerenciadas do gateway de aplicativos Claude falhou por outro motivo
• managed_settings.sources: toda fonte gerenciada que fornece pelo menos uma chave de política, da maior prioridade para a menor, incluindo fontes cujas chaves não têm efeito em first-wins. Os valores são "remote", "plist" ou "hklm" para a política MDM ou de nível do sistema operacional, "file" para arquivos de configurações gerenciadas e drop-ins, "parent" quando um host incorporador fornece configurações, e "hkcu" para o valor do registro HKCU do Windows quando o Claude Code o lê. Uma fonte que contém apenas chaves de controle, ou que o Claude Code não conseguiu ler, não é listada. Emitido como um array de strings, vazio quando nenhuma fonte gerenciada fornece uma chave de política
• managed_settings.source_behavior: o valor de managedSourcesBehavior que o 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 de 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 nem um arquivo de configurações gerenciadas
• managed_settings.helper.applied: "output" enquanto a própria saída do auxiliar serve como as configurações gerenciadas, "none" quando não serve
• managed_settings.helper.entry: "policyHelper" quando o Claude Code selecionou um policyHelper. Ausente quando nenhum auxiliar foi selecionado
• managed_settings.helper.path: o path configurado do auxiliar. Presente sempre que o Claude Code selecionou um auxiliar, esteja OTEL_LOG_MANAGED_SETTINGS definido ou não
• 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ços em branco. Máquinas com o mesmo digest executam a mesma política. O Claude Code envia o digest somente com a ativação opcional porque uma política curta pode ser recuperada calculando hashes de tentativas. Ausente quando nenhuma configuração gerenciada foi resolvida e em eventos refused
• managed_settings.settings (quando OTEL_LOG_MANAGED_SETTINGS=1): os nomes e a estrutura das configurações gerenciadas resolvidas como uma string JSON, com os valores redigidos. Ausente em eventos refused. O Claude Code o constrói a partir do seu esquema de configurações:
  • Um nome de configuração que o esquema declara é exportado, e uma chave que ele não declara é omitida
  • 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]"
  • Todas as outras strings, como model, apiKeyHelper, todos os valores de env, todas as URLs e todos os comandos, são exportadas como "[REDACTED]"
  • Os nomes das entradas de mapas, como nomes de variáveis de env e IDs de plugins, são exportados como estão. Uma configuração cujas entradas o esquema não tipa, como vimInsertModeRemaps, é exportada como um único "[REDACTED]", e sandbox.ignoreViolations é exportado como uma lista de suas listas de caminhos sem os padrões de comando
  • Uma lista mantém seu comprimento, com cada entrada redigida pelas mesmas regras
  • Uma regra permissions.allow, permissions.deny ou permissions.ask é exportada como o nome da ferramenta com o conteúdo redigido, como Read([REDACTED]), quando a ferramenta está integrada a esta versão do 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ções fixas e numéricos, como type e timeout, aparecem, enquanto cada comando, URL, matcher e condição if é exportado como "[REDACTED]"
  Por exemplo, configurações gerenciadas com apiKeyHelper, duas variáveis de 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])"]}}. O 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 o Claude Code cortou managed_settings.settings em 8 KB, false caso contrário. Emitido como booleano, não como 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

​

Mapear tokens de entrada para as convenções semânticas GenAI do OpenTelemetry

• input_tokens no span claude_code.llm_request e no evento api_request
• O tipo "input" da métrica claude_code.token.usage

• A partir do span ou evento: some input_tokens, cache_read_tokens e cache_creation_tokens
• A partir da métrica claude_code.token.usage: some seus tipos "input", "cacheRead" e "cacheCreation"

• cache_read_tokens corresponde a gen_ai.usage.cache_read.input_tokens
• cache_creation_tokens corresponde a gen_ai.usage.cache_write.input_tokens. Versões mais antigas das convenções nomeiam o atributo de gravação de cache como gen_ai.usage.cache_creation.input_tokens, portanto use o nome que seu backend espera.

​

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
• 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
• 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

​

Mapear caminhos de saída para controles gerenciados e eventos

• allowedHttpHookUrls: as entradas são mescladas entre os arquivos de configurações, então um desenvolvedor pode adicionar itens a uma lista gerenciada vazia. allowManagedHooksOnly decide quais hooks são executados
• managed-mcp.json: para desativar o MCP, veja Desativar o MCP completamente. Para confirmar que Claude Code lê o arquivo, veja Validar a configuração
• Eventos de hook: Claude Code registra hook_execution_start e hook_execution_complete uma vez por evento de hook, abrangendo todos os hooks correspondentes. OTEL_LOG_TOOL_DETAILS=1 sozinho não registra a URL de um hook HTTP. A configuração do hook aparece apenas em hook_definitions, que também exige o rastreamento beta detalhado

​

Verificar a varredura de retenção

• Ninguém inicia o Claude Code: nenhuma varredura é executada, e a máquina mantém seus dados até a próxima inicialização
• Uma sessão permanece aberta: Claude Code executa a varredura no máximo uma vez por sessão
• Uma sessão termina cedo: uma varredura que não terminou quando a sessão é encerrada não emite nada, assim como uma que para devido a um erro inesperado

​

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

​

Backends 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

​

Backends para eventos e 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

​

Backends 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 locais 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 locais 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 do OpenTelemetry para o seu backend é opcional e requer configuração explícita. Para a telemetria operacional separada da Anthropic e como desativá-la, consulte Uso de dados
• O conteúdo bruto de arquivos e trechos de código não são incluídos em métricas ou eventos. Os spans de trace são um caminho de dados separado: consulte o item sobre OTEL_LOG_TOOL_CONTENT abaixo
• Quando autenticado via OAuth, user.email é incluído nos atributos de telemetria, enviado apenas para o endpoint OTel que você configurar, nunca para a Anthropic. Se isso for uma preocupação para a sua organização, trabalhe com o seu backend de telemetria para filtrar ou ocultar esse campo
• O conteúdo dos prompts do usuário não é coletado por padrão. Apenas o comprimento do prompt é registrado. Para incluir o conteúdo do prompt, defina OTEL_LOG_USER_PROMPTS=1. Quando ativado:
  • Os eventos user_prompt carregam o texto do prompt em dois atributos, prompt e prompt_text. Se você descartar ou mascarar o texto do prompt do evento pelo nome do atributo no seu coletor, nomeie ambos os atributos na regra Este processador attributes do OpenTelemetry Collector exclui ambos os atributos nos pipelines que o listam:
    processors:
      attributes/drop-prompt-text:
        actions:
          - key: prompt
            action: delete
          - key: prompt_text
            action: delete
    
  • Com o tracing ativado, o span claude_code.interaction carrega o texto do prompt no seu atributo user_prompt
  • No tracing beta detalhado, os spans também carregam as novas mensagens do usuário, resultados de ferramentas e lembretes do sistema enviados com cada requisição, o texto do system prompt e a saída do modelo. Atributos de conteúdo no tracing beta detalhado lista cada atributo. O evento claude_code.system_prompt carrega o system prompt completo
• O texto das respostas do assistente não é coletado por padrão. Apenas o comprimento da resposta é registrado. Para incluir o texto da resposta, defina OTEL_LOG_ASSISTANT_RESPONSES=1. Como todos os dados do OpenTelemetry do Claude Code, o texto da resposta é enviado apenas para o endpoint OTel que você configurar, nunca para a Anthropic. Quando essa variável não está definida, OTEL_LOG_USER_PROMPTS é usada como fallback, então defina OTEL_LOG_ASSISTANT_RESPONSES=0 se quiser o conteúdo do prompt sem o conteúdo da resposta nos eventos. No tracing beta detalhado, o span claude_code.llm_request ainda carrega a saída do modelo em response.model_output, que segue OTEL_LOG_USER_PROMPTS em vez dessa variável
• Os argumentos e parâmetros de entrada das ferramentas não são registrados em log por padrão. Para incluí-los, defina OTEL_LOG_TOOL_DETAILS=1. Para os servidores integrados do Claude Desktop, em sessões que pertencem ao Claude Desktop, tool_decision e tool_result carregam o par mcp_server_name/mcp_tool_name, nomes definidos pelo host em vez de conteúdo de argumentos, mesmo com a flag desativada. Esses dados são enviados apenas para o endpoint OTEL que você configurar, nunca para a Anthropic. Os argumentos ainda podem conter valores sensíveis, então configure o seu backend de telemetria para filtrar ou ocultar esses atributos conforme necessário. Quando ativado:
  • Os eventos tool_result e tool_decision incluem um atributo tool_parameters com comandos Bash, nomes de servidores MCP e de ferramentas, e nomes de skills. Campos como full_command são emitidos sem truncamento
  • Os eventos tool_result incluem adicionalmente um atributo tool_input com caminhos de arquivos, URLs, padrões de pesquisa e outros argumentos. Valores individuais com mais de 512 caracteres são truncados e o total é limitado a ~4 K caracteres
  • Os eventos user_prompt incluem o command_name literal para comandos personalizados, de plugins e MCP
  • Os contadores de custo e de tokens e os eventos api_request, api_error e api_refusal carregam os nomes reais de agentes, skills, plugins, servidores MCP e ferramentas nos seus atributos de atribuição
  • O span claude_code.tool carrega atributos derivados da entrada, como file_path. No tracing beta detalhado, ele também carrega um atributo tool_input
• O conteúdo das ferramentas não é registrado em log nos spans de trace por padrão. Para incluí-lo, defina OTEL_LOG_TOOL_CONTENT=1. O span claude_code.tool passa então a carregar um evento de span tool.output com o conteúdo bruto de arquivos, a saída de comandos Bash e o que as ferramentas MCP, WebFetch e WebSearch retornam, truncados no limite de conteúdo (60 KB por padrão) por atributo. Os resultados de ferramentas MCP, WebFetch e WebSearch requerem o Claude Code v2.1.283 ou posterior. O conteúdo das ferramentas também chega aos spans por meio de new_context, cuja condição difere por span. Configure o seu backend de telemetria para filtrar ou ocultar esses atributos conforme necessário
• Os corpos brutos de requisição e resposta da Anthropic Messages API não são registrados em log por padrão. Para incluí-los, defina OTEL_LOG_RAW_API_BODIES no seu shell, nas configurações de usuário ou nas configurações gerenciadas. Ela é ignorada nas configurações de projeto e locais. Os corpos contêm o histórico completo da conversa, incluindo o system prompt, todos os turnos anteriores do usuário e do assistente, e os resultados de ferramentas, portanto ativar essa opção implica consentimento com tudo o que as outras flags de conteúdo OTEL_LOG_* revelariam. O Claude Code sempre remove (oculta) 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, o Claude Code emite eventos de log api_request_body e api_response_body para cada chamada de API. O atributo body dos eventos carrega o payload serializado em JSON, truncado no limite de conteúdo (60 KB por padrão)
  • Com =file:<dir>, o Claude Code grava os corpos sem truncamento em arquivos .request.json e .response.json nesse diretório, e os eventos carregam um caminho body_ref em vez do corpo embutido. Envie o diretório com um coletor de logs ou sidecar, em vez de pelo fluxo de telemetria. Para cada resposta bem-sucedida, o Claude Code também acrescenta uma linha ao index.jsonl nesse diretório, vinculando o arquivo de resposta ao arquivo de requisição que a produziu e à mensagem da transcrição em que ela se tornou. Cada linha não contém conteúdo de mensagens, e a seção evento de corpo de resposta da API lista seus campos. O arquivo de índice requer o Claude Code v2.1.274 ou posterior

​

Monitorar Claude Code no Amazon Bedrock