Telemetry: non-blocking, broader categories, simple opt-out setting

- initTelemetry is now fire-and-forget — client.start() runs in the
  background so activation never blocks on it. trackEvent() was already
  in-memory + batched, so subsequent sendEvent calls are non-blocking.
- Drop per-command COMMAND_INVOKED events. Replace with FEATURE_USED,
  bucketed by broad category (sandbox/webdav/content/codeSync/apiBrowser/
  debugger/scaffold/cap/pageDesigner/logs/instance) and deduped to one
  event per category per session.
- Add b2c-dx.telemetry.enabled setting (default true). Telemetry is off
  if any of the three signals say off: VS Code's telemetry.telemetryLevel,
  this setting, or the SF/SFCC env var.
- Strip the Telemetry section from the docs site — the setting's
  description in the VS Code Settings UI is the disclosure surface. Add
  the row to the configuration page's settings reference table.
- Wire markFeatureUsed into the page-designer command and the script
  debugger factory so non-safety-wrapped features still register usage.

Author: clavery

.changeset/vscode-telemetry.md

@@ -2,4 +2,4 @@
 'b2c-vs-extension': minor
 ---
 
-Add anonymous usage telemetry (extension lifecycle, command invocations, exceptions) to help prioritize fixes during the Developer Preview. Honors VS Code's `telemetry.telemetryLevel` setting and the `SFCC_DISABLE_TELEMETRY` / `SF_DISABLE_TELEMETRY` environment variables. No credentials, hostnames, or business data are collected. See the [Telemetry section in Configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/vscode-extension/configuration#telemetry) for opt-out instructions and the full data inventory.
+Add anonymous usage telemetry (extension activation/deactivation lifecycle, broad feature-category usage, exceptions) to help prioritize fixes during the Developer Preview. Sending is non-blocking. Honors the new `b2c-dx.telemetry.enabled` setting (default `true`), VS Code's `telemetry.telemetryLevel`, and the `SFCC_DISABLE_TELEMETRY` / `SF_DISABLE_TELEMETRY` environment variables. No credentials, hostnames, or business data are collected.

docs/vscode-extension/configuration.md

@@ -11,7 +11,6 @@ This page covers:
 - [Connecting to a B2C Instance](#connecting-to-a-b2c-instance) — credentials per feature.
 - [Switching the Active Instance](#switching-the-active-instance) — single-workspace, multi-instance.
 - [Project Root Pinning](#project-root-pinning) — multi-root workspaces.
-- [Telemetry](#telemetry) — what we collect and how to opt out.
 - [Settings Reference](#settings-reference) — the `b2c-dx.*` toggles and verbosity controls.
 
 ## Connecting to a B2C Instance
@@ -76,24 +75,6 @@ In a multi-root workspace, the extension auto-detects the project root by walkin
 
 The pin is workspace-scoped (stored in workspace state).
 
-## Telemetry
-
-The extension reports anonymous usage data to help us prioritize fixes during the Developer Preview.
-
-**What we collect:** extension lifecycle events (`EXTENSION_ACTIVATED`, `EXTENSION_DEACTIVATED`, `ACTIVATION_FAILED`), command invocations (command ID, success/failure, duration), and exceptions. Each event includes anonymous session and machine identifiers, plus environment info (VS Code version, platform, architecture, Node.js version).
-
-**What we don't collect:** credentials, hostnames, sandbox IDs, file contents, command arguments, or any business data. String attributes have `$HOME` redacted to `~` before transmission.
-
-**Opt out** in any of the following ways — telemetry is disabled if **any** of them is true:
-
-| Source | Setting |
-| ------ | ------- |
-| VS Code `settings.json` | `"telemetry.telemetryLevel": "off"` (also disables when set to `crash` or `error`) |
-| Environment variable | `SFCC_DISABLE_TELEMETRY=true` |
-| Environment variable | `SF_DISABLE_TELEMETRY=true` (Salesforce CLI standard) |
-
-The extension respects VS Code's built-in `telemetry.telemetryLevel` first, so opting out of all VS Code telemetry automatically disables ours.
-
 ## Settings Reference
 
 These VS Code settings live under the `b2c-dx.*` namespace. **You usually don't need to change any of them** — they exist for niche cases like disabling a feature you don't use, or quieting the log channel for a bug report. To browse: **Settings** (Cmd+,) → search for `b2c-dx`.
@@ -115,12 +96,13 @@ Each feature is enabled by default. Set to `false` to skip its activation entire
 
 The B2C Script Debugger registers regardless of these toggles — it activates only when a `b2c-script` launch configuration is used.
 
-### Verbosity & polling
+### Verbosity, polling, telemetry
 
 | Setting | Default | Description |
 | ------- | ------- | ----------- |
 | `b2c-dx.logLevel` | `info` | Verbosity for the **B2C DX** output channel. Allowed: `trace`, `debug`, `info`, `warn`, `error`, `silent`. Applied immediately on change. Drop to `debug` or `trace` when filing a bug. |
 | `b2c-dx.sandbox.pollingInterval` | `10` | Seconds between polls while a sandbox is in a transitional state (`creating`, `starting`, `stopping`, `deleting`, `cloning`). Range: 2–300. Polling stops automatically once the realm settles. |
+| `b2c-dx.telemetry.enabled` | `true` | Send anonymous usage telemetry. Honors VS Code's `telemetry.telemetryLevel` — disabling that disables this regardless of this setting. |
 
 ### Complete defaults (copy-paste)
 
@@ -136,7 +118,8 @@ The B2C Script Debugger registers regardless of these toggles — it activates o
   "b2c-dx.features.apiBrowser": true,
   "b2c-dx.features.cap": true,
   "b2c-dx.logLevel": "info",
-  "b2c-dx.sandbox.pollingInterval": 10
+  "b2c-dx.sandbox.pollingInterval": 10,
+  "b2c-dx.telemetry.enabled": true
 }
 ```
 

packages/b2c-vs-extension/package.json

@@ -96,6 +96,11 @@
           "type": "boolean",
           "default": true,
           "description": "Enable Code Sync (watch and deploy cartridges)."
+        },
+        "b2c-dx.telemetry.enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Send anonymous usage telemetry (extension lifecycle and broad feature-category events). Honors VS Code's telemetry.telemetryLevel — disabling that disables this regardless of this setting."
         }
       }
     },

packages/b2c-vs-extension/src/debugger/index.ts

@@ -8,13 +8,15 @@ import {B2CScriptDebugAdapter} from '@salesforce/b2c-tooling-sdk/operations/debu
 import type {DebugSessionConfig} from '@salesforce/b2c-tooling-sdk/operations/debug';
 import * as vscode from 'vscode';
 import type {B2CExtensionConfig} from '../config-provider.js';
+import {markFeatureUsed} from '../telemetry.js';
 
 const DEBUG_TYPE = 'b2c-script';
 
 class B2CDebugAdapterFactory implements vscode.DebugAdapterDescriptorFactory {
   constructor(private readonly configProvider: B2CExtensionConfig) {}
 
   createDebugAdapterDescriptor(_session: vscode.DebugSession): vscode.ProviderResult<vscode.DebugAdapterDescriptor> {
+    markFeatureUsed('debugger');
     const config = this.configProvider.getConfig();
     if (!config || !config.hasB2CInstanceConfig()) {
       void vscode.window.showErrorMessage(

packages/b2c-vs-extension/src/extension.ts

@@ -22,7 +22,7 @@ import {registerApiBrowser} from './api-browser/index.js';
 import {registerDebugger} from './debugger/index.js';
 import {registerCodeSync} from './code-sync/index.js';
 import {registerWebDavTree} from './webdav-tree/index.js';
-import {disposeTelemetry, initTelemetry, sendEvent, sendException} from './telemetry.js';
+import {disposeTelemetry, initTelemetry, markFeatureUsed, sendEvent, sendException} from './telemetry.js';
 
 function getWebviewContent(context: vscode.ExtensionContext): string {
   const htmlPath = path.join(context.extensionPath, 'src', 'webview.html');
@@ -115,15 +115,14 @@ export async function activate(context: vscode.ExtensionContext) {
 
   applyLogLevel(log);
 
-  // Best-effort telemetry init. A no-op when the user has VS Code telemetry
-  // disabled, when SFCC_DISABLE_TELEMETRY/SF_DISABLE_TELEMETRY is set, or when
-  // no connection string is configured.
-  await initTelemetry(context);
-  const activationStart = Date.now();
+  // Best-effort telemetry init. Non-blocking: client.start() runs in the
+  // background. No-ops entirely when the user has telemetry disabled or no
+  // connection string is configured.
+  initTelemetry(context);
 
   try {
     const result = await activateInner(context, log);
-    sendEvent('EXTENSION_ACTIVATED', {durationMs: Date.now() - activationStart});
+    sendEvent('EXTENSION_ACTIVATED');
     return result;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -132,7 +131,7 @@ export async function activate(context: vscode.ExtensionContext) {
     if (stack) log.appendLine(stack);
     console.error('B2C DX extension activation failed:', err);
     if (err instanceof Error) sendException(err, {phase: 'activate'});
-    sendEvent('ACTIVATION_FAILED', {durationMs: Date.now() - activationStart});
+    sendEvent('ACTIVATION_FAILED');
     vscode.window.showErrorMessage(`B2C DX: Extension failed to activate. See Output > B2C DX. Error: ${message}`);
     const showActivationError = () => {
       log.show();
@@ -166,6 +165,7 @@ async function activateInner(context: vscode.ExtensionContext, log: vscode.Outpu
   registerSafety(context, configProvider);
 
   const disposable = vscode.commands.registerCommand('b2c-dx.openUI', () => {
+    markFeatureUsed('pageDesigner');
     vscode.window.showInformationMessage('B2C DX: Opening Page Designer Assistant.');
 
     const panel = vscode.window.createWebviewPanel(

packages/b2c-vs-extension/src/safety.ts

@@ -15,7 +15,32 @@ import {createSafetyMiddleware, globalMiddlewareRegistry} from '@salesforce/b2c-
 import {getLogger} from '@salesforce/b2c-tooling-sdk/logging';
 import * as vscode from 'vscode';
 import type {B2CExtensionConfig} from './config-provider.js';
-import {wrapCommandHandler} from './telemetry.js';
+import {type FeatureCategory, markFeatureUsed} from './telemetry.js';
+
+/**
+ * Map command-id prefixes to broad feature categories so usage telemetry can
+ * answer "did the user use feature X this session" without per-command noise.
+ * Commands not matched here don't emit a usage event (the lifecycle events
+ * still fire). Keep the prefix list short and stable.
+ */
+const COMMAND_PREFIX_TO_CATEGORY: Array<readonly [string, FeatureCategory]> = [
+  ['b2c-dx.sandbox.', 'sandbox'],
+  ['b2c-dx.webdav.', 'webdav'],
+  ['b2c-dx.content.', 'content'],
+  ['b2c-dx.codeSync.', 'codeSync'],
+  ['b2c-dx.apiBrowser.', 'apiBrowser'],
+  ['b2c-dx.scaffold.', 'scaffold'],
+  ['b2c-dx.cap.', 'cap'],
+  ['b2c-dx.logs.', 'logs'],
+  ['b2c-dx.instance.', 'instance'],
+];
+
+function categoryForCommand(commandId: string): FeatureCategory | undefined {
+  for (const [prefix, category] of COMMAND_PREFIX_TO_CATEGORY) {
+    if (commandId.startsWith(prefix)) return category;
+  }
+  return undefined;
+}
 
 const PROVIDER_NAME = 'vscode-safety-guard';
 
@@ -100,9 +125,10 @@ export function runWithSafety<T>(operation: () => Promise<T>, detail?: string):
 // Matches vscode.commands.registerCommand's own signature, which uses any[] for context-menu args.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function registerSafeCommand(commandId: string, handler: (...args: any[]) => any): vscode.Disposable {
-  const tracedHandler = wrapCommandHandler(commandId, handler);
+  const category = categoryForCommand(commandId);
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return vscode.commands.registerCommand(commandId, async (...args: any[]) => {
+    if (category) markFeatureUsed(category);
     try {
       currentGuard.assert({type: 'command', commandId});
     } catch (err) {
@@ -119,13 +145,13 @@ export function registerSafeCommand(commandId: string, handler: (...args: any[])
         if (choice !== 'Proceed') return undefined;
         const release = currentGuard.temporarilyAllow(err.evaluation.operation);
         try {
-          return await tracedHandler(...args);
+          return await handler(...args);
         } finally {
           release();
         }
       }
       throw err;
     }
-    return tracedHandler(...args);
+    return handler(...args);
   });
 }