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
| Umgebungsvariable | Beschreibung | Beispielwerte |
CLAUDE_CODE_ENABLE_TELEMETRY | Aktiviert die Telemetrie-Erfassung (erforderlich) | 1 |
OTEL_METRICS_EXPORTER | Metriken-Exporter-Typ(en) (kommagetrennt) | console, otlp, prometheus |
OTEL_LOGS_EXPORTER | Logs/Events-Exporter-Typ(en) (kommagetrennt) | console, otlp |
OTEL_EXPORTER_OTLP_PROTOCOL | Protokoll für OTLP-Exporter (alle Signale) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP-Collector-Endpunkt (alle Signale) | http://localhost:4317 |
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | Protokoll für Metriken (überschreibt allgemein) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | OTLP-Metriken-Endpunkt (überschreibt allgemein) | http://localhost:4318/v1/metrics |
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Protokoll für Logs (überschreibt allgemein) | grpc, http/json, http/protobuf |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | OTLP-Logs-Endpunkt (überschreibt allgemein) | http://localhost:4318/v1/logs |
OTEL_EXPORTER_OTLP_HEADERS | Authentifizierungsheader für OTLP | Authorization=Bearer token |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY | Client-Schlüssel für mTLS-Authentifizierung | Pfad zur Client-Schlüsseldatei |
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE | Client-Zertifikat für mTLS-Authentifizierung | Pfad zur Client-Zertifikatsdatei |
OTEL_METRIC_EXPORT_INTERVAL | Exportintervall in Millisekunden (Standard: 60000) | 5000, 60000 |
OTEL_LOGS_EXPORT_INTERVAL | Logs-Exportintervall in Millisekunden (Standard: 5000) | 1000, 10000 |
OTEL_LOG_USER_PROMPTS | Aktiviert 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:
| Umgebungsvariable | Beschreibung | Standardwert | Beispiel zum Deaktivieren |
OTEL_METRICS_INCLUDE_SESSION_ID | Attribut session.id in Metriken einschließen | true | false |
OTEL_METRICS_INCLUDE_VERSION | Attribut app.version in Metriken einschließen | false | true |
OTEL_METRICS_INCLUDE_ACCOUNT_UUID | Attribut user.account_uuid in Metriken einschließen | true | false |
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.
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:
| Attribut | Beschreibung | Gesteuert durch |
session.id | Eindeutige Sitzungskennung | OTEL_METRICS_INCLUDE_SESSION_ID (Standard: true) |
app.version | Aktuelle Claude Code-Version | OTEL_METRICS_INCLUDE_VERSION (Standard: false) |
organization.id | Organisations-UUID (wenn authentifiziert) | Immer enthalten, wenn verfügbar |
user.account_uuid | Konto-UUID (wenn authentifiziert) | OTEL_METRICS_INCLUDE_ACCOUNT_UUID (Standard: true) |
terminal.type | Terminaltyp (z. B. iTerm.app, vscode, cursor, tmux) | Immer enthalten, wenn erkannt |
Metriken
Claude Code exportiert die folgenden Metriken:
| Metrikname | Beschreibung | Einheit |
claude_code.session.count | Anzahl der gestarteten CLI-Sitzungen | count |
claude_code.lines_of_code.count | Anzahl der geänderten Codezeilen | count |
claude_code.pull_request.count | Anzahl der erstellten Pull Requests | count |
claude_code.commit.count | Anzahl der erstellten Git-Commits | count |
claude_code.cost.usage | Kosten der Claude Code-Sitzung | USD |
claude_code.token.usage | Anzahl der verwendeten Token | tokens |
claude_code.code_edit_tool.decision | Anzahl der Entscheidungen zur Berechtigung des Code-Bearbeitungstools | count |
claude_code.active_time.total | Gesamte aktive Zeit in Sekunden | s |
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:
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”)
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)
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)
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
| Metrik | Analysemöglichkeit |
claude_code.token.usage | Aufschlüsselung nach type (input/output), Benutzer, Team oder Modell |
claude_code.session.count | Verfolgung der Einführung und des Engagements im Laufe der Zeit |
claude_code.lines_of_code.count | Messung der Produktivität durch Verfolgung von Code-Hinzufügungen/Entfernungen |
claude_code.commit.count & claude_code.pull_request.count | Verstä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.
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).