Skip to content

feat!: label the VS Code family and report built-in app usage per app - #29906

Draft
EhabY wants to merge 1 commit into
feat/session-app-methodfrom
ehab/vscode-family-label
Draft

EhabY wants to merge 1 commit into
feat/session-app-methodfrom
ehab/vscode-family-label

Conversation

@EhabY

@EhabY EhabY commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Two breaking changes:

  • The session banner labels the VS Code family as VS Code Family, so it isn't confused with the VS Code editor. Family labels are generated from the shared Go table.

  • coderd_insights_applications_usage_seconds reports built-in apps per app instead of per family, gets a connection_method label, and renames application_name to display_name:

    connection_method Apps slug display_name
    workspace_app Template apps slug or port app display name
    ssh, reconnecting_pty, port_forwarding Built-in apps (desktop IDEs, SSH, web terminal) app name, e.g. cursor registry name, e.g. Cursor; the app name if unregistered

connection_method + slug is the row key of GET /api/v2/insights/templates, so a template app with slug vscode stays separate from the VS Code desktop app. Built-in apps report the method stored by #31028, so the same app name under two methods gets two series.

Each app counts its own minutes. A family total only differs from the sum of its apps when two apps of one family are open at once; dogfood connection logs showed no such overlap.

Note

A per-template total without overlap, such as coderd_insights_session_usage_seconds{template_name, organization_name}, is additive and costs about 2 to 7% more query time. Left out until someone needs it.

Closes #29940
Closes CLIENT-1034
Closes CLIENT-1036

Important

Stacked on #31028. Merge that first, then retarget this PR to main.

Size

Against #31028:

Files Lines
Production 8 +167 / -80
Tests (incl. stories) 6 +124 / -29
Docs 1 +56 / -8
Generated 4 +57 / -35

RFC status

Important

Land only after the RFC amendment is approved. Its unapproved sentences are marked ⏳.

Change RFC status
VS Code Family label, generated family labels ✅ Approved
Built-in apps leave the slug="" family series (breaking, with migration docs) ✅ Approved
Built-in apps per app, no family metric ⏳ Not approved
Built-in apps stay in this metric, with connection_method; application_name renamed to display_name ⏳ Not approved
Series limit shared with the template insights API ⏳ Not approved

Series limit

Same rule as the template insights API: registered apps, unknown, and overflow always get a series, plus the 64 busiest other (method, app) pairs per template. The rest add up under the overflow series of their method. Series exist only for apps used in the window.

Upgrade impact

  • Selectors with a value for application_name, or with slug="", return nothing.
  • Template-app queries by slug also match a built-in app with the same name (e.g. vscode). Add connection_method="workspace_app".
  • Totals without a slug selector now include every built-in app, including port_forwarding, sftp, and unknown.
  • Built-in series are no longer emitted at 0, so panels can show "no data".

The docs map each old series to its new one.

Performance

Prometheus runs this query every tick over a fixed 5-minute window. Medians of interleaved EXPLAIN (ANALYZE) rounds, local Postgres 13, 2,000 agents, 5M agent stat rows:

Window main #31028 This PR
5 minutes 35 ms 58 ms 49 ms

The extra time is the method level. The query looks up each connection_log_method the row has (session_counts ? method) instead of expanding the object with jsonb_each. That keeps the planner's estimate under the JIT threshold, and it stays under it with larger windows (tested up to 120 minutes, which stands in for bigger deployments).

Decision log
  • One metric with connection_method, not a separate coderd_insights_session_apps_usage_seconds. Matches the API's method + slug key.
  • connection_method, not method. Same name as the database enum and connection logs; method alone is vague.
  • Rename application_name to display_name. Registry names JetBrains and SSH equal the old family labels, so keeping the label would make old selectors silently match one app. The rename makes them return nothing, and matches the API field name.
  • display_name holds the registry name for built-in apps, not a copy of slug.
  • Stacked on feat: record the connection method for session app usage #31028 (2026-10-19). Both PRs replaced the read-time sessionAppMethod guess and rewrote the same query. Stacking lets the metric read the stored method instead of guessing it, and drops the temporary codersdk.SessionAppConnectionMethod. GetTemplateInsightsByTemplate now returns {method: {app: seconds}}, and capSessionApps limits (method, app) pairs with one overflow per method, matching GetTemplateInsights.
  • Method lookup over enum_range(NULL::connection_log_method), filtered by ?, not jsonb_each. Same result, without the row overestimate that turned on JIT.
  • capSessionApps edits the decoded map in place and only sorts when a template has more than 64 unregistered pairs.

Generated with Coder Agents on behalf of @EhabY.

@EhabY EhabY changed the title feat: label the VS Code family as VS Code Family feat!: label the VS Code family as VS Code Family Sep 25, 2026
@github-actions github-actions Bot added the release/breaking This label is applied to PRs to detect breaking changes as part of the release process label Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 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.

nickvigilante added a commit that referenced this pull request Oct 2, 2026
`coder port-forward` reported usage with the deprecated
`UpdateWorkspaceUsageContext`.
It now reports a `port_forwarding` session, like `coder ssh` and the VS
Code SSH path, but only while a forwarded TCP connection is open.

**Behavior change:** CLI output is unchanged.
Port-forward sessions previously only bumped the workspace's last-used
time.
With the hidden `workspace-usage` experiment enabled, the server now
also records `port_forwarding` session counts under a new
`port_forwarding` family, which the deployment banner totals under
**Other**.
Without the experiment, `postWorkspaceUsage` returns 204 before reading
the body, so nothing changes.

<details>
<summary>Decisions</summary>

- Added `codersdk.UsageAppNamePortForwarding` (`port_forwarding`) rather
than reusing `ssh`, so port-forwarding isn't counted as interactive SSH.
The name matches the arbitrary app names RFC's connection-method name.
- Registered a `port_forwarding` family in `codersdk/appname.go`.
Families resolve at read time, so no data migration is needed. Template
insights list apps individually; telemetry, metricscache, and agentstats
gauges are legacy fixed fields and stay as they are. The Prometheus
insights family is left to #29906.
- Only TCP connections count. UDP forwards never see EOF, so one
datagram would keep the session active until exit.
- Reports once at startup, like the old call, then every minute and once
on shutdown. An idle tick sends an empty body, which still bumps
last-used.

</details>

Closes [CLI-31](https://linear.app/codercom/issue/CLI-31)

_This PR was generated by Coder Agents on behalf of @nickvigilante._


<details>
<summary>CI note: unrelated test-go-race-pg flake</summary>

The `test-go-race-pg` job failed on a data race between
`tailnet.(*configMaps).updatePeerLocked` and slog formatting of the same
peer value, which does not touch port-forward code. The job was rerun.

</details>
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from da188c4 to 6bdbd8c Compare October 7, 2026 13:51
@EhabY
EhabY requested a review from nickvigilante as a code owner October 7, 2026 13:51
@EhabY
EhabY changed the base branch from main to ehab/client-642-per-app-template-insights October 7, 2026 13:51
@EhabY
EhabY added this pull request to stack #30468 October 7, 2026 13:59
@EhabY
EhabY marked this pull request as draft October 7, 2026 13:59
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 6bdbd8c to b35afa2 Compare October 7, 2026 17:32
@EhabY
EhabY removed this pull request from stack #30468 October 8, 2026 09:15
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from b35afa2 to 14839f0 Compare October 8, 2026 09:16
@EhabY
EhabY added this pull request to stack #30499 October 8, 2026 09:16
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 14839f0 to 4d31a5d Compare October 8, 2026 15:45
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch 2 times, most recently from e363467 to 62b1f30 Compare October 8, 2026 16:00

@nickvigilante nickvigilante left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Docs LGTM

@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 62b1f30 to 77ef278 Compare October 8, 2026 16:25
@EhabY EhabY changed the title feat!: label the VS Code family as VS Code Family feat!: label the VS Code family and move built-in app usage to its own metric Oct 8, 2026

@nickvigilante nickvigilante left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Docs LGTM! One small nit

Comment thread docs/admin/integrations/prometheus.md Outdated
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 60237b8 to f1d8041 Compare October 16, 2026 19:22
@EhabY EhabY changed the title feat!: label the VS Code family and move built-in app usage to its own metric feat!: label the VS Code family and report built-in app usage per app Oct 16, 2026
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 90bc72b to e9c73dd Compare October 17, 2026 11:46
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from e9c73dd to 3ae4ca4 Compare October 19, 2026 10:29
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 3ae4ca4 to 7afe77c Compare October 19, 2026 10:46
Base automatically changed from ehab/client-642-per-app-template-insights to main October 19, 2026 14:59
EhabY added a commit that referenced this pull request Oct 19, 2026
Report template insights session usage per app instead of five fixed
family rows, with registry names and icons.

- Add per-app rows for reported session apps (VS Code, Cursor, GoLand,
  Zed, etc.); unused apps are omitted
- Replace `type` (`builtin`/`app`) with `method` (`ssh`,
  `reconnecting_pty`, `port_forwarding`, `workspace_app`); session
  methods are derived from the app name until #31012 stores them
- Add `usage_total_seconds` to count each user's active minutes once,
  and use it as the UI bar denominator so overlapping apps can exceed
  100%
- Merge template apps sharing a slug into one row across templates,
  using the newest display name and icon
- Rename Web Terminal slug from `reconnecting-pty` to
  `reconnecting_pty`
- Cap the response at the 64 busiest unregistered apps and fold the
  rest into "Other apps", flagged with `seconds_is_upper_bound`
  ("Up to" in the UI)
- Add `unknown` and `overflow` accounting rows with explanatory
  tooltips, and a fallback icon for apps without one
- Remove the unused `codersdk.UnionByFamily` helper from the Go SDK

BREAKING CHANGE: `report.apps_usage` in `GET /api/v2/insights/templates`
no longer returns the fixed five rows, family slugs, or previous display
names. Consumers must update.

Part of CLIENT-642
Prometheus metrics handled separately in #29906
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 7afe77c to d06ce5c Compare October 19, 2026 14:59
@linear-code

linear-code Bot commented Oct 19, 2026

Copy link
Copy Markdown

CLIENT-1034

@EhabY
EhabY removed this pull request from stack #30499 October 19, 2026 20:00
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 263cbb0 to 3b30952 Compare October 19, 2026 20:15
@EhabY
EhabY changed the base branch from main to feat/session-app-method October 19, 2026 20:15
@EhabY
EhabY added this pull request to stack #31031 October 19, 2026 21:32
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch 2 times, most recently from 7ac063d to 30c6158 Compare October 19, 2026 22:51
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 30c6158 to 128abb6 Compare October 19, 2026 22:56
The session banner labels the VS Code family as VS Code Family, using
display names generated from the shared Go table.

coderd_insights_applications_usage_seconds reports built-in apps per app
instead of per family. A new connection_method label (workspace_app,
ssh, reconnecting_pty, port_forwarding) separates template apps from
built-in apps, matching the method and slug key of the template insights
API, and built-in apps report the method stored by the previous commit.
application_name is renamed to display_name so old selectors return
nothing instead of silently matching one app.

Each template reports registered apps and the 64 busiest other
(method, app) pairs, like the template insights API; the rest add up
under the overflow series of their method.

Closes #29940
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from 128abb6 to 5ba96c1 Compare October 20, 2026 00:00

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release/breaking This label is applied to PRs to detect breaking changes as part of the release process

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Export per-app usage time per template to Prometheus

2 participants