Überwachung

Claude Code unterstützt OpenTelemetry (OTel) Metriken und Ereignisse für Überwachung und Observability.

Alle Metriken sind Zeitreihendaten, die über OpenTelemetrys Standard-Metriken-Protokoll exportiert werden, und Ereignisse werden über OpenTelemetrys Logs/Events-Protokoll exportiert. Es liegt in der Verantwortung des Benutzers sicherzustellen, dass ihre Metriken- und Logs-Backends ordnungsgemäß konfiguriert sind und dass die Aggregationsgranularität ihren Überwachungsanforderungen entspricht.

​

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 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. Für Debugging: Export-Intervalle 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

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

​

Konfigurationsdetails

​

Allgemeine Konfigurationsvariablen

​

Metriken-Kardinalitätskontrolle

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

Diese Variablen helfen dabei, die Kardinalität von Metriken zu kontrollieren, was die Speicheranforderungen und Abfrageleistung in Ihrem Metriken-Backend beeinflusst. 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"
}

​

Skript-Anforderungen

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 liegt an den Architektur-Einschränkungen des OpenTelemetry-Exporters.

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 eingeschlossen, wodurch Sie folgendes können:

• Metriken nach Team oder Abteilung filtern
• Kosten pro Kostenstelle verfolgen
• Team-spezifische Dashboards erstellen
• Warnungen für bestimmte Teams einrichten

# ❌ Ungültig - enthält Leerzeichen
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

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

# ✅ Gültig - prozent-kodieren Sie Sonderzeichen bei Bedarf
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

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

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

​

Standard-Attribute

Alle Metriken und Ereignisse teilen diese Standard-Attribute:

​

Metriken

Claude Code exportiert die folgenden Metriken:

​

Metrik-Details

​

Sitzungszähler

Wird zu Beginn jeder Sitzung erhöht.

Attribute:

• Alle Standard-Attribute

​

Codezeilen-Zähler

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

Attribute:

• Alle Standard-Attribute
• type: ("added", "removed")

​

Pull Request-Zähler

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

Attribute:

• Alle Standard-Attribute

​

Commit-Zähler

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

Attribute:

• Alle Standard-Attribute

​

Kostenzähler

Wird nach jeder API-Anfrage erhöht.

Attribute:

• Alle Standard-Attribute
• model: Modell-Identifikator (z.B. “claude-3-5-sonnet-20241022”)

​

Token-Zähler

Wird nach jeder API-Anfrage erhöht.

Attribute:

• Alle Standard-Attribute
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Modell-Identifikator (z.B. “claude-3-5-sonnet-20241022”)

​

Code-Bearbeitungstool-Entscheidungszähler

Wird erhöht, wenn der Benutzer die Verwendung von Edit-, MultiEdit-, Write- oder NotebookEdit-Tools akzeptiert oder ablehnt.

Attribute:

• Alle Standard-Attribute
• tool: Tool-Name ("Edit", "MultiEdit", "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ächlich aktiv mit Claude Code verbrachte Zeit (nicht Leerlaufzeit). Diese Metrik wird während Benutzerinteraktionen wie dem Eingeben von Prompts oder dem Empfangen von Antworten erhöht.

Attribute:

• Alle Standard-Attribute

​

Ereignisse

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

​

Benutzer-Prompt-Ereignis

Wird protokolliert, wenn ein Benutzer einen Prompt einreicht.

Ereignisname: claude_code.user_prompt

Attribute:

• Alle Standard-Attribute
• event.name: "user_prompt"
• event.timestamp: ISO 8601-Zeitstempel
• prompt_length: Länge des Prompts
• prompt: Prompt-Inhalt (standardmäßig redigiert, aktivieren mit OTEL_LOG_USER_PROMPTS=1)

​

Tool-Ergebnis-Ereignis

Wird protokolliert, wenn ein Tool die Ausführung abschließt.

Ereignisname: claude_code.tool_result

Attribute:

• Alle Standard-Attribute
• 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 (bei Fehlschlag)
• decision: Entweder "accept" oder "reject"
• source: Entscheidungsquelle - "config", "user_permanent", "user_temporary", "user_abort" oder "user_reject"
• tool_parameters: JSON-String mit tool-spezifischen Parametern (wenn verfügbar)
  • Für Bash-Tool: enthält bash_command, full_command, timeout, description, sandbox

​

API-Anfrage-Ereignis

Wird für jede API-Anfrage an Claude protokolliert.

Ereignisname: claude_code.api_request

Attribute:

• Alle Standard-Attribute
• event.name: "api_request"
• event.timestamp: ISO 8601-Zeitstempel
• model: Verwendetes Modell (z.B. “claude-3-5-sonnet-20241022”)
• 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 Cache-Erstellung verwendeten Token

​

API-Fehler-Ereignis

Wird protokolliert, wenn eine API-Anfrage an Claude fehlschlägt.

Ereignisname: claude_code.api_error

Attribute:

• Alle Standard-Attribute
• event.name: "api_error"
• event.timestamp: ISO 8601-Zeitstempel
• model: Verwendetes Modell (z.B. “claude-3-5-sonnet-20241022”)
• error: Fehlermeldung
• status_code: HTTP-Statuscode (falls zutreffend)
• duration_ms: Anfragedauer in Millisekunden
• attempt: Versuchsnummer (für wiederholte Anfragen)

​

Tool-Entscheidungs-Ereignis

Wird protokolliert, wenn eine Tool-Berechtigungsentscheidung getroffen wird (akzeptieren/ablehnen).

Ereignisname: claude_code.tool_decision

Attribute:

• Alle Standard-Attribute
• event.name: "tool_decision"
• event.timestamp: ISO 8601-Zeitstempel
• tool_name: Name des Tools (z.B. “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit”, etc.)
• 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

​

Kostenüberwachung

Die Metrik claude_code.cost.usage hilft bei:

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

​

Alarmierung und Segmentierung

Häufige Alarme zu berücksichtigen:

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

​

Ereignisanalyse

Die Ereignisdaten bieten detaillierte Einblicke in Claude Code-Interaktionen:

Tool-Nutzungsmuster: Analysieren Sie Tool-Ergebnis-Ereignisse, um zu identifizieren:

• Am häufigsten verwendete Tools
• Tool-Erfolgsraten
• Durchschnittliche Tool-Ausführungszeiten
• Fehlermuster nach Tool-Typ

Leistungsüberwachung: Verfolgen Sie API-Anfragedauern und Tool-Ausfü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, Alarmierung

​

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 eindeutige Wert-Abfragen unterstützen.

​

Service-Informationen

Alle Metriken und Ereignisse werden mit den folgenden Ressourcen-Attributen exportiert:

• service.name: claude-code
• service.version: Aktuelle Claude Code-Version
• os.type: Betriebssystemtyp (z.B. linux, darwin, windows)
• os.version: Betriebssystem-Versionsstring
• host.arch: Host-Architektur (z.B. amd64, arm64)
• wsl.version: WSL-Versionsnummer (nur vorhanden bei Ausführung auf Windows Subsystem for Linux)
• Meter Name: com.anthropic.claude_code

​

ROI-Messungsressourcen

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

​

Sicherheits-/Datenschutzüberlegungen

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