Monitoramento

Saiba como ativar e configurar OpenTelemetry para Claude Code.

Rastreie o uso, custos e atividade de ferramentas do Claude Code em toda a sua organização exportando dados de telemetria através do OpenTelemetry (OTel). Claude Code exporta métricas como dados de série temporal via protocolo de métricas padrão, eventos via protocolo de logs/eventos e, opcionalmente, rastreamentos distribuídos via protocolo de rastreamentos.

Início rápido

Configure OpenTelemetry usando variáveis de ambiente:

# 1. Ativar telemetria
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Escolher exportadores (ambos são opcionais - configure apenas o que você precisa)
export OTEL_METRICS_EXPORTER=otlp       # Opções: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Opções: otlp, console, none

# 3. Configurar endpoint OTLP (para exportador OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Definir autenticação (se necessário)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Para depuração: reduzir intervalos de exportação e redefini-los para uso em produção
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 segundos (padrão: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 segundos (padrão: 5000ms)

# 6. Executar Claude Code
claude

Para verificar uma configuração que exporta métricas, verifique seu backend para a métrica claude_code.session.count, que Claude Code emite quando uma sessão é iniciada. Para verificar uma configuração apenas de logs, envie um prompt e verifique o evento claude_code.user_prompt.

Se nada chegar, execute claude --debug e verifique o log de depuração. Claude Code relata falhas dos exportadores que você configura como erros [3P telemetry], onde 3P significa third-party. As linhas prefixadas com [Anthropic telemetry] descrevem a telemetria operacional separada da Anthropic e não indicam um problema com sua configuração.

Para opções de configuração completas, consulte a especificação OpenTelemetry.

Configuração do administrador

Os administradores podem configurar as definições de OpenTelemetry para todos os usuários através do arquivo de configurações gerenciadas. Consulte a precedência de configurações para obter mais informações sobre como as configurações são aplicadas.

Exemplo de configuração de configurações gerenciadas:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Claude Code não passa variáveis de ambiente OTEL_* para os subprocessos que ele gera, incluindo a ferramenta Bash, hooks, servidores MCP e servidores de linguagem. Um aplicativo instrumentado com OpenTelemetry que você executa através da ferramenta Bash não herda o endpoint do exportador ou cabeçalhos do Claude Code, então defina essas variáveis diretamente no comando se esse aplicativo precisar exportar sua própria telemetria.

Como as configurações gerenciadas bloqueiam o destino OTLP

Quando você define uma variável OTEL_EXPORTER_OTLP_* nas configurações gerenciadas, Claude Code remove variáveis conflitantes definidas pelo desenvolvedor na inicialização e registra um aviso que você pode ver com claude --debug. O que ele remove depende de qual variável você define:

• Endpoints: quando você define OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code remove todos os endpoints por sinal definidos pelo desenvolvedor. Os desenvolvedores não podem apontar um sinal para um coletor diferente, portanto você não precisa também definir as variáveis de endpoint por sinal nas configurações gerenciadas.

• Protocolos: quando você define OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code remove todos os protocolos por sinal definidos pelo desenvolvedor.

• Credenciais: quando você define OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY ou OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, Claude Code remove as versões por sinal definidas pelo desenvolvedor dessa variável, além de todas as variáveis de endpoint definidas pelo desenvolvedor, genéricas ou por sinal, já que essas credenciais de outra forma alcançariam um coletor que as configurações gerenciadas não escolheram.

• Seletores de exportador: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER e o OTEL_TRACES_EXPORTER beta seguem a precedência normal por chave. Uma configuração do desenvolvedor ainda pode desabilitar um sinal ou alterá-lo para o exportador de console, portanto defina os seletores nas configurações gerenciadas também se você precisar que eles sejam bloqueados. Através de fontes de administrador, OTEL_LOGS_EXPORTER segue a unidade de telemetria enquanto os outros dois seletores se mesclam por chave. Requer Claude Code v2.1.223 ou posterior.

• Endpoints de rastreamento beta: com rastreamento beta detalhado ativo, Claude Code exporta logs e rastreamentos para BETA_TRACING_ENDPOINT em vez de através dos exportadores de logs e rastreamentos. Claude Code portanto remove um BETA_TRACING_ENDPOINT definido pelo desenvolvedor sempre que qualquer uma dessas configurações gerenciadas decide o destino de qualquer sinal:

  • Um endpoint genérico ou de logs/rastreamentos ou credencial
  • Um otelHeadersHelper
  • Um seletor de exportador de logs ou rastreamentos definido como none, console ou vazio, valores que mantêm o sinal fora de um coletor
  • CLAUDE_CODE_ENABLE_TELEMETRY desativado

  Um endpoint ou credencial apenas de métricas não o remove. Antes da v2.1.251, um BETA_TRACING_ENDPOINT definido pelo desenvolvedor redirecionava os logs e rastreamentos que o rastreamento beta detalhado exporta mesmo quando as configurações gerenciadas fixavam o coletor.

Claude Code não remove variáveis por sinal que você define nas configurações gerenciadas em si, portanto você pode rotear um sinal para um coletor diferente definindo sua variável lá, como o exemplo SIEM faz. Se você definir uma credencial por sinal lá, Claude Code remove o endpoint definido pelo desenvolvedor para esse sinal.

Este comportamento de remoção muda para onde a telemetria é entregue, não o que Claude Code coleta.

Antes da v2.1.217, cada variável seguia a precedência de configurações por chave independentemente, portanto um endpoint específico de sinal definido nas configurações do usuário ou no shell redirecionava esse sinal para longe do coletor gerenciado.

Quando o aplicativo de desktop ou um executor de ambiente auto-hospedado inicia Claude Code e nomeia um endpoint OTLP no ambiente que fornece, Claude Code fixa o destino da mesma forma: as variáveis de telemetria do iniciador removem variáveis definidas pelo desenvolvedor exatamente como as configurações gerenciadas fazem. Claude Code não remove variáveis que o próprio iniciador definiu. Requer Claude Code v2.1.251 ou posterior.

Detalhes de configuração

Variáveis de configuração comuns

Essas variáveis configuram exportadores, endpoints e comportamento de exportação para todas as implantações. Se você definir uma variável de endpoint ou protocolo por sinal, como OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, Claude Code a usa em vez da variável genérica para esse sinal. Se você definir uma variável de cabeçalhos por sinal, como OTEL_EXPORTER_OTLP_METRICS_HEADERS, Claude Code a mescla com a genérica OTEL_EXPORTER_OTLP_HEADERS para esse sinal. Em máquinas com configurações gerenciadas, veja Como as configurações gerenciadas bloqueiam o destino OTLP para saber o que Claude Code remove.

Para os protocolos http/protobuf e http/json, Claude Code envia cada solicitação de exportação com um cabeçalho Content-Length. Antes da v2.1.212, versões do Claude Code a partir da v2.1.191 enviavam essas solicitações com codificação de transferência em chunks; Azure Monitor e outros endpoints que exigem um comprimento declarado as rejeitavam com erros 411 Length Required ou 400.

Autenticação mTLS

Como você configura certificados de cliente para o exportador OTLP depende do protocolo OTLP em uso para esse sinal, definido via OTEL_EXPORTER_OTLP_PROTOCOL ou a substituição por sinal. A mesma configuração se aplica a métricas, logs e rastreamentos.

Para grpc, o SDK OpenTelemetry lê as variáveis OTLP padrão diretamente, então as configurações existentes que definem as variáveis de métricas por sinal continuam funcionando. Em máquinas com configurações gerenciadas, Claude Code pode remover credenciais e endpoints por sinal definidos pelo desenvolvedor na inicialização.

Controle de cardinalidade de métricas

As seguintes variáveis de ambiente controlam quais atributos são incluídos nas métricas para gerenciar a cardinalidade:

Cardinalidade mais baixa geralmente significa melhor desempenho e custos de armazenamento mais baixos, mas dados menos granulares para análise.

Rastreamentos (beta)

O rastreamento distribuído exporta spans que vinculam cada prompt do usuário às solicitações de API e execuções de ferramentas que ele dispara, para que você possa visualizar uma solicitação completa como um único rastreamento no seu backend de rastreamento.

O rastreamento está desativado por padrão. Para ativá-lo, defina tanto CLAUDE_CODE_ENABLE_TELEMETRY=1 quanto CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, depois defina OTEL_TRACES_EXPORTER para escolher para onde os spans são enviados. Os rastreamentos reutilizam a configuração OTLP comum para endpoint, protocolo, cabeçalhos e mTLS. Em máquinas com configurações gerenciadas, Claude Code pode remover credenciais e endpoints por sinal definidos pelo desenvolvedor na inicialização.

Os spans reduzem o texto do prompt do usuário, detalhes de entrada de ferramenta e conteúdo de ferramenta por padrão. Defina OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 e OTEL_LOG_TOOL_CONTENT=1 para incluí-los.

Quando o rastreamento está ativo, subprocessos Bash e PowerShell herdam automaticamente uma variável de ambiente TRACEPARENT contendo o contexto de rastreamento W3C do span de execução de ferramenta ativo. Isso permite que qualquer subprocesso que leia TRACEPARENT coloque seus próprios spans sob o mesmo rastreamento, permitindo rastreamento distribuído de ponta a ponta através de scripts e comandos que Claude executa.

Quando o rastreamento está ativo e Claude Code está conectado diretamente à API Anthropic, cada solicitação de modelo carrega um cabeçalho W3C traceparent definido para o contexto do span claude_code.llm_request, e o cabeçalho traceresponse da API é registrado como um link de span. Juntos, esses conectam os spans do lado do cliente do Claude Code ao rastreamento do lado do servidor através de qualquer intermediário compatível. As solicitações HTTP MCP de saída carregam traceparent da mesma forma. O cabeçalho não é enviado para provedores terceirizados.

Por padrão, o cabeçalho traceparent em solicitações de modelo e HTTP MCP é enviado apenas quando ANTHROPIC_BASE_URL não está definido ou aponta para a API Anthropic, já que alguns proxies rejeitam cabeçalhos não reconhecidos. A variável TRACEPARENT do subprocesso é controlada pelo mesmo switch para consistência. Se você executar Claude Code através de um proxy ANTHROPIC_BASE_URL customizado e quiser que o contexto de rastreamento seja propagado, defina CLAUDE_CODE_PROPAGATE_TRACEPARENT=1.

No Agent SDK e sessões não-interativas iniciadas com -p, Claude Code também lê TRACEPARENT e TRACESTATE de seu próprio ambiente ao iniciar cada span de interação. Isso permite que um processo de incorporação passe seu contexto de rastreamento W3C ativo para o subprocesso para que os spans do Claude Code apareçam como filhos do rastreamento distribuído do chamador. Sessões interativas ignoram TRACEPARENT de entrada para evitar herdar acidentalmente valores ambientes de CI ou ambientes de contêiner.

O contexto de rastreamento de entrada também se aplica a eventos. No Agent SDK e sessões -p com TRACEPARENT definido, cada registro de log de evento OTLP carrega valores trace_id e span_id que o unem ao rastreamento da sua aplicação, mesmo quando o exportador de rastreamentos não está configurado, para que seu backend de logging possa correlacionar eventos com o resto do rastreamento.

Um registro emitido enquanto uma interação está ativa carrega os IDs do span de interação, mesmo quando Claude Code o emite fora do contexto assíncrono do span, como em um callback de prompt de permissão ou para um registro armazenado em buffer durante a inicialização e exportado posteriormente. Um registro emitido sem nenhum span de interação ativo carrega os IDs TRACEPARENT de entrada diretamente. Antes da v2.1.214, registros emitidos fora do contexto assíncrono do span carregavam os IDs TRACEPARENT de entrada em vez dos IDs do span. Antes da v2.1.212, registros de eventos emitidos fora de um span ativo não carregavam trace_id ou span_id.

Hierarquia de span

Cada prompt do usuário inicia um span raiz claude_code.interaction. Chamadas de API, chamadas de ferramenta e execuções de hook são registradas como seus filhos. Os spans de ferramenta têm dois spans filhos próprios: um para o tempo gasto esperando uma decisão de permissão e outro para a execução em si. Quando a ferramenta Agent ou a ferramenta Task legada gera um subagente, os spans de API e ferramenta do subagente se aninham sob o span claude_code.tool do pai.

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

No Agent SDK e sessões claude -p, claude_code.interaction em si se torna um filho do span do chamador quando TRACEPARENT está definido no ambiente.

Quando um hook PreToolUse adia uma chamada de ferramenta, Claude Code salva o contexto de rastreamento do turno que o adiou. Quando você retoma a sessão e a ferramenta é executada novamente, os spans da ferramenta se unem ao rastreamento daquele turno anterior como filhos do span claude_code.interaction do turno.

Atributos de span

Cada span carrega os atributos padrão mais um atributo span.type correspondendo ao seu nome. As tabelas abaixo listam os atributos adicionais definidos em cada span. Os spans llm_request, tool.execution e hook definem status OpenTelemetry ERROR quando registram uma falha; os outros spans sempre terminam com status UNSET.

claude_code.interaction

claude_code.llm_request

Cada tentativa de repetição também é registrada como um evento de span gen_ai.request.attempt com atributos attempt e client_request_id.

claude_code.tool

Quando OTEL_LOG_TOOL_CONTENT=1, este span também registra um evento de span tool.output cujos atributos contêm os corpos de entrada e saída da ferramenta, truncados no limite de conteúdo (60 KB por padrão) por atributo.

claude_code.tool.blocked_on_user

claude_code.tool.execution

claude_code.hook

Este span aparece apenas quando rastreamento beta detalhado está ativo, o que requer ENABLE_BETA_TRACING_DETAILED=1 e BETA_TRACING_ENDPOINT, um par que também muda para onde seus logs e rastreamentos vão. Defina o par em seu shell, configurações de usuário ou configurações gerenciadas; ambas as variáveis são ignoradas em configurações de projeto e local. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA sozinho não o produz.

Em sessões CLI interativas, rastreamento beta detalhado também requer que sua organização esteja na lista de permissões para o recurso. Sessões Agent SDK e não-interativas -p não requerem lista de permissões.

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 apenas aos protocolos http/protobuf e http/json. Com o protocolo grpc, Claude Code usa apenas as variáveis de cabeçalhos estáticos, OTEL_EXPORTER_OTLP_HEADERS e suas variantes por sinal.

Configuração de 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, incluindo um caminho que contém espaços, ou uma linha de comando shell com argumentos. No Windows, o valor sempre é executado através do shell, então coloque entre aspas um caminho que contém espaços dentro do valor JSON.

Requisitos do script

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

#!/bin/bash
# Exemplo: Múltiplos cabeçalhos
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Se o auxiliar falhar ou imprimir saída que não atenda a esses requisitos, Claude Code relata o erro em:

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

Comportamento de atualização

O script auxiliar de cabeçalhos é executado na inicialização e periodicamente depois para suportar atualização de token. 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 multi-equipe

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

# Adicionar atributos personalizados para identificação de equipe
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

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

• Filtre métricas por equipe ou departamento
• Rastreie custos por centro de custo
• Crie dashboards específicos de equipe
• Configure alertas para equipes específicas

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 atributos de ponto de dados como rótulos consultáveis, você pode agrupar e filtrar métricas por suas chaves personalizadas diretamente. Chaves personalizadas nunca substituem os atributos padrão como user.id ou session.id: quando uma chave colide, Claude Code mantém o valor integrado.

Cada chave personalizada se torna um rótulo em cada série de métrica, então 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 de ponto de dados, defina OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. Veja Controle de cardinalidade de métricas.

Configurações de exemplo

Defina essas 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 seu backend para a métrica claude_code.session.count após iniciar uma sessão; o Início rápido cobre verificação apenas de logs e o que verificar quando nada chega.

Para depuração de console com 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, raspado 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 apenas na capacidade padrão do runner de um. Em capacidade mais alta, o runner re-expõe contadores e medidores de sessão em seu próprio endpoint /metrics em vez disso.

Para enviar métricas para múltiplos 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 diferentes endpoints ou backends:

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

Métricas e eventos disponíveis

Atributos padrão

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

Quando Claude Code está conectado a um gateway de aplicativos Claude, a CLI marca as exportações com a identidade autenticada da sessão do gateway: user.id é o assunto do IdP em vez de um identificador de instalação anônimo, user.email é o email conectado e user.groups carrega a associação de grupo do IdP como uma string separada por vírgula. 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 em sessões de 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 evento.
• workspace.host_paths: diretórios de workspace do host selecionados no aplicativo desktop, como um array de string
• workflow.run_id: identificador de execução, prefixado com wf_, nos eventos de API e ferramenta emitidos por agentes que pertencem a uma execução de ferramenta Workflow. Filtrando eventos por um workflow.run_id reconstrói as solicitações de API e resultados de ferramentas dessa execução. O identificador cobre os agentes que o script de workflow gera e quaisquer agentes que esses gerem por sua vez, como invocações de skill. Ele corresponde ao identificador de execução relatado no resultado da ferramenta Workflow. Ausente em todos os outros eventos. Requer Claude Code v2.1.202 ou posterior
• workflow.name: nome do workflow, o meta.name do seu script, emitido junto com workflow.run_id. Nomes de workflow integrados aparecem verbatim quando a execução executa o script integrado não modificado. Nomes criados pelo usuário, incluindo cópias editadas de scripts integrados, são substituídos por custom a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido. Requer Claude Code v2.1.202 ou posterior

Métricas

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 de 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 observadas 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 lançada pelo usuário em vez de uma sessão conversacional. Filtre neste valor para separar lançamentos de processo de UI de sessões conversacionais em seus painéis.

Contador de linhas de código

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 um 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 solicitação de API.

Atributos:

• Todos os atributos padrão
• model: Identificador do modelo (por exemplo, "claude-sonnet-5")
• query_source: Categoria do subsistema que emitiu a solicitação. Um de "main", "subagent" ou "auxiliary"
• speed: "fast" quando a solicitação usou modo rápido. Ausente caso contrário
• effort: Nível de esforço aplicado à solicitação: "low", "medium", "high", "xhigh" ou "max". Ausente quando o modelo não suporta esforço.
• agent.name: Tipo de subagente que emitiu a solicitação. Nomes de agente integrados e agentes de plugins do marketplace oficial aparecem verbatim. Outros nomes de agente definidos pelo usuário são substituídos por "custom". Ausente quando a solicitação não foi emitida por um tipo de subagente nomeado.
• skill.name: Skill ativa para a solicitação, definida pela ferramenta Skill, um comando / ou herdada por um subagente gerado. Nomes de skill integrados, agrupados, definidos pelo usuário e de plugins do marketplace oficial aparecem verbatim. Nomes de skill de plugin de terceiros são substituídos por "third-party". Ausente quando nenhuma skill está ativa.
• plugin.name: Plugin proprietário quando a skill ativa ou subagente é fornecido por um plugin. Nomes de plugin do marketplace oficial aparecem verbatim. Nomes de plugin de terceiros são substituídos por "third-party". Ausente quando nem a skill nem o subagente têm um plugin proprietário.
• marketplace.name: Marketplace do qual o plugin proprietário foi instalado. Emitido apenas para plugins do marketplace oficial. Ausente caso contrário.
• mcp_server.name: Servidor MCP cuja ferramenta resultado esta solicitação consumiu. Nomes de servidor integrados, proxied por claude.ai e do registro oficial aparecem verbatim. Nomes de servidor configurados pelo usuário são substituídos por "custom". Ausente quando a solicitação não consumiu nenhum resultado de ferramenta MCP. Antes da v2.1.222, Claude Code definia este atributo em cada solicitação após uma chamada de ferramenta MCP, não apenas em solicitações que consumiram um resultado de ferramenta, então painéis que o agregam mostram uma queda após você atualizar.
• mcp_tool.name: Ferramenta MCP cujo resultado esta solicitação consumiu, com a mesma redação e comportamento de versão que mcp_server.name. Ausente quando a solicitação não consumiu nenhum resultado de ferramenta MCP.

Contador de token

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

Atributos:

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

Contador de decisão da ferramenta de edição de código

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: Onde a decisão veio. Um de "config", "hook", "user_permanent", "user_temporary", "user_abort" ou "user_reject". Veja o Evento de decisão da ferramenta para o que cada valor significa.
• language: Linguagem de programação do arquivo editado, como "TypeScript", "Python", "JavaScript" ou "Markdown". Retorna "unknown" para extensões de arquivo não reconhecidas.

Contador de tempo ativo

Rastreia o tempo real gasto usando ativamente Claude Code, excluindo tempo ocioso. Essa métrica é incrementada durante interações do usuário, como digitação e leitura de respostas, e durante processamento CLI, como execução de ferramentas 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 ferramentas 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 evento

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 vincular todos esses eventos de volta ao único prompt que os acionou.

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

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 de transcrição é interno ao Claude Code e muda entre versões, então um pipeline que se une nestes campos pode quebrar em qualquer versão; trate as uniões como específicas da versão em vez de um contrato estável:

• message.uuid em user_prompt e assistant_response
• request_id nos eventos de API, persistido como requestId nas entradas do 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• prompt_length: Comprimento do prompt
• prompt: Conteúdo do prompt. Reduzido por padrão. Defina OTEL_LOG_USER_PROMPTS=1 para incluí-lo
• message.uuid: UUID da mensagem do usuário resultante, correspondendo à entrada de transcrição persistida. Ausente em despachos 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 como digitados em vez do nome canônico. Nomes de comando customizado, plugin e MCP colapsam para custom ou mcp a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido
• command_source: Origem do comando quando presente: builtin, custom ou mcp. Comandos fornecidos por plugin relatam como custom

Evento de resposta do assistente

Registrado após cada solicitaçã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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• response_length: Comprimento do texto de resposta em caracteres
• response: Texto de resposta, truncado no limite de conteúdo (60 KB por padrão). Reduzido para <REDACTED> por padrão. Defina OTEL_LOG_ASSISTANT_RESPONSES=1 para incluí-lo. Quando OTEL_LOG_ASSISTANT_RESPONSES não está definido, OTEL_LOG_USER_PROMPTS controla isso em vez disso, então defina OTEL_LOG_ASSISTANT_RESPONSES=0 para manter respostas reduzidas enquanto o registro de prompt está ativado
• model: Identificador do modelo (por exemplo, "claude-sonnet-5")
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta. Presente apenas quando a API retorna um
• message.uuid: UUID da entrada de transcrição final 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 da próxima rodada se encadeia. Requer Claude Code v2.1.214 ou posterior
• query_source: Subsistema que emitiu a solicitação, como "repl_main_thread", "compact" ou um nome de subagente

Evento de resultado da ferramenta

Registrado quando uma ferramenta conclui a execução. Não é emitido se a chamada da ferramenta foi rejeitada; veja o Evento de decisão da 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• tool_name: Nome da ferramenta
• tool_use_id: Identificador único para esta invocação de ferramenta. Corresponde ao tool_use_id passado para hooks, permitindo correlação entre eventos OTel e dados capturados por hook.
• success: "true" ou "false"
• duration_ms: Tempo de execução em milissegundos
• error_type: String de categoria de erro quando a ferramenta falhou, como "Error:ENOENT" ou "ShellError"
• error (quando OTEL_LOG_TOOL_DETAILS=1): Mensagem de erro completa quando a ferramenta falhou
• decision_type: Sempre "accept", já que este evento é emitido apenas após a ferramenta ser executada. Chamadas rejeitadas não produzem um resultado de ferramenta
• decision_source: Onde a decisão de permissão veio. Um de "config", "hook", "user_permanent" ou "user_temporary". Veja o Evento de decisão da ferramenta para o que cada valor significa. As fontes apenas de rejeição "user_abort" e "user_reject" nunca aparecem neste evento.
• tool_input_size_bytes: Tamanho da entrada da ferramenta serializada em JSON em bytes
• tool_result_size_bytes: Tamanho do resultado da ferramenta em bytes
• mcp_server_scope: Identificador de escopo do servidor MCP (para ferramentas MCP)
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): String JSON contendo parâmetros específicos da ferramenta. Para servidores integrados do Claude Desktop, em sessões que o Claude Desktop possui, o par mcp_server_name/mcp_tool_name é incluído mesmo com a flag desligada, a mesma exceção de autoria do host que o Evento de decisão da 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, dangerouslyDisableSandbox e git_commit_id (o SHA do commit, quando um comando git commit é bem-sucedido). 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
• tool_input (quando OTEL_LOG_TOOL_DETAILS=1): Argumentos de ferramenta serializados em JSON. Valores individuais com mais de 512 caracteres são truncados, e a carga útil completa é limitada a ~4 K caracteres. Aplica-se a todas as ferramentas, incluindo ferramentas MCP.

