Skip to content

fix: deduplicate template insights family metrics - #30497

Merged
EhabY merged 2 commits into
mainfrom
fix/insights-family-metrics
Oct 12, 2026
Merged

EhabY merged 2 commits into
mainfrom
fix/insights-family-metrics

Conversation

@EhabY

@EhabY EhabY commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

coderd_insights_applications_usage_seconds summed each family's per-app minutes. Because of that, a user with VS Code and Cursor open in the same minute was reported as two VS Code minutes. This PR counts each user-minute once per template and app family. It reads the raw agent statistics, because the rollup keeps minutes per app and cannot tell overlapping apps apart.

This implements the metrics portion of Completing Scalable IDE Session Tracking RFC, separately from the per-app HTTP API and UI.

Changes

Area Change
Query GetTemplateInsightsByTemplate takes app_families, a jsonb app→family map built from codersdk.SessionCountAppFamilies(). It groups the raw stats by family and counts distinct minutes per user and family. App names not in the map count as unknown.
Collector Keeps the existing four built-in series (Visual Studio Code, JetBrains, Web Terminal, SSH) and their labels; only their values change. It reads query rows directly instead of keeping its own row type. The metric's HELP text now says built-in apps are grouped by family.
SDK Adds AppFamilyName.DisplayName(), backed by one family display-name table, and removes the TemplateBuiltinAppDisplayName* constants it duplicated. Nothing outside the template insights handler used them. Existing labels are kept; #29906 renames the VS Code family.
Tests The query test and the collector test cover same-family overlap (VS Code with Cursor, SSH with Zed). The collector golden file is unchanged. A new test pins how the migration 596 rollback approximates family minutes (sum per bucket, capped at 30).
HTTP / storage GetTemplateInsights and the per-app HTTP/UI path behave the same; #29796 handles them. The handler's built-in display names now come from DisplayName(), which returns the same strings. No migration and no storage changes.

Line breakdown

Category Added Deleted
Production (query, sqlc config, collector, insights handler, codersdk) +77 −92
Generated (querier, queries, metric reference, TypeScript types) +30 −55
Tests and goldens +133 −48
Documentation +1 −1
Total +241 −196

Follow-up

This PR stays non-breaking: the metric keeps its four built-in series and labels. SFTP, port forwarding, and unrecognized apps stay unreported here, as on main. #29906 moves all families, those included, to their own metric, coderd_insights_session_families_usage_seconds, labeled by family key. Per-app usage is in the HTTP API and UI with #29796; a per-app Prometheus metric is tracked in #29940.

Performance

The query runs once per collector tick, every five minutes. The benchmark below ran on Postgres 17 with default work_mem and 6 hours of synthetic agent stats, with agents reporting every 30s and a 5-minute window. Times are the median of 7 runs.

Agents Rows in table Rows in window main (per-app) This PR
1,000 720k 10k 21.2 ms 21.4 ms
5,000 3.6M 50k 108.2 ms 108.4 ms
20,000 14.4M 200k 544.5 ms 565.5 ms

Deduplicating by family costs at most about 4%. An earlier version of this PR passed the mapping as two parallel arrays; it was 12 to 18% slower and spilled to disk at 5,000 agents. At 20,000 agents both main and this PR spill about 8 MB per worker in the existing join on template and user.

Operational impact

Family values can drop wherever the old per-app sum double-counted overlapping apps. The metrics window defaults to five minutes. Raw agent stats are kept for roughly a day behind the rollup, so a custom window longer than that would undercount session families.

Stack

Targets main. Review and land in order: #30497 → #29796 → #29906. The connection-log stack (#30466 → #30467) is independent.

Generated with Coder Agents on behalf of @EhabY.

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@EhabY
EhabY added this pull request to stack #30499 October 8, 2026 09:16
@EhabY
EhabY force-pushed the fix/insights-family-metrics branch 4 times, most recently from 7053de1 to 91d62e9 Compare October 8, 2026 16:25
@EhabY
EhabY marked this pull request as ready for review October 8, 2026 16:29
@EhabY
EhabY requested a review from nickvigilante as a code owner October 8, 2026 16:29
@EhabY
EhabY force-pushed the fix/insights-family-metrics branch 2 times, most recently from 09e47eb to e5ed18e Compare October 8, 2026 16:36

@nickvigilante nickvigilante 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.

Docs LGTM

@EhabY
EhabY requested a review from ssncferreira October 9, 2026 13:21
@EhabY
EhabY force-pushed the fix/insights-family-metrics branch from e5ed18e to b77bd9e Compare October 12, 2026 13:20
coderd_insights_applications_usage_seconds summed each family's per-app
minutes, so apps of one family open in the same minute counted that
minute more than once. GetTemplateInsightsByTemplate now takes the
registry's app-to-family mapping as jsonb, groups the raw agent stats by
family, and counts each minute once per user and family.

The metric keeps its existing built-in series and labels.

Also pins how the 000596 rollback approximates family minutes from
per-app rows.
@EhabY
EhabY force-pushed the fix/insights-family-metrics branch from b77bd9e to e954704 Compare October 12, 2026 13:58

@ssncferreira ssncferreira 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.

LGTM, just a few notes 👍

Comment thread coderd/database/queries/insights.sql Resolved
Comment thread docs/admin/integrations/prometheus.md Resolved
Comment thread codersdk/appname.go Resolved
- Rename the family_usage CTE to app_family_usage and familySeries to
  appFamilySeries.
- Drop the TemplateBuiltinAppDisplayName* constants; the insights
  handler uses AppFamilyName.DisplayName(), which returns the same
  strings.
- Move the prometheus.md section into the metric's HELP text.
- Note each app's family in the migration 000596 rollback test cases.
@EhabY
EhabY merged commit 2f2169e into main Oct 12, 2026
36 checks passed
@EhabY
EhabY deleted the fix/insights-family-metrics branch October 12, 2026 20:58
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 12, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants