Document 0064: concepts, changelog, example

Document the Langfuse trace.userId / trace.sessionId population in the
observability concepts page, add the 0.15.0 changelog entry (folding
0064 into the cycle's spec-pin bullet), and demonstrate the userId
promotion in the langfuse-observability example (a per-operator userId
that surfaces in the captured trace). sessionId is left out of the
example since it stays dormant until the sessions capability lands.

Author: chris-colinsky

CHANGELOG.md

@@ -10,10 +10,11 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 - **Detached-trace invocation span** (proposal 0061, observability §4.4, spec v0.61.0). The OTel observer now synthesizes an `openarmature.invocation` span at the root of each detached trace (a detached subgraph and each detached fan-out instance), carrying the parent's shared `invocation_id` (detached mode is observer-side trace rendering, not a new run) and the detached unit's own `entry_node`; the detached subgraph / instance span nests under it. A raising detached subgraph surfaces ERROR plus the error category and an OTel exception event on both the parent dispatch span and the detached invocation span. This is observer-side only, with no graph-engine change; the Langfuse observer is unchanged (its Trace entity already plays the invocation-level-container role). Conformance fixtures 008 (rewritten) and 058 (newly wired) run in `test_observability`.
 - **Per-attempt LLM spans under call-level retry** (proposal 0050, observability §5.5 / llm-provider §7.1). Completes proposal 0050, which shipped `partial` in v0.14.0 (failure-isolation middleware and the `complete(retry=...)` loop landed then; the per-attempt span surface was deferred). Under call-level retry the OTel observer now emits one `openarmature.llm.complete` span per attempt, each carrying `openarmature.llm.attempt_index` (0-based, 0..N-1, and 0 for a no-retry call). An intermediate failed attempt's span carries ERROR status plus its error category and the request-side attributes; the final attempt's span carries the terminal outcome and, on success, the full response surface. A python-internal `LlmRetryAttemptEvent`, dispatched once per attempt, is the sole source of the OTel span; the terminal `LlmCompletionEvent` / `LlmFailedEvent` stay one per call (payload, latency, Langfuse Generation) and no longer drive the OTel span. Langfuse renders one terminal Generation per call, with the per-attempt detail on the OTel span surface only (a spec-side §8 clarification to pin this is tracked, non-blocking). `conformance.toml` flips proposal 0050 to `implemented`; the call-level fixtures 056-058 are driven through the provider plus OTel observer and the single-attempt observability fixture 057 is wired.
+- **Langfuse `trace.userId` / `trace.sessionId` population** (proposal 0064, observability §8.4.1, spec v0.62.0). The Langfuse observer now promotes a recognized `userId` key in the caller-supplied invocation metadata to Langfuse's first-class `trace.userId` field (the Users dashboard), additively: the key also remains at `trace.metadata.userId`. Promotion is automatic and unconditional; an absent key leaves `trace.userId` unset. The `LangfuseClient.trace()` surface (the Protocol, the in-memory client, and the SDK adapter) gains `session_id` / `user_id`. `trace.sessionId` is sourced from `openarmature.session_id`, which the sessions capability (proposal 0020) establishes; that capability is not yet implemented in python, so the `sessionId` plumbing is in place but dormant (no source) and unset in the interim. `conformance.toml` records proposal 0064 `partial` on that basis: fixture 084 cases 2/3/4 (not session-bound, `userId` present additively, `userId` absent) run, and the session-bound cases 1/5 defer until 0020. Langfuse-only: the OTel side already carries `openarmature.session_id` and `openarmature.user.*` as span attributes, and OTel has no trace-level session/user field.
 
 ### Changed
 
-- **Pinned spec advances v0.60.0 → v0.61.0** (proposal 0061, the detached-trace invocation span above). A single step this cycle; `conformance.toml` records proposal 0061 as `implemented`. Proposal 0050 needed no pin bump of its own (it was already within the pin from its v0.42.0 acceptance); its v0.14.0 `partial` entry flips to `implemented` with the per-attempt span surface above.
+- **Pinned spec advances v0.60.0 → v0.62.0** across the v0.15.0 cycle: v0.61.0 (proposal 0061, the detached-trace invocation span above) and v0.62.0 (proposal 0064, the Langfuse session/user population above). `conformance.toml` records 0061 `implemented` and 0064 `partial` (its `sessionId` half is dormant pending the sessions capability). Proposal 0050 needed no pin bump of its own (it was already within the pin from its v0.42.0 acceptance); its v0.14.0 `partial` entry flips to `implemented` with the per-attempt span surface above.
 
 ## [0.14.0] — 2026-06-17
 

docs/concepts/observability.md

@@ -1048,6 +1048,18 @@ for a runnable demo.
 - **Trace name.** Defaults to the entry-node name (spec §8.6
   fallback). Caller-supplied invocation labels land in PR 4
   (proposal 0034).
+- **Session / user grouping (`trace.sessionId` / `trace.userId`).**
+  The observer populates the two cross-trace grouping fields behind
+  Langfuse's Sessions and Users dashboards (spec §8.4.1, proposal
+  0064). `trace.userId` is promoted from a recognized `userId` key in
+  the caller-supplied invocation metadata, automatically and
+  additively (the key also stays at `trace.metadata.userId`); an
+  absent key leaves it unset. `trace.sessionId` is sourced from
+  `openarmature.session_id` (the sessions capability), which is not
+  yet implemented, so it is unset for now. There is no OTel
+  equivalent (an OTel trace has no trace-level session / user field);
+  the same identity already rides as `openarmature.session_id` and the
+  `openarmature.user.*` family on the OTel span side.
 - **Per-observation metadata.** Each Span / Generation carries
   `namespace`, `step`, `attempt_index`, optional `fan_out_index` /
   `branch_name`, and the `correlation_id` cross-cutting join key

examples/langfuse-observability/main.py

@@ -16,7 +16,10 @@
 observation picks that up and links back to the entity, which is how
 production Langfuse dashboards thread "this generation came from prompt
 v7 of `mission-briefing`" without you having to wire anything up
-manually.
+manually. It also tags each trace with a ``userId`` (operator identity)
+via invocation metadata; the observer promotes that to Langfuse's
+first-class user dimension, so the Users dashboard groups and filters
+the assistant's traffic by operator.
 
 The example uses the bundled ``InMemoryLangfuseClient`` recorder so the
 demo runs without a Langfuse account; at the end we print the captured
@@ -193,6 +196,8 @@ def _format_trace(trace: LangfuseTrace) -> str:
     lines: list[str] = []
     lines.append(f"Trace id={trace.id}")
     lines.append(f"      name={trace.name!r}")
+    if trace.user_id is not None:
+        lines.append(f"      userId={trace.user_id!r}  (promoted to the Langfuse Users dimension)")
     lines.append(f"      metadata={_format_metadata(trace.metadata)}")
     for obs in trace.children_of(None):
         _format_observation(lines, trace, obs, indent="  ")
@@ -274,7 +279,15 @@ async def main() -> None:
     graph.attach_observer(observer)
 
     try:
-        final = await graph.invoke(BriefingState(question=question))
+        # metadata={"userId": ...} tags the trace with an operator
+        # identity. The Langfuse observer promotes a recognized ``userId``
+        # key to the first-class trace.userId field so the Users dashboard
+        # can group and filter traces by operator (additive: it also stays
+        # in trace.metadata.userId).
+        final = await graph.invoke(
+            BriefingState(question=question),
+            metadata={"userId": "flight-controller-gene"},
+        )
     finally:
         # Required for short-lived processes: invoke() returns when the
         # graph reaches END regardless of whether the observer queue