Skip to main content

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.

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 fieldRequiredDefaultDescription
public_keyyesLangfuse project public key
secret_keyyesLangfuse project secret key
hostnohttps://cloud.langfuse.comLangfuse API host URL
default_trace_limitno100Default trace/observation cap for listings
default_search_limitno50Default 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

CommandLimit behavior
ls traces/Returns up to default_trace_limit traces
cat traces/<id>.jsonFull 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

CommandNotes
lsList traces, sessions, prompts, datasets
catRead trace JSON, prompt version, dataset items
head / tailPaginated trace listing with sort
grep / rgSmart: uses Langfuse filter API at directory scope
jqQuery JSON trace/prompt data
statMetadata (trace count, prompt versions, dataset items)
findSearch across resources with -name
treeDirectory tree view