Agenten-Observability: sehen, was dein Agent wirklich tut

Logs, Kosten-Tracking und OpenTelemetry-Support machen aus einer Blackbox-Session nachvollziehbare Daten – wichtig, sobald Agenten automatisiert oder im Team laufen.

Warum Beobachten wichtig wird

Solange du allein und interaktiv mit einem Agenten arbeitest, siehst du direkt, was passiert. Sobald Agenten automatisiert, im Team oder in CI/CD laufen, brauchst du dafür echte Daten: Was hat der Agent gemacht, wie viel hat es gekostet, welche Tools wurden aufgerufen.

Session-Logs als Grundpuffer

Claude Code schreibt jede Session als JSONL-Datei auf die Festplatte (unter ~/.claude/projects/). Das Format ist intern und ändert sich zwischen Versionen – parse diese Dateien nicht direkt, sondern nutze /export oder die dokumentierten Schnittstellen. Auch bei Abo-Plänen zeigt /usage eine Kosten- und Nutzungsaufschlüsselung direkt im Terminal.

Kosten-Tracking im Terminal

Der Befehl /usage zeigt geschätzte Kosten und Token-Nutzung der aktuellen Session direkt im Terminal, aufgeschlüsselt nach Skills, Subagents, Plugins und einzelnen MCP-Servern. Die Zahl ist eine lokale Schätzung aus Token-Zählungen, keine autoritative Rechnung.

OpenTelemetry für den großen Überblick

Für Team- oder Organisationsebene bietet Claude Code nativen OpenTelemetry-Support: Mit CLAUDE_CODE_ENABLE_TELEMETRY=1 exportierst du Metriken, Events und optional Traces an ein eigenes Observability-Backend (Prometheus, Grafana, Datadog & Co.). So bekommst du Kosten, Tool-Nutzung und Sicherheitsereignisse zentral über alle Nutzer:innen hinweg – statt Logs von jeder Maschine einzeln einzusammeln.

BEISPIEL

`export CLAUDE_CODE_ENABLE_TELEMETRY=1`, `export OTEL_METRICS_EXPORTER=otlp` und `export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317` vor dem Start von `claude` reichen, um Metriken an ein lokales OpenTelemetry-Collector-Setup zu schicken.

🛠️ ÜBUNG — MACH DAS BEI DIR

Aktiviere lokal die Kosten- und Session-Transparenz in Claude Code, ohne einen externen Observability-Stack aufzusetzen.

Führe in einer laufenden Claude-Code-Session /usage aus und lies die Aufschlüsselung nach Skills, Subagents und MCP-Servern.
Öffne /usage und sieh dir die Kosten-/Nutzungsaufschlüsselung an.
Setze testweise CLAUDE_CODE_ENABLE_TELEMETRY=1 und OTEL_METRICS_EXPORTER=console, starte claude neu und beobachte, welche Metriken in der Konsole erscheinen.

✅ SELBST-CHECK

☐ Konntest du anhand von /usage sagen, welcher Teil der Session (z. B. ein bestimmter MCP-Server) am meisten Kontext verbraucht hat?
☐ Was stand in der JSONL-Zeile – reichte dir das für eine Kosten-Nachvollziehung?
☐ Welche der OTEL_LOG_*-Variablen würdest du in einem echten Team-Setup NICHT aktivieren, weil sie zu sensible Daten exportiert?

KURZ-QUIZ

Wie aktivierst du OpenTelemetry-Export in Claude Code am einfachsten?