Evento de solicitação de API

Registrado para cada solicitaçã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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• 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 solicitação em milissegundos
• input_tokens: Número de tokens de entrada
• output_tokens: Número de tokens de saída
• cache_read_tokens: Número de tokens lidos do cache
• cache_creation_tokens: Número de tokens usados para criação de cache
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta, como "req_011...". Presente apenas quando a API retorna um.
• client_request_id: UUID gerado pelo cliente enviado como o cabeçalho de solicitação x-client-request-id; veja a tabela atributos de correlação de evento 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 solicitação, como "repl_main_thread", "compact" ou um nome de subagente
• effort: Nível de esforço aplicado à solicitação: "low", "medium", "high", "xhigh" ou "max". Ausente quando o modelo não suporta esforço.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja Contador de custo para definições e comportamento de redação.

Evento de erro de API

Registrado quando uma solicitaçã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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• model: Modelo usado (por exemplo, "claude-sonnet-5")
• error: Mensagem de erro
• status_code: Código de status HTTP como número. Ausente para erros não-HTTP, como falhas de conexão.
• duration_ms: Duração da solicitação em milissegundos
• attempt: Número total de tentativas feitas, incluindo a solicitação inicial (1 significa que nenhuma tentativa ocorreu)
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta, como "req_011...". Presente apenas quando a API retorna um.
• client_request_id: UUID gerado pelo cliente enviado como o cabeçalho de solicitação x-client-request-id. Disponível mesmo quando uma falha como timeout ou erro de conexão nunca produziu um request_id do servidor; veja a tabela atributos de correlação de evento 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 solicitação, como "repl_main_thread", "compact" ou um nome de subagente
• effort: Nível de esforço aplicado à solicitação. Ausente quando o modelo não suporta esforço.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja Contador de custo para definições e comportamento de redação.

