> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Langfuse

> Mount Langfuse traces, observations, prompts, datasets, and scores as a Mirage virtual filesystem.

The Langfuse VFS exposes LLM observability data (traces, observations,
prompts, datasets, scores) as a virtual filesystem mounted at some prefix
such as `/langfuse/`.

For credential setup, see [Langfuse Setup](/home/setup/langfuse).

## Config

```python theme={null}
import os

from mirage import MountMode, Workspace
from mirage.vfs.langfuse import LangfuseConfig, LangfuseVFS

config = LangfuseConfig(
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
    host=os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"),
)
vfs = LangfuseVFS(config=config)
ws = Workspace({"/langfuse": vfs}, mode=MountMode.READ)
```

| Config field | Required | Default | Description |
| - | - | - | - |
| `public_key` | yes | | Langfuse project public key |
| `secret_key` | yes | | Langfuse project secret key |
| `host` | no | `https://cloud.langfuse.com` | Langfuse API host URL |
| `default_trace_limit` | no | 100 | Default trace/observation cap for listings |
| `default_search_limit` | no | 50 | Default result cap for search at directory scope |

## Filesystem Layout

```text theme={null}
/langfuse/
  traces/
    <trace-id>.json
    ...
  sessions/
    <session-id>/
      <trace-id>.json
      ...
  prompts/
    <prompt-name>/
      <version>.json
      ...
  datasets/
    <dataset-name>/
      items.jsonl
      runs/
        <run-name>.jsonl
        ...
```

Example:

```text theme={null}
/langfuse/
  traces/
    abc123.json
    def456.json
  sessions/
    chat-session-1/
      abc123.json
      ghi789.json
  prompts/
    summarize/
      1.json
      2.json
    classify/
      1.json
  datasets/
    eval-v1/
      items.jsonl
      runs/
        run-2026-04-01.jsonl
```

### Traces

`/langfuse/traces/` lists recent traces (capped at `default_trace_limit`,
from `default_from_timestamp` on). The cap bounds the listing, not the tree:
`stat` and `cat` still reach an older trace by its id, and `sessions/<id>/`
serves only that session's traces.
Each trace is a `.json` file containing the full trace object with nested
observations (spans, generations, events).

### Sessions

`/langfuse/sessions/` groups traces by session ID. Each session directory
contains trace `.json` files belonging to that session.

### Prompts

`/langfuse/prompts/` lists prompt names as directories. Each prompt directory
contains version files (`1.json`, `2.json`, etc.) with the prompt content
and metadata.

### Datasets

`/langfuse/datasets/` lists dataset names as directories. Each contains
`items.jsonl` (dataset items) and `runs/` with run results.

## Smart Commands

### grep at different scopes

```bash theme={null}
# FILE level - downloads the file, greps locally
grep "error" "/langfuse/traces/abc123.json"

# TRACES level - uses Langfuse trace filter API (name, tags, metadata)
grep "error" "/langfuse/traces/"

# SESSIONS level - uses Langfuse session listing
grep "chat" "/langfuse/sessions/"

# PROMPTS level - filters prompt names
grep "classify" "/langfuse/prompts/"

# ROOT level - searches across all resource types
grep "error" "/langfuse/"
```

At directory scope, the VFS uses Langfuse's filter API instead of
downloading data:

* **traces/**: filters by trace name, user ID, or tags
* **sessions/**: filters by session listing
* **prompts/**: filters by prompt name

### head / tail

`head` and `tail` on `traces/` use Langfuse API pagination with sort order
instead of downloading all traces:

```bash theme={null}
# Returns 10 most recent traces
head -n 10 "/langfuse/traces/"

# Returns 10 oldest traces
tail -n 10 "/langfuse/traces/"
```

## Limits

| Command | Limit behavior |
| - | - |
| `ls traces/` | Returns up to `default_trace_limit` traces |
| `cat traces/<id>.json` | Full trace (single doc, no limit needed) |
| `grep` (directory level) | Server-side filter, capped at `default_search_limit` |
| `wc -l traces/` | Not supported (Langfuse has no count endpoint) |

## Cache

The Langfuse VFS uses `IndexCacheStore` (same as other mounts).
Index entries store trace IDs, session IDs, and prompt names.

## Example

```python theme={null}
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.vfs.langfuse import LangfuseConfig, LangfuseVFS

load_dotenv(".env.development")

config = LangfuseConfig(
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
)
vfs = LangfuseVFS(config=config)


async def main():
    ws = Workspace({"/langfuse": vfs}, mode=MountMode.READ)

    # List top-level resources
    r = await ws.shell("ls /langfuse/")
    print(await r.stdout_str())

    # List recent traces
    r = await ws.shell("ls /langfuse/traces/")
    print(await r.stdout_str())

    # Read a specific trace
    traces = r.stdout_str().strip().splitlines()
    if traces:
        r = await ws.shell(f'cat "/langfuse/traces/{traces[0]}"')
        print(r.stdout_str()[:500])

    # List prompts
    r = await ws.shell("ls /langfuse/prompts/")
    print(await r.stdout_str())

    # Search traces (uses Langfuse filter API)
    r = await ws.shell('grep "error" "/langfuse/traces/"')
    print(await r.stdout_str())

    # List datasets
    r = await ws.shell("ls /langfuse/datasets/")
    print(await r.stdout_str())



if __name__ == "__main__":
    asyncio.run(main())
```

## Shell Commands

| Command | Notes |
| - | - |
| `ls` | List traces, sessions, prompts, datasets |
| `cat` | Read trace JSON, prompt version, dataset items |
| `head` / `tail` | Paginated trace listing with sort |
| `grep` / `rg` | Smart: uses Langfuse filter API at directory scope |
| `jq` | Query JSON trace/prompt data |
| `stat` | Metadata (trace count, prompt versions, dataset items) |
| `find` | Search across resources with `-name` |
| `tree` | Directory tree view |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.