Monitoraggio

Scopri come abilitare e configurare OpenTelemetry per Claude Code.

Traccia l'utilizzo di Claude Code, i costi e l'attività degli strumenti in tutta l'organizzazione esportando i dati di telemetria tramite OpenTelemetry (OTel). Claude Code esporta le metriche come dati di serie temporali tramite il protocollo di metriche standard, gli eventi tramite il protocollo di log/eventi, e facoltativamente le tracce distribuite tramite il protocollo di tracce.

Avvio rapido

Configura OpenTelemetry utilizzando variabili di ambiente:

# 1. Abilita la telemetria
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Scegli gli esportatori (entrambi sono facoltativi - configura solo ciò di cui hai bisogno)
export OTEL_METRICS_EXPORTER=otlp       # Opzioni: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Opzioni: otlp, console, none

# 3. Configura l'endpoint OTLP (per l'esportatore OTLP)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Imposta l'autenticazione (se richiesta)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Per il debug: riduci gli intervalli di esportazione e ripristinali per l'uso in produzione
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 secondi (predefinito: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 secondi (predefinito: 5000ms)

# 6. Esegui Claude Code
claude

Per verificare una configurazione che esporta metriche, controlla il tuo backend per la metrica claude_code.session.count, che Claude Code emette quando inizia una sessione. Per verificare una configurazione solo log, invia un prompt e controlla l'evento claude_code.user_prompt.

Se non arriva nulla, esegui claude --debug e controlla il log di debug. Claude Code segnala i guasti degli esportatori che configuri come errori [3P telemetry], dove 3P significa third-party. Le righe con prefisso [Anthropic telemetry] descrivono la telemetria operativa separata di Anthropic e non indicano un problema con la tua configurazione.

Per le opzioni di configurazione complete, consulta la specifica OpenTelemetry.

Configurazione dell'amministratore

Gli amministratori possono configurare le impostazioni di OpenTelemetry per tutti gli utenti tramite il file di impostazioni gestite. Consulta la precedenza delle impostazioni per ulteriori informazioni su come vengono applicate le impostazioni.

Esempio di configurazione delle impostazioni gestite:

{
  "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 non passa le variabili di ambiente OTEL_* ai sottoprocessi che genera, incluso lo strumento Bash, gli hooks, i server MCP e i language server. Un'applicazione strumentata con OpenTelemetry che esegui tramite lo strumento Bash non eredita l'endpoint dell'esportatore di Claude Code o le intestazioni, quindi imposta quelle variabili direttamente nel comando se quell'applicazione ha bisogno di esportare la propria telemetria.

Come le impostazioni gestite bloccano la destinazione OTLP

Quando imposti una variabile OTEL_EXPORTER_OTLP_* nelle impostazioni gestite, Claude Code rimuove le variabili conflittuali impostate dagli sviluppatori all'avvio e registra un avviso che puoi visualizzare con claude --debug. Ciò che rimuove dipende da quale variabile imposti:

• Endpoint: quando imposti OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code rimuove ogni endpoint per segnale impostato dagli sviluppatori. Gli sviluppatori non possono puntare un segnale a un collector diverso, quindi non è necessario impostare anche le variabili di endpoint per segnale nelle impostazioni gestite.

• Protocolli: quando imposti OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code rimuove ogni protocollo per segnale impostato dagli sviluppatori.

• Credenziali: quando imposti OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY o OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, Claude Code rimuove le versioni per segnale di quella variabile impostate dagli sviluppatori, più ogni variabile di endpoint impostata dagli sviluppatori, generica o per segnale, poiché quelle credenziali raggiungerebbero altrimenti un collector che le impostazioni gestite non hanno scelto.

• Selettori di esportatore: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER e il beta OTEL_TRACES_EXPORTER seguono la precedenza normale per chiave. L'impostazione di uno sviluppatore può comunque disabilitare un segnale o passarlo all'esportatore della console, quindi imposta i selettori anche nelle impostazioni gestite se hai bisogno che siano bloccati. Tra le fonti amministratore, OTEL_LOGS_EXPORTER segue l'unità di telemetria mentre gli altri due selettori si uniscono per chiave. Richiede Claude Code v2.1.223 o successivo.

• Endpoint di tracciamento beta: con il tracciamento beta dettagliato attivo, Claude Code esporta log e tracce a BETA_TRACING_ENDPOINT invece che tramite gli esportatori di log e tracce. Claude Code quindi rimuove un BETA_TRACING_ENDPOINT impostato dagli sviluppatori ogni volta che una di queste impostazioni gestite decide la destinazione di uno dei due segnali:

  • Un endpoint generico o di log/tracce o una credenziale
  • Un otelHeadersHelper
  • Un selettore di esportatore di log o tracce impostato su none, console o vuoto, valori che mantengono il segnale fuori da un collector
  • CLAUDE_CODE_ENABLE_TELEMETRY disattivato

  Un endpoint o una credenziale solo per metriche non lo rimuove. Prima della v2.1.251, un BETA_TRACING_ENDPOINT impostato dagli sviluppatori reindirizzava i log e le tracce che il tracciamento beta dettagliato esporta anche quando le impostazioni gestite hanno fissato il collector.

Claude Code non rimuove le variabili per segnale che imposti nelle impostazioni gestite stesse, quindi puoi instradare un segnale a un collector diverso impostando la sua variabile lì, come fa l'esempio SIEM. Se imposti una credenziale per segnale lì, Claude Code rimuove l'endpoint impostato dagli sviluppatori per quel segnale.

Questo comportamento di rimozione cambia dove viene consegnata la telemetria, non cosa raccoglie Claude Code.

Prima della v2.1.217, ogni variabile seguiva la precedenza delle impostazioni per chiave indipendentemente, quindi un endpoint specifico del segnale impostato nelle impostazioni dell'utente o nella shell reindirizzava quel segnale lontano dal collector gestito.

Quando l'app desktop o un runner di ambiente self-hosted avvia Claude Code e nomina un endpoint OTLP nell'ambiente che fornisce, Claude Code fissa la destinazione allo stesso modo: le variabili di telemetria del launcher rimuovono le variabili impostate dagli sviluppatori esattamente come fanno le impostazioni gestite. Claude Code non rimuove le variabili che il launcher stesso ha impostato. Richiede Claude Code v2.1.251 o successivo.

Dettagli della configurazione

Variabili di configurazione comuni

Queste variabili configurano esportatori, endpoint e comportamento di esportazione per tutti i deployment. Se imposti una variabile di endpoint o protocollo per segnale specifico, come OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, Claude Code la utilizza al posto della variabile generica per quel segnale. Se imposti una variabile di intestazioni per segnale specifico, come OTEL_EXPORTER_OTLP_METRICS_HEADERS, Claude Code la unisce con la generica OTEL_EXPORTER_OTLP_HEADERS per quel segnale. Su macchine con impostazioni gestite, vedi Come le impostazioni gestite bloccano la destinazione OTLP per sapere cosa Claude Code rimuove.

Per i protocolli http/protobuf e http/json, Claude Code invia ogni richiesta di esportazione con un'intestazione Content-Length. Prima della v2.1.212, le versioni di Claude Code dalla v2.1.191 in poi inviavano queste richieste con codifica di trasferimento chunked; Azure Monitor e altri endpoint che richiedono una lunghezza dichiarata le rifiutavano con errori 411 Length Required o 400.

Autenticazione mTLS

Il modo in cui configuri i certificati client per l'esportatore OTLP dipende dal protocollo OTLP in uso per quel segnale, impostato tramite OTEL_EXPORTER_OTLP_PROTOCOL o l'override per segnale. La stessa configurazione si applica a metriche, log e tracce.

Per grpc, l'SDK OpenTelemetry legge direttamente le variabili OTLP standard, quindi le configurazioni esistenti che impostano le variabili di metriche per segnale continuano a funzionare. Su macchine con impostazioni gestite, Claude Code può rimuovere credenziali e endpoint per segnale impostati dallo sviluppatore all'avvio.

Controllo della cardinalità delle metriche

Le seguenti variabili di ambiente controllano quali attributi sono inclusi nelle metriche per gestire la cardinalità:

Una cardinalità inferiore generalmente significa prestazioni migliori e costi di archiviazione inferiori ma dati meno granulari per l'analisi.

Tracce (beta)

Le tracce distribuite esportano span che collegano ogni prompt dell'utente alle richieste API e alle esecuzioni degli strumenti che attiva, in modo da poter visualizzare una richiesta completa come una singola traccia nel tuo backend di traccia.

Le tracce sono disabilitate per impostazione predefinita. Per abilitarle, imposta sia CLAUDE_CODE_ENABLE_TELEMETRY=1 che CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, quindi imposta OTEL_TRACES_EXPORTER per scegliere dove vengono inviati gli span. Le tracce riutilizzano la configurazione OTLP comune per endpoint, protocollo, intestazioni e mTLS. Su macchine con impostazioni gestite, Claude Code può rimuovere credenziali e endpoint per segnale impostati dallo sviluppatore all'avvio.

Gli span oscurano il testo del prompt dell'utente, i dettagli di input dello strumento e il contenuto dello strumento per impostazione predefinita. Imposta OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1, e OTEL_LOG_TOOL_CONTENT=1 per includerli.

Quando la traccia è attiva, i sottoprocessi Bash e PowerShell ereditano automaticamente una variabile di ambiente TRACEPARENT contenente il contesto di traccia W3C dello span di esecuzione dello strumento attivo. Ciò consente a qualsiasi sottoprocesso che legge TRACEPARENT di far diventare i propri span figli della stessa traccia, abilitando la traccia distribuita end-to-end attraverso script e comandi che Claude esegue.

Quando la traccia è attiva e Claude Code è connesso direttamente all'API Anthropic, ogni richiesta del modello porta un'intestazione W3C traceparent impostata al contesto dello span claude_code.llm_request, e l'intestazione traceresponse dell'API viene registrata come collegamento di span. Insieme questi collegano gli span lato client di Claude Code alla traccia lato server attraverso qualsiasi intermediario conforme. Le richieste HTTP MCP in uscita portano traceparent allo stesso modo. L'intestazione non viene inviata ai provider di terze parti.

Per impostazione predefinita, l'intestazione traceparent sulle richieste di modello e HTTP MCP viene inviata solo quando ANTHROPIC_BASE_URL non è impostato o punta all'API Anthropic, poiché alcuni proxy rifiutano intestazioni non riconosciute. La variabile TRACEPARENT del sottoprocesso è controllata dallo stesso switch per coerenza. Se esegui Claude Code attraverso un proxy ANTHROPIC_BASE_URL personalizzato e desideri che il contesto di traccia sia propagato, imposta CLAUDE_CODE_PROPAGATE_TRACEPARENT=1.

In Agent SDK e sessioni non interattive avviate con -p, Claude Code legge anche TRACEPARENT e TRACESTATE dal proprio ambiente quando avvia ogni span di interazione. Ciò consente a un processo di incorporamento di passare il suo contesto di traccia W3C attivo nel sottoprocesso in modo che gli span di Claude Code appaiano come figli della traccia distribuita del chiamante. Le sessioni interattive ignorano TRACEPARENT in entrata per evitare di ereditare accidentalmente valori ambientali da ambienti CI o container.

Il contesto di traccia in entrata si applica anche agli eventi. In sessioni Agent SDK e -p con TRACEPARENT impostato, ogni record di log di evento OTLP porta valori trace_id e span_id che lo collegano alla traccia della tua applicazione, anche quando l'esportatore di tracce non è configurato, in modo che il tuo backend di logging possa correlare gli eventi con il resto della traccia.

Un record emesso mentre un'interazione è attiva porta gli ID dello span di interazione, anche quando Claude Code lo emette al di fuori del contesto asincrono dello span, come in un callback di prompt di autorizzazione o per un record memorizzato nel buffer durante l'avvio ed esportato in seguito. Un record emesso senza uno span di interazione attivo porta gli ID TRACEPARENT in entrata direttamente. Prima della v2.1.214, i record emessi al di fuori del contesto asincrono dello span portavano gli ID TRACEPARENT in entrata al posto degli ID dello span. Prima della v2.1.212, i record di evento emessi al di fuori di uno span attivo non portavano trace_id o span_id.

Gerarchia degli span

Ogni prompt dell'utente avvia uno span radice claude_code.interaction. Le chiamate API, le chiamate agli strumenti e le esecuzioni degli hook vengono registrate come suoi figli. Gli span degli strumenti hanno due span figli propri: uno per il tempo trascorso in attesa di una decisione di autorizzazione e uno per l'esecuzione stessa. Quando lo strumento Agent o lo strumento Task legacy genera un subagent, gli span API e degli strumenti del subagent si annidano sotto lo span claude_code.tool del genitore.

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (richiede traccia beta dettagliata)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Strumento Agent) span claude_code.llm_request / claude_code.tool del subagent

In Agent SDK e sessioni claude -p, claude_code.interaction stesso diventa un figlio dello span del chiamante quando TRACEPARENT è impostato nell'ambiente.

Quando un hook PreToolUse rinvia una chiamata dello strumento, Claude Code salva il contesto di traccia del turno che lo ha rinviato. Quando riprendi la sessione e lo strumento viene rieseguito, gli span dello strumento si uniscono alla traccia di quel turno precedente come figli dello span claude_code.interaction del turno.

Attributi degli span

Ogni span porta gli attributi standard più un attributo span.type che corrisponde al suo nome. Le tabelle seguenti elencano gli attributi aggiuntivi impostati su ogni span. Gli span llm_request, tool.execution, e hook impostano lo stato OpenTelemetry ERROR quando registrano un errore; gli altri span terminano sempre con stato UNSET.

claude_code.interaction

claude_code.llm_request

Ogni tentativo di ripetizione viene anche registrato come evento di span gen_ai.request.attempt con attributi attempt e client_request_id.

claude_code.tool

Quando OTEL_LOG_TOOL_CONTENT=1, questo span registra anche un evento di span tool.output i cui attributi contengono i corpi di input e output dello strumento, troncati al limite di contenuto (60 KB per impostazione predefinita) per attributo.

claude_code.tool.blocked_on_user

claude_code.tool.execution

claude_code.hook

Questo span viene emesso solo quando la traccia beta dettagliata è attiva, il che richiede ENABLE_BETA_TRACING_DETAILED=1 e BETA_TRACING_ENDPOINT, una coppia che inoltre cambia dove vanno i tuoi log e tracce. Imposta la coppia nella tua shell, nelle impostazioni utente o nelle impostazioni gestite; entrambe le variabili vengono ignorate nelle impostazioni di progetto e locali. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA da solo non lo produce.

Nelle sessioni CLI interattive, la traccia beta dettagliata richiede anche che la tua organizzazione sia nella lista di autorizzazione per la funzione. Le sessioni Agent SDK e non interattive -p non richiedono l'autorizzazione.

Intestazioni dinamiche

Per gli ambienti aziendali che richiedono autenticazione dinamica, puoi configurare uno script per generare intestazioni dinamicamente. Le intestazioni dinamiche si applicano solo ai protocolli http/protobuf e http/json. Con il protocollo grpc, Claude Code utilizza solo le variabili di intestazioni statiche, OTEL_EXPORTER_OTLP_HEADERS e i suoi varianti per segnale.

Configurazione delle impostazioni

Aggiungi al tuo .claude/settings.json, sostituendo il percorso con il tuo script:

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

Il valore può essere il percorso di un file eseguibile, incluso un percorso che contiene spazi, o una riga di comando della shell con argomenti. Su Windows, il valore viene sempre eseguito attraverso la shell, quindi racchiudi tra virgolette un percorso che contiene spazi all'interno del valore JSON.

Requisiti dello script

Lo script deve generare JSON valido con coppie chiave-valore di stringhe che rappresentano intestazioni HTTP:

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

Se l'helper non riesce o stampa output che non soddisfa questi requisiti, Claude Code segnala l'errore in:

• Output di /status
• Il log di debug, quando si esegue con --debug o dopo aver eseguito /debug nella sessione
• stderr, in sessioni non interattive avviate con -p

Comportamento di aggiornamento

Lo script dell'helper di intestazioni viene eseguito all'avvio e periodicamente in seguito per supportare l'aggiornamento dei token. Per impostazione predefinita, lo script viene eseguito ogni 29 minuti. Personalizza l'intervallo con la variabile di ambiente CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Supporto per organizzazioni multi-team

Le organizzazioni con più team o dipartimenti possono aggiungere attributi personalizzati per distinguere tra diversi gruppi utilizzando la variabile di ambiente OTEL_RESOURCE_ATTRIBUTES:

# Aggiungi attributi personalizzati per l'identificazione del team
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Questi attributi personalizzati verranno inclusi in tutte le metriche e gli eventi, permettendoti di:

• Filtrare le metriche per team o dipartimento
• Tracciare i costi per centro di costo
• Creare dashboard specifici per team
• Configurare avvisi per team specifici

Claude Code allega questi valori come attributi su ogni punto dati di metrica e record di evento, oltre a inviarli nel blocco di risorse OTLP. Poiché la maggior parte dei backend di metriche espone gli attributi dei punti dati come etichette interrogabili, puoi raggruppare e filtrare le metriche direttamente per le tue chiavi personalizzate. Le chiavi personalizzate non sostituiscono mai gli attributi standard come user.id o session.id: quando una chiave collide, Claude Code mantiene il valore integrato.

Ogni chiave personalizzata diventa un'etichetta su ogni serie di metriche, quindi i valori ad alta cardinalità aumentano il costo di archiviazione nel tuo backend di metriche. Per inviare attributi personalizzati solo nel blocco di risorse e ometterli dalle etichette dei punti dati, imposta OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. Vedi Controllo della cardinalità delle metriche.

Configurazioni di esempio

Imposta queste variabili di ambiente prima di eseguire claude. Ogni scenario seguente mostra una configurazione completa, e ogni variabile è descritta sotto Variabili di configurazione comuni. Per confermare che una configurazione ha avuto effetto, controlla il tuo backend per la metrica claude_code.session.count dopo aver avviato una sessione; la Guida rapida copre la verifica solo log e cosa controllare quando nulla arriva.

Per il debug della console con un intervallo di esportazione di 1 secondo:

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

Per OTLP su 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

Per Prometheus, raschiato da http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

Su un ambiente self-hosted, la sessione lega la porta 9464 solo alla capacità predefinita del runner di uno. A capacità superiore, il runner ri-espone i contatori e i gauge della sessione sul suo endpoint /metrics invece.

Per inviare metriche a più esportatori:

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

Per inviare metriche e log a endpoint o backend diversi:

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

Per esportare solo metriche, senza eventi o log:

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

Per esportare solo eventi e log, senza metriche:

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

Metriche e eventi disponibili

Attributi standard

Tutte le metriche e gli eventi condividono questi attributi standard:

Quando Claude Code è connesso a un gateway di app Claude, la CLI contrassegna le esportazioni con l'identità autenticata dalla sessione del gateway: user.id è il soggetto IdP piuttosto che un identificatore di installazione anonimo, user.email è l'email connessa, e user.groups contiene l'appartenenza al gruppo IdP come stringa separata da virgole. Ogni esportazione contiene anche identity.source: gateway-oidc. L'identità del gateway viene applicata per ultima, quindi le chiavi user.* e identity.* impostate tramite OTEL_RESOURCE_ATTRIBUTES vengono ignorate nelle sessioni del gateway.

Gli eventi includono inoltre i seguenti attributi. Questi non vengono mai allegati alle metriche perché causerebbero cardinalità illimitata:

• prompt.id: UUID che correla un prompt dell'utente con tutti gli eventi successivi fino al prompt successivo. Vedi Attributi di correlazione degli eventi.
• workspace.host_paths: directory dell'area di lavoro host selezionate nell'app desktop, come array di stringhe
• workflow.run_id: identificatore di esecuzione, con prefisso wf_, sugli eventi API e degli strumenti emessi da agenti che appartengono a un'esecuzione dello strumento Workflow. Filtrando gli eventi per un workflow.run_id si ricostruisce l'esecuzione delle richieste API e dei risultati degli strumenti. L'identificatore copre gli agenti che lo script del workflow genera e tutti gli agenti che questi generano a loro volta, come le invocazioni di skill. Corrisponde all'identificatore di esecuzione segnalato nel risultato dello strumento Workflow. Assente su tutti gli altri eventi. Richiede Claude Code v2.1.202 o successivo
• workflow.name: nome del workflow, il meta.name del suo script, emesso insieme a workflow.run_id. I nomi dei workflow incorporati vengono visualizzati così come sono quando l'esecuzione esegue lo script incorporato non modificato. I nomi creati dall'utente, incluse le copie modificate degli script incorporati, vengono sostituiti con custom a meno che OTEL_LOG_TOOL_DETAILS=1 non sia impostato. Richiede Claude Code v2.1.202 o successivo

Metriche

Claude Code esporta le seguenti metriche. La colonna Unit mostra la stringa di unità OpenTelemetry allegata a ogni metrica; le metriche di conteggio non ne hanno alcuna.

Quando prometheus è l'unico esportatore elencato in OTEL_METRICS_EXPORTER, Claude Code omette le unità USD, tokens, e s dalle metriche esportate in modo che lo scrape rimanga in formato testo Prometheus valido. I nomi delle metriche non cambiano, e le configurazioni che combinano esportatori, come otlp,prometheus, mantengono le unità. Prima della v2.1.216, lo scrape Prometheus includeva righe # UNIT solo OpenMetrics che alcuni scraper rifiutavano.

Dettagli delle metriche

Ogni metrica include gli attributi standard elencati sopra. Le metriche con attributi aggiuntivi specifici del contesto sono indicate di seguito.

Contatore di sessione

Incrementato all'inizio di ogni sessione.

Attributi:

• Tutti gli attributi standard
• start_type: Come la sessione è stata avviata. Uno di "fresh", "resume", "continue", o "agents_view". Il valore "agents_view" identifica il processo della dashboard claude agents, un'interfaccia utente locale avviata dall'utente piuttosto che una sessione conversazionale. Filtra su questo valore per separare i lanci del processo UI dalle sessioni conversazionali nei tuoi dashboard.

Contatore di righe di codice

Incrementato quando il codice viene aggiunto o rimosso.

Attributi:

• Tutti gli attributi standard
• type: ("added", "removed")
• model: Identificatore del modello per il modello che ha effettuato la modifica (ad esempio, "claude-sonnet-5")

Contatore di pull request

Incrementato quando Claude Code crea una pull request o merge request tramite un comando shell o uno strumento MCP.

Attributi:

• Tutti gli attributi standard

Contatore di commit

Incrementato quando si creano commit git tramite Claude Code.

Attributi:

• Tutti gli attributi standard

Contatore di costo

Incrementato dopo ogni richiesta API.

Attributi:

• Tutti gli attributi standard
• model: Identificatore del modello (ad esempio, "claude-sonnet-5")
• query_source: Categoria del sottosistema che ha emesso la richiesta. Uno di "main", "subagent", o "auxiliary"
• speed: "fast" quando la richiesta ha utilizzato la modalità veloce. Assente altrimenti
• effort: Livello di sforzo applicato alla richiesta: "low", "medium", "high", "xhigh", o "max". Assente quando il modello non supporta lo sforzo.
• agent.name: Tipo di subagent che ha emesso la richiesta. I nomi degli agenti incorporati e i nomi degli agenti dai plugin del marketplace ufficiale vengono visualizzati così come sono. Gli altri nomi degli agenti definiti dall'utente vengono sostituiti con "custom". Assente quando la richiesta non è stata emessa da un tipo di subagent denominato.
• skill.name: Skill attiva per la richiesta, impostata dallo strumento Skill, da un comando /, o ereditata da un subagent generato. I nomi delle skill incorporate, in bundle, definite dall'utente e dei plugin del marketplace ufficiale vengono visualizzati così come sono. I nomi delle skill dei plugin di terze parti vengono sostituiti con "third-party". Assente quando nessuna skill è attiva.
• plugin.name: Plugin proprietario quando la skill attiva o il subagent è fornito da un plugin. I nomi dei plugin del marketplace ufficiale vengono visualizzati così come sono. I nomi dei plugin di terze parti vengono sostituiti con "third-party". Assente quando né la skill né il subagent hanno un plugin proprietario.
• marketplace.name: Marketplace da cui è stato installato il plugin proprietario. Emesso solo per i plugin del marketplace ufficiale. Assente altrimenti.
• mcp_server.name: Server MCP il cui risultato dello strumento questa richiesta ha consumato. I nomi dei server incorporati, proxy di claude.ai, e del registro ufficiale vengono visualizzati così come sono. I nomi dei server configurati dall'utente vengono sostituiti con "custom". Assente quando la richiesta non ha consumato alcun risultato dello strumento MCP. Prima della v2.1.222, Claude Code impostava questo attributo su ogni richiesta dopo una chiamata dello strumento MCP, non solo su richieste che hanno consumato un risultato dello strumento, quindi i dashboard che lo aggregano mostrano un calo dopo l'aggiornamento.
• mcp_tool.name: Strumento MCP il cui risultato questa richiesta ha consumato, con lo stesso comportamento di oscuramento e di versione di mcp_server.name. Assente quando la richiesta non ha consumato alcun risultato dello strumento MCP.

Contatore di token

Incrementato dopo ogni richiesta API.

Attributi:

• Tutti gli attributi standard
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Identificatore del modello (ad esempio, "claude-sonnet-5")
• query_source: Categoria del sottosistema che ha emesso la richiesta. Uno di "main", "subagent", o "auxiliary"
• speed: "fast" quando la richiesta ha utilizzato la modalità veloce. Assente altrimenti
• effort: Livello di sforzo applicato alla richiesta. Vedi Contatore di costo per i dettagli.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Attribuzione di skill, plugin, agente e MCP per la richiesta. Vedi Contatore di costo per le definizioni e il comportamento di oscuramento.

Contatore di decisione dello strumento di modifica del codice

Incrementato quando l'utente accetta o rifiuta l'utilizzo dello strumento Edit, Write o NotebookEdit.

Attributi:

• Tutti gli attributi standard
• tool_name: Nome dello strumento ("Edit", "Write", "NotebookEdit")
• decision: Decisione dell'utente ("accept", "reject")
• source: Fonte della decisione. Uno di "config", "hook", "user_permanent", "user_temporary", "user_abort", o "user_reject". Vedi l'Evento di decisione dello strumento per il significato di ogni valore.
• language: Linguaggio di programmazione del file modificato, come "TypeScript", "Python", "JavaScript", o "Markdown". Restituisce "unknown" per estensioni di file non riconosciute.

Contatore di tempo attivo

Traccia il tempo effettivo trascorso utilizzando attivamente Claude Code, escludendo il tempo di inattività. Questa metrica viene incrementata durante le interazioni dell'utente, come la digitazione e la lettura delle risposte, e durante l'elaborazione CLI, come l'esecuzione degli strumenti e la generazione della risposta AI.

Attributi:

• Tutti gli attributi standard
• type: "user" per le interazioni da tastiera, "cli" per l'esecuzione degli strumenti e le risposte AI

Eventi

Claude Code esporta i seguenti eventi tramite log/eventi OpenTelemetry (quando OTEL_LOGS_EXPORTER è configurato):

Attributi di correlazione degli eventi

Quando un utente invia un prompt, Claude Code potrebbe effettuare più chiamate API ed eseguire diversi strumenti. L'attributo prompt.id ti consente di collegare tutti questi eventi al singolo prompt che li ha attivati.

Per tracciare tutta l'attività attivata da un singolo prompt, filtra i tuoi eventi per un valore specifico di prompt.id. Questo restituisce l'evento user_prompt, eventuali eventi api_request, e eventuali eventi tool_result che si sono verificati durante l'elaborazione di quel prompt.

Per la ricostruzione a livello di messaggio, ogni classe di evento porta una chiave che corrisponde a un campo nella trascrizione della sessione. Il formato della voce della trascrizione è interno a Claude Code e cambia tra le versioni, quindi una pipeline che si unisce su questi campi può rompersi in qualsiasi rilascio; tratta gli join come specifici della versione piuttosto che come un contratto stabile:

• message.uuid su user_prompt e assistant_response
• request_id sugli eventi API, persistito come requestId sulle voci dell'assistente della trascrizione
• tool_use_id su tool_result e tool_decision eventi

Evento di prompt dell'utente

Registrato quando un utente invia un prompt.

Nome evento: claude_code.user_prompt

Attributi:

• Tutti gli attributi standard
• event.name: "user_prompt"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• prompt_length: Lunghezza del prompt
• prompt: Contenuto del prompt. Oscurato per impostazione predefinita. Imposta OTEL_LOG_USER_PROMPTS=1 per includerlo
• message.uuid: UUID del messaggio utente risultante, corrispondente alla voce della trascrizione persistente. Assente nei dispatching dei comandi, che possono produrre zero o molti messaggi. Richiede Claude Code v2.1.214 o successivo
• command_name: Nome del comando quando il prompt ne invoca uno. I nomi dei comandi incorporati e in bundle come compact o debug vengono emessi così come sono; gli alias come reset vengono emessi come digitati piuttosto che il nome canonico. I nomi dei comandi personalizzati, plugin e MCP si riducono a custom o mcp a meno che OTEL_LOG_TOOL_DETAILS=1 non sia impostato
• command_source: Origine del comando quando presente: builtin, custom, o mcp. I comandi forniti dai plugin vengono segnalati come custom

Evento di risposta dell'assistente

Registrato dopo ogni richiesta API che restituisce contenuto di testo dal modello. Solo i blocchi di testo della risposta sono inclusi; i blocchi di pensiero e i blocchi di utilizzo dello strumento sono esclusi. Richiede Claude Code v2.1.193 o successivo.

Nome evento: claude_code.assistant_response

Attributi:

• Tutti gli attributi standard
• event.name: "assistant_response"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• response_length: Lunghezza del testo della risposta in caratteri
• response: Testo della risposta, troncato al limite di contenuto (60 KB per impostazione predefinita). Sostituito con <REDACTED> per impostazione predefinita. Imposta OTEL_LOG_ASSISTANT_RESPONSES=1 per includerlo. Quando OTEL_LOG_ASSISTANT_RESPONSES non è impostato, OTEL_LOG_USER_PROMPTS lo controlla invece, quindi imposta OTEL_LOG_ASSISTANT_RESPONSES=0 per mantenere le risposte oscurate mentre la registrazione dei prompt è attiva
• model: Identificatore del modello (ad esempio, "claude-sonnet-5")
• request_id: ID della richiesta API Anthropic dall'intestazione request-id della risposta. Presente solo quando l'API ne restituisce uno
• message.uuid: UUID della voce della trascrizione finale della risposta. Una risposta API viene persistita come una voce della trascrizione per blocco di contenuto; questa è l'ultima, da cui la parentUuid del turno successivo si collega. Richiede Claude Code v2.1.214 o successivo
• query_source: Sottosistema che ha emesso la richiesta, come "repl_main_thread", "compact", o un nome di subagent

Evento di risultato dello strumento

Registrato quando uno strumento completa l'esecuzione. Non emesso se la chiamata dello strumento è stata rifiutata; vedi l'Evento di decisione dello strumento per i rifiuti.

Nome evento: claude_code.tool_result

Attributi:

• Tutti gli attributi standard
• event.name: "tool_result"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• tool_name: Nome dello strumento
• tool_use_id: Identificatore univoco per questa invocazione dello strumento. Corrisponde al tool_use_id passato agli hooks, consentendo la correlazione tra gli eventi OTel e i dati acquisiti dagli hooks.
• success: "true" o "false"
• duration_ms: Tempo di esecuzione in millisecondi
• error_type: Stringa di categoria di errore quando lo strumento non è riuscito, come "Error:ENOENT" o "ShellError"
• error (quando OTEL_LOG_TOOL_DETAILS=1): Messaggio di errore completo quando lo strumento non è riuscito
• decision_type: Sempre "accept", poiché questo evento viene emesso solo dopo l'esecuzione dello strumento. Le chiamate rifiutate non producono un risultato dello strumento
• decision_source: Fonte della decisione di autorizzazione. Uno di "config", "hook", "user_permanent", o "user_temporary". Vedi l'Evento di decisione dello strumento per il significato di ogni valore. Le fonti solo per il rifiuto "user_abort" e "user_reject" non compaiono mai su questo evento.
• tool_input_size_bytes: Dimensione dell'input dello strumento serializzato in JSON in byte
• tool_result_size_bytes: Dimensione del risultato dello strumento in byte
• mcp_server_scope: Identificatore dell'ambito del server MCP (per gli strumenti MCP)
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): Stringa JSON contenente parametri specifici dello strumento. Per i server incorporati di Claude Desktop, nelle sessioni che Claude Desktop possiede, la coppia mcp_server_name/mcp_tool_name è inclusa anche con il flag disattivato, la stessa eccezione creata dall'host dell'Evento di decisione dello strumento, richiedendo Claude Code v2.1.214 o successivo. I parametri variano per strumento:
  • Per lo strumento Bash: include bash_command, full_command, timeout, description, dangerouslyDisableSandbox, e git_commit_id (lo SHA del commit, quando un comando git commit ha successo). Lo strumento bash dell'area di lavoro dell'app desktop segnala anche tool_name come Bash, ma include solo bash_command, full_command, e timeout
  • Per gli strumenti MCP: include mcp_server_name, mcp_tool_name
  • Per lo strumento Skill: include skill_name
  • Per lo strumento Agent o lo strumento Task legacy: include subagent_type
• tool_input (quando OTEL_LOG_TOOL_DETAILS=1): Argomenti dello strumento serializzati in JSON. I singoli valori superiori a 512 caratteri vengono troncati, e il payload completo è limitato a circa 4 K caratteri. Si applica a tutti gli strumenti inclusi gli strumenti MCP.

Evento di richiesta API

Registrato per ogni richiesta API a Claude.

Nome evento: claude_code.api_request

Attributi:

• Tutti gli attributi standard
• event.name: "api_request"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• model: Modello utilizzato (ad esempio, "claude-sonnet-5")
• cost_usd: Costo stimato in USD
• cost_usd_micros: Costo stimato in milionesimi di dollaro USA, emesso come numero intero
• duration_ms: Durata della richiesta in millisecondi
• input_tokens: Numero di token di input
• output_tokens: Numero di token di output
• cache_read_tokens: Numero di token letti dalla cache
• cache_creation_tokens: Numero di token utilizzati per la creazione della cache
• request_id: ID della richiesta API Anthropic dall'intestazione request-id della risposta, come "req_011...". Presente solo quando l'API ne restituisce uno.
• client_request_id: UUID generato dal client inviato come intestazione della richiesta x-client-request-id; vedi la tabella attributi di correlazione degli eventi per quando è presente. Richiede Claude Code v2.1.214 o successivo
• speed: "fast" o "normal", indicando se la modalità veloce era attiva
• query_source: Sottosistema che ha emesso la richiesta, come "repl_main_thread", "compact", o un nome di subagent
• effort: Livello di sforzo applicato alla richiesta: "low", "medium", "high", "xhigh", o "max". Assente quando il modello non supporta lo sforzo.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Attribuzione di skill, plugin, agente e MCP per la richiesta. Vedi Contatore di costo per le definizioni e il comportamento di oscuramento.

