add telemetry for addProject actions

Author: eleanorjboyd

.github/prompts/add-telemetry.prompt.md

@@ -0,0 +1,22 @@
+---
+mode: agent
+---
+
+If the user does not specify an event name or properties, pick an informative and descriptive name for the telemetry event based on the task or feature. Add properties as you see fit to collect the necessary information to achieve the telemetry goal, ensuring they are relevant and useful for diagnostics or analytics.
+
+When adding telemetry:
+
+-   If the user wants to record when an action is started (such as a command invocation), place the telemetry call at the start of the handler or function.
+-   If the user wants to record successful completions or outcomes, place the telemetry call at the end of the action, after the operation has succeeded (and optionally, record errors or failures as well).
+
+Instructions to add a new telemetry event:
+
+1. Add a new event name to the `EventNames` enum in `src/common/telemetry/constants.ts`.
+2. Add a corresponding entry to the `IEventNamePropertyMapping` interface in the same file, including a GDPR comment and the expected properties.
+3. In the relevant code location, call `sendTelemetryEvent` with the new event name and required properties. Example:
+    ```typescript
+    sendTelemetryEvent(EventNames.YOUR_EVENT_NAME, undefined, { property: value });
+    ```
+4. If the event is triggered by a command, ensure the call is placed at the start of the command handler.
+
+Expected output: The new event is tracked in telemetry and follows the GDPR and codebase conventions.

src/common/telemetry/constants.ts

@@ -11,6 +11,7 @@ export enum EventNames {
     VENV_CREATION = 'VENV.CREATION',
 
     PACKAGE_MANAGEMENT = 'PACKAGE_MANAGEMENT',
+    ADD_PROJECT = 'ADD_PROJECT',
 }
 
 // Map all events to their properties
@@ -86,4 +87,19 @@ export interface IEventNamePropertyMapping {
         managerId: string;
         result: 'success' | 'error' | 'cancelled';
     };
