Cabeçalhos dinâmicos

Para ambientes corporativos que exigem autenticação dinâmica, você pode configurar um script para gerar cabeçalhos dinamicamente. Cabeçalhos dinâmicos se aplicam somente aos protocolos http/protobuf e http/json. Com o protocolo grpc, o Claude Code usa apenas as variáveis de cabeçalhos estáticos, OTEL_EXPORTER_OTLP_HEADERS e suas variantes por sinal.

Configuração nas configurações

Adicione ao seu .claude/settings.json, substituindo o caminho pelo seu próprio script:

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

O valor pode ser o caminho para um arquivo executável, inclusive um caminho que contenha espaços, ou uma linha de comando do shell com argumentos. No Windows, o valor sempre é executado pelo shell, portanto coloque entre aspas, dentro do valor JSON, um caminho que contenha espaços.

Requisitos do script

O script deve gerar JSON válido com pares chave-valor de strings representando cabeçalhos HTTP:

#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Se o helper falhar ou imprimir uma saída que não atenda a esses requisitos, as exportações falham e o seu backend de telemetria não recebe nada da sessão até que o helper volte a funcionar. O Claude Code informa a falha em:

• 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

O script helper de cabeçalhos é executado na inicialização e periodicamente depois disso para oferecer suporte à atualização de tokens. Por padrão, o script é executado a cada 29 minutos. Personalize o intervalo com a variável de ambiente CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Suporte a organizações com várias equipes

Organizações com várias equipes ou departamentos podem adicionar atributos personalizados para distinguir entre diferentes grupos usando a variável de ambiente OTEL_RESOURCE_ATTRIBUTES:

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

Esses atributos personalizados são incluídos em todas as métricas e eventos, permitindo que você:

• 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

O Claude Code anexa esses valores como atributos em cada ponto de dados de métrica e registro de evento, além de enviá-los no bloco de recurso OTLP. Como a maioria dos backends de métricas expõe os atributos dos pontos de dados como rótulos consultáveis, você pode agrupar e filtrar métricas diretamente pelas suas chaves personalizadas. Exceto pelos atributos de repositório vcs.*, as chaves personalizadas nunca sobrescrevem os atributos padrão, como user.id ou session.id: quando uma chave colide, o Claude Code mantém o valor integrado.

Cada chave personalizada se torna um rótulo em todas as séries de métricas, portanto valores de alta cardinalidade aumentam o custo de armazenamento no seu backend de métricas. Para enviar atributos personalizados apenas no bloco de recurso e omiti-los dos rótulos dos pontos de dados, defina OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. Consulte Controle de cardinalidade de métricas.

Exemplos de configuração

Defina estas variáveis de ambiente antes de executar claude. Cada cenário abaixo mostra uma configuração completa, e cada variável é descrita em Variáveis de configuração comuns. Para confirmar que uma configuração entrou em vigor, verifique no seu backend a métrica claude_code.session.count após iniciar uma sessão; o Início rápido aborda a verificação apenas de logs e o que verificar quando nada chega.

Para depuração no console com um intervalo de exportação de 1 segundo:

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

Para OTLP sobre gRPC:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Para Prometheus, coletado de http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

Em um ambiente auto-hospedado, a sessão vincula a porta 9464 somente na capacidade padrão de um do runner. Em capacidades maiores, o runner reexpõe os contadores e medidores da sessão em seu próprio endpoint /metrics.

Para enviar métricas para vários exportadores:

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

Para enviar métricas e logs para endpoints ou backends diferentes:

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

Para exportar apenas métricas, sem eventos ou logs:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Para exportar apenas eventos e logs, sem métricas:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Telemetria de sessões em nuvem e Claude Tag

Sessões em nuvem, incluindo sessões do canal Claude Tag, são executadas em ambientes em nuvem em vez de nos dispositivos dos seus usuários, portanto um arquivo de configurações gerenciado ou perfil de shell nesses dispositivos não configura sua telemetria. Para sessões em ambientes hospedados pela Anthropic, esta seção aborda onde definir as variáveis de telemetria, como tornar seu coletor acessível a partir do ambiente e como distinguir sessões em nuvem e Claude Tag nos dados exportados.

Para exportar telemetria dessas sessões, defina CLAUDE_CODE_ENABLE_TELEMETRY e as variáveis OTEL_*, usando as mesmas chaves do exemplo de configuração do administrador, em um de dois locais:

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

Qualquer pessoa que use um ambiente pode ler suas variáveis, portanto não coloque uma credencial lá, como um token de coletor em OTEL_EXPORTER_OTLP_HEADERS. Uma credencial de API no ambiente também não ajuda, porque a exportação de telemetria do próprio Claude Code é uma das solicitações que nunca recebem a credencial. Se seu coletor exigir uma credencial, configure toda a exportação através de configurações gerenciadas pelo servidor, porque quando você define uma credencial lá, Claude Code remove variáveis de endpoint definidas fora das configurações gerenciadas.

Mantenha essas restrições em mente ao configurar telemetria para sessões em nuvem:

• 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 usam ambientes no nível da organização: sessões de canal são executadas em ambientes no nível da organização em vez dos pessoais dos membros, portanto faça as alterações na lista de permissões 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

Por padrão, métricas e eventos de uma sessão em nuvem carregam os atributos padrão, incluindo session.id, ccr.session.id e organization.id, para que você possa filtrar por sessão ou organização sem configuração extra. O valor ccr.session.id é o CLAUDE_CODE_REMOTE_SESSION_ID da sessão. Para convertê-lo na URL da transcrição da sessão, consulte Vincular saída de volta à sessão.

Para atribuir telemetria em mais detalhes, use estas opções:

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

Em sessões do canal Claude Tag, Claude funciona como a identidade compartilhada da sua organização em vez de qualquer membro, portanto não confie nos atributos user.* para identificar quem marcou Claude.

Métricas e eventos disponíveis

Atributos padrão

Todas as métricas e eventos compartilham estes atributos padrão:

Em sessões conectadas a um gateway de aplicativos Claude através de /login, a CLI marca as exportações com a identidade autenticada: user.id é o assunto do IdP, user.email é o email conectado, e user.groups carrega a associação de grupo do IdP como uma string separada por vírgulas. Cada exportação também carrega identity.source: gateway-oidc. A identidade do gateway é aplicada por último, então as chaves user.* e identity.* definidas através de OTEL_RESOURCE_ATTRIBUTES são ignoradas nessas sessões.

Para os atributos de identidade em sessões Claude Desktop e Cowork que se conectam através de um gateway, veja a referência de telemetria do gateway.

Os eventos incluem adicionalmente os seguintes atributos. Estes nunca são anexados a métricas porque causariam cardinalidade ilimitada:

• 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 de workspace do host selecionados no aplicativo desktop, como um array de strings
• workflow.run_id: identificador de execução, prefixado com wf_, na API e eventos de 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 ferramenta dessa execução. O identificador cobre os agentes que o script de workflow gera e quaisquer agentes que esses gerem por sua vez, como invocações de skill. 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 criados pelo usuário, incluindo cópias editadas de scripts integrados, são substituídos por custom a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido. Requer Claude Code v2.1.202 ou posterior

Atributos de repositório

Defina OTEL_METRICS_INCLUDE_REPOSITORY=true para marcar métricas e eventos com a identidade do repositório da sessão, para que um coletor compartilhado possa atribuir uso por repositório. Requer Claude Code v2.1.269 ou posterior.

Claude Code deriva esses atributos uma vez por sessão do remoto origin do repositório. Quando os remotos HTTPS e SSH de um repositório nomeiam o mesmo host e o mesmo caminho, como fazem no GitHub, GitLab e Bitbucket Cloud, ambos produzem valores idênticos:

Os valores são minúsculos, e credenciais, strings de consulta e fragmentos da URL remota nunca aparecem neles. Os atributos são omitidos quando a sessão não tem um remoto origin, quando o remoto não é em forma de URL, ou quando o único repositório envolvente é seu diretório home.

Para obter esses atributos de uma sessão na nuvem, defina as variáveis de telemetria, incluindo OTEL_METRICS_INCLUDE_REPOSITORY, em seu ambiente na nuvem. Também permita o domínio do seu coletor no acesso à rede do ambiente.

Uma chave vcs.* que você declara em OTEL_RESOURCE_ATTRIBUTES substitui o valor derivado para essa chave. Se você declarar vcs.repository.url.full, Claude Code nunca lê o remoto e relata apenas as chaves que você declara.

Se clones HTTPS e SSH de um repositório relatarem valores diferentes, como em uma instalação auto-hospedada cujo clone HTTPS URL carrega um prefixo de caminho que a URL SSH não tem, declare vcs.repository.url.full em OTEL_RESOURCE_ATTRIBUTES junto com todas as outras chaves vcs.* que você quer relatadas. Cada clone então relata a identidade que você declara.

Os atributos fluem apenas para seus próprios exportadores; a telemetria Anthropic descarta todas as chaves vcs.*.

Métricas

Claude Code exporta as seguintes métricas. A coluna Unit mostra a string de unidade OpenTelemetry anexada a cada métrica; métricas de contagem não carregam nenhuma.

Quando prometheus é o único exportador listado em OTEL_METRICS_EXPORTER, Claude Code omite as unidades USD, tokens, e s das métricas exportadas para que o scrape permaneça em formato de texto Prometheus válido. Os nomes das métricas não mudam, e configurações que combinam exportadores, como otlp,prometheus, mantêm as unidades. Antes da v2.1.216, o scrape Prometheus incluía linhas # UNIT apenas do OpenMetrics que alguns scrapers rejeitavam.

Detalhes das métricas

Cada métrica inclui os atributos padrão listados acima. Métricas com atributos adicionais específicos do contexto são anotadas abaixo.

Contador de sessão

Incrementado no início de cada sessão.

Atributos:

• 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 neste valor para separar inicializações de processo de UI de sessões conversacionais em seus dashboards.

Contador de linhas de código

Incrementado quando código é adicionado ou removido.

Atributos:

• 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

Incrementado quando Claude Code cria uma pull request ou merge request através de um comando shell ou uma ferramenta MCP.

Atributos:

• Todos os atributos padrão

Contador de commit

Incrementado ao criar commits git via Claude Code.

Atributos:

• Todos os atributos padrão

Contador de custo

Incrementado após cada requisição de API.

Os atributos agent.name, skill.name, plugin.name, mcp_server.name, e mcp_tool.name cada um redige alguns nomes para um placeholder "custom" ou "third-party" por padrão. Se você definir OTEL_LOG_TOOL_DETAILS=1, eles carregam os nomes reais em vez disso. Antes da v2.1.273, os contadores de custo e token e os eventos api_request, api_error, e api_refusal carregavam os valores redigidos mesmo com OTEL_LOG_TOOL_DETAILS=1 definido.

Atributos:

• 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 ou um comando /, ou herdada por um subagente gerado. Nomes de skills integrados, agrupados, definidos pelo usuário e do plugin 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 token

Incrementado após cada requisição de API.

Atributos:

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

Incrementado quando o usuário aceita ou rejeita o uso da ferramenta Edit, Write, ou NotebookEdit.

Atributos:

• 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

Rastreia o tempo real gasto usando ativamente Claude Code, excluindo tempo ocioso. Esta métrica é incrementada durante interações do usuário, como digitação e leitura de respostas, e durante processamento CLI, como execução de ferramenta e geração de resposta de IA.

Atributos:

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

Eventos

Claude Code exporta os seguintes eventos via logs/eventos OpenTelemetry (quando OTEL_LOGS_EXPORTER está configurado):

Atributos de correlação de eventos

Quando um usuário envia um prompt, Claude Code pode fazer múltiplas chamadas de API e executar várias ferramentas. O atributo prompt.id permite que você vincule todos esses eventos de volta ao único prompt que os acionou.

Para rastrear toda atividade acionada por um único prompt, filtre seus eventos por um valor específico de prompt.id. Isto retorna o evento user_prompt, quaisquer eventos api_request, e quaisquer eventos tool_result que ocorreram ao processar esse prompt.

