Add ENVIRONMENT_TOOL_USAGE telemetry to track actual environment tool usage (#1272)

This is a follow-up PR after discussion with Eleanor and Graham, the PR
adds a new ENVIRONMENT_TOOL_USAGE telemetry event that fires once per
distinct environment tool actively in use across a user's projects. It
resolves each project's actual environment and emits `toolName` for each
unique tool (e.g., venv, uv, conda, poetry, system). UV environments are
detected separately since they share the `venv` manager. Will add a new
chart to the dashboard once it's checked in.

Author: StellaHuang95

src/common/telemetry/constants.ts

@@ -32,6 +32,14 @@ export enum EventNames {
      * - projectUnderRoot: number (count of projects nested under workspace roots)
      */
     PROJECT_STRUCTURE = 'PROJECT_STRUCTURE',
+    /**
+     * Telemetry event for environment tool usage at extension startup.
+     * Fires once per tool that has at least one project using it.
+     * Use dcount(machineId) by toolName to get unique users per tool.
+     * Properties:
+     * - toolName: string (the tool being used: venv, conda, poetry, etc.)
+     */
+    ENVIRONMENT_TOOL_USAGE = 'ENVIRONMENT_TOOL_USAGE',
     /**
      * Telemetry event for environment discovery per manager.
      * Properties:
@@ -195,6 +203,14 @@ export interface IEventNamePropertyMapping {
         projectUnderRoot: number;
     };
 
+    /* __GDPR__
+        "environment_tool_usage": {
+            "toolName": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "stellaHuang95" }
+        }
+    */
+    [EventNames.ENVIRONMENT_TOOL_USAGE]: {
+        toolName: string;
+    };
     /* __GDPR__
         "environment_discovery": {
             "managerId": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },

src/common/telemetry/helpers.ts

@@ -1,9 +1,22 @@
 import { getDefaultEnvManagerSetting, getDefaultPkgManagerSetting } from '../../features/settings/settingHelpers';
 import { EnvironmentManagers, PythonProjectManager } from '../../internal.api';
+import { getUvEnvironments } from '../../managers/builtin/uvEnvironments';
+import { traceVerbose } from '../logging';
 import { getWorkspaceFolders } from '../workspace.apis';
 import { EventNames } from './constants';
 import { sendTelemetryEvent } from './sender';
 
+/**
+ * Extracts the base tool name from a manager ID.
+ * Example: 'ms-python.python:venv' -> 'venv'
+ * Example: 'ms-python.python:conda' -> 'conda'
+ */
+function extractToolName(managerId: string): string {
+    // Manager IDs follow the pattern 'extensionId:toolName'
+    const parts = managerId.split(':');
+    return parts.length > 1 ? parts[1].toLowerCase() : managerId.toLowerCase();
+}
+
 export function sendManagerSelectionTelemetry(pm: PythonProjectManager) {
     const ems: Set<string> = new Set();
     const ps: Set<string> = new Set();
@@ -58,7 +71,7 @@ export async function sendProjectStructureTelemetry(
         for (const wsFolder of workspaceFolders) {
             const workspacePath = wsFolder.uri.fsPath;
             const projectPath = project.uri.fsPath;
-            
+
             // Check if project is a subdirectory of workspace folder:
             // - Path must start with workspace path
             // - Path must not be equal to workspace path
@@ -80,3 +93,64 @@ export async function sendProjectStructureTelemetry(
         projectUnderRoot,
     });
 }
+
+/**
+ * Sends telemetry about which environment tools are actively used across all projects.
+ * This tracks ACTUAL USAGE (which environments are set for projects), not just what's installed.
+ *
+ * Fires one event per tool that has at least one project using it.
+ * This allows simple deduplication: dcount(machineId) by toolName gives unique users per tool.
+ *
+ * Called once at extension activation to understand user's environment tool usage patterns.
+ */
+export async function sendEnvironmentToolUsageTelemetry(
+    pm: PythonProjectManager,
+    envManagers: EnvironmentManagers,
+): Promise<void> {
+    try {
+        const projects = pm.getProjects();
+
+        // Track which tools are used (Set ensures uniqueness)
+        const toolsUsed = new Set<string>();
+
+        // Lazily loaded once when a venv environment is first encountered
+        let uvEnvPaths: string[] | undefined;
+
+        // Check which environment manager is used for each project
+        for (const project of projects) {
+            try {
+                const env = await envManagers.getEnvironment(project.uri);
+                if (env?.envId?.managerId) {
+                    let toolName = extractToolName(env.envId.managerId);
+
+                    // UV environments share the venv manager. Check the persistent UV env list instead
+                    if (toolName === 'venv' && env.environmentPath) {
+                        uvEnvPaths ??= await getUvEnvironments();
+                        if (uvEnvPaths.includes(env.environmentPath.fsPath)) {
+                            toolName = 'uv';
+                        }
+                    }
+
+                    // Normalize 'global' to 'system' for consistency
+                    if (toolName === 'global') {
+                        toolName = 'system';
+                    }
+
+                    toolsUsed.add(toolName);
+                }
+            } catch {
+                // Ignore errors when getting environment for a project
+            }
+        }
+
+        // Fire one event per tool used
+        toolsUsed.forEach((tool) => {
+            sendTelemetryEvent(EventNames.ENVIRONMENT_TOOL_USAGE, undefined, {
+                toolName: tool,
+            });
+        });
+    } catch (error) {
+        // Telemetry failures must never disrupt extension activation
+        traceVerbose('Failed to send environment tool usage telemetry:', error);
+    }
+}

src/extension.ts

@@ -17,7 +17,11 @@ import { clearPersistentState, setPersistentState } from './common/persistentSta
 import { newProjectSelection } from './common/pickers/managers';
 import { StopWatch } from './common/stopWatch';
 import { EventNames } from './common/telemetry/constants';
-import { sendManagerSelectionTelemetry, sendProjectStructureTelemetry } from './common/telemetry/helpers';
+import {
+    sendEnvironmentToolUsageTelemetry,
+    sendManagerSelectionTelemetry,
+    sendProjectStructureTelemetry,
+} from './common/telemetry/helpers';
 import { sendTelemetryEvent } from './common/telemetry/sender';
 import { createDeferred } from './common/utils/deferred';
 
@@ -545,6 +549,7 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
             await terminalManager.initialize(api);
             sendManagerSelectionTelemetry(projectManager);
             await sendProjectStructureTelemetry(projectManager, envManagers);
+            await sendEnvironmentToolUsageTelemetry(projectManager, envManagers);
         } catch (error) {
             traceError('Failed to initialize environment managers:', error);
             // Show a user-friendly error message