Investigate: propagate Langfuse session/user to LiteLLM's agent-completion traces

[sheepdestroyer]

Context

When the triage router propagates session_id and user_id via Langfuse's propagate_attributes(), only the litellm-proxy trace (created by LiteLLM's proxy layer) inherits these attributes. The agent-completion trace (created by LiteLLM's internal LLM call instrumentation) does not — it appears as a separate trace with sessionId: null.

This was observed during PR #302 verification:

• Session-bearing request → litellm-proxy trace gets sessionId=e2e-verify-*, userId=verify-script
• Same request → agent-completion trace gets sessionId=None, userId=None

Why this matters

The agent-completion trace is where actual token usage, latency, and model metadata live. Without session context there, session-scoped Langfuse dashboards, cost-tracking, and user-level analytics are incomplete — you can see the proxy hop but not the actual model call.

Root cause

LiteLLM creates agent-completion as a separate trace (not an observation within our parent trace). Langfuse's propagate_attributes sets context on the current OpenTelemetry span; LiteLLM's internal agent-completion span lives in a different trace tree and doesn't inherit.

What to investigate

1. Use cases: Which Langfuse features break without session on agent-completion? (session-scoped dashboards, per-user cost reports, trace-linking in UI)
2. Benefits: What would full session propagation across both litellm-proxy AND agent-completion enable?
3. Implementation options (ranked by feasibility):
   • A) LiteLLM config: Does LiteLLM's langfuse config section support a session_id parameter that would be forwarded to backend traces?
   • B) Trace header forwarding: Pass X-Langfuse-Trace-Id + X-Langfuse-Session-Id headers through LiteLLM to the backend provider — does LiteLLM respect these?
   • C) LiteLLM callback: Can a LiteLLM success_callback or failure_callback patch the agent-completion trace's session after creation?
   • D) OpenTelemetry context propagation: Wire our parent trace's OTel context into LiteLLM's trace provider so child traces share context
4. Sibling trace linking: If full propagation isn't feasible, can we at least link agent-completion traces to our session-bearing traces so Langfuse UI shows them together?

Affected components

• router/main.py — chat_completions (session_id/user_id extraction + propagate_attributes)
• LiteLLM's Langfuse integration (external, version-dependent)
• Langfuse UI session views, cost dashboards

Requirements

• Research LiteLLM's Langfuse session support across versions
• Test each implementation option in dev
• Document chosen approach and trade-offs
• Update PR fix: always exit propagate_attributes context manager to prevent session leak #302 verification script once fixed

[sheepdestroyer]

Investigation Results

Confirmed

E2E verified on dev: agent-completion traces consistently have sessionId=None while litellm-proxy traces correctly receive sessionId. Tested with session_id=e2e-issue303-*, user=issue303-verify.

Root Cause

propagate_attributes() sets Langfuse session/user on the current OpenTelemetry span. litellm-proxy runs within that OTel context and inherits the attributes. However, LiteLLM creates agent-completion as a separate trace in a different OTel trace tree — it doesn't inherit the propagated context.

Solution

LiteLLM's Langfuse integration reads session_id and trace_user_id directly from the request metadata dict, independent of OTel context propagation. We already set metadata["trace_name"] = "agent-completion" — we just need to add these two fields.

Changes (2 locations in router/main.py)

1. Metadata propagation — add session_id and trace_user_id alongside existing trace_name:

   body_to_send["metadata"]["trace_name"] = "agent-completion"
   if _trace_session_id:
       body_to_send["metadata"]["session_id"] = _trace_session_id
   if _trace_user_id:
       body_to_send["metadata"]["trace_user_id"] = _trace_user_id

2. Header propagation — add langfuse_session_id and langfuse_trace_user_id headers alongside existing X-Langfuse-Trace-Id for belt-and-suspenders coverage.

Both changes apply to streaming and non-streaming paths since they share the same body_to_send construction block.

Why not the other options?

• Option C (callback): Overkill — success_callback patching traces post-creation adds complexity without benefit.
• Option D (OTel context propagation): Already tried via propagate_attributes() — works for litellm-proxy but cannot reach separate trace trees.
• Option B (headers only): Works but metadata approach is more direct and is already the established pattern (we already use metadata for trace_name).
• existing_trace_id (linking agent-completion into parent trace): Undesirable — changes trace topology fundamentally; we already have litellm-proxy as the child observation.

Reference

LiteLLM Langfuse Integration docs confirm session_id and trace_user_id in metadata are read by Langfuse callback: https://docs.litellm.ai/docs/observability/langfuse_integration