event.sequence começa em 0 cada vez que um processo Claude Code inicia e conta para a vida desse processo. Continua contando através de /clear, que atribui um novo session.id. Se você retomar uma sessão sem fazer fork, a sessão mantém seu session.id mas toma seus valores de event.sequence do processo que a retomou, então dentro de uma sessão um evento posterior pode carregar um valor menor que um anterior, ou repetir um. Para ordenar os eventos de uma sessão, ordene por event.timestamp e use event.sequence para ordenar eventos que compartilham um timestamp.

Para reconstrução em nível de mensagem, cada classe de evento carrega uma chave que corresponde a um campo na transcrição da sessão. O formato de entrada da transcrição é interno ao Claude Code e muda entre versões, então um pipeline que se une nestes campos pode quebrar em qualquer release; trate as uniões como específicas da versão em vez de um contrato estável:

• 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

Registrado quando um usuário envia um prompt.

Nome do Evento: claude_code.user_prompt

Atributos:

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

Registrado após cada requisição de API que retorna conteúdo de texto do modelo. Apenas os blocos de texto da resposta são incluídos; blocos de pensamento e blocos de uso de ferramenta são excluídos. Requer Claude Code v2.1.193 ou posterior.

Nome do Evento: claude_code.assistant_response

Atributos:

• 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). Redigido 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 redigidas enquanto o logging 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

Registrado quando uma ferramenta completa a execução. Não emitido se a chamada de ferramenta foi rejeitada; veja o evento de decisão de ferramenta para rejeições.

Nome do Evento: claude_code.tool_result

Atributos:

• 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 executar. 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 de 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 desligada, a mesma exceção de autoria de 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 de 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 a carga útil completa é limitada a ~4 K caracteres. Aplica-se a todas as ferramentas incluindo ferramentas MCP.

Evento de requisição de API

Registrado para cada requisição de API para Claude.

Nome do Evento: claude_code.api_request

Atributos:

• 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
• 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 cabeçalho 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

Registrado quando uma requisição de API para Claude falha.

Nome do Evento: claude_code.api_error

Atributos:

• 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 cabeçalho 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 de 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

Registrado quando uma requisição de API retorna stop_reason: "refusal". Recusas chegam em um stream de resposta bem-sucedido em vez de como um erro HTTP, então o evento api_error não dispara para elas. Este evento permite que você rastreie a frequência de recusa e agrupe recusas pelos mesmos atributos que api_request e api_error.

Nome do Evento: claude_code.api_refusal

Atributos:

• 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 hop true quanto um evento final false posterior quando o modelo de fallback também recusa.
• has_category: true quando a resposta de API carregava um stop_details.category de "cyber", "bio", "frontier_llm", ou "reasoning_extraction". false quando a resposta não carregava categoria ou um valor fora desse conjunto. Ausente quando server_fallback_hop é true, porque blocos hop não carregam stop_details.
• has_explanation: true quando a resposta de API carregava um stop_details.explanation, caso contrário false. Ausente quando server_fallback_hop é true.
• category: O valor stop_details.category da resposta de 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

Registrado para cada tentativa de requisição de API quando OTEL_LOG_RAW_API_BODIES está definido. Um evento é emitido por tentativa, então retentativas com parâmetros ajustados cada uma produzem seu próprio evento.

Nome do Evento: claude_code.api_request_body

Atributos:

• 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 é redigido. 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

Registrado para cada resposta de API bem-sucedida quando OTEL_LOG_RAW_API_BODIES está definido.

Em modo arquivo (OTEL_LOG_RAW_API_BODIES=file:<dir>), Claude Code também anexa uma linha JSON a <dir>/index.jsonl para cada resposta bem-sucedida, com os campos timestamp, session_id, query_source, model, request_id, message_id, message_uuid, request_file, e response_file. Leia-a para encontrar os arquivos de requisição e resposta atrás de uma mensagem de transcrição dada sem consultar seu backend de telemetria. O arquivo de índice requer Claude Code v2.1.274 ou posterior.

Nome do Evento: claude_code.api_response_body

Atributos:

• 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 é redigido. 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

Registrado quando uma decisão de permissão de ferramenta é feita (aceitar/rejeitar).

Nome do Evento: claude_code.tool_decision

Atributos:

• 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 criados pela 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 é uma criança aninhada; 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 permitir ou negar 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 permitir 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 negar 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 negar 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á desligado, 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 ligada; 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 de 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 modo de permissão alterado

Registrado quando o modo de permissão muda, por exemplo de ciclagem Shift+Tab, saída do modo de plano, ou uma verificação de gate de modo automático.

Nome do Evento: claude_code.permission_mode_changed

Atributos:

• 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

Registrado quando /login ou /logout é concluído.

Nome do Evento: claude_code.auth

Atributos:

• 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

Registrado quando um servidor MCP se conecta, desconecta, ou falha em se conectar.

Nome do Evento: claude_code.mcp_server_connection

Atributos:

• 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 Anthropic oficiais são sempre identificados por nome. Os atributos plugin_id_hash e plugin.name fluem para seu próprio backend de monitoramento e não são enviados para Anthropic
• server_name (quando OTEL_LOG_TOOL_DETAILS=1): Nome do servidor configurado
• error (quando OTEL_LOG_TOOL_DETAILS=1): Mensagem de erro completa quando a conexão falhou

Evento de erro interno

Registrado quando Claude Code captura um erro interno inesperado. Apenas o nome da classe de erro e um código estilo errno são registrados. A mensagem de erro e stack trace nunca são incluídos. Este evento não é emitido ao executar contra Amazon Bedrock, Agent Platform do Google Cloud, ou Microsoft Foundry, ou quando DISABLE_ERROR_REPORTING está definido.

Nome do Evento: claude_code.internal_error

Atributos:

• 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

Registrado quando um plugin termina de instalar, tanto do comando CLI claude plugin install quanto da UI interativa /plugin.

Nome do Evento: claude_code.plugin_installed

Atributos:

• 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 Anthropic oficial, "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

Registrado uma vez por plugin habilitado no início da sessão. Use este evento para inventariar quais plugins estão ativos em sua frota, como complemento a plugin_installed que registra a ação de instalação em si.

Nome do Evento: claude_code.plugin_loaded

Atributos:

• 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. Redigido 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 é redigido 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 que você conte 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

Registrado quando uma skill é invocada, seja Claude a chama através da ferramenta Skill ou você a executa como um comando /.

Nome do Evento: claude_code.skill_activated

Atributos:

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

Registrado quando Claude Code resolve uma menção @ em um prompt. Nem toda menção emite um evento: caminhos de saída antecipada como negações de permissão, arquivos superdimensionados, anexos de referência PDF e falhas de listagem de diretório retornam sem registrar.

Nome do Evento: claude_code.at_mention

Atributos:

• 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

Registrado uma vez quando uma requisição de API falha após mais de uma tentativa. Emitido junto com o evento api_error final.

Nome do Evento: claude_code.api_retries_exhausted

Atributos:

• 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 relógio de parede em todas as tentativas
• speed: "fast" ou "normal"

Evento de hook registrado

Registrado uma vez por hook configurado no início da sessão. Use este evento para inventariar quais hooks estão ativos em sua frota, como complemento aos eventos por execução hook_execution_start e hook_execution_complete.

Nome do Evento: claude_code.hook_registered

Atributos:

• 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 que você conte 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

Registrado quando um ou mais hooks começam a executar para um evento de hook.

Nome do Evento: claude_code.hook_execution_start

Atributos:

• 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

Registrado quando todos os hooks para um evento de hook terminaram.

Nome do Evento: claude_code.hook_execution_complete

Atributos:

• 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 relógio de parede 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

Registrado quando um hook de plugin do marketplace oficial emite métricas por invocação. Apenas plugins instalados de um marketplace Anthropic oficial podem emitir estes. Plugins de marketplace de terceiros e hooks configurados pelo usuário não emitem para este evento. Use este evento para monitorar comportamento de plugin como taxas de descoberta, custos e durações de sua própria pilha de observabilidade.

Nome do Evento: claude_code.hook_plugin_metrics

Atributos:

• 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

Registrado quando a compactação de conversa é concluída.

Nome do Evento: claude_code.compaction

Atributos:

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

Evento de subagente concluído

