Langfuse

Langfuse

This skill helps you use Langfuse effectively: debugging traces, inspecting LLM generations and tool calls, reviewing sessions, and managing prompts.

Core Principles

1. Use the query script for data access: Run langfuse_query.sh for all Langfuse queries. It detects the server's API generation and picks the right endpoints. The script ships in this skill's bin/ directory, which is on the Bash tool's PATH whenever the skill is installed — invoke it by bare name, never by an absolute path.
2. Documentation First: When implementing SDK integrations, always fetch current docs before writing code (Langfuse updates frequently).

Per-Project Configuration (.agent.env)

Each project should have a .agent.env file in the project root:

LANGFUSE_BASE_URL: http://localhost:3000
LANGFUSE_PUBLIC_KEY: pk-lf-...
LANGFUSE_SECRET_KEY: sk-lf-...

• LANGFUSE_BASE_URL: base URL of your Langfuse instance — local, EU cloud (https://cloud.langfuse.com), or US cloud (https://us.cloud.langfuse.com).
• API keys are in your Langfuse project under Settings > API Keys.

If any value is missing from .agent.env, ask the user to add it before proceeding.

Permissions

The query script is meant to be pre-approved, via this rule:

Bash(langfuse_query.sh:*)

Neither install route installs that rule — it ships in the toolkit's project-files/.claude/settings.json template, which the user merges into a project's .claude/settings.json (or their user settings) themselves. If every call prompts, the rule is absent: that is unfinished setup, not a broken skill, and not a reason to reach for curl. Say so once and carry on.

Run the script directly — never export env vars manually or run curl directly for data access. Both trigger permission prompts. The script reads .agent.env automatically from the project root.

The rule approves the bare command name, matching whatever PATH resolves it to. An invocation prefixed with an inline env var (LANGFUSE_MAX_RECORDS=10000 langfuse_query.sh ...) falls outside it and will prompt — expected, and rare enough not to warrant a broader rule.

Two failures are environment rather than defects: Missing required command: <x> (exit 127) means a dependency is absent — tell the user to install it; and command not found: langfuse_query.sh means the skill's bin/ is not on PATH, so the plugin is disabled or the session predates the install. Neither is a reason to edit the script.

API generations (important)

Langfuse v4 changed the read API surface. The script reads the server version once from /api/public/health and routes accordingly:

Check what you're talking to:

langfuse_query.sh apigen        # → legacy | v4

Override detection with LANGFUSE_API_GEN=legacy|v4 if needed.

Three v4 behaviours worth knowing

• traces and sessions are derived, not equivalent. v4 exposes no trace or session read entity, so the script groups observations by traceId / sessionId. Both label their output as derived. A trace's "name" is inferred from its earliest observation.
• Content requires field groups. /v2/observations returns only core and basic fields by default — no input, output, usage, or model. The script requests fields=core,basic,time,io,metadata,model,usage,prompt where content matters. A port that forgets this silently returns metadata only.
• Input/output are always raw strings. parseIoAsJson=true is deprecated and returns 400. The script decodes JSON-looking strings client-side.

Pagination

v4 pagination is cursor-based (meta.cursor), not page-numbered — passing page=N is silently ignored and returns the same rows. The script walks the cursor transparently, so commands return the complete set rather than one page.

Walks are bounded by LANGFUSE_MAX_RECORDS (default 2000) so a busy project can't trigger an unbounded crawl. When the cap is hit the script says so on stderr and tells you what to raise:

note: stopped at the 2000-record cap after 20 pages; raise LANGFUSE_MAX_RECORDS for more

LANGFUSE_MAX_RECORDS=10000 langfuse_query.sh trace <trace-id>

1. Querying Langfuse Data

# List recent traces
langfuse_query.sh traces --limit 5
langfuse_query.sh traces --name my-trace-name --limit 10
langfuse_query.sh traces --session-id abc123 --limit 10

# Get a full trace with all observations
langfuse_query.sh trace <trace-id>

# Show LLM generations and tool calls for a trace (most common debugging task)
langfuse_query.sh generations <trace-id>

# List observations for a trace, optionally filtered by type
langfuse_query.sh observations <trace-id> --type GENERATION

# Get a single observation with full detail (raw JSON)
langfuse_query.sh observation <obs-id>

# Sessions, scores, prompts
langfuse_query.sh sessions --limit 5
langfuse_query.sh scores --trace-id <trace-id>
langfuse_query.sh prompts

# Which API generation am I on?
langfuse_query.sh apigen

Common Workflows

Check what the LLM actually received and returned:

langfuse_query.sh traces --limit 3        # find the trace
langfuse_query.sh generations <trace-id>  # model, prompt name+version, tokens, input, output

On v4 this also shows the linked prompt (promptName / promptVersion), which is the fastest way to confirm which prompt version produced a given output.

Review a full trace end-to-end:

langfuse_query.sh trace <trace-id>

Shows trace metadata plus a chronological list of all observations with tool calls and token counts.

Inspect token usage and cost:

langfuse_query.sh generations <trace-id>

Get raw JSON for one observation (full untruncated input/output):

langfuse_query.sh observation <obs-id>

Troubleshooting

• 404s on every command — you are on a v4 server but detection returned legacy (or vice versa). Check langfuse_query.sh apigen and force with LANGFUSE_API_GEN.
• Generations show no input/output — the observation genuinely has none, or you are calling the API directly without fields=...,io.
• traces shows fewer traces than expected on v4 — the walk stopped at LANGFUSE_MAX_RECORDS. The script prints a note on stderr when that happens; raise it and re-run.
• A command is slow on v4 — it is paging. Each page is 100 observations, so a 2000-record trace costs 20 round trips. Narrow with --type where you can.

2. Langfuse Documentation

Three methods to access Langfuse docs, in order of preference. Always prefer your application's native web fetch and search tools (e.g., WebFetch, WebSearch) over curl when available.

2a. Documentation Index (llms.txt)

curl -s https://langfuse.com/llms.txt

Returns a structured list of every doc page with titles and URLs. Use this to discover the right page for a topic, then fetch that page directly.

2b. Fetch Individual Pages as Markdown

Any page listed in llms.txt can be fetched as markdown by appending .md:

curl -s "https://langfuse.com/docs/observability/overview.md"

2c. Search Documentation

curl -s "https://langfuse.com/api/search-docs?query=How+do+I+trace+LangGraph+agents"

Instance API spec

A self-hosted instance serves its own OpenAPI spec, which is authoritative for that exact version — more reliable than the docs site when endpoints have moved:

curl -s "$LANGFUSE_BASE_URL/generated/api/openapi.yml"