feat(inference): measured-power Y-axis metrics on scatter chart

Adds two new options under a new "Measured Energy" dropdown group on
both the "vs. Interactivity" and "vs. E2E Latency" charts:

  - Measured Avg Power per GPU (W)        — no roofline (no universal
                                             "better" direction)
  - Measured J per Output Token (J/tok)   — roofline lower_right
                                             (interactivity) / lower_left
                                             (e2e)

Distinct from the existing y_jTotal/y_jOutput/y_jInput which derive
joules from each GPU's spec-sheet TDP. The new metrics are sourced
from runner GPU telemetry averaged over the exact bench load window
(see aggregate_power.py in semianalysisai/InferenceX).

Wiring:

  - packages/constants/src/metric-keys.ts: register avg_power_w,
    joules_per_output_token in the canonical metric key set so the ETL
    auto-capture warning doesn't fire.
  - packages/app/src/lib/benchmark-transform.ts: pass the two raw
    fields through rowToAggDataEntry. Left undefined when absent so
    downstream code can distinguish "no measurement" from "0 W".
  - packages/app/src/components/inference/types.ts: extend AggDataEntry,
    InferenceData, YAxisMetricKey, and ChartDefinition.
  - packages/app/src/lib/chart-utils.ts: extend Y_AXIS_METRICS,
    createChartDataPoint (gated on typeof===number), calculateRoofline
    and computeAllRooflines yKey union, markRooflinePoints init+mark
    blocks.
  - packages/app/src/components/inference/inference-chart-config.json:
    add y_measured* entries to both chartTypes.
  - packages/app/src/components/inference/ui/ChartControls.tsx: add
    "Measured Energy" group to METRIC_GROUPS.

The overlay (unofficial run) path is automatic — transformBenchmarkRows
is shared between official and overlay rendering, so the new metrics
flow to ?unofficialrun= URLs once the runner-side PR is merged and
benchmarks ingest the new fields.

For rows without measured-power data (historical runs, runs predating
aggregate_power.py, runs where the SMI poller didn't start), points
are simply omitted from the new charts — the existing TDP-derived
y_jTotal/y_jOutput/y_jInput stay visible as a comparable fallback.

Verification:

  - pnpm typecheck: clean
  - pnpm lint: 0 warnings, 0 errors
  - pnpm test:unit: 1921/1921 passing (+7 new tests covering
    rowToAggDataEntry pass-through, createChartDataPoint field gating,
    zero-value preservation, missing-field handling)
  - Dev-server smoke: confirmed "Measured Energy" group label and
    both metric labels are present in the served JS bundle at
    /_next/static/chunks/

Follow-up: Cypress E2E covering both the official path and
?unofficialrun= overlay path for the two new metrics, to be added
once the runner PR ships real data to the DB.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: arygupt

packages/app/src/components/inference/inference-chart-config.json

@@ -88,6 +88,13 @@
     "y_jInput_label": "All-in Provisioned J per Input Token (J/tok)",
     "y_jInput_title": "All-in Provisioned Joules per Input Token",
     "y_jInput_roofline": "lower_right",
+    "y_measuredAvgPower": "measuredAvgPower.y",
+    "y_measuredAvgPower_label": "Measured Avg Power per GPU (W)",
+    "y_measuredAvgPower_title": "Measured Average Power per GPU",
+    "y_measuredJPerOutputToken": "measuredJPerOutputToken.y",
+    "y_measuredJPerOutputToken_label": "Measured J per Output Token (J/tok)",
+    "y_measuredJPerOutputToken_title": "Measured Joules per Output Token",
+    "y_measuredJPerOutputToken_roofline": "lower_right",
     "y_cost_limit": 5,
     "y_latency_limit": 60
   },
@@ -179,6 +186,13 @@
     "y_jInput_label": "All-in Provisioned J per Input Token (J/tok)",
     "y_jInput_title": "All-in Provisioned Joules per Input Token",
     "y_jInput_roofline": "lower_left",
