Skip to content

feat(metrics): count app opens and foreground time from the owner's app pages - #39793

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
feat/app-view-metrics
Nov 20, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
feat/app-view-metrics

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

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.opened and kirocrew.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 opened and foreground_time come from the machine owner's own dashboard tabs only; a Shared Crew teammate passes the dashboard gate but is answered 204 and not counted. session.started, app.session_started and app.run_time count 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

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.

Part Change
dashboard/handlers/telemetry_app_view.py, dashboard/routes/system.py POST /api/telemetry/app-view, a copy of ui-control: require_owner_dashboard_request, read_bounded_json with a 256-byte cap, 204. Body {"app", "surface", "event": "opened"} or {..., "event": "foreground", "seconds": <int>}; any other shape is a 400 with a code. app may be any valid app name (up to APP_NAME_MAX_LENGTH, 128). A Shared Crew teammate is answered 204 and not counted (is_host_owner_dashboard_request). Registered next to /api/telemetry/ui-control.
metrics/feature_usage.py record_app_opened and record_app_foreground label with app_public_id / app_public_version read on the server, so an unknown name is private and no version comes from the page. surface is closed (desktop only on opened). The duration label reuses app_duration_bucket from run_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.json Two rows on scope kiro.crew, shape ("app", None, "app"); manifest regenerated with python test/metrics_schema_helpers.py --write (+2 rows). foreground_time has unit s.
lib/appViewTelemetry.ts, api/client/telemetry.ts useAppViewMetrics(app): one opened per mount (a re-render sends none), one foreground span each time the page stops being visible (hidden tab, another Crew's pane in front via useLocalCrewHidden, a zero-size viewport when this dashboard sits in a display:none remote Crew pane frame, unmount, pagehide), measured on the monotonic clock (performance.now()) and sent with keepalive; coming back starts a new span with no second opened. popout inside an app pop-out window, else page. Failures are swallowed.
apps/BuiltinAppRoute.tsx, components/InstalledAppSurface.tsx, pages/apps/LibraryPage.tsx The installed-app page calls the hook. The compiled built-in page calls it only once the apps list has loaded and the released lookup has answered, so a cold load that swaps to an adopted copy counts one opened, from the copy, and a released app counts none. A Library openCommand launch reports opened with surface=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.md Export table, metrics spec and feature map list the route and rows, marked owner views only; the spec says a tab killed before pagehide sends 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 is private with version private; the version is the server's own; a 42 s span adds 42 in le_1m; a 3-day span is cut to 86400 s (gt_4h); a 0 s span adds nothing; 18 bad shapes are 400 with a code; a non-JSON content type is 415; a raising recorder still answers 204; the route is registered after ui-control.
  • website/src/test/appViewTelemetry.test.tsx (vitest run): one mount sends one opened and re-renders none; hiding the page sends one span and unmount none more; a show after hide starts a new span that pagehide ends; 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 second opened) 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 with Date.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; null counts 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 one opened (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 the Feature / Activity / Entity shape. test/test_json_object_body_guard.py: the route's cap is registered.
  • Schema gates: 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.py pass.
  • Determinism: the new pytest tests pass 20 times at -n0 (620 passed in one run), 10 of 10 runs at -n 2 beside test_feature_usage.py and test_telemetry_ui_control_route.py, and once in a shuffled order (84 passed); appViewTelemetry.test.tsx and BuiltinAppRoute.adopted.test.tsx each pass 20 of 20 runs with --sequence.shuffle, seeds 1-20.
  • The 47 vitest files that mount BuiltinAppRoute, InstalledAppSurface, AppPage, AppPopoutFrame or LibraryPage, plus the new one, pass (1050 tests); tsc --noEmit and 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 passed
Cleanup: 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

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of ff8b956214af841571b57c5fc307ae15bc66b0d8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ff8b956214af841571b57c5fc307ae15bc66b0d8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • The analytics store drops surface, duration and entity_version until the collector's key list is widened outside this repo. Until then, the version and bucket breakdowns exist only in the local metrics store. Track that follow-up so nobody reads the new rows as complete.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ff8b956214af841571b57c5fc307ae15bc66b0d8 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Every item adds telemetry behind consent, defaults stay unchanged, and the route follows the existing ui-control owner gate. One redundant bound is noted.

Notes

  • Item 2 — oversized: the route's _MAX_SECONDS = 10 * 366 * 24 * 3600 check does nothing that is not already done. The 256-byte body cap already limits how many digits seconds can have, and record_app_foreground already cuts each span to 24 h with min(seconds, APP_FOREGROUND_MAX_SECONDS). Subtraction: delete _MAX_SECONDS and its range test in telemetry_app_view.py, and keep only the int/non-bool/>= 0 checks.

What this change ships

Inventory (7 items) — 6 justified

Intent: let maintainers and app authors tell an app that is installed from one that is actually opened and looked at. This is an ADDITION.

  1. The owner opening an app's page or pop-out is counted as kirocrew.app.opened — justified
  2. New owner-only POST /api/telemetry/app-view route, 256-byte closed body — oversized (redundant seconds bound)
  3. Time an app page stays visible is counted in seconds as kirocrew.app.foreground_time — justified
  4. Launching an app's openCommand from the Library counts as an opened with surface=desktop — justified
  5. A Shared Crew teammate's views get a 204 and are not counted — justified
  6. Two new rows in the schema manifest and behavioral metrics — justified
  7. Docs: export guide, metrics spec and feature map list the owner-views-only rows — justified

[FIRST-PRINCIPLES-REVIEWED] ff8b956

Description read

[DESCRIPTION-READ] 616320e05dc65283c40996b8cc8ff4446911d116c982ba18d376abbc91e3dabd

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed ff8b956214af841571b57c5fc307ae15bc66b0d8 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ff8b956

Verdict parsed from the review's SHA-scoped output markers for commit ff8b956214af841571b57c5fc307ae15bc66b0d8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ff8b956214af841571b57c5fc307ae15bc66b0d8 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ff8b956214af841571b57c5fc307ae15bc66b0d8 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ff8b956

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ff8b956214af841571b57c5fc307ae15bc66b0d8 false-positive: <reason, 20 to 500 characters>

@chenmingwei23
chenmingwei23 force-pushed the feat/app-view-metrics branch 2 times, most recently from a652feb to 939fb0d Compare November 20, 2026 05:55
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 20, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/app-view-metrics branch 2 times, most recently from 9018bcc to 690ee71 Compare November 20, 2026 06:41
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 20, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 20, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 20, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 ff8b956214 · 863 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 20, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/app-view-metrics branch 2 times, most recently from 8bf4db9 to fb437e0 Compare November 20, 2026 11:24
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 20, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 20, 2026
…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.
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 20, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 20, 2026 14:02

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 the desktop open report or the remote branch that does not count. Adding reportAppView to the LibraryPageLaunchpad.test.tsx api mock would pin both.
  • BuiltinAppRoute.tsx:219-220: the releasedAnswered and !released guards have no test. A case where getApp rejects 404 with app_released and opens() 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.

@KiroCrewCaptain
KiroCrewCaptain merged commit 649c2f8 into main Nov 20, 2026
99 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the feat/app-view-metrics branch November 20, 2026 14:02
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

metrics: add kirocrew.app.opened and kirocrew.app.foreground_time via owner-only POST /api/telemetry/app-view

2 participants