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
scout/forge:scout/11457-system-shows-each-first-opened-page-s-me → main 3 commits fork
9 files
changed +103
−4
docs/MCP.md +2
| @@ -314,6 +314,8 @@ the blocked host counted last, read by `violationsByDirective` in | ||
| 314 | 314 | `src/http/csp_report.ts` as the security page reads its week. A forge admin |
| 315 | 315 | only; anyone else is `forbidden`. |
| 316 | 316 | |
| 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 | ||
| 317 | 319 | `system` with `{ kind: "routes" }` (#11476): up to 10 budgeted routes as |
| 318 | 320 | `{ route, p95Ms, budgetMs, n, slowestPhase }` over the watcher's 15-minute |
| 319 | 321 | 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 @@ | ||
| 3 | 3 | "src/flow/clog_words.ts", |
| 4 | 4 | "src/flow/conflict_pairs.ts", |
| 5 | 5 | "src/flow/shared_red.ts", |
| 6 | "src/perf/page_budget.ts", | |
| 7 | 6 | "src/spawn/pod.ts", |
| 8 | 7 | "src/tui/ui/qr.ts", |
| 9 | 8 | "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"; | ||
| 11 | 11 | |
| 12 | 12 | export const tool: Tool = { |
| 13 | 13 | 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", | |
| 15 | 15 | description: |
| 16 | 16 | "The forge machine now: CPU, memory, disk, network. Admin or telemetry:read; `kind: csp`: 24 h of CSP violations (admin).", |
| 17 | 17 | 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"; | ||
| 29 | 29 | import type { SystemView } from "./view.ts"; |
| 30 | 30 | import { readerPaces, type ReaderPace } from "./telemetry_reads.ts"; |
| 31 | 31 | 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"; | |
| 32 | 34 | |
| 33 | 35 | export function systemFor(app: App, reader: Reader): SystemView { |
| 34 | 36 | const view = live().read(); |
| @@ -40,8 +42,9 @@ export function systemFor(app: App, reader: Reader): SystemView { | ||
| 40 | 42 | * rows /system draws (#9088). Names are accounts, so only a telemetry reader gets |
| 41 | 43 | * here. Call it before `countRead` so the read does not count into its own answer. |
| 42 | 44 | */ |
| 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 }; | |
| 45 | 48 | } |
| 46 | 49 | |
| 47 | 50 | /** |
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 @@ | ||
| 14 | 14 | * /api/v1/telemetry/flow always, as /metrics exports them. |
| 15 | 15 | * Just above the stalls, the last 20 minutes' worst loop lag against the |
| 16 | 16 | * 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`). | |
| 17 | 18 | * Then the in-process caches that answer strangers' code pages (#9514), each |
| 18 | 19 | * with its entries, bytes held beside its cap, and hits and misses: together |
| 19 | 20 | * they may hold ~128 MB, so what they hold is shown where memory is. |
| @@ -30,6 +31,9 @@ import { eventStream } from "../../http/sse.ts"; | ||
| 30 | 31 | import type { SystemView } from "../../system/view.ts"; |
| 31 | 32 | import { live } from "../../system/live.ts"; |
| 32 | 33 | 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"; | |
| 33 | 37 | import { slowPageLine, slowPages, type SlowPage } from "../../perf/watch.ts"; |
| 34 | 38 | import { stallHour } from "../../metrics/stalls.ts"; |
| 35 | 39 | import { HOUR_MS, type RouteStall } from "../../perf/loop.ts"; |
| @@ -405,6 +409,7 @@ export async function systemPage(ctx: Ctx): Promise<Response> { | ||
| 405 | 409 | ${lagSection(lagMinutes.readings())} |
| 406 | 410 | <div id="sys-stalls">${stallSection(stalls, worstStallsTable(worst, nowMono, Date.now()))}</div> |
| 407 | 411 | <div id="sys-slow-pages">${slowPagesSection(timePhase(ctx.request, "slowpages", () => slowPagesCached(ctx.app.db)))}</div> |
| 412 | ${budgetSection(budgetRowsCached(perfRecord))} | |
| 408 | 413 | <div id="sys-readers">${readersSection(readerPaces())}</div> |
| 409 | 414 | <div id="sys-caches">${cachesSection(pageCaches())}</div> |
| 410 | 415 | ${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 | }); |
new above
offline