> ## 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 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 theme={null} 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 theme={null} /langfuse/ traces/ .json ... sessions/ / .json ... prompts/ / .json ... datasets/ / items.jsonl runs/ .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`). 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 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 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/.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 theme={null} 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 |