SpyBara
Go Premium

monitoring-usage.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

955 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Monitoraggio

Scopri come abilitare e configurare OpenTelemetry per Claude Code.

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

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
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 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. Ciò consente il controllo centralizzato delle impostazioni di telemetria in tutta l'organizzazione. 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"
  }
}

Dettagli della configurazione

Variabili di configurazione comuni

Variabile di ambiente Descrizione Valori di esempio
CLAUDE_CODE_ENABLE_TELEMETRY Abilita la raccolta della telemetria (obbligatorio) 1
OTEL_METRICS_EXPORTER Tipi di esportatore di metriche, separati da virgola. Usa none per disabilitare console, otlp, prometheus, none
OTEL_LOGS_EXPORTER Tipi di esportatore di log/eventi, separati da virgola. Usa none per disabilitare console, otlp, none
OTEL_EXPORTER_OTLP_PROTOCOL Protocollo per l'esportatore OTLP, si applica a tutti i segnali grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT Endpoint del collettore OTLP per tutti i segnali http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL Protocollo per le metriche, sostituisce l'impostazione generale grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT Endpoint OTLP per le metriche, sostituisce l'impostazione generale http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL Protocollo per i log, sostituisce l'impostazione generale grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT Endpoint OTLP per i log, sostituisce l'impostazione generale http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERS Intestazioni di autenticazione per OTLP Authorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY Chiave client per l'autenticazione mTLS Percorso del file della chiave client
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE Certificato client per l'autenticazione mTLS Percorso del file del certificato client
OTEL_METRIC_EXPORT_INTERVAL Intervallo di esportazione in millisecondi (predefinito: 60000) 5000, 60000
OTEL_LOGS_EXPORT_INTERVAL Intervallo di esportazione dei log in millisecondi (predefinito: 5000) 1000, 10000
OTEL_LOG_USER_PROMPTS Abilita la registrazione del contenuto del prompt dell'utente (predefinito: disabilitato) 1 per abilitare
OTEL_LOG_TOOL_DETAILS Abilita la registrazione dei parametri dello strumento e degli argomenti di input negli eventi dello strumento e negli attributi di span di traccia: comandi Bash, nomi dei server MCP e dello strumento, nomi delle skill e input dello strumento. Abilita anche i nomi dei comandi personalizzati, plugin e MCP negli eventi user_prompt (predefinito: disabilitato) 1 per abilitare
OTEL_LOG_TOOL_CONTENT Abilita la registrazione del contenuto di input e output dello strumento negli eventi di span (predefinito: disabilitato). Richiede tracce. Il contenuto viene troncato a 60 KB 1 per abilitare
OTEL_LOG_RAW_API_BODIES Emetti il corpo completo della richiesta e della risposta JSON dell'API Anthropic Messages come eventi di log api_request_body / api_response_body (predefinito: disabilitato). I corpi includono l'intera cronologia della conversazione. L'abilitazione di questa opzione implica il consenso a tutto ciò che OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, e OTEL_LOG_TOOL_CONTENT rivelerebbero 1 per corpi inline troncati a 60 KB, o file:<dir> per corpi non troncati su disco con un puntatore body_ref nell'evento
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE Preferenza di temporalità delle metriche (predefinito: delta). Imposta su cumulative se il tuo backend prevede temporalità cumulativa delta, cumulative
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS Intervallo per l'aggiornamento delle intestazioni dinamiche (predefinito: 1740000ms / 29 minuti) 900000

Controllo della cardinalità delle metriche

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

Variabile di ambiente Descrizione Valore predefinito Esempio per disabilitare
OTEL_METRICS_INCLUDE_SESSION_ID Includi l'attributo session.id nelle metriche true false
OTEL_METRICS_INCLUDE_VERSION Includi l'attributo app.version nelle metriche false true
OTEL_METRICS_INCLUDE_ACCOUNT_UUID Includi gli attributi user.account_uuid e user.account_id nelle metriche true false

Queste variabili aiutano a controllare la cardinalità delle metriche, che influisce sui requisiti di archiviazione e sulle prestazioni delle query nel backend delle metriche. Una cardinalità inferiore generalmente significa prestazioni migliori e costi di archiviazione inferiori, ma dati meno granulari per l'analisi.

Tracce (beta)

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

