Eve library

OSHUN V1 Structured Tracing Manifest

Spec

Revision 1

On this page

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 shells
  • shell_admin_web, shell_admin_mobile — admin shells
  • bff_consumer, bff_admin, bff_flows, bff_release, bff_assistant
  • sophia — grounding/evidence
  • iris — memory
  • psyche — embodiment
  • lilith — persona / policy
  • isis — generation control

2. Required propagation channels#

Every cross-subsystem call MUST forward trace context through one of:

  • W3C traceparent / tracestate over HTTP headers
  • W3C traceparent / tracestate over gRPC metadata
  • baggage headers / 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:

  1. updating tracing-manifest.ts
  2. updating tests (lock-style tests fail closed if entries drift)
  3. updating this document if the change is structurally significant
  4. 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).