Skip to content

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

Merged
EhabY merged 2 commits into
mainfrom
ehab/vscode-family-label
Oct 27, 2026
Merged

EhabY merged 2 commits into
mainfrom
ehab/vscode-family-label

Conversation

@EhabY

@EhabY EhabY commented Sep 25, 2026 •

Copy link
Copy Markdown
Collaborator

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; the catch-all slot stays "Other" because it also totals families without a slot.

  • 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; Unknown for unknown, Other apps for overflow; otherwise the app name

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 take their method from the app name (codersdk.SessionAppMethod, from #31028).

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 9 +104 / -74
Tests (incl. stories) 5 +85 / -53
Docs 1 +50 / -1
Generated 5 +40 / -31

RFC status

Every change here is approved in the RFC.

Series limit

Same rule and order as the template insights API and ingest (codersdk.FoldUnregisteredSessionApps, from #31028): registered apps, unknown, and overflow always get a series, plus the 64 busiest other apps per template, ties broken by app name in byte order. The rest add up under the overflow series. 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. It keeps the shape of the query on main, one jsonb_object_keys call per stat row, and only groups by app name instead of app family. Not measured again after the method storage was dropped from #31028; the earlier measurement was 35 ms on main for 2,000 agents and 5M agent stat rows.

Decision log

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
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 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
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
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch 2 times, most recently from 5ba96c1 to a9566cd Compare October 20, 2026 15:43
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch from a9566cd to ab641f7 Compare October 20, 2026 16:06
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch 2 times, most recently from b7532cb to d624989 Compare October 20, 2026 16:21
@EhabY
EhabY marked this pull request as ready for review October 26, 2026 18:23
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch 2 times, most recently from 29b993d to c15c118 Compare October 26, 2026 19:18
@EhabY
EhabY force-pushed the ehab/vscode-family-label branch 2 times, most recently from 4c59752 to 31c092d Compare October 26, 2026 19:45

@code-asher code-asher left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Lovely!

EhabY added 2 commits October 27, 2026 12:41
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
The docs name the display names of unknown and overflow, the reserved
overflow name, and that the dashboard limit spans all selected
templates. The new lists keep the file's existing bullet style.
appFamiliesGenerated.ts is marked as generated, and a collector test
folds a template's apps past the limit into overflow.
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

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

3 participants