Claude Code supporta metriche e eventi OpenTelemetry (OTel) per il monitoraggio e l’osservabilità. Tutte le metriche sono dati di serie temporali esportati tramite il protocollo di metriche standard di OpenTelemetry, e gli eventi vengono esportati tramite il protocollo di log/eventi di OpenTelemetry. È responsabilità dell’utente assicurarsi che i backend di metriche e log siano configurati correttamente e che la granularità dell’aggregazione soddisfi i requisiti di monitoraggio.
Il supporto di OpenTelemetry è attualmente in versione beta e i dettagli sono soggetti a modifiche.

​
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
export OTEL_LOGS_EXPORTER=otlp          # Opzioni: otlp, console

# 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
Gli intervalli di esportazione predefiniti sono 60 secondi per le metriche e 5 secondi per i log. Durante la configurazione, potresti voler utilizzare intervalli più brevi per scopi di debug. Ricordati di ripristinare questi valori per l’uso in produzione.
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. Il file di impostazioni gestite si trova in:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux e WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json
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.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}
Le impostazioni gestite possono essere distribuite tramite MDM (Mobile Device Management) o altre soluzioni di gestione dei dispositivi. Le variabili di ambiente definite nel file di impostazioni gestite hanno una precedenza elevata e non possono essere sovrascritte dagli utenti.

​
Dettagli della configurazione

​
Variabili di configurazione comuni

Variabile di ambienteDescrizioneValori di esempio
CLAUDE_CODE_ENABLE_TELEMETRYAbilita la raccolta della telemetria (obbligatorio)1
OTEL_METRICS_EXPORTERTipo/i di esportatore di metriche (separati da virgola)console, otlp, prometheus
OTEL_LOGS_EXPORTERTipo/i di esportatore di log/eventi (separati da virgola)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLProtocollo per l’esportatore OTLP (tutti i segnali)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint del collettore OTLP (tutti i segnali)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLProtocollo per le metriche (sostituisce quello generale)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTEndpoint OTLP per le metriche (sostituisce quello generale)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLProtocollo per i log (sostituisce quello generale)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTEndpoint OTLP per i log (sostituisce quello generale)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSIntestazioni di autenticazione per OTLPAuthorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYChiave client per l’autenticazione mTLSPercorso del file della chiave client
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATECertificato client per l’autenticazione mTLSPercorso del file del certificato client
OTEL_METRIC_EXPORT_INTERVALIntervallo di esportazione in millisecondi (predefinito: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALIntervallo di esportazione dei log in millisecondi (predefinito: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSAbilita la registrazione del contenuto del prompt dell’utente (predefinito: disabilitato)1 per abilitare

​
Controllo della cardinalità delle metriche

Le seguenti variabili di ambiente controllano quali attributi sono inclusi nelle metriche per gestire la cardinalità:
Variabile di ambienteDescrizioneValore predefinitoEsempio per disabilitare
OTEL_METRICS_INCLUDE_SESSION_IDIncludi l’attributo session.id nelle metrichetruefalse
OTEL_METRICS_INCLUDE_VERSIONIncludi l’attributo app.version nelle metrichefalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDIncludi l’attributo user.account_uuid nelle metrichetruefalse
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à più bassa generalmente significa migliori prestazioni e costi di archiviazione inferiori, ma dati meno granulari per l’analisi.

​
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: Più intestazioni
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​
Limitazioni importanti

Le intestazioni vengono recuperate solo all’avvio, non durante l’esecuzione. Ciò è dovuto alle limitazioni dell’architettura dell’esportatore OpenTelemetry. Per scenari che richiedono un aggiornamento frequente del token, utilizza un Collettore OpenTelemetry come proxy che può aggiornare le proprie intestazioni.

​
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 saranno 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
Requisiti di formattazione importanti per OTEL_RESOURCE_ATTRIBUTES:La variabile di ambiente OTEL_RESOURCE_ATTRIBUTES segue la specifica W3C Baggage, che ha requisiti di formattazione rigorosi:
  • Nessuno spazio consentito: I valori non possono contenere spazi. Ad esempio, user.organizationName=My Company non è valido
  • Formato: Deve essere coppie chiave=valore separate da virgola: key1=value1,key2=value2
  • Caratteri consentiti: Solo caratteri US-ASCII escludendo caratteri di controllo, spazi, virgolette doppie, virgole, punti e virgola e barre rovesciate
  • Caratteri speciali: I caratteri al di fuori dell’intervallo consentito devono essere codificati in percentuale
Esempi:
# ❌ Non valido - contiene spazi
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valido - usa sottolineature o camelCase invece
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valido - codifica in percentuale i caratteri speciali se necessario
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
Nota: Racchiudere l’intera coppia chiave=valore tra virgolette (ad es. "key=value with spaces") non è supportato dalla specifica OpenTelemetry e comporterà attributi con prefisso di virgolette.

​
Configurazioni di esempio

# 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.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.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:
AttributoDescrizioneControllato da
session.idIdentificatore di sessione univocoOTEL_METRICS_INCLUDE_SESSION_ID (predefinito: true)
app.versionVersione corrente di Claude CodeOTEL_METRICS_INCLUDE_VERSION (predefinito: false)
organization.idUUID dell’organizzazione (quando autenticato)Sempre incluso quando disponibile
user.account_uuidUUID dell’account (quando autenticato)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (predefinito: true)
terminal.typeTipo di terminale (ad es. iTerm.app, vscode, cursor, tmux)Sempre incluso quando rilevato

​
Metriche

Claude Code esporta le seguenti metriche:
Nome della metricaDescrizioneUnità
claude_code.session.countConteggio delle sessioni CLI avviatecount
claude_code.lines_of_code.countConteggio delle righe di codice modificatecount
claude_code.pull_request.countNumero di pull request createcount
claude_code.commit.countNumero di commit git creaticount
claude_code.cost.usageCosto della sessione di Claude CodeUSD
claude_code.token.usageNumero di token utilizzatitokens
claude_code.code_edit_tool.decisionConteggio delle decisioni di autorizzazione dello strumento di modifica del codicecount
claude_code.active_time.totalTempo attivo totale in secondis

​
Dettagli delle metriche

​
Contatore di sessione

Incrementato all’inizio di ogni sessione. Attributi:

​
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 es. “claude-sonnet-4-5-20250929”)

​
Contatore di token

Incrementato dopo ogni richiesta API. Attributi:
  • Tutti gli attributi standard
  • type: ("input", "output", "cacheRead", "cacheCreation")
  • model: Identificatore del modello (ad es. “claude-sonnet-4-5-20250929”)

​
Contatore delle decisioni 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: Nome dello strumento ("Edit", "Write", "NotebookEdit")
  • decision: Decisione dell’utente ("accept", "reject")
  • language: Linguaggio di programmazione del file modificato (ad es. "TypeScript", "Python", "JavaScript", "Markdown"). Restituisce "unknown" per estensioni di file non riconosciute.

​
Contatore di tempo attivo

Traccia il tempo effettivo trascorso utilizzando attivamente Claude Code (non il tempo di inattività). Questa metrica viene incrementata durante le interazioni dell’utente come la digitazione di prompt o la ricezione di risposte. Attributi:

​
Eventi

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

​
Evento di prompt dell’utente

Registrato quando un utente invia un prompt. Nome dell’evento: claude_code.user_prompt Attributi:
  • Tutti gli attributi standard
  • event.name: "user_prompt"
  • event.timestamp: Timestamp ISO 8601
  • prompt_length: Lunghezza del prompt
  • prompt: Contenuto del prompt (redatto per impostazione predefinita, abilita con OTEL_LOG_USER_PROMPTS=1)

​
Evento di risultato dello strumento

Registrato quando uno strumento completa l’esecuzione. Nome dell’evento: claude_code.tool_result Attributi:
  • Tutti gli attributi standard
  • event.name: "tool_result"
  • event.timestamp: Timestamp ISO 8601
  • tool_name: Nome dello strumento
  • success: "true" o "false"
  • duration_ms: Tempo di esecuzione in millisecondi
  • error: Messaggio di errore (se non riuscito)
  • decision: "accept" o "reject"
  • source: Fonte della decisione - "config", "user_permanent", "user_temporary", "user_abort" o "user_reject"
  • tool_parameters: Stringa JSON contenente parametri specifici dello strumento (quando disponibili)
    • Per lo strumento Bash: include bash_command, full_command, timeout, description, sandbox

​
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
  • model: Modello utilizzato (ad es. “claude-sonnet-4-5-20250929”)
  • 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

​
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
  • model: Modello utilizzato (ad es. “claude-sonnet-4-5-20250929”)
  • error: Messaggio di errore
  • status_code: Codice di stato HTTP (se applicabile)
  • duration_ms: Durata della richiesta in millisecondi
  • attempt: Numero di tentativo (per richieste riprovate)

​
Evento di decisione dello strumento

Registrato quando viene presa una decisione di autorizzazione dello strumento (accetta/rifiuta). Nome dell’evento: claude_code.tool_decision Attributi:
  • Tutti gli attributi standard
  • event.name: "tool_decision"
  • event.timestamp: Timestamp ISO 8601
  • tool_name: Nome dello strumento (ad es. “Read”, “Edit”, “Write”, “NotebookEdit”, ecc.)
  • decision: "accept" o "reject"
  • source: Fonte della decisione - "config", "user_permanent", "user_temporary", "user_abort" o "user_reject"

​
Interpretazione dei dati di metriche e eventi

Le metriche esportate da Claude Code forniscono informazioni preziose sui modelli di utilizzo e sulla produttività. Ecco alcune visualizzazioni e analisi comuni che puoi creare:

​
Monitoraggio dell’utilizzo

MetricaOpportunità di analisi
claude_code.token.usageSuddividi per type (input/output), utente, team o modello
claude_code.session.countTraccia l’adozione e l’engagement nel tempo
claude_code.lines_of_code.countMisura la produttività tracciando aggiunte/rimozioni di codice
claude_code.commit.count & claude_code.pull_request.countComprendi l’impatto sui flussi di lavoro di sviluppo

​
Monitoraggio dei costi

La metrica claude_code.cost.usage aiuta con:
  • Tracciamento dei trend di utilizzo tra team o individui
  • Identificazione di sessioni ad alto utilizzo per l’ottimizzazione
Le metriche di costo sono approssimazioni. Per i dati di fatturazione ufficiali, consulta il tuo provider API (Claude Console, AWS Bedrock o Google Cloud Vertex).

​
Avvisi e segmentazione

Avvisi comuni da considerare:
  • Picchi di costo
  • Consumo di token inusuale
  • Volume di sessione elevato da utenti specifici
Tutte le metriche possono essere segmentate per user.account_uuid, organization.id, session.id, model e app.version.

​
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ù utilizzati di frequente
  • 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 e log determinerà i tipi di analisi che puoi eseguire:

​
Per le metriche:

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

​
Per eventi/log:

  • Sistemi di aggregazione dei log (ad es. Elasticsearch, Loki): Ricerca full-text, analisi dei log
  • Archivi colonnari (ad es. ClickHouse): Analisi di eventi strutturati
  • Piattaforme di osservabilità complete (ad es. Honeycomb, Datadog): Correlazione tra metriche e eventi
Per le organizzazioni che richiedono metriche Daily/Weekly/Monthly Active User (DAU/WAU/MAU), considera backend che supportano query efficienti di valori univoci.

​
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 es. linux, darwin, windows)
  • os.version: Stringa della versione del sistema operativo
  • host.arch: Architettura dell’host (ad es. 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 per la 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 la generazione di 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.

​
Considerazioni sulla sicurezza/privacy

  • La telemetria è opt-in e richiede una configurazione esplicita
  • Le informazioni sensibili come le chiavi API o i contenuti dei file non vengono mai incluse nelle metriche o negli eventi
  • Il contenuto del prompt dell’utente è redatto per impostazione predefinita - viene registrata solo la lunghezza del prompt. Per abilitare la registrazione del prompt dell’utente, imposta OTEL_LOG_USER_PROMPTS=1

​
Monitoraggio di Claude Code su Amazon Bedrock

Per una guida dettagliata sul monitoraggio dell’utilizzo di Claude Code per Amazon Bedrock, consulta Implementazione del monitoraggio di Claude Code (Bedrock).