​

OpenTelemetry in Claude Code

Claude Code supporta le metriche OpenTelemetry (OTel) per il monitoraggio e l’osservabilità. Questo documento spiega come abilitare e configurare OTel per Claude Code.

Tutti i dati metrici sono serie temporali esportate tramite il protocollo standard di metriche di OpenTelemetry. È responsabilità dell’utente assicurarsi che il proprio backend di metriche sia configurato correttamente e che la granularità di aggregazione soddisfi i requisiti di monitoraggio.

​

Avvio Rapido

Configura OpenTelemetry utilizzando le variabili d’ambiente:

# 1. Abilita la telemetria
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Scegli un esportatore
export OTEL_METRICS_EXPORTER=otlp       # Opzioni: otlp, prometheus, 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 l'intervallo di esportazione (predefinito: 600000ms/10min)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 secondi

# 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 attraverso il file delle impostazioni gestite. Questo permette un controllo centralizzato delle impostazioni di telemetria in tutta l’organizzazione. Consulta la gerarchia di configurazione 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_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 backend delle metriche. Una cardinalità inferiore generalmente significa migliori prestazioni e costi di archiviazione più bassi, ma dati meno granulari per l’analisi.

​

Configurazioni di Esempio

# Debug su 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

​

Metriche Disponibili

Claude Code esporta le seguenti metriche:

​

Dettagli delle Metriche

Tutte le metriche condividono questi attributi standard:

• session.id: Identificatore univoco della sessione (controllato da OTEL_METRICS_INCLUDE_SESSION_ID)
• app.version: Versione corrente di Claude Code (controllato da OTEL_METRICS_INCLUDE_VERSION)
• organization.id: UUID dell’organizzazione (quando autenticato)
• user.account_uuid: UUID dell’account (quando autenticato, controllato da OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

​

1. Contatore di Sessione

Emesso all’inizio di ogni sessione.

​

2. Contatore di Righe di Codice

Emesso quando il codice viene aggiunto o rimosso.

• Attributo aggiuntivo: type ("added" o "removed")

​

3. Contatore di Pull Request

Emesso quando si creano pull request tramite Claude Code.

​

4. Contatore di Commit

Emesso quando si creano commit git tramite Claude Code.

​

5. Contatore di Costi

Emesso dopo ogni richiesta API.

• Attributo aggiuntivo: model

​

6. Contatore di Token

Emesso dopo ogni richiesta API.

• Attributi aggiuntivi: type ("input", "output", "cacheRead", "cacheCreation") e model

​

Interpretazione dei Dati Metrici

Queste metriche forniscono informazioni sui modelli di utilizzo, sulla produttività e sui costi:

​

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
• Alto volume di sessioni da utenti specifici

Tutte le metriche possono essere segmentate per user.account_uuid, organization.id, session.id, model e app.version.

​

Considerazioni sul Backend

Per le metriche DAU/WAU/MAU, scegli backend che supportano query efficienti di valori unici.

​

Informazioni sul Servizio

Tutte le metriche vengono esportate con:

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

​

Considerazioni sulla Sicurezza

• La telemetria è opt-in e richiede una configurazione esplicita
• Informazioni sensibili come chiavi API o contenuti di file non sono mai inclusi nelle metriche