Evento di errore API

Registrato quando una richiesta API a Claude non riesce.

Nome evento: claude_code.api_error

Attributi:

• Tutti gli attributi standard
• event.name: "api_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• model: Modello utilizzato (ad esempio, "claude-sonnet-5")
• error: Messaggio di errore
• status_code: Codice di stato HTTP come numero. Assente per errori non-HTTP come i guasti di connessione.
• duration_ms: Durata della richiesta in millisecondi
• attempt: Numero totale di tentativi effettuati, inclusa la richiesta iniziale (1 significa che non si sono verificati tentativi)
• request_id: ID della richiesta API Anthropic dall'intestazione request-id della risposta, come "req_011...". Presente solo quando l'API ne restituisce uno.
• client_request_id: UUID generato dal client inviato come intestazione della richiesta x-client-request-id. Disponibile anche quando un guasto come un timeout o un errore di connessione non ha mai prodotto un request_id del server; vedi la tabella attributi di correlazione degli eventi per quando è presente. Richiede Claude Code v2.1.214 o successivo
• speed: "fast" o "normal", indicando se la modalità veloce era attiva
• query_source: Sottosistema che ha emesso la richiesta, come "repl_main_thread", "compact", o un nome di subagent
• effort: Livello di sforzo applicato alla richiesta. Assente quando il modello non supporta lo sforzo.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Attribuzione di skill, plugin, agente e MCP per la richiesta. Vedi Contatore di costo per le definizioni e il comportamento di oscuramento.

Evento di rifiuto API

Registrato quando una richiesta API restituisce stop_reason: "refusal". I rifiuti arrivano su un flusso di risposta riuscito piuttosto che come errore HTTP, quindi l'evento api_error non si attiva per loro. Questo evento ti consente di tracciare la frequenza dei rifiuti e raggruppare i rifiuti per gli stessi attributi di api_request e api_error.

Nome evento: claude_code.api_refusal

Attributi:

• Tutti gli attributi standard
• event.name: "api_refusal"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• model: Identificatore del modello dalla richiesta
• request_id: ID della richiesta API Anthropic dall'intestazione request-id della risposta, come "req_011...". Presente solo quando l'API ne restituisce uno.
• query_source: Sottosistema che ha emesso la richiesta, come "repl_main_thread", "compact", o un nome di subagent. Vedi api_request per le definizioni.
• speed: "fast" quando Fast mode è attivo, o "normal"
• attempt: Numero del tentativo di ripetizione. Il primo tentativo è 1.
• effort: Livello di sforzo applicato alla richiesta. Assente quando il modello non supporta lo sforzo.
• server_fallback_hop: true quando il fallback del modello lato server dell'API ha già ritentato questo rifiuto su un modello diverso, quindi l'utente non ha visto questo particolare rifiuto. false quando la richiesta è terminata in un rifiuto. Un singolo turno può emettere sia un evento hop true che un successivo evento finale false quando il modello di fallback rifiuta anche.
• has_category: true quando la risposta API ha portato una stop_details.category di "cyber", "bio", "frontier_llm", o "reasoning_extraction". false quando la risposta non ha portato alcuna categoria o un valore al di fuori di quel set. Assente quando server_fallback_hop è true, perché i blocchi hop non portano stop_details.
• has_explanation: true quando la risposta API ha portato una stop_details.explanation, altrimenti false. Assente quando server_fallback_hop è true.
• category: Il valore stop_details.category dalla risposta API. Uno di "cyber", "bio", "frontier_llm", o "reasoning_extraction". Presente solo quando OTEL_LOG_TOOL_DETAILS=1 è impostato e has_category è true.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Attribuzione di skill, plugin, agente e MCP per la richiesta. Vedi Contatore di costo per le definizioni e il comportamento di oscuramento.

Evento di corpo della richiesta API

Registrato per ogni tentativo di richiesta API quando OTEL_LOG_RAW_API_BODIES è impostato. Un evento viene emesso per tentativo, quindi i tentativi con parametri regolati producono ciascuno il proprio evento.

Nome evento: claude_code.api_request_body

Attributi:

• Tutti gli attributi standard
• event.name: "api_request_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• body: Parametri della richiesta dell'API Messages serializzati in JSON, come il prompt di sistema, i messaggi e gli strumenti, troncati al limite di contenuto (60 KB per impostazione predefinita). Il contenuto del pensiero esteso nei turni precedenti dell'assistente viene oscurato. Emesso solo in modalità inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Percorso assoluto a un file <dir>/<uuid>.request.json contenente il corpo non troncato. Emesso solo in modalità file (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Lunghezza del corpo non troncato. Byte UTF-8 quando OTEL_LOG_RAW_API_BODIES=file:<dir>, o unità di codice UTF-16 quando =1
• body_truncated: "true" quando si è verificato il troncamento inline. Assente in modalità file e quando non si è verificato alcun troncamento.
• model: Identificatore del modello dai parametri della richiesta
• query_source: Sottosistema che ha emesso la richiesta (ad esempio, "compact")

Evento di corpo della risposta API

Registrato per ogni risposta API riuscita quando OTEL_LOG_RAW_API_BODIES è impostato.

Nome evento: claude_code.api_response_body

Attributi:

• Tutti gli attributi standard
• event.name: "api_response_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• body: Risposta dell'API Messages serializzata in JSON, inclusi l'id, i blocchi di contenuto, l'utilizzo e il motivo di arresto, troncata al limite di contenuto (60 KB per impostazione predefinita). Il contenuto del pensiero esteso viene oscurato. Emesso solo in modalità inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Percorso assoluto a un file <dir>/<request_id>.response.json contenente il corpo non troncato. Emesso solo in modalità file (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Lunghezza del corpo non troncato. Byte UTF-8 quando OTEL_LOG_RAW_API_BODIES=file:<dir>, o unità di codice UTF-16 quando =1
• body_truncated: "true" quando si è verificato il troncamento inline. Assente in modalità file e quando non si è verificato alcun troncamento.
• model: Identificatore del modello
• query_source: Sottosistema che ha emesso la richiesta
• request_id: ID della richiesta API Anthropic dall'intestazione request-id della risposta, come "req_011...". Presente solo quando l'API ne restituisce uno.

Evento di decisione dello strumento

Registrato quando viene presa una decisione di autorizzazione dello strumento (accetta/rifiuta).

Nome evento: claude_code.tool_decision

Attributi:

• Tutti gli attributi standard
• event.name: "tool_decision"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• tool_name: Nome dello strumento (ad esempio, "Read", "Edit", "Write", "NotebookEdit")
• tool_use_id: Identificatore univoco per questa invocazione dello strumento. Corrisponde al tool_use_id passato agli hooks, consentendo la correlazione tra gli eventi OTel e i dati acquisiti dagli hooks.
• decision: "accept" o "reject"
• tool_source: Sempre presente. La provenienza dello strumento, come un insieme chiuso di valori creati dalla CLI. Richiede Claude Code v2.1.214 o successivo
  • "builtin": gli strumenti della CLI stessa
  • "mcp": server MCP in generale
  • "sdk_host_builtin_mcp": un server in-process incorporato in Claude Desktop stesso, in una sessione che Claude Desktop possiede. Claude Desktop possiede una sessione che ha avviato da uno dei suoi propri punti di ingresso, claude-desktop, claude-desktop-3p, o local-agent, quando quella sessione non è un figlio annidato; le sessioni annidate, incluse le sessioni che Claude Code stesso genera, segnalano questi server come "mcp"
