Langfuse Observability 🔍

Mission: Zero-fluff, high-density, idiot-proof tracing & observability in Oh My Pi (OMP) / Quartz.

🧠 Architectural Invariants

• API Standard: Langfuse v3/v4+. Use @observe directly. NEVER use legacy langfuse_context properties.
• Async Continuity: Trace contexts (traceId, parentObservationId) MUST explicitly span async boundaries to render nested flame graphs.
• Payload Limits: 3.5MB hard cap. Shard massive payloads via sequential .update_current_span() calls; never blindly truncate.

---

🔧 Core Implementation Patterns

1. Synchronous Decorator Tracing

from langfuse.decorators import observe, langfuse_context
 
@observe()
def master_task(input_data: dict):
    # Dynamically inject metadata into the active span
    langfuse_context.update_current_span(
        metadata={"user_tier": "god-level"},
        tags=["critical-path"]
    )
    return process(input_data)

2. Parallel / Swarm Trace Propagation

from langfuse.decorators import observe, langfuse_context
 
@observe()
def orchestrate_swarm(tasks: list):
    trace_id = langfuse_context.get_current_trace_id()
    parent_id = langfuse_context.get_current_observation_id()
 
    # 🚨 CRITICAL: Pass IDs to maintain the flame graph in parallel workers
    return parallel([
        lambda t=t: worker_node(t, trace_id, parent_id)
        for t in tasks
    ])

---

🚨 Gotchas, Traps & Fatal Errors

• ❌ Broken Flame Graphs: Occur when parentObservationId is lost across thread boundaries. Always inject context manually for threaded/parallel executions.
• ❌ Span Crashes: Sending >3.5MB in one payload crashes the trace. Chunk data using update_current_generation().
• ❌ Event Hook Clobbering (OMP): Tracking LLM generations using ev.agentId as a Map key causes state clobbering. Always use generation-specific keys like ev.id or ev.messageId.

---

💡 Masterful Best Practices

• Auto-Capture: Wrap every core agent step, eval iteration, and sub-agent handoff in @observe.
• Dynamic Updates: Use .update_current_generation() inside the function once the outcome is fully resolved rather than pre-defining static metadata.
• Idiot-Proof Validations: Build MapReduce verification loops to auto-audit trace findings dynamically (e.g. Adversarial Verification rounds).