strukto-ai--mirage/docs/python/resource/langfuse.mdx

---
title: Langfuse
description: Mount Langfuse traces, observations, prompts, datasets, and scores as a Mirage virtual filesystem.
icon: chart-line
---
The Langfuse resource 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](/python/setup/langfuse).

## Config

```python
import os

from mirage import MountMode, Workspace
from mirage.resource.langfuse import LangfuseConfig, LangfuseResource

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"),
)
resource = LangfuseResource(config=config)
ws = Workspace({"/langfuse": resource}, 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
/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
/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`).
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
# 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 resource 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
# 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 resource uses `IndexCacheStore` (same as other resources).
Index entries store trace IDs, session IDs, and prompt names.

## Example

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.langfuse import LangfuseConfig, LangfuseResource

load_dotenv(".env.development")

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


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

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

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

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

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

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

    # List datasets
    r = await ws.execute("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                                    |