Claude Code kann OpenTelemetry (OTel) exportieren um Usage, Costs und Tool-Activity zu tracken. Das ist opt-in und erfordert explizite Konfiguration.

Quick Start

1. Aktiviere Telemetry

export CLAUDE_CODE_ENABLE_TELEMETRY=1

Oder in .claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

2. Waehle Exporters

# Metriken exportieren
export OTEL_METRICS_EXPORTER=otlp

# Events/Logs exportieren
export OTEL_LOGS_EXPORTER=otlp

# Oder console zum Debuggen
export OTEL_METRICS_EXPORTER=console

3. Konfiguriere Endpoint

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

4. Optional: Authentication

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

5. Starte Claude Code

claude

Metriken und Events werden jetzt an deinen Collector exportiert.

Exporter Optionen

OTLP (OpenTelemetry Protocol)

Standard Protocol — funktioniert mit den meisten Backends.

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Backends:

  • OpenTelemetry Collector
  • Datadog
  • New Relic
  • Honeycomb
  • Jaeger

Prometheus

Fuer Metriken direct in Prometheus:

export OTEL_METRICS_EXPORTER=prometheus

Startet einen Prometheus-Endpoint auf Port 8888.

Console

Zum Debuggen — Metriken werden in der Console ausgegeben:

export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=10000  # Every 10 seconds

Konfiguration

Environment Variables

Variable Beschreibung Beispiel
CLAUDE_CODE_ENABLE_TELEMETRY Aktiviert Telemetry (MUSS gesetzt sein) 1
OTEL_METRICS_EXPORTER Metriken-Exporter otlp, prometheus, console
OTEL_LOGS_EXPORTER Logs/Events-Exporter otlp, console
OTEL_EXPORTER_OTLP_ENDPOINT OTLP Collector Endpoint http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL OTLP Protocol grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_HEADERS Auth Headers Authorization=Bearer token
OTEL_METRIC_EXPORT_INTERVAL Export-Interval in ms 60000 (default)
OTEL_LOGS_EXPORT_INTERVAL Logs Export-Interval 5000 (default)

Cardinality Control

Reduziere Metriken-Cardinality (weniger Storage):

export OTEL_METRICS_INCLUDE_SESSION_ID=false
export OTEL_METRICS_INCLUDE_ACCOUNT_UUID=false
export OTEL_METRICS_INCLUDE_VERSION=false

Verfuegbare Metriken

Sessions

claude_code.session.count

Zaehler: Neue Sessions gestartet.

Attributes:

  • session.id
  • user.email
  • organization.id

Code Changes

claude_code.lines_of_code.count

Zaehler: Lines hinzugefuegt/entfernt.

Attributes:

  • type: "added" oder "removed"

Commits

claude_code.commit.count

Zaehler: Git Commits erstellt.

Pull Requests

claude_code.pull_request.count

Zaehler: PRs erstellt.

Token Usage

claude_code.token.usage

Zaehler: Tokens verwendet.

Attributes:

  • type: "input", "output", "cacheRead", "cacheCreation"
  • model: Model verwendet

Cost

claude_code.cost.usage

Zaehler: Geschaetzte Kosten in USD.

Attributes:

  • model: Model

Tool Decisions

claude_code.code_edit_tool.decision

Zaehler: Code-Edit Genehmigungen (accept/reject).

Attributes:

  • tool_name: "Edit", "Write", "NotebookEdit"
  • decision: "accept" oder "reject"
  • language: Programmiersprache

Active Time

claude_code.active_time.total

Zaehler: Aktive Zeit in Sekunden (ohne Idle).

Attributes:

  • type: "user" (Tastatur) oder "cli" (Tool Execution)

Verfuegbare Events

User Prompt Event

Wenn Benutzer einen Prompt eingibt.

Feld: claude_code.user_prompt

Daten:

  • prompt_length
  • prompt (optional, aktiviere mit OTEL_LOG_USER_PROMPTS=1)

Tool Result Event

Wenn ein Tool ausfuehrung abschliesst.

Feld: claude_code.tool_result

Daten:

  • tool_name
  • success: true/false
  • duration_ms
  • error (wenn fehlgeschlagen)

API Request Event

Fuer jeden Claude API Request.

Feld: claude_code.api_request

Daten:

  • model
  • cost_usd
  • duration_ms
  • input_tokens
  • output_tokens
  • cache_read_tokens
  • cache_creation_tokens

API Error Event

Wenn API Request fehlschlaegt.

Feld: claude_code.api_error

Daten:

  • model
  • error
  • status_code
  • attempt (Retry-Nummer)

Dynamic Headers (Enterprise)

Fuer Organisationen mit dynamischen Authentifizierung (Token Refresh):

{
  "otelHeadersHelper": "/bin/generate_headers.sh"
}

Script muss JSON-Header zurueckgeben:

#!/bin/bash
echo "{\"Authorization\": \"Bearer $(get-token.sh)\"}"

Wird alle 29 Minuten refreshed. Interval konfigurierbar:

export CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS=900000

Dashboards & Analyse

Mit Prometheus/Grafana

  1. Exportiere Metriken zu Prometheus
  2. Erstelle Grafana Dashboard
  3. Query Metriken:
rate(claude_code_token_usage_total{type="input"}[5m])

Mit Datadog

Verbinde Datadog OTel Receiver:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://datadog-agent:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $DD_API_KEY"

Metriken erscheinen automatisch in Datadog.

Mit Honeycomb

Einfach Honeycomb als OTLP Receiver:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=$HC_API_KEY"

Team Multi-Tenancy

Fuer Organisationen mit mehreren Teams:

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Alle Metriken werden mit diesen Attributen tagged.

Formatting-Regeln:

  • Komma-getrennte key=value Paare
  • Keine Spaces in Values
  • Percent-encode spezielle Zeichen
# FALSCH
export OTEL_RESOURCE_ATTRIBUTES="team=My Team"

# RICHTIG
export OTEL_RESOURCE_ATTRIBUTES="team=my_team"

ROI Measurement

Basis-Metriken

Metrik Beschreibung Formel
LOC/Session Code per Session total_lines_added / session_count
Cost/LOC Kosten pro Zeile total_cost / total_lines_added
Time Saved Geschaetzte Zeit commits_count * avg_commit_time
Commits/Day Velocity commits_count / days

Berechnung von ROI

ROI % = ((Time_Saved * Hourly_Rate) - Total_Cost) / Total_Cost * 100

Beispiel:

  • Time Saved: 40 Stunden (400 commits × 6 min each)
  • Hourly Rate: $100
  • Total Cost: $500 (Tokens)
ROI = ((40 × 100) - 500) / 500 × 100 = 7,900%

Cost Optimization

# Reduziere Export-Interval wenn unnoetiger Overhead
export OTEL_METRIC_EXPORT_INTERVAL=120000  # 2 minutes statt 60s

# Deaktiviere Session-ID wenn cardinality ein Problem
export OTEL_METRICS_INCLUDE_SESSION_ID=false

# Reduziere Event-Logging
export OTEL_LOG_USER_PROMPTS=0
export OTEL_LOG_TOOL_DETAILS=0

Security & Privacy

Was wird gecollected

IMMER:

  • Session ID
  • User Email (wenn OAuth)
  • Organization ID
  • Token Counts
  • Cost
  • Tool Names

NUR wenn aktiviert:

  • User Prompt Content (OTEL_LOG_USER_PROMPTS=1)
  • MCP/Skill Names (OTEL_LOG_TOOL_DETAILS=1)

Was wird NICHT gecollected

  • File Contents
  • Raw Code
  • Secrets/API Keys
  • Passwords

Redaction & Filtering

Dein Backend kann Telemetry filtern:

# Nur Public Metrics
rate(claude_code_cost_usage_total[5m])

# Exclude sensitive orgs
rate(claude_code_token_usage_total{organization_id!="private"}[5m])

Troubleshooting

Metriken kommen nicht an

  1. Pruefen ob enabled:

    echo $CLAUDE_CODE_ENABLE_TELEMETRY

  2. Pruefen ob Endpoint erreichbar:

    curl http://localhost:4317/healthz

  3. Checken ob Exporter konfiguriert:

    echo $OTEL_METRICS_EXPORTER

Zu viele Metriken (Cardinality Issue)

Problem: claude_code.session.count mit jedem Session-ID wird 10000+ Time Series.

Loesungen:

# Deaktiviere Session ID
export OTEL_METRICS_INCLUDE_SESSION_ID=false

# Oder nutze organisationID aggregation
export OTEL_RESOURCE_ATTRIBUTES="organization.id=org-1"

Authentisierung fehlgeschlagen

# Pruefen ob Token valid
echo $OTEL_EXPORTER_OTLP_HEADERS

# Test mit curl
curl -H "$OTEL_EXPORTER_OTLP_HEADERS" \
  http://your-collector:4317/metrics

Weitere Ressourcen

Stand: 2026-03-21 | Claude Code Monitoring & Telemetry Reference