Langfuse: Manual Spans, Scores and Flushing

When decorators are not enough

Decorators map one function to one observation. Sometimes you need finer control: a span that covers only part of a function, a generation for a model client that has no integration, or setting fields you only know midway. The Langfuse SDK offers context managers such as start_as_current_span() and start_as_current_generation(); entering one makes it the current observation, so nested work attaches to it. Inside, update() sets output, metadata or usage, and update_current_trace() sets trace-level fields. Scores attach quality signals to a trace or observation: a name, a numeric, boolean or categorical value, and an optional comment. Finally, the SDK sends events asynchronously in batches from a background thread so it does not slow your requests. That is great for servers but dangerous for scripts, notebooks, CLI jobs and serverless functions: if the process exits before the batch is sent, data is lost. Call flush() before exit in those environments.

Manual span plus a score

Langfuse Python SDK (v3 style). The score could come from a user's thumbs-up or an automated check.

from langfuse import get_client

langfuse = get_client()

with langfuse.start_as_current_span(name="classify-ticket") as span:
    span.update(input={"text": "My payment failed twice"})
    label = "payments"                    # result of your model call
    span.update(output={"label": label})
    trace_id = langfuse.get_current_trace_id()

langfuse.create_score(
    trace_id=trace_id,
    name="label-correct",
    value=1,
    comment="verified by support agent",
)
langfuse.flush()  # required in scripts and serverless handlers

The missing-traces bug

"It works locally but no traces appear from my Lambda or cron job" is almost always a missing flush. The function returns, the runtime freezes or kills the process, and the background queue never sends. Flush at the end of each invocation, accepting a few milliseconds of extra latency.

Quick check: A nightly batch script uses Langfuse but only some traces show up. What is the most likely cause?

• The script uses too many decorators
• Langfuse only records traces during business hours
• Batch scripts must use LangSmith instead
• The process exits before the background queue is flushed