Eve library

OSHUN Studio Metrics and Analytics Instrumentation Dependency and Data Contract Map

Spec

Revision 1

On this page

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.md
  • docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.md
  • libs/oshun/analytics/src/types.ts
  • libs/oshun/domain-registry/src/index.ts
  • docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md
  • docs/releases/v1/design/ux-principles.md
  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/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:

  1. This dependency and contract map exists.
  2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
  3. Contracts for metric definitions, flow spans, audit-linkage, KPI composition, quality snapshots, and governance audit events are documented.
  4. Ownership boundaries and validation rules are explicit.