+    "y_measuredAvgPower": "measuredAvgPower.y",
+    "y_measuredAvgPower_label": "Measured Avg Power per GPU (W)",
+    "y_measuredAvgPower_title": "Measured Average Power per GPU",
+    "y_measuredJPerOutputToken": "measuredJPerOutputToken.y",
+    "y_measuredJPerOutputToken_label": "Measured J per Output Token (J/tok)",
+    "y_measuredJPerOutputToken_title": "Measured Joules per Output Token",
+    "y_measuredJPerOutputToken_roofline": "lower_left",
     "y_cost_limit": 5,
     "y_latency_limit": 60
   }

packages/app/src/components/inference/types.ts

@@ -67,6 +67,10 @@ export interface AggDataEntry {
   median_e2el: number;
   std_e2el: number;
   p99_e2el: number;
+  // Measured GPU telemetry (emitted by runner's aggregate_power.py).
+  // Optional because historical runs predate the field.
+  avg_power_w?: number;
+  joules_per_output_token?: number;
   disagg: boolean;
   num_prefill_gpu: number;
   num_decode_gpu: number;
@@ -152,6 +156,12 @@ export interface InferenceData extends Partial<Omit<AggDataEntry, AggDataConflic
   jTotal?: { y: number; roof: boolean };
   jOutput?: { y: number; roof: boolean };
   jInput?: { y: number; roof: boolean };
+
+  // Measured power / energy from runner GPU telemetry. Optional because
+  // pre-aggregate_power.py runs (and runs with monitoring disabled) won't
+  // emit these fields.
+  measuredAvgPower?: { y: number; roof: boolean };
+  measuredJPerOutputToken?: { y: number; roof: boolean };
 }
 
 /**
@@ -177,7 +187,9 @@ export type YAxisMetricKey =
   | 'powerUser'
   | 'jTotal'
   | 'jOutput'
-  | 'jInput';
+  | 'jInput'
+  | 'measuredAvgPower'
+  | 'measuredJPerOutputToken';
 
 /**
  * Defines the configuration and labels for a specific chart.
@@ -277,6 +289,18 @@ export interface ChartDefinition {
   y_jInput_label?: string;
   y_jInput_title?: string;
   y_jInput_roofline?: 'upper_right' | 'upper_left' | 'lower_left' | 'lower_right';
+  // Measured power / energy from runner GPU telemetry
+  y_measuredAvgPower?: string;
+  y_measuredAvgPower_label?: string;
+  y_measuredAvgPower_title?: string;
+  // Intentionally no roofline for avg power: there's no universal "better"
+  // direction for absolute draw. Omitting roofline causes computeAllRooflines
+  // to skip the metric (it requires a direction); points render plain.
+  y_measuredAvgPower_roofline?: 'upper_right' | 'upper_left' | 'lower_left' | 'lower_right';
+  y_measuredJPerOutputToken?: string;
+  y_measuredJPerOutputToken_label?: string;
+  y_measuredJPerOutputToken_title?: string;
+  y_measuredJPerOutputToken_roofline?: 'upper_right' | 'upper_left' | 'lower_left' | 'lower_right';
   y_cost_limit?: number;
   y_latency_limit?: number;
 }

packages/app/src/components/inference/ui/ChartControls.tsx

@@ -46,6 +46,10 @@ const METRIC_GROUPS = [
   },
   { label: 'Cost per Million Input Tokens', metrics: ['y_costhi', 'y_costni', 'y_costri'] },
   { label: 'All-in Provisioned Energy per Token', metrics: ['y_jTotal', 'y_jOutput', 'y_jInput'] },
+  {
+    label: 'Measured Energy',
+    metrics: ['y_measuredAvgPower', 'y_measuredJPerOutputToken'],
+  },
   { label: 'Custom User Values', metrics: ['y_costUser', 'y_powerUser'] },
 ];
 

packages/app/src/lib/benchmark-transform.test.ts

@@ -115,6 +115,24 @@ describe('rowToAggDataEntry', () => {
     const entryNull = rowToAggDataEntry(makeRow({ image: null }));
     expect(entryNull.image).toBeUndefined();
   });
+
+  it('passes through measured power telemetry fields when present', () => {
+    const entry = rowToAggDataEntry(
+      makeRow({
+        metrics: { tput_per_gpu: 100, avg_power_w: 685.5, joules_per_output_token: 8.4 },
+      }),
+    );
+    expect(entry.avg_power_w).toBe(685.5);
+    expect(entry.joules_per_output_token).toBe(8.4);
+  });
+
+  it('leaves measured power fields undefined for rows that predate the metric', () => {
+    // Distinguishing "no measurement" from "0 W" matters: createChartDataPoint
+    // uses typeof===number to decide whether to emit the measuredAvgPower field.
+    const entry = rowToAggDataEntry(makeRow({ metrics: {} }));
+    expect(entry.avg_power_w).toBeUndefined();
+    expect(entry.joules_per_output_token).toBeUndefined();
+  });
 });
 
 describe('transformBenchmarkRows', () => {

packages/app/src/lib/benchmark-transform.ts

@@ -49,6 +49,11 @@ export function rowToAggDataEntry(row: BenchmarkRow): AggDataEntry {
     median_e2el: m.median_e2el ?? 0,
     std_e2el: m.std_e2el ?? 0,
     p99_e2el: m.p99_e2el ?? 0,
+    // Measured GPU telemetry (runner's aggregate_power.py). Left undefined for
+    // rows predating the field so downstream chart code can distinguish
+    // "no measurement" from "0 W" via createChartDataPoint's typeof guard.
+    avg_power_w: m.avg_power_w,
+    joules_per_output_token: m.joules_per_output_token,
     disagg: row.disagg,
     num_prefill_gpu: row.num_prefill_gpu,
     num_decode_gpu: row.num_decode_gpu,

packages/app/src/lib/chart-utils.test.ts

@@ -1218,6 +1218,55 @@ describe('createChartDataPoint energy fields', () => {
   });
 });
 
+// ===========================================================================
+// createChartDataPoint — measured power / energy fields (from runner telemetry)
+// ===========================================================================
+describe('createChartDataPoint measured power fields', () => {
+  it('emits measuredAvgPower when avg_power_w is present on the entry', () => {
+    const e = entry({ avg_power_w: 685.5 });
+    const point = createChartDataPoint('2025-01-01', e, 'median_e2el', 'tput_per_gpu', 'h100');
+    expect(point.measuredAvgPower).toBeDefined();
+    expect(point.measuredAvgPower!.y).toBe(685.5);
+    expect(point.measuredAvgPower!.roof).toBe(false);
+  });
+
+  it('emits measuredJPerOutputToken when joules_per_output_token is present', () => {
+    const e = entry({ joules_per_output_token: 8.4 });
+    const point = createChartDataPoint('2025-01-01', e, 'median_e2el', 'tput_per_gpu', 'h100');
+    expect(point.measuredJPerOutputToken).toBeDefined();
+    expect(point.measuredJPerOutputToken!.y).toBe(8.4);
+  });
+
+  it('omits both fields when neither is on the entry', () => {
+    // Legacy runs predating aggregate_power.py.
+    const point = createChartDataPoint(
+      '2025-01-01',
+      entry(),
+      'median_e2el',
+      'tput_per_gpu',
+      'h100',
+    );
+    expect(point.measuredAvgPower).toBeUndefined();
+    expect(point.measuredJPerOutputToken).toBeUndefined();
+  });
+
+  it('emits one and omits the other when only one is present', () => {
+    // Defensive: aggregator can patch only avg_power_w if total_output_tokens=0.
+    const e = entry({ avg_power_w: 500 });
+    const point = createChartDataPoint('2025-01-01', e, 'median_e2el', 'tput_per_gpu', 'h100');
+    expect(point.measuredAvgPower).toBeDefined();
+    expect(point.measuredJPerOutputToken).toBeUndefined();
+  });
+
+  it('preserves a zero measured power value (not falsy-coerced away)', () => {
+    // Guards against a refactor switching the gate from typeof===number to truthiness.
+    const e = entry({ avg_power_w: 0 });
+    const point = createChartDataPoint('2025-01-01', e, 'median_e2el', 'tput_per_gpu', 'h100');
+    expect(point.measuredAvgPower).toBeDefined();
+    expect(point.measuredAvgPower!.y).toBe(0);
+  });
+});
+
 // ===========================================================================
 // createChartDataPoint — boolean narrowing for prefill/decode dp_attention, is_multinode
 // ===========================================================================

packages/app/src/lib/chart-utils.ts

@@ -148,6 +148,10 @@ export const Y_AXIS_METRICS = [
   'y_jTotal',
   'y_jOutput',
   'y_jInput',
+  // Measured power / energy (sourced from runner's aggregate_power.py output;
+  // distinct from the spec-sheet TDP-derived jTotal/jOutput/jInput above).
+  'y_measuredAvgPower',
+  'y_measuredJPerOutputToken',
 ] as const;
 
 export type YAxisMetric = (typeof Y_AXIS_METRICS)[number];
@@ -389,6 +393,16 @@ export function createChartDataPoint(
           },
         }
       : {}),
+
+    // Measured power / energy from runner's aggregate_power.py. Gated on the
+    // raw fields existing so points from runs predating the measurement land
+    // without these keys and the chart correctly filters them out.
+    ...(typeof entry.avg_power_w === 'number'
+      ? { measuredAvgPower: { y: entry.avg_power_w, roof: false } }
+      : {}),
+    ...(typeof entry.joules_per_output_token === 'number'
+      ? { measuredJPerOutputToken: { y: entry.joules_per_output_token, roof: false } }
+      : {}),
   };
 }
 
@@ -549,7 +563,9 @@ export const calculateRoofline = (
     | `costri.y`
     | `jTotal.y`
     | `jOutput.y`
-    | `jInput.y`,
+    | `jInput.y`
+    | `measuredAvgPower.y`
+    | `measuredJPerOutputToken.y`,
   rooflineDirection: 'upper_right' | 'upper_left' | 'lower_left' | 'lower_right',
 ): InferenceData[] => {
   const pointsForRoofline = points.map((p) => {
@@ -619,7 +635,9 @@ export function computeAllRooflines(
             | `costri.y`
             | `jTotal.y`
             | `jOutput.y`
-            | `jInput.y`,
+            | `jInput.y`
+            | `measuredAvgPower.y`
+            | `measuredJPerOutputToken.y`,
           rooflineDirection,
         );
       }
@@ -663,6 +681,8 @@ export function markRooflinePoints(
       if (newPoint.jTotal) newPoint.jTotal.roof = false;
       if (newPoint.jOutput) newPoint.jOutput.roof = false;
       if (newPoint.jInput) newPoint.jInput.roof = false;
+      if (newPoint.measuredAvgPower) newPoint.measuredAvgPower.roof = false;
+      if (newPoint.measuredJPerOutputToken) newPoint.measuredJPerOutputToken.roof = false;
 
       for (const chartDefYKey of Y_AXIS_METRICS) {
         const rooflinePoints = computedRooflines[hwKey]?.[chartDefYKey];
@@ -722,6 +742,13 @@ export function markRooflinePoints(
           newPoint.jOutput.roof = onCurrentRoofline;
         } else if (chartDefYKey === 'y_jInput' && newPoint.jInput) {
           newPoint.jInput.roof = onCurrentRoofline;
+        } else if (chartDefYKey === 'y_measuredAvgPower' && newPoint.measuredAvgPower) {
+          newPoint.measuredAvgPower.roof = onCurrentRoofline;
+        } else if (
+          chartDefYKey === 'y_measuredJPerOutputToken' &&
+          newPoint.measuredJPerOutputToken
+        ) {
+          newPoint.measuredJPerOutputToken.roof = onCurrentRoofline;
         }
       }
       finalProcessedData.push(newPoint);

packages/constants/src/metric-keys.ts

@@ -43,4 +43,9 @@ export const METRIC_KEYS = new Set([
   'p99_intvty',
   'p99.9_intvty',
   'std_intvty',
+  // measured power / energy (emitted by runner's aggregate_power.py)
+  // avg_power_w: mean per-GPU draw (W) during the load window
+  // joules_per_output_token: avg_power_w * num_gpus * duration / total_output_tokens
+  'avg_power_w',
+  'joules_per_output_token',
 ]);