Registrado quando um subagente termina e retorna seu resultado para a conversa que o iniciou. Use-o para agregar uso de ferramenta e tempo de execução por tipo de subagente; para agregações de token ou custo, use o contador de token e contador de custo filtrados para query_source "subagent", já que o total_tokens deste evento cobre apenas a requisição final. A categoria "subagent" também conta requisições de hooks baseados em agente, que não emitem evento de subagente.

Nome do Evento: claude_code.subagent_completed

Atributos:

• 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 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 de 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 plugins são substituídos por "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido

Evento de pesquisa de feedback

Registrado quando uma pesquisa de qualidade de sessão é mostrada ou respondida. Veja Pesquisas de qualidade de sessão para o que as pesquisas coletam e como controlá-las.

Nome do Evento: claude_code.feedback_survey

Atributos:

• 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 de 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 booleano, não uma string. Presente em eventos de pesquisa session. Filtre neste atributo para confirmar que a substituição está aplicada em uma frota

Evento de varredura de retenção

Registrado uma vez por execução da varredura de limpeza de retenção, que deleta transcrições de sessão e outros dados de aplicação mais antigos que a configuração cleanupPeriodDays. Claude Code executa a varredura em background no máximo uma vez por sessão, e uma execução que não deleta nada ainda emite o evento. Se Claude Code executou a varredura em qualquer sessão na mesma máquina nos últimos 24 horas, ele atrasa a varredura desta sessão por pelo menos 10 minutos, então uma sessão que sai mais cedo não emite nada. Quando você executa claude -p com --bare, Claude Code não executa a varredura e não emite nada.

Como todo evento OTel nesta página, ele vai apenas para o backend de telemetria que você configura. Requer Claude Code v2.1.227 ou posterior.

Quando Claude Code não pode determinar com segurança o período de retenção, ele pausa a varredura e emite o evento com result definido para "skipped" e um skip_reason. Quando configurações gerenciadas definem cleanupPeriodDays, o valor gerenciado fixa o período de retenção e a varredura executa mesmo quando um arquivo de configurações em um escopo de prioridade mais baixa está quebrado ou inválido. Quando managed-settings.json em si não pode ser lido, Claude Code ainda pausa a varredura a menos que o nível gerenciado forneça cleanupPeriodDays de outro lugar, como configurações gerenciadas pelo servidor ou um drop-in managed-settings.d/ ao lado do arquivo quebrado. Os atributos do contador de exclusão estão presentes apenas quando result é "complete".

Nome do Evento: claude_code.retention_sweep

Atributos:

• 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 executou, "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 de 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 Claude Desktop e Cowork. Estas 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 session-files deletou: transcrições mais arquivos complementares por sessão como sidecars, gravações e resultados de ferramenta
• 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 alguns passes de limpeza não contribuem para o contador, então trate o valor como um piso em vez de uma contagem exata de arquivo
• files_retained_fresh: Arquivos inspecionados e deixados no 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

Registrado com as configurações gerenciadas que uma sessão resolveu: uma vez no início da sessão, novamente quando as configurações gerenciadas ou o auxiliar de política mudam de estado durante a sessão, e quando Claude Code recusa iniciar ou termina a sessão por uma das razões que o atributo error.type lista. Use este evento para encontrar máquinas executando em uma fonte gerenciada inesperada, máquinas cujo auxiliar de política está falhando, e a razão pela qual uma máquina recusou iniciar. Requer Claude Code v2.1.274 ou posterior.

Por padrão, o evento carrega as fontes gerenciadas e o estado do auxiliar de política mas não as configurações em si. Para adicionar o atributo managed_settings.settings redigido e o digest managed_settings.resolved_sha256, defina OTEL_LOG_MANAGED_SETTINGS=1:

• Defina-o no bloco env de configurações gerenciadas, configurações de 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ê-las.
• 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 redigida da organização a um evento que sua organização já recebe.

Em uma sessão interativa em uma pasta que você não confiou, Claude Code não exporta o evento de recusa.

Nome do Evento: claude_code.managed_settings_resolved

Atributos:

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

• error.type: por que Claude Code parou a sessão. Presente apenas em eventos refused:

  • "helper_failed": uma execução de auxiliar de política falhou
  • "policy_invalid": as configurações gerenciadas contêm um erro que para Claude Code de iniciar, ou uma fonte de admin falhou em carregar, então Claude Code não pode verificar a imposição de login da organização
  • "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 allowedProviders gerenciada não permite. Requer Claude Code v2.1.285 ou posterior
  • "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 outra razão

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

