# Langfuse

> Interact with Langfuse and access its documentation. Use when needing to (1) query or modify Langfuse data programmatically — traces, prompts, scores, sessions, observations, (2) look up Langfuse documentation, concepts, integration guides, or SDK usage, or (3) understand how any Langfuse feature works. Works against self-hosted and cloud Langfuse, on both the legacy v1 REST API (server major <=…

- **Type:** Skill
- **Install:** `agentstack add skill-lunarcommand-claude-skills-langfuse`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [LunarCommand](https://agentstack.voostack.com/s/lunarcommand)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [LunarCommand](https://github.com/LunarCommand)
- **Source:** https://github.com/LunarCommand/claude-skills/tree/main/skills/langfuse

## Install

```sh
agentstack add skill-lunarcommand-claude-skills-langfuse
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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: `
(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:

| | **legacy** (server ≤ 3) | **v4** (server ≥ 4) |
|---|---|---|
| Traces | `/traces`, `/traces/{id}` | **gone (404)** — derived from observations |
| Observations | `/observations`, `/observations/{id}` | `/v2/observations` (+ structured `filter` for a single id) |
| Sessions | `/sessions` | **gone (404)** — derived from observations |
| Scores | `/scores` | `/v3/scores` |
| Prompts | `/v2/prompts` | `/v2/prompts` (unchanged) |

Check what you're talking to:

```bash
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
```

```bash
LANGFUSE_MAX_RECORDS=10000 langfuse_query.sh trace 
```

## 1. Querying Langfuse Data

```bash
# 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 

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

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

# Get a single observation with full detail (raw JSON)
langfuse_query.sh observation 

# Sessions, scores, prompts
langfuse_query.sh sessions --limit 5
langfuse_query.sh scores --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:**
```bash
langfuse_query.sh traces --limit 3        # find the trace
langfuse_query.sh generations   # 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:**
```bash
langfuse_query.sh trace 
```
Shows trace metadata plus a chronological list of all observations with tool
calls and token counts.

**Inspect token usage and cost:**
```bash
langfuse_query.sh generations 
```

**Get raw JSON for one observation** (full untruncated input/output):
```bash
langfuse_query.sh observation 
```

### 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)

```bash
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`:

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

### 2c. Search Documentation

```bash
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:

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LunarCommand](https://github.com/LunarCommand)
- **Source:** [LunarCommand/claude-skills](https://github.com/LunarCommand/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lunarcommand-claude-skills-langfuse
- Seller: https://agentstack.voostack.com/s/lunarcommand
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.