Claude Code Observability: OTEL to LangFuse

Route Claude Code's built-in OpenTelemetry signals through a local bridge to LangFuse for full session observability — cost tracking, token analysis, tool profiling, and multi-agent trace correlation.

Companion to Turning on the lights on SapientTech.dev. Also available as a video.

Architecture

Claude Code (OTEL env vars — always active)
    | metrics + events + distributed trace spans
    | OTLP HTTP/JSON → localhost:4318
    v
lainra/claude-code-telemetry bridge (Node.js)
    | converts OTEL signals → LangFuse format
    | binds 127.0.0.1 only (no LAN exposure)
    v
LangFuse Cloud (cloud.langfuse.com)
    | traces, observations, sessions, scores
    | queryable via CLI, SDK, API, dashboard

Two modes: bridge off (OTEL exports silently fail, zero impact) or bridge on (full telemetry flows to LangFuse).

What You Get

Capability	Detail
Cost tracking	Per-session, per-model (Opus / Sonnet / Haiku) cost breakdown
Token analysis	Input, output, and cache tokens per API call
Tool profiling	Tool call counts, durations, success rates, parameters
Multi-agent traces	All subagent calls correlated under one trace via prompt.id
Run comparison	Compare cost and tokens across runs of the same command
Content capture	Full prompt text, tool I/O (up to 60KB per span) when enabled

Prerequisites

• Claude Code (OTEL telemetry is built in)
• Node.js 18+
• LangFuse account — cloud or self-hosted
• npm — for installing the bridge and CLI

Platform Notes

This was built on Windows and works on macOS and Linux. The bridge control functions auto-detect the platform and use the right process management commands (netstat/taskkill on Windows, lsof/kill on macOS/Linux).

Windows users: You need Git for Windows (which includes Git Bash). Run setup.sh from Git Bash, not PowerShell. Claude Code's built-in Bash tool uses Git Bash, so the OTEL vars and record functions in ~/.bashrc are picked up automatically.

macOS/Linux users: Everything works natively. No special requirements.

Setup

Quick Start (automated)

git clone https://github.com/lifegenieai/claude-code-observability.git
cd claude-code-observability
bash setup.sh

The script walks you through each step interactively. Or follow the manual steps below.

Manual Setup

Step 1: Clone the telemetry bridge

mkdir -p "$HOME/.claude/telemetry"
cd "$HOME/.claude/telemetry"
git clone https://github.com/lainra/claude-code-telemetry.git
cd claude-code-telemetry
git checkout 5ae1fc3    # Pin to an audited commit
npm install

Pin to a specific commit rather than tracking HEAD. The bridge sees all telemetry data in cleartext — prompts, tool I/O, file contents. Audit before updating.

Step 2: Configure bridge credentials

Copy the template and fill in your LangFuse API keys:

cp <this-repo>/config/.env.example "$HOME/.claude/telemetry/claude-code-telemetry/.env"
chmod 600 "$HOME/.claude/telemetry/claude-code-telemetry/.env"

Edit .env with your keys from LangFuse Settings > API Keys:

LANGFUSE_PUBLIC_KEY=pk-lf-your-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-secret-key
LANGFUSE_HOST=https://cloud.langfuse.com
OTLP_RECEIVER_HOST=127.0.0.1

Step 3: Add OTEL environment variables to your shell profile

Append the contents of config/otel-env-vars.sh to your shell profile (~/.bashrc, ~/.zshrc, or equivalent):

cat config/otel-env-vars.sh >> ~/.bashrc

This sets the OTEL export variables that Claude Code reads at startup, plus the LangFuse CLI auth variables. When the bridge isn't running, exports silently fail with zero impact.

Step 4: Add bridge control functions

Append the contents of config/record-functions.sh to the same shell profile:

cat config/record-functions.sh >> ~/.bashrc

This gives you two commands:

• record-start — starts the bridge, traces begin flowing to LangFuse
• record-stop — kills the bridge, OTEL exports silently fail again

The functions auto-detect Windows vs macOS/Linux and use the right process commands.

Step 5: Install the LangFuse CLI

npm install -g langfuse-cli

This lets you query traces, observations, metrics, and scores directly from the terminal.

Step 6: Install the agent skill (optional)

Copy the skill into your project so your agents can query their own traces:

cp -r skills/langfuse <your-project>/.claude/skills/langfuse

With this skill loaded, you can ask your agent: "How much did my last session cost?" or "What tools were used most in recent traces?"

Step 7: Source and verify

source ~/.bashrc
record-start
curl http://localhost:4318/health
# Expected: {"status":"healthy","langfuse":"connected"}

Then start a Claude Code session, run any command, and check your LangFuse dashboard for traces.

When done: record-stop

Repo Structure

claude-code-observability/
├── README.md                              # This file
├── setup.sh                               # Automated setup script
├── config/
│   ├── otel-env-vars.sh                   # OTEL + LangFuse CLI env vars
│   ├── record-functions.sh                # record-start / record-stop
│   └── .env.example                       # Bridge credential template
└── skills/
    └── langfuse/
        ├── SKILL.md                       # Agent skill for querying traces
        └── references/
            ├── bridge-architecture.md     # Bridge internals and troubleshooting
            └── cli-patterns.md            # Advanced LangFuse CLI queries

Usage

# Start recording
record-start

# ... use Claude Code normally ...

# Query traces
langfuse api traces list --limit 10
langfuse api observations list --fields core,usage,model --limit 20

# Aggregated cost by model
langfuse api metrics list \
  --view observations \
  --measures totalCost \
  --dimensions providedModelName \
  --from-timestamp "2026-01-01T00:00:00Z"

# Stop recording
record-stop

See skills/langfuse/references/cli-patterns.md for advanced filtering, pagination, metrics aggregation, and scoring patterns.

Known Quirks

Input tokens underreported: The bridge may report input_tokens: 1 for many API calls. This is a known limitation of the OTEL bridge. Output tokens and cost_usd are accurate — focus on those for analysis.

References

• Claude Code: Monitoring usage — official OTEL variable docs
• LangFuse Data Model — sessions, traces, observations
• LangFuse API Reference — full REST API
• lainra/claude-code-telemetry — the bridge repo

License

MIT

---

Built by Erik Benjaminson at Sapient Technology Group.