CLAUDE.md, skills or auto-loaded context, so the system prompt that actually shaped the answer is not in the trace, and no setting changes that yet. Read a trace as the flight recorder, not the cockpit: it tells you what happened, in what order, at what cost, and nothing about how the pilot was briefed. Langfuse is a recorder, not a runtime; nothing routes through it, and if it is down the agent runs exactly as before.The moves that matter
| Move | Think of it as | What actually happens |
|---|---|---|
| Trace | One flight | One request end to end: the question in, the answer out, every step between. |
| Observation | One instrument reading | A step inside a trace: a span (any code), a generation (a model call, with tokens and cost) or a tool call. They nest. |
| Session | The whole trip | Traces that belong together, such as one Claude Code session. Set with session_id; browse in the Sessions tab. |
| Score | The grade | A number or label pinned to a trace by you, by code, or by an LLM judge: langfuse.create_score(name, value, trace_id). |
| Prompt | The call sheet | A versioned prompt kept in Langfuse with labels (production, latest); code fetches it by name instead of hard-coding it. |
| Dataset + experiment | The test track | Saved inputs with expected outputs. Rerun after a change and compare the scores side by side. |
| Unit | The meter | Cloud billing counts every trace, observation and score as one unit. Hobby plan: 50k units a month, 30 days of history, free, no card. |
Safe to try
None of this touches the agent. The hook runs after a turn has ended; the decorator records and returns. Remove either and you lose history, nothing else.
| Safe move | Why it cannot hurt |
|---|---|
| Sign up at cloud.langfuse.com, Hobby plan | Nothing to install or run; the hook posts to the cloud. No card, 50k units a month. If you never send an event, nothing happens. |
docker compose up in a clone of langfuse/langfuse, only if you want the data on your own machine | Self-hosting is six processes (Postgres, ClickHouse, Redis, object storage, web, worker); Compose is just the one-command way to start them together. Local Langfuse at http://localhost:3000 in two to three minutes; Ctrl-C stops it. |
@observe(as_type="generation") on any function | Records input, output, timing and errors, then returns the same value it always did. |
The everyday loop
Run the agent. Open the trace that was slow, expensive or wrong, and read the step where it went sideways, not the summary. Fix the prompt or the tool. Score the fixed run so it shows up next week. Once a week, sort sessions by cost and look at the top three.
Practice, start to finish
| Step | Do | What you should see |
|---|---|---|
| 1 | claude plugin marketplace add langfuse/Claude-Observability-Plugin then claude plugin install langfuse-observability@langfuse-observability | A Stop hook appears in ~/.claude/settings.json. It runs after every response. |
| 2 | In the project's .claude/settings.json, under "env": TRACE_TO_LANGFUSE=true, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL | Nothing yet. The hook only fires when a turn ends. |
| 3 | Run claude and ask for something that uses a tool; wait for the answer | Langfuse, Sessions tab: one session. Inside it, one trace per turn. |
| 4 | Open a trace | A generation span (your prompt, the reply, any tool calls) and one tool span per tool (input, output, duration), plus input, output and cache tokens from Anthropic's usage field. |
| 5 | For a script that calls Claude directly: pip install "langfuse>=4,<5" anthropic opentelemetry-instrumentation-anthropic, then AnthropicInstrumentor().instrument() before the first call, and langfuse.flush() at the end | Every messages.create() becomes a generation with tokens. Without the flush, a short script exits before the last events leave the buffer. |
When you make a mess
| Situation | Way out | What it does |
|---|---|---|
| Nothing shows up | Check TRACE_TO_LANGFUSE=true, the three keys, and that the python3 on your PATH has langfuse installed | Hooks fail quietly, on purpose. They are telemetry, not enforcement. |
Keys in a committed settings.json | Project settings, API keys, revoke; issue a new pair | The old key dies at once. Traces stay. |
| Trace flood, units climbing | Tag test runs environment=development and filter them out, or self-host, where units are free | The 50k cap is monthly and cloud-only. |
| Right answer, wrong step | Add a score with a comment on that trace | The comment is the note-to-self you find next week. |
| Local instance broken | docker compose down, then docker compose up --pull always | Restarts and upgrades. Volumes, and the history in them, survive. |
Leave this alone: docker compose down -v. The -v deletes the volumes, and the volumes are every trace you ever recorded. There is no undo.
Words you will see
| Term | Plain meaning |
|---|---|
| OTel / OTLP | OpenTelemetry, the open standard the v4 SDK is built on. Anything that speaks OTLP over HTTP can post to /api/public/otel, no SDK needed. |
| Generation | An observation that is a model call. Carries the model name, tokens and cost; the thing you sort by when the bill surprises you. |
| Environment | A tag that separates production, staging and development. Filter on it before you trust any chart. |
| LLM-as-judge | An evaluator prompt that scores traces for you. Set up in the UI; the output is ordinary scores. |
| Prompt label | production or latest. Code asks for a prompt by name and receives whichever version wears the label. |
| Stop hook | The command Claude Code runs after each response. It is what ships the turn to Langfuse, and a developer can switch it off locally. |
Deliberately not here
Prompt management, datasets and experiments, and evaluator setup: each is its own page, and none matters until you have a week of traces to judge. Kubernetes self-hosting (4 cores, 16 GB, not a laptop job). The JavaScript SDK, the new AI gateway, roles and permissions. All of it waits until the first week of traces has told you which of them you want.
Where it sits for this harness
The Natural Helper intake parked Langfuse as “later: keep the HTML trace, revisit if a card runs unattended for more than a day.” That still holds, and the trial is now cheap enough to run the day that trigger fires: the Claude Code plugin is two commands and the Hobby tier costs nothing. Langfuse is v4.35 as of September 11, 2026. ClickHouse bought the company in January 2026; the core stays MIT and self-hosting stays first-class, so the exit is a docker compose up on your own machine.
Langfuse · two-page primer · September 13, 2026 · langfuse.com/docs