{"row":{"id":"ADR-035","title":"Telemetry seams: SpanGuard parent_span_id + SpanRef (OTel-ready)","file":"adr-035-telemetry-seams.md","status":"accepted","date":"2026-04-17","cites":5,"supersedes":[],"superseded_by":[],"layers":["L0.5"],"tags":["l0.5","telemetry","observability","otel"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-035: Telemetry seams: SpanGuard parent_span_id + SpanRef (OTel-ready)","id":"adr-035-telemetry-seams-spanguard-parent_span_id--spanref-otel-ready"},{"k":"p","inline":[{"k":"text","text":"Status flipped "},{"k":"code","text":"proposed → accepted"},{"k":"text","text":" 2026-07-12 under the merged-code\nrule (the #474 ADR ruling): both reservations ship in\n"},{"k":"code","text":"crates/nika-kernel-core/src/infra/trace.rs"},{"k":"text","text":" (the kernel's core member\n— the ADR predates the kernel descent; "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" re-exports)."}]},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Wave 4B #1 (commit "},{"k":"code","text":"861f09bc9"},{"k":"text","text":", 2026-04-17) extended the kernel\ntelemetry types with two additive reservations so span identity can\ntravel — across await points, channels, spawned tasks — without a\nthread-local stack (which the tokio runtime breaks) and without\ncloning a live guard."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"Both shapes ship in "},{"k":"code","text":"nika-kernel-core/src/infra/trace.rs"},{"k":"text","text":":"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"`SpanGuard.parent_span_id: Option<SpanId>`"},{"k":"text","text":" — the explicit\nparent link. Nested spans stitch into a tree by data, not by\nambient state: the module doc states the law (« parent_span_id\nthreads parent→child links »), and the field is "},{"k":"code","text":"Option"},{"k":"text","text":" because a\nroot span honestly has no parent — this is the one place an absent\nvalue IS the semantics, not a policy hole."}],[{"k":"strong","text":"`SpanRef { trace_id, span_id }`"},{"k":"text","text":" — the lightweight copyable\nhandle (with "},{"k":"code","text":"::new()"},{"k":"text","text":", FCI #19) for propagating span identity\nacross boundaries where a "},{"k":"code","text":"SpanGuard"},{"k":"text","text":" cannot go: channel payloads,\nspawn captures, cross-process IPC. The shape deliberately mirrors\nOTel's "},{"k":"code","text":"SpanContext"},{"k":"text","text":" so a future bridge is a field-for-field map."}]]},{"k":"p","inline":[{"k":"text","text":"Both are "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" — OTel's "},{"k":"code","text":"TraceFlags"},{"k":"text","text":"/"},{"k":"code","text":"TraceState"},{"k":"text","text":" can\njoin "},{"k":"code","text":"SpanRef"},{"k":"text","text":" later without a major."}]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Thread-local span stack"},{"k":"text","text":" — rejected: tokio task migration breaks\nambient parenting; the explicit field survives every executor."}],[{"k":"strong","text":"Clone the `SpanGuard` across boundaries"},{"k":"text","text":" — rejected: a guard's\nDrop is its END event; two owners means double-close or leaked\nspans. A "},{"k":"code","text":"Copy"},{"k":"text","text":"-able ref carries identity without lifecycle."}],[{"k":"strong","text":"Adopt the `opentelemetry` crate types directly in L0.5"},{"k":"text","text":" —\nrejected: the kernel stays zero-heavy-deps; mirroring the SHAPE\nkeeps the bridge zero-copy while the dependency stays out."}]]},{"k":"h","depth":2,"text":"Empirical validation (what makes this \"merged code\")","id":"empirical-validation-what-makes-this-merged-code"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-kernel-core/src/infra/trace.rs"},{"k":"text","text":" — "},{"k":"code","text":"SpanRef"},{"k":"text","text":" (line ~21, with\nconstructor), "},{"k":"code","text":"parent_span_id: Option<SpanId>"},{"k":"text","text":" on "},{"k":"code","text":"SpanGuard"},{"k":"text","text":"\n(line ~49), module-doc law at the top."}],[{"k":"text","text":"The OTel direction the reservation aimed at materialized\nprojection-side meanwhile: "},{"k":"code","text":"nika trace export"},{"k":"text","text":"\n("},{"k":"code","text":"nika-dap/src/otel.rs"},{"k":"text","text":") projects recorded journals to OTLP/JSON —\nconsuming the same span-identity vocabulary these types reserved."}]]},{"k":"h","depth":2,"text":"See also","id":"see-also"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-028 — Forward-compat reservation policy (this ADR is an instance)."}],[{"k":"text","text":"ADR-034 — the tracer trait family that emits these shapes."}],[{"k":"text","text":"FCI-035 addendum — Wave 4A/4B reservation catalog."}],[{"k":"text","text":"NIKA-800..819 — Observability / telemetry error code range (reserved\nv0.80)."}],[{"k":"code","text":"nika trace export"},{"k":"text","text":" — the shipped OTLP projection (journal-side)."}]]},{"k":"p","inline":[{"k":"text","text":"🦋"}]}]

ADR-035

Telemetry seams: SpanGuard parent_span_id + SpanRef (OTel-ready)

accepted · 2026-04-17 · L0.5 · cites 5

ADR-035: Telemetry seams: SpanGuard parent_span_id + SpanRef (OTel-ready) #

Status flipped proposed → accepted 2026-07-12 under the merged-code rule (the #474 ADR ruling): both reservations ship in crates/nika-kernel-core/src/infra/trace.rs (the kernel's core member — the ADR predates the kernel descent; nika-kernel re-exports).

Context #

Wave 4B #1 (commit 861f09bc9, 2026-04-17) extended the kernel telemetry types with two additive reservations so span identity can travel — across await points, channels, spawned tasks — without a thread-local stack (which the tokio runtime breaks) and without cloning a live guard.

Decision #

Both shapes ship in nika-kernel-core/src/infra/trace.rs:

`SpanGuard.parent_span_id: Option<SpanId>` — the explicit parent link. Nested spans stitch into a tree by data, not by ambient state: the module doc states the law (« parent_span_id threads parent→child links »), and the field is Option because a root span honestly has no parent — this is the one place an absent value IS the semantics, not a policy hole.
`SpanRef { trace_id, span_id }` — the lightweight copyable handle (with ::new(), FCI #19) for propagating span identity across boundaries where a SpanGuard cannot go: channel payloads, spawn captures, cross-process IPC. The shape deliberately mirrors OTel's SpanContext so a future bridge is a field-for-field map.

Both are #[non_exhaustive] — OTel's TraceFlags/TraceState can join SpanRef later without a major.

Alternatives considered #

Thread-local span stack — rejected: tokio task migration breaks ambient parenting; the explicit field survives every executor.
Clone the `SpanGuard` across boundaries — rejected: a guard's Drop is its END event; two owners means double-close or leaked spans. A Copy-able ref carries identity without lifecycle.
Adopt the `opentelemetry` crate types directly in L0.5 — rejected: the kernel stays zero-heavy-deps; mirroring the SHAPE keeps the bridge zero-copy while the dependency stays out.

Empirical validation (what makes this "merged code") #

nika-kernel-core/src/infra/trace.rs — SpanRef (line ~21, with constructor), parent_span_id: Option<SpanId> on SpanGuard (line ~49), module-doc law at the top.
The OTel direction the reservation aimed at materialized projection-side meanwhile: nika trace export (nika-dap/src/otel.rs) projects recorded journals to OTLP/JSON — consuming the same span-identity vocabulary these types reserved.