Monitoraggio

Claude Code supporta le metriche e gli 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 sono esportati tramite il protocollo logs/eventi di OpenTelemetry. È responsabilità dell’utente assicurarsi che i loro backend di metriche e log siano configurati correttamente e che la granularità di aggregazione soddisfi i loro requisiti di monitoraggio.

​

Avvio Rapido

Configura OpenTelemetry utilizzando le variabili d’ambiente:

# 1. Abilita la telemetria
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Scegli gli esportatori (entrambi sono opzionali - configura solo quello che ti serve)
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

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

​

Configurazione Amministratore

Gli amministratori possono configurare le impostazioni OpenTelemetry per tutti gli utenti tramite il file delle impostazioni gestite. Questo consente il controllo centralizzato delle impostazioni di telemetria in un’organizzazione. Consulta la precedenza delle impostazioni per maggiori informazioni su come vengono applicate le impostazioni.

Il file delle impostazioni gestite si trova in:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux: /etc/claude-code/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"
  }
}

​

Dettagli di Configurazione

​

Variabili di Configurazione Comuni

​

Controllo della Cardinalità delle Metriche

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

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

​

Supporto per Organizzazioni Multi-Team

Le organizzazioni con più team o dipartimenti possono aggiungere attributi personalizzati per distinguere tra diversi gruppi utilizzando la variabile d’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 specifiche per team
• Impostare avvisi per team specifici

​

Configurazioni di Esempio

# Debug 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 ed Eventi Disponibili

​

Attributi Standard

Tutte le metriche e gli eventi condividono questi attributi standard:

​

Metriche

Claude Code esporta le seguenti metriche:

​

Dettagli delle Metriche

​

Contatore Sessioni

Incrementato all’inizio di ogni sessione.

Attributi:

• Tutti gli attributi standard

​

Contatore Righe di Codice

Incrementato quando il codice viene aggiunto o rimosso.

Attributi:

• Tutti gli attributi standard
• type: ("added", "removed")

​

Contatore Pull Request

Incrementato quando si creano pull request tramite Claude Code.

Attributi:

• Tutti gli attributi standard

​

Contatore Commit

Incrementato quando si creano commit git tramite Claude Code.

Attributi:

• Tutti gli attributi standard

​

Contatore Costi

Incrementato dopo ogni richiesta API.

Attributi:

• Tutti gli attributi standard
• model: Identificatore del modello (es. “claude-3-5-sonnet-20241022”)

​

Contatore Token

Incrementato dopo ogni richiesta API.

Attributi:

• Tutti gli attributi standard
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Identificatore del modello (es. “claude-3-5-sonnet-20241022”)

​

Contatore Decisioni Strumento Modifica Codice

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

Attributi:

• Tutti gli attributi standard
• tool: Nome dello strumento ("Edit", "MultiEdit", "Write", "NotebookEdit")
• decision: Decisione dell’utente ("accept", "reject")
• language: Linguaggio di programmazione del file modificato (es. "TypeScript", "Python", "JavaScript", "Markdown"). Restituisce "unknown" per estensioni di file non riconosciute.

​

Eventi

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

​

Evento Prompt 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
• prompt_length: Lunghezza del prompt
• prompt: Contenuto del prompt (censurato per impostazione predefinita, abilita con OTEL_LOG_USER_PROMPTS=1)

​

Evento Risultato 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
• name: Nome dello strumento
• success: "true" o "false"
• duration_ms: Tempo di esecuzione in millisecondi
• error: Messaggio di errore (se fallito)

​

Evento 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
• model: Modello utilizzato (es. “claude-3-5-sonnet-20241022”)
• 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 Errore API

Registrato quando una richiesta API a Claude fallisce.

Nome Evento: claude_code.api_error

Attributi:

• Tutti gli attributi standard
• event.name: "api_error"
• event.timestamp: Timestamp ISO 8601
• model: Modello utilizzato (es. “claude-3-5-sonnet-20241022”)
• error: Messaggio di errore
• status_code: Codice di stato HTTP (se applicabile)
• duration_ms: Durata della richiesta in millisecondi
• attempt: Numero del tentativo (per richieste ripetute)

​

Evento Decisione Strumento

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

Nome Evento: claude_code.tool_decision

Attributi:

• Tutti gli attributi standard
• event.name: "tool_decision"
• event.timestamp: Timestamp ISO 8601
• tool_name: Nome dello strumento (es. “Read”, “Edit”, “MultiEdit”, “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 ed Eventi

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

​

Monitoraggio dell’Utilizzo

​

Monitoraggio dei Costi

La metrica claude_code.cost.usage aiuta con:

• Tracciamento delle tendenze di utilizzo tra team o individui
• Identificazione di sessioni ad alto utilizzo per l’ottimizzazione

​

Avvisi e Segmentazione

Avvisi comuni da considerare:

• Picchi di costo
• Consumo insolito di token
• Volume elevato di sessioni 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 degli Strumenti: Analizza gli eventi dei risultati degli strumenti per identificare:

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

Monitoraggio delle Prestazioni: Traccia le durate delle richieste API e i tempi di esecuzione degli strumenti per identificare i colli di bottiglia delle prestazioni.

​

Considerazioni sui Backend

La tua scelta di backend per metriche e log determinerà i tipi di analisi che puoi eseguire:

​

Per le Metriche:

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

​

Per Eventi/Log:

• Sistemi di aggregazione log (es. Elasticsearch, Loki): Ricerca full-text, analisi log
• Archivi colonnari (es. ClickHouse): Analisi eventi strutturati
• Piattaforme di osservabilità complete (es. Honeycomb, Datadog): Correlazione tra metriche ed eventi

Per le organizzazioni che richiedono metriche di Utenti Attivi Giornalieri/Settimanali/Mensili (DAU/WAU/MAU), considera backend che supportano query efficienti di valori unici.

​

Informazioni sul Servizio

Tutte le metriche sono esportate con:

• Nome Servizio: claude-code
• Versione Servizio: Versione corrente di Claude Code
• Nome Meter: com.anthropic.claude_code

​

Considerazioni su Sicurezza/Privacy

• La telemetria è opt-in e richiede configurazione esplicita
• Informazioni sensibili come chiavi API o contenuti di file non sono mai incluse nelle metriche o negli eventi -Il contenuto dei prompt utente è censurato per impostazione predefinita - viene registrata solo la lunghezza del prompt. Per abilitare il logging dei prompt utente, imposta OTEL_LOG_USER_PROMPTS=1