Langfuse Tracing Guide ⚡

Superseded runtime guide: use SSOT ompfuse. The local langfuse.ts remains a gated fallback only; do not enable both exporters.

---

Historical snapshot

The former standalone exporter is preserved only for incident comparison. Current credentials and setup belong to ompfuse in SSOT; it finalizes token usage on message_end and tracks subagents on the same trace tree.

---

🏗️ Architecture

graph TB
    subgraph OMP["OMP Runtime (Bun)"]
        subgraph Ext["langfuse.ts extension"]
            Events["Events<br>(pi.on)"]
            Queue["Queue<br>(batch)"]
            Post["POST /ingestion<br>(2s / 500 cap)"]

            Events --> Queue
            Queue --> Post
        end
    end

    Server[Langfuse Server]

    Post -->|HTTP| Server

    style OMP fill:#f9f9f9,stroke:#333,stroke-width:2px
    style Ext fill:#e1f5fe,stroke:#0288d1,stroke-width:1.5px
    style Events fill:#fff,stroke:#333
    style Queue fill:#fff,stroke:#333
    style Post fill:#fff,stroke:#333
    style Server fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

Key design decisions:

• 📨 Batched — events queue in memory, flush every 2s or at 500 events
• 🔗 Ordered — flushes chain via promise to preserve event sequence
• 🛡️ Fail-open — all handlers wrapped in safeOn() try-catch + sendBatch try-catch; errors logged, never crash OMP
• ⏱️ 10s timeout — slow Langfuse server can’t hang your session
• 🏁 Graceful shutdown — final flush is awaited before process exits
• 🔒 Type-safe — all event properties coerced with String()/Number() before use; no unsafe as casts

---

📊 What Gets Traced

OMP Event	→ Langfuse	Data Captured
🎬 session_start	Trace omp-session	cwd, model, hostname, tags, userId (profile)
🏁 session_shutdown	Trace update	turn count summary
🔄 turn_start/end	Span turn	duration (ms), context tokens, context %
🧠 before_provider_request	Generation llm-call	model, provider, prompt input (redacted + 15k truncated)
🧠 message_end	Generation complete	final output, tokens (in/out), cache stats, cost, latency, stop reason
🔧 tool_call	Span tool:<name>	input (redacted + truncated)
🔧 tool_result	Span update	output (redacted + 4k), duration, error level
🤖 agent_start/end	Span agent:<type>	subagent type, model, nesting hierarchy, duration
📦 session_compact	Span compaction	summary, tokens before
⚠️ auto_retry_start	Span auto-retry	reason, attempt (WARNING level)
📏 ttsr_triggered	Span ttsr-injection	injected rule names
🎯 goal_updated	Trace update	session title → trace name

---

Historical configuration

Legacy environment variables are intentionally not documented here. Configure the active package through ompfuse in SSOT.

---

🏷️ Langfuse Dashboard Tips

Filtering traces

• Tag omp — always present on every trace
• Tag provider:<name> — filter by LLM provider (anthropic, google, etc.)
• Tag model:<name> — filter by model (claude-opus-4, gemini-pro, etc.)
• Custom tags via LANGFUSE_TAGS=prod,gpu-node → tags prod, gpu-node

Understanding the trace tree

graph TD
    %% Define Styles
    classDef session style fill:#1f77b4,stroke:#115588,stroke-width:2px,color:#fff;
    classDef turn style fill:#aec7e8,stroke:#1f77b4,stroke-width:1.5px,color:#000;
    classDef leaf style fill:#f7f7f7,stroke:#ccc,stroke-width:1px,color:#333;
    classDef warning fill:#ffbb78,stroke:#ff7f0e,stroke-dasharray: 5 5,stroke-width:2px,color:#000;
    classDef system style fill:#c7c7c7,stroke:#7f7f7f,stroke-width:1px,color:#000;

    %% Nodes
    Session["omp-session (Trace)<br/><i>1 per OMP session</i>"]:::session

    Turn1["turn (Span)<br/><i>1 per user↔agent exchange</i>"]:::turn
    Turn2["turn (Span)"]:::turn
    Compaction["compaction (Span)<br/><i>context window compacted</i>"]:::system
    AutoRetry["⚠️ auto-retry (Span)<br/><i>WARNING level</i>"]:::warning
    Ttsr["ttsr-injection (Span)<br/><i>rule injection event</i>"]:::system

    %% Children of Turn 1
    LLM1["llm-call (Generation)<br/><i>model request/response + tokens</i>"]:::leaf
    Read["tool:read (Span)<br/><i>tool with I/O</i>"]:::leaf
    Edit["tool:edit (Span)<br/><i>another tool</i>"]:::leaf
    Bash["tool:bash (Span)<br/><i>...</i>"]:::leaf
    AgentTask["agent:task (Span)<br/><i>subagent spawn</i>"]:::leaf

    %% Children of Turn 2
    LLM2["llm-call (Generation)"]:::leaf
    Search["tool:search (Span)"]:::leaf

    %% Hierarchy Connections
    Session --> Turn1
    Session --> Turn2
    Session --> Compaction
    Session --> AutoRetry
    Session --> Ttsr

    Turn1 --> LLM1
    Turn1 --> Read
    Turn1 --> Edit
    Turn1 --> Bash
    Turn1 --> AgentTask

    Turn2 --> LLM2
    Turn2 --> Search

