Zum Hauptinhalt springen
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 seine Metriken- und Logs-Backends ordnungsgemäß konfiguriert sind und dass die Aggregationsgranularität seinen Überwachungsanforderungen entspricht.
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.

Administratorkonfiguration

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 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 einer verwalteten 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

Häufige 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 kontrollieren, was sich auf die Speicheranforderungen und die Abfrageleistung in Ihrem Metriken-Backend auswirkt. Niedrigere Kardinalität bedeutet im Allgemeinen 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
  • Erlaubte 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 enthalten, wenn verfügbar
user.account_uuidKonto-UUID (wenn authentifiziert)OTEL_METRICS_INCLUDE_ACCOUNT_UUID (Standard: true)
terminal.typeTerminaltyp (z. B. iTerm.app, vscode, cursor, tmux)Immer enthalten, 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 Entscheidungen zur Berechtigung des Code-Bearbeitungstoolscount
claude_code.active_time.totalGesamte aktive Zeit in Sekundens

Metrikdetails

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:

Kostenzä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 Counter

Wird erhöht, wenn der Benutzer die Verwendung des Edit-, Write- oder NotebookEdit-Tools akzeptiert oder ablehnt. Attribute:
  • Alle Standardattribute
  • tool: Toolname ("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.

Active Time Counter

Verfolgt die tatsächliche Zeit, die Claude Code aktiv verwendet wird (nicht die 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 geschwärzt, aktivieren mit OTEL_LOG_USER_PROMPTS=1)

Tool Result Event

Protokolliert, wenn ein Tool 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 Tools
  • 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 toolspezifischen Parametern (falls verfügbar)
    • Für Bash-Tool: enthält bash_command, full_command, timeout, description, sandbox

API Request Event

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 Event

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 Event

Protokolliert, wenn eine Tool-Berechtigungsentscheidung 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 Tools (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.countVerfolgung der Einführung und des Engagements im Laufe der Zeit
claude_code.lines_of_code.countMessung der Produktivität durch Verfolgung von Code-Hinzufügungen/Entfernungen
claude_code.commit.count & claude_code.pull_request.countVerständnis der 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 beziehen Sie sich auf Ihren API-Anbieter (Claude Console, AWS Bedrock oder Google Cloud Vertex).

Warnungen und Segmentierung

Häufige Warnungen, die zu berücksichtigen sind:
  • 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: Tool-Nutzungsmuster: Analysieren Sie Tool-Result-Ereignisse, um zu identifizieren:
  • Am häufigsten verwendete Tools
  • Tool-Erfolgsquoten
  • Durchschnittliche Tool-Ausführungszeiten
  • Fehlermuster nach Tool-Typ
Leistungsüberwachung: Verfolgen Sie API-Anfrage-Dauern und Tool-Ausführungszeiten, um Leistungsengpässe zu identifizieren.

Backend-Überlegungen

Ihre Wahl des 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.

Dienstinformationen

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 werden niemals in Metriken oder Ereignisse aufgenommen
  • Benutzer-Prompt-Inhalte werden standardmäßig geschwärzt - nur die Prompt-Länge wird aufgezeichnet. Um die 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).