| name | langfuse |
| description | Query, analyze, and score Claude Code session traces in LangFuse. Use this skill whenever you need to check session costs, token usage, tool execution patterns, or agent performance in LangFuse. Also use when creating scores, investigating trace data, comparing runs, or when the user mentions LangFuse, observability, telemetry, traces, session costs, or wants to understand what happened in a previous Claude Code session. This skill covers both reading traces and writing scores/annotations back to LangFuse.
|
LangFuse Observability
Access and analyze Claude Code session telemetry stored in LangFuse. This skill covers querying traces, analyzing costs and performance, and writing scores back to LangFuse.
How the Setup Works
Claude Code emits OpenTelemetry (OTEL) signals — metrics, events, and distributed traces — on every API call and tool execution, including subagent calls. These signals are configured to export to localhost:4318.
When the telemetry bridge is running, it catches those signals and forwards them to your LangFuse instance. When the bridge is off, exports silently fail with zero impact.
Claude Code (OTEL always active)
→ localhost:4318 (OTLP HTTP/JSON)
→ lainra/claude-code-telemetry bridge (Node.js)
→ cloud.langfuse.com (LangFuse Cloud)
Bridge location: ~/.claude/telemetry/claude-code-telemetry/
Bridge control: record-start / record-stop (shell functions)
Credentials: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST set in your shell profile.
Primary Tool: LangFuse CLI
The langfuse-cli is installed globally and is the primary way to interact with LangFuse. Auth is handled via environment variables already configured in the shell.
langfuse api <resource> <action> [options]
Discovery pattern — when you're unsure what's available:
langfuse api __schema
langfuse api <resource> --help
langfuse api <resource> <action> --help
langfuse api <resource> <action> --curl
Key Resources
| Resource | What it holds |
|---|
traces | One per user prompt. Contains cost, tokens, metadata. |
observations | Individual steps within a trace (API calls, tool executions) |
sessions | Groups of traces from one Claude Code CLI session |
scores | Quality ratings attached to traces or observations |
score-configs | Schema definitions for score types |
metrics | Aggregated data (costs, tokens, latency) across dimensions |
prompts | Managed prompts (not relevant to OTEL traces) |
datasets | Evaluation datasets |
Common Queries
List recent traces:
langfuse api traces list --limit 10
Get a specific trace by ID:
langfuse api traces get <trace-id>
List traces for a specific session:
langfuse api traces list --session-id <session-id>
List observations with cost/token data:
langfuse api observations list --fields core,usage,model --limit 20
Get aggregated metrics (cost by model):
langfuse api metrics list --view observations --measures totalCost --dimensions providedModelName --from-timestamp <ISO-date>
List sessions:
langfuse api sessions list --limit 5
For complex queries, read references/cli-patterns.md for advanced filtering, pagination, and aggregation examples.
Data Model
Understanding how LangFuse structures data helps you query effectively.
Session → contains multiple Traces → each trace contains multiple Observations
- Session (
session.id): One Claude Code CLI session. All prompts within that session share the same session ID.
- Trace (
prompt.id): One user prompt and everything it triggered — API calls, tool executions, subagent work. The trace name field shows conversation-N (the Nth prompt in the session).
- Observation: A single step within a trace. Types:
GENERATION — an API call to Claude (has model, tokens, cost)SPAN — a tool execution or logical grouping (has duration)EVENT — a discrete event (tool_result, user_prompt, etc.)
Scores can be attached to traces or observations. They have a name, value, dataType (NUMERIC, BOOLEAN, CATEGORICAL), and source (API, ANNOTATION, EVAL).
What's Captured in Each Trace
Every trace from Claude Code includes these OTEL signals:
| Signal | Key Fields |
|---|
api_request | model, cost_usd, input/output/cache tokens, duration_ms, speed |
tool_result | tool_name, success, duration_ms, tool_parameters, tool_input |
user_prompt | prompt text, prompt_length |
api_error | model, error, status_code, duration_ms |
tool_decision | tool_name, decision (accept/reject), source |
Subagent correlation: All subagent API calls and tool executions share the parent trace's prompt.id. A multi-agent command with 12 subagents produces one trace with all their events correlated.
Writing Scores
Create score configs to define your scoring schema, then attach scores to traces:
Create a score config:
langfuse api score-configs create --name "response-quality" --data-type NUMERIC --min-value 1 --max-value 5 --description "Quality of agent response"
Score a trace via the ingestion API:
langfuse api ingestions create --body '{
"batch": [{
"id": "unique-event-id",
"type": "score-create",
"timestamp": "2026-04-03T00:00:00Z",
"body": {
"traceId": "<trace-id>",
"name": "response-quality",
"value": 4,
"dataType": "NUMERIC",
"source": "API"
}
}]
}'
Documentation & References
When You Can't Find What You Need
If the CLI doesn't surface what you're looking for:
- Use the LangFuse docs MCP —
mcp__langfuse-docs__searchLangfuseDocs is available for semantic search across all LangFuse documentation.
- Check the API reference —
langfuse api <resource> <action> --curl previews the raw HTTP request, which you can adapt.
- Fetch a docs page directly —
mcp__langfuse-docs__getLangfuseDocsPage with a path like /docs/evaluation/overview.
