<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/engineering/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=630922) </details> <!--IssueSummary end--> Client identity is how we work out which client, an IDE plugin, a CLI, a mobile app, and so on, made a request, so we can attribute Snowplow events to the right `client_type` and `client_name` for analytics. !257624 adds the Rails-side resolution for this, using an allowlist for `client_type` and alias tables that normalize the free-text names and types clients actually send. While preparing that MR we audited what real clients send against seven days of production request headers, and found several mismatches between what is sent and what the allowlist and aliases expect; the table below documents each one. This issue tracks the items that need a fix outside the monolith, in a plugin, the CLI, or the language server, or a decision on who owns a given name. The proposed split: Developer Clients own the names their plugins send, Analytics Instrumentation approves the backend mapping and schema, and the Data team is informed when a value changes. ## Already fixed in !257624 In gitlab-org/gitlab@573074fef1234, the `gitlab duo` alias now maps to `jetbrains` instead of `vscode`, and the Duo CLI's `duo_cli` type and `gitlab-duo-cli` name are now aliased too. That covers recommendations 1 and 2 in the table below; the remaining numbered items are still open. ## Inventory: what each client sends and how Rails resolves it Source: client and language-server source code, Workhorse, and 7 days of production header data (`PROD.COMMON.FCT_BEHAVIOR_STRUCTURED_EVENT`, queried 2026-09-25). Volumes are AI Gateway and Duo Workflow Service events, which already echo the headers; Rails emits `client_type` / `client_name` only from !257624 on. "Resolved" and "Legacy `client`" describe the behaviour of !257624 at the time of the audit, before the fixes listed below. | Client | `X-Gitlab-Client-Type` sent | `X-Gitlab-Client-Name` sent | User-Agent / other signal | Resolved type / name | Legacy `client` property | Events (7d) | Status | |---|---|---|---|---|---|---|---| | GitLab web UI (after !257624) | `web` | `gitlab-web` | browser UA | web / gitlab-web | `web` | 150,088 `web` today | ✅ OK | | Duo Agentic Chat / Agent Platform in the browser | `web_browser` on GraphQL; `client_type=browser` query param on the websocket | none (browsers cannot set upgrade headers; Workhorse fills in `gitlab-duo-workflow`) | browser UA | web / gitlab-web via alias | `web` | 3,000,211 | ✅ OK, alias commented | | Web IDE (VS Code extension, browser build) | none | `GitLab` | browser UA (web worker cannot change it); `platform_origin: vs_code_extension` | ide / vscode | `vscode` (was `web_ide`) | 21,444 `web_ide` today | ⚠️ Probable regression: same name as desktop VS Code, indistinguishable by header. Verify with a Web IDE chat. | | VS Code extension, desktop | `node-websocket` on websockets, none on REST | `GitLab` (older: `Visual Studio Code`) | `visual-studio-code/… gitlab/… gitlab-language-server/…`; `platform_origin: vs_code_extension` | ide / vscode | `vscode` | 2,780,838 + 1,921,785 | ✅ OK | | JetBrains plugin, current versions | `node-websocket` or none | `GitLab Duo` (plugin.xml name, passed to the language server) | `gitlab-jetbrains-plugin/…` | ide / **vscode** | **`vscode`** | 609,927 | ❌ Was wrong: counted as VS Code. Fixed, see below. | | JetBrains plugin, older versions | `node-websocket` or none | `IntelliJ IDEA`, `PyCharm`, `GoLand`, … (IDE name) or `gitlab-jetbrains-plugin` | `gitlab-jetbrains-plugin/…` | ide / jetbrains | `jetbrains` | 977,397 + 303,437 | ✅ OK | | JetBrains bundled plugin (shipped by JetBrains) | none | none | `IntelliJ-GitLab-Plugin …` | ide / jetbrains-bundled | `jetbrains_bundled` | | ✅ OK | | Eclipse plugin | `node-websocket` or none | `GitLab Duo` (hard-coded extension name) | `eclipse/… gitlab-duo/… gitlab-language-server/…`; LSP `clientInfo` `gitlab-eclipse-plugin` | ide / **jetbrains** | **`jetbrains`** | none identifiable (no `GitLab Duo` events carry an Eclipse version) | ❌ Counted as JetBrains; needs its own extension name. | | Visual Studio extension | `node-websocket` or none | `gl-visual-studio-extension`, `Microsoft Visual Studio` | `… (gl-visual-studio-extension:…)` | ide / visual-studio | `visual_studio` | 74,726 + 27,051 | ✅ OK | | Neovim plugin | none | `gitlab.vim`, `Neovim LSP client` | `… Neovim …` | ide / neovim | `neovim` | | ✅ OK | | Zed | none | `Zed Duo Extension` | | ide / zed | `ide` | | ✅ OK | | Kiro | none | `Kiro` | | ide / kiro | `ide` | 237 | ✅ OK | | Duo CLI | `node-websocket` | `Duo CLI` | | cli / duo-cli | `duo_cli` | 6,407,510 | ✅ OK | | Duo CLI, sessions typed `duo_cli` with no own name | `duo_cli` | none (Workhorse fills in `gitlab-duo-workflow`) | | **web / gitlab-web** | **`web`** | 2,504 | ❌ Was wrong: type alias missing, fallback name won. Fixed, see below. | | Duo CLI, name `gitlab-duo-cli` | `node-websocket` | `gitlab-duo-cli` | | api / none | `api` | 112 | ⚠️ Name was not allowlisted. Fixed, see below. | | Unnamed language-server sessions (any IDE or CLI without telemetry configured) | `node-websocket` | none (Workhorse fills in `gitlab-duo-workflow`) | | **web / gitlab-web** | **`web`** | 203,558 | ❌ Wrong: IDE/CLI sessions counted as web | | glab CLI | none | none | `glab/v…` | cli / glab | `gitlab_cli` | | ✅ OK | | Mobile app | none until gitlab-mobile!13 ships, then `mobile` | none, then `gitlab-mobile-ios` / `gitlab-mobile-android` | `GitLabMobile/…` | api → mobile / gitlab-mobile-* | `api` → `mobile` | | ⏳ Pending app release | | MCP server | set server-side by Rails | `mcp` | irrelevant | integration / mcp | `integration` | | ✅ OK | | Slack app | set server-side by Rails | `slack` | irrelevant | integration / slack | `integration` | | ✅ OK | | Workhorse running agent actions for the Duo Workflow Service | forwards the human's headers (!257626) | forwarded, or none | `Agent-Flow-via-GitLab-Workhorse` | inherits the human's identity, else system | inherited, else `system` | | ✅ OK | | Server-side flows (Duo as reviewer, etc.) | `gitlab-server-side` (not allowlisted, dropped) | none | `Agent-Flow-via-GitLab-Workhorse` | system / gitlab-rails via UA | `system` | 119 | ✅ OK, would flip to web if a name were forwarded; worth a spec | | GitLab itself: runner, git over HTTP, GitLab Shell, Workhorse, cron jobs | none | none | `gitlab-runner`, `git/`, `GitLab-Shell`, `gitlab-workhorse`, or no request | system / gitlab-rails | `system` | | ✅ OK | | Internal experiments | `node-websocket`, `python-websocket`, `evergreen-poc` | `anymodel-gitlab-duo`, `duo-web`, `duo-api-server`, `GitLab Duo Adapter`, `evergreen-duo-poc` | | api / none | `api` | 34,976 | ➖ Acceptable, unowned names | | Scripts, CI jobs, third-party tools | none | none | anything | api / none | `api` | | ✅ By design | | Requests with no User-Agent at all | none | none | none | api / none, or inherited lineage | `api` (was `null`) | 77,503 `null` today | ✅ Improvement, Data team already notified | ## Problems 1. ~~**`GitLab Duo` is the JetBrains plugin, not VS Code.**~~ Fixed in !257624, see below. 2. **Unnamed language-server sessions become `web`.** Workhorse's fallback name `gitlab-duo-workflow` is aliased to the web UI, but it also appears on `node-websocket` sessions (~204k events a week), which are IDE or CLI users without telemetry configured. 3. **Web IDE and desktop VS Code both report the name `GitLab`.** The legacy `client` property loses `web_ide` (~21k events a week today) unless Rails also looks at the browser User-Agent. 4. **Small gaps:** `gitlab-server-side` is not a type alias (resolves to `system` via the User-Agent today, so harmless, but implicit). 5. **The Eclipse plugin also sends `GitLab Duo`.** Both it and the JetBrains plugin get this string from their product display name rather than a distinct identifier, so Eclipse usage is counted as JetBrains in Rails and the name alone cannot tell them apart. Their LSP `clientInfo` values already differ (`gitlab-jetbrains-plugin` vs `gitlab-eclipse-plugin`), but the language server prefers the extension name for the `X-Gitlab-Client-Name` header. ## Recommendations For gitlab-org/gitlab: 1. ~~`'gitlab duo' => 'jetbrains'` in `NAME_ALIASES`.~~ Done in !257624. 2. ~~`'duo_cli' => 'cli'` in `TYPE_ALIASES` and `'gitlab-duo-cli' => 'duo-cli'` in `NAME_ALIASES`.~~ Done in !257624. 3. Apply the `gitlab-duo-workflow` alias only when the type header is `browser` or `web_browser`; otherwise treat the name as unknown so those sessions resolve to `api`, not `web`. For Developer Clients (@james.casey, @andrei.zubov): 4. Give the Web IDE build its own extension name (for example `gitlab-web-ide`) so it stops colliding with desktop VS Code. Until then Rails could treat a browser User-Agent plus the name `GitLab` as the Web IDE. 5. Always send a client name on websockets and a real type (`ide`, `cli`) instead of the transport `node-websocket`; send the type on REST calls too. Then Workhorse never needs a fallback name and the alias tables in Rails can shrink. 6. Send distinct extension names from the JetBrains and Eclipse plugins (for example `gitlab-jetbrains-plugin` and `gitlab-eclipse-plugin`, which are already their LSP `clientInfo` names) instead of the shared display name `GitLab Duo`. Once both plugins send a distinct name, the `gitlab duo` alias in Rails can be removed. Governance: 7. Record the allowlist and its owners on `doc/development/internal_analytics/internal_event_instrumentation/client_identity.md`: Developer Clients own the names the plugins send, Analytics Instrumentation (@ankit.panchal) approves the backend mapping, the Data team is told when values change. `X-Gitlab-Client-Version` is already sent and the `gitlab_standard` schema has `client_version`; capturing it is a cheap follow-up. ## Related - gitlab-org/gitlab!257624 (Rails client identity), gitlab-org/gitlab!257626 (Workhorse forwarding), mvanremmerden/gitlab-mobile!13 (mobile headers) - gitlab-org/editor-extensions/gitlab-lsp!3951 (language server prefers the extension name), gitlab-org/editor-extensions/gitlab-lsp#2901