Überwachung

Erfahren Sie, wie Sie OpenTelemetry für Claude Code aktivieren und konfigurieren.

Verfolgen Sie die Nutzung, Kosten und Toolaktivität von Claude Code in Ihrer Organisation, indem Sie Telemetriedaten über OpenTelemetry (OTel) exportieren. Claude Code exportiert Metriken als Zeitreihendaten über das Standard-Metriken-Protokoll, Ereignisse über das Logs/Events-Protokoll und optional verteilte Traces über OpenTelemetry.

[!NOTE]

Informationen zur Claude API oder zu Managed Agents finden Sie unter OpenTelemetry für die Claude API.

Schnellstart

Konfigurieren Sie OpenTelemetry mit Umgebungsvariablen:

# 1. Telemetrie aktivieren
export CLAUDE_CODE_ENABLE_TELEMETRY=1

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

# 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 und für die Produktionsnutzung zurücksetzen
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

Um eine Einrichtung zu überprüfen, die Metriken exportiert, suchen Sie in Ihrem Backend nach der Metrik claude_code.session.count, die Claude Code beim Start einer Sitzung ausgibt. Um eine reine Logs-Einrichtung zu überprüfen, senden Sie eine Eingabeaufforderung und suchen Sie nach dem Ereignis claude_code.user_prompt.

Wenn nichts ankommt, führen Sie Claude Code mit claude --debug-file <path> aus und überprüfen Sie das Protokoll, das es in diesen Pfad schreibt. Claude Code meldet Fehler von den konfigurierten Exportern als [3P telemetry]-Fehler, wobei 3P für Drittanbieter steht. Zeilen mit dem Präfix [Anthropic telemetry] beschreiben Anthropics separate operative Telemetrie und deuten nicht auf ein Problem mit Ihrer Einrichtung hin.

Für vollständige Konfigurationsoptionen siehe die OpenTelemetry-Spezifikation.

Administratorkonfiguration

Administratoren können OpenTelemetry-Einstellungen für alle Benutzer über die verwaltete Einstellungsdatei konfigurieren. Weitere Informationen zur Anwendung von Einstellungen finden Sie unter Einstellungspriorität.

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.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

In der Claude Desktop-App lesen Code-Tab-Sitzungen diese verwalteten Einstellungen aus den Quellen, die jede Art von Desktop-Sitzung erreichen. Das OpenTelemetry-Formular für Cowork unter Überwachung in den Daten- und Datenschutzeinstellungen der Admin-Konsole gilt nur für Cowork-Sitzungen, daher exportieren weder die Terminal-CLI noch der Code-Tab zu einem Collector, den Sie dort festlegen.

Claude Code ignoriert die OpenTelemetry-Exporter-Variablen in der .claude/settings.json und .claude/settings.local.json eines Repositorys, daher kann ein Repository diese nicht verwenden, um Telemetrie einzuschalten, zu wählen, wohin sie geht, oder Inhalte zu erfassen. Setzen Sie sie in verwalteten Einstellungen, oder lassen Sie jeden Entwickler sie in seiner Shell oder ~/.claude/settings.json setzen. Ein Repository kann ein Signal immer noch ausschalten, indem es seinen Exporter-Selektor, wie OTEL_LOGS_EXPORTER, auf none setzt, es sei denn, verwaltete Einstellungen, eine --settings-Datei oder die Umgebung, aus der Sie Claude Code starten, setzen diese Variable.

Claude Code übergibt OTEL_* Umgebungsvariablen nicht an die Subprozesse, die es erzeugt, einschließlich des Bash-Tools, Hooks, MCP-Server und Sprachserver. Eine OpenTelemetry-instrumentierte Anwendung, die Sie über das Bash-Tool ausführen, erbt nicht den Exporter-Endpunkt oder die Header von Claude Code, daher setzen Sie diese Variablen direkt im Befehl, wenn diese Anwendung ihre eigene Telemetrie exportieren muss.

Wie verwaltete Einstellungen das OTLP-Ziel sperren

Wenn Sie eine OTEL_EXPORTER_OTLP_* Variable in verwalteten Einstellungen setzen, entfernt Claude Code bei der Initialisierung konfligierende von Entwicklern gesetzte Variablen und protokolliert eine Warnung im Debug-Protokoll. Was entfernt wird, hängt davon ab, welche Variable Sie setzen:

• Endpunkte: Wenn Sie OTEL_EXPORTER_OTLP_ENDPOINT setzen, entfernt Claude Code jeden von Entwicklern gesetzten signalspezifischen Endpunkt. Entwickler können ein Signal nicht auf einen anderen Collector verweisen, daher müssen Sie die signalspezifischen Endpunkt-Variablen nicht auch in verwalteten Einstellungen setzen.

• Protokolle: Wenn Sie OTEL_EXPORTER_OTLP_PROTOCOL setzen, entfernt Claude Code jeden von Entwicklern gesetzten signalspezifischen Protokoll.

• Anmeldedaten: Wenn Sie OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY oder OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE setzen, entfernt Claude Code die von Entwicklern gesetzten signalspezifischen Versionen dieser Variable sowie jede von Entwicklern gesetzte Endpunkt-Variable, generisch oder signalspezifisch, da diese Anmeldedaten sonst einen Collector erreichen würden, den die verwalteten Einstellungen nicht ausgewählt haben.

• Exporter-Selektoren: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER und der Beta-OTEL_TRACES_EXPORTER folgen der normalen Pro-Schlüssel-Priorität. Eine Einstellung eines Entwicklers kann ein Signal immer noch deaktivieren oder auf den Console-Exporter umschalten, daher setzen Sie die Selektoren auch in verwalteten Einstellungen, wenn Sie sie sperren müssen. Über Admin-Quellen folgt OTEL_LOGS_EXPORTER der Telemetrie-Einheit, während die anderen beiden Selektoren pro Schlüssel zusammengeführt werden. Erfordert Claude Code v2.1.223 oder später.

• Beta-Tracing-Endpunkte: Mit detailliertem Beta-Tracing aktiv exportiert Claude Code Logs und Traces zu BETA_TRACING_ENDPOINT statt über die Logs- und Traces-Exporter. Claude Code entfernt daher einen von Entwicklern gesetzten BETA_TRACING_ENDPOINT, wenn eine dieser verwalteten Einstellungen das Ziel eines Signals entscheidet:

  • Ein generischer oder Logs/Traces-Endpunkt oder Anmeldedaten
  • Ein otelHeadersHelper
  • Ein Logs- oder Traces-Exporter-Selektor auf none, console oder leer gesetzt, Werte, die das Signal von einem Collector fernhalten
  • CLAUDE_CODE_ENABLE_TELEMETRY ausgeschaltet

  Ein nur-Metriken-Endpunkt oder Anmeldedaten entfernen ihn nicht. Vor v2.1.251 leitete ein von Entwicklern gesetzter BETA_TRACING_ENDPOINT die Logs und Traces um, die detailliertes Beta-Tracing exportiert, selbst wenn verwaltete Einstellungen den Collector festlegten.

Claude Code entfernt signalspezifische Variablen nicht, die Sie in verwalteten Einstellungen selbst setzen, daher können Sie ein Signal zu einem anderen Collector leiten, indem Sie seine Variable dort setzen, wie das SIEM-Beispiel zeigt. Wenn Sie dort eine signalspezifische Anmeldedaten setzen, entfernt Claude Code den von Entwicklern gesetzten Endpunkt für dieses Signal.

Dieses Entfernungsverhalten ändert, wohin Telemetrie geliefert wird, nicht was Claude Code erfasst.

Vor v2.1.217 folgte jede Variable unabhängig der Pro-Schlüssel-Einstellungspriorität, daher leitete ein signalspezifischer Endpunkt, der in Benutzereinstellungen oder der Shell gesetzt wurde, dieses Signal vom verwalteten Collector ab.

Wenn die Desktop-App oder ein selbst gehosteter Umgebungs-Runner Claude Code startet und einen OTLP-Endpunkt in der bereitgestellten Umgebung benennt, heftet Claude Code das Ziel auf die gleiche Weise fest: Die Telemetrie-Variablen des Launchers entfernen von Entwicklern gesetzte Variablen genau wie verwaltete Einstellungen. Claude Code entfernt Variablen nicht, die der Launcher selbst gesetzt hat. Erfordert Claude Code v2.1.251 oder später.

Konfigurationsdetails

Allgemeine Konfigurationsvariablen

Diese Variablen konfigurieren Exporter, Endpunkte und das Exportverhalten für alle Bereitstellungen.

Wenn Sie eine signalspezifische Endpunkt- oder Protokollvariable setzen, etwa OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, verwendet Claude Code diese anstelle der allgemeinen Variable für das jeweilige Signal. Wenn Sie eine signalspezifische Header-Variable setzen, etwa OTEL_EXPORTER_OTLP_METRICS_HEADERS, führt Claude Code sie für dieses Signal mit der allgemeinen OTEL_EXPORTER_OTLP_HEADERS zusammen.

Auf Rechnern mit verwalteten Einstellungen finden Sie unter Wie verwaltete Einstellungen das OTLP-Ziel festlegen, was Claude Code entfernt.

Bei den Protokollen http/protobuf und http/json sendet Claude Code jede Exportanfrage mit einem Content-Length-Header.

mTLS-Authentifizierung

Wie Sie Client-Zertifikate für den OTLP-Exporter konfigurieren, hängt vom OTLP-Protokoll ab, das für das jeweilige Signal verwendet wird und über OTEL_EXPORTER_OTLP_PROTOCOL oder die signalspezifische Überschreibung festgelegt ist. Dieselbe Konfiguration gilt für Metriken, Logs und Traces.

Bei grpc liest das OpenTelemetry SDK die Standard-OTLP-Variablen direkt, sodass bestehende Konfigurationen, die die signalspezifischen Metrikvariablen setzen, weiterhin funktionieren. Auf Rechnern mit verwalteten Einstellungen entfernt Claude Code beim Start möglicherweise von Entwicklern gesetzte signalspezifische Anmeldedaten und Endpunkte.

Steuerung der Metrik-Kardinalität

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

Eine geringere Kardinalität bedeutet in der Regel bessere Performance und niedrigere Speicherkosten, aber weniger granulare Daten für die Analyse.

Traces (Beta)

Verteiltes Tracing exportiert Spans, die jeden Benutzer-Prompt mit den API-Anfragen und Tool-Ausführungen verknüpfen, die er auslöst, sodass Sie eine vollständige Anfrage als einzelnen Trace in Ihrem Tracing-Backend betrachten können.

Tracing ist standardmäßig deaktiviert. Um es zu aktivieren, setzen Sie sowohl CLAUDE_CODE_ENABLE_TELEMETRY=1 als auch CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 und setzen dann OTEL_TRACES_EXPORTER, um festzulegen, wohin Spans gesendet werden. Traces verwenden die allgemeine OTLP-Konfiguration für Endpunkt, Protokoll, Header und mTLS. Auf Rechnern mit verwalteten Einstellungen entfernt Claude Code beim Start möglicherweise von Entwicklern gesetzte signalspezifische Anmeldedaten und Endpunkte.

Spans schwärzen standardmäßig den Text von Benutzer-Prompts, Details zu Tool-Eingaben und Tool-Inhalte. Setzen Sie OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 und OTEL_LOG_TOOL_CONTENT=1, um diese aufzunehmen.

Wenn Tracing aktiv ist, erben Bash- und PowerShell-Unterprozesse automatisch eine Umgebungsvariable TRACEPARENT, die den W3C-Trace-Kontext des aktiven Tool-Ausführungs-Spans enthält. Dadurch kann jeder Unterprozess, der TRACEPARENT liest, seine eigenen Spans unter demselben Trace einhängen, was durchgängiges verteiltes Tracing durch Skripte und Befehle ermöglicht, die Claude ausführt.

Wenn Tracing aktiv ist und Claude Code direkt mit der Anthropic API verbunden ist, enthält jede Modellanfrage einen W3C-traceparent-Header, der auf den Kontext des claude_code.llm_request-Spans gesetzt ist, und der traceresponse-Header der API wird als Span-Link erfasst. Zusammen verbinden diese die clientseitigen Spans von Claude Code über jeden konformen Vermittler mit dem serverseitigen Trace. Ausgehende HTTP-MCP-Anfragen enthalten traceparent auf dieselbe Weise. Der Header wird nicht an Drittanbieter gesendet.

Standardmäßig wird der traceparent-Header bei Modell- und HTTP-MCP-Anfragen nur gesendet, wenn ANTHROPIC_BASE_URL nicht gesetzt ist oder auf die Anthropic API verweist, da manche Proxys unbekannte Header ablehnen. Die Unterprozess-Variable TRACEPARENT wird aus Konsistenzgründen über denselben Schalter gesteuert. Wenn Sie Claude Code über einen benutzerdefinierten ANTHROPIC_BASE_URL-Proxy betreiben und möchten, dass der Trace-Kontext weitergegeben wird, setzen Sie CLAUDE_CODE_PROPAGATE_TRACEPARENT=1.

In Agent-SDK- und nicht-interaktiven Sitzungen, die mit -p gestartet werden, liest Claude Code beim Start jedes Interaktions-Spans außerdem TRACEPARENT und TRACESTATE aus seiner eigenen Umgebung. Dadurch kann ein einbettender Prozess seinen aktiven W3C-Trace-Kontext an den Unterprozess übergeben, sodass die Spans von Claude Code als Kinder des verteilten Traces des Aufrufers erscheinen. Interaktive Sitzungen ignorieren eingehende TRACEPARENT-Werte, um zu vermeiden, dass versehentlich Umgebungswerte aus CI- oder Container-Umgebungen übernommen werden.

Der eingehende Trace-Kontext gilt auch für Events. In Agent-SDK- und -p-Sitzungen mit gesetztem TRACEPARENT enthält jeder OTLP-Event-Log-Eintrag trace_id- und span_id-Werte, die ihn mit dem Trace Ihrer Anwendung verbinden, auch wenn der Trace-Exporter nicht konfiguriert ist, sodass Ihr Logging-Backend Events mit dem Rest des Traces korrelieren kann.

Ein Eintrag, der ausgegeben wird, während eine Interaktion aktiv ist, enthält die IDs des Interaktions-Spans, selbst wenn Claude Code ihn außerhalb des asynchronen Kontexts des Spans ausgibt, etwa in einem Callback einer Berechtigungsabfrage oder bei einem Eintrag, der während des Starts gepuffert und später exportiert wird. Ein Eintrag, der ohne aktiven Interaktions-Span ausgegeben wird, enthält direkt die IDs aus dem eingehenden TRACEPARENT.

Span-Hierarchie

Jeder Benutzer-Prompt startet einen Root-Span claude_code.interaction. API-Aufrufe, Tool-Aufrufe und Hook-Ausführungen werden als dessen Kinder erfasst. Tool-Spans haben ihrerseits zwei Kind-Spans: einen für die Wartezeit auf eine Berechtigungsentscheidung und einen für die eigentliche Ausführung. Wenn das Agent-Tool oder das ältere Task-Tool einen Subagenten startet, werden die API- und Tool-Spans des Subagenten unter dem claude_code.tool-Span des übergeordneten Agenten verschachtelt.

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (requires detailed beta tracing)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans

In Agent-SDK- und claude -p-Sitzungen wird claude_code.interaction selbst zum Kind des Spans des Aufrufers, wenn TRACEPARENT in der Umgebung gesetzt ist.

Wenn ein PreToolUse-Hook einen Tool-Aufruf zurückstellt, speichert Claude Code den Trace-Kontext des Turns, der ihn zurückgestellt hat. Wenn Sie die Sitzung fortsetzen und das Tool erneut ausgeführt wird, werden die Spans des Tools als Kinder des claude_code.interaction-Spans dieses früheren Turns in dessen Trace eingefügt.

Span-Attribute

Jeder Span enthält die Standardattribute sowie ein span.type-Attribut, das seinem Namen entspricht. Die folgenden Tabellen listen die zusätzlichen Attribute auf, die für jeden Span gesetzt werden. Die Spans llm_request, tool.execution und hook setzen den OpenTelemetry-Status ERROR, wenn sie einen Fehler erfassen; die anderen Spans enden immer mit dem Status UNSET.

claude_code.interaction

claude_code.llm_request

Jeder Wiederholungsversuch wird außerdem als Span-Event gen_ai.request.attempt mit den Attributen attempt und client_request_id erfasst.

claude_code.tool

Span-Event tool.output auf claude_code.tool

Wenn Sie OTEL_LOG_TOOL_CONTENT=1 setzen, können Read- und Bash-Aufrufe ein Span-Event tool.output auf dem claude_code.tool-Span erfassen. Edit- und Write-Aufrufe erfassen eines nur, wenn Sie zusätzlich OTEL_LOG_TOOL_DETAILS=1 setzen. Diese Variable ist nicht auf diese beiden Tools beschränkt; prüfen Sie daher ihre Zeile in der Konfigurationstabelle auf die Argumente, die sie an anderer Stelle hinzufügt.

MCP-Tools, WebFetch und WebSearch erfassen dieses Event ab Claude Code v2.1.283 ebenfalls.

Claude Code schreibt dieses Event aus der erfolgreichen Rückgabe eines Tool-Aufrufs, sodass ein Aufruf, der einen Fehler auslöst, unabhängig vom Tool nichts erfasst. Unter den Aufrufen, die zurückkehren, wird kein tool.output-Event erfasst für:

• Einen Aufruf eines anderen Tools als Read, Edit, Write, Bash, WebFetch, WebSearch und MCP-Tools
• Einen Read-Aufruf, der etwas anderes als Dateitext zurückgibt, etwa ein Bild, ein PDF oder ein erneutes Lesen einer Datei, deren Inhalt sich nicht geändert hat
• Einen Edit- oder Write-Aufruf, sofern Sie nicht zusätzlich OTEL_LOG_TOOL_DETAILS=1 setzen
• Einen WebFetch- oder WebSearch-Aufruf, den Claude Code während der Ausführung in den Hintergrund verschoben hat, damit eine wartende Nachricht Claude erreichen konnte. Das später eintreffende Ergebnis wird ebenfalls nicht erfasst. Wann Claude Code einen Aufruf verschiebt, erfahren Sie unter Wann Claude Code das sendet, was Sie in die Warteschlange gestellt haben für das Terminal und im priority-Feld für Agent-SDK-Sitzungen

Das Event enthält diese Attribute, die jeweils am Inhaltslimit (standardmäßig 60 KB) abgeschnitten werden. Geschaltet durch nennt die Variable, die ein Attribut zusätzlich zu OTEL_LOG_TOOL_CONTENT=1 benötigt; bei Edit und Write schaltet diese Variable das Event selbst statt des Attributs.

Das Attribut tool_name des übergeordneten Spans zeigt Ihnen, von welchem Tool ein Event stammt. Ein am Inhaltslimit abgeschnittenes Attribut wird von <attribute>_truncated und <attribute>_original_length begleitet.

claude_code.tool.blocked_on_user

Eine cancelled-Entscheidung mit source user_abort bedeutet, dass eine Nachricht, die sofort zugestellt werden musste, den Turn unterbrochen hat, während die Berechtigungsabfrage oder die Prüfung im Auto-Modus ausstand. Zum Beispiel hatte der Benutzer während einer Prüfung im Auto-Modus eine Nachricht in der Warteschlange und hat sie sofort gesendet.

claude_code.tool.execution

claude_code.hook

Dieser Span erscheint nur, wenn detailliertes Beta-Tracing aktiv ist. Dafür sind ENABLE_BETA_TRACING_DETAILED=1 und BETA_TRACING_ENDPOINT erforderlich, ein Paar, das auch ändert, wohin Ihre Logs und Traces gehen. Setzen Sie das Paar in Ihrer Shell, Ihren Benutzereinstellungen oder den verwalteten Einstellungen; beide Variablen werden in Projekt- und lokalen Einstellungen ignoriert. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA allein erzeugt ihn nicht.

In interaktiven CLI-Sitzungen erfordert detailliertes Beta-Tracing außerdem, dass Ihre Organisation für die Funktion freigeschaltet ist. Agent-SDK- und nicht-interaktive -p-Sitzungen erfordern keine Freischaltung.

[!WARNING]

Setzen Sie ENABLE_BETA_TRACING_DETAILED nur für das Debugging, nicht in der Produktion. Detailliertes Beta-Tracing hat ein hohes Exportvolumen, und seine Inhaltsattribute sind nicht Teil des stabilen Span-Schemas.

Inhaltsattribute unter detailliertem Beta-Tracing

[!NOTE]

Zusätzliche inhaltstragende Attribute wie new_context, system_reminders, system_prompt_preview, user_system_prompt, tool_input und response.model_output werden nur ausgegeben, wenn detailliertes Beta-Tracing aktiv ist. Sie sind nicht Teil des stabilen Span-Schemas.

Diese Attribute erscheinen auf den unten aufgeführten Spans, und Geschaltet durch nennt die Variable, die ein Attribut zusätzlich zum detaillierten Beta-Tracing benötigt. Werte, die länger als das Inhaltslimit (standardmäßig 60 KB) sind, werden abgeschnitten.

Unter detailliertem Beta-Tracing mit OTEL_LOG_USER_PROMPTS=1 gibt Claude Code außerdem ein claude_code.system_prompt-Event aus, das den vollständigen System-Prompt enthält, abgeschnitten am Inhaltslimit. Es wird jeweils beim ersten Senden eines bestimmten System-Prompts in einer Sitzung ausgegeben und erneut nach einer Komprimierung.

Dynamische Header

Für Unternehmensumgebungen, die eine dynamische Authentifizierung erfordern, können Sie ein Skript konfigurieren, das Header dynamisch generiert. Dynamische Header gelten nur für die Protokolle http/protobuf und http/json. Beim Protokoll grpc verwendet Claude Code nur die statischen Header-Variablen, OTEL_EXPORTER_OTLP_HEADERS und deren signalspezifische Varianten.

Konfiguration der Einstellungen

Fügen Sie Folgendes zu Ihrer .claude/settings.json hinzu und ersetzen Sie den Pfad durch Ihr eigenes Skript:

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

Der Wert kann der Pfad zu einer ausführbaren Datei sein, einschließlich eines Pfads mit Leerzeichen, oder eine Shell-Befehlszeile mit Argumenten. Unter Windows wird der Wert immer über die Shell ausgeführt; setzen Sie daher einen Pfad mit Leerzeichen innerhalb des JSON-Werts in Anführungszeichen.

Anforderungen an das Skript

Das Skript muss gültiges JSON mit String-Schlüssel-Wert-Paaren ausgeben, die HTTP-Header darstellen:

#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Wenn der Helper fehlschlägt oder eine Ausgabe erzeugt, die diese Anforderungen nicht erfüllt, schlagen Exporte fehl, und Ihr Telemetrie-Backend erhält aus der Sitzung nichts, bis der Helper wieder funktioniert. Claude Code meldet den Fehler:

• In einer Warnmeldung in interaktiven Sitzungen, otelHeadersHelper failed; telemetry is not being exported, die einmal pro Sitzung beim ersten Fehlschlagen des Helpers angezeigt wird
• In der Ausgabe von /status
• Im Debug-Log, wenn Sie mit --debug arbeiten oder in der Sitzung /debug ausgeführt haben
• Auf stderr in nicht-interaktiven Sitzungen, die mit -p gestartet wurden

Aktualisierungsverhalten

Das Header-Helper-Skript wird beim Start und danach regelmäßig ausgeführt, um die Token-Aktualisierung zu unterstützen. Standardmäßig wird das Skript alle 29 Minuten ausgeführt. Passen Sie das Intervall mit der Umgebungsvariable CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS an.

Unterstützung für Organisationen mit mehreren Teams

Organisationen mit mehreren Teams oder Abteilungen können mit der Umgebungsvariable OTEL_RESOURCE_ATTRIBUTES benutzerdefinierte Attribute hinzufügen, um zwischen verschiedenen Gruppen zu unterscheiden:

# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Diese benutzerdefinierten Attribute sind in allen Metriken und Events enthalten, sodass Sie:

• Metriken nach Team oder Abteilung filtern
• Kosten pro Kostenstelle nachverfolgen
• Teamspezifische Dashboards erstellen
• Benachrichtigungen für bestimmte Teams einrichten

Claude Code hängt diese Werte als Attribute an jeden Metrik-Datenpunkt und jeden Event-Eintrag an und sendet sie zusätzlich im OTLP-Ressourcenblock. Da die meisten Metrik-Backends Datenpunkt-Attribute als abfragbare Labels bereitstellen, können Sie Metriken direkt nach Ihren benutzerdefinierten Schlüsseln gruppieren und filtern. Mit Ausnahme der vcs.*-Repository-Attribute überschreiben benutzerdefinierte Schlüssel niemals die Standardattribute wie user.id oder session.id: Bei einer Kollision behält Claude Code den integrierten Wert.

Jeder benutzerdefinierte Schlüssel wird zu einem Label an jeder Metrikreihe, sodass Werte mit hoher Kardinalität die Speicherkosten in Ihrem Metrik-Backend erhöhen. Um benutzerdefinierte Attribute nur im Ressourcenblock zu senden und sie aus den Datenpunkt-Labels auszulassen, setzen Sie OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false. Siehe Steuerung der Metrik-Kardinalität.

[!WARNING]

Die Umgebungsvariable OTEL_RESOURCE_ATTRIBUTES verwendet durch Kommas getrennte key=value-Paare mit strengen Formatierungsanforderungen:

• Keine Leerzeichen erlaubt: Werte dürfen keine Leerzeichen enthalten. Zum Beispiel ist user.organizationName=My Company ungültig
• Format: Es müssen durch Kommas getrennte key=value-Paare sein: key1=value1,key2=value2
• Erlaubte Zeichen: Nur US-ASCII-Zeichen mit Ausnahme von Steuerzeichen, Leerraum, doppelten Anführungszeichen, Kommas, Semikolons und Backslashes
• Sonderzeichen: Zeichen außerhalb des erlaubten Bereichs müssen prozentkodiert werden

Verwenden Sie für einen Wert, der ein Leerzeichen benötigen würde, stattdessen Unterstriche oder camelCase. Die folgenden Beispiele setzen org.name in jeder der beiden Formen:

export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

Sie können jedes Zeichen prozentkodieren, nicht nur die ausgeschlossenen. Dieses Beispiel kodiert sowohl das Leerzeichen als auch den Apostroph:

export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Das Einschließen von Werten in Anführungszeichen maskiert keine Leerzeichen. Zum Beispiel ergibt org.name="My Company" den literalen Wert "My Company" einschließlich der Anführungszeichen, nicht My Company.

Telemetrie Desktop-SSH-Sitzungen zuordnen

Um zu sehen, auf welchem entfernten Rechner eine Desktop-SSH-Sitzung lief, benennen Sie jeden Rechner in einem benutzerdefinierten Attribut. Metriken und Events nennen den Rechner, auf dem eine Sitzung lief, nicht.

Fügen Sie auf jedem entfernten Rechner OTEL_RESOURCE_ATTRIBUTES zum env-Block hinzu, der die Telemetrie einschaltet, und zwar in der Datei mit verwalteten Einstellungen, die die Sitzung liest. Schreiben Sie den Namen in der Datei jedes Rechners aus. Claude Code expandiert den Wert nicht, sodass host.name=$(hostname) genau als diese Zeichen ankommt.

Das folgende Beispiel benennt den Rechner build-7:

{
  "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.example.com:4317",
    "OTEL_RESOURCE_ATTRIBUTES": "host.name=build-7"
  }
}

Wenn nichts anderes die Variable setzt, kommt host.name im Ressourcenblock an, sowohl in Desktop-SSH-Sitzungen als auch in der CLI auf diesem Rechner. Wo benutzerdefinierte Attribute sonst noch erscheinen, erfahren Sie unter Unterstützung für Organisationen mit mehreren Teams.

Wenn der Name nicht ankommt, prüfen Sie, ob eine dieser Ursachen vorliegt:

• Sie haben ihn auf dem Computer gesetzt, auf dem Desktop läuft: Desktop gibt einen dort gesetzten Wert nicht an die SSH-Sitzung weiter
• Sie haben ihn in /etc/profile oder einer anderen Datei exportiert, die nur Login-Shells lesen: Der Name kommt an, wenn Sie claude aus einer Login-Shell ausführen, aber nicht in einer Desktop-SSH-Sitzung. Desktop startet Claude Code nicht über eine Login-Shell. Setzen Sie die Variable stattdessen unter env in der Datei mit verwalteten Einstellungen auf dem entfernten Rechner.
• Ein Wert enthält ein Leerzeichen: Claude Code kopiert dann keinen der Schlüssel auf Events oder Datenpunkte und meldet keinen Fehler. Entfernen Sie das Leerzeichen aus dem Wert.
• Etwas anderes setzt die Variable bereits: In einer Sitzung, die die Desktop-App startet, hat eine bereits in der Startumgebung gesetzte Variable Vorrang vor Einstellungsdateien. Das Debug-Log nennt jede ignorierte Variable. Wenn eine Desktop-Bereitstellung eines Drittanbieters einen OTLP-Endpunkt in der von ihr bereitgestellten Umgebung angibt, enthält diese Umgebung die eigene OTEL_RESOURCE_ATTRIBUTES von Desktop.

Beispielkonfigurationen

Setzen Sie diese Umgebungsvariablen, bevor Sie claude ausführen. Jedes der folgenden Szenarien zeigt eine vollständige Konfiguration, und jede Variable ist unter Allgemeine Konfigurationsvariablen beschrieben. Um zu bestätigen, dass eine Konfiguration wirksam geworden ist, prüfen Sie nach dem Start einer Sitzung Ihr Backend auf die Metrik claude_code.session.count; der Schnellstart behandelt die Überprüfung nur für Logs und was zu prüfen ist, wenn nichts ankommt.

Für das Debugging über die Konsole mit einem Exportintervall von 1 Sekunde:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

Für OTLP über 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

Für Prometheus, abgerufen von http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

In einer selbst gehosteten Umgebung bindet die Sitzung Port 9464 nur bei der Standardkapazität des Runners von eins. Bei höherer Kapazität stellt der Runner Zähler und Gauges der Sitzungen stattdessen über seinen eigenen /metrics-Endpunkt bereit.

Um Metriken an mehrere Exporter zu senden:

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

Um Metriken und Logs an unterschiedliche Endpunkte oder Backends zu senden:

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.example.com:4318/v1/metrics
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

Um nur Metriken ohne Events oder Logs zu exportieren:

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

Um nur Events und Logs ohne Metriken zu exportieren:

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

Telemetrie aus Cloud-Sitzungen und Claude Tag

Cloud-Sitzungen, einschließlich Claude Tag-Kanalsitzungen, werden in Cloud-Umgebungen statt auf den Geräten Ihrer Benutzer ausgeführt, daher konfiguriert eine verwaltete Einstellungsdatei oder ein Shell-Profil auf diesen Geräten nicht deren Telemetrie. Für Sitzungen in von Anthropic gehosteten Umgebungen behandelt dieser Abschnitt, wo Sie die Telemetrie-Variablen festlegen, wie Sie Ihren Collector aus der Umgebung erreichbar machen und wie Sie Cloud- und Claude Tag-Sitzungen in den exportierten Daten unterscheiden.

Um Telemetrie aus diesen Sitzungen zu exportieren, legen Sie CLAUDE_CODE_ENABLE_TELEMETRY und die OTEL_*-Variablen mit denselben Schlüsseln wie im Beispiel der Administrator-Konfiguration an einem von zwei Orten fest:

• Vom Server verwaltete Einstellungen: Fügen Sie sie zum env-Block der vom Server verwalteten Einstellungen Ihrer Organisation hinzu. Claude Code ruft diese Einstellungen beim Start überall dort ab, wo vom Server verwaltete Einstellungen gelten, was die Maschinen Ihrer Benutzer und Cloud-Sitzungen außer Claude Tag-Kanalsitzungen einschließt. Claude Tag-Sitzungen erhalten Ihre vom Server verwalteten Einstellungen nicht, daher konfiguriert diese Route sie nicht.
• Die Variablen der Umgebung: Fügen Sie sie zu den Umgebungsvariablen einer Cloud-Umgebung hinzu, um nur die Sitzungen zu konfigurieren, die in dieser Umgebung ausgeführt werden. Dies ist die Route, die Claude Tag-Sitzungen erreicht.

Jeder, der eine Umgebung nutzt, kann ihre Variablen lesen, daher legen Sie dort keine Anmeldedaten ab, wie etwa ein Collector-Token in OTEL_EXPORTER_OTLP_HEADERS. Ein Netzwerk-Secret in der Umgebung hilft auch nicht, da der eigene Telemetrie-Export von Claude Code zu den Anfragen gehört, die das Secret niemals erhalten. Wenn Ihr Collector Anmeldedaten benötigt, konfigurieren Sie stattdessen den gesamten Export über vom Server verwaltete Einstellungen, da Claude Code, wenn Sie dort Anmeldedaten festlegen, Endpunkt-Variablen entfernt, die außerhalb verwalteter Einstellungen festgelegt sind.

Beachten Sie diese Einschränkungen, wenn Sie Telemetrie für Cloud-Sitzungen konfigurieren:

• Lassen Sie Sitzungen den Collector erreichen: Claude Code sendet den Export über das Netzwerk der Sitzung, daher hängt es davon ab, ob es den Host in Ihrem OTEL_EXPORTER_OTLP_ENDPOINT erreicht, von der Netzwerkzugriffsstufe der Umgebung ab. Wenn Sitzungen die Domäne des Collectors auf der von Ihnen gewählten Stufe nicht erreichen können, fügen Sie die Domäne zur Zulassungsliste der Umgebung hinzu, da keine vom Server verwaltete Einstellung Domänen zur Netzwerk-Zulassungsliste einer Umgebung hinzufügt.
• Claude Tag-Channels: Nehmen Sie Änderungen an der Allowlist und an Umgebungsvariablen in der gemeinsamen Umgebung vor, die als Standard Ihrer Organisation festgelegt oder an den Channel angeheftet ist.
• Cowork wird separat konfiguriert: Cowork-Sitzungen erhalten keine vom Server verwalteten Einstellungen, wie die Oberflächenabdeckungstabelle zeigt, daher konfiguriert der vom Server verwaltete env-Block nicht deren Telemetrie.

Telemetrie Cloud-Sitzungen zuordnen

Standardmäßig tragen Metriken und Ereignisse aus einer Cloud-Sitzung die Standard-Attribute, einschließlich session.id, ccr.session.id und organization.id, mit sich, sodass Sie nach Sitzung oder Organisation filtern können, ohne zusätzliche Konfiguration. Der ccr.session.id-Wert ist die CLAUDE_CODE_REMOTE_SESSION_ID der Sitzung. Um ihn in die Transkript-URL der Sitzung umzuwandeln, siehe Ausgabe zurück zur Sitzung verlinken.

Um Cloud-Sitzungen voneinander zu unterscheiden, gruppieren oder filtern Sie nach ccr.session.id, nicht nach session.id.

Um Telemetrie detaillierter zuzuordnen, verwenden Sie diese Optionen:

• Claude Tag-Sitzungen identifizieren: Legen Sie OTEL_METRICS_INCLUDE_ENTRYPOINT=true fest, wie unter Metriken-Kardinalitätskontrolle beschrieben. Metriken und Ereignisse tragen dann app.entrypoint, dessen Wert claude-in-slack für Claude Tag-Sitzungen ist.
• Benutzerdefinierte Attribute hinzufügen: Legen Sie OTEL_RESOURCE_ATTRIBUTES an derselben Stelle fest, an der Sie die anderen OTEL_*-Variablen für diese Sitzungen festlegen. Wenn Sie es stattdessen im Setup-Skript der Umgebung exportieren, erreicht der Wert Claude Code nicht: Das Setup-Skript ist ein separates Bash-Skript, das vor dem Start von Claude Code ausgeführt wird, und Variablen, die es exportiert, enden damit.

In Claude Tag-Kanalsitzungen funktioniert Claude als gemeinsame Identität Ihrer Organisation statt als ein Mitglied, daher verlassen Sie sich nicht auf die user.*-Attribute, um zu identifizieren, wer Claude markiert hat.

Verfügbare Metriken und Ereignisse

Standardattribute

Alle Metriken und Ereignisse teilen sich diese Standardattribute:

In Sitzungen, die über /login bei einem Claude-Apps-Gateway angemeldet sind, versieht die CLI Exporte mit der authentifizierten Identität: user.id ist das IdP-Subject, user.email ist die angemeldete E-Mail-Adresse, und user.groups enthält die IdP-Gruppenmitgliedschaften als kommagetrennte Zeichenfolge. Jeder Export enthält außerdem identity.source: gateway-oidc. Die Gateway-Identität wird zuletzt angewendet, daher werden user.*- und identity.*-Schlüssel, die über OTEL_RESOURCE_ATTRIBUTES gesetzt werden, in diesen Sitzungen ignoriert.

[!NOTE]

Ereignisse, die Claude Code protokolliert, bevor sich ein Entwickler anmeldet, enthalten nicht die Gateway-Identität. Wenn Claude Code eine Sitzung öffnet, die nicht beim Gateway angemeldet ist, zum Beispiel nachdem das Gateway die Anmeldung beendet hat, enthalten die vor der Anmeldung protokollierten Startereignisse die anonyme user.id und kein identity.source. Dazu gehören managed_settings_resolved, plugin_loaded und mcp_server_connection.

Informationen zu den Identitätsattributen von Claude Desktop- und Cowork-Sitzungen, die sich über ein Gateway verbinden, finden Sie in der telemetry-Referenz des Gateways.

Ereignisse enthalten zusätzlich die folgenden Attribute. Diese werden niemals an Metriken angehängt, da sie eine unbegrenzte Kardinalität verursachen würden:

• prompt.id: UUID, die einen Benutzer-Prompt mit allen nachfolgenden Ereignissen bis zum nächsten Prompt verknüpft. Siehe Attribute zur Ereigniskorrelation.
• workspace.host_paths: in der Desktop-App ausgewählte Workspace-Verzeichnisse des Hosts, als String-Array
• workflow.run_id: Ausführungskennung mit dem Präfix wf_ bei den API- und Tool-Events, die von Agenten ausgegeben werden, die zu einer Ausführung des Workflow-Tools gehören. Wenn Sie Events nach einer workflow.run_id filtern, rekonstruieren Sie die API-Anfragen und Tool-Ergebnisse dieser Ausführung. Die Kennung umfasst die Agenten, die das Workflow-Skript startet, sowie alle Agenten, die diese wiederum starten, etwa Skill-Aufrufe. Sie entspricht der im Ergebnis des Workflow-Tools gemeldeten Ausführungskennung.
• workflow.name: Name des Workflows, das meta.name seines Skripts, ausgegeben zusammen mit workflow.run_id. Namen integrierter Workflows erscheinen unverändert, wenn die Ausführung das unveränderte integrierte Skript ausführt. Von Benutzern erstellte Namen, einschließlich bearbeiteter Kopien integrierter Skripte, werden durch custom ersetzt, sofern nicht OTEL_LOG_TOOL_DETAILS=1 gesetzt ist.
• agent_id: Kennung des Subagenten, der das Event ausgelöst hat, etwa a3f2c1b4d5e6f7a80. Zu den Events, die sie tragen, gehören die API- und Tool-Events eines Subagenten, seine assistant_response-Events und subagent_completed für den abgeschlossenen Subagenten. Fehlt bei Events der Hauptsitzung und von In-Process-Teammates. Die Span-agent_id des Subagenten hat denselben Wert oder fügt nach dem führenden a eine Bezeichnung hinzu, wie in acompact-3f2c1b4d5e6f7a80. Erfordert Claude Code v2.1.310 oder höher
• parent_agent_id: die agent_id des Agenten, der den Subagenten, der das Event ausgelöst hat, gestartet oder zuletzt fortgesetzt hat. Fehlt, wenn dieser Agent die Hauptsitzung ist. Erfordert Claude Code v2.1.310 oder höher

Repository-Attribute

Setzen Sie OTEL_METRICS_INCLUDE_REPOSITORY=true, um Metriken und Ereignisse mit der Identität des Repositorys der Sitzung zu kennzeichnen, damit ein gemeinsam genutzter Collector die Nutzung pro Repository zuordnen kann. Erfordert Claude Code v2.1.269 oder höher.

Claude Code leitet diese Attribute einmal pro Sitzung aus dem origin-Remote des Repositorys ab. Wenn die HTTPS- und SSH-Remotes eines Repositorys denselben Host und denselben Pfad nennen, wie es bei GitHub, GitLab und Bitbucket Cloud der Fall ist, ergeben beide identische Werte:

Die Werte werden in Kleinbuchstaben umgewandelt, und Anmeldedaten, Query-Strings und Fragmente aus der Remote-URL erscheinen niemals darin. Die Attribute werden weggelassen, wenn die Sitzung keinen origin-Remote hat, wenn der Remote keine URL-Form hat oder wenn das einzige umschließende Repository Ihr Home-Verzeichnis ist.

Um diese Attribute aus einer Cloud-Sitzung zu erhalten, setzen Sie die Telemetrievariablen, einschließlich OTEL_METRICS_INCLUDE_REPOSITORY, in deren Cloud-Umgebung. Erlauben Sie außerdem die Domain Ihres Collectors im Netzwerkzugriff der Umgebung.

Ein vcs.*-Schlüssel, den Sie in OTEL_RESOURCE_ATTRIBUTES deklarieren, ersetzt den abgeleiteten Wert für diesen Schlüssel. Wenn Sie vcs.repository.url.full deklarieren, liest Claude Code den Remote nie aus und meldet nur die Schlüssel, die Sie deklarieren.

Wenn HTTPS- und SSH-Klone eines Repositorys unterschiedliche Werte melden, etwa bei einer selbst gehosteten Installation, deren HTTPS-Klon-URL ein Pfadpräfix enthält, das der SSH-URL fehlt, deklarieren Sie vcs.repository.url.full in OTEL_RESOURCE_ATTRIBUTES zusammen mit allen anderen vcs.*-Schlüsseln, die gemeldet werden sollen. Jeder Klon meldet dann die Identität, die Sie deklarieren.

Die Attribute fließen nur an Ihre eigenen Exporter; die Telemetrie von Anthropic verwirft jeden vcs.*-Schlüssel.

Metriken

Claude Code exportiert die folgenden Metriken. Die Spalte „Einheit“ zeigt den OpenTelemetry-Einheiten-String, der jeder Metrik angehängt ist; Zählmetriken haben keinen.

Wenn prometheus der einzige in OTEL_METRICS_EXPORTER aufgeführte Exporter ist, lässt Claude Code die Einheiten USD, tokens und s aus den exportierten Metriken weg, damit der Scrape gültiges Prometheus-Textformat bleibt. Metriknamen ändern sich nicht, und Konfigurationen, die Exporter kombinieren, wie otlp,prometheus, behalten die Einheiten.

Details zu den Metriken

Jede Metrik enthält die oben aufgeführten Standardattribute. Metriken mit zusätzlichen kontextspezifischen Attributen sind unten vermerkt.

Sitzungszähler

Wird zu Beginn jeder Sitzung erhöht. Informationen zum Zählen von Personen finden Sie unter Nutzungsüberwachung.

Attribute:

• Alle Standardattribute
• start_type: Wie die Sitzung gestartet wurde. Einer der Werte "fresh", "resume", "continue" oder "agents_view". Der Wert "agents_view" kennzeichnet den Dashboard-Prozess von claude agents, eine vom Benutzer gestartete lokale Oberfläche und keine Konversationssitzung. Filtern Sie nach diesem Wert, um in Ihren Dashboards Starts des UI-Prozesses von Konversationssitzungen zu trennen.

Zähler für Codezeilen

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

Attribute:

• Alle Standardattribute
• type: ("added", "removed")
• model: Modellkennung des Modells, das die Änderung vorgenommen hat (zum Beispiel „claude-sonnet-5“)

Pull-Request-Zähler

Wird erhöht, wenn Claude Code über einen Shell-Befehl oder ein MCP-Tool einen Pull Request oder Merge Request erstellt.

Attribute:

• Alle Standardattribute

Commit-Zähler

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

Attribute:

• Alle Standardattribute

Kostenzähler

Wird nach jeder API-Anfrage erhöht.

Die Attribute agent.name, skill.name, plugin.name, mcp_server.name und mcp_tool.name ersetzen standardmäßig jeweils einige Namen durch einen Platzhalter "custom" oder "third-party". Wenn Sie OTEL_LOG_TOOL_DETAILS=1 setzen, enthalten sie stattdessen die tatsächlichen Namen. Vor v2.1.273 enthielten der Kosten- und der Token-Zähler sowie die Ereignisse api_request, api_error und api_refusal auch bei gesetztem OTEL_LOG_TOOL_DETAILS=1 die geschwärzten Werte.

Attribute:

• Alle Standardattribute
• model: Modellkennung (zum Beispiel „claude-sonnet-5“)
• query_source: Kategorie des Subsystems, das die Anfrage gestellt hat. Einer der Werte "main", "subagent" oder "auxiliary"
• speed: "fast", wenn die Anfrage den Fast-Modus verwendet hat. Andernfalls nicht vorhanden
• effort: Auf die Anfrage angewendete Effort-Stufe: "low", "medium", "high", "xhigh" oder "max". Nicht vorhanden, wenn Claude Code keine Effort-Stufe sendet, zum Beispiel bei einem Modell, das Effort nicht unterstützt.
• agent.name: Subagent-Typ, der die Anfrage gestellt hat. Namen integrierter Agenten und Agenten aus Plugins des offiziellen Marketplace erscheinen unverändert. Andere benutzerdefinierte Agentennamen werden durch "custom" ersetzt. Nicht vorhanden, wenn die Anfrage nicht von einem benannten Subagent-Typ gestellt wurde.
• skill.name: Für die Anfrage aktiver Skill, gesetzt durch das Skill-Tool oder einen /-Befehl oder von einem gestarteten Subagenten geerbt. Namen integrierter, gebündelter und benutzerdefinierter Skills sowie von Skills aus Plugins des offiziellen Marketplace erscheinen unverändert. Namen von Skills aus Drittanbieter-Plugins werden durch "third-party" ersetzt. Nicht vorhanden, wenn kein Skill aktiv ist.
• plugin.name: Zugehöriges Plugin, wenn der aktive Skill oder Subagent von einem Plugin bereitgestellt wird. Namen von Plugins aus dem offiziellen Marketplace erscheinen unverändert. Namen von Drittanbieter-Plugins werden durch "third-party" ersetzt. Nicht vorhanden, wenn weder der Skill noch der Subagent ein zugehöriges Plugin hat.
• marketplace.name: Marketplace, aus dem das zugehörige Plugin installiert wurde. Wird nur für Plugins aus dem offiziellen Marketplace ausgegeben, auch wenn OTEL_LOG_TOOL_DETAILS=1 gesetzt ist. Andernfalls nicht vorhanden.
• mcp_server.name: MCP-Server, dessen Tool-Ergebnis diese Anfrage verarbeitet hat. Namen integrierter, über claude.ai weitergeleiteter und im offiziellen Registry eingetragener Server erscheinen unverändert. Namen benutzerkonfigurierter Server werden durch "custom" ersetzt. Nicht vorhanden, wenn die Anfrage kein MCP-Tool-Ergebnis verarbeitet hat. Vor v2.1.222 setzte Claude Code dieses Attribut bei jeder Anfrage nach einem MCP-Tool-Aufruf, nicht nur bei Anfragen, die ein Tool-Ergebnis verarbeitet haben. Dashboards, die es aggregieren, zeigen daher nach dem Upgrade einen Rückgang.
• mcp_tool.name: MCP-Tool, dessen Ergebnis diese Anfrage verarbeitet hat, mit demselben Schwärzungs- und Versionsverhalten wie mcp_server.name. Nicht vorhanden, wenn die Anfrage kein MCP-Tool-Ergebnis verarbeitet hat.

Token-Zähler

Wird nach jeder API-Anfrage erhöht.

Attribute:

• Alle Standardattribute
• type: ("input", "output", "cacheRead", "cacheCreation"). Der Typ "input" schließt Token aus, die aus dem Prompt-Cache gelesen oder in ihn geschrieben wurden; diese werden unter "cacheRead" und "cacheCreation" gezählt. Der Typ "cacheCreation" zählt Cache-Schreibvorgänge mit den Cache-Lebensdauern von fünf Minuten und einer Stunde zusammen.
• model: Modellkennung (zum Beispiel „claude-sonnet-5“)
• query_source: Kategorie des Subsystems, das die Anfrage gestellt hat. Einer der Werte "main", "subagent" oder "auxiliary"
• speed: "fast", wenn die Anfrage den Fast-Modus verwendet hat. Andernfalls nicht vorhanden
• effort: Auf die Anfrage angewendete Effort-Stufe. Details finden Sie unter Kostenzähler.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Zuordnung der Anfrage zu Skill, Plugin, Agent und MCP. Definitionen und Schwärzungsverhalten finden Sie unter Kostenzähler.

Zähler für Entscheidungen zu Code-Bearbeitungstools

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

Attribute:

• Alle Standardattribute
• tool_name: Tool-Name ("Edit", "Write", "NotebookEdit")
• decision: Entscheidung des Benutzers ("accept", "reject")
• source: Woher die Entscheidung stammt. Einer der Werte "config", "hook", "user_permanent", "user_temporary", "user_abort" oder "user_reject". Was jeder Wert bedeutet, erfahren Sie beim Tool-Entscheidungsereignis.
• language: Programmiersprache der bearbeiteten Datei, etwa "TypeScript", "Python", "JavaScript" oder "Markdown". Gibt "unknown" für nicht erkannte Dateierweiterungen zurück.

Zähler für aktive Zeit

Erfasst die tatsächlich mit der aktiven Nutzung von Claude Code verbrachte Zeit, ohne Leerlaufzeit. Diese Metrik wird während Benutzerinteraktionen, etwa beim Tippen und Lesen von Antworten, sowie während der CLI-Verarbeitung, etwa bei der Tool-Ausführung und der Generierung von KI-Antworten, erhöht.

Attribute:

• Alle Standardattribute
• type: "user" für Tastaturinteraktionen, "cli" für Tool-Ausführung und KI-Antworten

Ereignisse

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

Attribute zur Ereigniskorrelation

Wenn ein Benutzer einen Prompt sendet, kann Claude Code mehrere API-Aufrufe ausführen und mehrere Tools ausführen. Mit dem Attribut prompt.id können Sie all diese Ereignisse dem einzelnen Prompt zuordnen, der sie ausgelöst hat.

Um alle Aktivitäten zu verfolgen, die durch einen einzelnen Prompt ausgelöst wurden, filtern Sie Ihre Ereignisse nach einem bestimmten prompt.id-Wert. Dadurch erhalten Sie das user_prompt-Ereignis, alle api_request-Ereignisse und alle tool_result-Ereignisse, die während der Verarbeitung dieses Prompts aufgetreten sind.

event.sequence beginnt bei jedem Start eines Claude Code-Prozesses bei 0 und zählt während der Lebensdauer dieses Prozesses hoch. Es zählt über /clear hinweg weiter, das eine neue session.id vergibt. Wenn Sie eine Sitzung ohne Forken fortsetzen, behält die Sitzung ihre session.id, übernimmt ihre event.sequence-Werte aber von dem Prozess, der sie fortgesetzt hat. Innerhalb einer Sitzung kann ein späteres Ereignis daher einen niedrigeren Wert als ein früheres tragen oder einen Wert wiederholen. Um die Ereignisse einer Sitzung zu ordnen, sortieren Sie nach event.timestamp und verwenden Sie event.sequence, um Ereignisse mit demselben Zeitstempel zu ordnen.

Für die Rekonstruktion auf Nachrichtenebene enthält jede Ereignisklasse einen Schlüssel, der einem Feld im Sitzungstranskript entspricht. Das Format der Transkripteinträge ist intern in Claude Code und ändert sich zwischen Versionen. Eine Pipeline, die über diese Felder verknüpft, kann daher mit jedem Release brechen; betrachten Sie diese Verknüpfungen als versionsspezifisch und nicht als stabilen Vertrag:

• message.uuid bei user_prompt, assistant_response und api_response_body
• request_id bei den API-Ereignissen, gespeichert als requestId in den Assistenteneinträgen des Transkripts
• tool_use_id bei den Ereignissen tool_result und tool_decision sowie bei safety_event-Ereignissen, außer denen für das Ende eines Turns

Benutzer-Prompt-Ereignis

Wird protokolliert, wenn ein Prompt gesendet wird, einschließlich Turns, die Claude Code selbst startet.

Ereignisname: claude_code.user_prompt

Attribute:

• Alle Standardattribute
• event.name: "user_prompt"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• prompt_length: Länge des Prompts
• prompt: Inhalt des Prompts. Standardmäßig geschwärzt. Setzen Sie OTEL_LOG_USER_PROMPTS=1, um ihn einzuschließen
• prompt_text: Derselbe Wert wie prompt, unter derselben Bedingung geschwärzt. Ein Backend, das Attributnamen mit Punkten als verschachtelte Objekte speichert, liest prompt.id als id innerhalb eines Objekts namens prompt und kann dadurch den Prompt-String verlieren. Lesen Sie dort stattdessen prompt_text. Erfordert Claude Code v2.1.287 oder höher
• message.uuid: UUID der resultierenden Benutzernachricht, entsprechend dem gespeicherten Transkripteintrag. Nicht vorhanden bei Befehlsaufrufen, die null oder viele Nachrichten erzeugen können.
• command_name: Befehlsname, wenn der Prompt einen Befehl aufruft. Namen integrierter und gebündelter Befehle wie compact oder debug werden unverändert ausgegeben; Aliase wie reset werden so ausgegeben, wie sie eingegeben wurden, und nicht als kanonischer Name. Namen benutzerdefinierter, Plugin- und MCP-Befehle werden auf custom bzw. mcp reduziert, sofern nicht OTEL_LOG_TOOL_DETAILS=1 gesetzt ist
• command_source: Herkunft des Befehls, falls vorhanden: builtin, custom oder mcp. Von Plugins bereitgestellte Befehle werden als custom gemeldet

Assistenten-Antwort-Ereignis

Wird nach jeder API-Anfrage protokolliert, die Textinhalt vom Modell zurückgibt. Nur die Textblöcke der Antwort werden einbezogen; Thinking-Blöcke und Tool-Use-Blöcke sind ausgeschlossen.

Ereignisname: claude_code.assistant_response

Attribute:

• Alle Standardattribute
• event.name: "assistant_response"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• response_length: Länge des Antworttexts in Zeichen
• response: Antworttext, abgeschnitten beim Inhaltslimit (standardmäßig 60 KB). Standardmäßig zu <REDACTED> geschwärzt. Setzen Sie OTEL_LOG_ASSISTANT_RESPONSES=1, um ihn einzuschließen. Wenn OTEL_LOG_ASSISTANT_RESPONSES nicht gesetzt ist, steuert stattdessen OTEL_LOG_USER_PROMPTS dieses Attribut. Setzen Sie daher OTEL_LOG_ASSISTANT_RESPONSES=0, um Antworten geschwärzt zu halten, während die Prompt-Protokollierung aktiviert ist
• model: Modellkennung (zum Beispiel „claude-sonnet-5“)
• request_id: API-Anfrage-ID, beschrieben unter Attribute zur Ereigniskorrelation
• message.uuid: UUID des letzten Transkripteintrags der Antwort. Eine API-Antwort wird als ein Transkripteintrag pro Inhaltsblock gespeichert; dies ist der letzte, an den die parentUuid des nächsten Turns anknüpft.
• query_source: Subsystem, das die Anfrage gestellt hat, etwa "repl_main_thread", "compact" oder ein Subagent-Name

Tool-Ergebnis-Ereignis

Wird protokolliert, wenn ein Tool die Ausführung abschließt. Wird nicht ausgegeben, wenn der Tool-Aufruf abgelehnt wurde; für Ablehnungen siehe das Tool-Entscheidungsereignis.

Ereignisname: claude_code.tool_result

Attribute:

• Alle Standardattribute
• event.name: "tool_result"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• tool_name: Name des Tools
• tool_use_id: Eindeutige Kennung für diesen Tool-Aufruf. Entspricht der an Hooks übergebenen tool_use_id und ermöglicht so die Korrelation zwischen OTel-Ereignissen und von Hooks erfassten Daten.
• request_id: die request_id der API-Antwort, die diesen Tool-Aufruf enthielt, sodass Sie den Aufruf mit den API-Events dieser Antwort verknüpfen können. Fehlt, wenn diese Antwort keine Anfrage-ID hatte oder wenn keine API-Antwort den Aufruf enthielt. Erfordert Claude Code v2.1.310 oder höher
• success: "true" oder "false"
• duration_ms: Ausführungszeit in Millisekunden
• error_type: String mit der Fehlerkategorie, wenn das Tool fehlgeschlagen ist, etwa "Error:ENOENT" oder "ShellError"
• error (wenn OTEL_LOG_TOOL_DETAILS=1): Vollständige Fehlermeldung, wenn das Tool fehlgeschlagen ist
• decision_type: Immer "accept", da dieses Ereignis nur nach der Ausführung des Tools ausgegeben wird. Abgelehnte Aufrufe erzeugen kein Tool-Ergebnis
• decision_source: Woher die Berechtigungsentscheidung stammt. Einer der Werte "config", "hook", "user_permanent" oder "user_temporary". Was jeder Wert bedeutet, erfahren Sie beim Tool-Entscheidungsereignis. Die nur bei Ablehnungen vorkommenden Quellen "user_abort" und "user_reject" erscheinen bei diesem Ereignis nie.
• tool_input_size_bytes: Größe der JSON-serialisierten Tool-Eingabe in Byte
• tool_result_size_bytes: Größe des Tool-Ergebnisses in Byte
• mcp_server_scope: Kennung des Geltungsbereichs des MCP-Servers (für MCP-Tools)
• vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (wenn OTEL_LOG_TOOL_DETAILS=1): die Commit-Identität eines erfolgreichen git commit, der vom Bash- oder PowerShell-Tool ausgeführt wurde. vcs.ref.head.revision ist der Commit-SHA, vcs.ref.head.name ist der Branch, auf dem committet wurde, und vcs.ref.head.type ist branch. Name und Typ werden weggelassen, wenn der Commit auf einem Detached HEAD erstellt wurde. Erfordert Claude Code v2.1.269 oder höher
• tool_parameters (wenn OTEL_LOG_TOOL_DETAILS=1): JSON-String mit toolspezifischen Parametern. Bei den integrierten Servern von Claude Desktop wird in Sitzungen, die Claude Desktop gehören, das Paar mcp_server_name/mcp_tool_name auch bei deaktiviertem Flag einbezogen – dieselbe vom Host festgelegte Ausnahme wie beim Tool-Entscheidungsereignis. Die Parameter variieren je nach Tool:
  • Für das Bash-Tool: enthält bash_command, full_command, timeout, description und dangerouslyDisableSandbox sowie git_commit_id und git_branch, wenn ein git commit-Befehl erfolgreich ist. git_commit_id ist der vollständige Commit-SHA, wenn der Commit der HEAD des Arbeitsverzeichnisses der Sitzung ist, andernfalls der von Git abgekürzte SHA. git_branch ist der Branch, auf dem committet wurde; bei einem Detached HEAD weggelassen
  • Für das Workspace-Bash-Tool der Desktop-App, das tool_name ebenfalls als Bash meldet: enthält nur bash_command, full_command und timeout
  • Für MCP-Tools: enthält mcp_server_name, mcp_tool_name
  • Für das Skill-Tool: enthält skill_name
  • Für das Agent-Tool oder das ältere Task-Tool: enthält subagent_type
• tool_input (wenn OTEL_LOG_TOOL_DETAILS=1): JSON-serialisierte Tool-Argumente. Einzelne Werte über 512 Zeichen werden abgeschnitten, und die gesamte Payload ist auf ca. 4.000 Zeichen begrenzt. Gilt für alle Tools einschließlich MCP-Tools.

API-Anfrage-Ereignis

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

Ereignisname: claude_code.api_request

Attribute:

• Alle Standardattribute
• event.name: "api_request"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• model: Verwendetes Modell (zum Beispiel „claude-sonnet-5“)
• cost_usd: Geschätzte Kosten in USD
• cost_usd_micros: Geschätzte Kosten in Millionstel US-Dollar, ausgegeben als Ganzzahl
• duration_ms: Dauer der Anfrage in Millisekunden
• input_tokens: Anzahl der Eingabe-Token, ohne Token, die aus dem Prompt-Cache gelesen oder in ihn geschrieben wurden
• 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
• cache_creation_5m_tokens, cache_creation_1h_tokens: die Anzahl der Token, die laut API-Antwort mit einer Cache-Lebensdauer von fünf Minuten in den Cache geschrieben wurden, und die Anzahl der mit einer Lebensdauer von einer Stunde geschriebenen. Beide sind 0, wenn die API-Antwort sie nicht meldet, auch wenn cache_creation_tokens größer als null ist. Erfordert Claude Code v2.1.300 oder höher
• request_id: API-Anfrage-ID, etwa "req_011...", beschrieben unter Attribute zur Ereigniskorrelation.
• client_request_id: Vom Client generierte UUID, die als Request-Header x-client-request-id gesendet wird; wann sie vorhanden ist, sehen Sie in der Tabelle Attribute zur Ereigniskorrelation
• speed: "fast" oder "normal", gibt an, ob der Fast-Modus aktiv war
• query_source: Subsystem, das die Anfrage gestellt hat, etwa "repl_main_thread", "compact" oder ein Subagent-Name
• effort: Auf die Anfrage angewendete Effort-Stufe: "low", "medium", "high", "xhigh" oder "max". Nicht vorhanden, wenn Claude Code keine Effort-Stufe sendet, zum Beispiel bei einem Modell, das Effort nicht unterstützt.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Zuordnung der Anfrage zu Skill, Plugin, Agent und MCP. Definitionen und Schwärzungsverhalten finden Sie unter Kostenzähler.

API-Fehler-Ereignis

Wird 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
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• model: Verwendetes Modell (zum Beispiel „claude-sonnet-5“)
• error: Fehlermeldung
• status_code: HTTP-Statuscode als Zahl. Nicht vorhanden bei Nicht-HTTP-Fehlern wie Verbindungsfehlern.
• duration_ms: Dauer der Anfrage in Millisekunden
• attempt: Anzahl der unternommenen Versuche, einschließlich der ursprünglichen Anfrage. Unter Ausgeschöpfte Wiederholungsversuche erkennen erfahren Sie, wann die Zählung neu beginnt
• request_id: API-Anfrage-ID, etwa "req_011...", beschrieben unter Attribute zur Ereigniskorrelation.
• client_request_id: Vom Client generierte UUID, die als Request-Header x-client-request-id gesendet wird. Auch dann verfügbar, wenn ein Fehler wie ein Timeout oder Verbindungsfehler nie eine request_id vom Server erzeugt hat; wann sie vorhanden ist, sehen Sie in der Tabelle Attribute zur Ereigniskorrelation.
• speed: "fast" oder "normal", gibt an, ob der Fast-Modus aktiv war
• query_source: Subsystem, das die Anfrage gestellt hat, etwa "repl_main_thread", "compact" oder ein Subagent-Name
• effort: Auf die Anfrage angewendete Effort-Stufe. Nicht vorhanden, wenn Claude Code keine Effort-Stufe sendet, zum Beispiel bei einem Modell, das Effort nicht unterstützt.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Zuordnung der Anfrage zu Skill, Plugin, Agent und MCP. Definitionen und Schwärzungsverhalten finden Sie unter Kostenzähler.

API-Ablehnungs-Ereignis

Wird protokolliert, wenn eine API-Anfrage stop_reason: "refusal" zurückgibt. Ablehnungen kommen in einem erfolgreichen Antwortstream an und nicht als HTTP-Fehler, daher wird das Ereignis api_error für sie nicht ausgelöst. Mit diesem Ereignis können Sie die Häufigkeit von Ablehnungen verfolgen und Ablehnungen nach denselben Attributen wie api_request und api_error gruppieren.

Ereignisname: claude_code.api_refusal

Attribute:

• Alle Standardattribute
• event.name: "api_refusal"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• model: Modellkennung aus der Anfrage
• request_id: API-Anfrage-ID, etwa "req_011...", beschrieben unter Attribute zur Ereigniskorrelation.
• query_source: Subsystem, das die Anfrage gestellt hat, etwa "repl_main_thread", "compact" oder ein Subagent-Name. Definitionen finden Sie unter api_request.
• speed: Entweder "fast", wenn der Fast-Modus aktiv ist, oder "normal"
• attempt: Nummer des Versuchs. Der erste Versuch ist 1.
• effort: Auf die Anfrage angewendete Effort-Stufe. Nicht vorhanden, wenn Claude Code keine Effort-Stufe sendet, zum Beispiel bei einem Modell, das Effort nicht unterstützt.
• server_fallback_hop: true, wenn der serverseitige Modell-Fallback der API diese Ablehnung bereits mit einem anderen Modell erneut versucht hat, sodass der Benutzer diese konkrete Ablehnung nicht gesehen hat. false, wenn die Anfrage mit einer Ablehnung endete. Ein einzelner Turn kann sowohl ein Hop-Ereignis mit true als auch ein späteres abschließendes Ereignis mit false ausgeben, wenn auch das Fallback-Modell ablehnt.
• has_category: true, wenn die API-Antwort eine stop_details.category mit dem Wert "cyber", "bio", "frontier_llm" oder "reasoning_extraction" enthielt. false, wenn die Antwort keine Kategorie oder einen Wert außerhalb dieser Menge enthielt. Nicht vorhanden, wenn server_fallback_hop true ist, da Hop-Blöcke kein stop_details enthalten.
• has_explanation: true, wenn die API-Antwort eine stop_details.explanation enthielt, andernfalls false. Nicht vorhanden, wenn server_fallback_hop true ist.
• category: Der Wert stop_details.category aus der API-Antwort. Einer der Werte "cyber", "bio", "frontier_llm" oder "reasoning_extraction". Nur vorhanden, wenn OTEL_LOG_TOOL_DETAILS=1 gesetzt ist und has_category true ist.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: Zuordnung der Anfrage zu Skill, Plugin, Agent und MCP. Definitionen und Schwärzungsverhalten finden Sie unter Kostenzähler.

API-Request-Body-Ereignis

Wird für jeden API-Anfrageversuch protokolliert, wenn OTEL_LOG_RAW_API_BODIES gesetzt ist. Pro Versuch wird ein Ereignis ausgegeben, sodass Wiederholungsversuche mit angepassten Parametern jeweils ein eigenes Ereignis erzeugen.

Ereignisname: claude_code.api_request_body

Attribute:

• Alle Standardattribute
• event.name: "api_request_body"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• body: JSON-serialisierte Anfrageparameter der Messages API, etwa der System-Prompt, die Nachrichten und die Tools, abgeschnitten beim Inhaltslimit (standardmäßig 60 KB). Extended-Thinking-Inhalte in vorherigen Assistenten-Turns werden geschwärzt. Wird nur im Inline-Modus ausgegeben (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Absoluter Pfad zu einer Datei <dir>/<uuid>.request.json, die den nicht abgeschnittenen Body enthält. Wird nur im Dateimodus ausgegeben (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Länge des nicht abgeschnittenen Bodys. UTF-8-Byte bei OTEL_LOG_RAW_API_BODIES=file:<dir> oder UTF-16-Codeeinheiten bei =1
• body_truncated: "true", wenn beim Inline-Modus abgeschnitten wurde. Nicht vorhanden im Dateimodus und wenn nicht abgeschnitten wurde.
• model: Modellkennung aus den Anfrageparametern
• query_source: Subsystem, das die Anfrage gestellt hat (zum Beispiel "compact")
• request_body_id: UUID, die den Request-Body dieses Versuchs identifiziert. Das api_response_body-Ereignis für den erfolgreichen Versuch enthält denselben Wert, sodass Sie eine Antwort genau der Anfrage zuordnen können, die sie erzeugt hat. Erfordert Claude Code v2.1.274 oder höher

API-Response-Body-Ereignis

Wird für jede erfolgreiche API-Antwort protokolliert, wenn OTEL_LOG_RAW_API_BODIES gesetzt ist.

Im Dateimodus (OTEL_LOG_RAW_API_BODIES=file:<dir>) hängt Claude Code für jede erfolgreiche Antwort außerdem eine JSON-Zeile an <dir>/index.jsonl an, mit den Feldern timestamp, session_id, query_source, model, request_id, message_id, message_uuid, request_file und response_file. Lesen Sie diese Datei, um die Anfrage- und Antwortdateien zu einer bestimmten Transkriptnachricht zu finden, ohne Ihr Telemetrie-Backend abzufragen. Die Indexdatei erfordert Claude Code v2.1.274 oder höher.

Ereignisname: claude_code.api_response_body

Attribute:

• Alle Standardattribute
• event.name: "api_response_body"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• body: JSON-serialisierte Antwort der Messages API, einschließlich ID, Inhaltsblöcken, Nutzung und Stoppgrund, abgeschnitten beim Inhaltslimit (standardmäßig 60 KB). Extended-Thinking-Inhalte werden geschwärzt. Wird nur im Inline-Modus ausgegeben (OTEL_LOG_RAW_API_BODIES=1).
• body_ref: Absoluter Pfad zu einer Datei <dir>/<request_id>.response.json, die den nicht abgeschnittenen Body enthält. Wird nur im Dateimodus ausgegeben (OTEL_LOG_RAW_API_BODIES=file:<dir>).
• body_length: Länge des nicht abgeschnittenen Bodys. UTF-8-Byte bei OTEL_LOG_RAW_API_BODIES=file:<dir> oder UTF-16-Codeeinheiten bei =1
• body_truncated: "true", wenn beim Inline-Modus abgeschnitten wurde. Nicht vorhanden im Dateimodus und wenn nicht abgeschnitten wurde.
• model: Modellkennung
• query_source: Subsystem, das die Anfrage gestellt hat
• request_id: API-Anfrage-ID, etwa "req_011...", beschrieben unter Attribute zur Ereigniskorrelation.
• request_body_id: Die request_body_id des api_request_body-Ereignisses, auf das diese Antwort antwortet. Erfordert Claude Code v2.1.274 oder höher
• message.id: Nachrichten-ID, die die API der Antwort zugewiesen hat, das Feld id des Response-Bodys. Erfordert Claude Code v2.1.274 oder höher
• message.uuid: UUID des letzten Transkripteintrags der Antwort. Zusammen mit request_body_id verknüpft sie eine Transkriptnachricht mit den zugehörigen Request- und Response-Bodys. Erfordert Claude Code v2.1.274 oder höher

Tool-Entscheidungsereignis

Wird protokolliert, wenn eine Berechtigungsentscheidung für ein Tool getroffen wird (akzeptieren/ablehnen).

Ereignisname: claude_code.tool_decision

Attribute:

• Alle Standardattribute

• event.name: "tool_decision"

• event.timestamp: ISO-8601-Zeitstempel

• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation

• tool_name: Name des Tools (zum Beispiel „Read“, „Edit“, „Write“, „NotebookEdit“)

• tool_use_id: Eindeutige Kennung für diesen Tool-Aufruf. Entspricht der an Hooks übergebenen tool_use_id und ermöglicht so die Korrelation zwischen OTel-Ereignissen und von Hooks erfassten Daten.

• request_id: die request_id der API-Antwort, die diesen Tool-Aufruf enthielt, sodass Sie den Aufruf mit den API-Events dieser Antwort verknüpfen können. Fehlt, wenn diese Antwort keine Anfrage-ID hatte oder wenn keine API-Antwort den Aufruf enthielt. Erfordert Claude Code v2.1.310 oder höher

• decision: Entweder "accept" oder "reject"

• tool_source: Immer vorhanden. Die Herkunft des Tools, als geschlossene Menge von der CLI festgelegter Werte:

  • "builtin": die eigenen Tools der CLI
  • "mcp": MCP-Server allgemein
  • "sdk_host_builtin_mcp": ein prozessinterner Server, der in Claude Desktop selbst integriert ist, in einer Sitzung, die Claude Desktop gehört. Eine Sitzung gehört Claude Desktop, wenn Claude Desktop sie über einen seiner eigenen Einstiegspunkte claude-desktop, claude-desktop-3p oder local-agent gestartet hat und diese Sitzung kein verschachteltes Kind ist; verschachtelte Sitzungen, einschließlich Sitzungen, die Claude Code selbst startet, melden diese Server als "mcp"

• source: Woher die Entscheidung stammt:

  • "config": Automatisch ohne Nachfrage entschieden, durch eine dieser Quellen:

    • Projekteinstellungen
    • Allow- oder Deny-Regeln in den persönlichen Einstellungen des Benutzers
    • Verwaltete Unternehmensrichtlinie
    • Die Flags --allowedTools oder --disallowedTools
    • Der aktive Berechtigungsmodus
    • Der Klassifikator des Auto-Modus, dessen Urteil dasselbe Ereignis in classifier_verdict erfasst
    • Eine Freigabe für den Rest der Sitzung, die bei einer früheren Berechtigungsabfrage in derselben interaktiven CLI-Sitzung erteilt wurde
    • Das Tool ist grundsätzlich sicher

    Der Wert von source gibt nicht an, welche dieser Quellen zugetroffen hat. Um herauszufinden, welche einen Aufruf abgelehnt hat, suchen Sie das Sicherheitsereignis mit derselben tool_use_id und lesen Sie dessen Attribute category und rule_source. Für einige abgelehnte Aufrufe gibt es kein Sicherheitsereignis.

    Claude Code meldet "config" auch, wenn die Anfrage für die Berechtigungsabfrage selbst fehlschlägt. Diese Anfrage schlägt beispielsweise fehl, wenn der canUseTool-Callback des Agent SDK oder das Tool --permission-prompt-tool ein ungültiges Ergebnis zurückgibt oder wenn der Eingabestream geschlossen wird, während die Anfrage aussteht.

  • "hook": Ein PreToolUse- oder PermissionRequest-Hook hat die Entscheidung zurückgegeben.

  • "user_permanent": Wird ausgegeben, wenn der Benutzer bei einer Berechtigungsabfrage „Yes, and don't ask again for ...“ gewählt hat, wodurch eine allow-Regel in seinen persönlichen Einstellungen gespeichert wird. In der interaktiven CLI wird dies nur für genau diese Wahl ausgegeben; spätere Aufrufe, die der gespeicherten Regel entsprechen, geben stattdessen "config" aus. In Agent SDK- oder nicht interaktiven -p-Sitzungen geben sowohl die ursprüngliche Wahl als auch spätere Regeltreffer "user_permanent" aus. Wird als Annahme behandelt.

  • "user_temporary": Wird ausgegeben, wenn der Benutzer bei einer Berechtigungsabfrage „Yes“ für eine einmalige Genehmigung gewählt hat oder bei einer Abfrage zum Bearbeiten oder Lesen einer Datei eine Option gewählt hat, die Zugriff für den Rest der Sitzung gewährt. In der interaktiven CLI wird dies nur für die Wahl selbst ausgegeben; spätere Aufrufe, die durch diese sitzungsbezogene Freigabe erlaubt werden, geben stattdessen "config" aus. In Agent SDK- oder nicht interaktiven -p-Sitzungen geben sowohl die Wahl als auch spätere Treffer "user_temporary" aus. Wird als Annahme behandelt.

  • "user_abort": Wird ausgegeben, wenn der Benutzer die Berechtigungsabfrage geschlossen hat, ohne zu antworten. In Agent SDK- und nicht interaktiven -p-Sitzungen gehört dazu auch das Unterbrechen des Turns, während eine Berechtigungsanfrage über canUseTool oder --permission-prompt-tool aussteht. Wird als Ablehnung behandelt.

  • "user_reject": Wird ausgegeben, wenn der Benutzer bei der Nachfrage „No“ gewählt hat. In der interaktiven CLI wird dies nur für genau diese Wahl ausgegeben; Aufrufe, die einer deny-Regel in den persönlichen Einstellungen des Benutzers entsprechen, geben stattdessen "config" aus. In Agent SDK- oder nicht interaktiven -p-Sitzungen geben Aufrufe, die einer deny-Regel in den persönlichen Einstellungen entsprechen, "user_reject" aus. Wird als Ablehnung behandelt.

• classifier_verdict: Das Urteil des Klassifikators des Auto-Modus für den Aufruf oder der Grund, warum Claude Code den Aufruf abgelehnt hat, wenn kein Urteil kam. Erfordert Claude Code v2.1.301 oder höher

  • "allow": Der Klassifikator hat den Aufruf genehmigt
  • "block": Der Klassifikator hat den Aufruf blockiert. Eine Klassifikatorprüfung, die mittendrin fehlschlägt, kann ebenfalls mit "block" enden, sodass ein teilweiser Ausfall des Klassifikators als Zunahme von Blockierungen statt als "unavailable" erscheinen kann
  • "no_verdict": Die Prüfung lief, lieferte aber kein verwertbares Urteil, daher hat Claude Code den Aufruf abgelehnt. Die Ablehnung bedeutet nicht, dass der Klassifikator den Aufruf als unsicher eingestuft hat
  • "unavailable": Die Anfrage an den Klassifikator ist fehlgeschlagen, zum Beispiel wegen eines Rate-Limits, eines Timeouts oder eines Verbindungsfehlers, daher hat Claude Code den Aufruf abgelehnt. Bei der serverseitigen Klassifikatorprüfung kennzeichnet der Wert außerdem einen Aufruf, der abgelehnt wurde, weil der Server kein Sicherheitsurteil zurückgegeben hat

  Das Attribut erscheint auch bei Aufrufen im Plan-Modus, wenn der Klassifikator Befehle im Plan-Modus prüft. Das Attribut fehlt in diesen Fällen:

  • Eine Allow- oder Deny-Berechtigungsregel hat über den Aufruf entschieden
  • Claude Code hat den Aufruf im Auto-Modus genehmigt, ohne den Klassifikator zu fragen
  • Der Benutzer hat die Abfrage beantwortet, die Claude Code nach wiederholten Blockierungen angezeigt hat
  • In einem -p-Lauf ohne --permission-prompt-tool hat Claude Code den Aufruf nach wiederholten Blockierungen abgelehnt, weil niemand eine Abfrage beantworten konnte. Dieses Ereignis meldet decision als "reject" und source als "config"

• classifier_category (wenn OTEL_LOG_TOOL_DETAILS=1): Der Name der integrierten Regel, die der Klassifikator beim Blockieren des Aufrufs genannt hat, in Kleinbuchstaben mit Unterstrichen, etwa "data_exfiltration" für die Regel Data Exfiltration. Erfordert Claude Code v2.1.301 oder höher. Das Attribut ist vorhanden, wenn beide der folgenden Bedingungen erfüllt sind:

  • classifier_verdict ist "block"
  • Der Klassifikator hat genau eine Regel genannt, und diese Regel ist eine integrierte Regel und keine, die Sie geschrieben haben

  Vor v2.1.302 fehlte das Attribut auch bei jeder Blockierung, über die die serverseitige Klassifikatorprüfung entschieden hat.

• permission_mode: Berechtigungsmodus, der aktiv war, als die Berechtigungsprüfung dieses Aufrufs begann: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" oder "auto". Der manuelle Modus erscheint als "default". Ein Aufruf eines Subagenten meldet den Berechtigungsmodus des Subagenten statt den der Sitzung. Erfordert Claude Code v2.1.301 oder höher

• tool_parameters (wenn OTEL_LOG_TOOL_DETAILS=1): JSON-String mit toolspezifischen Parametern. Gleiche Struktur wie beim Tool-Ergebnis-Ereignis, ohne Felder, die erst nach der Ausführung entstehen, wie git_commit_id. Bei einem akzeptierten Aufruf können die Werte von tool_result abweichen, wenn die Berechtigungsentscheidung die Tool-Eingabe über updatedInput umschreibt. Verwenden Sie dieses Attribut, um zu sehen, welcher Befehl abgelehnt wurde, wenn decision "reject" ist.

  • Für "sdk_host_builtin_mcp"-Tools: mcp_server_name und mcp_tool_name sind auch dann enthalten, wenn OTEL_LOG_TOOL_DETAILS deaktiviert ist, da die Host-Anwendung diese Namen festlegt; ohne sie ließe sich ein abgelehnter Aufruf an einen dieser integrierten Server im Standardstream nicht zuordnen. Bei benutzerkonfigurierten MCP-Servern ist der tool_name des Ereignisses immer das Literal "mcp_tool", und die Server- und Tool-Namen erscheinen nur bei aktiviertem Flag in tool_parameters; Argumentinhalte erfordern überall das Flag.
  • Für das Bash-Tool: enthält bash_command, full_command, timeout, description, dangerouslyDisableSandbox. Das Workspace-Bash-Tool der Desktop-App meldet tool_name ebenfalls als Bash, enthält aber nur bash_command, full_command und timeout
  • Für MCP-Tools: enthält mcp_server_name, mcp_tool_name
  • Für das Skill-Tool: enthält skill_name
  • Für das Agent-Tool oder das ältere Task-Tool: enthält subagent_type

Wenn Sie OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT des OpenTelemetry SDK unter die Anzahl der Attribute eines tool_decision-Events senken, verwirft das SDK die Attribute, die Claude Code zuletzt gesetzt hat. Das SDK verwirft diese vor allen anderen Attributen, in dieser Reihenfolge, wobei es diejenigen überspringt, die das Event nicht trägt:

1. parent_agent_id
2. agent_id
3. request_id
4. permission_mode
5. classifier_category
6. classifier_verdict

permission_mode, classifier_category und classifier_verdict werden ab Claude Code v2.1.302 in dieser Reihenfolge verworfen. parent_agent_id, agent_id und request_id erfordern v2.1.310 oder höher.

Sicherheitsereignis

Wird protokolliert, wenn eine Prüfung einen Tool-Aufruf ablehnt oder eine Berechtigungsabfrage erfordert, außer bei Aufrufen ohne Sicherheitsereignis. Wird außerdem protokolliert, wenn der Netzwerk-Proxy der Sandbox eine Verbindung oder Anfrage ablehnt und wenn ein Hook ein Ergebnis blockiert. Erfordert Claude Code v2.1.307 oder neuer.

Das Ereignis wird zusammen mit den anderen Ereignissen exportiert und hat keine eigene Einstellung. Die eigenen Attribute des Ereignisses enthalten keinen Befehlstext, keine Dateipfade, keine Hostnamen und keine Namen von MCP-Servern oder -Tools. Der Datensatz enthält außerdem die Standardattribute, die jedes Ereignis hat und zu denen workspace.host_paths und die Repository-Attribute gehören können. Um den Befehl oder das MCP-Tool hinter einem Ereignis zu sehen, setzen Sie OTEL_LOG_TOOL_DETAILS=1 und lesen Sie tool_parameters beim passenden tool_decision-Ereignis.

Ereignisname: claude_code.safety_event

Attribute:

• Alle Standardattribute
• event.name: "safety_event"
• event.timestamp: Zeitstempel nach ISO 8601
• event.sequence: Zähler pro Prozess zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• category: Die Prüfung oder das Ergebnis, ein Kategoriewert
• decision: "accept", "reject" oder "sent_back", wenn ein Hook ein Ergebnis oder das Ende eines Turns blockiert hat
• decision_source: Wer oder was entschieden hat, ein source-Wert von tool_decision oder "other"
• reason_code: Der Grund der Prüfung, etwa "rule:policySettings", "mode:dontAsk", "hook:PreToolUse", "classifier:auto-mode", "bashMiss:too-complex" oder "unknown"
• reason_type: Der Grundtyp der Prüfung, etwa "rule", "subcommandResults", "mode", "hook", "classifier" oder "asyncAgent"
• rule_source: Einstellungsquelle der beteiligten Regel, etwa "policySettings", "userSettings", "projectSettings", "localSettings", "flagSettings", "cliArg" oder "session"
• grant_scope: "once" oder "session" für eine Abfrage, die genehmigt wurde, ohne eine Regel in einer Einstellungsdatei zu speichern
• circuit_breaker: Die integrierte Sicherheitsprüfung, etwa "dangerousRemoval", "outsideReadsBlocked" oder "claudeSettingsFile"
• classifier_category: Bei OTEL_LOG_TOOL_DETAILS=1 die integrierte Regel hinter einer Blockierung im Auto-Modus, etwa "data_exfiltration"
• hook_event: "pre_tool_use" für einen PreToolUse-Hook oder "post_tool_use", "post_tool_use_failure", "stop" oder "subagent_stop" bei "hook_review"-Ereignissen
• tool_class: "bash" für Bash und Monitor, "powershell", "file" für Read, Edit, Write, NotebookEdit, Glob und Grep, "web" für WebFetch und WebSearch, "mcp" oder "other"
• tool_name: Der Name des Tools, etwa "Bash" für ein integriertes Tool, oder "mcp_tool", "skill_tool", "dynamic_tool" oder "other_tool"
• tool_source: "builtin", "mcp" oder "sdk_host_builtin_mcp", wie bei tool_decision
• permission_mode: Der Berechtigungsmodus des Aufrufs zum Zeitpunkt der Prüfung: "default", "plan", "acceptEdits", "bypassPermissions", "dontAsk" oder "auto"
• tool_use_id: Die ID des Aufrufs, wie bei tool_decision und tool_result
• sandbox_violation_count: Wie viele unterschiedliche Verbindungen oder Anfragen aus dem Befehl des Aufrufs der Netzwerk-Proxy der Sandbox abgelehnt hat, "0" bis "20" als Zeichenfolge. Ablehnungen werden für einen in einer Sandbox ausgeführten Befehl gezählt, der im Vordergrund beendet wurde
• sandbox_enabled: "true", wenn Sandboxing für die Sitzung aktiviert ist, andernfalls "false"

Dies sind die eigenen Attribute des Ereignisses, wenn eine deny-Regel aus den verwalteten Einstellungen einen Bash-Befehl ablehnt:

{
  "event.name": "safety_event",
  "category": "managed_policy",
  "decision": "reject",
  "decision_source": "config",
  "reason_code": "rule:policySettings",
  "rule_source": "policySettings",
  "tool_class": "bash",
  "tool_name": "Bash",
  "tool_source": "builtin",
  "permission_mode": "default",
  "tool_use_id": "toolu_01ABC123...",
  "sandbox_violation_count": "0",
  "sandbox_enabled": "false"
}

Kategorien von Sicherheitsereignissen

Um Proxy-Ablehnungen unter beliebigen category-Werten zu finden, filtern Sie nach einem sandbox_violation_count, der vorhanden und nicht "0" ist.

Aufrufe ohne Sicherheitsereignis

Um Aufrufe zu finden, die abgelehnt wurden, weil niemand eine Abfrage ohne Kategorie beantworten konnte, suchen Sie nach tool_decision-Ereignissen, die "reject" mit source "config" melden und für deren tool_use_id kein Sicherheitsereignis existiert. Solche Ablehnungen treten in einer -p-Ausführung auf, die weder --permission-prompt-tool noch --permission-prompts none verwendet.

Prüfen Sie Aufrufe wie die folgenden auf ein tool_decision-Ereignis, da sie kein Sicherheitsereignis haben, abgesehen von "sandbox_network"-, "sandbox_other"- oder "hook_review"-Ereignissen, die nach ihrer Ausführung gesendet werden:

• Ein Aufruf, der bei einer Abfrage ohne Kategorie genehmigt wurde
• Ein Aufruf, den ein canUseTool-Callback oder ein --permission-prompt-tool-Tool bei einer Abfrage genehmigt hat, die nur ein PreToolUse-Hook erforderte
• Ein Aufruf von AskUserQuestion oder ExitPlanMode, ob abgelehnt oder nicht

Abfragen ohne Kategorie

Eine Abfrage hat keine Kategorie, wenn kein category-Wert ihre Prüfung benennt, etwa die Abfrage im Modus default für eine Bearbeitung innerhalb Ihres Arbeitsverzeichnisses.

Ereignis für geänderten Berechtigungsmodus

Wird protokolliert, wenn sich der Berechtigungsmodus ändert, zum Beispiel durch Durchschalten mit Shift+Tab, durch Verlassen des Plan-Modus oder durch eine Gate-Prüfung des Auto-Modus.

Um Tool-Aufrufe nach dem Berechtigungsmodus zu gruppieren, in dem sie jeweils geprüft wurden, verwenden Sie permission_mode beim Tool-Entscheidungsereignis.

Ereignisname: claude_code.permission_mode_changed

Attribute:

• Alle Standardattribute
• event.name: "permission_mode_changed"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• from_mode: Der vorherige Berechtigungsmodus, zum Beispiel "default", "plan", "acceptEdits", "auto" oder "bypassPermissions"
• to_mode: Der neue Berechtigungsmodus
• trigger: Was die Änderung verursacht hat, zum Beispiel "shift_tab", "exit_plan_mode" oder "auto_gate_denied". Fehlt bei einigen Änderungen, etwa wenn das SDK den Berechtigungsmodus über setPermissionMode() setzt

Authentifizierungsereignis

Wird protokolliert, wenn /login oder /logout abgeschlossen wird.

Ereignisname: claude_code.auth

Attribute:

• Alle Standardattribute
• event.name: "auth"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• action: "login" oder "logout"
• success: "true" oder "false"
• auth_method: Authentifizierungsmethode, etwa "oauth"
• error_category: Kategorisierte Fehlerart, wenn die Aktion fehlgeschlagen ist. Die unverarbeitete Fehlermeldung wird nie einbezogen
• status_code: HTTP-Statuscode als String, wenn die Aktion mit einem HTTP-Fehler fehlgeschlagen ist

MCP-Server-Verbindungsereignis

Wird protokolliert, wenn ein MCP-Server eine Verbindung herstellt, trennt oder die Verbindung nicht herstellen kann.

Ereignisname: claude_code.mcp_server_connection

Attribute:

• Alle Standardattribute
• event.name: "mcp_server_connection"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• status: "connected", "failed" oder "disconnected"
• transport_type: Transport des Servers, etwa "stdio", "sse" oder "http"
• server_scope: Geltungsbereich, in dem der Server konfiguriert ist, etwa "user", "project" oder "local"
• duration_ms: Dauer des Verbindungsversuchs in Millisekunden
• error_code: Fehlercode, wenn die Verbindung fehlgeschlagen ist
• is_plugin: true, wenn der Server von einem Plugin bereitgestellt wird, andernfalls false
• plugin_id_hash (wenn is_plugin true ist): Stabiler Hash aus Plugin-Name und Marketplace, um Ereignisse nach Plugin zu gruppieren, ohne den Namen offenzulegen. Claude Code berechnet ihn wie beim Plugin-geladen-Ereignis beschrieben
• plugin.name (wenn is_plugin true ist): Name des Plugins, das den Server bereitstellt. Bei Drittanbieter-Plugins ist dies der literale String "third-party", sofern nicht OTEL_LOG_TOOL_DETAILS=1 gesetzt ist; dadurch wird verhindert, dass Namen von Drittanbieter-Plugins standardmäßig in Logs erscheinen. Plugins aus offiziellen Anthropic-Quellen werden immer mit Namen identifiziert. Die Attribute plugin_id_hash und plugin.name fließen an Ihr eigenes Monitoring-Backend und werden nicht an Anthropic gesendet
• server_name (wenn OTEL_LOG_TOOL_DETAILS=1): Konfigurierter Servername
• error (wenn OTEL_LOG_TOOL_DETAILS=1): Vollständige Fehlermeldung, wenn die Verbindung fehlgeschlagen ist

Ereignis für interne Fehler

Wird protokolliert, wenn Claude Code einen unerwarteten internen Fehler abfängt. Nur der Name der Fehlerklasse und ein Code im errno-Stil werden erfasst. Die Fehlermeldung und der Stacktrace werden nie einbezogen. Dieses Ereignis wird nicht ausgegeben, wenn Claude Code mit Amazon Bedrock, der Agent Platform von Google Cloud oder Microsoft Foundry ausgeführt wird oder wenn DISABLE_ERROR_REPORTING gesetzt ist.

Ereignisname: claude_code.internal_error

Attribute:

• Alle Standardattribute
• event.name: "internal_error"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• error_name: Name der Fehlerklasse, etwa "TypeError" oder "SyntaxError"
• error_code: Node.js-errno-Code wie "ENOENT", sofern am Fehler vorhanden

Plugin-installiert-Ereignis

Wird protokolliert, wenn die Installation eines Plugins abgeschlossen ist, sowohl über den CLI-Befehl claude plugin install als auch über die interaktive /plugin-Oberfläche.

Ereignisname: claude_code.plugin_installed

Attribute:

• Alle Standardattribute
• event.name: "plugin_installed"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• marketplace.is_official: "true", wenn der Marketplace ein offizieller Anthropic-Marketplace ist, andernfalls "false"
• install.trigger: "cli" oder "ui"
• plugin.name: Name des installierten Plugins. Bei Drittanbieter-Marketplaces nur enthalten, wenn OTEL_LOG_TOOL_DETAILS=1
• plugin.version: Plugin-Version, sofern im Marketplace-Eintrag deklariert. Bei Drittanbieter-Marketplaces nur enthalten, wenn OTEL_LOG_TOOL_DETAILS=1
• marketplace.name: Marketplace, aus dem das Plugin installiert wurde. Bei Drittanbieter-Marketplaces nur enthalten, wenn OTEL_LOG_TOOL_DETAILS=1

Plugin-geladen-Ereignis

Wird beim Sitzungsstart einmal pro aktiviertem Plugin protokolliert. Verwenden Sie dieses Ereignis, um zu inventarisieren, welche Plugins in Ihrer gesamten Flotte aktiv sind, als Ergänzung zu plugin_installed, das den Installationsvorgang selbst erfasst.

Ereignisname: claude_code.plugin_loaded

Attribute:

• Alle Standardattribute
• event.name: "plugin_loaded"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• plugin.name: Name des Plugins. Bei Plugins außerhalb des offiziellen Marketplace und des integrierten Pakets ist der Wert "third-party", sofern nicht OTEL_LOG_TOOL_DETAILS=1 gesetzt ist
• marketplace.name: Marketplace, aus dem das Plugin installiert wurde, sofern bekannt. Unter derselben Bedingung wie plugin.name zu "third-party" geschwärzt
• plugin.version: Version aus dem Plugin-Manifest. Nur enthalten, wenn der Name nicht geschwärzt ist und das Manifest eine Version deklariert
• plugin.scope: Herkunftskategorie des Plugins: "official", "community", "org", "user-local" oder "default-bundle"
• enabled_via: Wie das Plugin aktiviert wurde: "default-enable", "org-policy", "admin-install", "seed-mount" oder "user-install". Der Wert "admin-install" bedeutet, dass das Plugin für Ihre Organisation unter Organization settings > Plugins & skills als erforderlich oder zur automatischen Installation festgelegt ist. Vor v2.1.246 meldete Claude Code diese Plugins als "user-install" oder "seed-mount"
• plugin_id_hash: Deterministischer Hash aus Plugin-Name und Marketplace, der nur an Ihren konfigurierten Exporter gesendet wird. Damit können Sie die unterschiedlichen Drittanbieter-Plugins zählen, die in Ihrer Flotte geladen werden, ohne ihre Namen zu erfassen. Bei von claude.ai synchronisierten Plugins hasht Claude Code den Plugin-Namen mit dem Marketplace-Namen, den claude.ai für das Plugin meldet, andernfalls mit synced. Vor v2.1.246 verwendete Claude Code den von claude.ai gemeldeten Marketplace-Namen nicht im Hash
• has_hooks: Ob das Plugin Hooks beisteuert, über eine Hook-Konfiguration oder als Mod
• has_mcp: Ob das Plugin MCP-Server beisteuert
• host_owned_mcp: true, wenn der SDK-Host die MCP-Verbindungen dieses Plugins verwaltet und Claude Code das Lesen der MCP-Serverkonfiguration des Plugins übersprungen hat, andernfalls false
• skill_path_count: Anzahl der Skill-Verzeichnisse, die das Plugin deklariert
• command_path_count: Anzahl der Befehlsverzeichnisse, die das Plugin deklariert
• agent_path_count: Anzahl der Agentenverzeichnisse, die das Plugin deklariert
• safe_mode: "true", wenn die Sitzung mit --safe-mode gestartet wurde, andernfalls "false". Im abgesicherten Modus meldet dieses Ereignis nur das konfigurierte Inventar; die Befehle, Skills, Hooks und MCP-Server des Plugins werden nicht geladen. Erfordert Claude Code v2.1.169 oder höher

Skill-aktiviert-Ereignis

Wird protokolliert, wenn ein Skill aufgerufen wird, unabhängig davon, ob Claude ihn über das Skill-Tool aufruft oder Sie ihn als /-Befehl ausführen.

Ereignisname: claude_code.skill_activated

Attribute:

• Alle Standardattribute
• event.name: "skill_activated"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• skill.name: Name des Skills. Bei benutzerdefinierten Skills und Skills aus Drittanbieter-Plugins ist der Wert der Platzhalter "custom_skill", sofern nicht OTEL_LOG_TOOL_DETAILS=1 gesetzt ist
• invocation_trigger: Wie der Skill ausgelöst wurde ("user-slash", "claude-proactive" oder "nested-skill")
• skill.source: Woher der Skill geladen wurde (zum Beispiel "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind: "workflow", wenn der Skill ein Workflow-Skill ist. Andernfalls nicht vorhanden
• plugin.name (wenn OTEL_LOG_TOOL_DETAILS=1 oder das Plugin aus einem offiziellen Marketplace stammt): Name des zugehörigen Plugins, wenn der Skill von einem Plugin bereitgestellt wird
• marketplace.name (wenn OTEL_LOG_TOOL_DETAILS=1 oder das Plugin aus einem offiziellen Marketplace stammt): Marketplace, aus dem das zugehörige Plugin installiert wurde, wenn der Skill von einem Plugin bereitgestellt wird

@-Erwähnungsereignis

Wird protokolliert, wenn Claude Code eine @-Erwähnung in einem Prompt auflöst. Nicht jede Erwähnung gibt ein Ereignis aus: Pfade mit vorzeitigem Abbruch wie verweigerte Berechtigungen, übergroße Dateien, PDF-Referenzanhänge und fehlgeschlagene Verzeichnisauflistungen kehren zurück, ohne zu protokollieren.

Jedes Mal, wenn Claude Code einen Prompt liest, protokolliert es höchstens 100 Ereignisse mit dem mention_type "agent" und 100 mit "mcp_resource". Erwähnungen jenseits eines dieser Limits werden weiterhin aufgelöst, geben aber kein Ereignis aus.

Ereignisname: claude_code.at_mention

Attribute:

• Alle Standardattribute
• event.name: "at_mention"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• mention_type: Art der Erwähnung ("file", "directory", "agent", "mcp_resource", "peer"). Der Wert "peer" bedeutet, dass Sie eine Ihrer anderen Claude Code-Sitzungen erwähnt haben. Erfordert Claude Code v2.1.232 oder höher
• success: Ob die Erwähnung erfolgreich aufgelöst wurde ("true" oder "false")

Ereignis für ausgeschöpfte API-Wiederholungsversuche

Wird einmal protokolliert, wenn eine API-Anfrage nach mehr als einem Versuch fehlschlägt. Wird zusammen mit dem abschließenden api_error-Ereignis ausgegeben.

Ereignisname: claude_code.api_retries_exhausted

Attribute:

• Alle Standardattribute
• event.name: "api_retries_exhausted"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• model: Verwendetes Modell
• error: Abschließende Fehlermeldung
• status_code: HTTP-Statuscode als Zahl. Nicht vorhanden bei Nicht-HTTP-Fehlern.
• total_attempts: Gesamtzahl der unternommenen Versuche
• total_retry_duration_ms: Gesamte tatsächlich verstrichene Zeit über alle Versuche
• speed: "fast" oder "normal"

Hook-registriert-Ereignis

Wird beim Sitzungsstart einmal pro konfiguriertem Hook protokolliert. Verwenden Sie dieses Ereignis, um zu inventarisieren, welche Hooks in Ihrer gesamten Flotte aktiv sind, als Ergänzung zu den pro Ausführung ausgegebenen Ereignissen hook_execution_start und hook_execution_complete.

Ereignisname: claude_code.hook_registered

Attribute:

• Alle Standardattribute
• event.name: "hook_registered"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• hook_event: Typ des Hook-Ereignisses, etwa "PreToolUse" oder "PostToolUse"
• hook_type: Implementierungstyp des Hooks: "command", "prompt", "mcp_tool", "http" oder "agent"
• hook_source: Wo der Hook definiert ist: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings" oder "pluginHook"
• safe_mode: "true", wenn die Sitzung mit --safe-mode gestartet wurde, andernfalls "false". Erfordert Claude Code v2.1.169 oder höher
• hook_matcher (wenn OTEL_LOG_TOOL_DETAILS=1): Der Matcher-String aus der Hook-Konfiguration, sofern einer gesetzt ist
• plugin.name (wenn hook_source "pluginHook" ist): Name des beisteuernden Plugins. Bei Plugins außerhalb des offiziellen Marketplace und des integrierten Pakets ist der Wert "third-party", sofern nicht OTEL_LOG_TOOL_DETAILS=1 gesetzt ist
• plugin_id_hash (wenn hook_source "pluginHook" ist): Deterministischer Hash aus Plugin-Name und Marketplace, der nur an Ihren konfigurierten Exporter gesendet wird. Damit können Sie die unterschiedlichen beisteuernden Plugins zählen, ohne ihre Namen zu erfassen. Claude Code berechnet ihn wie beim Plugin-geladen-Ereignis beschrieben

Hook-Ausführungsstart-Ereignis

Wird protokolliert, wenn für ein Hook-Ereignis die Ausführung eines oder mehrerer Hooks beginnt.

Ereignisname: claude_code.hook_execution_start

Attribute:

• Alle Standardattribute
• event.name: "hook_execution_start"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zum Ordnen von Ereignissen, beschrieben unter Attribute zur Ereigniskorrelation
• hook_event: Typ des Hook-Ereignisses, etwa "PreToolUse" oder "PostToolUse"
• hook_name: Vollständiger Hook-Name einschließlich Matcher, etwa "PreToolUse:Write"
• num_hooks: Anzahl der passenden Hook-Befehle
• managed_only: "true", wenn nur Hooks aus verwalteten Richtlinien zulässig sind
• hook_source: "policySettings" oder "merged"
• safe_mode: "true", wenn die Sitzung mit --safe-mode gestartet wurde, andernfalls "false". Erfordert Claude Code v2.1.169 oder höher
• hook_definitions: JSON-serialisierte Hook-Konfiguration. Nur enthalten, wenn sowohl das detaillierte Beta-Tracing als auch OTEL_LOG_TOOL_DETAILS=1 aktiviert sind

Hook-Ausführung-abgeschlossen-Ereignis

Wird protokolliert, wenn alle Hooks für ein Hook-Ereignis abgeschlossen sind.

Ereignisname: claude_code.hook_execution_complete

Attribute:

• Alle Standardattribute
• event.name: "hook_execution_complete"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zur Sortierung von Ereignissen, beschrieben unter Ereigniskorrelationsattribute
• hook_event: Hook-Ereignistyp
• hook_name: Vollständiger Hook-Name einschließlich Matcher
• num_hooks: Anzahl der passenden Hook-Befehle
• num_success: Anzahl der erfolgreich abgeschlossenen Hooks
• num_blocking: Anzahl der Hooks, die eine blockierende Entscheidung zurückgegeben haben
• num_non_blocking_error: Anzahl der Hooks, die ohne Blockierung fehlgeschlagen sind
• num_cancelled: Anzahl der vor Abschluss abgebrochenen Hooks
• total_duration_ms: Tatsächliche Gesamtdauer (Wall-Clock) aller passenden Hooks
• stdout_chars: Gesamtzahl der Zeichen in stdout über alle passenden Hooks, die erfolgreich waren. Erfordert Claude Code v2.1.280 oder höher
• additional_context_chars: Gesamtzahl der Zeichen von additionalContext, die von den passenden Hooks zurückgegeben wurden. Erfordert Claude Code v2.1.280 oder höher
• system_message_chars: Gesamtzahl der Zeichen von systemMessage, die von den passenden Hooks zurückgegeben wurden. Erfordert Claude Code v2.1.280 oder höher
• initial_user_message_chars: Gesamtzahl der Zeichen von initialUserMessage, die von den passenden Hooks zurückgegeben wurden. Erfordert Claude Code v2.1.280 oder höher
• num_outputs_persisted: Anzahl der Hook-Ausgaben über der Obergrenze von 10.000 Zeichen, die Claude Code in einer Datei gespeichert hat. Erfordert Claude Code v2.1.280 oder höher
• managed_only: "true", wenn nur Hooks aus verwalteten Richtlinien zulässig sind
• hook_source: "policySettings" oder "merged"
• safe_mode: "true", wenn die Sitzung mit --safe-mode gestartet wurde, andernfalls "false". Erfordert Claude Code v2.1.169 oder höher
• hook_definitions: JSON-serialisierte Hook-Konfiguration. Nur enthalten, wenn sowohl detailliertes Beta-Tracing als auch OTEL_LOG_TOOL_DETAILS=1 aktiviert sind

Hook-Plugin-Metriken-Ereignis

Wird protokolliert, wenn ein Plugin-Hook aus einem offiziellen Marketplace Metriken pro Aufruf ausgibt. Nur Plugins, die aus einem offiziellen Anthropic-Marketplace installiert wurden, können diese ausgeben. Plugins aus Drittanbieter-Marketplaces und benutzerkonfigurierte Hooks geben dieses Ereignis nicht aus. Verwenden Sie dieses Ereignis, um das Plugin-Verhalten wie Trefferquoten, Kosten und Dauern mit Ihrem eigenen Observability-Stack zu überwachen.

Ereignisname: claude_code.hook_plugin_metrics

Attribute:

• Alle Standardattribute
• event.name: "hook_plugin_metrics"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zur Sortierung von Ereignissen, beschrieben unter Ereigniskorrelationsattribute
• plugin_id: Plugin-Kennung in der Form <name>@<marketplace>
• hook_event: Hook-Ereignistyp, der die Metriken ausgegeben hat
• Bis zu 20 vom Plugin ausgegebene Metrikschlüssel. Die Namen entsprechen ^[a-z][a-z0-9_]{0,39}$. Die Werte sind Boolesche Werte oder Zahlen.

Komprimierungsereignis

Wird protokolliert, wenn die Komprimierung der Konversation abgeschlossen ist.

Ereignisname: claude_code.compaction

Attribute:

• Alle Standardattribute
• event.name: "compaction"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zur Sortierung von Ereignissen, beschrieben unter Ereigniskorrelationsattribute
• trigger: "auto" oder "manual"
• success: "true" oder "false"
• duration_ms: Dauer der Komprimierung
• pre_tokens: Ungefähre Token-Anzahl vor der Komprimierung
• post_tokens: Ungefähre Token-Anzahl nach der Komprimierung
• error: Fehlermeldung, wenn die Komprimierung fehlgeschlagen ist
• precompute_reuse: Nur gesetzt, wenn trigger den Wert "manual" hat, oder wenn trigger bei einer Leerlauf-Komprimierung in einer interaktiven Terminal-Sitzung den Wert "auto" hat. Die automatische Komprimierung kann im Hintergrund eine Zusammenfassung vorbereiten, bevor sich das Kontextfenster füllt, und dieses Attribut hält fest, ob die Komprimierung diese vorbereitete Zusammenfassung wiederverwendet hat. "hit" bedeutet, dass sie wiederverwendet wurde; "miss_custom_instructions", "miss_hook" und "miss_not_ready" geben den Grund an, warum stattdessen eine neue Zusammenfassung berechnet wurde

Subagent-abgeschlossen-Ereignis

Wird protokolliert, wenn ein Subagent fertig ist und sein Ergebnis an die Konversation zurückgibt, die ihn gestartet hat. Verwenden Sie es, um Tool-Nutzung und Laufzeit nach Subagenten-Typ zusammenzufassen; für Token- oder Kostenauswertungen verwenden Sie den Token-Zähler und den Kostenzähler, gefiltert nach query_source "subagent", da total_tokens dieses Ereignisses nur die letzte Anfrage abdeckt. Die Kategorie "subagent" zählt auch Anfragen von agentenbasierten Hooks, die kein Subagent-Ereignis ausgeben.

Ereignisname: claude_code.subagent_completed

Attribute:

• Alle Standardattribute
• event.name: "subagent_completed"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zur Sortierung von Ereignissen, beschrieben unter Ereigniskorrelationsattribute
• agent_type: Der Subagenten-Typ. Namen integrierter Agenten und Agenten aus Plugins offizieller Marketplaces erscheinen unverändert; andere Agentennamen werden durch "custom" ersetzt, sofern OTEL_LOG_TOOL_DETAILS=1 nicht gesetzt ist
• agent.source: Herkunft der Agentendefinition: built-in, plugin oder die Einstellungsquelle, die einen benutzerdefinierten Agenten definiert hat, etwa userSettings oder projectSettings
• is_built_in: Ob der Subagent ein integrierter Agententyp ist
• is_async: Ob der Subagent im Hintergrund ausgeführt wurde
• total_tokens: Der Token-Umfang der letzten API-Anfrage des Subagenten: Eingabe-, Cache-Erstellungs-, Cache-Lese- und Ausgabe-Token dieser einen Anfrage, ungefähr die Kontextgröße des Subagenten bei Abschluss. Keine Summe über den gesamten Lauf
• total_tool_uses: Anzahl der Tool-Aufrufe, die der Subagent während des gesamten Laufs durchgeführt hat
• duration_ms: Laufzeit in Millisekunden
• model: Das Modell, mit dem der Subagent ausgeführt werden sollte
• final_model: Das Modell, das die abschließende Antwort des Subagenten erzeugt hat; es unterscheidet sich von model nach einem Wechsel während des Laufs, etwa einem Fallback
• model_swapped: Ob mehr als ein Modell die Anfragen des Subagenten bedient hat
• plugin_id_hash, plugin.name: Vorhanden bei Agenten, die von Plugins bereitgestellt werden. Plugin-Namen aus offiziellen Marketplaces erscheinen unverändert; andere Plugin-Namen werden durch "third-party" ersetzt, sofern OTEL_LOG_TOOL_DETAILS=1 nicht gesetzt ist

Feedback-Umfrage-Ereignis

Wird protokolliert, wenn eine Umfrage zur Sitzungsqualität angezeigt oder beantwortet wird. Unter Umfragen zur Sitzungsqualität erfahren Sie, welche Daten die Umfragen erfassen und wie Sie sie steuern.

Ereignisname: claude_code.feedback_survey

Attribute:

• Alle Standardattribute
• event.name: "feedback_survey"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zur Sortierung von Ereignissen, beschrieben unter Ereigniskorrelationsattribute
• event_type: Lebenszyklusereignis der Umfrage, zum Beispiel "appeared", "responded" oder "transcript_prompt_appeared"
• appearance_id: Eindeutige ID, die die für eine Umfrageinstanz ausgegebenen Ereignisse verknüpft
• survey_type: Welche Umfrage das Ereignis erzeugt hat. "session" ist die Bewertungsabfrage „How is Claude doing?“
• response: Die Auswahl des Benutzers bei responded-Ereignissen
• enabled_via_override: true, wenn CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL gesetzt ist. Wird als Boolescher Wert ausgegeben, nicht als Zeichenkette. Vorhanden bei session-Umfrageereignissen. Filtern Sie nach diesem Attribut, um zu bestätigen, dass die Überschreibung auf allen Geräten angewendet wird

Aufbewahrungsbereinigungs-Ereignis

Wird einmal pro Lauf der Aufbewahrungsbereinigung protokolliert, die Sitzungstranskripte und andere Anwendungsdaten löscht, die älter sind als in der Einstellung cleanupPeriodDays festgelegt. Claude Code führt die Bereinigung im Hintergrund höchstens einmal pro Sitzung aus, und auch ein Lauf, der nichts löscht, gibt das Ereignis aus. Wenn Claude Code die Bereinigung in den letzten 24 Stunden in einer beliebigen Sitzung auf demselben Rechner ausgeführt hat, verzögert es die Bereinigung dieser Sitzung um mindestens 10 Minuten, sodass eine Sitzung, die früher beendet wird, nichts ausgibt. Wenn Sie claude -p mit --bare ausführen, führt Claude Code die Bereinigung nicht aus und gibt nichts aus.

Wie jedes OTel-Ereignis auf dieser Seite wird es nur an das von Ihnen konfigurierte Telemetrie-Backend gesendet. Erfordert Claude Code v2.1.227 oder höher.

Wenn Claude Code den Aufbewahrungszeitraum nicht sicher bestimmen kann, pausiert es die Bereinigung und gibt das Ereignis mit result auf "skipped" und einem skip_reason aus. Wenn verwaltete Einstellungen cleanupPeriodDays festlegen, legt der verwaltete Wert den Aufbewahrungszeitraum fest, und die Bereinigung läuft auch dann, wenn eine Einstellungsdatei in einem Geltungsbereich mit niedrigerer Priorität beschädigt oder ungültig ist. Wenn managed-settings.json selbst nicht gelesen werden kann, pausiert Claude Code die Bereinigung trotzdem, es sei denn, die verwaltete Ebene liefert cleanupPeriodDays aus einer anderen Quelle, etwa aus serververwalteten Einstellungen oder einem managed-settings.d/-Drop-in neben der beschädigten Datei. Die Attribute der Löschzähler sind nur vorhanden, wenn result den Wert "complete" hat.

Ereignisname: claude_code.retention_sweep

Attribute:

• Alle Standardattribute
• event.name: "retention_sweep"
• event.timestamp: ISO-8601-Zeitstempel
• event.sequence: prozessbezogener Zähler zur Sortierung von Ereignissen, beschrieben unter Ereigniskorrelationsattribute
• result: "complete", wenn die Bereinigung ausgeführt wurde, "skipped", wenn Claude Code sie pausiert hat
• period_days: Der Wert von cleanupPeriodDays aus den zusammengeführten Einstellungen in Tagen, oder 30, wenn keine Quelle ihn festlegt. Bei übersprungenen Ereignissen der Wert, den die Bereinigung verwendet hätte, berechnet aus den Einstellungsquellen, die Claude Code lesen konnte
• used_default: "true", wenn keine lesbare Einstellungsquelle cleanupPeriodDays festlegt, andernfalls "false". Bei abgeschlossenen Ereignissen bedeutet "true", dass der Standardwert von 30 Tagen angewendet wurde
• skip_reason: Warum Claude Code die Bereinigung ausgesetzt hat. Nur vorhanden, wenn result den Wert "skipped" hat:
  • "user_source_disabled": Benutzereinstellungen sind ausgeschlossen, zum Beispiel durch das Flag --setting-sources oder die SDK-Option settingSources, und keine aktivierte Quelle stellt cleanupPeriodDays bereit
  • "settings_unknowable": Eine Einstellungsdatei konnte nicht gelesen oder geparst werden, sodass cleanupPeriodDays oder desktopSessionCleanupPeriodDays möglicherweise auf einen Wert gesetzt ist, den Claude Code nicht sehen kann
  • "settings_invalid_key_set": Die Einstellungen enthalten Validierungsfehler, und cleanupPeriodDays oder desktopSessionCleanupPeriodDays ist explizit gesetzt, sodass ein Rückgriff auf den Standardwert Dateien entgegen dieser Einstellung löschen oder behalten könnte
  • "remote_settings_unknowable": Eine Sitzung im Code-Tab von Claude Desktop in einer Drittanbieter-Bereitstellung hat serververwaltete Einstellungen angefordert. Sie hat keine verwendbare Antwort erhalten, sodass cleanupPeriodDays möglicherweise auf einen Wert gesetzt ist, den Claude Code nicht sehen kann
• transcripts_deleted: Anzahl der Sitzungstranskripte, also der Dateien ~/.claude/projects/*/*.jsonl auf oberster Ebene, die die Bereinigung gelöscht hat
• transcripts_exempted_desktop: Anzahl der Transkripte jenseits des Aufbewahrungszeitraums, die die Bereinigung gemäß der Regel für Claude Desktop und Cowork behalten hat. Diese zählen nicht zu files_past_cutoff. Erfordert Claude Code v2.1.248 oder höher
• session_files_deleted: Anzahl der Artefakte, die die Bereinigung der Sitzungsdateien gelöscht hat: Transkripte sowie sitzungsbezogene Begleitdateien wie Sidecars, Aufzeichnungen und Tool-Ergebnisse
• artifacts_deleted: Gesamtzahl der Elemente, die die Bereinigung in den abgedeckten Datenverzeichnissen gelöscht hat, einschließlich der Sitzungsdateien. Einige Bereinigungen zählen einen vollständig entfernten Verzeichnisbaum als ein Element, und einige Bereinigungsdurchläufe tragen nicht zum Zähler bei; betrachten Sie den Wert daher als Untergrenze und nicht als exakte Dateianzahl
• files_retained_fresh: Dateien, die geprüft und beibehalten wurden, weil sie noch innerhalb des Aufbewahrungszeitraums liegen. Nur dateibasierte Bereinigungen zählen diese, daher ist der Wert eine Untergrenze; ein Wert ungleich null ist der normale Dauerzustand
• files_past_cutoff: Dateien, die älter als der Aufbewahrungszeitraum sind und die die Bereinigung nicht löschen konnte, zum Beispiel wegen eines Berechtigungsfehlers oder einer geöffneten Datei. Die Anzahl umfasst auch jeden veralteten Ordner, den die Bereinigung unter skills/synced/ oder plugins/synced/ findet, unabhängig davon, ob sie den Ordner in den Papierkorb verschiebt. Abgesehen von diesen Ordnern bedeutet ein Wert über null, dass Dateien den konfigurierten Aufbewahrungszeitraum überdauert haben; null ist jedoch kein Beweis dafür, dass dies bei keiner Datei der Fall war, da ein fehlgeschlagenes Entfernen eines ganzen Verzeichnisses stattdessen zu error_count zählt
• error_count: Anzahl der Fehler, die bei der Bereinigung beim Auflisten oder Löschen von Dateien aufgetreten sind

Ereignis „Verwaltete Einstellungen aufgelöst“

Wird mit den verwalteten Einstellungen protokolliert, die eine Sitzung aufgelöst hat: einmal beim Sitzungsstart, erneut, wenn sich während der Sitzung entweder die verwalteten Einstellungen oder der Zustand des Richtlinien-Helpers ändern, und wenn Claude Code aus einem der im Attribut error.type aufgeführten Gründe den Start verweigert oder die Sitzung beendet. Verwenden Sie dieses Ereignis, um Rechner zu finden, die mit einer unerwarteten verwalteten Quelle laufen, Rechner, deren Richtlinien-Helper fehlschlägt, sowie den Grund, warum ein Rechner den Start verweigert hat. Erfordert Claude Code v2.1.274 oder höher.

Standardmäßig enthält das Ereignis die verwalteten Quellen und den Zustand des Richtlinien-Helpers, aber nicht die Einstellungen selbst. Um das geschwärzte Attribut managed_settings.settings und den Digest managed_settings.resolved_sha256 hinzuzufügen, setzen Sie OTEL_LOG_MANAGED_SETTINGS=1:

• Setzen Sie es im env-Block der verwalteten Einstellungen, der Benutzereinstellungen oder von --settings oder in der Umgebung, mit der Sie Claude Code starten. Ein Wert in Projekt- oder lokalen Einstellungen aktiviert es nicht, da ein geklontes Repository diese schreiben kann.
• Serververwaltete Einstellungen können es setzen, ohne den Sicherheitsgenehmigungsdialog anzuzeigen, da die Variable lediglich die eigene geschwärzte Richtlinie Ihrer Organisation zu einem Ereignis hinzufügt, das Ihre Organisation bereits empfängt.

In einer interaktiven Sitzung in einem Ordner, dem Sie nicht vertraut haben, exportiert Claude Code das Verweigerungsereignis nicht.

Ereignisname: claude_code.managed_settings_resolved

Attribute:

• Alle Standardattribute

• event.name: "managed_settings_resolved"

• event.timestamp: ISO-8601-Zeitstempel

• event.sequence: prozessbezogener Zähler zur Sortierung von Ereignissen, beschrieben unter Ereigniskorrelationsattribute

• managed_settings.trigger: "startup" für das Ereignis beim Sitzungsstart, "change", wenn sich die verwalteten Einstellungen oder der Zustand des Richtlinien-Helpers später in der Sitzung geändert haben, oder "refused", wenn eine Richtlinie der verwalteten Einstellungen die Sitzung gestoppt hat. Claude Code sendet ein change-Ereignis nur, wenn sich ein Attribut vom zuletzt gesendeten Ereignis unterscheidet, und ein geänderter Einstellungswert zählt auch dann, wenn OTEL_LOG_MANAGED_SETTINGS deaktiviert ist

• error.type: Warum Claude Code die Sitzung gestoppt hat. Nur bei refused-Ereignissen vorhanden:

  • "helper_failed": Ein Lauf des Richtlinien-Helpers ist fehlgeschlagen
  • "policy_invalid": Die verwalteten Einstellungen enthalten einen Fehler, der den Start von Claude Code verhindert, oder eine Admin-Quelle konnte aus einem anderen Grund als einem verweigerten Lesezugriff nicht geladen werden, sodass Claude Code die Organisationsanmeldung oder die Anbieterdurchsetzung nicht prüfen kann
  • "provider_not_allowed": Die Sitzung würde einen API-Anbieter verwenden oder den Datenverkehr eines Anbieters an einen Host senden, den die verwaltete Liste allowedProviders nicht zulässt. Erfordert Claude Code v2.1.285 oder höher
  • "consent_rejected": Der Benutzer hat den Sicherheitsgenehmigungsdialog für serververwaltete Einstellungen abgelehnt
  • "force_refresh_failed": Der Abruf der Einstellungen, den forceRemoteSettingsRefresh erfordert, ist fehlgeschlagen
  • "gateway_rejected": Ein Claude-Apps-Gateway hat das Laden der verwalteten Einstellungen mit HTTP 403 beantwortet
  • "version_below_minimum": Diese Version von Claude Code liegt unter requiredMinimumVersion oder über requiredMaximumVersion
  • "_OTHER": Das Laden der verwalteten Einstellungen über das Claude-Apps-Gateway ist aus einem anderen Grund fehlgeschlagen

• managed_settings.sources: Jede verwaltete Quelle, die mindestens einen Richtlinienschlüssel liefert, mit der höchsten Priorität zuerst, einschließlich Quellen, deren Schlüssel unter first-wins nicht wirksam werden. Die Werte sind "remote", "plist" oder "hklm" für die MDM- oder Betriebssystemrichtlinie, "file" für verwaltete Einstellungsdateien und Drop-ins, "parent", wenn ein einbettender Host Einstellungen liefert, und "hkcu" für den Windows-HKCU-Registrierungswert, wenn Claude Code ihn liest. Eine Quelle, die nur Steuerungsschlüssel enthält oder die Claude Code nicht lesen konnte, wird nicht aufgeführt. Wird als Array von Zeichenketten ausgegeben, leer, wenn keine verwaltete Quelle einen Richtlinienschlüssel liefert

• managed_settings.source_behavior: Der von Claude Code gelesene Wert von managedSourcesBehavior, "first-wins" oder "merge". "first-wins", wenn keine Quelle den Schlüssel festlegt

• managed_settings.helper.state: Zustand des Richtlinien-Helpers, den die ausgewählte MDM- oder Dateiquelle konfiguriert:

  • "ok": Die Ausgabe des Helpers dient als verwaltete Einstellungen
  • "bad_path", "not_a_file", "exit_nonzero", "timed_out", "oversize", "parse_failed", "envelope_invalid" oder "schema_rejected": Der letzte Lauf des Helpers ist fehlgeschlagen. Unter Helper-Fehler werden die Fälle beschrieben
  • "none": Es ist kein Helper konfiguriert, oder die Quelle, die ihn konfiguriert, ist keine MDM-Richtlinie oder verwaltete Einstellungsdatei

• managed_settings.helper.applied: "output", solange die eigene Ausgabe des Helpers als verwaltete Einstellungen dient, "none", wenn dies nicht der Fall ist

• managed_settings.helper.entry: "policyHelper", wenn Claude Code einen policyHelper ausgewählt hat. Fehlt, wenn kein Helper ausgewählt wurde

• managed_settings.helper.path: Der konfigurierte path des Helpers. Vorhanden, wann immer Claude Code einen Helper ausgewählt hat, unabhängig davon, ob OTEL_LOG_MANAGED_SETTINGS gesetzt ist

• managed_settings.resolved_sha256 (wenn OTEL_LOG_MANAGED_SETTINGS=1): SHA-256 der aufgelösten verwalteten Einstellungen vor der Schwärzung, serialisiert als JSON mit rekursiv sortierten Schlüsseln und ohne Leerzeichen. Rechner mit demselben Digest verwenden dieselbe Richtlinie. Claude Code sendet den Digest nur bei ausdrücklicher Aktivierung, da eine kurze Richtlinie durch das Hashen von Vermutungen rekonstruiert werden kann. Fehlt, wenn keine verwalteten Einstellungen aufgelöst wurden, sowie bei refused-Ereignissen

• managed_settings.settings (wenn OTEL_LOG_MANAGED_SETTINGS=1): Die Namen und die Struktur der aufgelösten verwalteten Einstellungen als JSON-Zeichenkette, mit geschwärzten Werten. Fehlt bei refused-Ereignissen. Claude Code erstellt es aus seinem Einstellungsschema:

  • Ein Einstellungsname, den das Schema deklariert, wird exportiert, und ein Schlüssel, den es nicht deklariert, wird weggelassen
  • Boolesche Werte, Zahlen und Zeichenkettenwerte, die das Schema auf eine feste Menge von Optionen beschränkt, etwa permissions.defaultMode, werden unverändert exportiert. sandbox.network.httpProxyPort und sandbox.network.socksProxyPort werden als "[REDACTED]" exportiert
  • Jede andere Zeichenkette, etwa model, apiKeyHelper, jeder env-Wert, jede URL und jeder Befehl, wird als "[REDACTED]" exportiert
  • Die Eintragsnamen von Maps, etwa env-Variablennamen und Plugin-IDs, werden unverändert exportiert. Eine Einstellung, deren Einträge das Schema nicht typisiert, etwa vimInsertModeRemaps, wird als einzelnes "[REDACTED]" exportiert, und sandbox.ignoreViolations wird als Liste seiner Pfadlisten ohne die Befehlsmuster exportiert
  • Eine Liste behält ihre Länge, wobei jeder Eintrag nach denselben Regeln geschwärzt wird
  • Eine permissions.allow-, permissions.deny- oder permissions.ask-Regel wird als ihr Tool-Name mit geschwärztem Inhalt exportiert, etwa Read([REDACTED]), wenn das Tool in diese Version von Claude Code integriert ist oder eine mcp__-Referenz wie mcp__jira__create_issue ist. Jede andere Regel wird als "[REDACTED]" exportiert
  • Hooks folgen denselben Regeln, sodass Felder mit festen Optionen und numerische Felder wie type und timeout angezeigt werden, während jeder Befehl, jede URL, jeder matcher und jede if-Bedingung als "[REDACTED]" exportiert wird

  Beispielsweise werden verwaltete Einstellungen mit apiKeyHelper, zwei env-Variablen und einer Deny-Regel als {"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}} exportiert.

  Claude Code kürzt den Wert bei 8 KB UTF-8, und der gekürzte Wert ist kein gültiges JSON

• managed_settings.settings_truncated (wenn managed_settings.settings vorhanden ist): true, wenn Claude Code managed_settings.settings bei 8 KB gekürzt hat, andernfalls false. Wird als Boolescher Wert ausgegeben, nicht als Zeichenkette

Interpretation von Metriken- und Ereignisdaten

Die exportierten Metriken und Ereignisse unterstützen eine Reihe von Analysen:

Nutzungsüberwachung

Um aktive Benutzer über Oberflächen hinweg zu vergleichen, setzen Sie OTEL_METRICS_INCLUDE_ENTRYPOINT=true, um app.entrypoint zu Metriken und Ereignissen hinzuzufügen. Zählen Sie dann die eindeutigen user.account_uuid-Werte pro Entrypoint bei claude_code.user_prompt-Ereignissen oder bei claude_code.token.usage, wenn Sie nur Metriken exportieren. Verwenden Sie beispielsweise cli für interaktive CLI-Sitzungen und gruppieren Sie claude-desktop, claude-desktop-3p und remote_desktop für den Code-Tab von Claude Desktop.

user.account_uuid identifiziert in Claude-Tag-Channel-Sitzungen keine Personen und fehlt in Sitzungen ohne Claude-Konto: siehe Aktionen Benutzern zuordnen. Wenn eine Person viele Sitzungen startet oder eine Sitzung keinen Prompt erhält, steigt claude_code.session.count, ohne dass ein aktiver Benutzer hinzukommt.

Kostenüberwachung

Die Metrik claude_code.cost.usage hilft bei:

• Verfolgung von Nutzungstrends über Teams oder Einzelpersonen hinweg
• Identifikation von Sitzungen mit hoher Nutzung zur Optimierung
• Zuordnung von Ausgaben zu spezifischen Skills, Plugins oder Subagent-Typen über die Attribute skill.name, plugin.name und agent.name

[!NOTE]

Kostenmetriken sind Näherungswerte. Offizielle Abrechnungsdaten finden Sie unter Kosten für Ihre Organisation verwalten.

Claude Code zählt jede Streaming-Antwort genau einmal zu den Kosten- und Token-Metriken, auch wenn ein Gateway oder Proxy hinter ANTHROPIC_BASE_URL die Nutzung progressiv über mehrere Frames hinweg streamt.

Warnungen und Segmentierung

Häufige Warnungen, die Sie in Betracht ziehen sollten:

• Kostensteigerungen
• Ungewöhnlicher Token-Verbrauch
• Hohes Sitzungsvolumen von bestimmten Benutzern

Alle Metriken können nach den Standard-Attributen segmentiert werden. Das Attribut model ist auf claude_code.token.usage, claude_code.cost.usage und claude_code.lines_of_code.count verfügbar.

Aufschlüsselungen pro Modell von Commits können nur durch Verknüpfung mit den Token- oder Kostenmetriken auf session.id angenähert werden, da eine Sitzung mehrere Modelle umfassen kann. Filtern Sie die Token- oder Kostenseite auf Zeilen, bei denen query_source "main" ist, damit Hilfs- und Subagent-Anfragen die Commits der Sitzung nicht einem Modell zuordnen, das sie nicht erstellt hat.

Wiederholungserschöpfung erkennen

Claude Code wiederholt fehlgeschlagene API-Anfragen intern und gibt nur nach dem Aufgeben ein einzelnes claude_code.api_error Ereignis aus, daher ist das Ereignis selbst das Endsignal für diese Anfrage. Zwischenzeitliche Wiederholungsversuche werden nicht als separate Ereignisse protokolliert.

Das Attribut attempt auf dem Ereignis zeichnet die Anzahl der Versuche auf. CLAUDE_CODE_MAX_RETRIES hat einen Standardwert von 10 und ist auf 15 begrenzt; wenn CLAUDE_CODE_RETRY_WATCHDOG gesetzt ist, ist der Standardwert höher und es gibt keine Obergrenze.

Wenn die Anfrage alle Wiederholungsversuche bei einem vorübergehenden Fehler erschöpft, ist attempt höchstens um eins höher als dieses effektive Limit: standardmäßig 11.

Auch ein niedrigerer Wert kann bedeuten, dass die Wiederholungsversuche aufgebraucht wurden: attempt beginnt jedes Mal wieder bei 1, wenn Claude Code die Anfrage nach einem Streaming-Fehler erneut sendet.

Um eine Sitzung zu unterscheiden, die sich von einer, die steckengeblieben ist, erholt hat, gruppieren Sie Ereignisse nach session.id und prüfen Sie, ob ein späteres api_request Ereignis nach dem Fehler vorhanden ist.

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

Eingabe-Token den OpenTelemetry-GenAI-Semantikkonventionen zuordnen

Claude Code exportiert Eingabe-Token-Zahlen so, wie sie im Usage-Block der API-Antwort erscheinen, daher schließen diese Werte Token aus, die aus dem Prompt-Cache gelesen oder in ihn geschrieben werden:

• input_tokens auf dem Span claude_code.llm_request und dem Ereignis api_request
• Der Typ "input" der Metrik claude_code.token.usage

Claude Code setzt keine gen_ai.usage.*-Attribute. Laut den OpenTelemetry-GenAI-Semantikkonventionen sollte gen_ai.usage.input_tokens Token einschließen, die aus dem Cache gelesen und in ihn geschrieben werden. So berechnen Sie diese Summe:

• Aus dem Span oder Ereignis: Addieren Sie input_tokens, cache_read_tokens und cache_creation_tokens
• Aus der Metrik claude_code.token.usage: Addieren Sie deren Typen "input", "cacheRead" und "cacheCreation"

Die Konventionen definieren außerdem separate Attribute für Cache-Lesevorgänge und Cache-Schreibvorgänge:

• cache_read_tokens entspricht gen_ai.usage.cache_read.input_tokens
• cache_creation_tokens entspricht gen_ai.usage.cache_write.input_tokens. Ältere Versionen der Konventionen benennen das Cache-Schreibattribut gen_ai.usage.cache_creation.input_tokens, verwenden Sie daher den Namen, den Ihr Backend erwartet.

Audit-Sicherheitsereignisse

OpenTelemetry-Ereignisse sind die Audit-Datenquelle für Claude Code-Aktivität. Jedes Ereignis trägt Identitätsattribute, die Tool-Aufrufe, MCP-Aktivität und Berechtigungsentscheidungen an den Benutzer zurückbinden, der sie ausgelöst hat. Der OTLP-Logs-Exporter kann diese Ereignisse an jede Security Information and Event Management (SIEM)-Plattform mit einem OTLP-Receiver oder an einen OpenTelemetry Collector liefern, der an Ihr SIEM weiterleitet.

Attribut-Aktionen an Benutzer

Die Standardattribute auf jedem Ereignis enthalten die Identität des authentifizierten Benutzers: user.email, user.account_uuid, user.account_id und organization.id, wenn mit einem Claude-Konto angemeldet oder in einer Cloud-Sitzung, wenn die Anmeldedaten der Sitzung selbst diese tragen, plus user.id und die pro-Sitzung session.id. user.id ist ein installationsbegrenzter Bezeichner, außer in Sitzungen mit einem Claude apps gateway über /login, wo es das IdP-Subjekt aus dem vom Gateway ausgegebenen Token ist.

In einer Sitzung, die ein Entwickler startet, werden MCP-Tool-Aufrufe, Bash-Befehle und Dateibearbeitungen daher diesem Entwickler zugeordnet. Claude Code handelt nicht unter einem separaten Service-Konto; die Identität, die auf jedem Ereignis aufgezeichnet wird, ist das Claude-Konto des Entwicklers selbst, oder die IdP-Identität des Entwicklers bei einer Claude apps gateway-Sitzung. In Claude Tag-Kanalsitzungen arbeitet Claude stattdessen als gemeinsame Identität Ihrer Organisation.

Wenn Claude Code sich mit einem direkten API-Schlüssel authentifiziert oder gegen Amazon Bedrock, Google Cloud's Agent Platform oder Microsoft Foundry, gibt es kein Claude-Konto in der Sitzung und nur user.id und session.id werden gefüllt. In diesen Bereitstellungen fügen Sie die Benutzeridentität selbst mit OTEL_RESOURCE_ATTRIBUTES hinzu, die pro Benutzer über die verwaltete Einstellungsdatei oder einen Launch-Wrapper gesetzt wird. Claude apps gateway-Sitzungen benötigen nichts davon: siehe Standardattribute für die Identität, die ihre Exporte tragen.

export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

Audit MCP-Aktivität

Um MCP-Server-Aktivität mit vollständiger Call-Detail zu erfassen, aktivieren Sie den Logs-Exporter und setzen Sie OTEL_LOG_TOOL_DETAILS=1. Jede MCP-Operation erzeugt dann strukturierte Ereignisse, die den Server-Namen, Tool-Namen und Call-Argumente zusammen mit den Standard-Identitätsattributen tragen:

Ohne OTEL_LOG_TOOL_DETAILS lassen diese Ereignisse die identifizierende Detail fallen:

• tool_result: behält mcp_server_scope und einen tool_name, der für benutzerkonfigurierte Server auf das Literal "mcp_tool" redigiert ist, lässt Argument-Inhalte weg. Für Claude Desktop's integrierte Server, in Sitzungen, die Claude Desktop besitzt, behält es auch das mcp_server_name/mcp_tool_name-Paar innerhalb von tool_parameters, die gleiche von Host verfasste Ausnahme wie tool_decision
• tool_decision: behält tool_source und einen tool_name, der für benutzerkonfigurierte Server auf das Literal "mcp_tool" redigiert ist, lässt Argument-Inhalte weg. Für Claude Desktop's integrierte Server, in Sitzungen, die Claude Desktop besitzt, behält es auch das mcp_server_name/mcp_tool_name-Paar innerhalb von tool_parameters
• mcp_server_connection: lässt server_name und die Fehlermeldung weg, behält aber is_plugin, plugin_id_hash und plugin.name, wobei Namen von Nicht-Anthropic-Plugins auf das Literal "third-party" redigiert werden, sodass von Plugins bereitgestellte Server ohne detaillierte Protokollierung unterscheidbar bleiben

Sicherheitsfragen zu Ereignissen zuordnen

Beim Erstellen von Erkennungsregeln schlagen Sie das Signal auf, das Sie überwachen möchten, und fragen Sie Ihr Backend nach dem entsprechenden Ereignis und den Attributen ab:

Claude Code gibt nur den rohen Ereignisstrom aus. Anomalieerkennung, Baselining, Korrelation über Sitzungen hinweg und Warnungen sind die Verantwortung Ihres SIEM oder Observability-Backends.

Ausgangspfade verwalteten Kontrollen und Ereignissen zuordnen

Die Tabelle ordnet Pfade, über die Sitzungsinhalte einen Computer verlassen können, sowie die lokale Aufbewahrung den Schlüsseln der verwalteten Einstellungen zu, die sie einschränken, und den Ereignissen, die sie aufzeichnen. Was Claude Code selbst an Anthropic sendet, etwa /feedback-Berichte, finden Sie unter Datennutzung. Die Namen verlinken auf ihre Referenzeinträge, die Werte und Standardwerte angeben.

Die Einträge zu allowedHttpHookUrls, managed-mcp.json und den Hook-Ereignissen erfordern mehr, als die Tabelle zeigt:

• allowedHttpHookUrls: Einträge werden über Einstellungsdateien hinweg zusammengeführt, sodass ein Entwickler einer leeren verwalteten Liste Einträge hinzufügen kann. allowManagedHooksOnly entscheidet, welche Hooks ausgeführt werden
• managed-mcp.json: Um MCP auszuschalten, siehe MCP vollständig deaktivieren. Um zu bestätigen, dass Claude Code die Datei liest, siehe Konfiguration validieren
• Hook-Ereignisse: Claude Code protokolliert hook_execution_start und hook_execution_complete einmal pro Hook-Ereignis und deckt dabei jeden passenden Hook ab. OTEL_LOG_TOOL_DETAILS=1 allein zeichnet die URL eines HTTP-Hooks nicht auf. Die Hook-Konfiguration erscheint nur in hook_definitions, wofür zusätzlich detailliertes Beta-Tracing erforderlich ist

OTEL_LOG_TOOL_DETAILS=1 fügt diesen Ereignissen Befehlszeichenfolgen, Server- und Tool-Namen sowie Tool-Eingaben hinzu. Diese Details können dieselben sensiblen Inhalte wie die Sitzung selbst enthalten. Aktivieren Sie die Option daher nur, wenn Ihr Collector für die Speicherung dieser Inhalte freigegeben ist.

Den Aufbewahrungsdurchlauf überprüfen

Um allen Computern denselben Aufbewahrungszeitraum vorzugeben, setzen Sie cleanupPeriodDays in den verwalteten Einstellungen. Um zu überprüfen, ob die Computer den Durchlauf mit diesem Wert ausführen, erfassen Sie das Ereignis retention_sweep. period_days und die Zähler sind Zeichenfolgen. Wandeln Sie sie daher in Zahlen um, bevor Sie sie vergleichen.

Ein Computer, der wie vorgesehen funktioniert, kann beispielsweise aus folgenden Gründen kein Ereignis senden:

• Niemand startet Claude Code: Es wird kein Durchlauf ausgeführt, und der Computer behält seine Daten bis zum nächsten Start
• Eine Sitzung bleibt geöffnet: Claude Code führt den Durchlauf höchstens einmal pro Sitzung aus
• Eine Sitzung endet vorzeitig: Ein Durchlauf, der beim Beenden der Sitzung noch nicht abgeschlossen ist, gibt nichts aus, ebenso wenig einer, der aufgrund eines unerwarteten Fehlers abbricht

Der Durchlauf deckt nicht jeden Pfad ab. Aufbewahrt, bis Sie sie löschen listet auf, was erhalten bleibt, und Lokale Daten löschen zeigt, wie Sie es entfernen.

Ereignisse an ein SIEM senden

Zeigen Sie OTEL_EXPORTER_OTLP_LOGS_ENDPOINT auf den OTLP-Receiver Ihres SIEM oder auf einen OpenTelemetry Collector, der an die native Ingest-API Ihres SIEM weiterleitet. Das folgende verwaltete Einstellungsbeispiel exportiert nur Ereignisse, mit vollständiger Tool-Detail-Aktivierung für MCP- und Bash-Auditing:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

Um zu bestätigen, dass Ereignisse ankommen, senden Sie eine Eingabeaufforderung in einer Sitzung, die unter dieser Konfiguration ausgeführt wird, und überprüfen Sie Ihr SIEM auf das claude_code.user_prompt-Ereignis. Wenn nichts ankommt, starten Sie Claude Code mit claude --debug-file <path> und überprüfen Sie dieses Protokoll auf [3P telemetry]-Exportfehler.

Backend-Überlegungen

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

Backends für Metriken

• Zeitreihendatenbanken: Ratenberechnungen, aggregierte Metriken
• Spaltenorientierte Speicher: Komplexe Abfragen, eindeutige Benutzeranalyse
• Vollständige Observability-Plattformen: Erweiterte Abfragen, Visualisierung, Warnungen

Backends für Ereignisse und Logs

• Log-Aggregationssysteme: Volltextsuche, Log-Analyse
• Spaltenorientierte Speicher: Strukturierte Ereignisanalyse
• Vollständige Observability-Plattformen: Korrelation zwischen Metriken und Ereignissen

Backends für Traces

Wählen Sie ein Backend, das verteilte Trace-Speicherung und Span-Korrelation unterstützt:

• Verteilte Tracing-Systeme: Span-Visualisierung, Request-Waterfalls, Latenzanalyse
• Vollständige Observability-Plattformen: Trace-Suche und Korrelation mit Metriken und Logs

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 für Terminal-Sitzungen, claude-code-desktop für lokale Sitzungen, die über die Registerkarte „Code“ in der Claude Desktop-App gestartet werden
• service.version: Aktuelle Claude Code-Version oder die Desktop-App-Version für lokale Sitzungen in der Code-Registerkarte
• os.type: Betriebssystemtyp (zum Beispiel linux, darwin, windows)
• os.version: Betriebssystem-Versionsnummer
• host.arch: Host-Architektur (zum Beispiel amd64, arm64)
• wsl.version: WSL-Versionsnummer (nur vorhanden, wenn auf Windows Subsystem for Linux ausgeführt)
• Meter-Name: com.anthropic.claude_code

Wenn Ihre Collector-Pipelines oder Dashboards nach service.name = claude-code filtern, fügen Sie claude-code-desktop zum Filter hinzu, um auch Telemetrie von lokalen Sitzungen in der Code-Registerkarte zu erfassen.

ROI-Messung-Ressourcen

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 einsatzbereite Docker Compose-Konfigurationen, Prometheus- und OpenTelemetry-Setups sowie Vorlagen zur Generierung von Produktivitätsberichten, die in Tools wie Linear integriert sind.

Sicherheit und Datenschutz

• OpenTelemetry-Export zu Ihrem Backend ist opt-in und erfordert explizite Konfiguration. Informationen zu Anthropics separater operativer Telemetrie und wie Sie diese deaktivieren, finden Sie unter Datennutzung
• Standardmäßig sind rohe Dateiinhalte und Code-Snippets nicht in Metriken oder Ereignissen enthalten. Wenn Sie eine Variable wie OTEL_LOG_TOOL_DETAILS oder OTEL_LOG_RAW_API_BODIES setzen, können Ereignisse sie enthalten. Trace-Spans sind ein separater Datenpfad: siehe die Aufzählung OTEL_LOG_TOOL_CONTENT unten
• Wenn über OAuth authentifiziert, ist user.email in Telemetrie-Attributen enthalten und wird nur an den OTel-Endpunkt gesendet, den Sie konfigurieren, niemals an Anthropic. Wenn dies ein Problem für Ihre Organisation darstellt, arbeiten Sie mit Ihrem Telemetrie-Backend zusammen, um dieses Feld zu filtern oder zu schwärzen
• Benutzer-Prompt-Inhalte werden standardmäßig nicht erfasst. Nur die Prompt-Länge wird aufgezeichnet. Um Prompt-Inhalte einzubeziehen, setzen Sie OTEL_LOG_USER_PROMPTS=1. Wenn aktiviert:

  • user_prompt-Ereignisse tragen den Prompt-Text in zwei Attributen, prompt und prompt_text. Wenn Sie den Prompt-Text des Ereignisses in Ihrem Collector anhand des Attributnamens verwerfen oder maskieren, nennen Sie beide Attribute in der Regel

    Dieser attributes-Prozessor des OpenTelemetry Collector löscht beide Attribute in den Pipelines, die ihn aufführen:

    processors:
      attributes/drop-prompt-text:
        actions:
          - key: prompt
            action: delete
          - key: prompt_text
            action: delete
    

  • Bei aktiviertem Tracing trägt der claude_code.interaction-Span den Prompt-Text in seinem user_prompt-Attribut

  • Unter detailliertem Beta-Tracing tragen Spans außerdem die neuen Benutzernachrichten, Tool-Ergebnisse und System-Erinnerungen, die mit jeder Anfrage gesendet werden, den Text des System-Prompts und die Modellausgabe. Inhaltsattribute unter detailliertem Beta-Tracing listet jedes Attribut auf. Das claude_code.system_prompt-Ereignis trägt den vollständigen System-Prompt

• Assistent-Antworttext wird standardmäßig nicht erfasst. Nur die Antwortlänge wird aufgezeichnet. Um Antworttext einzubeziehen, setzen Sie OTEL_LOG_ASSISTANT_RESPONSES=1. Wie alle OpenTelemetry-Daten von Claude Code wird der Antworttext nur an den OTel-Endpunkt gesendet, den Sie konfigurieren, niemals an Anthropic. Wenn diese Variable nicht gesetzt ist, wird OTEL_LOG_USER_PROMPTS als Fallback verwendet, daher setzen Sie OTEL_LOG_ASSISTANT_RESPONSES=0, wenn Sie Prompt-Inhalte ohne Antwortinhalte in Ereignissen möchten. Unter detailliertem Beta-Tracing trägt der claude_code.llm_request-Span weiterhin die Modellausgabe in response.model_output, das OTEL_LOG_USER_PROMPTS statt dieser Variable folgt
• Tool-Eingabeargumente und Parameter werden standardmäßig nicht protokolliert. Um sie einzubeziehen, setzen Sie OTEL_LOG_TOOL_DETAILS=1. Für die integrierten Server von Claude Desktop werden in Sitzungen, die Claude Desktop besitzt, tool_decision und tool_result mit dem Paar mcp_server_name/mcp_tool_name übertragen, von Hosts erstellte Namen statt Argumentinhalte, auch wenn das Flag aus ist. Diese Daten werden nur an den OTEL-Endpunkt gesendet, den Sie konfigurieren, niemals an Anthropic. Argumente können immer noch vertrauliche Werte enthalten, daher konfigurieren Sie Ihr Telemetrie-Backend, um diese Attribute nach Bedarf zu filtern oder zu schwärzen. Wenn aktiviert:
  • tool_result- und tool_decision-Ereignisse enthalten ein tool_parameters-Attribut mit Bash-Befehlen, MCP-Server- und Tool-Namen sowie Skill-Namen. Felder wie full_command werden ungekürzt ausgegeben
  • tool_result-Ereignisse enthalten zusätzlich ein tool_input-Attribut mit Dateipfaden, URLs, Suchmustern und anderen Argumenten. Einzelne Werte über 512 Zeichen werden gekürzt und die Gesamtmenge ist auf etwa 4 K Zeichen begrenzt
  • user_prompt-Ereignisse enthalten den wörtlichen command_name für benutzerdefinierte, Plugin- und MCP-Befehle
  • Die Kosten- und Token-Zähler und die Ereignisse api_request, api_error und api_refusal tragen echte Agent-, Skill-, Plugin- und MCP-Server- und Tool-Namen in ihren Attributionierungsattributen
  • Der claude_code.tool-Span trägt eingabebezogene Attribute wie file_path. Unter detailliertem Beta-Tracing trägt er außerdem ein tool_input-Attribut
• Tool-Inhalte werden in Trace-Spans standardmäßig nicht protokolliert. Um sie einzubeziehen, setzen Sie OTEL_LOG_TOOL_CONTENT=1. Der claude_code.tool-Span trägt dann ein tool.output-Span-Ereignis mit rohen Dateiinhalten, Bash-Befehlsausgabe und dem, was MCP-Tools, WebFetch und WebSearch zurückgeben, gekürzt bei der Inhaltsbegrenzung (standardmäßig 60 KB) pro Attribut. Ergebnisse von MCP-Tools, WebFetch und WebSearch erfordern Claude Code v2.1.283 oder später. Tool-Inhalte erreichen Spans auch durch new_context, dessen Gate je nach Span unterschiedlich ist. Konfigurieren Sie Ihr Telemetrie-Backend, um diese Attribute nach Bedarf zu filtern oder zu schwärzen
• Rohe Anthropic Messages API-Anfrage- und Antwort-Texte werden standardmäßig nicht protokolliert. Um sie einzubeziehen, setzen Sie OTEL_LOG_RAW_API_BODIES in Ihrer Shell, Benutzereinstellungen oder verwalteten Einstellungen. Es wird in Projekt- und lokalen Einstellungen ignoriert. Die Texte enthalten die gesamte Konversationshistorie, einschließlich des Systemprompts, jedes vorherigen Benutzer- und Assistent-Durchgangs und Tool-Ergebnisse, daher impliziert das Aktivieren dies Zustimmung zu allem, was die anderen OTEL_LOG_*-Content-Flags offenbaren würden. Claude Code schwärzt immer Claudes Extended-Thinking-Inhalte aus diesen Texten, unabhängig von anderen Einstellungen. Der Wert, den Sie setzen, bestimmt, wie Claude Code die Texte bereitstellt:

  • Mit =1 gibt Claude Code api_request_body- und api_response_body-Log-Ereignisse für jeden API-Aufruf aus. Das body-Attribut der Ereignisse trägt die JSON-serialisierte Nutzlast, gekürzt bei der Inhaltsbegrenzung (standardmäßig 60 KB)

  • Mit =file:<dir> schreibt Claude Code ungekürzte Texte unter diesem Verzeichnis in .request.json- und .response.json-Dateien, und die Ereignisse tragen einen body_ref-Pfad statt des Inline-Textes. Versenden Sie das Verzeichnis mit einem Log-Collector oder Sidecar statt über den Telemetrie-Stream.

    Für jede erfolgreiche Antwort hängt Claude Code auch eine Zeile an index.jsonl in diesem Verzeichnis an, die die Antwortdatei mit der Anfragedatei verknüpft, die sie erzeugt hat, und mit der Transkriptnachricht, zu der sie wurde. Jede Zeile enthält keinen Nachrichteninhalt, und der Abschnitt API-Antwort-Body-Ereignis listet seine Felder auf. Die Index-Datei erfordert Claude Code v2.1.274 oder später

Ü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 (Amazon Bedrock).