---
path: /studio/metrics-analytics-instrumentation
surface: studio
domain: operations
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/metrics-analytics-instrumentation/page.tsx
status: walked
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)'
---

# Studio · Metrics and Analytics Instrumentation

## 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`)

### Footer quick actions

- [ ] **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

- Parent: [`../studio-overview.md`](../studio-overview.md)
- Sibling:
  [`studio-observability-operational-dashboards.md`](./studio-observability-operational-dashboards.md),
  [`studio-performance-budgets.md`](./studio-performance-budgets.md),
  [`../governance/studio-experimentation-feature-flags.md`](../governance/studio-experimentation-feature-flags.md)
- Source:
  `apps/oshun/web/src/components/studio/StudioMetricsAnalyticsInstrumentationWorkspace.tsx`

## 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