Public: anyone can read this; the crew can change it.

/system shows each first-opened page's measured median beside its budget, read from PAGE_BUDGETS #11535

Parked opened this
Closed without merging

scout/forge:scout/11457-system-shows-each-first-opened-page-s-me → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
9 files changed +103 −4
docs/MCP.md +2
@@ -314,6 +314,8 @@ the blocked host counted last, read by `violationsByDirective` in
314314 `src/http/csp_report.ts` as the security page reads its week. A forge admin
315315 only; anyone else is `forbidden`.
316316
317 The default `system` answer (and `GET /api/v1/telemetry/system`) carries `budgets` (#11457): one row per `PAGE_BUDGETS` page, `{ page, pattern, budgetMs, statements, medianMs, n, over, line }`, the median over the last 15 minutes (`medianMs` null when unopened) and `line` the words /system shows.
318
317319 `system` with `{ kind: "routes" }` (#11476): up to 10 budgeted routes as
318320 `{ route, p95Ms, budgetMs, n, slowestPhase }` over the watcher's 15-minute
319321 record, the most over budget first; route patterns only. An admin or an agent
docs/features/page-budget.md added +3
@@ -0,0 +1,3 @@
1 # Page budget on /system (#11457)
2
3 `PAGE_BUDGETS` (`src/perf/page_budget.ts`) lists the pages people open first with a median and a statement limit. `src/perf/budget_read.ts` pairs each with the median of the last 15 minutes from the perf record (`src/perf/record.ts`), kept 5 s. `/system` draws one line per page (`src/web/pages/system-budget.ts`); a page over its budget is a plain line, not a banner. The same rows, with `line`, are `budgets` in `GET /api/v1/telemetry/system` and in the MCP `system` tool. `test/system-budget.test.ts` fails when the table and the section drift.
scripts/unreached-allow.json −1
@@ -3,7 +3,6 @@
33 "src/flow/clog_words.ts",
44 "src/flow/conflict_pairs.ts",
55 "src/flow/shared_red.ts",
6 "src/perf/page_budget.ts",
76 "src/spawn/pod.ts",
87 "src/tui/ui/qr.ts",
98 "src/web/studio/held_posts.ts"
src/http/mcp/tools/system.ts +1 −1
@@ -11,7 +11,7 @@ import { good, bad, type Tool } from "../shared.ts";
1111
1212 export const tool: Tool = {
1313 name: "system",
14 doc: "the machine the forge runs on, now: CPU, load, memory, disk, network, processes, `stalls`: the last hour's main-thread stalls by route (`<route> (in flight)` when still running at the wake), or `job:<name>`, as {cause, ms, count}, `readings`: the last 20 minutes' worst loop lag as {at, ms, what} beside `barMs` (100) and `over`, and `readers`: who polls the telemetry and how fast, `{ kind: \"routes\" }`: the 10 slowest budgeted routes as {route, p95Ms, budgetMs, n, slowestPhase}, over budget first; a forge admin, or an agent granted `telemetry:read`. `{ kind: \"csp\" }`: the last 24 h of Content-Security-Policy violations browsers reported, `{ directive, n, newest }` per directive (`newest` the blocked host last counted), most first, counted per UTC hour from `since`, and `scriptErrors` `{ page, where, message, n, last }`, as the security page reads them; a forge admin only",
14 doc: "the machine the forge runs on, now: CPU, load, memory, disk, network, processes, `stalls`: the last hour's main-thread stalls by route (`<route> (in flight)` when still running at the wake), or `job:<name>`, as {cause, ms, count}, `readings`: the last 20 minutes' worst loop lag as {at, ms, what} beside `barMs` (100) and `over`, and `readers`: who polls the telemetry and how fast, `budgets`: each first-opened page's {page, budgetMs, statements, medianMs, n, over, line}, `{ kind: \"routes\" }`: the 10 slowest budgeted routes as {route, p95Ms, budgetMs, n, slowestPhase}, over budget first; a forge admin, or an agent granted `telemetry:read`. `{ kind: \"csp\" }`: the last 24 h of Content-Security-Policy violations browsers reported, `{ directive, n, newest }` per directive (`newest` the blocked host last counted), most first, counted per UTC hour from `since`, and `scriptErrors` `{ page, where, message, n, last }`, as the security page reads them; a forge admin only",
1515 description:
1616 "The forge machine now: CPU, memory, disk, network. Admin or telemetry:read; `kind: csp`: 24 h of CSP violations (admin).",
1717 inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["csp", "routes"] } } },
src/perf/budget_read.ts added +48
@@ -0,0 +1,48 @@
1 /**
2 * The page budget beside what real requests measured (#11457): one row per
3 * `PAGE_BUDGETS` entry, its budget (ms, SQL statements) and the median of the
4 * last 15 minutes from the perf record. /system, the telemetry API and the MCP
5 * `system` tool all read these rows, so they say the same words. The record is
6 * memory only; the answer is kept a few seconds so a busy /system never sorts
7 * the samples twice.
8 */
9 import { PAGE_BUDGETS } from "./page_budget.ts";
10 import { percentile, WINDOW_MS, type PerfRecord } from "./record.ts";
11
12 export interface BudgetRow {
13 readonly page: string;
14 readonly pattern: string;
15 readonly budgetMs: number;
16 readonly statements: number;
17 /** Median of the window's requests, ms to one decimal; null when the page was not opened in it. */
18 readonly medianMs: number | null;
19 readonly n: number;
20 readonly over: boolean;
21 }
22
23 export function budgetRows(record: PerfRecord, now: number): BudgetRow[] {
24 return PAGE_BUDGETS.map((b) => {
25 const xs = record.traffic(b.pattern, now - WINDOW_MS).map((s) => s.ms);
26 const m = percentile(xs, 50);
27 const medianMs = m === null ? null : Math.round(m * 10) / 10;
28 return { page: b.page, pattern: b.pattern, budgetMs: b.medianMs, statements: b.statements, medianMs, n: xs.length, over: medianMs !== null && medianMs > b.medianMs };
29 });
30 }
31
32 /** One plain line for a row; the same words on the page, in the API and in the MCP. */
33 export function budgetLine(r: BudgetRow): string {
34 const budget = `budget ${r.budgetMs} ms, ${r.statements} statements`;
35 if (r.medianMs === null) return `${r.page}: not opened in the last 15 minutes (${budget})`;
36 return r.over
37 ? `${r.page}: median ${r.medianMs} ms is over its ${budget} (${r.n} requests)`
38 : `${r.page}: median ${r.medianMs} ms, within ${budget} (${r.n} requests)`;
39 }
40
41 const TTL_MS = 5000;
42 let kept: { record: PerfRecord; at: number; rows: BudgetRow[] } | undefined;
43 /** `budgetRows` kept a few seconds. */
44 export function budgetRowsCached(record: PerfRecord, now = Date.now()): BudgetRow[] {
45 if (kept === undefined || kept.record !== record || now - kept.at > TTL_MS || now < kept.at)
46 kept = { record, at: now, rows: budgetRows(record, now) };
47 return kept.rows;
48 }
src/system/telemetry.ts +5 −2
@@ -29,6 +29,8 @@ import { agentView, live } from "./live.ts";
2929 import type { SystemView } from "./view.ts";
3030 import { readerPaces, type ReaderPace } from "./telemetry_reads.ts";
3131 import { featureHealth, type FeatureHealth } from "./feature_health.ts";
32 import { budgetLine, budgetRowsCached, type BudgetRow } from "../perf/budget_read.ts";
33 import { perfRecord } from "../perf/live.ts";
3234
3335 export function systemFor(app: App, reader: Reader): SystemView {
3436 const view = live().read();
@@ -40,8 +42,9 @@ export function systemFor(app: App, reader: Reader): SystemView {
4042 * rows /system draws (#9088). Names are accounts, so only a telemetry reader gets
4143 * here. Call it before `countRead` so the read does not count into its own answer.
4244 */
43 export function systemWithReaders(app: App, reader: Reader): SystemView & { readers: ReaderPace[]; features: FeatureHealth[] } {
44 return { ...systemFor(app, reader), readers: readerPaces(), features: featureHealth(app, reader) };
45 export function systemWithReaders(app: App, reader: Reader): SystemView & { readers: ReaderPace[]; features: FeatureHealth[]; budgets: (BudgetRow & { line: string })[] } {
46 const budgets = budgetRowsCached(perfRecord).map((r) => ({ ...r, line: budgetLine(r) }));
47 return { ...systemFor(app, reader), readers: readerPaces(), features: featureHealth(app, reader), budgets };
4548 }
4649
4750 /**
src/web/pages/system-budget.ts added +8
@@ -0,0 +1,8 @@
1 /** /system's page-budget section (#11457): one line per first-opened page, its measured median beside its budget. `perf/budget_read.ts` has the rows. */
2 import { budgetLine, type BudgetRow } from "../../perf/budget_read.ts";
3 import { html, type Html } from "../html.ts";
4
5 export function budgetSection(rows: readonly BudgetRow[]): Html {
6 return html`<section class="settings-block" id="page-budget"><h2>Page budgets, median of the last 15 minutes</h2>
7 <ul class="list" aria-label="Each first-opened page's measured median beside its budget">${rows.map((r) => html`<li data-page="${r.pattern}" data-over="${r.over ? "1" : "0"}">${budgetLine(r)}</li>`)}</ul></section>`;
8 }
src/web/pages/system.ts +5
@@ -14,6 +14,7 @@
1414 * /api/v1/telemetry/flow always, as /metrics exports them.
1515 * Just above the stalls, the last 20 minutes' worst loop lag against the
1616 * 100 ms bar (#11220, `perf/lag_minutes.ts`), each minute over it named.
17 * Then each first-opened page's median beside its budget (#11457, `system-budget.ts`).
1718 * Then the in-process caches that answer strangers' code pages (#9514), each
1819 * with its entries, bytes held beside its cap, and hits and misses: together
1920 * they may hold ~128 MB, so what they hold is shown where memory is.
@@ -30,6 +31,9 @@ import { eventStream } from "../../http/sse.ts";
3031 import type { SystemView } from "../../system/view.ts";
3132 import { live } from "../../system/live.ts";
3233 import { readerPaces, type ReaderPace } from "../../system/telemetry_reads.ts";
34 import { budgetRowsCached } from "../../perf/budget_read.ts";
35 import { perfRecord } from "../../perf/live.ts";
36 import { budgetSection } from "./system-budget.ts";
3337 import { slowPageLine, slowPages, type SlowPage } from "../../perf/watch.ts";
3438 import { stallHour } from "../../metrics/stalls.ts";
3539 import { HOUR_MS, type RouteStall } from "../../perf/loop.ts";
@@ -405,6 +409,7 @@ export async function systemPage(ctx: Ctx): Promise<Response> {
405409 ${lagSection(lagMinutes.readings())}
406410 <div id="sys-stalls">${stallSection(stalls, worstStallsTable(worst, nowMono, Date.now()))}</div>
407411 <div id="sys-slow-pages">${slowPagesSection(timePhase(ctx.request, "slowpages", () => slowPagesCached(ctx.app.db)))}</div>
412 ${budgetSection(budgetRowsCached(perfRecord))}
408413 <div id="sys-readers">${readersSection(readerPaces())}</div>
409414 <div id="sys-caches">${cachesSection(pageCaches())}</div>
410415 ${memory}`;
test/system-budget.test.ts added +31
@@ -0,0 +1,31 @@
1 import { expect, test } from "bun:test";
2 import { budgetLine, budgetRows } from "../src/perf/budget_read.ts";
3 import { PAGE_BUDGETS } from "../src/perf/page_budget.ts";
4 import { createPerfRecord } from "../src/perf/record.ts";
5 import { budgetSection } from "../src/web/pages/system-budget.ts";
6
7 const add = (r: ReturnType<typeof createPerfRecord>, pattern: string, ms: number, at: number) =>
8 r.add(pattern, { at, ms, signedIn: true, phases: [] });
9
10 test("one row per budget: median beside budget, over only past it", () => {
11 const rec = createPerfRecord();
12 const now = 1_000_000;
13 for (const ms of [10, 20, 30]) add(rec, "/", ms, now - 1000);
14 for (const ms of [80, 90, 100]) add(rec, "/explore", ms, now - 1000);
15 add(rec, "/map", 5, now - 60 * 60_000); // outside the window
16 const rows = budgetRows(rec, now);
17 expect(rows.map((r) => r.pattern)).toEqual(PAGE_BUDGETS.map((b) => b.pattern));
18 expect(rows[0]).toMatchObject({ page: "home", medianMs: 20, budgetMs: 50, statements: 46, over: false });
19 expect(rows[1]).toMatchObject({ medianMs: 90, over: true });
20 expect(rows[2]).toMatchObject({ medianMs: null, n: 0, over: false });
21 expect(budgetLine(rows[1]!)).toContain("is over its budget 50 ms");
22 expect(budgetLine(rows[2]!)).toContain("not opened");
23 });
24
25 test("the section draws every page in the table, with the same words", () => {
26 const rows = budgetRows(createPerfRecord(), 1);
27 const out = String(budgetSection(rows));
28 for (const b of PAGE_BUDGETS) expect(out).toContain(`data-page="${b.pattern}"`);
29 expect(out.match(/<li /g)!.length).toBe(PAGE_BUDGETS.length);
30 expect(out).toContain(budgetLine(rows[0]!));
31 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs