Graph View

OMP ⇆ Langfuse Telemetry

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

1. Historical snapshot

This archived page describes the former zero-dependency exporter. Configure ompfuse in SSOT instead; never run the legacy and package exporters together.

2. 🧠 Architecture

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,color:#fff
    style T fill:#2b6cb0,stroke:#2c5282,color:#fff
    style LLM fill:#48bb78,stroke:#2f855a,color:#fff
    style Tool fill:#ed8936,stroke:#c05621,color:#fff
    style Comp fill:#9f7aea,stroke:#7638c1,color:#fff
    style S_End fill:#e53e3e,stroke:#9b2c2c,color:#fff

1. 🗺️ Event Map

  • 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 for final usage/output; 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).

3. 🚨 Gotchas

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

4. 🔧 Configuration

VariableDescriptionDefault
LANGFUSE_FLUSH_MSBatch flush interval in milliseconds2000
LANGFUSE_MAX_QUEUEMax queued events before forced flush500
LANGFUSE_SAMPLE_RATE0.0-1.0 fraction of sessions to trace1.0
LANGFUSE_TAGSComma-separated extra tags (e.g., prod)""
LANGFUSE_DEBUGSet to "1" to log flush diagnostics"0"
LANGFUSE_UI_INDICATOREnable OMP UI tracing indicatortrue

Contents

1 item under this folder.

Properties2
descriptionA guide to integrating zero-dependency Langfuse telemetry for Oh My Pi (OMP) sessions.
tagsomp, langfuse, telemetry, integration