OMP ⇄ Langfuse Telemetry

Superseded runtime guide: active telemetry is ompfuse; ~/.omp/agent/extensions/langfuse.ts is a gated legacy fallback. Token usage finalizes on message_end, not after_provider_response.

This page is retained as historical architecture context. Do not use it as a setup guide.

🚀 Quick Start & Integration

The Langfuse extension provides zero-dependency, non-blocking telemetry for Oh My Pi (OMP) sessions. It relies entirely on Bun-native fetch and crypto.randomUUID().

Activation Environment Variables:

export LANGFUSE_PUBLIC_KEY="pk-lf-***"
export LANGFUSE_SECRET_KEY="sk-lf-***"
export LANGFUSE_HOST="https://cloud.langfuse.com"

🧠 Trace Architecture & Lifecycle

The telemetry extension maps the native OMP event loop to Langfuse’s hierarchical trace structures.

graph TD
    S["Session (trace-create)"] -->|"starts"| T["Turn (span-create)"]
    T -->|"yields"| LLM["LLM Call (generation-create)"]
    T -->|"invokes"| Tool["Tool Call (span-create)"]
    T -->|"triggers"| Comp["Compaction (span-create)"]
    S -->|"ends"| S_End["Session Shutdown (trace-update)"]
    
    style S fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style T fill:#2b6cb0,stroke:#2c5282,stroke-width:2px,color:#fff
    style LLM fill:#48bb78,stroke:#2f855a,stroke-width:2px,color:#fff
    style Tool fill:#ed8936,stroke:#c05621,stroke-width:2px,color:#fff
    style Comp fill:#9f7aea,stroke:#6b46c1,stroke-width:2px,color:#fff
    style S_End fill:#e53e3e,stroke:#9b2c2c,stroke-width:2px,color:#fff

Event Mapping Dictionary

• Session: session_start ➔ session_shutdown (Captures total turns).
• Turns: turn_start ➔ turn_end (Captures duration, context tokens, usage %).
• LLM Generations: before_provider_request ➔ message_end (final output, token usage, cache, cost, stop reason); use after_provider_response for transport errors only.
• Tool Spans: tool_call ➔ tool_result (Captures sanitized I/O, duration, error state).
• Annotations: session_compact, auto_retry_start, ttsr_triggered, goal_updated (Renames trace to active objective).

🚨 Gotchas, Traps & Safeguards

Trap	Risk	Enforced Fix / Invariant
Payload Limits	Langfuse rejects batches > 3.5MB.	Aggressively deep-truncates I/O to 64k-250k chars. Omits base64 images entirely.
Secret Leakage	Tokens in prompts sent to cloud.	Auto-redacts regex-matched standard tokens + dynamic runtime ENV variables matching secret patterns.
Event Loop Hangs	Network failure crashes OMP.	Batched async flushes strictly bounded by a 10s AbortSignal timeout.
Extension Crashes	Uncaught exceptions kill process.	All event hooks wrapped in safeOn try-catch blocks.

🔧 Configuration Reference

Variable	Description	Default
LANGFUSE_FLUSH_MS	Batch flush interval in milliseconds	2000
LANGFUSE_MAX_QUEUE	Max queued events before forced flush	500
LANGFUSE_SAMPLE_RATE	0.0-1.0 fraction of sessions to trace	1.0
LANGFUSE_TAGS	Comma-separated extra tags (e.g., prod)	""
LANGFUSE_DEBUG	Set to "1" to log flush diagnostics	"0"
LANGFUSE_UI_INDICATOR	Enable OMP UI tracing indicator	true