Claude Code unterstützt OpenTelemetry (OTel) Metriken und Ereignisse für Überwachung und Observability. Alle Metriken sind Zeitreihendaten, die über das Standard-Metriken-Protokoll von OpenTelemetry exportiert werden, und Ereignisse werden über das Logs/Events-Protokoll von OpenTelemetry exportiert. Es liegt in der Verantwortung des Benutzers, sicherzustellen, dass ihre Metriken- und Logs-Backends ordnungsgemäß konfiguriert sind und dass die Aggregationsgranularität ihre Überwachungsanforderungen erfüllt.
OpenTelemetry-Unterstützung befindet sich derzeit in der Beta-Phase und Details können sich ändern.

​
Schnellstart

Konfigurieren Sie OpenTelemetry mit Umgebungsvariablen: 
# 1. Telemetrie aktivieren
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Exporter wählen (beide sind optional - konfigurieren Sie nur das, was Sie benötigen)
export OTEL_METRICS_EXPORTER=otlp       # Optionen: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # Optionen: otlp, console

# 3. OTLP-Endpunkt konfigurieren (für OTLP-Exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Authentifizierung festlegen (falls erforderlich)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. Zum Debuggen: Exportintervalle reduzieren
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 Sekunden (Standard: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 Sekunden (Standard: 5000ms)

# 6. Claude Code ausführen
claude
Die Standard-Exportintervalle betragen 60 Sekunden für Metriken und 5 Sekunden für Logs. Während der Einrichtung möchten Sie möglicherweise kürzere Intervalle für Debugging-Zwecke verwenden. Denken Sie daran, diese für die Produktionsnutzung zurückzusetzen.
Für vollständige Konfigurationsoptionen siehe die OpenTelemetry-Spezifikation.

​
Administrator-Konfiguration

Administratoren können OpenTelemetry-Einstellungen für alle Benutzer über die verwaltete Einstellungsdatei konfigurieren. Dies ermöglicht eine zentrale Kontrolle der Telemetrie-Einstellungen in einer Organisation. Siehe die Einstellungspriorität für weitere Informationen darüber, wie Einstellungen angewendet werden. Die verwaltete Einstellungsdatei befindet sich unter:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux und WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json
Beispiel für verwaltete Einstellungskonfiguration: 
{
  "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"
  }
}
Verwaltete Einstellungen können über MDM (Mobile Device Management) oder andere Geräteverwaltungslösungen verteilt werden. Umgebungsvariablen, die in der verwalteten Einstellungsdatei definiert sind, haben hohe Priorität und können von Benutzern nicht überschrieben werden.

​
Konfigurationsdetails

​
Allgemeine Konfigurationsvariablen

UmgebungsvariableBeschreibungBeispielwerte
CLAUDE_CODE_ENABLE_TELEMETRYAktiviert die Telemetrie-Erfassung (erforderlich)1
OTEL_METRICS_EXPORTERMetriken-Exporter-Typ(en) (kommagetrennt)console, otlp, prometheus
OTEL_LOGS_EXPORTERLogs/Events-Exporter-Typ(en) (kommagetrennt)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLProtokoll für OTLP-Exporter (alle Signale)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTOTLP-Collector-Endpunkt (alle Signale)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOLProtokoll für Metriken (überschreibt allgemein)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTOTLP-Metriken-Endpunkt (überschreibt allgemein)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOLProtokoll für Logs (überschreibt allgemein)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTLP-Logs-Endpunkt (überschreibt allgemein)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSAuthentifizierungsheader für OTLPAuthorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYClient-Schlüssel für mTLS-AuthentifizierungPfad zur Client-Schlüsseldatei
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATEClient-Zertifikat für mTLS-AuthentifizierungPfad zur Client-Zertifikatsdatei
OTEL_METRIC_EXPORT_INTERVALExportintervall in Millisekunden (Standard: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVALLogs-Exportintervall in Millisekunden (Standard: 5000)1000, 10000
OTEL_LOG_USER_PROMPTSAktiviert die Protokollierung von Benutzer-Prompt-Inhalten (Standard: deaktiviert)1 zum Aktivieren

​
Metriken-Kardinalitätskontrolle

Die folgenden Umgebungsvariablen steuern, welche Attribute in Metriken enthalten sind, um die Kardinalität zu verwalten:
UmgebungsvariableBeschreibungStandardwertBeispiel zum Deaktivieren
OTEL_METRICS_INCLUDE_SESSION_IDAttribut session.id in Metriken einschließentruefalse
OTEL_METRICS_INCLUDE_VERSIONAttribut app.version in Metriken einschließenfalsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUIDAttribut user.account_uuid in Metriken einschließentruefalse
Diese Variablen helfen, die Kardinalität von Metriken zu steuern, was sich auf die Speicheranforderungen und die Abfrageleistung in Ihrem Metriken-Backend auswirkt. Niedrigere Kardinalität bedeutet in der Regel bessere Leistung und niedrigere Speicherkosten, aber weniger granulare Daten für die Analyse.

​
Dynamische Header

Für Unternehmensumgebungen, die dynamische Authentifizierung erfordern, können Sie ein Skript konfigurieren, um Header dynamisch zu generieren:

​
Einstellungskonfiguration

Fügen Sie zu Ihrer .claude/settings.json hinzu: 
{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​
Skriptanforderungen

Das Skript muss gültiges JSON mit String-Schlüssel-Wert-Paaren ausgeben, die HTTP-Header darstellen: 
#!/bin/bash
# Beispiel: Mehrere Header
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​
Wichtige Einschränkungen

Header werden nur beim Start abgerufen, nicht während der Laufzeit. Dies ist auf Einschränkungen der OpenTelemetry-Exporter-Architektur zurückzuführen. Für Szenarien, die häufige Token-Aktualisierung erfordern, verwenden Sie einen OpenTelemetry Collector als Proxy, der seine eigenen Header aktualisieren kann.

​
Multi-Team-Organisationsunterstützung

Organisationen mit mehreren Teams oder Abteilungen können benutzerdefinierte Attribute hinzufügen, um zwischen verschiedenen Gruppen zu unterscheiden, indem Sie die Umgebungsvariable OTEL_RESOURCE_ATTRIBUTES verwenden: 
# Benutzerdefinierte Attribute für Team-Identifikation hinzufügen
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
Diese benutzerdefinierten Attribute werden in alle Metriken und Ereignisse einbezogen, sodass Sie:
  • Metriken nach Team oder Abteilung filtern können
  • Kosten pro Kostenstelle verfolgen können
  • Team-spezifische Dashboards erstellen können
  • Warnungen für bestimmte Teams einrichten können
Wichtige Formatierungsanforderungen für OTEL_RESOURCE_ATTRIBUTES:Die Umgebungsvariable OTEL_RESOURCE_ATTRIBUTES folgt der W3C Baggage-Spezifikation, die strenge Formatierungsanforderungen hat:
  • Keine Leerzeichen erlaubt: Werte dürfen keine Leerzeichen enthalten. Zum Beispiel ist user.organizationName=My Company ungültig
  • Format: Muss kommagetrennte Schlüssel=Wert-Paare sein: key1=value1,key2=value2
  • Zulässige Zeichen: Nur US-ASCII-Zeichen ohne Steuerzeichen, Leerzeichen, doppelte Anführungszeichen, Kommas, Semikola und Backslashes
  • Sonderzeichen: Zeichen außerhalb des zulässigen Bereichs müssen prozentcodiert sein
Beispiele:
# ❌ Ungültig - enthält Leerzeichen
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Gültig - verwenden Sie stattdessen Unterstriche oder camelCase
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Gültig - prozentcodieren Sie Sonderzeichen, falls erforderlich
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
Hinweis: Das Zitieren des gesamten Schlüssel=Wert-Paares (z. B. "key=value with spaces") wird von der OpenTelemetry-Spezifikation nicht unterstützt und führt dazu, dass Attribute mit Anführungszeichen vorangestellt werden.

​
Beispielkonfigurationen

# Console-Debugging (1-Sekunden-Intervalle)
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

# Mehrere Exporter
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Unterschiedliche Endpunkte/Backends für Metriken und Logs
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

# Nur Metriken (keine Ereignisse/Logs)
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

# Nur Ereignisse/Logs (keine Metriken)
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

​
Verfügbare Metriken und Ereignisse

​
Standardattribute

Alle Metriken und Ereignisse teilen diese Standardattribute:
AttributBeschreibungGesteuert durch
session.idEindeutige SitzungskennungOTEL_METRICS_INCLUDE_SESSION_ID (Standard: true)
app.versionAktuelle Claude Code-VersionOTEL_METRICS_INCLUDE_VERSION (Standard: false)
organization.idOrganisations-UUID (wenn authentifiziert)Immer einbezogen, wenn verfügbar
user.account_uuidKonto-UUID (wenn authentifiziert)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (Standard: true)
terminal.typeTerminal-Typ (z. B. iTerm.app, vscode, cursor, tmux)Immer einbezogen, wenn erkannt

​
Metriken

Claude Code exportiert die folgenden Metriken:
MetriknameBeschreibungEinheit
claude_code.session.countAnzahl der gestarteten CLI-Sitzungencount
claude_code.lines_of_code.countAnzahl der geänderten Codezeilencount
claude_code.pull_request.countAnzahl der erstellten Pull Requestscount
claude_code.commit.countAnzahl der erstellten Git-Commitscount
claude_code.cost.usageKosten der Claude Code-SitzungUSD
claude_code.token.usageAnzahl der verwendeten Tokentokens
claude_code.code_edit_tool.decisionAnzahl der Berechtigungsentscheidungen für Code-Bearbeitungswerkzeugecount
claude_code.active_time.totalGesamtaktive Zeit in Sekundens

​
Metrik-Details

​
Sitzungszähler

Wird zu Beginn jeder Sitzung erhöht. Attribute:

​
Codezeilen-Zähler

Wird erhöht, wenn Code hinzugefügt oder entfernt wird. Attribute:

​
Pull Request-Zähler

Wird erhöht, wenn Pull Requests über Claude Code erstellt werden. Attribute:

​
Commit-Zähler

Wird erhöht, wenn Git-Commits über Claude Code erstellt werden. Attribute:

​
Kosten-Zähler

Wird nach jeder API-Anfrage erhöht. Attribute:
  • Alle Standardattribute
  • model: Modellkennung (z. B. “claude-sonnet-4-5-20250929”)

​
Token-Zähler

Wird nach jeder API-Anfrage erhöht. Attribute:
  • Alle Standardattribute
  • type: ("input", "output", "cacheRead", "cacheCreation")
  • model: Modellkennung (z. B. “claude-sonnet-4-5-20250929”)

​
Code Edit Tool Decision-Zähler

Wird erhöht, wenn der Benutzer die Verwendung von Edit-, Write- oder NotebookEdit-Werkzeugen akzeptiert oder ablehnt. Attribute:
  • Alle Standardattribute
  • tool: Werkzeugname ("Edit", "Write", "NotebookEdit")
  • decision: Benutzerentscheidung ("accept", "reject")
  • language: Programmiersprache der bearbeiteten Datei (z. B. "TypeScript", "Python", "JavaScript", "Markdown"). Gibt "unknown" für nicht erkannte Dateierweiterungen zurück.

​
Aktive Zeit-Zähler

Verfolgt die tatsächliche Zeit, die aktiv Claude Code verwendet wird (nicht Leerlaufzeit). Diese Metrik wird während Benutzerinteraktionen wie dem Eingeben von Prompts oder dem Empfangen von Antworten erhöht. Attribute:

​
Ereignisse

Claude Code exportiert die folgenden Ereignisse über OpenTelemetry Logs/Events (wenn OTEL_LOGS_EXPORTER konfiguriert ist):

​
Benutzer-Prompt-Ereignis

Protokolliert, wenn ein Benutzer einen Prompt einreicht. Ereignisname: claude_code.user_prompt Attribute:
  • Alle Standardattribute
  • event.name: "user_prompt"
  • event.timestamp: ISO 8601-Zeitstempel
  • prompt_length: Länge des Prompts
  • prompt: Prompt-Inhalt (standardmäßig redigiert, aktivieren Sie mit OTEL_LOG_USER_PROMPTS=1)

​
Tool Result-Ereignis

Protokolliert, wenn ein Werkzeug die Ausführung abgeschlossen hat. Ereignisname: claude_code.tool_result Attribute:
  • Alle Standardattribute
  • event.name: "tool_result"
  • event.timestamp: ISO 8601-Zeitstempel
  • tool_name: Name des Werkzeugs
  • success: "true" oder "false"
  • duration_ms: Ausführungszeit in Millisekunden
  • error: Fehlermeldung (falls fehlgeschlagen)
  • decision: Entweder "accept" oder "reject"
  • source: Entscheidungsquelle - "config", "user_permanent", "user_temporary", "user_abort" oder "user_reject"
  • tool_parameters: JSON-String mit werkzeugspezifischen Parametern (falls verfügbar)
    • Für Bash-Werkzeug: enthält bash_command, full_command, timeout, description, sandbox

​
API Request-Ereignis

Protokolliert für jede API-Anfrage an Claude. Ereignisname: claude_code.api_request Attribute:
  • Alle Standardattribute
  • event.name: "api_request"
  • event.timestamp: ISO 8601-Zeitstempel
  • model: Verwendetes Modell (z. B. “claude-sonnet-4-5-20250929”)
  • cost_usd: Geschätzte Kosten in USD
  • duration_ms: Anfragedauer in Millisekunden
  • input_tokens: Anzahl der Eingabe-Token
  • output_tokens: Anzahl der Ausgabe-Token
  • cache_read_tokens: Anzahl der aus dem Cache gelesenen Token
  • cache_creation_tokens: Anzahl der für die Cache-Erstellung verwendeten Token

​
API Error-Ereignis

Protokolliert, wenn eine API-Anfrage an Claude fehlschlägt. Ereignisname: claude_code.api_error Attribute:
  • Alle Standardattribute
  • event.name: "api_error"
  • event.timestamp: ISO 8601-Zeitstempel
  • model: Verwendetes Modell (z. B. “claude-sonnet-4-5-20250929”)
  • error: Fehlermeldung
  • status_code: HTTP-Statuscode (falls zutreffend)
  • duration_ms: Anfragedauer in Millisekunden
  • attempt: Versuchsnummer (für wiederholte Anfragen)

​
Tool Decision-Ereignis

Protokolliert, wenn eine Werkzeugberechtigungsentscheidung getroffen wird (akzeptieren/ablehnen). Ereignisname: claude_code.tool_decision Attribute:
  • Alle Standardattribute
  • event.name: "tool_decision"
  • event.timestamp: ISO 8601-Zeitstempel
  • tool_name: Name des Werkzeugs (z. B. “Read”, “Edit”, “Write”, “NotebookEdit” usw.)
  • decision: Entweder "accept" oder "reject"
  • source: Entscheidungsquelle - "config", "user_permanent", "user_temporary", "user_abort" oder "user_reject"

​
Interpretation von Metriken- und Ereignisdaten

Die von Claude Code exportierten Metriken bieten wertvolle Einblicke in Nutzungsmuster und Produktivität. Hier sind einige häufige Visualisierungen und Analysen, die Sie erstellen können:

​
Nutzungsüberwachung

MetrikAnalysemöglichkeit
claude_code.token.usageAufschlüsselung nach type (input/output), Benutzer, Team oder Modell
claude_code.session.countVerfolgen Sie Adoption und Engagement im Laufe der Zeit
claude_code.lines_of_code.countMessen Sie Produktivität durch Verfolgung von Code-Hinzufügungen/Entfernungen
claude_code.commit.count & claude_code.pull_request.countVerstehen Sie die Auswirkungen auf Entwicklungs-Workflows

​
Kostenüberwachung

Die Metrik claude_code.cost.usage hilft bei:
  • Verfolgung von Nutzungstrends über Teams oder Einzelpersonen
  • Identifikation von Sitzungen mit hoher Nutzung zur Optimierung
Kostenmetriken sind Näherungswerte. Für offizielle Abrechnungsdaten konsultieren Sie Ihren API-Anbieter (Claude Console, AWS Bedrock oder Google Cloud Vertex).

​
Warnungen und Segmentierung

Häufige Warnungen zu berücksichtigen:
  • Kostensteigerungen
  • Ungewöhnlicher Token-Verbrauch
  • Hohes Sitzungsvolumen von bestimmten Benutzern
Alle Metriken können nach user.account_uuid, organization.id, session.id, model und app.version segmentiert werden.

​
Ereignisanalyse

Die Ereignisdaten bieten detaillierte Einblicke in Claude Code-Interaktionen: Werkzeugnutzungsmuster: Analysieren Sie Tool Result-Ereignisse, um zu identifizieren:
  • Am häufigsten verwendete Werkzeuge
  • Erfolgsquoten von Werkzeugen
  • Durchschnittliche Werkzeugausführungszeiten
  • Fehlermuster nach Werkzeugtyp
Leistungsüberwachung: Verfolgen Sie API-Anfragedauern und Werkzeugausführungszeiten, um Leistungsengpässe zu identifizieren.

​
Backend-Überlegungen

Ihre Wahl der Metriken- und Logs-Backends bestimmt die Arten von Analysen, die Sie durchführen können:

​
Für Metriken:

  • Zeitreihendatenbanken (z. B. Prometheus): Ratenberechnungen, aggregierte Metriken
  • Spaltenorientierte Speicher (z. B. ClickHouse): Komplexe Abfragen, eindeutige Benutzeranalyse
  • Vollständige Observability-Plattformen (z. B. Honeycomb, Datadog): Erweiterte Abfragen, Visualisierung, Warnungen

​
Für Ereignisse/Logs:

  • Log-Aggregationssysteme (z. B. Elasticsearch, Loki): Volltextsuche, Log-Analyse
  • Spaltenorientierte Speicher (z. B. ClickHouse): Strukturierte Ereignisanalyse
  • Vollständige Observability-Plattformen (z. B. Honeycomb, Datadog): Korrelation zwischen Metriken und Ereignissen
Für Organisationen, die Daily/Weekly/Monthly Active User (DAU/WAU/MAU) Metriken benötigen, sollten Sie Backends in Betracht ziehen, die effiziente Abfragen eindeutiger Werte unterstützen.

​
Service-Informationen

Alle Metriken und Ereignisse werden mit den folgenden Ressourcenattributen exportiert:
  • service.name: claude-code
  • service.version: Aktuelle Claude Code-Version
  • os.type: Betriebssystemtyp (z. B. linux, darwin, windows)
  • os.version: Betriebssystem-Versionstring
  • host.arch: Host-Architektur (z. B. amd64, arm64)
  • wsl.version: WSL-Versionsnummer (nur vorhanden, wenn auf Windows Subsystem for Linux ausgeführt)
  • Meter-Name: com.anthropic.claude_code

​
ROI-Messung-Ressourcen

Für einen umfassenden Leitfaden zur Messung der Kapitalrendite für Claude Code, einschließlich Telemetrie-Einrichtung, Kostenanalyse, Produktivitätsmetriken und automatisierter Berichterstellung, siehe den Claude Code ROI Measurement Guide. Dieses Repository bietet einsatzbereite Docker Compose-Konfigurationen, Prometheus- und OpenTelemetry-Setups sowie Vorlagen zur Generierung von Produktivitätsberichten, die in Tools wie Linear integriert sind.

​
Sicherheits-/Datenschutzüberlegungen

  • Telemetrie ist opt-in und erfordert explizite Konfiguration
  • Vertrauliche Informationen wie API-Schlüssel oder Dateiinhalte sind niemals in Metriken oder Ereignissen enthalten
  • Benutzer-Prompt-Inhalte werden standardmäßig redigiert - nur die Prompt-Länge wird aufgezeichnet. Um Benutzer-Prompt-Protokollierung zu aktivieren, setzen Sie OTEL_LOG_USER_PROMPTS=1

​
Überwachung von Claude Code auf Amazon Bedrock

Für detaillierte Anleitung zur Überwachung der Claude Code-Nutzung für Amazon Bedrock siehe Claude Code Monitoring Implementation (Bedrock).