Evento de recusa de API

Registrado quando uma solicitação de API retorna stop_reason: "refusal". Recusas chegam em um fluxo 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 rastrear a frequência de recusa e agrupar 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• model: Identificador do modelo da solicitação
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta, como "req_011...". Presente apenas quando a API retorna um.
• query_source: Subsistema que emitiu a solicitação, como "repl_main_thread", "compact" ou um nome de subagente. Veja api_request para definições.
• speed: Ou "fast" quando Fast mode está ativo, ou "normal"
• attempt: Número de tentativa de repetição. A primeira tentativa é 1.
• effort: Nível de esforço aplicado à solicitação. Ausente quando o modelo não suporta esforço.
• server_fallback_hop: true quando o fallback de modelo do lado do servidor da API já tentou novamente esta recusa em um modelo diferente, então o usuário não viu esta recusa particular. false quando a solicitação terminou em uma recusa. Uma única rodada pode emitir tanto um evento hop true quanto um evento final false posterior quando o modelo de fallback também recusa.
• has_category: true quando a resposta da API carregava um stop_details.category de "cyber", "bio", "frontier_llm" ou "reasoning_extraction". false quando a resposta não carregava categoria ou um valor fora desse conjunto. Ausente quando server_fallback_hop é true, porque blocos hop não carregam stop_details.
• has_explanation: true quando a resposta da API carregava um stop_details.explanation, caso contrário false. Ausente quando server_fallback_hop é true.
• category: O valor stop_details.category da resposta da API. Um de "cyber", "bio", "frontier_llm" ou "reasoning_extraction". Presente apenas quando OTEL_LOG_TOOL_DETAILS=1 está definido e has_category é true.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja Contador de custo para definições e comportamento de redação.