Le tracce sono disabilitate per impostazione predefinita. Per abilitarle, imposta sia CLAUDE_CODE_ENABLE_TELEMETRY=1 che CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, quindi imposta OTEL_TRACES_EXPORTER per scegliere dove vengono inviati gli span. Le tracce riutilizzano la configurazione OTLP comune per endpoint, protocollo e intestazioni.

Variabile di ambiente Descrizione Valori di esempio
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA Abilita la traccia degli span (obbligatorio). ENABLE_ENHANCED_TELEMETRY_BETA è anche accettato 1
OTEL_TRACES_EXPORTER Tipi di esportatore di tracce, separati da virgola. Usa none per disabilitare console, otlp, none
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL Protocollo per le tracce, sostituisce OTEL_EXPORTER_OTLP_PROTOCOL grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT Endpoint OTLP per le tracce, sostituisce OTEL_EXPORTER_OTLP_ENDPOINT http://localhost:4318/v1/traces
OTEL_TRACES_EXPORT_INTERVAL Intervallo di esportazione batch degli span in millisecondi (predefinito: 5000) 1000, 10000

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

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

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

Gerarchia degli span

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

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

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

Attributi degli span

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

claude_code.interaction

Attributo Descrizione Controllato da
user_prompt Testo del prompt. Il valore è <REDACTED> a meno che il gate non sia impostato OTEL_LOG_USER_PROMPTS
user_prompt_length Lunghezza del prompt in caratteri
interaction.sequence Contatore basato su 1 delle interazioni in questa sessione
interaction.duration_ms Durata wall-clock del turno

claude_code.llm_request

Attributo Descrizione Controllato da
model Identificatore del modello
gen_ai.system Sempre anthropic. Convenzione semantica OpenTelemetry GenAI
gen_ai.request.model Stesso valore di model. Convenzione semantica OpenTelemetry GenAI
query_source Sottosistema che ha emesso la richiesta, come repl_main_thread o un nome di subagent
speed fast o normal
llm_request.context interaction, tool, o standalone a seconda dello span genitore
duration_ms Durata wall-clock inclusi i tentativi
ttft_ms Tempo al primo token in millisecondi
input_tokens Conteggio dei token di input dal blocco di utilizzo dell'API
output_tokens Conteggio dei token di output
cache_read_tokens Token letti dalla cache del prompt
cache_creation_tokens Token scritti nella cache del prompt
request_id ID della richiesta API Anthropic dall'intestazione della risposta request-id
gen_ai.response.id Stesso valore di request_id. Convenzione semantica OpenTelemetry GenAI
client_request_id x-client-request-id generato dal client del tentativo finale
attempt Tentativi totali effettuati per questa richiesta
success true o false
status_code Codice di stato HTTP quando la richiesta non è riuscita
error Messaggio di errore quando la richiesta non è riuscita
response.has_tool_call true quando la risposta conteneva blocchi di tool-use
stop_reason stop_reason della risposta API, come end_turn, tool_use, max_tokens, stop_sequence, pause_turn, o refusal
gen_ai.response.finish_reasons Stesso valore di stop_reason, racchiuso in un array di stringhe. Convenzione semantica OpenTelemetry GenAI

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

claude_code.tool

Attributo Descrizione Controllato da
tool_name Nome dello strumento
duration_ms Durata wall-clock inclusa l'attesa di autorizzazione e l'esecuzione
result_tokens Dimensione approssimativa in token del risultato dello strumento
file_path Percorso del file di destinazione per gli strumenti Read, Edit e Write OTEL_LOG_TOOL_DETAILS
full_command Stringa di comando per lo strumento Bash OTEL_LOG_TOOL_DETAILS
skill_name Nome della skill per lo strumento Skill OTEL_LOG_TOOL_DETAILS
subagent_type Tipo di subagent per lo strumento Task OTEL_LOG_TOOL_DETAILS

Quando OTEL_LOG_TOOL_CONTENT=1, questo span registra anche un evento di span tool.output i cui attributi contengono i corpi di input e output dello strumento, troncati a 60 KB per attributo.

claude_code.tool.blocked_on_user

Attributo Descrizione Controllato da
duration_ms Tempo trascorso in attesa della decisione di autorizzazione
decision accept o reject
source Fonte della decisione, corrispondente all'evento Tool decision event

claude_code.tool.execution

Attributo Descrizione Controllato da
duration_ms Tempo trascorso nell'esecuzione del corpo dello strumento
success true o false
error Stringa di categoria di errore quando l'esecuzione non è riuscita, come Error:ENOENT o ShellError. Contiene il messaggio di errore completo quando il gate è impostato OTEL_LOG_TOOL_DETAILS

claude_code.hook

Questo span viene emesso solo quando la traccia beta dettagliata è attiva, il che richiede ENABLE_BETA_TRACING_DETAILED=1 e BETA_TRACING_ENDPOINT oltre alla configurazione dell'esportatore di tracce sopra. Nelle sessioni CLI interattive, ciò richiede anche che la tua organizzazione sia nella lista di autorizzazione per la funzione. Le sessioni Agent SDK e non interattive -p non sono controllate. Non viene emesso quando è impostato solo CLAUDE_CODE_ENHANCED_TELEMETRY_BETA.

Attributo Descrizione Controllato da
hook_event Tipo di evento hook, come PreToolUse
hook_name Nome completo dell'hook, come PreToolUse:Write
num_hooks Numero di comandi hook corrispondenti eseguiti
hook_definitions Configurazione dell'hook serializzata in JSON OTEL_LOG_TOOL_DETAILS
duration_ms Durata wall-clock di tutti gli hook corrispondenti
num_success Conteggio degli hook completati con successo
num_blocking Conteggio degli hook che hanno restituito una decisione di blocco
num_non_blocking_error Conteggio degli hook che non hanno avuto esito positivo senza bloccare
num_cancelled Conteggio degli hook annullati prima del completamento

Intestazioni dinamiche

Per gli ambienti aziendali che richiedono autenticazione dinamica, puoi configurare uno script per generare intestazioni dinamicamente:

Configurazione delle impostazioni

Aggiungi al tuo .claude/settings.json:

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

Requisiti dello script

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

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

Comportamento di aggiornamento

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

Supporto per organizzazioni multi-team

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

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

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

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

Configurazioni di esempio

Imposta queste variabili di ambiente prima di eseguire claude. Ogni blocco mostra una configurazione completa per un diverso esportatore o scenario di distribuzione:

# Debug della console (intervalli di 1 secondo)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/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

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

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

# Endpoint/backend diversi per metriche e log
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

# Solo metriche (nessun evento/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

# Solo eventi/log (nessuna metrica)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Metriche e eventi disponibili

Attributi standard

Tutte le metriche e gli eventi condividono questi attributi standard:

Attributo Descrizione Controllato da
session.id Identificatore di sessione univoco OTEL_METRICS_INCLUDE_SESSION_ID (predefinito: true)
app.version Versione corrente di Claude Code OTEL_METRICS_INCLUDE_VERSION (predefinito: false)
organization.id UUID dell'organizzazione (quando autenticato) Sempre incluso quando disponibile
user.account_uuid UUID dell'account (quando autenticato) OTEL_METRICS_INCLUDE_ACCOUNT_UUID (predefinito: true)
user.account_id ID dell'account in formato taggato corrispondente alle API di amministrazione Anthropic (quando autenticato), come user_01BWBeN28... OTEL_METRICS_INCLUDE_ACCOUNT_UUID (predefinito: true)
user.id Identificatore anonimo del dispositivo/installazione, generato per ogni installazione di Claude Code Sempre incluso
user.email Indirizzo email dell'utente (quando autenticato tramite OAuth) Sempre incluso quando disponibile
terminal.type Tipo di terminale, come iTerm.app, vscode, cursor, o tmux Sempre incluso quando rilevato

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

  • prompt.id: UUID che correla un prompt dell'utente con tutti gli eventi successivi fino al prompt successivo. Vedi Attributi di correlazione degli eventi.
  • workspace.host_paths: directory dell'area di lavoro host selezionate nell'app desktop, come array di stringhe

Metriche

Claude Code esporta le seguenti metriche:

Nome della metrica Descrizione Unità
claude_code.session.count Conteggio delle sessioni CLI avviate count
claude_code.lines_of_code.count Conteggio delle righe di codice modificate count
claude_code.pull_request.count Numero di pull request create count
claude_code.commit.count Numero di commit git creati count
claude_code.cost.usage Costo della sessione Claude Code USD
claude_code.token.usage Numero di token utilizzati tokens
claude_code.code_edit_tool.decision Conteggio delle decisioni di autorizzazione dello strumento di modifica del codice count
claude_code.active_time.total Tempo attivo totale in secondi s

