​

OpenTelemetry in Claude Code

Claude Code unterstützt OpenTelemetry (OTel)-Metriken für Monitoring und Beobachtbarkeit. Dieses Dokument erklärt, wie Sie OTel für Claude Code aktivieren und konfigurieren können.

Alle Metriken sind Zeitreihendaten, die über das standardmäßige Metrik-Protokoll von OpenTelemetry exportiert werden. Es liegt in der Verantwortung des Benutzers, sicherzustellen, dass sein Metrik-Backend ordnungsgemäß konfiguriert ist und dass die Aggregationsgranularität seinen Überwachungsanforderungen entspricht.

​

Schnellstart

Konfigurieren Sie OpenTelemetry mit Umgebungsvariablen:

# 1. Telemetrie aktivieren
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Einen Exporter wählen
export OTEL_METRICS_EXPORTER=otlp       # Optionen: otlp, prometheus, 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. Für Debugging: Exportintervall reduzieren (Standard: 600000ms/10min)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 Sekunden

# 6. Claude Code ausführen
claude

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 zentralisierte Kontrolle der Telemetrie-Einstellungen in einer Organisation. Siehe die Konfigurationshierarchie 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: /etc/claude-code/managed-settings.json

Beispiel für eine verwaltete Einstellungskonfiguration:

{
  "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"
  }
}

​

Konfigurationsdetails

​

Häufige Konfigurationsvariablen

​

Kontrolle der Metrik-Kardinalität

Die folgenden Umgebungsvariablen steuern, welche Attribute in Metriken enthalten sind, um die Kardinalität zu verwalten:

Diese Variablen helfen, die Kardinalität von Metriken zu kontrollieren, was sich auf Speicheranforderungen und Abfrageleistung in Ihrem Metrik-Backend auswirkt. Niedrigere Kardinalität bedeutet im Allgemeinen bessere Leistung und niedrigere Speicherkosten, aber weniger granulare Daten für die Analyse.

​

Beispielkonfigurationen

# Konsolen-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

​

Verfügbare Metriken

Claude Code exportiert die folgenden Metriken:

​

Metrikdetails

Alle Metriken teilen diese Standardattribute:

• session.id: Eindeutige Sitzungskennung (gesteuert durch OTEL_METRICS_INCLUDE_SESSION_ID)
• app.version: Aktuelle Claude Code-Version (gesteuert durch OTEL_METRICS_INCLUDE_VERSION)
• organization.id: Organisations-UUID (bei Authentifizierung)
• user.account_uuid: Konto-UUID (bei Authentifizierung, gesteuert durch OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

​

1. Sitzungszähler

Wird zu Beginn jeder Sitzung ausgegeben.

​

2. Codezeilen-Zähler

Wird ausgegeben, wenn Code hinzugefügt oder entfernt wird.

• Zusätzliches Attribut: type ("added" oder "removed")

​

3. Pull-Request-Zähler

Wird beim Erstellen von Pull Requests über Claude Code ausgegeben.

​

4. Commit-Zähler

Wird beim Erstellen von Git-Commits über Claude Code ausgegeben.

​

5. Kostenzähler

Wird nach jeder API-Anfrage ausgegeben.

• Zusätzliches Attribut: model

​

6. Token-Zähler

Wird nach jeder API-Anfrage ausgegeben.

• Zusätzliche Attribute: type ("input", "output", "cacheRead", "cacheCreation") und model

​

Interpretation von Metrikdaten

Diese Metriken bieten Einblicke in Nutzungsmuster, Produktivität und Kosten:

​

Nutzungsüberwachung

​

Kostenüberwachung

Die Metrik claude_code.cost.usage hilft bei:

• Verfolgung von Nutzungstrends über Teams oder Einzelpersonen hinweg
• Identifizierung von Sitzungen mit hoher Nutzung zur Optimierung

​

Alarmierung und Segmentierung

Zu berücksichtigende häufige Alarme:

• Kostenspitzen
• 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.

​

Backend-Überlegungen

Für DAU/WAU/MAU-Metriken wählen Sie Backends, die effiziente Abfragen für eindeutige Werte unterstützen.

​

Serviceinformationen

Alle Metriken werden exportiert mit:

• Servicename: claude-code
• Serviceversion: Aktuelle Claude Code-Version
• Metername: com.anthropic.claude_code

​

Sicherheitsüberlegungen

• Telemetrie ist Opt-in und erfordert eine explizite Konfiguration
• Sensible Informationen wie API-Schlüssel oder Dateiinhalte sind niemals in Metriken enthalten