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 di log/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 dell’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 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"
  }
}

​

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.

​

Header Dinamici

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

​

Configurazione delle Impostazioni

Aggiungi al tuo .claude/settings.json:

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

​

Requisiti dello Script

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

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

​

Limitazioni Importanti

Gli header vengono recuperati solo all’avvio, non durante l’esecuzione. Questo è dovuto alle limitazioni dell’architettura dell’esportatore OpenTelemetry.

Per scenari che richiedono aggiornamento frequente dei token, utilizza un Collettore OpenTelemetry come proxy che può aggiornare i propri header.

​

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

# ❌ Non valido - contiene spazi
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valido - usa underscore 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"

​

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 di Sessioni

Incrementato all’inizio di ogni sessione.

Attributi:

• Tutti gli attributi standard

​

Contatore di Righe di Codice

Incrementato quando il codice viene aggiunto o rimosso.

Attributi:

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

​

Contatore di Pull Request

Incrementato quando si creano pull request tramite Claude Code.

Attributi:

• Tutti gli attributi standard

​

Contatore di Commit

Incrementato quando si creano commit git tramite Claude Code.

Attributi:

• Tutti gli attributi standard

​

Contatore di Costi

Incrementato dopo ogni richiesta API.

Attributi:

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

​

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-3-5-sonnet-20241022”)

​

Contatore di Decisioni dello Strumento di Modifica del 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 (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 digitare prompt o ricevere risposte.

Attributi:

• Tutti gli attributi standard

​

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
• tool_name: Nome dello strumento
• success: "true" o "false"
• duration_ms: Tempo di esecuzione in millisecondi
• error: Messaggio di errore (se fallito)
• decision: Sia "accept" che "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 disponibile)
  • Per lo strumento Bash: include bash_command, full_command, timeout, description, sandbox

​

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 (ad 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 (ad 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 dello 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 (ad es., “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit”, ecc.)
• decision: Sia "accept" che "reject"
• source: Fonte della decisione - "config", "user_permanent", "user_temporary", "user_abort", o "user_reject"

​

Interpretazione dei D ati di Metriche ed Eventi

Le metriche esportate da Claude Code forniscono preziose informazioni sui modelli di utilizzo e sulla 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 costi
• 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 (ad es., Prometheus): Calcoli di tasso, metriche aggregate
• Store colonnari (ad es., ClickHouse): Query complesse, analisi di utenti unici
• Piattaforme di osservabilità complete (ad es., Honeycomb, Datadog): Query avanzate, visualizzazione, avvisi

​

Per Eventi/Log:

• Sistemi di aggregazione log (ad es., Elasticsearch, Loki): Ricerca full-text, analisi log
• Store colonnari (ad es., ClickHouse): Analisi di eventi strutturati
• Piattaforme di osservabilità complete (ad 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 e gli eventi sono 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 in esecuzione su Windows Subsystem for Linux)
• Nome del Misuratore: 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 il reporting automatizzato, consulta la Guida alla Misurazione del ROI di Claude Code. Questo repository fornisce configurazioni Docker Compose pronte all’uso, configurazioni Prometheus e OpenTelemetry, e template per generare report di produttività integrati con strumenti come Linear.

​

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