From c883db9ee43975d4efd69582195335e938308ce2 Mon Sep 17 00:00:00 2001 From: Ehab Younes Date: Thu, 11 Jun 2026 19:08:08 +0300 Subject: [PATCH] docs: document VS Code local telemetry (#26215) Document local telemetry behavior, diagnostics commands, support bundle contents, and the VS Code telemetry event reference. --- docs/support/support-bundle.md | 8 +++ docs/user-guides/workspace-access/vscode.md | 67 +++++++++++++++++++++ 2 files changed, 75 insertions(+) diff --git a/docs/support/support-bundle.md b/docs/support/support-bundle.md index 11bd7a4183..b28ffc6c1d 100644 --- a/docs/support/support-bundle.md +++ b/docs/support/support-bundle.md @@ -53,6 +53,7 @@ A brief overview of all files contained in the bundle is provided below: | `workspace/template.json` | The template currently in use by the selected workspace. | | `workspace/template_file.zip` | The source code of the template currently in use by the selected workspace. | | `workspace/template_version.json` | The template version currently in use by the selected workspace. | +| `vscode-logs/` | Only present when generated from the VS Code Coder Remote extension. Includes logs, redacted settings, and local telemetry files. | ## How do I generate a Support Bundle? @@ -76,6 +77,13 @@ A brief overview of all files contained in the bundle is provided below: prompt. The support bundle will be generated in the current directory with the filename `coder-support-$TIMESTAMP.zip`. + If you use VS Code, you can also run **Coder: Create Support Bundle** from + the Command Palette. The VS Code Coder Remote extension runs + `coder support bundle` and appends recent VS Code diagnostics to the + generated archive. Bundles created with the CLI alone do not include + `vscode-logs/`. Learn more about + [VS Code diagnostics](../user-guides/workspace-access/vscode.md#diagnostics-and-support-bundles). + > [!NOTE] > While support bundles can be generated without a running workspace, it is > recommended to specify one to maximize troubleshooting information. diff --git a/docs/user-guides/workspace-access/vscode.md b/docs/user-guides/workspace-access/vscode.md index 3f89ac8e25..a467fbc376 100644 --- a/docs/user-guides/workspace-access/vscode.md +++ b/docs/user-guides/workspace-access/vscode.md @@ -34,6 +34,73 @@ ext install coder.coder-remote Alternatively, manually install the VSIX from the [latest release](https://github.com/coder/vscode-coder/releases/latest). +## Local telemetry + +The Coder Remote extension records local telemetry to help diagnose extension +and workspace connection issues. Telemetry is stored on your machine. It is not +sent to Coder unless you export it or include it in a support bundle and share +that file. + +Local telemetry is controlled by the VS Code setting `coder.telemetry.level`: + +| Value | Behavior | +|---------|---------------------------------------------------------------| +| `off` | Disable extension telemetry collection. | +| `local` | Record telemetry events on this machine. This is the default. | + +### Stored data + +Telemetry can include diagnostic details such as extension version, VS Code +version, operating system, machine and session identifiers, deployment URL, +workspace and agent names, command outcomes, connection state, request routes, +timing, and error details. It does not intentionally collect source code, +terminal contents, tokens, or credentials. + +### Tracked activity + +The exact events vary by extension version. For a comprehensive list of current +events, properties, and attributes, see the +[extension event reference](https://github.com/coder/vscode-coder/blob/main/src/instrumentation/EVENTS.md). +The following categories summarize the diagnostic signals the extension may +record: + +| Area | Examples | +|--------------------------------|----------------------------------------------------------------------------------------------| +| Extension lifecycle | Activation, deployment initialization, and configuration loading. | +| Authentication and credentials | Sign-in state, token refresh, logout, credential storage, and deployment recovery. | +| Commands and diagnostics | Command outcomes, telemetry exports, support bundle creation, ping, and speed tests. | +| Workspace workflows | Workspace selection, open attempts, dev container handoff, start, and update prompts. | +| CLI and remote setup | CLI binary resolution, download, verification, configuration, and setup through SSH handoff. | +| Connection health | Workspace and agent state transitions, reconnects, SSH process health, and network samples. | +| HTTP diagnostics | Normalized routes, status classes, and latency rollups. | + +### Storage and retention + +The extension stores telemetry as JSON Lines files in its VS Code global storage +under a `telemetry` directory. Files rotate at 5 MiB, are kept for up to 30 days, +and are capped at 100 MiB total by default. + +You can tune local retention with the advanced `coder.telemetry.local` setting. +Most users should keep the default values. + +### Diagnostics and support bundles + +The extension includes commands for collecting diagnostics from VS Code: + +- **Coder: Export Telemetry** exports only local telemetry. Choose a date range + and JSON or OTLP JSON zip format, then review the file before sharing it. +- **Coder: Create Support Bundle** runs `coder support bundle` and adds a + `vscode-logs/` directory with recent VS Code extension diagnostics, including + extension logs, proxy and Remote-SSH logs, redacted VS Code settings, and + local telemetry files when available. The `vscode-logs/` directory is only + added when the bundle is created from the VS Code Coder Remote extension; + bundles created with the CLI alone do not include it. +- **Coder: View Logs** opens the extension output logs in VS Code. + +Support bundles can contain sensitive diagnostic data. Review the generated +bundle before sharing it. Learn more about +[support bundles](../../support/support-bundle.md). + ## VS Code extensions There are multiple ways to add extensions to VS Code Desktop: