V1 Web PWA · Surface walkthrough

Studio · Metrics and Analytics Instrumentation

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked
8sections3 minread
Markdown source
On this page

Context. surface studio · domain operations · route /studio/metrics-analytics-instrumentation · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/metrics-analytics-instrumentation/page.tsx

Last walked. 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body re-derived 2026-06-03 from current source (lane-console architecture)

Purpose#

Score telemetry instrumentation health with the real metrics-instrumentation evaluator: KPI threshold states (healthy / warning / critical, evaluated by direction), per-metric instrumentation quality (issue codes such as missing owner, missing unit, high cardinality, low sample coverage), and a release gate that blocks on critical KPIs or uninstrumented metrics. The workspace (StudioMetricsAnalyticsInstrumentationWorkspace) is an admin lane console that loads the evaluator catalog on mount and posts an instrumentation payload for evaluation.

Entry points#

  • Studio root (/studio) — discoverable as an operations workspace
  • Sibling quick actions — Observability and Operational Dashboards, Resilience and Error UX, Background Jobs and Progress UX, Asset Preview Pipeline, and Activity and Change Feeds workspaces link in/out
  • Direct URL / bookmark — yes

Layout regions#

page.tsx mounts ShellLayout active="studio", renders StudioMetricsAnalyticsInstrumentationWorkspace, then a single panel of 5 quickAction links. There is no breadcrumb and no Route Map panel on this route.

  • Workspace heading (<h1> via WorkspaceHeading): "Studio Metrics & Analytics Instrumentation"
  • Summary (data-metrics-analytics-summary): describes per-KPI states, per-metric issue codes, and the gate
  • Instrumentation Evaluation Lane (<h2> data-mi-lane-heading): the load-states + evaluation form + result region
  • Footer quick actions (panel): 5 sibling quickAction links

States#

  • Loading — data-mi-loading "Loading instrumentation evaluator…" while the catalog request is in flight
  • Unauthorized — data-mi-unauthorized "Access restricted." on a 401/403 (admin scope required)
  • Error — data-mi-error "Could not load the instrumentation evaluator." on a non-OK catalog response or network failure
  • Ready (form) — catalog loaded: data-mi-enums counts (KPI directions / KPI states / issue codes) and the data-mi-form JSON form
  • Result — data-mi-result with the release-gate verdict, KPI summary + table, and metric summary + list
  • Validation — data-mi-evaluate-error for invalid JSON or a non-200 evaluate response

Interactions#

Instrumentation Evaluation Lane (form)#

  • Instrumentation JSON (textarea data-mi-payload, aria-label "instrumentation json") — payload of { kpis[{ kpiId, name, value, warningThreshold, criticalThreshold, direction }], metrics[{ metricId, name, hasOwner, hasUnit, cardinality, sampleCoverage }], gatePolicy{ maxCardinality, minSampleCoverage } }
  • Evaluate instrumentation (button data-mi-submit, type=submit) — POSTs the parsed payload to \${MI_ENDPOINT}/evaluate``

Result region#

  • Release gate (data-mi-gate, data-gate-passed) — PASS / BLOCKED, with data-mi-gate-reasons / data-mi-gate-reason list when blocked
  • KPI summary (data-mi-kpi-summary) and KPI table (data-mi-kpis, rows data-mi-kpi-row with data-kpi-state + data-mi-kpi-margin)
  • Metric summary (data-mi-metric-summary) and metric list (data-mi-metrics, rows data-mi-metric-row with data-instrumented)
  • Open Observability and Operational Dashboards workspace → /studio/observability-operational-dashboards
  • Back to Resilience and Error UX workspace → /studio/resilience-error-ux
  • Back to Background Jobs and Progress UX workspace → /studio/background-jobs-progress-ux
  • Back to Asset Preview Pipeline workspace → /studio/asset-preview-pipeline
  • Back to Activity and Change Feeds workspace → /studio/activity-change-feeds

Data & contracts#

  • Reads: GET /v1/admin/studio/metrics-instrumentation (catalog: kpiDirections, kpiStates, metricIssueCodes) on mount
  • Writes: POST /v1/admin/studio/metrics-instrumentation/evaluate
  • Realtime: none
  • Client fetch: buildBffAuthHeaders(), cache: 'no-store', abort-on-unmount
  • Auth/role check: admin-scoped, fail-closed (401/403 → unauthorized); route is signed-in + studio via the proxy gate

Cross-references#

Open questions / known gaps#

  • Confirm where the /v1/admin/studio/metrics-instrumentation BFF route sources its evaluator (engine module + which admin:* scopes)
  • Document whether evaluated gate verdicts persist anywhere or are request-scoped only