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

[!NOTE]

Per la Claude API o i Managed Agents, consulta OpenTelemetry per la Claude API.

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, avvia Claude Code con claude --debug-file <path> e controlla il log che scrive in quel percorso. 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"
  }
}

Nell'app Claude Desktop, le sessioni della scheda Code leggono queste impostazioni gestite dalle fonti che raggiungono ogni tipo di sessione Desktop. Il modulo OpenTelemetry per Cowork sotto Monitoring nelle impostazioni Data and privacy della console amministratore si applica solo alle sessioni Cowork, quindi né il CLI del terminale né la scheda Code esportano a un collector che imposti lì.

Claude Code ignora le variabili dell'esportatore OpenTelemetry nel .claude/settings.json e .claude/settings.local.json di un repository, quindi un repository non può usarle per attivare la telemetria, scegliere dove va, o acquisire contenuti. Impostale nelle impostazioni gestite, oppure fai in modo che ogni sviluppatore le imposti nella propria shell o in ~/.claude/settings.json. Un repository può comunque disattivare un segnale impostando il suo selettore di esportatore, come OTEL_LOGS_EXPORTER, su none, a meno che le impostazioni gestite, un file --settings, o l'ambiente da cui avvii Claude Code imposti quella variabile.

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 nel log di 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 di configurazione

Variabili di configurazione comuni

Queste variabili configurano gli exporter, gli endpoint e il comportamento di esportazione per tutti i deploy.

Se imposti una variabile di endpoint o di protocollo specifica per segnale, come OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, Claude Code la usa al posto della variabile generica per quel segnale. Se imposti una variabile di header specifica per segnale, come OTEL_EXPORTER_OTLP_METRICS_HEADERS, Claude Code ne esegue il merge con la variabile generica OTEL_EXPORTER_OTLP_HEADERS per quel segnale.

Sulle macchine con impostazioni gestite, consulta Come le impostazioni gestite bloccano la destinazione OTLP per sapere cosa rimuove Claude Code.

Per i protocolli http/protobuf e http/json, Claude Code invia ogni richiesta di esportazione con un header Content-Length.

Autenticazione mTLS

Il modo in cui configuri i certificati client per l'exporter OTLP dipende dal protocollo OTLP in uso per quel segnale, impostato tramite OTEL_EXPORTER_OTLP_PROTOCOL o l'override specifico 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 delle metriche specifiche per segnale continuano a funzionare. Sulle macchine con impostazioni gestite, Claude Code potrebbe rimuovere all'avvio le credenziali e gli endpoint specifici per segnale impostati dallo sviluppatore.

Controllo della cardinalità delle metriche

Le seguenti variabili d'ambiente controllano quali attributi vengono inclusi nelle metriche e negli eventi per gestire la cardinalità:

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

Tracce (beta)

Il tracing distribuito esporta span che collegano ogni prompt dell'utente alle richieste API e alle esecuzioni degli strumenti che attiva, così puoi visualizzare una richiesta completa come una singola traccia nel tuo backend di tracing.

Il tracing è disattivato per impostazione predefinita. Per abilitarlo, imposta sia CLAUDE_CODE_ENABLE_TELEMETRY=1 sia 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, header e mTLS. Sulle macchine con impostazioni gestite, Claude Code potrebbe rimuovere all'avvio le credenziali e gli endpoint specifici per segnale impostati dallo sviluppatore.

Per impostazione predefinita, gli span oscurano il testo dei prompt dell'utente, i dettagli dell'input degli strumenti e il contenuto degli strumenti. Imposta OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 e OTEL_LOG_TOOL_CONTENT=1 per includerli.

Quando il tracing è attivo, i sottoprocessi Bash e PowerShell ereditano automaticamente una variabile d'ambiente TRACEPARENT contenente il contesto di traccia W3C dello span di esecuzione dello strumento attivo. Questo consente a qualsiasi sottoprocesso che legge TRACEPARENT di collegare i propri span come figli all'interno della stessa traccia, abilitando il tracing distribuito end-to-end attraverso gli script e i comandi eseguiti da Claude.

Quando il tracing è attivo e Claude Code è connesso direttamente all'API di Anthropic, ogni richiesta al modello include un header W3C traceparent impostato sul contesto dello span claude_code.llm_request, e l'header traceresponse dell'API viene registrato come link di span. Insieme, questi collegano gli span lato client di Claude Code alla traccia lato server attraverso qualsiasi intermediario conforme. Le richieste MCP HTTP in uscita includono traceparent allo stesso modo. L'header non viene inviato a provider di terze parti.

Per impostazione predefinita, l'header traceparent sulle richieste al modello e sulle richieste MCP HTTP viene inviato solo quando ANTHROPIC_BASE_URL non è impostata o punta all'API di Anthropic, poiché alcuni proxy rifiutano header non riconosciuti. La variabile TRACEPARENT dei sottoprocessi è controllata dallo stesso interruttore per coerenza. Se esegui Claude Code attraverso un proxy ANTHROPIC_BASE_URL personalizzato e vuoi che il contesto di traccia venga propagato, imposta CLAUDE_CODE_PROPAGATE_TRACEPARENT=1.

Nell'Agent SDK e nelle sessioni non interattive avviate con -p, Claude Code legge anche TRACEPARENT e TRACESTATE dal proprio ambiente all'avvio di ogni span di interazione. Questo consente a un processo che incorpora Claude Code di passare il proprio contesto di traccia W3C attivo al sottoprocesso, in modo che gli span di Claude Code appaiano come figli della traccia distribuita del chiamante. Le sessioni interattive ignorano TRACEPARENT in ingresso per evitare di ereditare accidentalmente valori ambientali da ambienti CI o container.

Il contesto di traccia in ingresso si applica anche agli eventi. Nell'Agent SDK e nelle sessioni -p con TRACEPARENT impostata, ogni record di log degli eventi OTLP include valori trace_id e span_id che lo collegano alla traccia della tua applicazione, anche quando l'exporter delle tracce non è configurato, così il tuo backend di logging può correlare gli eventi con il resto della traccia.

Un record emesso mentre un'interazione è attiva riporta gli ID dello span di interazione, anche quando Claude Code lo emette al di fuori del contesto asincrono dello span, ad esempio in una callback di una richiesta di permesso o per un record bufferizzato durante l'avvio ed esportato in seguito. Un record emesso senza uno span di interazione attivo riporta direttamente gli ID di TRACEPARENT in ingresso.

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 a loro volta due span figli: uno per il tempo trascorso in attesa di una decisione sul permesso 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 vengono annidati sotto lo span claude_code.tool del genitore.

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

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

Quando un hook PreToolUse rinvia una chiamata a uno strumento, Claude Code salva il contesto di traccia del turno che l'ha rinviata. 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 include gli attributi standard più un attributo span.type corrispondente al suo nome. Le tabelle seguenti elencano gli attributi aggiuntivi impostati su ciascuno 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 nuovo tentativo viene registrato anche come evento di span gen_ai.request.attempt con gli attributi attempt e client_request_id.

claude_code.tool

Evento di span tool.output su claude_code.tool

Se imposti OTEL_LOG_TOOL_CONTENT=1, le chiamate Read e Bash possono registrare un evento di span tool.output sullo span claude_code.tool. Le chiamate Edit e Write ne registrano uno solo se imposti anche OTEL_LOG_TOOL_DETAILS=1. Questa variabile non è limitata a questi due strumenti, quindi controlla la sua riga nella tabella di configurazione per gli argomenti che aggiunge altrove.

Anche gli strumenti MCP, WebFetch e WebSearch registrano questo evento, su Claude Code v2.1.283 o successiva.

Claude Code scrive questo evento dal ritorno riuscito di una chiamata a uno strumento, quindi una chiamata che genera un errore non registra nulla, qualunque sia lo strumento. Tra le chiamate che restituiscono un risultato, non registra alcun evento tool.output per:

• Una chiamata a qualsiasi strumento diverso da Read, Edit, Write, Bash, WebFetch, WebSearch e gli strumenti MCP
• Una Read che restituisce qualcosa di diverso dal testo di un file, come un'immagine, un PDF o una nuova lettura di un file il cui contenuto non è cambiato
• Una chiamata Edit o Write, a meno che tu non imposti anche OTEL_LOG_TOOL_DETAILS=1
• Una chiamata WebFetch o WebSearch che Claude Code ha spostato in background durante l'esecuzione affinché un messaggio in attesa potesse raggiungere Claude. Nemmeno il risultato che arriva in seguito viene registrato. Per sapere quando Claude Code sposta una chiamata, consulta Quando Claude Code invia ciò che hai messo in coda per il terminale e il campo priority per le sessioni dell'Agent SDK

L'evento include questi attributi, ciascuno troncato al limite del contenuto (60 KB per impostazione predefinita). Controllato da indica la variabile di cui un attributo ha bisogno oltre a OTEL_LOG_TOOL_CONTENT=1, e per Edit e Write quella variabile controlla l'evento stesso anziché l'attributo.

L'attributo tool_name dello span genitore ti indica da quale strumento proviene un evento. Un attributo troncato al limite del contenuto è accompagnato da <attribute>_truncated e <attribute>_original_length.

claude_code.tool.blocked_on_user

Una decisione cancelled con source user_abort significa che un messaggio che richiedeva una consegna immediata ha interrotto il turno mentre la richiesta di permesso o il controllo della modalità auto era in sospeso. Ad esempio, durante un controllo della modalità auto, l'utente aveva un messaggio in coda e lo ha inviato immediatamente.

claude_code.tool.execution

claude_code.hook

Questo span appare solo quando il tracing beta dettagliato è attivo, il che richiede ENABLE_BETA_TRACING_DETAILED=1 e BETA_TRACING_ENDPOINT, una coppia che cambia anche la destinazione dei tuoi log e delle tue 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 sola non lo produce.

Nelle sessioni CLI interattive, il tracing beta dettagliato richiede anche che la tua organizzazione sia inserita nella lista di autorizzazione per la funzionalità. L'Agent SDK e le sessioni non interattive -p non richiedono l'inserimento nella lista di autorizzazione.

[!WARNING]

Imposta ENABLE_BETA_TRACING_DETAILED solo per il debug, non in produzione. Il tracing beta dettagliato ha un volume di esportazione elevato, e i suoi attributi di contenuto non fanno parte dello schema stabile degli span.

Attributi di contenuto con il tracing beta dettagliato

[!NOTE]

Ulteriori attributi che contengono contenuto, come new_context, system_reminders, system_prompt_preview, user_system_prompt, tool_input e response.model_output, vengono emessi solo quando il tracing beta dettagliato è attivo. Non fanno parte dello schema stabile degli span.

Questi attributi appaiono sugli span seguenti, e Controllato da indica la variabile di cui un attributo ha bisogno oltre al tracing beta dettagliato. I valori più lunghi del limite del contenuto (60 KB per impostazione predefinita) vengono troncati.

Con il tracing beta dettagliato e OTEL_LOG_USER_PROMPTS=1, Claude Code emette anche un evento claude_code.system_prompt che contiene il prompt di sistema completo, troncato al limite del contenuto. Arriva la prima volta che una sessione invia ciascun prompt di sistema distinto, e di nuovo dopo la compattazione.

Header dinamici

Per gli ambienti aziendali che richiedono un'autenticazione dinamica, puoi configurare uno script per generare header in modo dinamico. Gli header dinamici si applicano solo ai protocolli http/protobuf e http/json. Con il protocollo grpc, Claude Code usa solo le variabili degli header statici, OTEL_EXPORTER_OTLP_HEADERS e le sue varianti specifiche per segnale.

Configurazione delle impostazioni

Aggiungi al tuo .claude/settings.json, sostituendo il percorso con quello del 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, oppure una riga di comando della shell con argomenti. Su Windows, il valore viene sempre eseguito tramite la shell, quindi racchiudi tra virgolette un percorso che contiene spazi all'interno del valore JSON.

Requisiti dello script

Lo script deve produrre un JSON valido con coppie chiave-valore di tipo stringa che rappresentano gli header HTTP:

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

Se l'helper non riesce o stampa un output che non soddisfa questi requisiti, le esportazioni non riescono e il tuo backend di telemetria non riceve nulla dalla sessione finché l'helper non funziona di nuovo. Claude Code segnala l'errore in:

• Una notifica di avviso nelle sessioni interattive, otelHeadersHelper failed; telemetry is not being exported, mostrata una volta per sessione quando l'helper non riesce per la prima volta
• L'output di /status
• Il log di debug, quando esegui con --debug o dopo aver eseguito /debug nella sessione
• stderr, nelle sessioni non interattive avviate con -p

Comportamento di aggiornamento

Lo script helper degli header viene eseguito all'avvio e successivamente a intervalli regolari per supportare l'aggiornamento dei token. Per impostazione predefinita, lo script viene eseguito ogni 29 minuti. Personalizza l'intervallo con la variabile d'ambiente CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS.

Supporto per organizzazioni con più team

Le organizzazioni con più team o reparti possono aggiungere attributi personalizzati per distinguere tra gruppi diversi usando la variabile d'ambiente OTEL_RESOURCE_ATTRIBUTES:

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

Questi attributi personalizzati sono inclusi in tutte le metriche e in tutti gli eventi, consentendoti di:

• Filtrare le metriche per team o reparto
• Monitorare i costi per centro di costo
• Creare dashboard specifiche per team
• Configurare avvisi per team specifici

Claude Code associa questi valori come attributi su ogni datapoint delle metriche e su ogni record di evento, oltre a inviarli nel blocco delle risorse OTLP. Poiché la maggior parte dei backend di metriche espone gli attributi dei datapoint come etichette interrogabili, puoi raggruppare e filtrare le metriche direttamente in base alle tue chiavi personalizzate. Ad eccezione degli attributi del repository vcs.*, le chiavi personalizzate non sovrascrivono mai gli attributi standard come user.id o session.id: quando una chiave entra in conflitto, Claude Code mantiene il valore integrato.

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

[!WARNING]

La variabile d'ambiente OTEL_RESOURCE_ATTRIBUTES usa coppie key=value separate da virgole con requisiti di formattazione rigorosi:

• Nessuno spazio consentito: i valori non possono contenere spazi. Ad esempio, user.organizationName=My Company non è valido
• Formato: deve essere composta da coppie key=value separate da virgole: key1=value1,key2=value2
• Caratteri consentiti: solo caratteri US-ASCII esclusi i caratteri di controllo, gli spazi bianchi, le virgolette doppie, le virgole, i punti e virgola e le barre rovesciate
• Caratteri speciali: i caratteri al di fuori dell'intervallo consentito devono essere codificati con percent-encoding

Per un valore che richiederebbe uno spazio, usa invece underscore o camelCase. Gli esempi seguenti impostano org.name con ciascuna forma:

export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

Puoi codificare con percent-encoding qualsiasi carattere, non solo quelli esclusi. Questo esempio codifica sia lo spazio sia l'apostrofo:

export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Racchiudere i valori tra virgolette non esegue l'escape degli spazi. Ad esempio, org.name="My Company" produce il valore letterale "My Company" con le virgolette incluse, non My Company.

Attribuire la telemetria alle sessioni SSH di Desktop

Per vedere su quale macchina remota è stata eseguita una sessione SSH di Desktop, assegna un nome a ogni macchina in un attributo personalizzato. Le metriche e gli eventi non indicano la macchina su cui è stata eseguita una sessione.

Su ogni macchina remota, aggiungi OTEL_RESOURCE_ATTRIBUTES al blocco env che attiva la telemetria, nel file delle impostazioni gestite letto dalla sessione. Scrivi il nome per esteso nel file di ogni macchina. Claude Code non espande il valore, quindi host.name=$(hostname) arriva come quei caratteri.

L'esempio seguente assegna alla macchina il nome build-7:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_RESOURCE_ATTRIBUTES": "host.name=build-7"
  }
}

Quando nient'altro imposta la variabile, host.name arriva nel blocco delle risorse, nelle sessioni SSH di Desktop e nella CLI su quella macchina. Per sapere dove altro appaiono gli attributi personalizzati, consulta Supporto per organizzazioni con più team.

Se il nome non arriva, verifica una di queste cause:

• L'hai impostato sul computer che esegue Desktop: Desktop non passa alla sessione SSH un valore impostato lì
• L'hai esportato in /etc/profile o in un altro file letto solo dalle shell di login: il nome arriva quando esegui claude da una shell di login, ma non in una sessione SSH di Desktop. Desktop non avvia Claude Code tramite una shell di login. Imposta invece la variabile sotto env nel file delle impostazioni gestite sulla macchina remota.
• Un valore contiene uno spazio: in questo caso Claude Code non copia nessuna delle chiavi su eventi o datapoint e non segnala alcun errore. Rimuovi lo spazio dal valore.
• Qualcos'altro imposta già la variabile: in una sessione avviata dall'app desktop, una variabile già impostata nell'ambiente di avvio ha la precedenza sui file delle impostazioni. Il log di debug indica ogni variabile ignorata. Quando un deploy di Desktop di terze parti specifica un endpoint OTLP nell'ambiente che fornisce, quell'ambiente include il proprio OTEL_RESOURCE_ATTRIBUTES di Desktop.

Configurazioni di esempio

Imposta queste variabili d'ambiente prima di eseguire claude. Ogni scenario seguente mostra una configurazione completa, e ogni variabile è descritta in Variabili di configurazione comuni. Per confermare che una configurazione sia stata applicata, controlla nel tuo backend la metrica claude_code.session.count dopo aver avviato una sessione; la Guida rapida spiega la verifica dei soli log e cosa controllare quando non arriva nulla.

Per il debug sulla 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, con scraping da http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

In un ambiente self-hosted, la sessione si associa alla porta 9464 solo con la capacità predefinita del runner pari a uno. Con una capacità superiore, il runner espone invece nuovamente i contatori e gli indicatori della sessione sul proprio endpoint /metrics.

Per inviare le metriche a più exporter:

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/v1/metrics
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

Per esportare solo le 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

Telemetria da sessioni cloud e Claude Tag

Le sessioni cloud, incluse le sessioni del canale Claude Tag, vengono eseguite in ambienti cloud piuttosto che sui dispositivi dei vostri utenti, quindi un file di impostazioni gestito o un profilo shell su quei dispositivi non configura la loro telemetria. Per le sessioni in ambienti ospitati da Anthropic, questa sezione illustra dove impostare le variabili di telemetria, come rendere raggiungibile il vostro collector dall'ambiente e come distinguere le sessioni cloud e Claude Tag nei dati esportati.

Per esportare la telemetria da quelle sessioni, impostate CLAUDE_CODE_ENABLE_TELEMETRY e le variabili OTEL_*, utilizzando le stesse chiavi dell'esempio di configurazione dell'amministratore, in uno di due posti:

• Impostazioni gestite dal server: aggiungetele al blocco env delle impostazioni gestite dal server della vostra organizzazione. Claude Code recupera quelle impostazioni all'avvio ovunque si applichino le impostazioni gestite dal server, il che include i dispositivi dei vostri utenti e le sessioni cloud diverse dalle sessioni del canale Claude Tag. Le sessioni Claude Tag non ricevono le vostre impostazioni gestite dal server, quindi questo percorso non le configura.
• Le variabili dell'ambiente: aggiungetele alle variabili di ambiente di un ambiente cloud per configurare solo le sessioni eseguite in quell'ambiente. Questo è il percorso che raggiunge le sessioni Claude Tag.

Chiunque utilizzi un ambiente può leggerne le variabili, quindi non inserire lì una credenziale, come un token del collector in OTEL_EXPORTER_OTLP_HEADERS. Nemmeno un segreto di rete sull'ambiente è utile, perché l'esportazione della telemetria di Claude Code stesso è una delle richieste che non ricevono mai il segreto. Se il tuo collector richiede una credenziale, configura invece l'intera esportazione tramite le impostazioni gestite dal server, perché quando imposti lì una credenziale, Claude Code rimuove le variabili di endpoint impostate al di fuori delle impostazioni gestite.

Tenete presenti questi vincoli quando configurate la telemetria per le sessioni cloud:

• Consentire alle sessioni di raggiungere il collector: Claude Code invia l'esportazione attraverso la rete della sessione, quindi se raggiunge l'host nel vostro OTEL_EXPORTER_OTLP_ENDPOINT dipende dal livello di accesso di rete dell'ambiente. Se le sessioni non riescono a raggiungere il dominio del collector al livello scelto, aggiungete il dominio alla lista di autorizzazione dell'ambiente, perché nessuna impostazione gestita dal server aggiunge domini alla lista di autorizzazione di rete di un ambiente.
• Canali Claude Tag: apporta le modifiche all'allowlist e alle variabili d'ambiente sull'ambiente condiviso impostato come predefinito della tua organizzazione o fissato al canale.
• Cowork è configurato separatamente: le sessioni Cowork non ricevono impostazioni gestite dal server, come mostra la tabella di copertura della superficie, quindi il blocco env gestito dal server non configura la loro telemetria.

Attribuire la telemetria alle sessioni cloud

Per impostazione predefinita, le metriche e gli eventi da una sessione cloud portano gli attributi standard, inclusi session.id, ccr.session.id e organization.id, quindi potete filtrare per sessione o organizzazione senza configurazione aggiuntiva. Il valore ccr.session.id è l'CLAUDE_CODE_REMOTE_SESSION_ID della sessione. Per convertirlo nell'URL della trascrizione della sessione, vedete Collegare l'output alla sessione.

Per distinguere le sessioni cloud, raggruppa o filtra in base a ccr.session.id, non a session.id.

Per attribuire la telemetria in modo più dettagliato, utilizzate queste opzioni:

• Identificare le sessioni Claude Tag: imposta OTEL_METRICS_INCLUDE_ENTRYPOINT=true, come descritto in Controllo della cardinalità delle metriche. Le metriche e gli eventi portano quindi app.entrypoint, il cui valore è claude-in-slack per le sessioni Claude Tag.
• Aggiungere attributi personalizzati: impostate OTEL_RESOURCE_ATTRIBUTES nello stesso posto in cui impostate le altre variabili OTEL_* per quelle sessioni. Se lo export nello script di configurazione dell'ambiente, il valore non raggiunge Claude Code: lo script di configurazione è uno script Bash separato che viene eseguito prima dell'avvio di Claude Code e le variabili che esporta terminano con esso.

Nelle sessioni del canale Claude Tag, Claude funziona come l'identità condivisa della vostra organizzazione piuttosto che come qualsiasi membro, quindi non affidatevi agli attributi user.* per identificare chi ha taggato Claude.

Metriche ed eventi disponibili

Attributi standard

Tutte le metriche e gli eventi condividono questi attributi standard:

Nelle sessioni che hanno eseguito l'accesso a un Claude apps gateway tramite /login, la CLI contrassegna le esportazioni con l'identità autenticata: user.id è il soggetto dell'IdP, user.email è l'email con cui è stato eseguito l'accesso e user.groups contiene l'appartenenza ai gruppi dell'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 in queste sessioni.

[!NOTE]

Gli eventi che Claude Code registra prima che uno sviluppatore esegua l'accesso non contengono l'identità del gateway. Quando Claude Code apre una sessione senza accesso al gateway, ad esempio dopo che il gateway ha terminato l'accesso, gli eventi di avvio registrati prima dell'accesso contengono lo user.id anonimo e nessun identity.source. Tra questi ci sono managed_settings_resolved, plugin_loaded e mcp_server_connection.

Per gli attributi di identità nelle sessioni di Claude Desktop e Cowork che si connettono tramite un gateway, consulta il riferimento telemetry del gateway.

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

• prompt.id: UUID che correla un prompt dell'utente con tutti gli eventi successivi fino al prompt seguente. Consulta Attributi di correlazione degli eventi.
• workspace.host_paths: directory del workspace host selezionate nell'app desktop, come array di stringhe
• workflow.run_id: identificatore dell'esecuzione, con prefisso wf_, negli eventi API e degli strumenti emessi dagli agenti che appartengono a un'esecuzione dello strumento Workflow. Filtrando gli eventi per un singolo workflow.run_id si ricostruiscono le richieste API e i risultati degli strumenti di quell'esecuzione. L'identificatore copre gli agenti generati dallo script del workflow e tutti gli agenti che questi generano a loro volta, come le invocazioni di skill. Corrisponde all'identificatore dell'esecuzione riportato nel risultato dello strumento Workflow.
• workflow.name: nome del workflow, il meta.name del suo script, emesso insieme a workflow.run_id. I nomi dei workflow integrati compaiono testualmente quando l'esecuzione usa lo script integrato non modificato. I nomi creati dagli utenti, incluse le copie modificate degli script integrati, vengono sostituiti con custom a meno che non sia impostato OTEL_LOG_TOOL_DETAILS=1.
• agent_id: identificatore del subagent che ha generato l'evento, come a3f2c1b4d5e6f7a80. Gli eventi che lo contengono includono gli eventi API e degli strumenti di un subagent, i suoi eventi assistant_response e subagent_completed per il subagent terminato. Assente negli eventi della sessione principale e dei compagni di team in-process. L'agent_id dello span del subagent è lo stesso valore, oppure aggiunge un'etichetta dopo la a iniziale come in acompact-3f2c1b4d5e6f7a80. Richiede Claude Code v2.1.310 o successivo
• parent_agent_id: l'agent_id dell'agente che ha generato o ripreso per ultimo il subagent che ha generato l'evento. Assente quando quell'agente è la sessione principale. Richiede Claude Code v2.1.310 o successivo

Attributi del repository

Imposta OTEL_METRICS_INCLUDE_REPOSITORY=true per contrassegnare metriche ed eventi con l'identità del repository della sessione, in modo che un collector condiviso possa attribuire l'utilizzo per repository. Richiede Claude Code v2.1.269 o successiva.

Claude Code deriva questi attributi una volta per sessione dal remote origin del repository. Quando i remote HTTPS e SSH di un repository indicano lo stesso host e lo stesso percorso, come avviene su GitHub, GitLab e Bitbucket Cloud, entrambi producono valori identici:

I valori sono in minuscolo e credenziali, query string e frammenti dell'URL del remote non vi compaiono mai. Gli attributi vengono omessi quando la sessione non ha un remote origin, quando il remote non ha la forma di un URL o quando l'unico repository che la contiene è la tua directory home.

Per ottenere questi attributi da una sessione cloud, imposta le variabili di telemetria, incluso OTEL_METRICS_INCLUDE_REPOSITORY, nel suo ambiente cloud. Consenti inoltre il dominio del tuo collector nell'accesso alla rete dell'ambiente.

Una chiave vcs.* che dichiari in OTEL_RESOURCE_ATTRIBUTES sostituisce il valore derivato per quella chiave. Se dichiari vcs.repository.url.full, Claude Code non legge mai il remote e riporta solo le chiavi che dichiari.

Se i clone HTTPS e SSH di uno stesso repository riportano valori diversi, ad esempio in un'installazione self-hosted il cui URL di clone HTTPS contiene un prefisso di percorso assente nell'URL SSH, dichiara vcs.repository.url.full in OTEL_RESOURCE_ATTRIBUTES insieme a tutte le altre chiavi vcs.* che vuoi riportare. Ogni clone riporterà quindi l'identità che dichiari.

Gli attributi arrivano solo ai tuoi exporter; la telemetria di Anthropic scarta ogni chiave vcs.*.

Metriche

Claude Code esporta le seguenti metriche. La colonna Unità mostra la stringa dell'unità OpenTelemetry associata a ciascuna metrica; le metriche di conteggio non ne hanno.

Quando prometheus è l'unico exporter elencato in OTEL_METRICS_EXPORTER, Claude Code omette le unità USD, tokens e s dalle metriche esportate, in modo che lo scrape resti in formato testo Prometheus valido. I nomi delle metriche non cambiano, e le configurazioni che combinano più exporter, come otlp,prometheus, mantengono le unità.

Dettagli delle metriche

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

Contatore delle sessioni

Incrementato all'inizio di ogni sessione. Per contare invece le persone, consulta Monitoraggio dell'utilizzo.

Attributi:

• Tutti gli attributi standard
• start_type: Modo in cui è stata avviata la sessione. Uno tra "fresh", "resume", "continue" o "agents_view". Il valore "agents_view" identifica il processo della dashboard claude agents, un'interfaccia locale avviata dall'utente e non una sessione conversazionale. Filtra su questo valore per separare gli avvii dei processi dell'interfaccia dalle sessioni conversazionali nelle tue dashboard.

Contatore delle righe di codice

Incrementato quando viene aggiunto o rimosso codice.

Attributi:

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

Contatore delle pull request

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

Attributi:

• Tutti gli attributi standard

Contatore dei commit

Incrementato quando vengono creati commit git tramite Claude Code.

Attributi:

• Tutti gli attributi standard

Contatore dei costi

Incrementato dopo ogni richiesta API.

Per impostazione predefinita, gli attributi agent.name, skill.name, plugin.name, mcp_server.name e mcp_tool.name oscurano alcuni nomi sostituendoli con un segnaposto "custom" o "third-party". Se imposti OTEL_LOG_TOOL_DETAILS=1, contengono invece i nomi reali. Prima della v2.1.273, i contatori di costi e token e gli eventi api_request, api_error e api_refusal contenevano i valori oscurati anche con OTEL_LOG_TOOL_DETAILS=1 impostato.

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 tra "main", "subagent" o "auxiliary"
• speed: "fast" quando la richiesta ha usato la modalità veloce. Assente altrimenti
• effort: Livello di sforzo applicato alla richiesta: "low", "medium", "high", "xhigh" o "max". Assente quando Claude Code non invia alcun livello di sforzo, ad esempio con un modello che non supporta lo sforzo.
• agent.name: Tipo di subagent che ha emesso la richiesta. I nomi degli agenti integrati e degli agenti dei plugin del marketplace ufficiale compaiono testualmente. Gli altri nomi di agenti definiti dall'utente vengono sostituiti con "custom". Assente quando la richiesta non è stata emessa da un tipo di subagent con nome.
• skill.name: Skill attiva per la richiesta, impostata dallo strumento Skill o da un comando /, oppure ereditata da un subagent generato. I nomi delle skill integrate, incluse nel pacchetto, definite dall'utente e dei plugin del marketplace ufficiale compaiono testualmente. 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 o il subagent attivo è fornito da un plugin. I nomi dei plugin del marketplace ufficiale compaiono testualmente. 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, anche con OTEL_LOG_TOOL_DETAILS=1 impostato. Assente altrimenti.
• mcp_server.name: Server MCP il cui risultato dello strumento è stato consumato da questa richiesta. I nomi dei server integrati, tramite proxy di claude.ai e del registro ufficiale compaiono testualmente. I nomi dei server configurati dall'utente vengono sostituiti con "custom". Assente quando la richiesta non ha consumato alcun risultato di uno strumento MCP. Prima della v2.1.222, Claude Code impostava questo attributo su ogni richiesta successiva a una chiamata a uno strumento MCP, non solo sulle richieste che consumavano un risultato dello strumento, quindi le dashboard che lo aggregano mostrano un calo dopo l'aggiornamento.
• mcp_tool.name: Strumento MCP il cui risultato è stato consumato da questa richiesta, con lo stesso comportamento di oscuramento e di versione di mcp_server.name. Assente quando la richiesta non ha consumato alcun risultato di uno strumento MCP.

Contatore dei token

Incrementato dopo ogni richiesta API.

Attributi:

• Tutti gli attributi standard
• type: ("input", "output", "cacheRead", "cacheCreation"). Il tipo "input" esclude i token letti dalla cache dei prompt o scritti in essa, che vengono conteggiati in "cacheRead" e "cacheCreation". Il tipo "cacheCreation" conteggia insieme le scritture nella cache con le durate della cache di cinque minuti e di un'ora.
• model: Identificatore del modello (ad esempio, "claude-sonnet-5")
• query_source: Categoria del sottosistema che ha emesso la richiesta. Uno tra "main", "subagent" o "auxiliary"
• speed: "fast" quando la richiesta ha usato la modalità veloce. Assente altrimenti
• effort: Livello di sforzo applicato alla richiesta. Consulta Contatore dei costi 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. Consulta Contatore dei costi per le definizioni e il comportamento di oscuramento.

Contatore delle decisioni sugli strumenti di modifica del codice

Incrementato quando l'utente accetta o rifiuta l'uso degli strumenti Edit, Write o NotebookEdit.

Attributi:

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

Contatore del tempo attivo

Tiene traccia del tempo effettivamente trascorso a usare attivamente Claude Code, escluso 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 della CLI, come l'esecuzione degli strumenti e la generazione delle risposte dell'IA.

Attributi:

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

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 può effettuare più chiamate API ed eseguire diversi strumenti. L'attributo prompt.id ti consente di ricondurre tutti questi eventi al singolo prompt che li ha generati.

Per tracciare tutta l'attività generata da un singolo prompt, filtra i tuoi eventi per uno specifico valore di prompt.id. In questo modo ottieni l'evento user_prompt, tutti gli eventi api_request e tutti gli eventi tool_result verificatisi durante l'elaborazione di quel prompt.

event.sequence parte da 0 ogni volta che si avvia un processo di Claude Code e aumenta per tutta la durata di quel processo. Continua a contare anche dopo /clear, che assegna un nuovo session.id. Se riprendi una sessione senza fork, la sessione mantiene il suo session.id ma prende i valori di event.sequence dal processo che l'ha ripresa, quindi all'interno di una sessione un evento successivo può avere un valore inferiore a uno precedente, o ripeterlo. Per ordinare gli eventi di una sessione, ordina per event.timestamp e usa event.sequence per ordinare gli eventi che condividono lo stesso timestamp.

Per la ricostruzione a livello di messaggio, ogni classe di eventi contiene una chiave che corrisponde a un campo della trascrizione della sessione. Il formato delle voci della trascrizione è interno a Claude Code e cambia tra le versioni, quindi una pipeline che esegue join su questi campi può rompersi a ogni release; considera i join come specifici della versione anziché come un contratto stabile:

• message.uuid in user_prompt, assistant_response e api_response_body
• request_id negli eventi API, salvato come requestId nelle voci dell'assistente della trascrizione
• tool_use_id negli eventi tool_result e tool_decision, e negli eventi safety_event eccetto quelli per la fine di un turno

Evento del prompt dell'utente

Registrato quando viene inviato un prompt, inclusi i turni che Claude Code avvia autonomamente.

Nome dell'evento: claude_code.user_prompt

Attributi:

• Tutti gli attributi standard
• event.name: "user_prompt"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• prompt_length: Lunghezza del prompt
• prompt: Contenuto del prompt. Oscurato per impostazione predefinita. Imposta OTEL_LOG_USER_PROMPTS=1 per includerlo
• prompt_text: Stesso valore di prompt, oscurato con la stessa condizione. Un backend che memorizza i nomi di attributi con punti come oggetti annidati legge prompt.id come id all'interno di un oggetto chiamato prompt e può perdere la stringa del prompt. In quel caso leggi invece prompt_text. Richiede Claude Code v2.1.287 o successiva
• message.uuid: UUID del messaggio utente risultante, corrispondente alla voce salvata nella trascrizione. Assente nell'invio di comandi, che può produrre zero o più messaggi.
• command_name: Nome del comando quando il prompt ne invoca uno. I nomi dei comandi integrati e inclusi nel pacchetto, come compact o debug, vengono emessi così come sono; gli alias come reset vengono emessi come digitati anziché con il nome canonico. I nomi dei comandi personalizzati, dei plugin e MCP vengono ridotti a custom o mcp a meno che non sia impostato OTEL_LOG_TOOL_DETAILS=1
• command_source: Origine del comando, quando presente: builtin, custom o mcp. I comandi forniti dai plugin vengono riportati come custom

Evento della risposta dell'assistente

Registrato dopo ogni richiesta API che restituisce contenuto testuale dal modello. Sono inclusi solo i blocchi di testo della risposta; i blocchi di ragionamento e di uso degli strumenti sono esclusi.

Nome dell'evento: claude_code.assistant_response

Attributi:

• Tutti gli attributi standard
• event.name: "assistant_response"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• response_length: Lunghezza del testo della risposta in caratteri
• response: Testo della risposta, troncato al limite del contenuto (60 KB per impostazione predefinita). Oscurato come <REDACTED> per impostazione predefinita. Imposta OTEL_LOG_ASSISTANT_RESPONSES=1 per includerlo. Quando OTEL_LOG_ASSISTANT_RESPONSES non è impostato, lo controlla invece OTEL_LOG_USER_PROMPTS, quindi imposta OTEL_LOG_ASSISTANT_RESPONSES=0 per mantenere oscurate le risposte mentre la registrazione dei prompt è attiva
• model: Identificatore del modello (ad esempio, "claude-sonnet-5")
• request_id: ID della richiesta API, descritto in Attributi di correlazione degli eventi
• message.uuid: UUID della voce finale della trascrizione della risposta. Una risposta API viene salvata come una voce della trascrizione per ogni blocco di contenuto; questa è l'ultima, da cui si concatena il parentUuid del turno successivo.
• query_source: Sottosistema che ha emesso la richiesta, ad esempio "repl_main_thread", "compact" o il nome di un subagent