Evento de corpo de solicitação de API

Registrado para cada tentativa de solicitação de API quando OTEL_LOG_RAW_API_BODIES está definido. Um evento é emitido por tentativa, então tentativas 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• body: Parâmetros de solicitaçã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 é reduzido. Emitido apenas em modo inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Caminho absoluto para um arquivo <dir>/<uuid>.request.json contendo o corpo não truncado. Emitido apenas em modo arquivo (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Comprimento do corpo não truncado. Bytes UTF-8 quando OTEL_LOG_RAW_API_BODIES=file:<dir>, ou unidades de código UTF-16 quando =1
• body_truncated: "true" quando truncamento inline ocorreu. Ausente em modo arquivo e quando nenhum truncamento ocorreu.
• model: Identificador do modelo dos parâmetros de solicitação
• query_source: Subsistema que emitiu a solicitação (por exemplo, "compact")

Evento de corpo de resposta de API

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

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• 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 é reduzido. Emitido apenas em modo inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Caminho absoluto para um arquivo <dir>/<request_id>.response.json contendo o corpo não truncado. Emitido apenas em modo arquivo (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Comprimento do corpo não truncado. Bytes UTF-8 quando OTEL_LOG_RAW_API_BODIES=file:<dir>, ou unidades de código UTF-16 quando =1
• body_truncated: "true" quando truncamento inline ocorreu. Ausente em modo arquivo e quando nenhum truncamento ocorreu.
• model: Identificador do modelo
• query_source: Subsistema que emitiu a solicitação
• request_id: ID de solicitação da API Anthropic do cabeçalho request-id da resposta, como "req_011...". Presente apenas quando a API retorna um.

Evento de decisão da ferramenta

Registrado quando uma decisão de permissão da 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• tool_name: Nome da ferramenta (por exemplo, "Read", "Edit", "Write", "NotebookEdit")
• tool_use_id: Identificador único para esta invocação de ferramenta. Corresponde ao tool_use_id passado para hooks, permitindo correlação entre eventos OTel e dados capturados por hook.
• decision: Ou "accept" ou "reject"
• 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 a partir 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 o próprio Claude Code gera, relatam esses servidores como "mcp"
• source: Onde a decisão veio:
  • "config": Decidido automaticamente sem avisar, baseado em configurações de projeto, regras de permissão nas configurações pessoais do usuário, política gerenciada corporativa, sinalizadores --allowedTools ou --disallowedTools, o modo de permissão ativo, uma concessão com escopo de sessão de um prompt anterior na mesma sessão CLI interativa, ou porque a ferramenta é inerentemente segura. O evento não indica qual dessas fontes correspondeu. Claude Code também relata "config" quando a própria solicitação de aviso 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 fluxo de entrada fecha enquanto a solicitaçã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 aviso de permissão, que salva uma regra de permissão em suas configurações pessoais. Na CLI interativa isso é emitido apenas para essa escolha em si; chamadas posteriores que correspondem à regra salva emitem "config" em vez disso. No Agent SDK ou sessões não-interativas -p, tanto a escolha inicial quanto correspondências de regra posteriores emitem "user_permanent". Tratado como uma aceitação.
  • "user_temporary": Emitido quando o usuário escolheu "Sim" em um aviso de permissão para uma aprovação única, ou escolheu uma opção que concede acesso pelo resto da sessão em um aviso de edição ou leitura de arquivo. Na CLI interativa isso é emitido apenas para a escolha em si; chamadas posteriores permitidas por essa concessão com escopo de sessão emitem "config" em vez disso. No Agent SDK ou sessões não-interativas -p, tanto a escolha quanto correspondências posteriores emitem "user_temporary". Tratado como uma aceitação.
  • "user_abort": Emitido quando o usuário descartou o aviso de permissão sem responder. No Agent SDK e sessões não-interativas -p, isso inclui interromper a rodada enquanto uma solicitaçã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 isso é emitido apenas para essa escolha em si; chamadas que correspondem a uma regra de negação nas configurações pessoais do usuário emitem "config" em vez disso. No Agent SDK ou sessões não-interativas -p, chamadas que correspondem a uma regra de negação em configurações pessoais emitem "user_reject". Tratado como uma rejeição.
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): String JSON contendo parâmetros específicos da ferramenta. Mesma forma que o Evento de resultado da ferramenta, menos campos pós-execução como git_commit_id. Os valores podem diferir de tool_result para uma chamada aceita se a decisão de permissão reescrever a entrada da ferramenta via updatedInput. Use este atributo para ver qual comando foi rejeitado quando decision é "reject".
  • Para 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 fluxo 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 Plan Mode ou 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• from_mode: O modo de permissão anterior, por exemplo "default", "plan", "acceptEdits", "auto" ou "bypassPermissions"
• to_mode: O novo modo de permissão
• trigger: O que causou a mudança. Um de "shift_tab", "exit_plan_mode", "auto_gate_denied" ou "auto_opt_in". Ausente quando a transição se origina do SDK ou bridge

Evento de autenticação

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• action: "login" ou "logout"
• success: "true" ou "false"
• auth_method: Método de autenticação, como "oauth"
• error_category: Tipo de erro categórico quando a ação falhou. A mensagem de erro bruta nunca é incluída
• status_code: Código de status HTTP como string quando a ação falhou com um erro HTTP

Evento de conexão do servidor MCP

Registrado quando um servidor MCP se conecta, desconecta ou falha ao 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• status: "connected", "failed" ou "disconnected"
• transport_type: Transporte do servidor, como "stdio", "sse" ou "http"
• server_scope: Escopo em que o servidor está configurado, como "user", "project" ou "local"
• duration_ms: Duração da tentativa de conexão em milissegundos
• error_code: Código de erro quando a conexão falhou
• is_plugin: true quando o servidor é fornecido por um plugin, false caso contrário
• plugin_id_hash (quando is_plugin é true): Hash estável do nome do plugin e marketplace, para agrupar eventos por plugin sem expor o nome. Claude Code o computa conforme descrito sob o evento de plugin carregado
• plugin.name (quando is_plugin é true): Nome do plugin que fornece o servidor. Para plugins de terceiros isso é a string literal "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1; isso protege nomes de plugins de terceiros de aparecerem em logs por padrão. Plugins de fontes oficiais Anthropic são sempre identificados por nome. Os atributos plugin_id_hash e plugin.name fluem para seu próprio backend de monitoramento e não são enviados para Anthropic
• server_name (quando OTEL_LOG_TOOL_DETAILS=1): Nome do servidor configurado
• error (quando OTEL_LOG_TOOL_DETAILS=1): Mensagem de erro completa quando a conexão falhou

Evento de erro interno

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 rastreamento de pilha nunca são incluídos. Este evento não é emitido ao executar contra Amazon Bedrock, Google Cloud's Agent Platform 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• error_name: Nome da classe de erro, como "TypeError" ou "SyntaxError"
• error_code: Código errno Node.js como "ENOENT" quando presente no erro

Evento de plugin instalado

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• marketplace.is_official: "true" se o marketplace é um marketplace oficial Anthropic, "false" caso contrário
• install.trigger: "cli" ou "ui"
• plugin.name: Nome do plugin instalado. Para marketplaces de terceiros isso é incluído apenas quando OTEL_LOG_TOOL_DETAILS=1
• plugin.version: Versão do plugin quando declarada na entrada do marketplace. Para marketplaces de terceiros isso é incluído apenas quando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace do qual o plugin foi instalado. Para marketplaces de terceiros isso é incluído apenas quando OTEL_LOG_TOOL_DETAILS=1

Evento de plugin carregado

Registrado uma vez por plugin ativado no início da sessão. Use este evento para inventariar quais plugins estão ativos em toda a sua frota, como complemento ao 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• plugin.name: nome do plugin. Para plugins fora do marketplace oficial e pacote integrado o valor é "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: marketplace do qual o plugin foi instalado, quando conhecido. Reduzido para "third-party" sob a mesma condição que plugin.name
• plugin.version: versão do manifesto do plugin. Incluído apenas quando o nome não é reduzido e o manifesto declara uma versão
• plugin.scope: categoria de proveniência para o plugin: "official", "community", "org", "user-local" ou "default-bundle"
• enabled_via: como o plugin veio a ser ativado: "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. Antes da v2.1.246, Claude Code relatava esses plugins como "user-install" ou "seed-mount"
• plugin_id_hash: hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar os plugins de terceiros distintos carregados em toda a 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 ativado

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• skill.name: Nome da skill. Para skills definidas pelo usuário e de plugin de terceiros o valor é o placeholder "custom_skill" a menos que OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger: Como a skill foi acionada ("user-slash", "claude-proactive" ou "nested-skill")
• skill.source: De onde a skill foi carregada (por exemplo, "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind: "workflow" quando a skill é uma skill de workflow. Ausente caso contrário
• plugin.name (quando OTEL_LOG_TOOL_DETAILS=1 ou o plugin é de um marketplace oficial): Nome do plugin proprietário quando a skill é fornecida por um plugin
• marketplace.name (quando OTEL_LOG_TOOL_DETAILS=1 ou o plugin é de um marketplace oficial): Marketplace do qual o plugin proprietário foi instalado, quando a skill é fornecida por um plugin

Evento de menção @

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• 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 tentativas de API esgotadas

Registrado uma vez quando uma solicitaçã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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• model: Modelo usado
• error: Mensagem de erro final
• status_code: Código de status HTTP como número. Ausente para erros não-HTTP.
• total_attempts: Número total de tentativas feitas
• total_retry_duration_ms: Tempo total de parede em todas as tentativas
• speed: "fast" ou "normal"

Evento de hook registrado

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

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• hook_event: tipo de evento de hook, como "PreToolUse" ou "PostToolUse"
• hook_type: tipo de implementação de hook: "command", "prompt", "mcp_tool", "http" ou "agent"
• hook_source: onde o hook é definido: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings" ou "pluginHook"
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. Requer Claude Code v2.1.169 ou posterior
• hook_matcher (quando OTEL_LOG_TOOL_DETAILS=1): a string matcher da configuração do hook, quando uma está definida
• plugin.name (quando hook_source é "pluginHook"): nome do plugin contribuidor. Para plugins fora do marketplace oficial e pacote integrado o valor é "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1
• plugin_id_hash (quando hook_source é "pluginHook"): hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar plugins contribuidores distintos sem registrar seus nomes. Claude Code o computa conforme descrito sob o 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• hook_event: Tipo de evento de hook, como "PreToolUse" ou "PostToolUse"
• hook_name: Nome completo do hook incluindo matcher, como "PreToolUse:Write"
• num_hooks: Número de comandos de hook correspondentes
• managed_only: "true" quando apenas hooks de política gerenciada são permitidos
• hook_source: "policySettings" ou "merged"
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. Requer Claude Code v2.1.169 ou posterior
• hook_definitions: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e OTEL_LOG_TOOL_DETAILS=1 estão ambos ativados

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

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• hook_event: Tipo de evento de hook
• hook_name: Nome completo do hook incluindo matcher
• num_hooks: Número de comandos de hook correspondentes
• num_success: Contagem que completou com sucesso
• num_blocking: Contagem que retornou uma decisão de bloqueio
• num_non_blocking_error: Contagem que falhou sem bloquear
• num_cancelled: Contagem cancelada antes da conclusão
• total_duration_ms: Duração de parede de todos os hooks correspondentes
• managed_only: "true" quando apenas hooks de política gerenciada são permitidos
• hook_source: "policySettings" ou "merged"
• safe_mode: "true" quando a sessão foi iniciada com --safe-mode, "false" caso contrário. Requer Claude Code v2.1.169 ou posterior
• hook_definitions: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e OTEL_LOG_TOOL_DETAILS=1 estão ambos ativados

Evento de métricas de plugin de hook

Registrado quando um hook de plugin do marketplace oficial emite métricas por invocação. Apenas plugins instalados de um marketplace oficial Anthropic podem emitir esses dados. Plugins de marketplace de terceiros e hooks configurados pelo usuário não emitem para este evento. Use este evento para monitorar o comportamento do 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• plugin_id: identificador do plugin em forma <name>@<marketplace>
• hook_event: tipo de evento de hook que emitiu as métricas
• Até 20 chaves de métrica emitidas pelo plugin. Os nomes correspondem a ^[a-z][a-z0-9_]{0,39}$. Os valores são booleanos ou números.

Evento de compactação

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• trigger: "auto" ou "manual"
• success: "true" ou "false"
• duration_ms: Duração da compactação
• pre_tokens: Contagem aproximada de tokens antes da compactação
• post_tokens: Contagem aproximada de tokens após compactação
• error: Mensagem de erro quando a compactação falhou
• precompute_reuse: Definido apenas quando trigger é "manual". A compactação automática pode preparar um resumo em segundo plano antes da janela de contexto se encher, e este atributo registra se /compact reutilizou esse resumo preparado. "hit" significa que foi reutilizado; "miss_custom_instructions", "miss_hook" e "miss_not_ready" dão a razão pela qual um resumo fresco foi computado em vez disso. Requer Claude Code v2.1.153 ou posterior

Evento de 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 solicitação final. A categoria "subagent" também conta solicitações de hooks baseados em agentes, que não emitem nenhum 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• agent_type: O tipo de subagente. Nomes de agente integrados e agentes de plugins do marketplace oficial aparecem verbatim; outros nomes de agente são substituídos por "custom" a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido
• agent.source: De onde a definição do agente veio: built-in, plugin ou a fonte de configurações que definiu um agente customizado, como userSettings ou projectSettings
• is_built_in: Se o subagente é um tipo de agente integrado
• is_async: Se o subagente foi executado em segundo plano
• total_tokens: A pegada de token da solicitação final de API do subagente: tokens de entrada, criação de cache, leitura de cache e saída dessa solicitação, aproximadamente o tamanho do contexto do subagente na conclusão. Não é uma soma em toda a execução
• total_tool_uses: Número de chamadas de ferramenta que o subagente fez em toda a execução
• duration_ms: Tempo de execução em milissegundos
• model: O modelo que o subagente foi resolvido para executar
• final_model: O modelo que produziu a resposta final do subagente, que difere de model após uma mudança no meio da execução, como um fallback. Requer Claude Code v2.1.212 ou posterior
• model_swapped: Se mais de um modelo serviu as solicitações do subagente. Requer Claude Code v2.1.212 ou posterior
• plugin_id_hash, plugin.name: Presente para agentes fornecidos por plugin. Nomes de plugin do marketplace oficial aparecem verbatim; outros nomes de plugin são substituídos por "third-party" a menos que OTEL_LOG_TOOL_DETAILS=1 esteja definido

Evento de pesquisa de feedback

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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• event_type: Evento do ciclo de vida da pesquisa, por exemplo "appeared", "responded" ou "transcript_prompt_appeared"
• appearance_id: ID único vinculando os eventos emitidos para uma instância de pesquisa
• survey_type: Qual pesquisa produziu o evento. "session" é o prompt de classificação "Como Claude está se saindo?"
• response: A seleção do usuário em eventos responded
• enabled_via_override: true quando CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL está definido. Emitido como um booleano, não uma string. Presente em eventos de pesquisa session. Filtre neste atributo para confirmar que a substituição é aplicada em toda a frota

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 segundo plano 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 nas últimas 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 consegue determinar com segurança o período de retenção, ele pausa a varredura e emite o evento com result definido como "skipped" e um skip_reason. Quando configurações gerenciadas definem cleanupPeriodDays, o valor gerenciado fixa o período de retenção e a varredura é executada 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 consegue 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 monotonicamente crescente para ordenar eventos dentro de uma sessão
• result: "complete" quando a varredura foi executada, "skipped" quando Claude Code a pausou
• period_days: O valor cleanupPeriodDays das configurações mescladas, em dias, ou 30 quando nenhuma fonte o define. Em eventos ignorados, o valor que a varredura teria usado, computado a partir das fontes de configurações que Claude Code conseguiu 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 a opção settingSources do SDK, e nenhuma fonte ativada fornece cleanupPeriodDays
  • "settings_unknowable": Um arquivo de configurações não conseguiu ser lido ou analisado, então cleanupPeriodDays ou desktopSessionCleanupPeriodDays pode estar definido para um valor que Claude Code não consegue 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 de nível superior ~/.claude/projects/*/*.jsonl, 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. Estes não contam para files_past_cutoff. Requer Claude Code v2.1.248 ou posterior
• session_files_deleted: Número de artefatos que a varredura de arquivos de sessão deletou: transcrições mais arquivos complementares por sessão, como sidecars, gravações e resultados de ferramentas
• artifacts_deleted: Total de itens que a varredura deletou em todos os diretórios de dados que cobre, incluindo os arquivos de sessão. Algumas varreduras contam uma árvore de diretório removida inteira como um item e algumas passagens de limpeza não contribuem para o contador, então trate o valor como um piso em vez de uma contagem exata de arquivos
• files_retained_fresh: Arquivos inspecionados e deixados 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

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.

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, onde é o assunto do IdP do token emitido pelo gateway.

Chamadas de ferramenta MCP, comandos Bash e edições de arquivo são, portanto, atribuídas ao desenvolvedor que iniciou a sessão. 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.

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: a CLI marca a identidade do IdP automaticamente, conforme descrito em Atributos padrão.

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, execute claude --debug e verifique o log de depuração 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
• 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
  • Spans de rastreamento incluem o mesmo atributo tool_input e atributos derivados de entrada como file_path, com o mesmo truncamento que tool_input
• O conteúdo de entrada e saída de ferramenta não é registrado em spans de rastreamento por padrão. Para incluí-lo, defina OTEL_LOG_TOOL_CONTENT=1. Quando ativado, eventos de span incluem conteúdo completo de entrada e saída de ferramenta truncado no limite de conteúdo (60 KB por padrão) por atributo. Isso pode incluir conteúdos de arquivo brutos de resultados da ferramenta Read e saída de comando Bash. Configure seu backend de telemetria para filtrar ou reduzir esses atributos conforme necessário
• Corpos de solicitação e resposta da API Anthropic Messages brutos não são registrados por padrão. Para incluí-los, defina OTEL_LOG_RAW_API_BODIES 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

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