Key metadata fields

• durationMs — on generations + tools + turns
• contextTokens / contextPct — on turns (how full is the context window?)
• cacheRead / cacheWrite — on generations (prompt cache hits)
• totalCost — on generations (if provider reports cost)
• stopReason — on generations (stop, length, toolUse, error)
• hostname — on trace (which machine ran this session)

---

🔒 Security

Concern	Protection
🔑 API keys & credentials	Auto-redacted by regex before sending across all channels (LLM prompts, completions, and tool inputs/outputs). Matches both key-value pairs (api_key, secret, etc.) and raw keys (ghp_, sk-proj-, sk-lf-, sk-ant-, AIzaSy-).
🖼️ Base64 images	Stripped entirely → [base64 image omitted]
✂️ Large payloads	Deep-truncated: LLM I/O → 15k, tool I/O → 8k/4k, summaries → 5k (performed after redaction to avoid leaking pattern prefixes)
🔐 Auth to Langfuse	Basic Auth header from env vars (never logged)
📏 Batch limit	Langfuse’s 3.5 MB limit respected via truncation + queue cap

---

Historical troubleshooting

Diagnose the active exporter with the ompfuse SSOT. The only legacy decision is whether its explicit compatibility gate is enabled; never run both exporters.

---

🔮 Langfuse API Reference (what the extension uses)

Endpoint	Method	Auth	Purpose
/api/public/ingestion	POST	Basic (pk:sk)	Batch event ingestion

Event types sent

Type	When
trace-create	Session start, goal change, session end (upsert)
generation-create	LLM request start
generation-update	LLM response received
span-create	Turn/tool/agent/compaction/retry/ttsr start
span-update	Turn/tool end

---

📝 Changelog

2026-06-20 — 100% Perfection Refinement, Raw Token Redaction & Robust Telemetry Redaction

Security & Secret Redaction Hardening:

• 🔒 Unified & Structural Secret Redaction — Applied redactSecrets() consistently to all telemetry vectors (LLM prompt inputs, LLM completion outputs, and tool output text previews) before payload truncation. Implemented JSON-parsing inside redactSecrets() to detect and recursively redact stringified JSON payloads structurally, preventing regex escapes and ensuring robust schema-aware key redaction.
• 🔑 Raw Token Pattern Detection — Implemented RAW_TOKEN_PATTERN to scan and redact raw API keys/tokens (ghp_, github_pat_, sk-lf-, pk-lf-, sk-ant-, sk-proj-, sk-, AIzaSy) across all string payloads, preventing token leakage even without key-value prefix anchors.
• 🧪 Dynamic Environment Secrets Collection — Added code to dynamically scan and harvest secrets from the environment (process.env) on initialization, filtering for values >= 8 characters. Deduplicated and sorted these needles by length descending to prevent substring redaction collisions.
• 🗃️ Deep Metadata Redaction & Safety — Enforced redactSecrets() across all trace and span metadata blocks (including error messages, environment dumps, model configurations, and process telemetry). Implemented optional chaining and explicit null-pointer guards inside metadata mapping and array filters, eliminating potential runtime TypeError crashes on malformed payload inputs.

Subagent Nesting & Out-of-Scope Architecture:

• 🕸️ OTel-based Subagent Nesting Path — Identified that OMP runs subagents in-process sharing global process state (rather than isolated OS child processes). Thus, ad-hoc process.env mutations for trace propagation bleed and race on concurrent executions. Consequently, subagent span nesting has been declared out-of-scope for this event-based extension. Users requiring recursive multi-agent tracing should configure OMP’s native OpenTelemetry (OTel) OTLP exporter to Langfuse’s OTLP endpoint for correct, race-free trace hierarchies.

Tool Output Preview Hardening:

• 🔧 Support for Raw String & Custom Tool Outputs — Expanded the tool_result event handler to support raw string content and fallback stringification of non-string and non-array custom tool results (objects, numeric stats, booleans), ensuring custom tool outputs are properly captured and redacted in Langfuse.

2026-06-11 — Architectural Improvements, Subagent Nesting & UI Configs

Subagent Nesting & Developer Profiles:

• 🤖 Subagent Span Closing — Added agent_end hook listener to cleanly close subagent execution spans. Implemented activeAgents stack to track nested subagent calls (e.g. task calling plan) to correctly reconstruct parent-child execution graphs.
• 👤 Developer Profiles (userId) — Added OS user/username metadata capture (process.env.USER) as userId to traces, enabling trace filtering by developer profile.

Bug Fixes & Config Enhancements:

• 🐛 trace-update rejected by Langfuse API — The Ingestion API does not support trace-update events, returning HTTP 400. Corrected to trace-create events which Langfuse handles as upserts (updates/inserts) on existing id matches.
• 🐛 [object Object] tags & model names — When ctx.model or event.model is an object at runtime, String(model) coercion produced "model:[object Object]". Added robust object-to-string extraction of the model id or name field.
• 🛡️ JSON secrets redaction bypass — Tool input secrets in JSON/object keys (like { api_key: "value" }) bypassed the regex-based redactSecrets() due to missing separator matches on object keys. Added KEY_REDACT_PATTERN to correctly match and redact secret fields in object schemas.
• ⚙️ LANGFUSE_UI_INDICATOR — Introduced a dedicated env toggle to control the TUI status line tracing indicator, decoupled from verbose debug logging.

2026-06-10 — Robustness Hardening

Bug Fix:

• 🐛 model.split is not a function — ctx.model / event.model can be a non-string truthy value at runtime (object, number). Fixed by coercing with String() in buildTags() (line 237), before_provider_request (line 362–363), and after_provider_response (line 414).

Hardening:

• 🛡️ Fail-open handlers — all 13 event handlers now wrapped via safeOn() with try-catch; a thrown error in any handler is logged and swallowed, never crashes OMP.
• 🛡️ sendBatch try-catch — JSON.stringify failures and uncaught fetch errors now caught inside sendBatch(), preventing chain breakage.
• 🔢 Token coercion — usage.input/output/cacheRead/cacheWrite now coerced via Number() || 0 to handle string or undefined values.
• ⏱️ Consistent timestamps — agent_start handler now captures iso() once and reuses for both timestamp and startTime (was calling iso() twice, producing skewed values).
• 🏷️ Agent name coercion — agent_start span name ev.agentType coerced via String() to prevent [object Object] tags.
• 📐 buildTags signature — parameter types widened from string to unknown to match actual runtime event shapes.

---

🧩 Langfuse Agent Skills (langfuse/skills)

Repo: github.com/langfuse/skills — MIT · 160+ ⭐

Official Agent Skills that teach AI coding assistants (Claude Code, Cursor, etc.) how to work with Langfuse. Separate from the OMP extension above — these are agent-side skills for instrumentation, prompt management, and data access.

Available Skills

Skill	Description
langfuse	Query/manage traces, prompts, datasets, scores via API; documentation lookup; best-practice workflows

Installation

# Cursor Plugin
/add-plugin langfuse
 
# Skills CLI (no install required)
npx skills add langfuse/skills --skill "langfuse"
 
# Manual symlink
git clone https://github.com/langfuse/skills.git /path/to/langfuse-skills
ln -s /path/to/langfuse-skills/skills/langfuse /path/to/skills-directory/langfuse

Core Capabilities

1. CLI Data Access — npx langfuse-cli api __schema to discover resources; list/get any API entity (traces, prompts, datasets, scores, sessions)
2. Documentation Access — langfuse.com/llms.txt (full page index), append .md to any page path, or search via /api/search-docs?query=...
3. Use-case References — built-in guides for: instrumentation, prompt migration, user feedback capture, SDK upgrades, judge calibration, error analysis, CI/CD experiment gates

Prerequisites

These credentials configure Langfuse skills and the active ompfuse package:

export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://cloud.langfuse.com  # or us.cloud.langfuse.com / self-hosted

Auto-Allowed Tools

The skill auto-grants these (read-only, Langfuse-scoped):

• WebFetch(domain:langfuse.com)
• Bash(npx langfuse-cli api __schema/list/get/--help ...)

Plugin Manifests

Ships as plugins to two marketplaces (.claude-plugin/plugin.json + .cursor-plugin/plugin.json), versioned with semver and kept in lockstep.