• source: Fonte della decisione:
  • "config": Deciso automaticamente senza richiedere, in base alle impostazioni del progetto, alle regole di autorizzazione nelle impostazioni personali dell'utente, alla politica gestita dall'azienda, ai flag --allowedTools o --disallowedTools, alla modalità di autorizzazione attiva, a una concessione con ambito di sessione da un prompt precedente nella stessa sessione CLI interattiva, o perché lo strumento è intrinsecamente sicuro. L'evento non indica quale di queste fonti corrisponde. Claude Code segnala anche "config" quando la richiesta del prompt di autorizzazione stessa non riesce, ad esempio quando il callback canUseTool dell'Agent SDK o lo strumento --permission-prompt-tool restituisce un risultato non valido, o quando il flusso di input si chiude mentre la richiesta è in sospeso. Prima della v2.1.216, Claude Code segnalava questi guasti come "user_reject".
  • "hook": Un hook PreToolUse o PermissionRequest ha restituito la decisione.
  • "user_permanent": Emesso quando l'utente ha scelto "Sì, e non chiedere di nuovo per ..." in un prompt di autorizzazione, il che salva una regola di autorizzazione alle sue impostazioni personali. Nella CLI interattiva questo viene emesso solo per quella scelta stessa; le chiamate successive che corrispondono alla regola salvata emettono "config" invece. Nelle sessioni Agent SDK o non interattive -p, sia la scelta iniziale che le corrispondenze di regole successive emettono "user_permanent". Trattato come un'accettazione.
  • "user_temporary": Emesso quando l'utente ha scelto "Sì" in un prompt di autorizzazione per un'approvazione una tantum, o ha scelto un'opzione che concede l'accesso per il resto della sessione in un prompt di modifica o lettura di file. Nella CLI interattiva questo viene emesso solo per la scelta stessa; le chiamate successive consentite da quella concessione con ambito di sessione emettono "config" invece. Nelle sessioni Agent SDK o non interattive -p, sia la scelta che le corrispondenze successive emettono "user_temporary". Trattato come un'accettazione.
  • "user_abort": Emesso quando l'utente ha chiuso il prompt di autorizzazione senza rispondere. Nelle sessioni Agent SDK e non interattive -p, questo include l'interruzione del turno mentre una richiesta di autorizzazione canUseTool o --permission-prompt-tool è in sospeso; prima della v2.1.216, Claude Code segnalava quell'interruzione come "user_reject". Trattato come un rifiuto.
  • "user_reject": Emesso quando l'utente ha scelto "No" quando richiesto. Nella CLI interattiva questo viene emesso solo per quella scelta stessa; le chiamate che corrispondono a una regola di negazione nelle impostazioni personali dell'utente emettono "config" invece. Nelle sessioni Agent SDK o non interattive -p, le chiamate che corrispondono a una regola di negazione nelle impostazioni personali emettono "user_reject". Trattato come un rifiuto.
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): Stringa JSON contenente parametri specifici dello strumento. Stessa forma dell'Evento di risultato dello strumento, meno i campi post-esecuzione come git_commit_id. I valori possono differire da tool_result per una chiamata accettata se la decisione di autorizzazione riscrive l'input dello strumento tramite updatedInput. Usa questo attributo per vedere quale comando è stato rifiutato quando decision è "reject".
  • Per gli strumenti "sdk_host_builtin_mcp": mcp_server_name e mcp_tool_name sono inclusi anche quando OTEL_LOG_TOOL_DETAILS è disattivato, perché l'applicazione host definisce questi nomi; senza di loro, una chiamata rifiutata a uno di questi server incorporati sarebbe non attribuibile nel flusso predefinito. Per i server MCP configurati dall'utente, il tool_name dell'evento è sempre il letterale "mcp_tool", e i nomi del server e dello strumento appaiono solo in tool_parameters con il flag attivato; il contenuto dell'argomento richiede il flag ovunque. Richiede Claude Code v2.1.214 o successivo
  • Per lo strumento Bash: include bash_command, full_command, timeout, description, dangerouslyDisableSandbox. Lo strumento bash dell'area di lavoro dell'app desktop segnala anche tool_name come Bash, ma include solo bash_command, full_command, e timeout
  • Per gli strumenti MCP: include mcp_server_name, mcp_tool_name
  • Per lo strumento Skill: include skill_name
  • Per lo strumento Agent o lo strumento Task legacy: include subagent_type

Evento di cambio della modalità di autorizzazione

Registrato quando la modalità di autorizzazione cambia, ad esempio da ciclo Shift+Tab, uscita dalla Plan Mode, o un controllo del gate della modalità automatica.

Nome evento: claude_code.permission_mode_changed

Attributi:

• Tutti gli attributi standard
• event.name: "permission_mode_changed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• from_mode: La modalità di autorizzazione precedente, ad esempio "default", "plan", "acceptEdits", "auto", o "bypassPermissions"
• to_mode: La nuova modalità di autorizzazione
• trigger: Cosa ha causato il cambio. Uno di "shift_tab", "exit_plan_mode", "auto_gate_denied", o "auto_opt_in". Assente quando la transizione proviene dall'SDK o dal bridge

Evento di autenticazione

Registrato quando /login o /logout si completa.

Nome evento: claude_code.auth

Attributi:

• Tutti gli attributi standard
• event.name: "auth"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• action: "login" o "logout"
• success: "true" o "false"
• auth_method: Metodo di autenticazione, come "oauth"
• error_category: Tipo di errore categorico quando l'azione non è riuscita. Il messaggio di errore grezzo non viene mai incluso
• status_code: Codice di stato HTTP come stringa quando l'azione non è riuscita con un errore HTTP

Evento di connessione del server MCP

Registrato quando un server MCP si connette, si disconnette o non riesce a connettersi.

Nome evento: claude_code.mcp_server_connection

Attributi:

• Tutti gli attributi standard
• event.name: "mcp_server_connection"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• status: "connected", "failed", o "disconnected"
• transport_type: Trasporto del server, come "stdio", "sse", o "http"
• server_scope: Ambito in cui il server è configurato, come "user", "project", o "local"
• duration_ms: Durata del tentativo di connessione in millisecondi
• error_code: Codice di errore quando la connessione non è riuscita
• is_plugin: true quando il server è fornito da un plugin, false altrimenti
• plugin_id_hash (quando is_plugin è true): Hash stabile del nome del plugin e del marketplace, per raggruppare gli eventi per plugin senza esporre il nome. Claude Code lo calcola come descritto nell'evento di plugin caricato
• plugin.name (quando is_plugin è true): Nome del plugin che fornisce il server. Per i plugin di terze parti questo è la stringa letterale "third-party" a meno che OTEL_LOG_TOOL_DETAILS=1; questo protegge i nomi dei plugin di terze parti dall'apparire nei log per impostazione predefinita. I plugin da fonti ufficiali Anthropic sono sempre identificati per nome. Gli attributi plugin_id_hash e plugin.name fluiscono al tuo backend di monitoraggio e non vengono inviati ad Anthropic
• server_name (quando OTEL_LOG_TOOL_DETAILS=1): Nome del server configurato
• error (quando OTEL_LOG_TOOL_DETAILS=1): Messaggio di errore completo quando la connessione non è riuscita

Evento di errore interno

Registrato quando Claude Code cattura un errore interno inaspettato. Viene registrato solo il nome della classe di errore e un codice di stile errno. Il messaggio di errore e la traccia dello stack non vengono mai inclusi. Questo evento non viene emesso quando si esegue su Amazon Bedrock, Google Cloud's Agent Platform, o Microsoft Foundry, o quando DISABLE_ERROR_REPORTING è impostato.

Nome evento: claude_code.internal_error

Attributi:

• Tutti gli attributi standard
• event.name: "internal_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• error_name: Nome della classe di errore, come "TypeError" o "SyntaxError"
• error_code: Codice errno di Node.js come "ENOENT" quando presente nell'errore

Evento di plugin installato

Registrato quando un plugin finisce di installarsi, sia dal comando CLI claude plugin install che dall'interfaccia utente interattiva /plugin.

Nome evento: claude_code.plugin_installed

Attributi:

• Tutti gli attributi standard
• event.name: "plugin_installed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• marketplace.is_official: "true" se il marketplace è un marketplace ufficiale Anthropic, "false" altrimenti
• install.trigger: "cli" o "ui"
• plugin.name: Nome del plugin installato. Per i marketplace di terze parti questo è incluso solo quando OTEL_LOG_TOOL_DETAILS=1
• plugin.version: Versione del plugin quando dichiarata nella voce del marketplace. Per i marketplace di terze parti questo è incluso solo quando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace da cui è stato installato il plugin. Per i marketplace di terze parti questo è incluso solo quando OTEL_LOG_TOOL_DETAILS=1

Evento di plugin caricato

Registrato una volta per ogni plugin abilitato all'avvio della sessione. Usa questo evento per inventariare quali plugin sono attivi nella tua flotta, come complemento a plugin_installed che registra l'azione di installazione stessa.

Nome evento: claude_code.plugin_loaded

Attributi:

• Tutti gli attributi standard
• event.name: "plugin_loaded"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• plugin.name: Nome del plugin. Per i plugin al di fuori del marketplace ufficiale e del bundle incorporato il valore è "third-party" a meno che OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace da cui è stato installato il plugin, quando noto. Sostituito con "third-party" nella stessa condizione di plugin.name
• plugin.version: Versione dal manifesto del plugin. Incluso solo quando il nome non è oscurato e il manifesto dichiara una versione
• plugin.scope: Categoria di provenienza per il plugin: "official", "community", "org", "user-local", o "default-bundle"
• enabled_via: Come il plugin è stato abilitato: "default-enable", "org-policy", "admin-install", "seed-mount", o "user-install". Il valore "admin-install" significa che il plugin è impostato come obbligatorio o auto-installazione per la tua organizzazione in Impostazioni organizzazione > Plugin. Prima della v2.1.246, Claude Code segnalava questi plugin come "user-install" o "seed-mount"
• plugin_id_hash: Hash deterministico del nome del plugin e del marketplace, inviato solo al tuo esportatore configurato. Ti consente di contare i plugin di terze parti distinti caricati nella tua flotta senza registrare i loro nomi. Per i plugin sincronizzati da claude.ai, Claude Code esegue l'hash del nome del plugin con il nome del marketplace che claude.ai segnala per il plugin, o con synced altrimenti. Prima della v2.1.246, Claude Code non utilizzava il nome del marketplace che claude.ai segnala nell'hash
• has_hooks: Se il plugin contribuisce hooks
• has_mcp: Se il plugin contribuisce server MCP
• host_owned_mcp: true quando l'host SDK gestisce le connessioni MCP di questo plugin e Claude Code ha saltato la lettura della configurazione del server MCP del plugin, false altrimenti. Richiede Claude Code v2.1.172 o successivo
• skill_path_count: Numero di directory di skill che il plugin dichiara
• command_path_count: Numero di directory di comandi che il plugin dichiara
• agent_path_count: Numero di directory di agenti che il plugin dichiara
• safe_mode: "true" quando la sessione è stata avviata con --safe-mode, "false" altrimenti. In modalità sicura questo evento segnala solo l'inventario configurato; i comandi, le skill, gli hooks e i server MCP del plugin non si caricano. Richiede Claude Code v2.1.169 o successivo

Evento di skill attivata

Registrato quando una skill viene invocata, sia che Claude la chiami tramite lo strumento Skill sia che tu la esegua come comando /.

Nome evento: claude_code.skill_activated

Attributi:

• Tutti gli attributi standard
• event.name: "skill_activated"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• skill.name: Nome della skill. Per le skill definite dall'utente e di terze parti il valore è il placeholder "custom_skill" a meno che OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger: Come la skill è stata attivata ("user-slash", "claude-proactive", o "nested-skill")
• skill.source: Da dove è stata caricata la skill (ad esempio, "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind: "workflow" quando la skill è una skill di workflow. Assente altrimenti
• plugin.name (quando OTEL_LOG_TOOL_DETAILS=1 o il plugin è da un marketplace ufficiale): Nome del plugin proprietario quando la skill è fornita da un plugin
• marketplace.name (quando OTEL_LOG_TOOL_DETAILS=1 o il plugin è da un marketplace ufficiale): Marketplace del plugin proprietario da cui è stato installato, quando la skill è fornita da un plugin

Evento di menzione @

Registrato quando Claude Code risolve una menzione @ in un prompt. Non ogni menzione emette un evento: i percorsi di uscita anticipata come i rifiuti di autorizzazione, i file di grandi dimensioni, gli allegati di riferimento PDF e i guasti dell'elenco delle directory vengono restituiti senza registrazione.

Nome evento: claude_code.at_mention

Attributi:

• Tutti gli attributi standard
• event.name: "at_mention"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• mention_type: Tipo di menzione ("file", "directory", "agent", "mcp_resource", "peer"). Il valore "peer" significa che hai menzionato una delle tue altre sessioni Claude Code. Richiede Claude Code v2.1.232 o successivo
• success: Se la menzione è stata risolta con successo ("true" o "false")

Evento di tentativi API esauriti

Registrato una volta quando una richiesta API non riesce dopo più di un tentativo. Emesso insieme all'evento api_error finale.

Nome evento: claude_code.api_retries_exhausted

Attributi:

• Tutti gli attributi standard
• event.name: "api_retries_exhausted"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• model: Modello utilizzato
• error: Messaggio di errore finale
• status_code: Codice di stato HTTP come numero. Assente per errori non-HTTP.
• total_attempts: Numero totale di tentativi effettuati
• total_retry_duration_ms: Tempo wall-clock totale tra tutti i tentativi
• speed: "fast" o "normal"

Evento di hook registrato

Registrato una volta per ogni hook configurato all'avvio della sessione. Usa questo evento per inventariare quali hook sono attivi nella tua flotta, come complemento agli eventi per esecuzione hook_execution_start e hook_execution_complete.

Nome evento: claude_code.hook_registered

Attributi:

• Tutti gli attributi standard
• event.name: "hook_registered"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• hook_event: Tipo di evento hook, come "PreToolUse" o "PostToolUse"
• hook_type: Tipo di implementazione dell'hook: "command", "prompt", "mcp_tool", "http", o "agent"
• hook_source: Dove è definito l'hook: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings", o "pluginHook"
• safe_mode: "true" quando la sessione è stata avviata con --safe-mode, "false" altrimenti. Richiede Claude Code v2.1.169 o successivo
• hook_matcher (quando OTEL_LOG_TOOL_DETAILS=1): La stringa matcher dalla configurazione dell'hook, quando è impostata
• plugin.name (quando hook_source è "pluginHook"): Nome del plugin che contribuisce. Per i plugin al di fuori del marketplace ufficiale e del bundle incorporato il valore è "third-party" a meno che OTEL_LOG_TOOL_DETAILS=1
• plugin_id_hash (quando hook_source è "pluginHook"): Hash deterministico del nome del plugin e del marketplace, inviato solo al tuo esportatore configurato. Ti consente di contare i plugin che contribuiscono distinti senza registrare i loro nomi. Claude Code lo calcola come descritto nell'evento di plugin caricato

Evento di inizio esecuzione dell'hook

Registrato quando uno o più hook iniziano a eseguirsi per un evento hook.

Nome evento: claude_code.hook_execution_start

Attributi:

• Tutti gli attributi standard
• event.name: "hook_execution_start"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• hook_event: Tipo di evento hook, come "PreToolUse" o "PostToolUse"
• hook_name: Nome completo dell'hook incluso il matcher, come "PreToolUse:Write"
• num_hooks: Numero di comandi hook corrispondenti
• managed_only: "true" quando sono consentiti solo gli hook della politica gestita
• hook_source: "policySettings" o "merged"
• safe_mode: "true" quando la sessione è stata avviata con --safe-mode, "false" altrimenti. Richiede Claude Code v2.1.169 o successivo
• hook_definitions: Configurazione dell'hook serializzata in JSON. Incluso solo quando sia la traccia beta dettagliata che OTEL_LOG_TOOL_DETAILS=1 sono abilitati

Evento di completamento esecuzione dell'hook

Registrato quando tutti gli hook per un evento hook hanno terminato.

Nome evento: claude_code.hook_execution_complete

Attributi:

• Tutti gli attributi standard
• event.name: "hook_execution_complete"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• hook_event: Tipo di evento hook
• hook_name: Nome completo dell'hook incluso il matcher
• num_hooks: Numero di comandi hook corrispondenti
• num_success: Conteggio che ha completato con successo
• num_blocking: Conteggio che ha restituito una decisione di blocco
• num_non_blocking_error: Conteggio che non ha avuto esito positivo senza bloccare
• num_cancelled: Conteggio annullato prima del completamento
• total_duration_ms: Durata wall-clock di tutti gli hook corrispondenti
• managed_only: "true" quando sono consentiti solo gli hook della politica gestita
• hook_source: "policySettings" o "merged"
• safe_mode: "true" quando la sessione è stata avviata con --safe-mode, "false" altrimenti. Richiede Claude Code v2.1.169 o successivo
• hook_definitions: Configurazione dell'hook serializzata in JSON. Incluso solo quando sia la traccia beta dettagliata che OTEL_LOG_TOOL_DETAILS=1 sono abilitati

Evento di metriche plugin hook

Registrato quando un hook plugin del marketplace ufficiale emette metriche per invocazione. Solo i plugin installati da un marketplace ufficiale Anthropic possono emettere questi. I plugin di marketplace di terze parti e gli hook configurati dall'utente non emettono a questo evento. Usa questo evento per monitorare il comportamento del plugin come i tassi di ricerca, i costi e le durate dal tuo stack di osservabilità.

Nome evento: claude_code.hook_plugin_metrics

Attributi:

• Tutti gli attributi standard
• event.name: "hook_plugin_metrics"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• plugin_id: Identificatore del plugin in forma <name>@<marketplace>
• hook_event: Tipo di evento hook che ha emesso le metriche
• Fino a 20 chiavi di metriche emesse dal plugin. I nomi corrispondono a ^[a-z][a-z0-9_]{0,39}$. I valori sono booleani o numeri.

Evento di compattazione

Registrato quando la compattazione della conversazione si completa.

Nome evento: claude_code.compaction

Attributi:

• Tutti gli attributi standard
• event.name: "compaction"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• trigger: "auto" o "manual"
• success: "true" o "false"
• duration_ms: Durata della compattazione
• pre_tokens: Conteggio approssimativo dei token prima della compattazione
• post_tokens: Conteggio approssimativo dei token dopo la compattazione
• error: Messaggio di errore quando la compattazione non è riuscita
• precompute_reuse: Impostato solo quando trigger è "manual". La compattazione automatica può preparare un riepilogo in background prima che la finestra di contesto si riempia, e questo attributo registra se /compact ha riutilizzato quel riepilogo preparato. "hit" significa che è stato riutilizzato; "miss_custom_instructions", "miss_hook", e "miss_not_ready" forniscono il motivo per cui è stato calcolato un riepilogo fresco. Richiede Claude Code v2.1.153 o successivo

Evento di subagent completato

Registrato quando un subagent finisce e restituisce il suo risultato alla conversazione che lo ha avviato. Usalo per aggregare l'utilizzo dello strumento e il tempo di esecuzione per tipo di subagent; per aggregazioni di token o costo, usa il contatore di token e il contatore di costo filtrati a query_source "subagent", poiché il total_tokens di questo evento copre solo la richiesta finale. La categoria "subagent" conta anche le richieste dagli hook basati su agenti, che non emettono alcun evento di subagent.

Nome evento: claude_code.subagent_completed

Attributi:

• Tutti gli attributi standard
• event.name: "subagent_completed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• agent_type: Il tipo di subagent. I nomi degli agenti incorporati e i nomi degli agenti dai plugin del marketplace ufficiale vengono visualizzati così come sono; gli altri nomi degli agenti vengono sostituiti con "custom" a meno che OTEL_LOG_TOOL_DETAILS=1 non sia impostato
• agent.source: Da dove proviene la definizione dell'agente: built-in, plugin, o la fonte di impostazioni che ha definito un agente personalizzato, come userSettings o projectSettings
• is_built_in: Se il subagent è un tipo di agente incorporato
• is_async: Se il subagent è stato eseguito in background
• total_tokens: L'impronta di token della richiesta API finale del subagent: i token di input, creazione della cache, lettura della cache e output di quella richiesta, approssimativamente la dimensione del contesto del subagent al completamento. Non una somma nell'intera esecuzione
• total_tool_uses: Numero di chiamate dello strumento che il subagent ha effettuato nell'intera esecuzione
• duration_ms: Tempo di esecuzione in millisecondi
• model: Il modello in cui il subagent è stato risolto per l'esecuzione
• final_model: Il modello che ha prodotto la risposta finale del subagent, che differisce da model dopo un cambio a metà esecuzione come un fallback. Richiede Claude Code v2.1.212 o successivo
• model_swapped: Se più di un modello ha servito le richieste del subagent. Richiede Claude Code v2.1.212 o successivo
• plugin_id_hash, plugin.name: Presente per gli agenti forniti da plugin. I nomi dei plugin del marketplace ufficiale vengono visualizzati così come sono; gli altri nomi dei plugin vengono sostituiti con "third-party" a meno che OTEL_LOG_TOOL_DETAILS=1 non sia impostato

Evento di sondaggio di feedback

Registrato quando viene mostrato o risposto a un sondaggio sulla qualità della sessione. Vedi Sondaggi sulla qualità della sessione per sapere cosa raccolgono i sondaggi e come controllarli.

Nome evento: claude_code.feedback_survey

Attributi:

• Tutti gli attributi standard
• event.name: "feedback_survey"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• event_type: Evento del ciclo di vita del sondaggio, ad esempio "appeared", "responded", o "transcript_prompt_appeared"
• appearance_id: ID univoco che collega gli eventi emessi per un'istanza di sondaggio
• survey_type: Quale sondaggio ha prodotto l'evento. "session" è il prompt di valutazione "Come sta andando Claude?"
• response: La selezione dell'utente su eventi responded
• enabled_via_override: true quando CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL è impostato. Emesso come booleano, non come stringa. Presente su eventi di sondaggio session. Filtra su questo attributo per confermare che l'override è applicato in tutta la flotta

Evento di sweep di conservazione

Registrato una volta per esecuzione dello sweep di pulizia della conservazione, che elimina trascrizioni di sessione e altri dati dell'applicazione più vecchi dell'impostazione cleanupPeriodDays. Claude Code esegue lo sweep in background al massimo una volta per sessione, e un'esecuzione che non elimina nulla emette comunque l'evento. Se Claude Code ha eseguito lo sweep in qualsiasi sessione sulla stessa macchina negli ultimi 24 ore, ritarda lo sweep di questa sessione di almeno 10 minuti, quindi una sessione che esce prima non emette nulla. Quando esegui claude -p con --bare, Claude Code non esegue lo sweep e non emette nulla.

Come ogni evento OTel su questa pagina, va solo al backend di telemetria che configuri. Richiede Claude Code v2.1.227 o successivo.

Quando Claude Code non può determinare in modo sicuro il periodo di conservazione, mette in pausa lo sweep e emette l'evento con result impostato a "skipped" e una skip_reason. Quando le impostazioni gestite impostano cleanupPeriodDays, il valore gestito fissa il periodo di conservazione e lo sweep viene eseguito anche quando un file di impostazioni in un ambito di priorità inferiore è rotto o non valido. Quando managed-settings.json stesso non può essere letto, Claude Code mette comunque in pausa lo sweep a meno che il livello gestito fornisca cleanupPeriodDays da altrove, come impostazioni gestite dal server o un drop-in managed-settings.d/ accanto al file rotto. Gli attributi del contatore di eliminazione sono presenti solo quando result è "complete".

Nome evento: claude_code.retention_sweep

Attributi:

• Tutti gli attributi standard
• event.name: "retention_sweep"
• event.timestamp: Timestamp ISO 8601
• event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
• result: "complete" quando lo sweep è stato eseguito, "skipped" quando Claude Code lo ha messo in pausa
• period_days: Il valore cleanupPeriodDays dalle impostazioni unite, in giorni, o 30 quando nessuna fonte lo imposta. Su eventi saltati, il valore che lo sweep avrebbe utilizzato, calcolato dalle fonti di impostazioni che Claude Code potrebbe leggere
• used_default: "true" quando nessuna fonte di impostazioni leggibile imposta cleanupPeriodDays, "false" altrimenti. Su eventi completi, "true" significa che il default di 30 giorni è stato applicato
• skip_reason: Perché Claude Code ha messo in pausa lo sweep. Presente solo quando result è "skipped":
  • "user_source_disabled": Le impostazioni utente sono escluse, ad esempio dal flag --setting-sources o dall'opzione settingSources dell'SDK, e nessuna fonte abilitata fornisce cleanupPeriodDays
  • "settings_unknowable": Un file di impostazioni non poteva essere letto o analizzato, quindi cleanupPeriodDays o desktopSessionCleanupPeriodDays potrebbe essere impostato a un valore che Claude Code non può vedere
  • "settings_invalid_key_set": Le impostazioni hanno errori di convalida e cleanupPeriodDays o desktopSessionCleanupPeriodDays è esplicitamente impostato, quindi il fallback al default potrebbe eliminare o mantenere file contro quell'impostazione
• transcripts_deleted: Numero di trascrizioni di sessione, i file di primo livello ~/.claude/projects/*/*.jsonl, che lo sweep ha eliminato
• transcripts_exempted_desktop: Numero di trascrizioni passate il periodo di conservazione che lo sweep ha mantenuto secondo la regola di Claude Desktop e Cowork. Questi non contano verso files_past_cutoff. Richiede Claude Code v2.1.248 o successivo
• session_files_deleted: Numero di artefatti che lo sweep dei file di sessione ha eliminato: trascrizioni più file complementari per sessione come sidecars, registrazioni e risultati degli strumenti
• artifacts_deleted: Numero totale di elementi che lo sweep ha eliminato nelle directory di dati che copre, inclusi i file di sessione. Alcuni sweep contano un intero albero di directory rimosso come un elemento e alcuni passaggi di pulizia non contribuiscono al contatore, quindi tratta il valore come un limite inferiore piuttosto che un conteggio di file esatto
• files_retained_fresh: File ispezionati e lasciati in posizione perché sono ancora entro il periodo di conservazione. Solo gli sweep per file contano questi, quindi il valore è un limite inferiore; un valore diverso da zero è lo stato stazionario normale
• files_past_cutoff: File più vecchi del periodo di conservazione che lo sweep non ha potuto eliminare, ad esempio a causa di un errore di autorizzazione o di un file tenuto aperto. Un valore superiore a zero significa che i file hanno superato il periodo di conservazione configurato; zero non è una prova che nessuno lo ha fatto, perché un'eliminazione non riuscita di un'intera directory conta verso error_count invece
• error_count: Numero di errori che lo sweep ha incontrato durante l'elenco o l'eliminazione di file

Interpretazione dei dati di metriche e eventi

Le metriche e gli eventi esportati supportano una gamma di analisi:

Monitoraggio dell'utilizzo

Monitoraggio dei costi

La metrica claude_code.cost.usage aiuta con:

• Tracciare i trend di utilizzo tra team o individui
• Identificare sessioni ad alto utilizzo per l'ottimizzazione
• Attribuire la spesa a skill, plugin, o tipi di subagent specifici tramite gli attributi skill.name, plugin.name, e agent.name

Claude Code conta ogni risposta in streaming verso le metriche di costo e token esattamente una volta, incluso quando un gateway o proxy dietro ANTHROPIC_BASE_URL trasmette l'utilizzo progressivamente su più frame. Prima della v2.1.214, i flussi che contenevano utilizzo in più di un frame gonfiavano claude_code.cost.usage e claude_code.token.usage di circa una richiesta completa aggiuntiva per ogni frame aggiuntivo.

Avvisi e segmentazione

Avvisi comuni da considerare:

• Picchi di costo
• Consumo di token inusuale
• Alto volume di sessioni da utenti specifici

Tutte le metriche possono essere segmentate dagli attributi standard. L'attributo model è disponibile su claude_code.token.usage, claude_code.cost.usage, e da v2.1.172, claude_code.lines_of_code.count.

Le suddivisioni per modello dei commit possono essere solo approssimate tramite un join con le metriche di token o di costo su session.id, poiché una sessione può estendersi su più modelli. Filtra il lato token o costo sulle righe in cui query_source è "main", in modo che le richieste ausiliarie e dei subagent non attribuiscano i commit della sessione a un modello che non li ha effettuati.

Rilevare l'esaurimento dei tentativi

Claude Code ritenta internamente le richieste API non riuscite ed emette un singolo evento claude_code.api_error solo dopo che rinuncia, quindi l'evento stesso è il segnale terminale per quella richiesta. I tentativi di ripetizione intermedi non vengono registrati come eventi separati.

L'attributo attempt sull'evento registra il numero totale di tentativi. CLAUDE_CODE_MAX_RETRIES ha un valore predefinito di 10 ed è limitato a 15. A partire da v2.1.199, puoi impostare CLAUDE_CODE_RETRY_WATCHDOG per aumentare il valore predefinito e rimuovere il limite.

Quando la richiesta esaurisce tutti i tentativi su un errore transitorio, attempt è uguale a uno più di quel limite effettivo: 11 per impostazione predefinita, e mai più di 16 a meno che il watchdog non sia impostato. Un valore inferiore indica un errore non ritentabile come una risposta 400, o una causa con il suo proprio budget di tentativi più piccolo. Ad esempio, Claude Code ritenta un errore nel caricamento delle credenziali AWS o Google Cloud al massimo due volte.

Per distinguere una sessione che si è ripresa da una che si è bloccata, raggruppa gli eventi per session.id e verifica se esiste un evento api_request successivo dopo l'errore.

Analisi degli eventi

I dati degli eventi forniscono informazioni dettagliate sulle interazioni di Claude Code:

Modelli di utilizzo dello strumento: analizza gli eventi di risultato dello strumento per identificare:

• Strumenti più frequentemente utilizzati
• Tassi di successo dello strumento
• Tempi di esecuzione medi dello strumento
• Modelli di errore per tipo di strumento

Monitoraggio delle prestazioni: traccia le durate delle richieste API e i tempi di esecuzione dello strumento per identificare i colli di bottiglia delle prestazioni.

Audit degli eventi di sicurezza

Gli eventi OpenTelemetry sono la fonte di dati di audit per l'attività di Claude Code. Ogni evento porta attributi di identità che collegano le chiamate agli strumenti, l'attività MCP e le decisioni di autorizzazione all'utente che le ha attivate. L'esportatore di log OTLP può fornire questi eventi a qualsiasi piattaforma SIEM (Security Information and Event Management) con un ricevitore OTLP, o a un OpenTelemetry Collector che inoltra al vostro SIEM.

Attribuisci le azioni agli utenti

Gli attributi standard su ogni evento includono l'identità dell'utente autenticato: user.email, user.account_uuid, user.account_id, e organization.id quando accedete con un account Claude o, in una sessione cloud, quando le credenziali della sessione stessa le portano, più user.id e il session.id per sessione. user.id è un identificatore con ambito di installazione, tranne nelle sessioni Claude apps gateway, dove è il soggetto IdP dal token emesso dal gateway.

Le chiamate agli strumenti MCP, i comandi Bash e le modifiche ai file sono quindi attribuite allo sviluppatore che ha avviato la sessione. Claude Code non agisce con un account di servizio separato; l'identità registrata su ogni evento è l'account Claude dello sviluppatore, o l'identità IdP dello sviluppatore in una sessione Claude apps gateway.

Quando Claude Code si autentica con una chiave API diretta, o contro Amazon Bedrock, Google Cloud's Agent Platform, o Microsoft Foundry, non c'è un account Claude nella sessione e solo user.id e session.id vengono popolati. In questi deployment, allegate l'identità dell'utente voi stessi con OTEL_RESOURCE_ATTRIBUTES, impostato per utente tramite il file impostazioni gestite o un wrapper di avvio. Le sessioni Claude apps gateway non hanno bisogno di nulla di tutto questo: la CLI applica l'identità IdP automaticamente, come descritto in Attributi standard.

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

Audit dell'attività MCP

Per acquisire l'attività del server MCP con dettagli completi della chiamata, abilitate l'esportatore di log e impostate OTEL_LOG_TOOL_DETAILS=1. Ogni operazione MCP produce quindi eventi strutturati che portano il nome del server, il nome dello strumento e gli argomenti della chiamata insieme agli attributi di identità standard:

Senza OTEL_LOG_TOOL_DETAILS, questi eventi riducono il dettaglio identificativo:

• tool_result: mantiene mcp_server_scope e un tool_name sostituito con il letterale "mcp_tool" per i server configurati dall'utente, omette il contenuto degli argomenti. Per i server integrati di Claude Desktop, nelle sessioni di cui Claude Desktop è proprietario, mantiene anche la coppia mcp_server_name/mcp_tool_name all'interno di tool_parameters, la stessa eccezione creata dall'host come tool_decision, richiedendo Claude Code v2.1.214 o successivo
• tool_decision: mantiene tool_source e un tool_name sostituito con il letterale "mcp_tool" per i server configurati dall'utente, omette il contenuto degli argomenti. Per i server integrati di Claude Desktop, nelle sessioni di cui Claude Desktop è proprietario, mantiene anche la coppia mcp_server_name/mcp_tool_name all'interno di tool_parameters; tool_source e la coppia di nomi richiedono entrambi Claude Code v2.1.214 o successivo
• mcp_server_connection: omette server_name e il messaggio di errore, ma mantiene is_plugin, plugin_id_hash, e plugin.name, con i nomi dei plugin non Anthropic sostituiti con il letterale "third-party", in modo che i server forniti dai plugin rimangano distinguibili senza registrazione dettagliata

Mappa le domande di sicurezza agli eventi

Quando costruite regole di rilevamento, cercate il segnale che volete monitorare e interrogate il vostro backend per l'evento corrispondente e gli attributi:

Claude Code emette solo il flusso di eventi grezzo. Il rilevamento delle anomalie, il baselining, la correlazione tra sessioni e gli avvisi sono responsabilità del vostro SIEM o backend di osservabilità.

Invia gli eventi a un SIEM

Puntate OTEL_EXPORTER_OTLP_LOGS_ENDPOINT al ricevitore OTLP del vostro SIEM, o a un OpenTelemetry Collector che inoltra all'API di ingestione nativa del vostro SIEM. Il seguente esempio di impostazioni gestite esporta solo gli eventi, con dettagli completi dello strumento abilitati per il controllo 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"
  }
}

Per confermare che gli eventi arrivano, inviate un prompt in una sessione in esecuzione con questa configurazione e controllate il vostro SIEM per l'evento claude_code.user_prompt. Se nulla arriva, eseguite claude --debug e controllate il log di debug per gli errori di esportazione [3P telemetry].

Considerazioni sul backend

La scelta dei backend di metriche, log e tracce determina i tipi di analisi che puoi eseguire:

Per le metriche

• Database di serie temporali: Calcoli di velocità, metriche aggregate
• Archivi colonnari: Query complesse, analisi di utenti univoci
• Piattaforme di osservabilità complete: Query avanzate, visualizzazione, avvisi

Per eventi/log

• Sistemi di aggregazione dei log: Ricerca full-text, analisi dei log
• Archivi colonnari: Analisi degli eventi strutturati
• Piattaforme di osservabilità complete: Correlazione tra metriche e eventi

Per tracce

Scegli un backend che supporti l'archiviazione di tracce distribuite e la correlazione degli span:

• Sistemi di traccia distribuita: Visualizzazione degli span, waterfall delle richieste, analisi della latenza
• Piattaforme di osservabilità complete: Ricerca di tracce e correlazione con metriche e log

Per le organizzazioni che richiedono metriche Daily/Weekly/Monthly Active User (DAU/WAU/MAU), considera backend che supportano query di valori univoci efficienti.

Informazioni sul servizio

Tutte le metriche e gli eventi vengono esportati con i seguenti attributi di risorsa:

• service.name: claude-code per le sessioni di terminale, claude-code-desktop per le sessioni avviate dalla scheda Code nell'app Claude Desktop
• service.version: Versione corrente di Claude Code, o la versione dell'app Desktop per le sessioni della scheda Code
• os.type: Tipo di sistema operativo (ad esempio, linux, darwin, windows)
• os.version: Stringa della versione del sistema operativo
• host.arch: Architettura dell'host (ad esempio, amd64, arm64)
• wsl.version: Numero di versione WSL (presente solo quando si esegue su Windows Subsystem for Linux)
• Meter Name: com.anthropic.claude_code

Se le pipeline del collettore o i dashboard filtrano su service.name = claude-code, aggiungere claude-code-desktop al filtro per acquisire anche la telemetria dalle sessioni della scheda Code.

Risorse di misurazione del ROI

Per una guida completa sulla misurazione del ritorno sull'investimento per Claude Code, inclusa la configurazione della telemetria, l'analisi dei costi, le metriche di produttività e i report automatizzati, consulta la Guida alla misurazione del ROI di Claude Code. Questo repository fornisce configurazioni Docker Compose pronte all'uso, configurazioni Prometheus e OpenTelemetry, e modelli per generare report di produttività integrati con strumenti come Linear.

Sicurezza e privacy

• L'esportazione OpenTelemetry al tuo backend è opt-in e richiede una configurazione esplicita. Per la telemetria operazionale separata di Anthropic e come disabilitarla, vedi Data usage
• I contenuti dei file grezzi e i frammenti di codice non sono inclusi nelle metriche o negli eventi. I percorsi di traccia degli span sono un percorso dati separato: vedi il punto OTEL_LOG_TOOL_CONTENT di seguito
• Quando autenticato tramite OAuth, user.email è incluso negli attributi di telemetria, inviato solo all'endpoint OTel che configuri, mai ad Anthropic. Se questo è una preoccupazione per la tua organizzazione, lavora con il tuo backend di telemetria per filtrare o oscurare questo campo
• Il contenuto del prompt dell'utente non viene raccolto per impostazione predefinita. Viene registrata solo la lunghezza del prompt. Per includere il contenuto del prompt, imposta OTEL_LOG_USER_PROMPTS=1
• Il testo della risposta dell'assistente non viene raccolto per impostazione predefinita. Viene registrata solo la lunghezza della risposta. Per includere il testo della risposta, imposta OTEL_LOG_ASSISTANT_RESPONSES=1. Come tutti i dati OpenTelemetry da Claude Code, il testo della risposta viene inviato solo all'endpoint OTel che configuri, mai ad Anthropic. Quando questa variabile non è impostata, OTEL_LOG_USER_PROMPTS viene utilizzato come fallback, quindi imposta OTEL_LOG_ASSISTANT_RESPONSES=0 se desideri il contenuto del prompt senza il contenuto della risposta
• Gli argomenti di input dello strumento e i parametri non vengono registrati per impostazione predefinita. Per includerli, imposta OTEL_LOG_TOOL_DETAILS=1. Per i server integrati di Claude Desktop, nelle sessioni di cui Claude Desktop è proprietario, tool_decision e tool_result portano la coppia mcp_server_name/mcp_tool_name, nomi creati dall'host piuttosto che contenuto degli argomenti, anche con il flag disattivato. L'eccezione richiede Claude Code v2.1.214 o successivo. Questi dati vengono inviati solo all'endpoint OTEL che configuri, mai ad Anthropic. Gli argomenti potrebbero comunque contenere valori sensibili, quindi configura il tuo backend di telemetria per filtrare o oscurare questi attributi secondo necessità. Quando abilitato:
  • Gli eventi tool_result e tool_decision includono un attributo tool_parameters con comandi Bash, nomi dei server MCP e dello strumento, e nomi delle skill. I campi come full_command vengono emessi non troncati
  • Gli eventi tool_result includono inoltre un attributo tool_input con percorsi di file, URL, modelli di ricerca e altri argomenti. I singoli valori superiori a 512 caratteri vengono troncati e il totale è limitato a circa 4 K caratteri
  • Gli eventi user_prompt includono il command_name verbatim per i comandi personalizzati, plugin e MCP
  • Gli span di traccia includono lo stesso attributo tool_input e attributi derivati dall'input come file_path, con lo stesso troncamento di tool_input
• Il contenuto di input e output dello strumento non viene registrato negli span di traccia per impostazione predefinita. Per includerlo, imposta OTEL_LOG_TOOL_CONTENT=1. Quando abilitato, gli eventi di span includono il contenuto completo di input e output dello strumento troncato al limite di contenuto (60 KB per impostazione predefinita) per attributo. Questo può includere contenuti di file grezzi dai risultati dello strumento Read e output dei comandi Bash. Configura il tuo backend di telemetria per filtrare o oscurare questi attributi secondo necessità
• I corpi grezzi della richiesta e della risposta dell'API Anthropic Messages non vengono registrati per impostazione predefinita. Per includerli, imposta OTEL_LOG_RAW_API_BODIES nella tua shell, nelle impostazioni utente o nelle impostazioni gestite. Viene ignorato nelle impostazioni di progetto e locali. I corpi contengono l'intera cronologia della conversazione, incluso il prompt di sistema, ogni turno precedente dell'utente e dell'assistente, e risultati degli strumenti, quindi l'abilitazione di questa opzione implica il consenso a tutto ciò che gli altri flag di contenuto OTEL_LOG_* rivelerebbero. Claude Code oscura sempre il contenuto del pensiero esteso di Claude in questi corpi, indipendentemente da altre impostazioni. Il valore che imposti determina come Claude Code fornisce i corpi:
  • Con =1, Claude Code emette eventi di log api_request_body e api_response_body per ogni chiamata API. L'attributo body degli eventi porta il payload serializzato in JSON, troncato al limite di contenuto (60 KB per impostazione predefinita)
  • Con =file:<dir>, Claude Code scrive i corpi non troncati nei file .request.json e .response.json in quella directory, e gli eventi portano un percorso body_ref invece del corpo inline. Spedisci la directory con un log collector o sidecar piuttosto che attraverso il flusso di telemetria

Monitoraggio di Claude Code su Amazon Bedrock

Per una guida dettagliata al monitoraggio dell'utilizzo di Claude Code per Amazon Bedrock, consulta Claude Code Monitoring Implementation (Amazon Bedrock).