Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN Data/Analytics
Engineering
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.mddocs/releases/v1/specs/studio-metrics-and-analytics-instrumentation-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio metrics and analytics instrumentation workflows.
This document is the execution artifact for OST-00219.
Personas#
- Collaboration Lead
- Program Operator
- Domain Integrator
- Security Reviewer
- Compliance Auditor
Journey Principles#
- Every instrumentation flow must emit canonical requested/completed spans.
- Metric definitions and KPI compositions must be deterministic and traceable.
- Audit and analytics outcomes must remain contract-linked.
- Telemetry quality checks must gate release readiness.
1. Primary Journeys#
J1. Publish Metric Definition#
Goal: Define/update canonical Studio metric semantics and thresholds.
Entry: Metrics instrumentation workspace
Steps:
- Select metric type, unit, owner, and aggregation window.
- Configure warning and critical thresholds.
- Publish metric definition.
- Persist versioned metric-definition record.
- Emit metric-definition update event.
Success State:
- Metric definition is stored with deterministic semantics and ownership.
J2. Emit and Correlate Flow Spans#
Goal: Instrument actionable Studio flows with requested/completed spans.
Entry: Flow execution in Studio surface
Steps:
- Emit
flow_requestedevent with attribution context. - Execute flow state transition.
- Emit
flow_completedwith success/latency/error metadata. - Correlate span to workflow and source domain.
- Persist span lineage for KPI aggregation.
Success State:
- Flow spans are complete, attributable, and KPI-consumable.
J3. Link Audit Outcomes to Analytics#
Goal: Preserve deterministic linkage between policy outcomes and analytics.
Entry: Audit event generated by governance flow
Steps:
- Capture audit action and outcome.
- Map audit record to canonical analytics event contract.
- Persist linkage metadata (
auditEventId,analyticsEventName). - Validate linkage integrity and null-rate thresholds.
- Emit linkage completion event.
Success State:
- Every critical audit outcome is analytics-linked and queryable.
J4. Compose and Validate KPI Signals#
Goal: Build KPI aggregates for reliability, latency, and policy integrity.
Entry: Metric and span streams available
Steps:
- Select KPI composition model (
rate,ratio,p95,sum). - Bind numerator/denominator metric sources.
- Calculate KPI values for configured windows.
- Compare values against warning/critical thresholds.
- Emit KPI evaluation result and threshold status event.
Success State:
- KPI outputs are deterministic, threshold-aware, and release-gate ready.
J5. Run Telemetry Quality and Release Gate#
Goal: Validate telemetry completeness before production promotion.
Entry: Release candidate instrumentation bundle
Steps:
- Execute schema validation on instrumentation payloads.
- Evaluate completeness, null-dimension, and duplication rates.
- Verify flow-span and audit-linkage coverage.
- Generate release-gate verdict with evidence references.
- Emit telemetry-quality gate decision event.
Success State:
- Release gate passes only when telemetry quality thresholds are met.
2. Critical Edge Cases#
E1. Metric Definition Missing Owner#
- Trigger: metric definition published without
owner. - Required behavior: reject publish and require owner attribution.
E2. Metric Threshold Inversion#
- Trigger: critical threshold set below warning threshold.
- Required behavior: block publish and return deterministic validation error.
E3. Flow Requested Without Completion#
- Trigger: requested span emitted but completed span missing.
- Required behavior: flag orphan span and trigger instrumentation incident.
E4. Duplicate Flow Completion Emission#
- Trigger: same span completes multiple times.
- Required behavior: enforce idempotent completion and retain one canonical record.
E5. Audit Outcome Without Analytics Linkage#
- Trigger: audit event persists without linkage record.
- Required behavior: block release gate and emit quality-degradation event.
E6. KPI Composition Missing Denominator#
- Trigger: ratio KPI configured without denominator metric.
- Required behavior: reject KPI evaluation and require complete composition spec.
E7. High Null-Dimension Rate#
- Trigger: required attribution fields exceed null-rate threshold.
- Required behavior: mark telemetry quality failed and prevent production release.
E8. Domain Mapping Drift#
- Trigger: source domain not in canonical registry during ingestion.
- Required behavior: quarantine event and emit schema-mismatch alert.
E9. PII Field Detected in Payload#
- Trigger: payload includes disallowed PII property.
- Required behavior: reject ingestion and emit privacy-policy violation event.
E10. KPI Threshold Alert Not Routed#
- Trigger: critical KPI breach without alert routing.
- Required behavior: trigger fallback alert routing and incident marker.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Publish Metric Definition | Metrics/analytics instrumentation | Analytics contract services |
| J2 Emit and Correlate Flow Spans | Metrics/analytics instrumentation | Studio flow surfaces + BFF |
| J3 Link Audit Outcomes | Metrics/analytics instrumentation | Audit/compliance + analytics linkage |
| J4 Compose and Validate KPI Signals | Metrics/analytics instrumentation | KPI aggregation and threshold engine |
| J5 Run Telemetry Quality Release Gate | Metrics/analytics instrumentation | Release governance + quality checks |
4. Instrumentation Requirements#
Required events:
metrics_analytics_instrumentation.journey.startedmetrics_analytics_instrumentation.journey.step.completedmetrics_analytics_instrumentation.journey.blockedmetrics_analytics_instrumentation.journey.recoveredmetrics_analytics_instrumentation.journey.completed
Required dimensions:
metricId,metricType,spanId,auditEventId,kpiId,sourceDomainactorId,actorRole,workspaceId,releaseChannel,qualityScorejourneyId,stepId,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00219)#
OST-00219 is complete only when:
- At least five metrics/instrumentation journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.