+
+    /* __GDPR__
+        "add_project": {
+            "template": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "quickCreate": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "totalProjectCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "triggeredLocation": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.ADD_PROJECT]: {
+        template: string;
+        quickCreate: boolean;
+        totalProjectCount: number;
+        triggeredLocation: 'templateCreate' | 'add' | 'addGivenResource';
+    };
 }

src/extension.ts

@@ -1,4 +1,4 @@
-import { commands, extensions, ExtensionContext, LogOutputChannel, Terminal, Uri, window, workspace } from 'vscode';
+import { commands, ExtensionContext, extensions, LogOutputChannel, Terminal, Uri, window, workspace } from 'vscode';
 import { PythonEnvironment, PythonEnvironmentApi, PythonProjectCreator } from './api';
 import { ensureCorrectVersion } from './common/extVersion';
 import { registerLogger, traceError, traceInfo } from './common/logging';
@@ -75,27 +75,27 @@ import { registerPyenvFeatures } from './managers/pyenv/main';
 async function collectEnvironmentInfo(
     context: ExtensionContext,
     envManagers: EnvironmentManagers,
-    projectManager: PythonProjectManager
+    projectManager: PythonProjectManager,
 ): Promise<string> {
     const info: string[] = [];
-    
+
     try {
         // Extension version
         const extensionVersion = context.extension?.packageJSON?.version || 'unknown';
         info.push(`Extension Version: ${extensionVersion}`);
-        
+
         // Python extension version
         const pythonExtension = extensions.getExtension('ms-python.python');
         const pythonVersion = pythonExtension?.packageJSON?.version || 'not installed';
         info.push(`Python Extension Version: ${pythonVersion}`);
-        
+
         // Environment managers
         const managers = envManagers.managers;
         info.push(`\nRegistered Environment Managers (${managers.length}):`);
-        managers.forEach(manager => {
+        managers.forEach((manager) => {
             info.push(`  - ${manager.id} (${manager.displayName})`);
         });
-        
+
         // Available environments
         const allEnvironments: PythonEnvironment[] = [];
         for (const manager of managers) {
@@ -106,7 +106,7 @@ async function collectEnvironmentInfo(
                 info.push(`  Error getting environments from ${manager.id}: ${err}`);
             }
         }
-        
+
         info.push(`\nTotal Available Environments: ${allEnvironments.length}`);
         if (allEnvironments.length > 0) {
             info.push('Environment Details:');
@@ -117,7 +117,7 @@ async function collectEnvironmentInfo(
                 info.push(`  ... and ${allEnvironments.length - 10} more environments`);
             }
         }
-        
+
         // Python projects
         const projects = projectManager.getProjects();
         info.push(`\nPython Projects (${projects.length}):`);
@@ -133,18 +133,17 @@ async function collectEnvironmentInfo(
                 info.push(`     Error getting environment: ${err}`);
             }
         }
-        
+
         // Current settings (non-sensitive)
         const config = workspace.getConfiguration('python-envs');
         info.push('\nExtension Settings:');
         info.push(`  Default Environment Manager: ${config.get('defaultEnvManager')}`);
         info.push(`  Default Package Manager: ${config.get('defaultPackageManager')}`);
         info.push(`  Terminal Auto Activation: ${config.get('terminal.autoActivationType')}`);
-        
     } catch (err) {
         info.push(`\nError collecting environment information: ${err}`);
     }
-    
+
     return info.join('\n');
 }
 
@@ -273,13 +272,28 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         }),
         commands.registerCommand('python-envs.addPythonProject', async () => {
             await addPythonProjectCommand(undefined, projectManager, envManagers, projectCreators);
+            const totalProjectCount = projectManager.getProjects().length + 1;
+            sendTelemetryEvent(EventNames.ADD_PROJECT, undefined, {
+                template: 'none',
+                quickCreate: false,
+                totalProjectCount,
+                triggeredLocation: 'add',
+            });
         }),
         commands.registerCommand('python-envs.addPythonProjectGivenResource', async (resource) => {
             // Set context to show/hide menu item depending on whether the resource is already a Python project
             if (resource instanceof Uri) {
                 commands.executeCommand('setContext', 'python-envs:isExistingProject', isExistingProject(resource));
             }
+
             await addPythonProjectCommand(resource, projectManager, envManagers, projectCreators);
+            const totalProjectCount = projectManager.getProjects().length + 1;
+            sendTelemetryEvent(EventNames.ADD_PROJECT, undefined, {
+                template: 'none',
+                quickCreate: false,
+                totalProjectCount,
+                triggeredLocation: 'addGivenResource',
+            });
         }),
         commands.registerCommand('python-envs.removePythonProject', async (item) => {
             // Clear environment association before removing project
@@ -335,6 +349,9 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         commands.registerCommand(
             'python-envs.createNewProjectFromTemplate',
             async (projectType: string, quickCreate: boolean, newProjectName: string, newProjectPath: string) => {
+                let projectTemplateName = projectType || 'unknown';
+                let triggeredLocation: 'templateCreate' = 'templateCreate';
+                let totalProjectCount = projectManager.getProjects().length + 1;
                 if (quickCreate) {
                     if (!projectType || !newProjectName || !newProjectPath) {
                         throw new Error('Project type, name, and path are required for quick create.');
@@ -358,19 +375,26 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 } else {
                     const selected = await newProjectSelection(projectCreators.getProjectCreators());
                     if (selected) {
+                        projectTemplateName = selected.name || 'unknown';
                         await selected.create();
                     }
                 }
+                sendTelemetryEvent(EventNames.ADD_PROJECT, undefined, {
+                    template: projectTemplateName,
+                    quickCreate: quickCreate,
+                    totalProjectCount,
+                    triggeredLocation,
+                });
             },
         ),
         commands.registerCommand('python-envs.reportIssue', async () => {
             try {
                 const issueData = await collectEnvironmentInfo(context, envManagers, projectManager);
-                
+
                 await commands.executeCommand('workbench.action.openIssueReporter', {
                     extensionId: 'ms-python.vscode-python-envs',
                     issueTitle: '[Python Environments] ',
-                    issueBody: `<!-- Please describe the issue you're experiencing -->\n\n<!-- The following information was automatically generated -->\n\n<details>\n<summary>Environment Information</summary>\n\n\`\`\`\n${issueData}\n\`\`\`\n\n</details>`
+                    issueBody: `<!-- Please describe the issue you're experiencing -->\n\n<!-- The following information was automatically generated -->\n\n<details>\n<summary>Environment Information</summary>\n\n\`\`\`\n${issueData}\n\`\`\`\n\n</details>`,
                 });
             } catch (error) {
                 window.showErrorMessage(`Failed to open issue reporter: ${error}`);