How does Langfuse's @observe decorator trace a Python function?

## What the decorator does `@observe()` is Langfuse's least-invasive instrumentation: you add one line above a function and every call to it is recorded as an observation. On entry the SDK opens an observation; on return it closes it. Along the way it fills in: - **name** — the function's name, unless you override it with `@observe(name="...")`. - **input** — the call's arguments, serialised. - **output** — the return value. - **timing** — start and end, hence the duration you see in the waterfall. - **level and status** — if the function raises, the observation is marked accordingly and the exception is re-raised to your caller. Instrumentation never swallows your errors, and equally the SDK will not raise a tracing error into your request path. It works on both `def` and `async def` functions, and on generators, so you do not need a separate decorator for async code. ## Nesting is implicit The SDK keeps a notion of the *currently active* observation. When a decorated function runs, its observation becomes current for the duration of the body; anything created inside — another decorated function, a context-managed observation, an instrumented model call — attaches to it as a child. That is the whole reason the decorator is pleasant to use: to get a tree you decorate the functions you already have, and the call stack supplies the structure. If nothing is active when a decorated function runs, its observation becomes the root of a new trace. The corollary is the classic failure: work handed to a thread pool or scheduled as a detached task may run outside the active context, and its observations then land in their own trace instead of the one you expected. When you see orphaned traces that should have been children, that is the first thing to check. ## Arguments worth knowing - `as_type="generation"` records the call as a model call rather than a generic span, which is what you want if you are hand-rolling a provider call inside the function and want its tokens and cost to count. - `name="..."` gives a stable, readable label. Function names leak refactors into your dashboards; explicit names do not. - `capture_input=False` and `capture_output=False` stop the payloads being recorded at all. This is the blunt, code-local control for a function that handles data you are not allowed to store — a raw document, a payment payload, a full user profile. It is coarser than a masking function, but it is decided at the call site, which sometimes matters more. ## Configuration and lifecycle Credentials and destination come from the environment: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and `LANGFUSE_HOST` (which you must set for self-hosted deployments and for the non-default cloud region). The decorator uses the same client you can reach explicitly with `get_client()`. Export is asynchronous and batched. In a long-running server that is invisible and desirable. In a script, a CLI, a notebook cell or a serverless handler it matters: if the process exits or freezes before the batch is sent, the trace never arrives. Call `get_client().flush()` before the process ends. ## When the decorator is not the right tool The decorator's unit is the function. When the thing you want to time is a block inside a function, or when you need to create an observation, keep working, and end it later on some other code path, reach for the context-manager and manual APIs instead. They are not alternatives so much as different granularities of the same model, and they compose: a decorated function can open context-managed children freely. Equally, do not hand-decorate what an integration already covers. If you are calling OpenAI through Langfuse's drop-in client, the generation is captured for you; the decorator's job is to give that generation a meaningful parent. ## Interview framing Say what it captures (name, input, output, timing), say that nesting comes from the active-observation context rather than from anything you pass, name one real control you would use in production (`capture_input=False`, or an explicit `name`), and mention flushing in short-lived processes. That last point is what distinguishes someone who has actually shipped it from someone who has read the quickstart.