How do you create nested Langfuse observations without the @observe decorator?

## Why you need this at all The `@observe` decorator's unit is a function. Plenty of things you want to time are not functions: a block in the middle of a handler, a loop iteration, a piece of work that starts on one code path and finishes on another. The manual API covers those, and it composes freely with decorated functions — a decorated function can open context-managed children, and a manual span can contain decorated calls. ## The two creation methods **`start_as_current_observation(as_type=..., name=...)`** — a context manager. Entering it opens the observation *and* makes it the currently active one; leaving the block ends it, recording the duration, and restores the previous active observation. Because it is active for the duration of the block, anything created inside — another manual observation, a decorated function call, an instrumented model call — nests beneath it automatically. This is the default choice. **`start_observation(as_type=..., name=...)`** — creates the observation and returns it *without* making it active and *without* ending it. You are responsible for calling `.end()`. Use it when: - the work finishes somewhere else — a callback, a completion handler, a later event; - you want a child that must not capture unrelated concurrent work happening in the same block; - you are fanning out concurrent tasks and each needs its own object rather than a shared implicit context. The cost of the manual form is the obvious one: forget `.end()` and you ship an observation with no end time. ## Filling the observation in The object returned by either method carries the mutation surface: - `update(...)` — set input, output, metadata, level, and type-specific fields such as model or usage details on a generation. Call it as many times as you like; the last write wins. - `create_event(name=...)` — record a point-in-time marker beneath this observation, for things with no duration. - `score(...)` — attach a score to this observation, and `score_trace(...)` to score the whole trace. - `start_observation(...)` / `start_as_current_observation(...)` — create explicit children of *this* observation, regardless of what is currently active. This is the escape hatch for concurrency, where implicit nesting is unreliable. - `end()` — close it, when you created it with the non-context form. From inside a `start_as_current_observation` block you can also skip holding the object and use the client-level helpers: `langfuse.update_current_span(...)` and `langfuse.update_current_generation(...)` mutate whatever is active. Handy in a helper function that should annotate its caller's observation without knowing which one it is. ## Trace-level fields from inside a span A common need: you are three levels deep and want to set the *trace's* input and output, not the span's. In v4 that is `span.set_trace_io(input=..., output=...)`, with `span.set_trace_as_public(...)` alongside it for sharing. This is a place where stale knowledge bites. The v3 SDK had `langfuse.update_current_trace(...)` and `span.update_trace(...)`; **neither exists in the v4 SDK**, and code carried over from a v3 tutorial fails with an attribute error. For trace-level *attributes* like user id, session id and tags, v4 uses a separate module-level context manager rather than a client method. ## Choosing a shape In practice most codebases end up with a hybrid: decorators on the coarse functions that define the shape of a request, and manual context-managed observations inside the two or three functions where the interesting sub-steps live. Reach for `start_observation` only where the lifetime genuinely does not match a block — it is the sharpest tool here and the easiest to leave dangling. For async and concurrent code, prefer explicit parenting: create children off the parent object you hold rather than relying on the active context, because whether context follows a task depends on how it was scheduled. Orphaned traces that should have been children almost always trace back to implicit nesting across a concurrency boundary. ## Interview framing Name both methods and state the difference in one sentence — one makes itself current and self-ends, the other does neither. Then say what you would use each for, mention `update()` and the trace-level `set_trace_io`, and flag that the v3 trace-update method names are gone in v4. That last detail is a cheap way to show you are working from the current SDK rather than from memory.