Spot the bug when Langfuse traces from a short lived script never appear in the dashboard
The script exited before the SDK's background batch shipped. Call langfuse.flush() before exit; serverless handlers need the same fix.
Picture mailing letters from a hotel. You drop your letters into a basket at the front desk. The hotel collects baskets every hour and walks them to the post office. If you check out and leave the hotel five minutes after dropping your letters, the next pickup never happens for your batch and your letters sit there forever. The fix is asking the front desk to hand-carry your letters out before you leave. The Langfuse SDK does the same kind of batching. It collects records in memory and flushes them on a timer so your app stays fast. A short script that does its work and immediately exits beats the timer and the batch goes nowhere. Telling the SDK to flush before exit is the hand-carry step.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
This bug shows up in roughly half of teams' first month with Langfuse and is one of the easiest production failures to mis-diagnose. The script ran. The exit code was zero. The LLM call returned. Everything looks fine, and nothing showed up in the dashboard.
The answer is asynchronous batching. Understanding it teaches you the broader category of 'silent drop on exit' bugs in observability, which apply equally to OpenTelemetry, Phoenix, and any vendor SDK that prioritizes hot-path latency over delivery guarantees.
Why the SDK batches in the first place
If every span shipped synchronously to Langfuse, every LLM call would add a network round-trip's worth of latency on top of the actual model call. For a long-running web server handling thousands of requests per minute, that is unacceptable; the hot-path budget for observability instrumentation is typically <1ms, not >50ms.
The solution every production SDK converges on is: enqueue locally, ship asynchronously. The application thread writes the span to an in-memory queue (a few microseconds). A background thread or task drains the queue on a timer or size threshold and ships batches over HTTP. The hot path never waits on the network.
The cost is that delivery is now a separate concern from enqueue. The application has no direct signal that the batch arrived. Under normal long-running conditions, this is fine; the background thread always gets scheduled and always succeeds eventually. Under abnormal short-lived conditions, it is the bug under discussion.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- Langfuse Python SDK 3.x exposes langfuse.flush() and a context-manager API for exactly this case.
- AWS Lambda Python runtime with the Langfuse SDK requires an explicit flush at the end of every handler invocation.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow would you write a CI test that asserts traces actually shipped from a short-lived process?
Run the instrumented code in a subprocess, then query the Langfuse API for a trace with the expected metadata.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Assuming a clean exit code means traces shipped. Async SDKs decouple work from delivery; exit zero is no guarantee the batch made it out.
60 second bullets to scan on the way to the call.
Explain why production trace SDKs ship asynchronously
Name three idioms for forcing a flush before exit
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.