Evento del risultato dello strumento

Registrato quando uno strumento completa l'esecuzione. Non viene emesso se la chiamata allo strumento è stata rifiutata; per i rifiuti consulta l'evento di decisione sullo strumento.

Nome dell'evento: claude_code.tool_result

Attributi:

• Tutti gli attributi standard
• event.name: "tool_result"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• tool_name: Nome dello strumento
• tool_use_id: Identificatore univoco di questa invocazione dello strumento. Corrisponde al tool_use_id passato agli hook, consentendo la correlazione tra gli eventi OTel e i dati acquisiti dagli hook.
• request_id: il request_id della risposta API che conteneva questa chiamata allo strumento, così puoi collegare la chiamata agli eventi API di quella risposta. Assente quando quella risposta non aveva un ID di richiesta o quando nessuna risposta API conteneva la chiamata. Richiede Claude Code v2.1.310 o successivo
• success: "true" o "false"
• duration_ms: Tempo di esecuzione in millisecondi
• error_type: Stringa della categoria di errore quando lo strumento non è riuscito, ad esempio "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: Provenienza della decisione sul permesso. Uno tra "config", "hook", "user_permanent" o "user_temporary". Consulta l'evento di decisione sullo strumento per il significato di ciascun valore. Le fonti esclusive dei rifiuti "user_abort" e "user_reject" non compaiono mai in questo evento.
• tool_input_size_bytes: Dimensione in byte dell'input dello strumento serializzato in JSON
• tool_result_size_bytes: Dimensione in byte del risultato dello strumento
• mcp_server_scope: Identificatore dell'ambito del server MCP (per gli strumenti MCP)
• vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (quando OTEL_LOG_TOOL_DETAILS=1): l'identità del commit di un git commit riuscito eseguito dallo strumento Bash o PowerShell. vcs.ref.head.revision è lo SHA del commit, vcs.ref.head.name è il branch su cui è stato eseguito il commit e vcs.ref.head.type è branch. Il nome e il tipo vengono omessi quando il commit è stato eseguito su un HEAD scollegato. Richiede Claude Code v2.1.269 o successiva
• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): Stringa JSON contenente i parametri specifici dello strumento. Per i server integrati di Claude Desktop, nelle sessioni di proprietà di Claude Desktop, la coppia mcp_server_name/mcp_tool_name è inclusa anche con il flag disattivato, la stessa eccezione definita dall'host dell'evento di decisione sullo strumento. I parametri variano a seconda dello strumento:
  • Per lo strumento Bash: include bash_command, full_command, timeout, description e dangerouslyDisableSandbox, più git_commit_id e git_branch quando un comando git commit riesce. git_commit_id è lo SHA completo del commit quando il commit è l'HEAD della directory di lavoro della sessione, e lo SHA abbreviato di git altrimenti. git_branch è il branch su cui è stato eseguito il commit, omesso su un HEAD scollegato
  • Per lo strumento Bash del workspace dell'app desktop, che riporta anch'esso tool_name come Bash: 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 il precedente strumento Task: include subagent_type
• tool_input (quando OTEL_LOG_TOOL_DETAILS=1): Argomenti dello strumento serializzati in JSON. I singoli valori oltre 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 dell'evento: claude_code.api_request

Attributi:

• Tutti gli attributi standard
• event.name: "api_request"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• model: Modello utilizzato (ad esempio, "claude-sonnet-5")
• cost_usd: Costo stimato in USD
• cost_usd_micros: Costo stimato in milionesimi di dollaro statunitense, emesso come intero
• duration_ms: Durata della richiesta in millisecondi
• input_tokens: Numero di token di input, esclusi i token letti dalla cache dei prompt o scritti in essa
• 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
• cache_creation_5m_tokens, cache_creation_1h_tokens: il numero di token che la risposta API riporta come scritti nella cache con una durata della cache di cinque minuti e il numero di quelli scritti con una durata di un'ora. Entrambi valgono 0 quando la risposta API non li riporta, anche quando cache_creation_tokens è maggiore di zero. Richiede Claude Code v2.1.300 o successiva
• request_id: ID della richiesta API, ad esempio "req_011...", descritto in Attributi di correlazione degli eventi.
• client_request_id: UUID generato dal client e inviato come header di richiesta x-client-request-id; consulta la tabella degli attributi di correlazione degli eventi per sapere quando è presente
• speed: "fast" o "normal", a indicare se la modalità veloce era attiva
• query_source: Sottosistema che ha emesso la richiesta, ad esempio "repl_main_thread", "compact" o il nome di un subagent
• effort: Livello di sforzo applicato alla richiesta: "low", "medium", "high", "xhigh" o "max". Assente quando Claude Code non invia alcun livello di sforzo, ad esempio con un modello che 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. Consulta Contatore dei costi per le definizioni e il comportamento di oscuramento.

Evento di errore API

Registrato quando una richiesta API a Claude non riesce.

Nome dell'evento: claude_code.api_error

Attributi:

• Tutti gli attributi standard
• event.name: "api_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• 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 gli errori di connessione.
• duration_ms: Durata della richiesta in millisecondi
• attempt: Numero di tentativi effettuati, inclusa la richiesta iniziale. Rilevare l'esaurimento dei nuovi tentativi indica quando il conteggio ricomincia
• request_id: ID della richiesta API, ad esempio "req_011...", descritto in Attributi di correlazione degli eventi.
• client_request_id: UUID generato dal client e inviato come header di richiesta x-client-request-id. Disponibile anche quando un errore come un timeout o un errore di connessione non ha mai prodotto un request_id del server; consulta la tabella degli attributi di correlazione degli eventi per sapere quando è presente.
• speed: "fast" o "normal", a indicare se la modalità veloce era attiva
• query_source: Sottosistema che ha emesso la richiesta, ad esempio "repl_main_thread", "compact" o il nome di un subagent
• effort: Livello di sforzo applicato alla richiesta. Assente quando Claude Code non invia alcun livello di sforzo, ad esempio con un modello che 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. Consulta Contatore dei costi per le definizioni e il comportamento di oscuramento.

Evento di rifiuto API

Registrato quando una richiesta API restituisce stop_reason: "refusal". I rifiuti arrivano in uno stream di risposta riuscito anziché come errore HTTP, quindi l'evento api_error non viene attivato per essi. Questo evento ti consente di monitorare la frequenza dei rifiuti e di raggrupparli per gli stessi attributi di api_request e api_error.

Nome dell'evento: claude_code.api_refusal

Attributi:

• Tutti gli attributi standard
• event.name: "api_refusal"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• model: Identificatore del modello dalla richiesta
• request_id: ID della richiesta API, ad esempio "req_011...", descritto in Attributi di correlazione degli eventi.
• query_source: Sottosistema che ha emesso la richiesta, ad esempio "repl_main_thread", "compact" o il nome di un subagent. Consulta api_request per le definizioni.
• speed: "fast" quando la modalità veloce è attiva, oppure "normal"
• attempt: Numero del tentativo. Il primo tentativo è 1.
• effort: Livello di sforzo applicato alla richiesta. Assente quando Claude Code non invia alcun livello di sforzo, ad esempio con un modello che non supporta lo sforzo.
• server_fallback_hop: true quando il fallback del modello lato server dell'API ha già riprovato questo rifiuto su un modello diverso, quindi l'utente non ha visto questo particolare rifiuto. false quando la richiesta si è conclusa con un rifiuto. Un singolo turno può emettere sia un evento di passaggio true sia un successivo evento finale false quando anche il modello di fallback rifiuta.
• has_category: true quando la risposta API conteneva un stop_details.category con valore "cyber", "bio", "frontier_llm" o "reasoning_extraction". false quando la risposta non conteneva alcuna categoria o un valore al di fuori di questo insieme. Assente quando server_fallback_hop è true, perché i blocchi di passaggio non contengono stop_details.
• has_explanation: true quando la risposta API conteneva un stop_details.explanation, altrimenti false. Assente quando server_fallback_hop è true.
• category: Il valore stop_details.category dalla risposta API. Uno tra "cyber", "bio", "frontier_llm" o "reasoning_extraction". Presente solo quando è impostato OTEL_LOG_TOOL_DETAILS=1 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. Consulta Contatore dei costi per le definizioni e il comportamento di oscuramento.

Evento del corpo della richiesta API

Registrato per ogni tentativo di richiesta API quando OTEL_LOG_RAW_API_BODIES è impostato. Viene emesso un evento per tentativo, quindi i nuovi tentativi con parametri modificati producono ciascuno il proprio evento.

Nome dell'evento: claude_code.api_request_body

Attributi:

• Tutti gli attributi standard
• event.name: "api_request_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• body: Parametri della richiesta Messages API serializzati in JSON, come il prompt di sistema, i messaggi e gli strumenti, troncati al limite del contenuto (60 KB per impostazione predefinita). Il contenuto del ragionamento esteso nei turni precedenti dell'assistente viene oscurato. Emesso solo in modalità inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Percorso assoluto di 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>, oppure unità di codice UTF-16 quando =1
• body_truncated: "true" quando si è verificato un 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")
• request_body_id: UUID che identifica il corpo della richiesta di questo tentativo. L'evento api_response_body del tentativo riuscito contiene lo stesso valore, così puoi associare una risposta alla richiesta esatta che l'ha prodotta. Richiede Claude Code v2.1.274 o successiva

Evento del corpo della risposta API

Registrato per ogni risposta API riuscita quando OTEL_LOG_RAW_API_BODIES è impostato.

In modalità file (OTEL_LOG_RAW_API_BODIES=file:<dir>), Claude Code aggiunge anche una riga JSON a <dir>/index.jsonl per ogni risposta riuscita, con i campi timestamp, session_id, query_source, model, request_id, message_id, message_uuid, request_file e response_file. Leggilo per trovare i file di richiesta e risposta dietro un determinato messaggio della trascrizione senza interrogare il tuo backend di telemetria. Il file di indice richiede Claude Code v2.1.274 o successiva.

Nome dell'evento: claude_code.api_response_body

Attributi:

• Tutti gli attributi standard
• event.name: "api_response_body"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• body: Risposta della Messages API serializzata in JSON, inclusi id, blocchi di contenuto, utilizzo e motivo di arresto, troncata al limite del contenuto (60 KB per impostazione predefinita). Il contenuto del ragionamento esteso viene oscurato. Emesso solo in modalità inline (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Percorso assoluto di 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>, oppure unità di codice UTF-16 quando =1
• body_truncated: "true" quando si è verificato un 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, ad esempio "req_011...", descritto in Attributi di correlazione degli eventi.
• request_body_id: Il request_body_id dell'evento api_request_body a cui risponde questa risposta. Richiede Claude Code v2.1.274 o successiva
• message.id: ID del messaggio assegnato dall'API alla risposta, il campo id del corpo della risposta. Richiede Claude Code v2.1.274 o successiva
• message.uuid: UUID della voce finale della trascrizione della risposta. Insieme a request_body_id, collega un messaggio della trascrizione ai corpi di richiesta e risposta che lo hanno generato. Richiede Claude Code v2.1.274 o successiva

Evento di decisione sullo strumento

Registrato quando viene presa una decisione sul permesso di uno strumento (accettazione/rifiuto).

Nome dell'evento: claude_code.tool_decision

Attributi:

• Tutti gli attributi standard

• event.name: "tool_decision"

• event.timestamp: Timestamp ISO 8601

• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi

• tool_name: Nome dello strumento (ad esempio, "Read", "Edit", "Write", "NotebookEdit")

• tool_use_id: Identificatore univoco di questa invocazione dello strumento. Corrisponde al tool_use_id passato agli hook, consentendo la correlazione tra gli eventi OTel e i dati acquisiti dagli hook.

• request_id: il request_id della risposta API che conteneva questa chiamata allo strumento, così puoi collegare la chiamata agli eventi API di quella risposta. Assente quando quella risposta non aveva un ID di richiesta o quando nessuna risposta API conteneva la chiamata. Richiede Claude Code v2.1.310 o successivo

• decision: "accept" oppure "reject"

• tool_source: Sempre presente. La provenienza dello strumento, come insieme chiuso di valori definiti dalla CLI:

  • "builtin": gli strumenti propri della CLI
  • "mcp": server MCP in generale
  • "sdk_host_builtin_mcp": un server in-process integrato in Claude Desktop stesso, in una sessione di proprietà di Claude Desktop. Claude Desktop possiede una sessione che ha avviato da uno dei propri entrypoint, claude-desktop, claude-desktop-3p o local-agent, quando tale sessione non è un figlio annidato; le sessioni annidate, incluse quelle generate da Claude Code stesso, riportano questi server come "mcp"

• source: Provenienza della decisione:

  • "config": Decisione presa automaticamente senza chiedere, da una di queste fonti:

    • Impostazioni del progetto
    • Regole di consenso o di negazione nelle impostazioni personali dell'utente
    • Criterio gestito aziendale
    • Flag --allowedTools o --disallowedTools
    • La modalità di permesso attiva
    • Il classificatore della modalità auto, il cui verdetto viene registrato dallo stesso evento in classifier_verdict
    • Una concessione per il resto della sessione, data in una precedente richiesta di permesso nella stessa sessione interattiva della CLI
    • Lo strumento intrinsecamente sicuro

    Il valore source non indica quale di queste origini ha avuto corrispondenza. Per scoprire quale ha rifiutato una chiamata, cerca l'evento di sicurezza con lo stesso tool_use_id e leggi i suoi attributi category e rule_source. Alcune chiamate rifiutate non hanno un evento di sicurezza.

    Claude Code riporta "config" anche quando la richiesta di permesso stessa non riesce. Ad esempio, quella richiesta non riesce quando il callback canUseTool dell'Agent SDK o lo strumento --permission-prompt-tool restituisce un risultato non valido, o quando lo stream di input si chiude mentre la richiesta è in sospeso.

  • "hook": Un hook PreToolUse o PermissionRequest ha restituito la decisione.

  • "user_permanent": Emesso quando l'utente ha scelto "Yes, and don't ask again for ..." in una richiesta di permesso, il che salva una regola di consenso nelle sue impostazioni personali. Nella CLI interattiva viene emesso solo per quella scelta; le chiamate successive che corrispondono alla regola salvata emettono invece "config". Nelle sessioni dell'Agent SDK o non interattive -p, sia la scelta iniziale sia le successive corrispondenze alla regola emettono "user_permanent". Trattato come un'accettazione.

  • "user_temporary": Emesso quando l'utente ha scelto "Yes" in una richiesta di permesso per un'approvazione una tantum, o ha scelto un'opzione che concede l'accesso per il resto della sessione in una richiesta di modifica o lettura di file. Nella CLI interattiva viene emesso solo per la scelta stessa; le chiamate successive consentite da quella concessione limitata alla sessione emettono invece "config". Nelle sessioni dell'Agent SDK o non interattive -p, sia la scelta sia le corrispondenze successive emettono "user_temporary". Trattato come un'accettazione.

  • "user_abort": Emesso quando l'utente ha chiuso la richiesta di permesso senza rispondere. Nelle sessioni dell'Agent SDK e non interattive -p, questo include l'interruzione del turno mentre è in sospeso una richiesta di permesso canUseTool o --permission-prompt-tool. Trattato come un rifiuto.

  • "user_reject": Emesso quando l'utente ha scelto "No" quando gli è stato chiesto. Nella CLI interattiva viene emesso solo per quella scelta; le chiamate che corrispondono a una regola di negazione nelle impostazioni personali dell'utente emettono invece "config". Nelle sessioni dell'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.

• classifier_verdict: Il verdetto del classificatore della modalità auto per la chiamata, oppure il motivo per cui Claude Code ha negato la chiamata quando non è arrivato alcun verdetto. Richiede Claude Code v2.1.301 o successiva

  • "allow": il classificatore ha approvato la chiamata
  • "block": il classificatore ha bloccato la chiamata. Anche un controllo del classificatore che non riesce a metà può concludersi come "block", quindi un'interruzione parziale del classificatore può apparire come un aumento dei blocchi anziché come "unavailable"
  • "no_verdict": il controllo è stato eseguito ma non ha dato alcun verdetto utilizzabile, quindi Claude Code ha negato la chiamata. La negazione non significa che il classificatore abbia ritenuto la chiamata non sicura
  • "unavailable": la richiesta al classificatore non è riuscita, ad esempio per un rate limit, un timeout o un errore di connessione, quindi Claude Code ha negato la chiamata. Con la revisione del classificatore lato server, contrassegna anche una chiamata negata perché il server non ha restituito alcun verdetto di sicurezza

  L'attributo compare anche nelle chiamate in plan mode quando il classificatore esamina i comandi in plan mode. L'attributo è assente in questi casi:

  • Una regola di permesso di consenso o di negazione ha deciso la chiamata
  • Claude Code ha approvato la chiamata in modalità auto senza interpellare il classificatore
  • L'utente ha risposto alla richiesta che Claude Code ha mostrato dopo blocchi ripetuti
  • In un'esecuzione -p senza --permission-prompt-tool, Claude Code ha negato la chiamata dopo blocchi ripetuti perché non c'era nessuno a rispondere a una richiesta. Quell'evento riporta decision come "reject" e source come "config"

• classifier_category (quando OTEL_LOG_TOOL_DETAILS=1): Il nome della regola integrata indicata dal classificatore quando ha bloccato la chiamata, in minuscolo con trattini bassi, ad esempio "data_exfiltration" per la regola Data Exfiltration. Richiede Claude Code v2.1.301 o successivo. L'attributo è presente quando valgono entrambe queste condizioni:

  • classifier_verdict è "block"
  • Il classificatore ha indicato esattamente una regola, e quella regola è integrata anziché scritta da te

  Prima della v2.1.302, l'attributo era assente anche in qualsiasi blocco deciso dalla revisione del classificatore lato server.

• permission_mode: Modalità di permesso attiva quando è iniziato il controllo dei permessi di questa chiamata: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" o "auto". La modalità manuale appare come "default". Una chiamata di un subagent riporta la modalità di permesso del subagent anziché quella della sessione. Richiede Claude Code v2.1.301 o successiva

• tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): Stringa JSON contenente i parametri specifici dello strumento. Stessa forma dell'evento del risultato dello strumento, esclusi i campi successivi all'esecuzione come git_commit_id. I valori possono differire da tool_result per una chiamata accettata se la decisione sul permesso 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 a definire questi nomi; senza di essi, una chiamata rifiutata a uno di questi server integrati non sarebbe attribuibile nello stream predefinito. Per i server MCP configurati dall'utente, il tool_name dell'evento è sempre il valore letterale "mcp_tool", e i nomi del server e dello strumento compaiono solo in tool_parameters con il flag attivato; il contenuto degli argomenti richiede il flag in ogni caso.
  • Per lo strumento Bash: include bash_command, full_command, timeout, description, dangerouslyDisableSandbox. Anche lo strumento bash del workspace dell'app desktop riporta 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 il precedente strumento Task: include subagent_type

Se abbassi OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT dell'SDK OpenTelemetry al di sotto del numero di attributi di un evento tool_decision, l'SDK scarta gli attributi che Claude Code ha impostato per ultimi. L'SDK li scarta prima di qualsiasi altro attributo, in questo ordine, saltando quelli che l'evento non contiene:

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

permission_mode, classifier_category e classifier_verdict vengono scartati in questo ordine su Claude Code v2.1.302 o successivo. parent_agent_id, agent_id e request_id richiedono la v2.1.310 o successiva.

Evento di sicurezza

Registrato quando un controllo rifiuta una chiamata a uno strumento o richiede una richiesta di permesso, eccetto per le chiamate senza un evento di sicurezza. Registrato anche quando il proxy di rete della sandbox rifiuta una connessione o una richiesta, e quando un hook blocca un risultato. Richiede Claude Code v2.1.307 o successiva.

L'evento viene esportato insieme agli altri eventi e non ha un'impostazione separata. Gli attributi propri dell'evento non contengono testo dei comandi, percorsi di file, nomi host né nomi di server e strumenti MCP. Il record riporta anche gli attributi standard presenti in ogni evento, che possono includere workspace.host_paths e gli attributi del repository. Per vedere il comando o lo strumento MCP dietro un evento, imposta OTEL_LOG_TOOL_DETAILS=1 e leggi tool_parameters nell'evento tool_decision corrispondente.

Nome dell'evento: claude_code.safety_event

Attributi:

• Tutti gli attributi standard
• event.name: "safety_event"
• event.timestamp: timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• category: Il controllo o l'esito, un valore di categoria
• decision: "accept", "reject" o "sent_back" quando un hook ha bloccato un risultato o la fine di un turno
• decision_source: Chi o cosa ha deciso, un valore source di tool_decision oppure "other"
• reason_code: Il motivo del controllo, ad esempio "rule:policySettings", "mode:dontAsk", "hook:PreToolUse", "classifier:auto-mode", "bashMiss:too-complex" o "unknown"
• reason_type: Il tipo di motivo del controllo, ad esempio "rule", "subcommandResults", "mode", "hook", "classifier" o "asyncAgent"
• rule_source: Origine delle impostazioni della regola coinvolta, ad esempio "policySettings", "userSettings", "projectSettings", "localSettings", "flagSettings", "cliArg" o "session"
• grant_scope: "once" o "session" per una richiesta approvata senza salvare una regola in un file di impostazioni
• circuit_breaker: Il controllo di sicurezza integrato, ad esempio "dangerousRemoval", "outsideReadsBlocked" o "claudeSettingsFile"
• classifier_category: Con OTEL_LOG_TOOL_DETAILS=1, la regola integrata dietro un blocco della modalità auto, ad esempio "data_exfiltration"
• hook_event: "pre_tool_use" per un hook PreToolUse, oppure "post_tool_use", "post_tool_use_failure", "stop" o "subagent_stop" negli eventi "hook_review"
• tool_class: "bash" per Bash e Monitor, "powershell", "file" per Read, Edit, Write, NotebookEdit, Glob e Grep, "web" per WebFetch e WebSearch, "mcp" o "other"
• tool_name: Il nome dello strumento, ad esempio "Bash" per uno strumento integrato, oppure "mcp_tool", "skill_tool", "dynamic_tool" o "other_tool"
• tool_source: "builtin", "mcp" o "sdk_host_builtin_mcp", come in tool_decision
• permission_mode: La modalità di permesso della chiamata al momento del controllo: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" o "auto"
• tool_use_id: L'ID della chiamata, come in tool_decision e tool_result
• sandbox_violation_count: Quante connessioni o richieste distinte del comando della chiamata sono state rifiutate dal proxy di rete della sandbox, da "0" a "20" come stringa. I rifiuti vengono conteggiati per un comando in sandbox terminato in primo piano
• sandbox_enabled: "true" se il sandboxing è attivo per la sessione, altrimenti "false"

Questi sono gli attributi propri dell'evento quando una regola di negazione delle impostazioni gestite rifiuta un comando Bash:

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

Categorie degli eventi di sicurezza

Per trovare i rifiuti del proxy in qualsiasi category, filtra per un sandbox_violation_count presente e diverso da "0".

Chiamate senza un evento di sicurezza

Per trovare le chiamate rifiutate perché nessuno poteva rispondere a una richiesta senza categoria, cerca gli eventi tool_decision che riportano "reject" con source "config" e nessun evento di sicurezza che condivida il loro tool_use_id. Questi rifiuti si verificano in un'esecuzione -p senza né --permission-prompt-tool né --permission-prompts none.

Per chiamate come le seguenti, verifica la presenza di un evento tool_decision, poiché non hanno alcun evento di sicurezza eccetto gli eventi "sandbox_network", "sandbox_other" o "hook_review" inviati dopo la loro esecuzione:

• Una chiamata approvata in una richiesta senza categoria
• Una chiamata che un callback canUseTool o uno strumento --permission-prompt-tool ha approvato in una richiesta richiesta solo da un hook PreToolUse
• Una chiamata AskUserQuestion o ExitPlanMode, rifiutata o meno

Richieste senza categoria

Una richiesta non ha categoria quando nessun valore di category ne indica il controllo, ad esempio la richiesta della modalità default per una modifica all'interno della tua directory di lavoro.

Evento di modifica della modalità di permesso

