Repository navigation
feat(metrics): count app opens and foreground time from the owner's app pages - #39793
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check: the diff adds or changes nothing a user can see. It adds telemetry hooks and a background request, and every rendered branch is unchanged, so no screenshot is needed. [UX-REVIEWED] ff8b956 Description read[DESCRIPTION-READ] fe3db281344391071d8b17f8c8b4c55086a69b223f6a64af5a9d99c3e583dda9 That sha256 names everything this verdict read: the PR description, plus the 3 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 |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Additive and owner-gated: the page sends only the app name, the surface and whole seconds, and the server resolves the public id and version. The UI hooks draw nothing. Notes
[DESIGN-REVIEWED] ff8b956 Description read[DESCRIPTION-READ] a1210069c73e5efb1fc1d7a5e6f750f7b0e218e6d57544318dccaf5f696bc21a 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Every item adds telemetry behind consent, defaults stay unchanged, and the route follows the existing Notes
What this change shipsInventory (7 items) — 6 justifiedIntent: let maintainers and app authors tell an app that is installed from one that is actually opened and looked at. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] ff8b956 Description read[DESCRIPTION-READ] 616320e05dc65283c40996b8cc8ff4446911d116c982ba18d376abbc91e3dabd That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
a652feb to
939fb0d
Compare
9018bcc to
690ee71
Compare
690ee71 to
80e72cc
Compare
Code change approver recommendation: A person should decideWhy: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 863 lines, more than the 400 it may approve on its own. Additive, owner-gated telemetry route and two new counters, modelled on ui-control. The server resolves the public id and version itself, refuses any other body shape, and returns 204 without recording for a Shared Crew teammate (via the existing is_host_owner_dashboard_request helper). The client hook measures foreground time on performance.now(), pauses for Page Visibility, a hidden Crew pane or a zero-size viewport, and sends with keepalive through the normal jfetch transport. The hook is mounted only in InstalledAppSurface and BuiltinAppRoute; side-panel tabs and desktop windows use AppHost directly, so they are not counted, as described. The adopted, released and compiled branches of BuiltinAppRoute cannot double-count a view. The route, the recorder labelling, the hook and the adopted swap are tested; only the trivial Library desktop branch is untested. Nothing regresses: the change adds two schema rows and one route. Tier: 2, held for a person: security-sensitive path. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
80e72cc to
0a45a91
Compare
8bf4db9 to
fb437e0
Compare
…pp pages Implements RFC section 11 PR 7 (app usage metrics, closed #39107): a new owner-only POST /api/telemetry/app-view, copied from ui-control (require_owner_dashboard_request, 256-byte bounded JSON body, 204), and two counters on kiro.crew: kirocrew.app.opened{surface} and kirocrew.app.foreground_time{surface,duration} (unit s). The server resolves the public id and version from the app name itself; an unknown name is private. The page sends one opened per mount and one span per visible stretch (keepalive); spans under 1 s are not sent and the server cuts a span to 24 h. Both count owner views only.
fb437e0 to
ff8b956
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
This review checked head ff8b956 against main. The new POST /api/telemetry/app-view route sits behind the owner gate, and a Shared Crew teammate gets a 204 with nothing counted. The body is read with the 256-byte JSON cap and an exact key set for each event. Every exported label is closed, and app and entity_version are resolved on the server. Spans under 1 s are dropped and spans over 24 h are cut. The compiled page counts only after the list and the released lookup settle, so a cold load that swaps to the adopted copy counts one opened. The added tests fail when the code they cover is reverted.
Security: the route parses outside JSON input and adds schema manifest rows. The risk does not come true here. Each request must pass the owner gate, which denies by default and logs to the audit trail, and must fit the 256-byte cap. The page sends only a name, a surface and whole seconds. The public id and version come from the gateway's own install map, and an unknown name is recorded as private, so a private app's name or version cannot leave the machine. The manifest rows match the closed value lists. No auth, sandbox or approval gate changes.
Done well: the trust split. The page never supplies anything that gets exported as is, and the monotonic clock test proves a wall-clock jump cannot inflate a span.
The design is signed off under the standing maintainer sign-off for changes by team members.
Optional:
LibraryPage.tsx:337: no test covers thedesktopopen report or the remote branch that does not count. AddingreportAppViewto theLibraryPageLaunchpad.test.tsxapi mock would pin both.BuiltinAppRoute.tsx:219-220: thereleasedAnsweredand!releasedguards have no test. A case where getApp rejects 404 withapp_releasedandopens()stays empty would pin them.- The Real-machine verification section has no Before run on the base. A line showing the route answers 404 on main would show the missing behaviour.
Problem / Motivation
Goal: Count how often the owner opens each app, and how long its page stays in the foreground, per public app and version.
Crew counts app installs, updates and uninstalls, but not whether anyone opens an app or how long they look at it. This PR implements RFC section 11 PR 7 of the app usage metrics RFC (closed PR #39107; its text is the spec): one owner-only route,
POST /api/telemetry/app-view, and two counters,kirocrew.app.openedandkirocrew.app.foreground_time.Why it matters
App authors and Crew maintainers need opens and foreground time to tell an app that is installed from one that is used (RFC section 6.3: daily active machines and average foreground time).
Owner views only. The route is owner-gated, so
openedandforeground_timecome from the machine owner's own dashboard tabs only; a Shared Crew teammate passes the dashboard gate but is answered204and not counted.session.started,app.session_startedandapp.run_timecount every session, including other people's and agents'. Readers must not divide one population by the other; the metric docs say so on both rows.Not a goal
session_startedlanded in feat(metrics): count kirocrew.app.session_started per app and version #39777,run_timein feat(metrics): count an app's turn seconds as kirocrew.app.run_time #39784 andpresentin feat(metrics): count each installed app once per UTC day (kirocrew.app.present) #39783.app.opened, so neither is counted.entity_version,surfaceanddurationbefore the analytics store keeps these keys; that is the collector owner's privacy review, outside this repo. Until then the events arrive without those keys; the metrics store keeps every key.What changed (motivation -> approach -> change)
The page sends only the app's name, where it was shown and whole seconds. The server decides everything else.
dashboard/handlers/telemetry_app_view.py,dashboard/routes/system.pyPOST /api/telemetry/app-view, a copy ofui-control:require_owner_dashboard_request,read_bounded_jsonwith a 256-byte cap,204. Body{"app", "surface", "event": "opened"}or{..., "event": "foreground", "seconds": <int>}; any other shape is a 400 with acode.appmay be any valid app name (up toAPP_NAME_MAX_LENGTH, 128). A Shared Crew teammate is answered204and not counted (is_host_owner_dashboard_request). Registered next to/api/telemetry/ui-control.metrics/feature_usage.pyrecord_app_openedandrecord_app_foregroundlabel withapp_public_id/app_public_versionread on the server, so an unknown name isprivateand no version comes from the page.surfaceis closed (desktoponly onopened). Thedurationlabel reusesapp_duration_bucketfromrun_time(#39784), the RFC's 8 buckets. A span under 1 s adds nothing; one span is cut to 24 h. A raising recorder is caught.metrics/behavioral_metrics.py,metrics/product_metrics.py,metrics/schema_manifest.jsonkiro.crew, shape("app", None, "app"); manifest regenerated withpython test/metrics_schema_helpers.py --write(+2 rows).foreground_timehas units.lib/appViewTelemetry.ts,api/client/telemetry.tsuseAppViewMetrics(app): oneopenedper mount (a re-render sends none), oneforegroundspan each time the page stops being visible (hidden tab, another Crew's pane in front viauseLocalCrewHidden, a zero-size viewport when this dashboard sits in adisplay:noneremote Crew pane frame, unmount,pagehide), measured on the monotonic clock (performance.now()) and sent withkeepalive; coming back starts a new span with no secondopened.popoutinside an app pop-out window, elsepage. Failures are swallowed.apps/BuiltinAppRoute.tsx,components/InstalledAppSurface.tsx,pages/apps/LibraryPage.tsxopened, from the copy, and a released app counts none. A LibraryopenCommandlaunch reportsopenedwithsurface=desktop(not when a remote gateway only returns a command).docs/guides/telemetry-otlp-export.md,docs/system-specs/modules/metrics.md,docs/feature-map/README.mdpagehidesends nothing for its last span, so foreground time undercounts.Security: no new listener or port. The route sits on the existing dashboard server behind the same owner gate as
ui-control, writes nothing to disk, and accepts at most 256 bytes.Backwards compatibility
Compatible: two new rows, no row, key or value removed; the schema history gate allows them. A new route only; no existing route or API changes.
Tests
test/test_telemetry_app_view_route.py(real handler, mocked request): non-owner refused (403, nothing counted); a Shared Crew teammate answered 204 with nothing counted; a 128-character app name counted and 129 refused; a body over 256 bytes refused (413); an unknown name isprivatewith versionprivate; the version is the server's own; a 42 s span adds 42 inle_1m; a 3-day span is cut to 86400 s (gt_4h); a 0 s span adds nothing; 18 bad shapes are 400 with acode; a non-JSON content type is 415; a raising recorder still answers 204; the route is registered afterui-control.website/src/test/appViewTelemetry.test.tsx(vitest run): one mount sends oneopenedand re-renders none; hiding the page sends one span and unmount none more; a show after hide starts a new span thatpagehideends; a span under 1 s sends nothing; a page mounted hidden counts no time; another Crew's pane in front pauses the span (3 s, then 7 s after it comes back, no secondopened) and a page mounted behind one counts no time (both red without the pause); a wall-clock jump mid-span leaves a 5 s span at 5 s (red withDate.now()); a zero-size viewport pauses the span (10 s, then 4 s after it is resized back; red without the check); changing the app ends the old span;nullcounts nothing; a rejected or throwing request is swallowed.website/src/test/BuiltinAppRoute.adopted.test.tsx: a cold load of an adopted former built-in's route that swaps to the copy sends oneopened(red on the first head, which sent two); the compiled page sends one once the list and lookup answer.test/metrics/test_behavioral_metrics.py: both rows get theFeature/Activity/Entityshape.test/test_json_object_body_guard.py: the route's cap is registered.scripts/check_metrics_schema_history.py --test(10 probes ok) and against the merge base (+2 rows);test/metrics/test_metrics_schema.py,test/metrics/test_product_metrics.pypass.-n0(620 passed in one run), 10 of 10 runs at-n 2besidetest_feature_usage.pyandtest_telemetry_ui_control_route.py, and once in a shuffled order (84 passed);appViewTelemetry.test.tsxandBuiltinAppRoute.adopted.test.tsxeach pass 20 of 20 runs with--sequence.shuffle, seeds 1-20.BuiltinAppRoute,InstalledAppSurface,AppPage,AppPopoutFrameorLibraryPage, plus the new one, pass (1050 tests);tsc --noEmitand eslint on the touched files are clean.Manual verification
N/A -- unit coverage sufficient: the route test drives the real handler and recorder labelling, and the hook test drives the real hook with the Page Visibility events a browser fires. The change draws nothing.
Real-machine verification
Machine: Linux cloud desktop, Amazon Linux 2023, x86_64
After (head ff8b956, rebased on main 1c0c7ff):
pytest -n 2 test/test_telemetry_app_view_route.py test/test_telemetry_ui_control_route.py test/metrics/test_feature_usage.py test/metrics/test_app_run_time.py test/metrics/test_app_present.py test/metrics/test_behavioral_metrics.py test/metrics/test_metrics_schema.py test/metrics/test_product_metrics.py test/test_json_object_body_guard.py test/test_metrics_schema_history_gate.py-> 236 passed;vitest run src/test/appViewTelemetry.test.tsx src/test/BuiltinAppRoute.adopted.test.tsx src/test/uiControlTelemetry.test.tsx-> 34 passedCleanup: own computer
Screenshots / video
Why no screenshot: the frontend change adds a fire-and-forget usage report and renders nothing.
Related Issues
Closes #39775
Implements RFC section 11 PR 7 from closed #39107. Built on #39715 (RFC PR 3, merged), which added
app_public_version. Rebased on #39777 (RFC PR 4,session_started), #39784 (RFC PR 5,run_time) and #39783 (RFC PR 6,present), all merged; the manifest is regenerated on top of them.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commitsContribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.