Repository navigation
feat(metrics): count kirocrew.app.session_started per app and version - #39777
Conversation
Implements RFC section 11 PR 4 (app usage metrics, closed #39107): right after record_session_started counts kirocrew.session.started, a session whose provider carries a trusted owning_app also counts kirocrew.app.session_started with Entity = app_public_id, entity_version = app_public_version and kind = the session_kind (9 values). No owning_app, no count. A raising app recorder leaves session.started counted and the session start unchanged.
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change only adds one metric row. It reads the trusted Notes
[DESIGN-REVIEWED] 93e9b6f Description read[DESCRIPTION-READ] 15ee5fca406e8224333809574e8062785466bb51527dec0cadfc11f8b7dc262b 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. This adds one counter for a harm the author names, linked to issue #39774. A grep found no existing metric that records which app a session ran under; What this change shipsInventory (4 items) — 4 justifiedIntent: an app author can see how many sessions run under their app, per version and per kind of session. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 93e9b6f Description read[DESCRIPTION-READ] de3d3f9b68c08894c84f922eb4cb8a78d681e396332273f6dd57e1c49bf92651 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: |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
This review checked head 93e9b6f. provider.owning_app is set before every record_session_started caller that can carry an app. A private app is exported only as private/private through app_public_id/app_public_version, and kind is limited to the 9 SESSION_KIND_VALUES. The two touched test files pass (44 tests), and reverting the production code turns the new tests red. One thing done well: the counter runs inside the one shared start recorder, only after kirocrew.session.started is emitted, so every start path counts it the same way.
Security: the gate matched schema_manifest.json only because its name contains "manifest". The file grants no scopes, and this PR adds one telemetry row to it. The change touches no auth, sandbox, path or subprocess code, and no private app name or version leaves the machine.
Optional:
- Add a test that makes the
session.startedemit raise and asserts nokirocrew.app.session_startedis recorded. Today, deleting thereturninsessions.py:373turns no test red. - In the
metrics.mdrow, say that the counter counts session starts, including compaction and background recycles, not distinct sessions. - After a failed compaction recycle, the kept session is counted again, the same way
session.startedalready counts it on main.
Code change approver recommendation: A person should decideWhy: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: security-sensitive path. The PR adds a new counter, The new count is a synchronous in-memory add that comes after the function's only cancellable point, so a start that gets cancelled and rolled back never counts an app session. The early Labels reuse the existing Every place that lists the app lifecycle metrics is updated: 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 |
Problem / Motivation
Goal: An app author can see how many sessions run under their app, per app version and per kind of session.
Today Crew counts every session start (
kirocrew.session.started) but cannot tell which app a session ran under. The app usage metrics RFC (closed doc PR #39107, section 11 PR 4) adds one counter for that.Why it matters
Apps built on Crew have real users, and their authors cannot see whether anyone runs them. Sessions under an app are one of the wave 1 numbers the RFC promises (section 6.2), and the daily and weekly active machines in section 6.3 are derived from it.
Not a goal
kirocrew.app.run_time,kirocrew.app.present,kirocrew.app.openedandkirocrew.app.foreground_time(RFC PRs 5-7, separate PRs).space:<namespace>/<name>(RFC PR 8).entity_versionandkindfor this row to arrive whole in the analytics store. That list lives outside this repository and is the collector owner's privacy review.What changed (motivation -> approach -> change)
One new counter,
kirocrew.app.session_started, on scopekiro.crewwith the shapeFeature = app,Activity = session_started,Entity= the app's public id.Entityapp_public_id(owning_app): a built-in or store app's name, elseprivateentity_versionapp_public_version(owning_app):N.N.N, elseother;privatefor a private appkindsession_kind, the same 9 valueskirocrew.session.startedcarriesIt is counted in
record_session_started(src/kiro_crew/metrics/sessions.py), right afterkirocrew.session.started, when the provider'sowning_appis set. Session allocation sets that field from the caller's slot app, never from transcript metadata. Putting it in the one shared recorder means every start path counts it the same way, and it can never count more thansession.started. A session with noowning_appcounts nothing. The recorder (record_app_session_startedinsrc/kiro_crew/metrics/feature_usage.py) swallows its own failures, and a second guard insessions.pykeeps a raising recorder from touching the session start.The four places every new name changes together are updated:
_SHAPESinmetrics/behavioral_metrics.py,PRODUCT_METRICSinmetrics/product_metrics.py, the regeneratedmetrics/schema_manifest.json(+1 row), and the export table indocs/guides/telemetry-otlp-export.md.docs/system-specs/modules/metrics.mdgains the row.Backwards compatibility
Compatible: one new counter row;
kirocrew.session.startedkeeps its attributes and is still counted first.Removes nothing: the diff only adds a metric row, a recorder and docs.
Tests
test/metrics/test_session_started_attrs.py: a provider withowning_appcounts oneapp.session_startedwith the rightEntity,entity_versionandkind(store app, pre-release version, private app, cron and sub-agent kinds); noowning_app(None, empty, not a string) counts none; a raising app recorder leavessession.startedcounted and the start recorded.test/metrics/test_behavioral_metrics.py: the new row gets itsFeature/Activity/Entityshape.test/metrics/test_metrics_schema.pypasses, andscripts/check_metrics_schema_history.pyreports the schema only grows (+1 row).Manual verification
N/A -- unit coverage sufficient: the change is one in-memory counter add behind the existing recorder, and the tests drive the real
record_session_started.Real-machine verification
N/A -- a metric row and its recorder; no user-visible behaviour changes on a machine.
Related Issues
Fixes #39774
Implements RFC section 11 PR 4 from closed #39107 (the app usage metrics RFC doc PR; the RFC is not on main).
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits