Langfuse - Mirage

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.

Config

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

/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:

/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

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

# 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

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

​Config

​Filesystem Layout

​Traces

​Sessions

​Prompts

​Datasets

​Smart Commands

​grep at different scopes

​head / tail

​Limits

​Cache

​Example

​Shell Commands