• 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 redigidos. 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, cada valor env, cada URL e cada 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 é exportada como uma lista de suas listas de caminho 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 seu nome de ferramenta com o conteúdo redigido, 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 negar 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 booleano, não uma string

Interpretar dados de métricas e eventos

As métricas e eventos exportados suportam uma gama de análises:

Monitoramento de uso

Monitoramento de custo

A métrica claude_code.cost.usage ajuda com:

• 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

Claude Code conta cada resposta de streaming em relação às métricas de custo e token exatamente uma vez, incluindo quando um gateway ou proxy atrás de ANTHROPIC_BASE_URL transmite uso progressivamente em vários frames. Antes da v2.1.214, streams que carregavam uso em mais de um frame inflacionavam claude_code.cost.usage e claude_code.token.usage por aproximadamente uma solicitação completa extra por frame extra.

Alertas e segmentação

Alertas comuns a considerar:

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

Todas as métricas podem ser segmentadas pelos atributos padrão. O atributo model está disponível em claude_code.token.usage, claude_code.cost.usage e a partir da v2.1.172, claude_code.lines_of_code.count.

Divisões por modelo de commits podem ser apenas aproximadas unindo contra as métricas de token ou custo em session.id, já que uma sessão pode abranger vários modelos. Filtre o lado do token ou custo para linhas onde query_source é "main" para que solicitações auxiliares e de subagente não atribuam os commits da sessão a um modelo que não os fez.

Detectar esgotamento de tentativas

Claude Code retenta solicitações de API falhadas internamente e emite um único evento claude_code.api_error apenas depois de desistir, então o evento em si é o sinal terminal para essa solicitação. Tentativas de repetição intermediárias não são registradas como eventos separados.

O atributo attempt no evento registra o número total de tentativas. CLAUDE_CODE_MAX_RETRIES tem como padrão 10 e é limitado a 15. A partir da v2.1.199, você pode definir CLAUDE_CODE_RETRY_WATCHDOG para aumentar o padrão e remover o limite.

Quando a solicitação esgota todas as tentativas em um erro transitório, attempt é igual a um a mais do que esse limite efetivo: 11 por padrão, e nunca mais de 16 a menos que o watchdog esteja definido. Um valor menor indica um erro não retentável, como uma resposta 400, ou uma causa com seu próprio orçamento de tentativas menor. Por exemplo, Claude Code retenta uma falha ao carregar credenciais da AWS ou Google Cloud no máximo duas vezes.

Para distinguir uma sessão que se recuperou de uma que travou, agrupe eventos por session.id e verifique se um evento api_request posterior existe após o erro.

Análise de eventos

Os dados de eventos descrevem cada interação do Claude Code em detalhes:

Padrões de uso de ferramentas: analise eventos de resultado de ferramentas para identificar:

• 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

Monitoramento de desempenho: rastreie durações de solicitações de API e tempos de execução de ferramentas para identificar gargalos de desempenho.

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

Claude Code exporta as contagens de tokens de entrada conforme aparecem no bloco de uso da resposta da API, portanto esses valores excluem tokens lidos ou gravados no cache de prompt:

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

Claude Code não define atributos gen_ai.usage.*. As convenções semânticas GenAI do OpenTelemetry dizem que gen_ai.usage.input_tokens deve incluir tokens lidos e gravados no cache. Para calcular esse total:

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

As convenções também definem atributos separados para leituras e gravações de cache:

• 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

Os eventos OpenTelemetry são a fonte de dados de auditoria para atividade do Claude Code. Cada evento carrega atributos de identidade que vinculam chamadas de ferramenta, atividade MCP e decisões de permissão de volta ao usuário que as acionou. O exportador de logs OTLP pode entregar esses eventos a qualquer plataforma Security Information and Event Management (SIEM) com um receptor OTLP, ou a um OpenTelemetry Collector que encaminha para seu SIEM.

Atribuir ações a usuários

