Status: Canonical Date: 2026-04-26 Owners: OSHUN Platform Engineering, OSHUN
Reliability Tracks: V1-OBS-009 from OSHUN_V1_TODOS.md Spec source:
libs/oshun/analytics/src/tracing-manifest.ts
This document is the canonical, human-readable companion to the machine-readable
V1 tracing manifest in @oshun/analytics.
The machine-readable manifest is the single source of truth.
1. Scope#
This manifest defines the trace span boundaries, propagation rules, and attribute conventions every Oshun-critical subsystem MUST follow. Downstream OpenTelemetry SDKs (TS / Rust / Python) compile this manifest into their span builders so traces remain shape-compatible end to end.
Subsystems covered:
shell_web,shell_mobile,shell_pwa— customer shellsshell_admin_web,shell_admin_mobile— admin shellsbff_consumer,bff_admin,bff_flows,bff_release,bff_assistantsophia— grounding/evidenceiris— memorypsyche— embodimentlilith— persona / policyisis— generation control
2. Required propagation channels#
Every cross-subsystem call MUST forward trace context through one of:
- W3C
traceparent/tracestateover HTTP headers - W3C
traceparent/tracestateover gRPC metadata baggageheaders / metadata- queue message attributes
- browser pageload-to-BFF context exchange
- in-process AsyncLocalStorage (or equivalent)
BFF span families MUST propagate W3C trace context over HTTP (enforced by tests). Sophia/Iris/Psyche/Lilith/Isis span families MUST declare at least one propagation channel.
3. Shared attributes#
Every span carries the shared attribute set:
oshun.tenant_id(required)oshun.session_id(when known)oshun.domain_context(required)oshun.platform_shell(when known)oshun.user_id(sanitized hash; raw user_id is never sent)oshun.persona_id(assistant operations)oshun.event_id(correlation with analytics events)
4. Span families#
The manifest publishes the canonical span families:
- Shell entry:
shell.app.opened,shell.route.transitioned,shell.admin_app.opened - BFF:
bff_consumer.request.handled,bff_admin.request.handled,bff_flows.request.handled,bff_release.request.handled,bff_assistant.turn.handled - Sophia:
sophia.evidence_pack.assembled,sophia.grounding.applied - Iris:
iris.memory.retrieved,iris.memory.persisted - Psyche:
psyche.embodiment.invoked - Lilith:
lilith.persona.bound,lilith.policy.evaluated - Isis:
isis.generation.run,isis.workflow.run
Each family publishes its required propagation channels and span-specific attributes. The shared attribute set is added implicitly.
5. PII handling#
No span attribute carries PII. The oshun.user_id attribute records a stable
hash of the user identifier rather than the raw ID. Free-form content (prompts,
narratives, message bodies) never appears on any span.
6. Governance#
6.1 Amendments#
Adding or changing a span family or attribute requires:
- updating
tracing-manifest.ts - updating tests (lock-style tests fail closed if entries drift)
- updating this document if the change is structurally significant
- signoff from Platform Engineering and Reliability
6.2 Versioning#
The manifest publishes attribute keys without versions; SDKs compile the manifest at boot time, so changes are picked up on the next deploy.
7. Change log#
- 2026-04-26 — Initial canonical V1 structured tracing manifest published
alongside
libs/oshun/analytics/src/tracing-manifest.ts(V1-OBS-009).