Dettagli delle metriche

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

Contatore di sessione

Incrementato all'inizio di ogni sessione.

Attributi:

  • Tutti gli attributi standard
  • start_type: Come la sessione è stata avviata. Uno di "fresh", "resume", o "continue"

Contatore di righe di codice

Incrementato quando il codice viene aggiunto o rimosso.

Attributi:

Contatore di pull request

Incrementato quando si creano pull request tramite Claude Code.

Attributi:

Contatore di commit

Incrementato quando si creano commit git tramite Claude Code.

Attributi:

Contatore di costo

Incrementato dopo ogni richiesta API.

Attributi:

  • Tutti gli attributi standard
  • model: Identificatore del modello (ad esempio, "claude-sonnet-4-6")
  • query_source: Categoria del sottosistema che ha emesso la richiesta. Uno di "main", "subagent", o "auxiliary"
  • speed: "fast" quando la richiesta ha utilizzato la modalità veloce. Assente altrimenti
  • effort: Livello di sforzo applicato alla richiesta: "low", "medium", "high", "xhigh", o "max". Assente quando il modello non supporta lo sforzo.

Contatore di token

Incrementato dopo ogni richiesta API.

Attributi:

  • Tutti gli attributi standard
  • type: ("input", "output", "cacheRead", "cacheCreation")
  • model: Identificatore del modello (ad esempio, "claude-sonnet-4-6")
  • query_source: Categoria del sottosistema che ha emesso la richiesta. Uno di "main", "subagent", o "auxiliary"
  • speed: "fast" quando la richiesta ha utilizzato la modalità veloce. Assente altrimenti
  • effort: Livello di sforzo applicato alla richiesta. Vedi Contatore di costo per i dettagli.

Contatore di decisione dello strumento di modifica del codice

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

Attributi:

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

Contatore di tempo attivo

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

Attributi:

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

Eventi

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

Attributi di correlazione degli eventi

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

Attributo Descrizione
prompt.id Identificatore UUID v4 che collega tutti gli eventi prodotti durante l'elaborazione di un singolo prompt dell'utente

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

Evento di prompt dell'utente

Registrato quando un utente invia un prompt.

Nome evento: claude_code.user_prompt

Attributi:

  • Tutti gli attributi standard
  • event.name: "user_prompt"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • prompt_length: Lunghezza del prompt
  • prompt: Contenuto del prompt (redatto per impostazione predefinita, abilita con OTEL_LOG_USER_PROMPTS=1)
  • command_name: Nome del comando quando il prompt ne invoca uno. I nomi dei comandi incorporati e in bundle come compact o debug vengono emessi così come sono; gli alias come reset vengono emessi come digitati piuttosto che il nome canonico. I nomi dei comandi personalizzati, plugin e MCP si riducono a custom o mcp a meno che OTEL_LOG_TOOL_DETAILS=1 non sia impostato
  • command_source: Origine del comando quando presente: builtin, custom, o mcp. I comandi forniti dai plugin vengono segnalati come custom

Evento di risultato dello strumento

Registrato quando uno strumento completa l'esecuzione.

Nome evento: claude_code.tool_result

Attributi:

  • Tutti gli attributi standard
  • event.name: "tool_result"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • tool_name: Nome dello strumento
  • tool_use_id: Identificatore univoco per questa invocazione dello strumento. Corrisponde al tool_use_id passato agli hooks, consentendo la correlazione tra gli eventi OTel e i dati acquisiti dagli hooks.
  • success: "true" o "false"
  • duration_ms: Tempo di esecuzione in millisecondi
  • error_type: Stringa di categoria di errore quando lo strumento non è riuscito, come "Error:ENOENT" o "ShellError"
  • error (quando OTEL_LOG_TOOL_DETAILS=1): Messaggio di errore completo quando lo strumento non è riuscito
  • decision_type: "accept" o "reject"
  • decision_source: Fonte della decisione. Uno di "config", "hook", "user_permanent", "user_temporary", "user_abort", o "user_reject". Vedi l'Evento di decisione dello strumento per il significato di ogni valore.
  • tool_input_size_bytes: Dimensione dell'input dello strumento serializzato in JSON in byte
  • tool_result_size_bytes: Dimensione del risultato dello strumento in byte
  • mcp_server_scope: Identificatore dell'ambito del server MCP (per gli strumenti MCP)
  • tool_parameters (quando OTEL_LOG_TOOL_DETAILS=1): Stringa JSON contenente parametri specifici dello strumento:
    • Per lo strumento Bash: include bash_command, full_command, timeout, description, dangerouslyDisableSandbox, e git_commit_id (lo SHA del commit, quando un comando git commit ha successo)
    • Per gli strumenti MCP: include mcp_server_name, mcp_tool_name
    • Per lo strumento Skill: include skill_name
    • Per lo strumento Task: include subagent_type
  • tool_input (quando OTEL_LOG_TOOL_DETAILS=1): Argomenti dello strumento serializzati in JSON. I singoli valori superiori a 512 caratteri vengono troncati, e il payload completo è limitato a circa 4 K caratteri. Si applica a tutti gli strumenti inclusi gli strumenti MCP.

Evento di richiesta API

Registrato per ogni richiesta API a Claude.

Nome evento: claude_code.api_request

Attributi:

  • Tutti gli attributi standard
  • event.name: "api_request"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • model: Modello utilizzato (ad esempio, "claude-sonnet-4-6")
  • cost_usd: Costo stimato in USD
  • duration_ms: Durata della richiesta in millisecondi
  • input_tokens: Numero di token di input
  • output_tokens: Numero di token di output
  • cache_read_tokens: Numero di token letti dalla cache
  • cache_creation_tokens: Numero di token utilizzati per la creazione della cache
  • request_id: ID della richiesta API Anthropic dall'intestazione request-id della risposta, come "req_011...". Presente solo quando l'API ne restituisce uno.
  • speed: "fast" o "normal", indicando se la modalità veloce era attiva
  • query_source: Sottosistema che ha emesso la richiesta, come "repl_main_thread", "compact", o un nome di subagent
  • effort: Livello di sforzo applicato alla richiesta: "low", "medium", "high", "xhigh", o "max". Assente quando il modello non supporta lo sforzo.

Evento di errore API

Registrato quando una richiesta API a Claude non riesce.

Nome evento: claude_code.api_error

Attributi:

  • Tutti gli attributi standard
  • event.name: "api_error"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • model: Modello utilizzato (ad esempio, "claude-sonnet-4-6")
  • error: Messaggio di errore
  • status_code: Codice di stato HTTP come numero. Assente per errori non-HTTP come i guasti di connessione.
  • duration_ms: Durata della richiesta in millisecondi
  • attempt: Numero totale di tentativi effettuati, inclusa la richiesta iniziale (1 significa che non si sono verificati tentativi)
  • request_id: ID della richiesta API Anthropic dall'intestazione request-id della risposta, come "req_011...". Presente solo quando l'API ne restituisce uno.
  • speed: "fast" o "normal", indicando se la modalità veloce era attiva
  • query_source: Sottosistema che ha emesso la richiesta, come "repl_main_thread", "compact", o un nome di subagent
  • effort: Livello di sforzo applicato alla richiesta. Assente quando il modello non supporta lo sforzo.

Evento di corpo della richiesta API

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

Nome evento: claude_code.api_request_body

Attributi:

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

Evento di corpo della risposta API

Registrato per ogni risposta API riuscita quando OTEL_LOG_RAW_API_BODIES è impostato.

Nome evento: claude_code.api_response_body

Attributi:

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

Evento di decisione dello strumento

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

Nome evento: claude_code.tool_decision

Attributi:

  • Tutti gli attributi standard
  • event.name: "tool_decision"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • tool_name: Nome dello strumento (ad esempio, "Read", "Edit", "Write", "NotebookEdit")
  • tool_use_id: Identificatore univoco per questa invocazione dello strumento. Corrisponde al tool_use_id passato agli hooks, consentendo la correlazione tra gli eventi OTel e i dati acquisiti dagli hooks.
  • decision: "accept" o "reject"
  • source: Fonte della decisione:
    • "config": Deciso automaticamente senza richiedere, in base alle impostazioni del progetto, alla politica gestita dall'azienda, ai flag --allowedTools o --disallowedTools, alla modalità di autorizzazione attiva, o perché lo strumento è intrinsecamente sicuro.
    • "hook": Un hook PreToolUse o PermissionRequest ha restituito la decisione.
    • "user_permanent": Emesso quando l'utente ha scelto "Consenti sempre" quando richiesto, salvando una regola alle sue impostazioni personali. Emesso anche per le chiamate successive che corrispondono a quella regola salvata. Trattato come un'accettazione.
    • "user_temporary": Emesso quando l'utente ha scelto "Sì" o "Sì, per questa sessione" quando richiesto, senza salvare una regola. Emesso anche per le chiamate successive nella stessa sessione che corrispondono a quel permesso con ambito di sessione. Trattato come un'accettazione.
    • "user_abort": Emesso quando l'utente ha chiuso il prompt di autorizzazione senza rispondere. Trattato come un rifiuto.
    • "user_reject": Emesso quando l'utente ha scelto "No" quando richiesto, o una chiamata ha corrisposto a una regola di negazione nelle sue impostazioni personali. Trattato come un rifiuto.

Evento di cambio della modalità di autorizzazione

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

Nome evento: claude_code.permission_mode_changed

Attributi:

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

Evento di autenticazione

Registrato quando /login o /logout si completa.

Nome evento: claude_code.auth

Attributi:

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

Evento di connessione del server MCP

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

Nome evento: claude_code.mcp_server_connection

Attributi:

  • Tutti gli attributi standard
  • event.name: "mcp_server_connection"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • status: "connected", "failed", o "disconnected"
  • transport_type: Trasporto del server, come "stdio", "sse", o "http"
  • server_scope: Ambito in cui il server è configurato, come "user", "project", o "local"
  • duration_ms: Durata del tentativo di connessione in millisecondi
  • error_code: Codice di errore quando la connessione non è riuscita
  • server_name (quando OTEL_LOG_TOOL_DETAILS=1): Nome del server configurato
  • error (quando OTEL_LOG_TOOL_DETAILS=1): Messaggio di errore completo quando la connessione non è riuscita

Evento di errore interno

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

Nome evento: claude_code.internal_error

Attributi:

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

Evento di plugin installato

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

Nome evento: claude_code.plugin_installed

Attributi:

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

Evento di skill attivata

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

Nome evento: claude_code.skill_activated

Attributi:

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

Evento di menzione @

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

Nome evento: claude_code.at_mention

Attributi:

  • Tutti gli attributi standard
  • event.name: "at_mention"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • mention_type: Tipo di menzione ("file", "directory", "agent", "mcp_resource")
  • success: Se la menzione è stata risolta con successo ("true" o "false")

Evento di tentativi API esauriti

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

Nome evento: claude_code.api_retries_exhausted

Attributi:

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

Evento di inizio esecuzione dell'hook

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

Nome evento: claude_code.hook_execution_start

Attributi:

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

Evento di completamento esecuzione dell'hook

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

Nome evento: claude_code.hook_execution_complete

Attributi:

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

Evento di compattazione

Registrato quando la compattazione della conversazione si completa.

Nome evento: claude_code.compaction

Attributi:

  • Tutti gli attributi standard
  • event.name: "compaction"
  • event.timestamp: Timestamp ISO 8601
  • event.sequence: Contatore monotonicamente crescente per ordinare gli eventi all'interno di una sessione
  • trigger: "auto" o "manual"
  • success: "true" o "false"
  • duration_ms: Durata della compattazione
  • pre_tokens: Conteggio approssimativo dei token prima della compattazione
  • post_tokens: Conteggio approssimativo dei token dopo la compattazione
  • error: Messaggio di errore quando la compattazione non è riuscita

Interpretazione dei dati di metriche e eventi

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

Monitoraggio dell'utilizzo

Metrica Opportunità di analisi
claude_code.token.usage Suddividi per type (input/output), utente, team o modello
claude_code.session.count Traccia l'adozione e l'engagement nel tempo
claude_code.lines_of_code.count Misura la produttività tracciando le aggiunte/rimozioni di codice
claude_code.commit.count & claude_code.pull_request.count Comprendi l'impatto sui flussi di lavoro di sviluppo

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

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 per user.account_uuid, user.account_id, organization.id, session.id, model, e app.version.

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 quanti tentativi sono stati effettuati in totale. Un valore maggiore di CLAUDE_CODE_MAX_RETRIES (predefinito 10) indica che la richiesta ha esaurito tutti i tentativi su un errore transitorio. Un valore inferiore indica un errore non ritentabile come una risposta 400.

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.

Considerazioni sul backend

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

Per le metriche

  • Database di serie temporali (ad esempio, Prometheus): Calcoli di velocità, metriche aggregate
  • Archivi colonnari (ad esempio, ClickHouse): Query complesse, analisi di utenti univoci
  • Piattaforme di osservabilità complete (ad esempio, Honeycomb, Datadog): Query avanzate, visualizzazione, avvisi

Per eventi/log

  • Sistemi di aggregazione dei log (ad esempio, Elasticsearch, Loki): Ricerca full-text, analisi dei log
  • Archivi colonnari (ad esempio, ClickHouse): Analisi degli eventi strutturati
  • Piattaforme di osservabilità complete (ad esempio, Honeycomb, Datadog): Correlazione tra metriche e eventi

Per tracce

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

  • Sistemi di traccia distribuita (ad esempio, Jaeger, Zipkin, Grafana Tempo): Visualizzazione degli span, waterfall delle richieste, analisi della latenza
  • Piattaforme di osservabilità complete (ad esempio, Honeycomb, Datadog): 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
  • service.version: Versione corrente di Claude 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)
  • Nome del contatore: com.anthropic.claude_code

Risorse di misurazione del ROI

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

Sicurezza e privacy

  • L'esportazione OpenTelemetry al tuo backend è opt-in e richiede una configurazione esplicita. Per la telemetria operazionale separata di Anthropic e come disabilitarla, vedi Data usage
  • I contenuti dei file grezzi e i frammenti di codice non sono inclusi nelle metriche o negli eventi. I percorsi di traccia degli span sono un percorso dati separato: vedi il punto OTEL_LOG_TOOL_CONTENT di seguito
  • Quando autenticato tramite OAuth, user.email è incluso negli attributi di telemetria. Se questo è una preoccupazione per la tua organizzazione, lavora con il tuo backend di telemetria per filtrare o redarre 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
  • Gli argomenti di input dello strumento e i parametri non vengono registrati per impostazione predefinita. Per includerli, imposta OTEL_LOG_TOOL_DETAILS=1. Quando abilitato, gli eventi tool_result includono un attributo tool_parameters con comandi Bash, nomi dei server MCP e dello strumento, e nomi delle skill, più un attributo tool_input con percorsi di file, URL, modelli di ricerca e altri argomenti. Gli eventi user_prompt includono il command_name verbatim per i comandi personalizzati, plugin e MCP. Gli span di traccia includono lo stesso attributo tool_input e attributi derivati dall'input come file_path. I singoli valori superiori a 512 caratteri vengono troncati e il totale è limitato a circa 4 K caratteri, ma gli argomenti potrebbero comunque contenere valori sensibili. Configura il tuo backend di telemetria per filtrare o redarre questi attributi secondo necessità
  • Il contenuto di input e output dello strumento non viene registrato negli span di traccia per impostazione predefinita. Per includerlo, imposta OTEL_LOG_TOOL_CONTENT=1. Quando abilitato, gli eventi di span includono il contenuto completo di input e output dello strumento troncato a 60 KB per span. Questo può includere contenuti di file grezzi dai risultati dello strumento Read e output dei comandi Bash. Configura il tuo backend di telemetria per filtrare o redarre 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. Con =1, ogni chiamata API emette eventi di log api_request_body e api_response_body il cui attributo body è il payload serializzato in JSON, troncato a 60 KB. Con =file:<dir>, i corpi non troncati vengono scritti in 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. In entrambe le modalità, i corpi contengono l'intera cronologia della conversazione (prompt di sistema, ogni turno precedente dell'utente e dell'assistente, risultati degli strumenti), quindi l'abilitazione di questa opzione implica il consenso a tutto ciò che gli altri flag di contenuto OTEL_LOG_* rivelerebbero. Il contenuto del pensiero esteso di Claude viene sempre redatto da questi corpi indipendentemente da altre impostazioni

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