Disciplines · Decisions (ADRs)

ADR-0041: OSHUN Studio Observability and Operational Dashboards

Studio has canonical metrics instrumentation, but operators still need a first-class operational dashboard surface to detect regressions, triage policy issues, and coordinate incident response across domains.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, Platform SRE, OSHUN Data/Analytics Engineering
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio has canonical metrics instrumentation, but operators still need a first-class operational dashboard surface to detect regressions, triage policy issues, and coordinate incident response across domains.

Without a unified observability dashboard architecture, OSHUN risks:

  • fragmented dashboards with inconsistent SLI/SLO semantics
  • weak incident triage due to missing drill-down context
  • delayed detection of policy-denial or telemetry-quality regressions
  • governance gaps between runtime operations and audit evidence

Decision Drivers#

  • Operator velocity: fast, low-friction triage and remediation workflows.
  • Deterministic telemetry: one SLI/SLO vocabulary across Studio surfaces.
  • Actionability: every dashboard signal maps to a concrete workflow action.
  • Governance alignment: incident, policy, and release evidence must align.
  • Scale: dashboard design must span Yemaya/Isis/Hathor/Aja/Bellona.

Considered Options#

Option 1: Per-Domain Operational Dashboards#

Each domain publishes and manages its own dashboard patterns.

Pros:

  • Local ownership and domain-specific optimization.

Cons:

  • Inconsistent incident semantics and fragmented response workflows.
  • Cross-domain rollups become costly and unreliable.

Option 2: External Ops Tools Only#

Use external observability tools with minimal Studio-native dashboard UI.

Pros:

  • Lower Studio UI implementation effort.

Cons:

  • Weak integration with Studio context, permissions, and workflow controls.
  • Poor ergonomics for product/program operators working inside Studio.

Option 3: Canonical Studio Observability Dashboard Surface (Chosen)#

Implement a Studio-native operational dashboard with typed SLI/SLO cards, alert streams, dependency health drill-downs, and policy-aware remediation actions.

Pros:

  • Deterministic operational semantics across all Studio domains.
  • Faster incident triage with direct linkage to recovery workflows.
  • Strong alignment between telemetry, alerting, policy, and governance.

Cons:

  • Requires coordinated schema/version governance across data producers.

Decision Outcome#

Chosen option: Option 3.

Observability and dashboard requirements:

  1. Canonical dashboard data contract for SLI, SLO, and alert cards.
  2. Domain and workflow drill-down contract for rapid causality isolation.
  3. Policy and permission contract for remediation actions in-dashboard.
  4. Alert-state lifecycle contract for ack, assign, resolve, and export.
  5. Operational readiness contract for release and incident gating.

Normative Rules#

Dashboard Data Contract#

  • Every dashboard card must include signalId, signalType, status, window, currentValue, targetValue, and updatedAt.
  • Cards must map to one canonical source-of-truth telemetry stream.
  • Stale data beyond the configured freshness window is release-blocking.

SLI/SLO Contract#

  • Required SLI/SLO set includes success rate, latency, denial rate, availability, and telemetry completeness.
  • SLO breach thresholds must be explicit and environment-aware.
  • SLO calculations must be deterministic and reproducible.

Drill-Down Contract#

  • Every alerting card must provide domain + workflow + dependency drill-down.
  • Drill-down payload must preserve actor/workspace/release attribution.
  • Drill-down actions must never bypass policy constraints.

Policy and Permission Contract#

  • Dashboard remediation actions require role + permission-tier validation.
  • Production-impacting actions require CAB approval evidence where applicable.
  • Policy denials must be auditable and visible in dashboard history.

Alert Lifecycle Contract#

  • Alerts must support new, acknowledged, investigating, resolved, closed states with deterministic transitions.
  • Every transition must emit telemetry and audit events.
  • Duplicate/looping transitions must be idempotent and traceable.

Operational Readiness Contract#

An observability dashboard release is valid only when all are true:

  • SLI/SLO cards pass data-freshness and schema validation
  • alert lifecycle actions pass role/policy checks
  • drill-down links resolve to valid Studio context
  • telemetry and audit emissions pass completeness checks
  • runbook ownership/escalation artifacts are current

Architecture Implications#

  • Web and BFF layers share one typed dashboard contract.
  • Dashboard cards are sourced from canonical metrics instrumentation streams.
  • Policy enforcement is reused from Studio RBAC and permission-tier systems.
  • Incident playbooks become directly actionable from dashboard UI.

Acceptance Criteria (OST-00225)#

OST-00225 is complete only when:

  1. ADR exists at docs/adr/ADR-0047-oshun-studio-observability-and-operational-dashboards.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines dashboard data, SLI/SLO, drill-down, policy/permission, alert-lifecycle, and operational-readiness contracts.
  4. ADR aligns with ADR-0007 through ADR-0040, especially ADR-0012, ADR-0039, and ADR-0040.
  5. ADR aligns with docs/releases/v1/design/ux-principles.md, libs/oshun/analytics, and libs/oshun/domain-registry.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Faster operator response with dashboard-native triage/remediation context.
  • Higher observability consistency and incident-detection reliability.
  • Better governance posture for operational decisions and release gating.

Negative#

  • Added implementation and maintenance overhead for typed dashboard contracts.
  • Requires tight cross-team discipline for signal taxonomy and thresholds.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0045-oshun-studio-resilience-and-error-ux.md
  • docs/adr/ADR-0046-oshun-studio-metrics-and-analytics-instrumentation.md

References#

  • libs/oshun/analytics/src/types.ts
  • libs/oshun/domain-registry/src/index.ts
  • 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