The trend tools answer in time buckets sized to the window: a day of get_file_io_trend is 34 KB, not 1.4 MB (#3897)

[erikdarlingdata]

Closes #3897. Closes #3962.

Why

The trend tools returned every collection in the window, so an answer's size was window × cadence × series. Measured on DARLING01:

• get_file_io_trend at its 24 h default (SQL2022) was 12,500 points and 1.4 MB, and a week was 9.8 MB.
• get_lock_wait_trend was 349 KB (2 MB over a week), and 96% of its rows (3,368 of 3,523) were zeros.
• get_pg_io_trend / get_pg_database_trend were 448 KB / 294 KB over a day.

The store was never the bottleneck. EXPLAIN ANALYZE of every read on DARLING01 came in at 270 ms or less at 168 h. The one exception is get_pg_io_trend's automatic subject choice (3.8 s at 168 h, filed as #3961).

Where the diagnosis needed correcting (measured)

• File I/O. get_file_io_trend already capped itself at the top 10 files, so the "600 files → about 30 MB" extrapolation does not hold. What scaled it was the window: 9.8 MB at 168 h on any server. It also published indistinguishable rows. tempdb's nine data files shared one database name per timestamp, which accounts for 11,250 of 12,500 rows, and the web chart's pivot kept one of each.
• Lock waits. get_lock_wait_trend does scale with the number of LCK types: one row per type per collection.
• Rollups. Only query_stats and procedure_stats have a rollup tier, and the duration pair already routes to it. None of the other three reads has anything to route to.

What changes

One shared contract (PerformanceMonitor.Common/Mcp, both SKUs):

• TrendBuckets picks the width from a ladder (1, 2, 5, 10, 15, 30 minutes, 1 to 24 hours).
  • It takes the narrowest width that keeps the answer within 200 points, counted across series and including the edge bucket.
  • bucket_minutes (1–1440) asks for another width, up to a per-read cap sized so the largest answer stays under 256 KB.
  • A width out of range or over the cap is refused, never clamped, and the refusal names the narrowest width that fits.
  • PostgreSQL date_bin and DuckDB time_bucket share one origin, so both SKUs bin the same rows the same way.
• TrendPayloads builds the file I/O and lock-wait envelopes once for both SKUs.
• Every bucketed payload says what a point is: bucket, bucket_minutes, aggregate_note.
• Aggregation rules:
  • Counts are summed.
  • Rates are the bucket's summed work over its summed seconds.
  • Ratios are ratios of sums, never averages of averages.
  • peak_* / worst_* keep the single most extreme collection, so a spike survives.
  • A collection with no knowable interval is left out of both the numerator and the denominator, and is counted.

Per tool:

• get_file_io_trend
  • A line is a (database, file type) pair, ranked by the window's I/O stall.
  • The top five get their own lines. The rest fold into one (other) line, pooled collection by collection before bucketing. All lines are charted when there are six or fewer.
  • database_name narrows to one database, charted per file.
  • Latency is summed stall over summed operations: null over none, where it was a fabricated 0.00.
  • A series legend gives each line's window totals.
  • Restart rows (stored interval 0) neither rank nor chart.
• get_lock_wait_trend
  • The LCK family is one series, summed per collection over that collection's ONE interval.
  • A wait_types legend lists the types that waited, and wait_types_idle counts the rest.
  • A window of collected but idle types is a measured zero, not empty.
• get_query_duration_trend / get_procedure_duration_trend
  • The raw tier is time-weighted, with unknowable collections counted in unrated_collections.
  • The hourly tier gathers whole hours. A width that is not a whole number of hours is refused there.
  • peak_elapsed_ms_per_second is the busiest collection, or the busiest hour on the rollup.
  • effective_start is the first collection, not a bucket boundary.
• get_pg_io_trend / get_pg_database_trend
  • Intervals are gathered into buckets. point_count now counts buckets, and the new interval_count is the old count.
  • Every window figure is counted from the buckets' own sums, peaks and interval counts, so it is identical at any width. Those figures are resets, spilling intervals, the worst interval and when it happened, and the peak spill and read rates.
  • Per-point peak_* / worst_cache_hit_pct.

Surfaces:

• Web viewer. /api/read passes bucket_minutes through; an unparseable value is refused. It charts at a 1,500-point budget, so a day stays per-minute on one line. The file I/O panel pivots by line, and the PostgreSQL trend tables gain peak/worst columns.
• Lite. DuckDB twins live in LocalDataService.TrendBuckets.cs. The desktop charts' per-collection reads are untouched.
• get_query_heatmap. Its bucket_minutes and metric refusals (both SKUs) were bare sentences with no invalid status. They are now McpHelpers.Refusal.
• Refusal census (closes The refusal census cannot see a bare sentence returned through a private helper #3962). The two holes those bare sentences slipped through are closed:
  • It now walks every ?? operand, not just the first.
  • It follows a tool's return Helper(…) into the same-file helper and holds each result arm of that helper's return expressions to the bare-sentence and hand-built rules. Ternaries are split at depth zero and conditions excluded. 60 helpers are followed on the tree today, floored at 50, and a fixture proves the walk fires on the heatmap's old shape and not on its neighbours.
• Token budget (The MCP surface costs ~100k tokens of context before the first call: 157 tools, 336 KB of tools/list, 86 KB of instructions #3898). Instructions and descriptions are rewritten for the new shape. Descriptions, parameter descriptions and instruction rows for these tools, on both SKUs, total 508 characters fewer than before (24,824 → 24,316), bucket_minutes included.

Payload changes (deliberate, since "results identical" is not possible here)

• File I/O: a new grain and keys, as above.
• Lock waits: trend rows no longer carry wait_type; the per-type view is wait_types.
• Duration trends:
  • bucket is a width word.
  • aggregate_note is always set.
  • New keys: bucket_minutes, unrated_collections, peak_elapsed_ms_per_second.
  • The unrated_note sentence now counts collections, not points.
• PostgreSQL pair:
  • point_count counts buckets, and interval_count is new.
  • A point's interval_seconds is the seconds its intervals covered.
  • New per-point peak/worst keys.

No store migration.

Test plan

• Before → after on DARLING01 (read-only: my build's readers through a harness against the live store, 2026-09-22):

Tool	24 h default, before → after	168 h, before → after
get_file_io_trend (SQL2022)	1,398 KB → 34.3 KB	9,790 KB → 34.3 KB
get_lock_wait_trend (SQL2022)	349 KB → 17.9 KB	1,959 KB → 20.8 KB
get_query_duration_trend (SQL2022)	160 KB → 32.6 KB (72 h: 487 → 32.5 KB)	29.1 KB → 34.7 KB (hourly tier)
get_pg_io_trend (PG18)	448 KB → 54.2 KB	3,157 KB → 63.3 KB
get_pg_database_trend (PG18)	294 KB → 39.8 KB	2,046 KB → 46.4 KB

• Exactness on DARLING01, same fixed as_of, my build vs the deployed build:
  • The PostgreSQL window figures are identical, and interval_count equals the old point_count.
  • One-minute duration buckets equal the old per-collection rates on 1,251 and 1,237 buckets.
  • The hourly tier is identical at 60 minutes.
  • The lock family per minute equals the sum of the old per-type rates.
• Payload census (TrendPayloadBudgetLiveTests, new): a week of one-minute collections plus a 600-file server.
  • Every default answer is 8–69 KB, against a pinned ceiling of 80 KB.
  • The largest answer each read's cap admits is 196–249 KB, against a pinned ceiling of 320 KB.
  • The old reads fail it by an order of magnitude.
• New tests:
  • TrendBucketsTests: the width table, the budget invariant over every window (1–168 h) × line count (1–6) at both budgets, the edge bucket, the refusals naming the width that fits, and the hourly tier.
  • TrendBucketingLiveTests (Darling, live) and TrendBucketingToolTests (Lite) plant the same rows and assert the same hand-worked figures: the fold per collection, ratios of sums, null over no I/O, the restart row, time-weighting, unrated collections, and the window-start stamp.
  • The rewritten DarlingLockWaitTrendTests / LockWaitTrendToolTests: family plus legend, one interval per collection, and the all-idle window.
  • TryParseOptionalInt.
• Census and pin updates:
  • TrendBuckets producers are accepted as shared refusals, with executed shapes.
  • Every ?? operand is walked.
  • The Lite differenced-trend census covers the new file.
  • The shared unrated-note sentence is re-pinned.
• Full Darling suite, live (PostgreSQL 18.4 + TimescaleDB 2.28.1), on the final tree: 12,674 total, 0 failed, 22 skipped. Every skip is environment-gated: DARLING_TEST_SQL, DARLING_TEST_PGRUNTIME, the log target, or symlink rights.
• Full Lite suite: 5,131 total. 0 failed on the run before the rebase onto get_store_metrics returns ~1.9 MB by default (every store object × ~30 days) — ~500k tokens, larger than any agent context; even days_back=1 is 346 KB #3903/Lite's daily-summary contract test no longer fails in the first two minutes after midnight UTC #3963, which touched no Lite code under this change. The final run had 2 lock-timing failures, StatusBarSizeReadLockTests.GetUsedDataSizeMb_WhenTheWriteLockIsHeld_GivesUpInsteadOfBlocking and AnalysisPassTokenThreadingTests.TheReadLockWaitIsAbandonableWhileAWriterHoldsIt ("the writer never took the lock"). Both passed 3/3 when re-run alone: the known AnalysisPass threading flake family.
• 0 warnings, both test projects.

Folded in: #3962, the refusal census's helper blind spot.

Still open, and why:

• The rest of the trend family still returns every collection: a week of get_tempdb_trend is 2 MB, get_memory_trend 1.5 MB, get_wait_trend 1.1 MB #3960: the rest of the trend family. This is not a mechanical repeat. It covers five more tools across two SKUs, each with its own SQL, payload, web panel and tests. It also needs rulings on gauge points (average with max beside it), the memory trend's joined grant series, and perfmon's counter types.
• get_pg_io_trend's automatic subject choice reads every pg_io_stats row in order: 3.8 s over a week on DARLING01 #3961: get_pg_io_trend's default subject choice. The store's collation is already C, so the cheap fix that keeps the same semantics gains nothing (5.8 s vs 6.2 s). An endpoint form measured 0.30 s with an identical ranking. It needs a decision on reset detection, and TimescaleDB's first()/last() do not exist on a plain-PostgreSQL store.

🤖 Generated with Claude Code

https://claude.ai/code/session_018Z4T51J4E6L8fjriPHpsif