- quais ferramentas eles chamaram
- quanto tempo cada solicitação de modelo levou
- quantos tokens foram gastos
- onde ocorreram falhas
Como a telemetria flui do SDK
O Agent SDK executa o Claude Code CLI como um processo filho e se comunica com ele através de um pipe local. O CLI tem instrumentação OpenTelemetry integrada: ele registra spans em torno de cada solicitação de modelo e execução de ferramenta, emite métricas para contadores de token e custo, e emite eventos de log estruturados para prompts e resultados de ferramentas. O SDK não produz telemetria própria. Em vez disso, ele passa a configuração para o processo CLI, e o CLI exporta diretamente para seu coletor. A configuração é passada como variáveis de ambiente. Por padrão, o processo filho herda o ambiente da sua aplicação, então você pode configurar a telemetria em um de dois lugares:- Ambiente do processo: defina as variáveis em seu shell, container ou orquestrador antes de sua aplicação iniciar. Cada chamada
query()as coleta automaticamente sem alteração de código. Esta é a abordagem recomendada para implantações em produção. - Opções por chamada: defina as variáveis em
ClaudeAgentOptions.env(Python) ouoptions.env(TypeScript). Use isso quando diferentes agentes no mesmo processo precisam de diferentes configurações de telemetria. Em Python,envé mesclado no topo do ambiente herdado. Em TypeScript,envsubstitui completamente o ambiente herdado, então inclua...process.envno objeto que você passa.
Para a lista completa de nomes de métricas, nomes de eventos e atributos, consulte a referência de Monitoring do Claude Code. O Agent SDK emite os mesmos dados porque executa o mesmo CLI. Os nomes de span estão listados em Ler traces do agente abaixo.
Ativar exportação de telemetria
A telemetria está desativada até que você definaCLAUDE_CODE_ENABLE_TELEMETRY=1 e escolha pelo menos um exportador. A configuração mais comum envia todos os três sinais sobre OTLP HTTP para um coletor.
O exemplo a seguir define as variáveis em um dicionário e as passa através de options.env. O agente executa uma única tarefa, e o CLI exporta spans, métricas e eventos para o coletor em collector.example.com enquanto o loop consome o fluxo de resposta:
options.env inteiramente.
O exportador
console escreve telemetria na saída padrão, que o SDK usa
como seu canal de mensagem. Não defina console como um valor de exportador ao executar
através do SDK. Para inspecionar telemetria localmente, aponte
OTEL_EXPORTER_OTLP_ENDPOINT para um coletor local ou um container Jaeger
all-in-one em vez disso.Liberar telemetria de chamadas de curta duração
O CLI agrupa telemetria e exporta em um intervalo. Em uma saída limpa do processo, ele tenta liberar dados pendentes, mas a liberação é limitada por um timeout curto, então spans ainda podem ser descartados se o coletor for lento para responder. Se seu processo for morto antes do CLI desligar, qualquer coisa ainda no buffer de lote é perdida. Reduzir os intervalos de exportação reduz ambas as janelas. Por padrão, métricas exportam a cada 60 segundos e traces e logs exportam a cada 5 segundos. O exemplo a seguir encurta todos os três intervalos para que os dados cheguem ao coletor enquanto uma tarefa curta ainda está em execução:Ler traces do agente
Traces fornecem a visão mais detalhada de uma execução de agente. ComCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 definido, cada etapa do loop do agente se torna um span que você pode inspecionar em seu backend de rastreamento:
claude_code.interaction: envolve uma única volta do loop do agente, desde receber um prompt até produzir uma resposta.claude_code.llm_request: envolve cada chamada para a API Claude, com nome do modelo, latência e contagens de tokens como atributos.claude_code.tool: envolve cada invocação de ferramenta, com spans filhos para a espera de permissão (claude_code.tool.blocked_on_user) e a execução em si (claude_code.tool.execution).claude_code.hook: envolve cada execução de hook. Requer rastreamento beta detalhado (ENABLE_BETA_TRACING_DETAILED=1eBETA_TRACING_ENDPOINT) além das variáveis acima.
llm_request, tool e hook são filhos do span claude_code.interaction envolvente. Quando o agente gera um subagente através da ferramenta Task, os spans llm_request e tool do subagente se aninham sob o span claude_code.tool do agente pai, então a cadeia de delegação completa aparece como um trace.
Spans carregam um atributo session.id por padrão. Quando você faz várias chamadas query() contra a mesma sessão, filtre em session.id em seu backend para vê-las como uma linha do tempo. O atributo é omitido se OTEL_METRICS_INCLUDE_SESSION_ID for definido como um valor falso.
O rastreamento está em beta. Os nomes de span e atributos podem mudar entre versões. Consulte
Traces (beta) na referência de Monitoring
para as variáveis de configuração do exportador de trace.
Vincular traces à sua aplicação
O SDK propaga automaticamente o contexto de trace W3C para o subprocesso CLI. Quando você chamaquery() enquanto um span OpenTelemetry está ativo em sua aplicação, o SDK injeta TRACEPARENT e TRACESTATE no ambiente do processo filho, e o CLI os lê para que seu span claude_code.interaction se torne um filho do seu span. A execução do agente então aparece dentro do trace da sua aplicação em vez de como uma raiz desconectada.
Quando a propagação de contexto de trace está ativada, o CLI também encaminha TRACEPARENT para cada comando Bash e PowerShell que executa. Se um comando lançado através da ferramenta Bash emite seus próprios spans OpenTelemetry, esses spans se aninham sob o span claude_code.tool.execution que envolve o comando.
A injeção automática é ignorada quando você define TRACEPARENT explicitamente em options.env, então você pode fixar um contexto pai específico se necessário. As sessões interativas do CLI ignoram completamente TRACEPARENT de entrada; apenas execuções do Agent SDK e claude -p a honram. Consulte Traces (beta) na referência de Monitoring para a referência completa de span e atributo.
Marcar telemetria do seu agente
Por padrão, o CLI relataservice.name como claude-code. Se você executar vários agentes ou executar o SDK junto com outros serviços que exportam para o mesmo coletor, substitua o nome do serviço e adicione atributos de recurso para que você possa filtrar por agente em seu backend.
O exemplo a seguir renomeia o serviço e anexa metadados de implantação. Esses valores são aplicados como atributos de recurso OpenTelemetry em cada span, métrica e evento que o agente emite:
Atribuir ações aos seus usuários finais
O CLI anexa atributos de identidade a cada evento com base na credencial que usa para chamar Anthropic. Quando você constrói uma aplicação que serve muitos usuários finais a partir de uma implantação, esses atributos identificam a credencial do seu serviço, não o usuário final em nome de quem o agente agiu. Para tornar as chamadas de ferramentas e atividade MCP atribuíveis aos usuários finais da sua aplicação, injete identidade de usuário final como atributos de recurso em cada chamadaquery(). Codifique valores em percentual antes de interpolá-los, já que OTEL_RESOURCE_ATTRIBUTES reserva vírgulas, espaços e sinais de igual. O exemplo a seguir anexa o usuário solicitante e o tenant a cada span e evento de uma solicitação. Ele assume um objeto request do seu framework web contendo os IDs do usuário e do tenant:
tool_decision, tool_result, mcp_server_connection e permission_mode_changed, que são exportados como registros de log nomeados com um prefixo claude_code., se tornam uma trilha de auditoria por usuário que você pode encaminhar para uma plataforma de Security Information and Event Management (SIEM). Consulte Auditar eventos de segurança na referência de Monitoring para a lista completa de eventos relevantes para segurança e os atributos que cada um carrega.
Controlar dados sensíveis em exportações
A telemetria é estrutural por padrão. Durações, nomes de modelos e nomes de ferramentas são registrados em cada span; contagens de tokens são registradas quando a solicitação de API subjacente retorna dados de uso, então spans para solicitações falhadas ou abortadas podem omiti-los. O conteúdo que seu agente lê e escreve não é registrado por padrão. Essas variáveis opt-in adicionam conteúdo aos dados exportados:
Deixe essas não definidas a menos que seu pipeline de observabilidade seja aprovado para armazenar os dados que seu agente manipula. Consulte Segurança e privacidade na referência de Monitoring para a lista completa de atributos e comportamento de redação.
Documentação relacionada
Estes guias cobrem tópicos adjacentes para monitoramento e implantação de agentes:- Rastrear custo e uso: leia dados de token e custo do fluxo de mensagem sem um backend externo.
- Hospedando o Agent SDK: implante agentes em containers onde você pode definir variáveis OpenTelemetry no nível do ambiente.
- Monitoring: a referência completa para cada variável de ambiente, métrica e evento que o CLI emite.