Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Data/Analytics
Engineering
Last Updated: 2026-02-23
Related: docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.md
Purpose#
Define dependencies and canonical contracts for Studio metrics and analytics instrumentation capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00218.
Sources Used#
docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.mddocs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.mdlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/domains/bellona/features.md
1. Dependency Overview#
1.1 Control Surfaces#
- Metrics/instrumentation UI surfaces: Studio metrics modules in
apps/oshun/web/src/components/studio. - Telemetry ingestion and normalization services: BFF + analytics sink gateways for canonical event contracts.
- KPI aggregation services: rate/latency/reliability computation pipelines.
- Audit-linkage services: policy and governance event correlation pipelines.
- Quality and governance controls: schema validation, null-rate monitoring, and release-gate checks.
1.2 Domain Dependency Graph#
Metrics/Instrumentation -> Yemaya: release telemetry, publish-flow KPIs.Metrics/Instrumentation -> Isis: model workflow telemetry and reliability KPIs.Metrics/Instrumentation -> Hathor: narrative pipeline telemetry and quality KPIs.Metrics/Instrumentation -> Aja: timeline/render telemetry and latency KPIs.Metrics/Instrumentation -> Bellona: runtime/incident telemetry and recovery KPIs.Project Obsidian -> all: cross-domain KPI governance, comparability, and alerts.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Artifact | Contract |
|---|---|---|---|---|
| Canonical metric definitions | Data/Analytics + Studio | Product + operations | Metric definition | StudioMetricDefinition |
| Flow-span instrumentation | Web + BFF Engineering | Observability + analytics | Flow-span payload | StudioFlowTelemetrySpan |
| Audit-to-analytics linkage | Security + Data Platform | Compliance + operations | Linkage record | StudioAuditAnalyticsLinkage |
| KPI composition and thresholds | Data/Analytics | Leadership + on-call | KPI spec | StudioKpiCompositionSpec |
| Telemetry quality governance | Platform SRE + Analytics | Release managers + on-call | Quality snapshot | StudioTelemetryQualitySnapshot |
| Governance evidence export | Data Platform + Security | Compliance + audit operations | Telemetry/audit export | StudioMetricsGovernanceAuditEvent |
3. Canonical Contracts#
3.1 StudioMetricDefinition#
ts
export interface StudioMetricDefinition {
metricId: string;
metricName: string;
metricType: 'counter' | 'gauge' | 'rate' | 'histogram';
unit: 'count' | 'ms' | 'percent' | 'ratio';
owner: string;
aggregationWindow: '1m' | '5m' | '15m' | '1h' | '1d';
alertThreshold?: number;
updatedAt: string;
}
3.2 StudioFlowTelemetrySpan#
ts
export interface StudioFlowTelemetrySpan {
spanId: string;
flow: string;
actorId: string;
role: string;
workspaceId: string;
sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
startedAt: string;
completedAt?: string;
success?: boolean;
latencyMs?: number;
errorCode?: string;
}
3.3 StudioAuditAnalyticsLinkage#
ts
export interface StudioAuditAnalyticsLinkage {
linkageId: string;
auditEventId: string;
analyticsEventName: string;
outcome: 'allowed' | 'denied' | 'success' | 'error';
actorId: string;
workspaceId: string;
occurredAt: string;
}
3.4 StudioKpiCompositionSpec#
ts
export interface StudioKpiCompositionSpec {
kpiId: string;
kpiName: string;
numeratorMetricId: string;
denominatorMetricId?: string;
calculation: 'sum' | 'avg' | 'ratio' | 'p95' | 'p99';
targetValue: number;
warningThreshold: number;
criticalThreshold: number;
updatedAt: string;
}
3.5 StudioTelemetryQualitySnapshot#
ts
export interface StudioTelemetryQualitySnapshot {
snapshotId: string;
sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
completenessRate: number;
nullDimensionRate: number;
duplicateSpanRate: number;
schemaViolationRate: number;
capturedAt: string;
}
3.6 StudioMetricsGovernanceAuditEvent#
ts
export interface StudioMetricsGovernanceAuditEvent {
eventId: string;
action:
| 'metrics.definition.updated'
| 'metrics.flow_span.completed'
| 'metrics.audit_linkage.recorded'
| 'metrics.kpi.threshold_breached'
| 'metrics.quality.degraded'
| 'metrics.policy_denied';
outcome: 'allowed' | 'denied' | 'success' | 'error';
metricId?: string;
spanId?: string;
actorId?: string;
actorRole?: string;
traceId?: string;
occurredAt: string;
}
4. Validation Rules#
- Metric definitions must include owner, unit, and threshold metadata.
- Flow spans must emit requested/completed lifecycle with stable IDs.
- Audit-linkage records must map to canonical analytics event names.
- KPI specs must include deterministic threshold and calculation semantics.
- Telemetry quality snapshots must enforce completeness and schema-violation checks.
- Governance audit events must capture definition, linkage, threshold, and quality outcomes end to end.
5. Acceptance Criteria (OST-00218)#
OST-00218 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for metric definitions, flow spans, audit-linkage, KPI composition, quality snapshots, and governance audit events are documented.
- Ownership boundaries and validation rules are explicit.