Os atributos padrão em cada evento incluem a identidade do usuário autenticado: user.email, user.account_uuid, user.account_id e organization.id quando conectado com uma conta Claude ou, em uma sessão na nuvem, quando as credenciais da própria sessão as carregam, mais user.id e o session.id por sessão. user.id é um identificador com escopo de instalação, exceto em sessões do gateway de aplicativos Claude através de /login, onde é o assunto do IdP do token emitido pelo gateway.

Em uma sessão que um desenvolvedor inicia, chamadas de ferramenta MCP, comandos Bash e edições de arquivo são, portanto, atribuídas a esse desenvolvedor. Claude Code não atua sob uma conta de serviço separada; a identidade registrada em cada evento é a própria conta Claude do desenvolvedor, ou a identidade do IdP do desenvolvedor em uma sessão do gateway de aplicativos Claude. Em sessões de canal Claude Tag, Claude funciona como a identidade compartilhada da sua organização.

Quando Claude Code autentica com uma chave de API direta, ou contra Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry, não há conta Claude na sessão e apenas user.id e session.id são preenchidos. Nessas implantações, anexe identidade do usuário você mesmo com OTEL_RESOURCE_ATTRIBUTES, definido por usuário através do arquivo de configurações gerenciadas ou um wrapper de inicialização. Sessões do gateway de aplicativos Claude não precisam de nada disso: veja Atributos padrão para a identidade que suas exportações carregam.

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

Auditoria de atividade MCP

Para capturar atividade do servidor MCP com detalhe completo de chamada, ative o exportador de logs e defina OTEL_LOG_TOOL_DETAILS=1. Cada operação MCP então produz eventos estruturados que carregam o nome do servidor, nome da ferramenta e argumentos de chamada junto com os atributos de identidade padrão:

Sem OTEL_LOG_TOOL_DETAILS, esses eventos descartam o detalhe de identificação:

• 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

Ao construir regras de detecção, procure o sinal que você deseja monitorar e consulte seu backend para o evento correspondente e atributos:

Claude Code emite apenas o fluxo de eventos bruto. Detecção de anomalias, linha de base, correlação entre sessões e alertas são responsabilidade do seu SIEM ou backend de observabilidade.

Enviar eventos para um SIEM

Aponte OTEL_EXPORTER_OTLP_LOGS_ENDPOINT para o receptor OTLP do seu SIEM, ou para um OpenTelemetry Collector que encaminha para a API de ingestão nativa do seu SIEM. O seguinte exemplo de configurações gerenciadas exporta apenas eventos, com detalhe completo de ferramenta ativado para auditoria MCP e Bash:

{
  "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"
  }
}

Para confirmar que os eventos chegam, envie um prompt em uma sessão executada sob essa configuração e verifique seu SIEM para o evento claude_code.user_prompt. Se nada chegar, inicie Claude Code com claude --debug-file <path> e verifique esse log para erros de exportação [3P telemetry].

Considerações de backend

Sua escolha de backends de métricas, logs e rastreamentos determina os tipos de análises que você pode realizar:

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

Escolha um backend que suporte armazenamento de rastreamento distribuído e correlação de span:

• 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

Para organizações que exigem métricas de Usuário Ativo Diário/Semanal/Mensal (DAU/WAU/MAU), considere backends que suportam consultas eficientes de valor único.

Informações de serviço

Todas as métricas e eventos são exportados com os seguintes atributos de recurso:

• 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

Se seus pipelines de coletor ou painéis filtrarem em service.name = claude-code, adicione claude-code-desktop ao filtro para também capturar telemetria de sessões da aba Code.

Recursos de medição de ROI

Para um guia abrangente sobre como medir o retorno sobre investimento para Claude Code, incluindo configuração de telemetria, análise de custo, métricas de produtividade e relatórios automatizados, consulte o Guia de Medição de ROI do Claude Code. Este repositório fornece configurações Docker Compose prontas para uso, configurações Prometheus e OpenTelemetry, e modelos para gerar relatórios de produtividade integrados com ferramentas como Linear.

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

Para orientação detalhada de monitoramento de uso do Claude Code para Amazon Bedrock, consulte Implementação de Monitoramento do Claude Code (Amazon Bedrock).