Repository navigation
feat(telemetry): pick the Telemetry panel's time window - #16031
Conversation
|
Intent: Let the Telemetry panel reader choose the span every card reports on (24h to 90d presets or a custom date range), with each card labelled by the window the gateway actually measured. |
Design Review (Opus 5.5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Default and the 14d pick both say "Last 14d" but can show different numbers, because Default counts whole shards and a pick filters each point. Watch
[DESIGN-REVIEWED] 2e3cdbe Description read[DESCRIPTION-READ] 36a4c6a993e074f6bea9b71652be86039cccca5ac1d728f53ea63a6a7526955a That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5, fork) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS "Default" doesn't say which span it covers: on the same screen it shows a 7-day spend card next to a 14-day health strip and footer. Watch
[UX-REVIEWED] 2e3cdbe Description read[DESCRIPTION-READ] 4e29ea4c9a58e27dac29db7511b1d987e08efb92fe009405dad1044312cc9b42 That sha256 names everything this verdict read: the PR description, plus the 16 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check before merge: What this change shipsInventory (10 items) — 10 justifiedIntent: let a Telemetry panel reader choose the time span every card reports on (24h–90d or custom dates). ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 2e3cdbe Description read[DESCRIPTION-READ] 55240f0f5238e99c354b61176dbbb68fc8890ce2b61a9bf02331eef67addd5d8 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
c74ba85 to
82070d3
Compare
|
|
|
|
|
|
|
|
|
Design and First Principles both asked whether raising the |
82070d3 to
184e621
Compare
|
|
|
|
|
|
No code change in this round. GPT and Opus have no findings on a153a82, and the five new advisory items get one reply each below. SAST (Semgrep) failed on a finding in |
a153a82 to
a98bb05
Compare
|
Rebased on main as a98bb05, no behaviour change. The only conflict was the telemetry row in docs/feature-map/README.md: kept main's system row and this PR's telemetry row. Feature-map, catalog and metrics tests pass locally (1,059). SAST may still fail on main's #13374 test file, which this PR does not touch. |
|
Rebased on main as 5575fad, no behaviour change. The only conflict was in |
|
Replies to the round 14 reviews on 5575fad. The description changed and no code changed. note: The UX Review BLOCK listed three evidence gaps, and the description now carries four stills that close them. They were captured from a build of 5575fad and sit in a new "Telemetry off, Startup under the retention cap, Context on a custom range" fold.
The "Default" label point under Watch was answered in earlier rounds and is kept as ruled. note: First Principles item 7 is fixed in the description. Backwards compatibility now says that every caller of note: First Principles item 6 is unchanged. The Design note in the description states the Spend card and Sessions table divergence and why moving the Sessions table onto the pick is out of scope. The review says it clears when a maintainer accepts it. |
|
Rebased on main as 8e7ce91, no behaviour change. The only conflict was in |
|
issue (blocking, security): DST offset reuse in Upheld and fixed in e29df39.
The OTEL reader |
|
Rebased on main as de86198, no behaviour change. The only conflict was the key lists in website/src/i18n/en.context.json, where main added an aboutPanel key next to this PR's seven telemetry keys; both are kept. i18n:check and the metrics tests pass locally. |
|
Rebased on main as 8b736c3, no behaviour change. The only conflict was the key lists in website/src/i18n/en.context.json, where main added pages.chatSidebar.crew_status_disabled next to this PR's seven telemetry keys; both are kept. i18n:check and the metrics plus telemetry time-window tests (977) pass locally. |
|
|
|
|
|
|
|
Rebased on main as 1e06531, no behaviour change. The only conflict was the key lists in website/src/i18n/en.context.json, where main added guide-layer keys next to this PR's seven telemetry keys; both are kept. i18n:check, the metrics tests (977) and the MarkdownRenderer golden DOM test pass locally. |
|
Regenerated src/kiro_crew/docs/ui-index.generated.json on the rebased head. Build Wheel, both Build Desktop jobs and E2E failed on 1e06531 because |
One window control at the top of the Developer > Telemetry panel drives every card: presets (24h, 7d, 14d, 30d, 90d) or a custom start/end date. GET /api/telemetry/startup and /api/usage/turns accept days or since/until, clamp to a 90-day ceiling instead of refusing, and echo the effective window so each card labels what it measured. Spend compares against the equal-length period before the window; caches key on it.
|
Rebased on main as 2e3cdbe, no behaviour change. Two conflicts, both resolved by keeping both sides: the key lists in website/src/i18n/en.context.json, and telemetry.ts, where main added a usageSeries call next to this PR's usageTurns range parameter. Main's #18793 fixed the i18n-render base-stamp failure that kept E2E red on d46b75f. Locally tsc, i18n:check, 1466 vitest tests and the 977 test/metrics tests pass. |
iamwhatever
left a comment
There was a problem hiding this comment.
This PR adds one Period control to Developer > Telemetry (Default, 24h through 90d, or a custom date pair). It is backed by a single resolve_window in handlers/usage.py that turns days / since / until into a clamped [start, end), and every reader (cost_breakdown, context_occupancy, slot_turn_usage, the metric-shard aggregator) now cuts at the window's end as well as its start. I read all the backend and frontend production code at 2e3cdbe: telemetry.py, usage.py, TelemetryPanel.tsx, telemetryRange.ts, the API client and the SegmentedControl stacking fix. Default sends no parameters and keeps main's 7d spend and 14d OTEL and context windows, including the whole-shard read. I tried to break the clamp. NaN, inf, huge days, a far-past since, a future until and inverted or empty ranges all land inside the 90-day floor and the minute ceiling. Caches key on the window, so a week is never served as a month. The per-point nanosecond filter compares integers, and the drill-down refetches the bounds the payload reports it measured. The one security-relevant change is that the app-granted /api/usage/turns ceiling rises from 7 to 90 days and the route accepts since/until. I checked that the per-row app filter and the slot requirement are unchanged, so an app still reads only its own rows, which the store already keeps. Every open Design, UX and First Principles item has a disposition: Default-vs-14d boundary parity is kept for main parity, and the Sessions-table spend divergence is deferred and documented. Base is main, it is mergeable, checks and both code lanes are green, and nobody has requested changes. — crew-pr-reviewer (deep re-check)
Problem / Motivation
Goal: Let the reader of Developer > Telemetry pick the time span the panel reports on, from 24 hours to 90 days or any custom pair of dates.
Every card on the panel used a window fixed in code. Spend showed 7 days; context occupancy and the OTEL cards (health strip, latency, startup) showed 14. There was no way to ask what last month cost, or to look at one bad week in September.
Why it matters
Spend questions are rarely "the last 7 days". People ask about a sprint, a month, or the week a model switched. Today they read shard files by hand to answer that. The two fixed windows also put a 7-day spend total beside a 14-day turn count with no shared span; one pick now gives every card the same span.
Not a goal
telemetry.retention_days./api/telemetry/context-trace). It serves the Context breakdown pages, not this panel, and keeps its 14-day lookback.What changed (motivation → approach → change)
GET /api/telemetry/startupdays=N(rolling, ends now) orsince/untilin epoch seconds. The panel sends local midnights, so the browser's timezone decides what a day is. A named window drives every block. With no parameters the answer is main's: OTEL and context over 14 days, spend over 7, flaggedwindow_default: truewithcost_window_days.GET /api/usage/turnsdays(no start/end echo; nothing reads one). A session row's turn drill-down is fetched over the bounds the panel payload reports it measured, not over the request, so it lists the turns that row summed. On Default it reads the spend week.daysis at least 1 day and at most 90 (MAX_WINDOW_DAYS); a fixed start is clamped to 90 days back, the end to now. Inverted ranges are swapped and an empty one becomes the day before its end. The custom picker offers start days back to 89 days before today, so a picked range holds at most 90 whole dates, all inside the clamp. When a DST fall-back adds an hour to that span, the earliest day moves up one so its midnight stays inside the gateway'snow - 90 x 24hfloor. Emptying one date input resets only that date (start to a week before the end, end to today).window_days,window_start,window_endandwindow_rolling. Card titles are built from those, so a clamped pick shows what was actually measured. When the window starts beforetelemetry.retention_days, a line under the control says so ("Turn, latency and startup figures cover only the last 14d; older metrics are deleted", naming the setting throughSettingRef), and the health, latency and startup cards title themselves with the span the kept shards cover. The "OTEL sections · period:" footer names that same capped span, not the pick.In
src/kiro_crew/dashboard/handlers/usage.py,resolve_windowis the one place that turns query parameters into a[start, end)window.cost_breakdown,context_occupancy,slot_turn_usageand the metric-shard aggregator take an optionaluntil, so rows after the end of a past range are dropped too. Before, every reader only cut at the start. For a named window the metric reader inhandlers/telemetry.pyalso filters each data point by its owntime_unix_nano, because shard files cover a whole UTC day. That filter compares integers: the window's bounds are converted once to whole epoch nanoseconds (exact, throughFraction), and each point's timestamp is read with the exact integer reader, because a 2026 epoch in nanoseconds (~1.79e18) is past float's 2**53 range, where neighbouring floats are 256 ns apart. A point with no timestamp counts only when its shard's whole day is inside the window. On Default it counts every point of the picked shards, as main does. Spend still compares against the equal-length period right before the window, whichever way the window is anchored.Design note: the Sessions table and the Spend card agree only on Default. On main,
SPEND_WINDOW_DAYSwas the one window both sums used, so they could not report different totals for one session. The Sessions table still gets its spend fromslot_spend(), which the session-memory sampler calls with no arguments, so it always sums the last 7 days ending now. The Spend card's per-conversation rows come fromcost_breakdownover the picked window. With 30d picked, a session's row on the Spend card counts 30 days of turns and its Sessions-table cell counts 7; with a past custom range the two can share no turns at all. Moving the Sessions table onto the panel's pick would need the pick on the server (the table is polled from a different page), so it stays out of this PR. The comment onSPEND_WINDOW_DAYSstates the same narrowing.Caches key on the window. A rolling window keys on its length, so the 5s poll keeps hitting the cache while "now" moves. A fixed range's end rounds up to the minute for the same reason. In
website/src/pages/TelemetryPanel.tsxthe query key carries the range too (preset and date math lives inpages/telemetryRange.ts, the client inwebsite/src/api/client/telemetry.tspasses the range through), so a cached week is never served as a month.website/src/components/SegmentedControl.tsxno longer gives each segment button its own z-index. Each button was a stacking context, so the moving highlight painted over the label of every segment it passed (picking 90d from 7d blanked "30d"). The radio group is nowisolateand the labels sit above the highlight in one context. This touches every SegmentedControl; the one inline DOM golden that renders it is updated. The control also gainswrap="hug": the group wraps but keeps each segment at its content width and is no wider than its segments. The existingwrap(stretch to fill each row, used by the tag manager's policy picker) is unchanged.The spec in
docs/system-specs/modules/metrics.mdand the feature-map row describe the new parameters. New strings are translated in all 12 catalogs underwebsite/src/i18n/locales(en-XA regenerated), with translator notes inwebsite/src/i18n/en.context.json. Existing strings keep main's wording. The new strings say "period" to match the control's label:range_label, the empty-panel lineno_telemetry_in_windowand the footerwindow_footer.telemetry.retention_daysis added to the SettingRef schema fixture (website/src/test/fixtures/settingref-schema.json) so the retention line's setting reference resolves; the key already exists in the backend schema.Backwards compatibility
Compatible. Both endpoints answer a request with no parameters exactly as main does, and the panel opens on Default, so no card's visible window changes until the reader picks one.
dayson/api/usage/turnsis still accepted; its ceiling rises from 7 to 90. This widens the endpoint for every caller, not only the panel: any client of/api/usage/turns, apps included, can now read up to 90 days of turns and can pass a fixedsince/untilrange./api/telemetry/startupgains the fieldswindow_start,window_end,window_rolling,window_default,cost_window_daysandmetrics_retention_days. The 90-day ceiling lives in one constant per side (MAX_WINDOW_DAYSin the gateway,MAX_RANGE_DAYSin the panel) and is not sent in the payload.Tests
test/metrics/test_telemetry_time_window.py(new; every test runs on one pinned instant shared by the test and the handlers'time/datetimereads):resolve_windowclamping for every out-of-range case including the one-day floor, both ends of a fixed range on each reader, the equal-length prior period, cache keys that differ per window, per-point filtering of metric shards (including points 1 ns before, at and after each bound of a 2026 range), the route handing one window to every block, a request with no window keeping main's 7-day spend and 14-day OTEL and context windows, and that request counting every point of the in-window shards (as main does) while an explicitdays=14drops the points past the window's start.test/test_telemetry_handlers_cov80.py,test/metrics/test_usage_turns.pyand two shard-stub fixtures follow the new signatures; thedaysclamp test keeps its1 <=floor.website/src/test/TelemetryPanel.timeRange.test.tsx(new;Dateis pinned to one local instant for the panel and the expectations): the panel opens on Default with no window requested and per-card titles, a pick refetches with the right query and persists, custom ranges go out as epoch bounds and title the cards with their dates, the custom picker's earliest day keeps the range to 90 dates, clearing one date keeps the other, the control stays on screen when a window is empty, the loading line carries text only while a new pick is in flight and its row is the same element, with the same full-row fixed-height classes, before, during and after the load, and the retention line (with the setting reference kept clear of the brackets around it, the "cover only the last 14d; older metrics are deleted" wording and the day count said once), the capped card titles and the capped footer appear only when the window starts before the retention cut.website/src/test/telemetryRange.test.ts(new): Default, preset and custom query building, the earliest custom day (including a New York DST fall-back night), the measured-window query, inclusive end dates, invalid dates.TelemetryPanel.turnsDrilldown.test.tsx: the drill-down passes the measured window, keeps the shown window while a new pick loads, and reads the spend week on Default.SegmentedControl.indicatorLayout.test.tsx: no segment button carries a z-index and the group is isolated.SegmentedControl.wrapHug.test.tsx(new):wrap="hug"sizes segments to content and does not stretch the group;wrapstill stretches. The panel test also checks the period control uses the content-sized form.Manual verification
Earlier I rendered the built dist against payloads this machine's own stores produced through the new handler (7d, 30d, and 15 to 21 Sep): 453,214 credits for 30d against 227,585 for 7d. The screenshots below were captured on the current head: an isolated gateway from
kiro_crew.testing.harness.spawn_feature_gateway(fixtureminimal) serving this branch's built dist, with/api/telemetry/startupanswered by fixture payloads so each state (retention cut, empty window, in-flight pick) can be shown on demand. During the in-flight captures the script read the top of the first card before the click, while the response was held, and after it landed: 182.6px at all three points at 1280px, and 267.8px at all three at 390px, so the loading line no longer moves the cards.Screenshots / video
Default, as the panel opens. Spend says "Last 7d" and the health strip "Last 14d", as on main:
Custom range, 12 to 18 Sep. Every card title names the dates:
30d on an install with
telemetry.retention_days = 14. The line under the control says the OTEL figures stop at 14 days:A 24h pick with nothing recorded keeps the control on screen:
In-flight pick, 390px, German at 320px, full height with footer
90d clicked from 30d with its response held: the highlight sits on 90d, every other label stays readable, the figures are still 30d's and the loading line is shown:
The same at 390px:
Default at 390px:
7d, full height, footer naming the period:
Telemetry off, Startup under the retention cap, Context on a custom range
Telemetry off with no usage data, 30d picked. The period control stays above the "Telemetry is off" notice:
Telemetry off with local usage data, 30d picked. Credits and Context window title themselves "Last 30d" and the off banner sits below them:
The Startup tab with 30d picked and
telemetry.retention_days = 14. The Session startup card and the footer say "Last 14d":The Context tab on a custom range, 12 to 18 Sep. The card title names the dates:
Related Issues
no linked issue: requested directly by the repo owner's team, no tracking issue filed.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)