Registrato quando cambia la modalità di permesso, ad esempio con il ciclo tramite Shift+Tab, l'uscita dal plan mode o un controllo del gate della modalità auto.

Per raggruppare le chiamate agli strumenti in base alla modalità di permesso in cui ciascuna è stata controllata, usa permission_mode nell'evento di decisione sullo strumento.

Nome dell'evento: claude_code.permission_mode_changed

Attributi:

• Tutti gli attributi standard
• event.name: "permission_mode_changed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• from_mode: La modalità di permesso precedente, ad esempio "default", "plan", "acceptEdits", "auto" o "bypassPermissions"
• to_mode: La nuova modalità di permesso
• trigger: Cosa ha causato la modifica, ad esempio "shift_tab", "exit_plan_mode" o "auto_gate_denied". Assente per alcune modifiche, ad esempio quando l'SDK imposta la modalità di permesso tramite setPermissionMode()

Evento di autenticazione

Registrato quando /login o /logout viene completato.

Nome dell'evento: claude_code.auth

Attributi:

• Tutti gli attributi standard
• event.name: "auth"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• action: "login" o "logout"
• success: "true" o "false"
• auth_method: Metodo di autenticazione, ad esempio "oauth"
• error_category: Tipo di errore categoriale 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 dell'evento: claude_code.mcp_server_connection

Attributi:

• Tutti gli attributi standard
• event.name: "mcp_server_connection"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• status: "connected", "failed" o "disconnected"
• transport_type: Trasporto del server, ad esempio "stdio", "sse" o "http"
• server_scope: Ambito in cui è configurato il server, ad esempio "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 esporne 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 è la stringa letterale "third-party" a meno che non sia impostato OTEL_LOG_TOOL_DETAILS=1; questo impedisce che i nomi dei plugin di terze parti compaiano nei log per impostazione predefinita. I plugin provenienti da fonti ufficiali Anthropic sono sempre identificati per nome. Gli attributi plugin_id_hash e plugin.name arrivano al tuo backend di monitoraggio e non vengono inviati ad Anthropic
• server_name (quando OTEL_LOG_TOOL_DETAILS=1): Nome configurato del server
• error (quando OTEL_LOG_TOOL_DETAILS=1): Messaggio di errore completo quando la connessione non è riuscita

Evento di errore interno

Registrato quando Claude Code intercetta un errore interno imprevisto. Vengono registrati solo il nome della classe di errore e un codice in stile errno. Il messaggio di errore e lo stack trace non vengono mai inclusi. Questo evento non viene emesso quando si usa Amazon Bedrock, Agent Platform di Google Cloud o Microsoft Foundry, oppure quando è impostato DISABLE_ERROR_REPORTING.

Nome dell'evento: claude_code.internal_error

Attributi:

• Tutti gli attributi standard
• event.name: "internal_error"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• error_name: Nome della classe di errore, ad esempio "TypeError" o "SyntaxError"
• error_code: Codice errno di Node.js, ad esempio "ENOENT", quando presente nell'errore

Evento di plugin installato

Registrato quando un plugin termina l'installazione, sia dal comando CLI claude plugin install sia dall'interfaccia interattiva /plugin.

Nome dell'evento: claude_code.plugin_installed

Attributi:

• Tutti gli attributi standard
• event.name: "plugin_installed"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• 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 è 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 è inclusa solo quando OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace da cui è stato installato il plugin. Per i marketplace di terze parti è 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 fare l'inventario dei plugin attivi nel tuo parco macchine, come complemento a plugin_installed, che registra l'azione di installazione stessa.

Nome dell'evento: claude_code.plugin_loaded

Attributi:

• Tutti gli attributi standard
• event.name: "plugin_loaded"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• plugin.name: nome del plugin. Per i plugin esterni al marketplace ufficiale e al pacchetto integrato il valore è "third-party" a meno che non sia impostato OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: marketplace da cui è stato installato il plugin, quando noto. Oscurato come "third-party" alla stessa condizione di plugin.name
• plugin.version: versione dal manifest del plugin. Inclusa solo quando il nome non è oscurato e il manifest dichiara una versione
• plugin.scope: categoria di provenienza del plugin: "official", "community", "org", "user-local" o "default-bundle"
• enabled_via: modo in cui 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 a installazione automatica per la tua organizzazione in Organization settings > Plugins & skills. Prima della v2.1.246, Claude Code riportava questi plugin come "user-install" o "seed-mount"
• plugin_id_hash: hash deterministico del nome del plugin e del marketplace, inviato solo al tuo exporter configurato. Ti consente di contare i plugin di terze parti distinti caricati nel tuo parco macchine senza registrarne i nomi. Per i plugin sincronizzati da claude.ai, Claude Code calcola l'hash del nome del plugin con il nome del marketplace che claude.ai riporta per il plugin, oppure con synced altrimenti. Prima della v2.1.246, Claude Code non usava nell'hash il nome del marketplace riportato da claude.ai
• has_hooks: se il plugin fornisce hook, tramite la configurazione degli hook o come mod
• has_mcp: se il plugin fornisce server MCP
• host_owned_mcp: true quando l'host dell'SDK gestisce le connessioni MCP di questo plugin e Claude Code ha saltato la lettura della configurazione dei server MCP del plugin, false altrimenti
• skill_path_count: numero di directory di skill dichiarate dal plugin
• command_path_count: numero di directory di comandi dichiarate dal plugin
• agent_path_count: numero di directory di agenti dichiarate dal plugin
• safe_mode: "true" quando la sessione è stata avviata con --safe-mode, "false" altrimenti. In modalità sicura questo evento riporta solo l'inventario configurato; i comandi, le skill, gli hook e i server MCP del plugin non vengono caricati. Richiede Claude Code v2.1.169 o successiva

Evento di skill attivata

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

Nome dell'evento: claude_code.skill_activated

Attributi:

• Tutti gli attributi standard
• event.name: "skill_activated"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• skill.name: Nome della skill. Per le skill definite dall'utente e quelle dei plugin di terze parti il valore è il segnaposto "custom_skill" a meno che non sia impostato OTEL_LOG_TOOL_DETAILS=1
• invocation_trigger: Modo in cui è stata attivata la skill ("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 proviene 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 proviene da un marketplace ufficiale): Marketplace da cui è stato installato il plugin proprietario, quando la skill è fornita da un plugin

Evento di menzione con @

Registrato quando Claude Code risolve una menzione @ in un prompt. Non tutte le menzioni emettono un evento: i percorsi di uscita anticipata, come i permessi negati, i file troppo grandi, gli allegati di riferimento PDF e gli errori nell'elenco delle directory, terminano senza registrare nulla.

Ogni volta che Claude Code legge un prompt, registra al massimo 100 eventi con mention_type pari a "agent" e 100 con "mcp_resource". Le menzioni oltre uno dei due limiti vengono comunque risolte ma non emettono alcun evento.

Nome dell'evento: claude_code.at_mention

Attributi:

• Tutti gli attributi standard
• event.name: "at_mention"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• mention_type: Tipo di menzione ("file", "directory", "agent", "mcp_resource", "peer"). Il valore "peer" significa che hai menzionato una delle tue altre sessioni di Claude Code. Richiede Claude Code v2.1.232 o successiva
• success: Se la menzione è stata risolta correttamente ("true" o "false")

Evento di nuovi 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 dell'evento: claude_code.api_retries_exhausted

Attributi:

• Tutti gli attributi standard
• event.name: "api_retries_exhausted"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• 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 reale totale su 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 fare l'inventario degli hook attivi nel tuo parco macchine, come complemento agli eventi per singola esecuzione hook_execution_start e hook_execution_complete.

Nome dell'evento: claude_code.hook_registered

Attributi:

• Tutti gli attributi standard
• event.name: "hook_registered"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• hook_event: tipo di evento dell'hook, ad esempio "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 successiva
• hook_matcher (quando OTEL_LOG_TOOL_DETAILS=1): la stringa del matcher dalla configurazione dell'hook, quando impostata
• plugin.name (quando hook_source è "pluginHook"): nome del plugin che fornisce l'hook. Per i plugin esterni al marketplace ufficiale e al pacchetto integrato il valore è "third-party" a meno che non sia impostato 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 exporter configurato. Ti consente di contare i plugin distinti che forniscono hook senza registrarne i nomi. Claude Code lo calcola come descritto nell'evento di plugin caricato

Evento di avvio dell'esecuzione degli hook

Registrato quando uno o più hook iniziano l'esecuzione per un evento di hook.

Nome dell'evento: claude_code.hook_execution_start

Attributi:

• Tutti gli attributi standard
• event.name: "hook_execution_start"
• event.timestamp: Timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• hook_event: Tipo di evento dell'hook, ad esempio "PreToolUse" o "PostToolUse"
• hook_name: Nome completo dell'hook incluso il matcher, ad esempio "PreToolUse:Write"
• num_hooks: Numero di comandi hook corrispondenti
• managed_only: "true" quando sono consentiti solo gli hook dei criteri gestiti
• 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 successiva
• hook_definitions: Configurazione dell'hook serializzata in JSON. Inclusa solo quando sono abilitati sia il tracing beta dettagliato sia OTEL_LOG_TOOL_DETAILS=1

Evento di completamento dell'esecuzione degli hook

Registrato quando tutti gli hook per un evento hook sono terminati.

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 per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• hook_event: tipo di evento hook
• hook_name: nome completo dell'hook, incluso il matcher
• num_hooks: numero di comandi hook corrispondenti
• num_success: numero di quelli completati correttamente
• num_blocking: numero di quelli che hanno restituito una decisione bloccante
• num_non_blocking_error: numero di quelli che non sono riusciti senza bloccare
• num_cancelled: numero di quelli annullati prima del completamento
• total_duration_ms: durata in tempo reale di tutti gli hook corrispondenti
• stdout_chars: caratteri totali di stdout tra gli hook corrispondenti completati correttamente. Richiede Claude Code v2.1.280 o successiva
• additional_context_chars: caratteri totali di additionalContext restituiti dagli hook corrispondenti. Richiede Claude Code v2.1.280 o successiva
• system_message_chars: caratteri totali di systemMessage restituiti dagli hook corrispondenti. Richiede Claude Code v2.1.280 o successiva
• initial_user_message_chars: caratteri totali di initialUserMessage restituiti dagli hook corrispondenti. Richiede Claude Code v2.1.280 o successiva
• num_outputs_persisted: numero di output degli hook oltre il limite di 10.000 caratteri che Claude Code ha salvato in un file. Richiede Claude Code v2.1.280 o successiva
• managed_only: "true" quando sono consentiti solo gli hook delle policy gestite
• 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 successiva
• hook_definitions: configurazione degli hook serializzata in JSON. Inclusa solo quando sono abilitati sia il tracing beta dettagliato sia OTEL_LOG_TOOL_DETAILS=1

Evento delle metriche dei plugin hook

Registrato quando un hook di un plugin del marketplace ufficiale emette metriche per singola invocazione. Solo i plugin installati da un marketplace ufficiale di Anthropic possono emetterle. I plugin di marketplace di terze parti e gli hook configurati dall'utente non emettono questo evento. Usa questo evento per monitorare il comportamento dei plugin, come tassi di rilevamento, costi e 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 per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• plugin_id: identificatore del plugin nel formato <name>@<marketplace>
• hook_event: tipo di evento hook che ha emesso le metriche
• Fino a 20 chiavi di metrica emesse dal plugin. I nomi corrispondono a ^[a-z][a-z0-9_]{0,39}$. I valori sono booleani o numerici.

Evento di compattazione

Registrato al completamento della compattazione della conversazione.

Nome evento: claude_code.compaction

Attributi:

• Tutti gli attributi standard
• event.name: "compaction"
• event.timestamp: timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• trigger: "auto" o "manual"
• success: "true" o "false"
• duration_ms: durata della compattazione
• pre_tokens: numero approssimativo di token prima della compattazione
• post_tokens: numero approssimativo di token dopo la compattazione
• error: messaggio di errore quando la compattazione non è riuscita
• precompute_reuse: impostato solo quando trigger è "manual", oppure quando trigger è "auto" per una compattazione in inattività in una sessione interattiva nel terminale. La compattazione automatica può preparare un riepilogo in background prima che la finestra di contesto si riempia, e questo attributo registra se la compattazione ha riutilizzato quel riepilogo preparato. "hit" indica che è stato riutilizzato; "miss_custom_instructions", "miss_hook" e "miss_not_ready" indicano il motivo per cui è stato invece calcolato un nuovo riepilogo

Evento di completamento del subagent

Registrato quando un subagent termina e restituisce il suo risultato alla conversazione che lo ha avviato. Usalo per aggregare l'uso degli strumenti e il tempo di esecuzione per tipo di subagent; per aggregare token o costi, usa il contatore dei token e il contatore dei costi filtrati per query_source "subagent", poiché il total_tokens di questo evento copre solo la richiesta finale. La categoria "subagent" conta anche le richieste degli 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 per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• agent_type: il tipo di subagent. I nomi degli agenti integrati e degli agenti dei plugin del marketplace ufficiale appaiono testualmente; gli altri nomi di agenti sono sostituiti con "custom" a meno che non sia impostato OTEL_LOG_TOOL_DETAILS=1
• agent.source: la provenienza della definizione dell'agente: built-in, plugin o l'origine delle impostazioni che ha definito un agente personalizzato, come userSettings o projectSettings
• is_built_in: se il subagent è un tipo di agente integrato
• is_async: se il subagent è stato eseguito in background
• total_tokens: l'impronta in token della richiesta API finale del subagent: i token di input, creazione della cache, lettura della cache e output di quella sola richiesta, approssimativamente la dimensione del contesto del subagent al completamento. Non è una somma sull'intera esecuzione
• total_tool_uses: numero di chiamate agli strumenti effettuate dal subagent nell'intera esecuzione
• duration_ms: tempo di esecuzione in millisecondi
• model: il modello con cui è stato risolto il subagent
• final_model: il modello che ha prodotto la risposta finale del subagent, che differisce da model dopo un cambio durante l'esecuzione, come un fallback
• model_swapped: se più di un modello ha servito le richieste del subagent
• plugin_id_hash, plugin.name: presenti per gli agenti forniti da plugin. I nomi dei plugin del marketplace ufficiale appaiono testualmente; gli altri nomi di plugin sono sostituiti con "third-party" a meno che non sia impostato OTEL_LOG_TOOL_DETAILS=1

Evento del sondaggio di feedback

Registrato quando un sondaggio sulla qualità della sessione viene mostrato o riceve una risposta. Consulta 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 per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• 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 una singola istanza del sondaggio
• survey_type: quale sondaggio ha prodotto l'evento. "session" è il prompt di valutazione "How is Claude doing?"
• response: la selezione dell'utente negli eventi responded
• enabled_via_override: true quando è impostato CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL. Emesso come booleano, non come stringa. Presente negli eventi del sondaggio session. Filtra su questo attributo per verificare che l'override sia applicato su un'intera flotta

Evento della pulizia per conservazione

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

Come ogni evento OTel in questa pagina, viene inviato solo al backend di telemetria che configuri. Richiede Claude Code v2.1.227 o successiva.

Leggi result per sapere se la pulizia è stata eseguita:

• "complete": la pulizia è stata eseguita e l'evento riporta i relativi conteggi
• "skipped": Claude Code non è riuscito a determinare in modo sicuro il periodo di conservazione, quindi ha sospeso la pulizia e l'evento non riporta conteggi. Se skip_reason è "settings_unknowable" o "settings_invalid_key_set", correggi l'errore nelle impostazioni che /status segnala su quella macchina, in modo che una sessione successiva possa eseguire la pulizia

Quando le impostazioni gestite impostano cleanupPeriodDays, il valore gestito fissa il periodo di conservazione e la pulizia viene eseguita anche quando un file di impostazioni in un ambito a priorità inferiore è danneggiato o non valido.

Nome evento: claude_code.retention_sweep

Attributi:

• Tutti gli attributi standard
• event.name: "retention_sweep"
• event.timestamp: timestamp ISO 8601
• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi
• result: "complete" quando la pulizia è stata eseguita, "skipped" quando Claude Code l'ha sospesa
• period_days: il periodo di conservazione con cui è iniziata la pulizia, in giorni: cleanupPeriodDays dalle impostazioni combinate, con l'eventuale modifica di un hook settings.read applicata. 30 quando in questo modo la chiave resta non impostata. Negli eventi saltati, il valore che la pulizia avrebbe usato, calcolato dalle origini delle impostazioni che Claude Code è riuscito a leggere
• used_default: "true" quando period_days è ricaduto sul valore 30, "false" altrimenti. Negli eventi completati, "true" indica che è stato applicato il valore predefinito di 30 giorni
• skip_reason: perché Claude Code ha sospeso la pulizia. 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 origine abilitata fornisce cleanupPeriodDays
  • "settings_unknowable": un file di impostazioni non può essere letto o analizzato, quindi cleanupPeriodDays o desktopSessionCleanupPeriodDays potrebbero essere impostati su un valore che Claude Code non può vedere
  • "settings_invalid_key_set": le impostazioni presentano errori di validazione e cleanupPeriodDays o desktopSessionCleanupPeriodDays è impostato esplicitamente, quindi ripiegare sul valore predefinito potrebbe eliminare o conservare file in contrasto con tale impostazione
  • "remote_settings_unknowable": una sessione nella scheda Code di Claude Desktop su un deploy di terze parti ha richiesto le impostazioni gestite dal server. Non ha ricevuto alcuna risposta utilizzabile, quindi cleanupPeriodDays potrebbe essere impostato su un valore che Claude Code non può vedere
• transcripts_deleted: numero di trascrizioni delle sessioni, i file di primo livello ~/.claude/projects/*/*.jsonl, eliminate dalla pulizia
• transcripts_exempted_desktop: numero di trascrizioni oltre il periodo di conservazione che la pulizia ha conservato in base alla regola di Claude Desktop e Cowork. Queste non vengono conteggiate in files_past_cutoff. Richiede Claude Code v2.1.248 o successiva
• session_files_deleted: numero di artefatti eliminati dalla pulizia dei file di sessione: le trascrizioni più i file associati a ciascuna sessione, come sidecar, registrazioni e risultati degli strumenti
• artifacts_deleted: numero totale di elementi eliminati dalla pulizia nelle directory di dati che copre, inclusi i file di sessione. Alcune pulizie contano un intero albero di directory rimosso come un solo elemento e alcuni passaggi di pulizia non contribuiscono al contatore, quindi considera il valore come un minimo anziché un conteggio esatto dei file
• files_retained_fresh: file ispezionati e lasciati al loro posto perché ancora entro il periodo di conservazione. Solo le pulizie per singolo file li conteggiano, quindi il valore è un minimo; un valore diverso da zero è il normale stato a regime
• files_past_cutoff: file più vecchi del periodo di conservazione che la pulizia non è riuscita a eliminare, ad esempio a causa di un errore di permessi o di un file tenuto aperto. Il conteggio include anche ogni cartella obsoleta che la pulizia trova in skills/synced/ o plugins/synced/, indipendentemente dal fatto che sposti o meno la cartella nel cestino. A parte queste cartelle, un valore superiore a zero significa che alcuni file sono sopravvissuti oltre il periodo di conservazione configurato; zero non è la prova che nessuno lo abbia fatto, perché una rimozione non riuscita di un'intera directory viene invece conteggiata in error_count
• error_count: numero di errori incontrati dalla pulizia durante l'elenco o l'eliminazione dei file

Evento di risoluzione delle impostazioni gestite

Registrato con le impostazioni gestite risolte da una sessione: una volta all'avvio della sessione, di nuovo quando le impostazioni gestite o lo stato dell'helper di policy cambiano durante la sessione, e quando Claude Code si rifiuta di avviarsi o termina la sessione per uno dei motivi elencati dall'attributo error.type. Usa questo evento per individuare le macchine che operano con un'origine gestita inattesa, le macchine il cui helper di policy non funziona e il motivo per cui una macchina si è rifiutata di avviarsi. Richiede Claude Code v2.1.274 o successiva.

Per impostazione predefinita, l'evento contiene le origini gestite e lo stato dell'helper di policy, ma non le impostazioni stesse. Per aggiungere l'attributo redatto managed_settings.settings e il digest managed_settings.resolved_sha256, imposta OTEL_LOG_MANAGED_SETTINGS=1:

• Impostalo nel blocco env delle impostazioni gestite, delle impostazioni utente o di --settings, oppure nell'ambiente con cui avvii Claude Code. Un valore nelle impostazioni di progetto o locali non lo attiva, perché un repository clonato può scriverle.
• Le impostazioni gestite dal server possono impostarlo senza mostrare la finestra di dialogo di approvazione di sicurezza, perché la variabile aggiunge solo la policy redatta della tua organizzazione a un evento che la tua organizzazione riceve già.

In una sessione interattiva in una cartella che non hai considerato attendibile, Claude Code non esporta l'evento di rifiuto.

Nome evento: claude_code.managed_settings_resolved

Attributi:

• Tutti gli attributi standard

• event.name: "managed_settings_resolved"

• event.timestamp: timestamp ISO 8601

• event.sequence: contatore per processo per ordinare gli eventi, descritto in Attributi di correlazione degli eventi

• managed_settings.trigger: "startup" per l'evento di avvio della sessione, "change" quando le impostazioni gestite o lo stato dell'helper di policy sono cambiati più avanti nella sessione, oppure "refused" quando una policy delle impostazioni gestite ha interrotto la sessione. Claude Code invia un evento change solo quando un attributo differisce dall'ultimo evento inviato, e un valore di impostazione modificato conta anche quando OTEL_LOG_MANAGED_SETTINGS è disattivato

• error.type: il motivo per cui Claude Code ha interrotto la sessione. Presente solo negli eventi refused:

  • "helper_failed": un'esecuzione dell'helper di policy non è riuscita
  • "policy_invalid": le impostazioni gestite contengono un errore che impedisce a Claude Code di avviarsi, oppure un'origine di amministrazione non è stata caricata per un motivo diverso da una lettura negata, quindi Claude Code non può verificare il login dell'organizzazione o l'applicazione dei provider
  • "provider_not_allowed": la sessione userebbe un provider API, o invierebbe il traffico di un provider a un host, che l'elenco gestito allowedProviders non consente. Richiede Claude Code v2.1.285 o successiva
  • "consent_rejected": l'utente ha rifiutato la finestra di dialogo di approvazione di sicurezza per le impostazioni gestite dal server
  • "force_refresh_failed": il recupero delle impostazioni richiesto da forceRemoteSettingsRefresh non è riuscito
  • "gateway_rejected": un gateway delle app Claude ha risposto al caricamento delle impostazioni gestite con HTTP 403
  • "version_below_minimum": questa versione di Claude Code è inferiore a requiredMinimumVersion o superiore a requiredMaximumVersion
  • "_OTHER": il caricamento delle impostazioni gestite dal gateway delle app Claude non è riuscito per un altro motivo

• managed_settings.sources: ogni origine gestita che fornisce almeno una chiave di policy, dalla priorità più alta, incluse le origini le cui chiavi non hanno effetto con first-wins. I valori sono "remote", "plist" o "hklm" per la policy MDM o a livello di sistema operativo, "file" per i file di impostazioni gestite e i drop-in, "parent" quando un host di incorporamento fornisce impostazioni, e "hkcu" per il valore del registro HKCU di Windows quando Claude Code lo legge. Un'origine che contiene solo chiavi di controllo, o che Claude Code non è riuscito a leggere, non viene elencata. Emesso come array di stringhe, vuoto quando nessuna origine gestita fornisce una chiave di policy

• managed_settings.source_behavior: il valore di managedSourcesBehavior letto da Claude Code, "first-wins" o "merge". "first-wins" quando nessuna origine imposta la chiave

• managed_settings.helper.state: stato dell'helper di policy configurato dall'origine MDM o file selezionata:

  • "ok": l'output dell'helper funge da impostazioni gestite
  • "bad_path", "not_a_file", "exit_nonzero", "timed_out", "oversize", "parse_failed", "envelope_invalid" o "schema_rejected": l'ultima esecuzione dell'helper non è riuscita. Errori dell'helper descrive i casi
  • "none": nessun helper è configurato, oppure l'origine che lo configura non è una policy MDM o un file di impostazioni gestite

• managed_settings.helper.applied: "output" mentre l'output dell'helper funge da impostazioni gestite, "none" quando non è così

• managed_settings.helper.entry: "policyHelper" quando Claude Code ha selezionato un policyHelper. Assente quando non ha selezionato alcun helper

• managed_settings.helper.path: il path configurato per l'helper. Presente ogni volta che Claude Code ha selezionato un helper, indipendentemente dal fatto che OTEL_LOG_MANAGED_SETTINGS sia impostato

• managed_settings.resolved_sha256 (quando OTEL_LOG_MANAGED_SETTINGS=1): SHA-256 delle impostazioni gestite risolte prima della redazione, serializzate come JSON con chiavi ordinate ricorsivamente e senza spazi. Le macchine con lo stesso digest eseguono la stessa policy. Claude Code invia il digest solo con l'attivazione esplicita perché una policy breve può essere ricostruita calcolando l'hash di ipotesi. Assente quando non è stata risolta alcuna impostazione gestita, e negli eventi refused

• managed_settings.settings (quando OTEL_LOG_MANAGED_SETTINGS=1): i nomi e la struttura delle impostazioni gestite risolte come stringa JSON, con i valori redatti. Assente negli eventi refused. Claude Code lo costruisce a partire dal suo schema delle impostazioni:

  • Un nome di impostazione dichiarato dallo schema viene esportato, mentre una chiave non dichiarata viene omessa
  • I booleani, i numeri e i valori stringa che lo schema limita a un insieme fisso di opzioni, come permissions.defaultMode, vengono esportati così come sono. sandbox.network.httpProxyPort e sandbox.network.socksProxyPort vengono esportati come "[REDACTED]"
  • Ogni altra stringa, come model, apiKeyHelper, ogni valore di env, ogni URL e ogni comando, viene esportata come "[REDACTED]"
  • I nomi delle voci delle mappe, come i nomi delle variabili env e gli ID dei plugin, vengono esportati così come sono. Un'impostazione le cui voci non sono tipizzate dallo schema, come vimInsertModeRemaps, viene esportata come un singolo "[REDACTED]", e sandbox.ignoreViolations viene esportato come elenco dei suoi elenchi di percorsi senza i pattern dei comandi
  • Un elenco mantiene la sua lunghezza, con ogni voce redatta secondo le stesse regole
  • Una regola permissions.allow, permissions.deny o permissions.ask viene esportata come nome del suo strumento con il contenuto redatto, ad esempio Read([REDACTED]), quando lo strumento è integrato in questa versione di Claude Code o è un riferimento mcp__ come mcp__jira__create_issue. Qualsiasi altra regola viene esportata come "[REDACTED]"
  • Gli hook seguono le stesse regole, quindi i campi a opzioni fisse e numerici come type e timeout sono visibili, mentre ogni comando, URL, matcher e condizione if viene esportato come "[REDACTED]"

  Ad esempio, impostazioni gestite con apiKeyHelper, due variabili env e una regola di negazione vengono esportate come {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}.

  Claude Code tronca il valore a 8 KB di UTF-8, e il valore troncato non è JSON valido

• managed_settings.settings_truncated (quando managed_settings.settings è presente): true quando Claude Code ha troncato managed_settings.settings a 8 KB, false altrimenti. Emesso come booleano, non come stringa

Interpretazione dei dati di metriche e eventi

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

Monitoraggio dell'utilizzo

Per confrontare gli utenti attivi tra le superfici, imposta OTEL_METRICS_INCLUDE_ENTRYPOINT=true per aggiungere app.entrypoint a metriche ed eventi. Poi conta i valori distinti di user.account_uuid per entrypoint sugli eventi claude_code.user_prompt, oppure su claude_code.token.usage se esporti solo le metriche. Ad esempio, usa cli per le sessioni CLI interattive e raggruppa claude-desktop, claude-desktop-3p e remote_desktop per la scheda Code di Claude Desktop.

user.account_uuid non identifica le persone nelle sessioni dei canali Claude Tag ed è assente dalle sessioni senza un account Claude: consulta Attribuire le azioni agli utenti. Quando una persona avvia molte sessioni, o una sessione non riceve alcun prompt, claude_code.session.count aumenta senza aggiungere un utente attivo.

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

[!NOTE]

Le metriche di costo sono approssimazioni. Per i dati di fatturazione ufficiali, consulta Gestire i costi per la tua organizzazione.

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.

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 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 di tentativi. CLAUDE_CODE_MAX_RETRIES ha un valore predefinito di 10 ed è limitato a 15; con CLAUDE_CODE_RETRY_WATCHDOG impostato, il valore predefinito è più alto e non c'è alcun limite.

Quando la richiesta esaurisce tutti i nuovi tentativi su un errore transitorio, attempt è al massimo uno più di quel limite effettivo: 11 per impostazione predefinita.

Anche un valore inferiore può indicare che i nuovi tentativi sono stati esauriti: attempt riparte da 1 ogni volta che Claude Code invia di nuovo la richiesta dopo un errore di streaming.

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.

Mappare i token di input alle convenzioni semantiche GenAI di OpenTelemetry

Claude Code esporta i conteggi dei token di input così come appaiono nel blocco usage della risposta API, quindi questi valori escludono i token letti dalla o scritti nella cache del prompt:

• input_tokens sullo span claude_code.llm_request e sull'evento api_request
• Il tipo "input" della metrica claude_code.token.usage

Claude Code non imposta gli attributi gen_ai.usage.*. Le convenzioni semantiche GenAI di OpenTelemetry stabiliscono che gen_ai.usage.input_tokens dovrebbe includere i token letti dalla e scritti nella cache. Per calcolare questo totale:

• Dallo span o dall'evento: somma input_tokens, cache_read_tokens e cache_creation_tokens
• Dalla metrica claude_code.token.usage: somma i suoi tipi "input", "cacheRead" e "cacheCreation"

Le convenzioni definiscono anche attributi separati per le letture dalla cache e le scritture nella cache:

• cache_read_tokens corrisponde a gen_ai.usage.cache_read.input_tokens
• cache_creation_tokens corrisponde a gen_ai.usage.cache_write.input_tokens. Le versioni precedenti delle convenzioni chiamano l'attributo di scrittura nella cache gen_ai.usage.cache_creation.input_tokens, quindi usa il nome che il tuo backend si aspetta.

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 accedute a un Claude apps gateway tramite /login, dove è il soggetto IdP dal token emesso dal gateway.

In una sessione che uno sviluppatore avvia, le chiamate agli strumenti MCP, i comandi Bash e le modifiche ai file sono quindi attribuite a quello sviluppatore. 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. Nelle sessioni dei canali Claude Tag, Claude funziona come l'identità condivisa della vostra organizzazione.

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: vedete Attributi standard per l'identità che i loro export portano.

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

Mappa i percorsi di uscita ai controlli gestiti e agli eventi

La tabella associa i percorsi che possono portare il contenuto della sessione fuori da una macchina, più la conservazione locale, alle chiavi delle impostazioni gestite che li limitano e agli eventi che li registrano. Per ciò che Claude Code stesso invia ad Anthropic, come i report di /feedback, consulta Utilizzo dei dati. I nomi rimandano alle rispettive voci di riferimento, che riportano i valori e i valori predefiniti.

Le voci allowedHttpHookUrls, managed-mcp.json e degli eventi degli hook richiedono più di quanto mostra la tabella:

• allowedHttpHookUrls: le voci vengono sottoposte a merge tra i file di impostazioni, quindi uno sviluppatore può aggiungere voci a un elenco gestito vuoto. È allowManagedHooksOnly a decidere quali hook vengono eseguiti
• managed-mcp.json: per disattivare MCP, consulta Disable MCP entirely. Per confermare che Claude Code legga il file, consulta Validate the configuration
• Eventi degli hook: Claude Code registra hook_execution_start e hook_execution_complete una volta per ogni evento di hook, coprendo tutti gli hook corrispondenti. OTEL_LOG_TOOL_DETAILS=1 da solo non registra l'URL di un hook HTTP. La configurazione dell'hook compare solo in hook_definitions, che richiede anche il tracing beta dettagliato

OTEL_LOG_TOOL_DETAILS=1 aggiunge a questi eventi le stringhe dei comandi, i nomi dei server e degli strumenti e l'input degli strumenti. Quel dettaglio può contenere lo stesso contenuto sensibile della sessione stessa, quindi abilitalo solo quando il tuo collector è approvato per conservare quel contenuto.

Verifica la pulizia di conservazione

Per dare a ogni macchina lo stesso periodo di conservazione, imposta cleanupPeriodDays nelle impostazioni gestite. Per verificare che le macchine eseguano la pulizia con quel valore, raccogli l'evento retention_sweep. period_days e i contatori sono stringhe, quindi convertili in numeri prima di confrontarli.

Una macchina che funziona come previsto può non emettere eventi per motivi come questi:

• Nessuno avvia Claude Code: non viene eseguita alcuna pulizia e la macchina conserva i suoi dati fino al prossimo avvio
• Una sessione resta aperta: Claude Code esegue la pulizia al massimo una volta per sessione
• Una sessione termina in anticipo: una pulizia che non è terminata quando la sessione si chiude non emette nulla, e lo stesso vale per una che si interrompe per un errore imprevisto

La pulizia non copre ogni percorso. Kept until you delete them elenca ciò che rimane, e Clear local data mostra come rimuoverlo.

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, avviate Claude Code con claude --debug-file <path> e controllate il log 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:

Backend 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

Backend per eventi e 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

Backend per le 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 locali avviate dalla scheda Code nell'app Claude Desktop
• service.version: Versione corrente di Claude Code, o la versione dell'app Desktop per le sessioni locali 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 tuo collettore o i tuoi dashboard filtrano su service.name = claude-code, aggiungi claude-code-desktop al filtro per acquisire anche la telemetria dalle sessioni locali 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
• Per impostazione predefinita, i contenuti dei file grezzi e i frammenti di codice non sono inclusi nelle metriche o negli eventi. Se imposti una variabile come OTEL_LOG_TOOL_DETAILS o OTEL_LOG_RAW_API_BODIES, gli eventi possono includerli. Gli span di traccia 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. Quando abilitato:

  • Gli eventi user_prompt portano il testo del prompt in due attributi, prompt e prompt_text. Se nel tuo collector elimini o mascheri il testo del prompt dell'evento in base al nome dell'attributo, indica entrambi gli attributi nella regola

    Questo processore attributes di OpenTelemetry Collector elimina entrambi gli attributi nelle pipeline che lo elencano:

    processors:
      attributes/drop-prompt-text:
        actions:
          - key: prompt
            action: delete
          - key: prompt_text
            action: delete
    

  • Con il tracing attivo, lo span claude_code.interaction porta il testo del prompt nel suo attributo user_prompt

  • Sotto la traccia beta dettagliata, gli span portano anche i nuovi messaggi dell'utente, i risultati degli strumenti e i promemoria di sistema inviati con ogni richiesta, il testo del prompt di sistema e l'output del modello. Attributi di contenuto sotto la traccia beta dettagliata elenca ciascun attributo. L'evento claude_code.system_prompt porta il prompt di sistema completo

• 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 negli eventi. Sotto la traccia beta dettagliata, lo span claude_code.llm_request porta comunque l'output del modello in response.model_output, che segue OTEL_LOG_USER_PROMPTS anziché questa variabile
• 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. 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
  • I contatori di costo e token e gli eventi api_request, api_error e api_refusal portano nomi reali di agente, skill, plugin e server MCP e strumento nei loro attributi di attribuzione
  • Lo span claude_code.tool porta attributi derivati dall'input come file_path. Sotto la traccia beta dettagliata porta anche un attributo tool_input
• Il contenuto dello strumento non viene registrato negli span di traccia per impostazione predefinita. Per includerlo, imposta OTEL_LOG_TOOL_CONTENT=1. Lo span claude_code.tool quindi porta un evento span tool.output con contenuti di file grezzi, output dei comandi Bash e ciò che restituiscono gli strumenti MCP, WebFetch e WebSearch, troncato al limite di contenuto (60 KB per impostazione predefinita) per attributo. I risultati degli strumenti MCP, WebFetch e WebSearch richiedono Claude Code v2.1.283 o successivo. Il contenuto dello strumento raggiunge anche gli span attraverso new_context, il cui gate differisce per span. 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.

    Per ogni risposta riuscita, Claude Code aggiunge anche una riga a index.jsonl in quella directory, collegando il file di risposta al file di richiesta che lo ha prodotto e al messaggio di trascrizione in cui è diventato. Ogni riga non contiene contenuto di messaggio, e la sezione evento corpo della risposta API elenca i suoi campi. Il file di indice richiede Claude Code v2.1.274 o successivo

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