Add telemetry for manager registration failures (#1365)

StellaHuang95 · web-flow · commit f4021cac697d · 2026-03-18T10:18:42.000-07:00
Adds telemetry to diagnose why environments sometimes fail to appear for
users. Currently we do not know what went wrong or what's missing.

### New telemetry events
- **`MANAGER_REGISTRATION.FAILED`** — Fires when a manager throws an
unexpected error during registration. Tells us which managers fail and
the classified error type.

- **`MANAGER_REGISTRATION.SKIPPED`** — Fires when a manager's tool
(conda/pyenv/pipenv/poetry) wasn't found on the system. Tells us which
managers are commonly unavailable, helping us understand user
environments. Without `SKIPPED`, we'd only see that a manager didn't
register. We couldn't tell whether that's because the user doesn't use
conda (fine, nothing to fix) or because conda is installed but our code
crashed trying to register it (bug).

- **`SETUP.HANG_DETECTED`** — Fires when the entire setup block hasn't
completed within 120s. Tells us which stage was in progress when the
hang occurred (nativeFinder, managerRegistration, envSelection, etc.).


### Enhanced existing event

- **`EXTENSION_MANAGER_REGISTRATION_DURATION`** now includes `result`
(`success`/`error`), `failureStage`, and `errorType` — previously it
only reported duration.

### Non-telemetry changes

- **Conda registration refactor:** Separated the "conda not found" path
(try/catch on `getConda`) from the registration path, so `SKIPPED` vs
`FAILED` telemetry is accurate. Post-getConda errors still call
`notifyMissingManagerIfDefault` and re-throw for `safeRegister` to
handle.
- **`safeRegister` in asyncUtils.ts:** Now sends
`MANAGER_REGISTRATION.FAILED` telemetry when a manager's promise
rejects, so failures are captured even when individual managers don't
add their own telemetry.
diff --git a/src/common/telemetry/constants.ts b/src/common/telemetry/constants.ts
@@ -50,6 +50,30 @@ export enum EventNames {
      */
     ENVIRONMENT_DISCOVERY = 'ENVIRONMENT_DISCOVERY',
     MANAGER_READY_TIMEOUT = 'MANAGER_READY.TIMEOUT',
+    /**
+     * Telemetry event for individual manager registration failure.
+     * Fires once per manager that fails during registration (inside safeRegister).
+     * Properties:
+     * - managerName: string (e.g. 'system', 'conda', 'pyenv', 'pipenv', 'poetry', 'shellStartupVars')
+     * - errorType: string (classified error category from classifyError)
+     */
+    MANAGER_REGISTRATION_FAILED = 'MANAGER_REGISTRATION.FAILED',
+    /**
+     * Telemetry event fired when the setup block appears to be hung.
+     * A watchdog timer fires after a deadline; if the setup completes normally,
+     * the timer is cancelled and this event never fires.
+     * Properties:
+     * - failureStage: string (which phase was in progress when the watchdog fired)
+     */
+    SETUP_HANG_DETECTED = 'SETUP.HANG_DETECTED',
+    /**
+     * Telemetry event for when a manager skips registration because its tool was not found.
+     * This is an expected outcome (not an error) and is distinct from MANAGER_REGISTRATION_FAILED.
+     * Properties:
+     * - managerName: string (e.g. 'conda', 'pyenv', 'pipenv', 'poetry')
+     * - reason: string ('tool_not_found')
+     */
+    MANAGER_REGISTRATION_SKIPPED = 'MANAGER_REGISTRATION.SKIPPED',
 }
 
 // Map all events to their properties
@@ -62,10 +86,17 @@ export interface IEventNamePropertyMapping {
     [EventNames.EXTENSION_ACTIVATION_DURATION]: never | undefined;
     /* __GDPR__
        "extension.manager_registration_duration": {
-           "duration" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" }
+           "duration" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+           "result" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
+           "failureStage" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
+           "errorType" : { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" }
        }
     */
-    [EventNames.EXTENSION_MANAGER_REGISTRATION_DURATION]: never | undefined;
+    [EventNames.EXTENSION_MANAGER_REGISTRATION_DURATION]: {
+        result: 'success' | 'error';
+        failureStage?: string;
+        errorType?: string;
+    };
 
     /* __GDPR__
         "environment_manager.registered": {
@@ -239,4 +270,36 @@ export interface IEventNamePropertyMapping {
         managerId: string;
         managerKind: 'environment' | 'package';
     };
+
+    /* __GDPR__
+        "manager_registration.failed": {
+            "managerName": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
+            "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" }
+        }
+    */
+    [EventNames.MANAGER_REGISTRATION_FAILED]: {
+        managerName: string;
+        errorType: string;
+    };
+
+    /* __GDPR__
+        "setup.hang_detected": {
+            "failureStage": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
+            "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "StellaHuang95" }
+        }
+    */
+    [EventNames.SETUP_HANG_DETECTED]: {
+        failureStage: string;
+    };
+
+    /* __GDPR__
+        "manager_registration.skipped": {
+            "managerName": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
+            "reason": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" }
+        }
+    */
+    [EventNames.MANAGER_REGISTRATION_SKIPPED]: {
+        managerName: string;
+        reason: 'tool_not_found';
+    };
 }
diff --git a/src/common/utils/asyncUtils.ts b/src/common/utils/asyncUtils.ts
@@ -1,4 +1,7 @@
 import { traceError } from '../logging';
+import { EventNames } from '../telemetry/constants';
+import { classifyError } from '../telemetry/errorClassifier';
+import { sendTelemetryEvent } from '../telemetry/sender';
 
 export async function timeout(milliseconds: number): Promise<void> {
     return new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
@@ -13,5 +16,9 @@ export async function safeRegister(name: string, task: Promise<void>): Promise<v
         await task;
     } catch (error) {
         traceError(`Failed to register ${name} features:`, error);
+        sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
+            managerName: name,
+            errorType: classifyError(error),
+        });
     }
 }
diff --git a/src/extension.ts b/src/extension.ts
@@ -17,6 +17,7 @@ import { clearPersistentState, setPersistentState } from './common/persistentSta
 import { newProjectSelection } from './common/pickers/managers';
 import { StopWatch } from './common/stopWatch';
 import { EventNames } from './common/telemetry/constants';
+import { classifyError } from './common/telemetry/errorClassifier';
 import {
     logDiscoverySummary,
     sendEnvironmentToolUsageTelemetry,
@@ -522,13 +523,34 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
      * Below are all the contributed features using the APIs.
      */
     setImmediate(async () => {
+        let failureStage = 'nativeFinder';
+        // Watchdog: fires if setup hasn't completed within 120s, indicating a likely hang
+        const SETUP_HANG_TIMEOUT_MS = 120_000;
+        let hangWatchdogActive = true;
+        const clearHangWatchdog = () => {
+            if (!hangWatchdogActive) {
+                return;
+            }
+            hangWatchdogActive = false;
+            clearTimeout(hangWatchdog);
+        };
+        const hangWatchdog = setTimeout(() => {
+            if (!hangWatchdogActive) {
+                return;
+            }
+            hangWatchdogActive = false;
+            traceError(`Setup appears hung during stage: ${failureStage}`);
+            sendTelemetryEvent(EventNames.SETUP_HANG_DETECTED, start.elapsedTime, { failureStage });
+        }, SETUP_HANG_TIMEOUT_MS);
+        context.subscriptions.push({ dispose: clearHangWatchdog });
         try {
             // This is the finder that is used by all the built in environment managers
             const nativeFinder: NativePythonFinder = await createNativePythonFinder(outputChannel, api, context);
             context.subscriptions.push(nativeFinder);
             const sysMgr = new SysPythonManager(nativeFinder, api, outputChannel);
             sysPythonManager.resolve(sysMgr);
             // Each manager registers independently — one failure must not block the others.
+            failureStage = 'managerRegistration';
             await Promise.all([
                 safeRegister(
                     'system',
@@ -547,17 +569,23 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 safeRegister('shellStartupVars', shellStartupVarsMgr.initialize()),
             ]);
 
+            failureStage = 'envSelection';
             await applyInitialEnvironmentSelection(envManagers, projectManager, nativeFinder, api);
 
             // Register manager-agnostic terminal watcher for package-modifying commands
+            failureStage = 'terminalWatcher';
             registerTerminalPackageWatcher(api, terminalActivation, outputChannel, context.subscriptions);
 
             // Register listener for interpreter settings changes for interpreter re-selection
+            failureStage = 'settingsListener';
             context.subscriptions.push(
                 registerInterpreterSettingsChangeListener(envManagers, projectManager, nativeFinder, api),
             );
 
-            sendTelemetryEvent(EventNames.EXTENSION_MANAGER_REGISTRATION_DURATION, start.elapsedTime);
+            sendTelemetryEvent(EventNames.EXTENSION_MANAGER_REGISTRATION_DURATION, start.elapsedTime, {
+                result: 'success',
+            });
+            clearHangWatchdog();
             try {
                 await terminalManager.initialize(api);
                 sendManagerSelectionTelemetry(projectManager);
@@ -570,11 +598,16 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
                 traceError('Post-initialization tasks failed:', postInitError);
             }
         } catch (error) {
+            clearHangWatchdog();
             traceError('Failed to initialize environment managers:', error);
             sendTelemetryEvent(
                 EventNames.EXTENSION_MANAGER_REGISTRATION_DURATION,
                 start.elapsedTime,
-                undefined,
+                {
+                    result: 'error',
+                    failureStage,
+                    errorType: classifyError(error),
+                },
                 error instanceof Error ? error : undefined,
             );
             // Show a user-friendly error message
diff --git a/src/managers/conda/main.ts b/src/managers/conda/main.ts
@@ -1,6 +1,8 @@
 import { Disposable, LogOutputChannel } from 'vscode';
 import { PythonEnvironmentApi } from '../../api';
 import { traceInfo } from '../../common/logging';
+import { EventNames } from '../../common/telemetry/constants';
+import { sendTelemetryEvent } from '../../common/telemetry/sender';
 import { getPythonApi } from '../../features/pythonApi';
 import { PythonProjectManager } from '../../internal.api';
 import { NativePythonFinder } from '../common/nativePythonFinder';
@@ -18,9 +20,22 @@ export async function registerCondaFeatures(
 ): Promise<void> {
     const api: PythonEnvironmentApi = await getPythonApi();
 
+    let condaPath: string | undefined;
     try {
         // get Conda will return only ONE conda manager, that correlates to a single conda install
-        const condaPath: string = await getConda(nativeFinder);
+        condaPath = await getConda(nativeFinder);
+    } catch (ex) {
+        traceInfo('Conda not found, turning off conda features.', ex);
+        sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_SKIPPED, undefined, {
+            managerName: 'conda',
+            reason: 'tool_not_found',
+        });
+        await notifyMissingManagerIfDefault('ms-python.python:conda', projectManager, api);
+        return;
+    }
+
+    // Conda was found — errors below are real registration failures (let safeRegister handle telemetry)
+    try {
         const sourcingStatus: CondaSourcingStatus = await constructCondaSourcingStatus(condaPath);
         traceInfo(sourcingStatus.toString());
 
@@ -36,7 +51,7 @@ export async function registerCondaFeatures(
             api.registerPackageManager(packageManager),
         );
     } catch (ex) {
-        traceInfo('Conda not found, turning off conda features.', ex);
         await notifyMissingManagerIfDefault('ms-python.python:conda', projectManager, api);
+        throw ex;
     }
 }
diff --git a/src/managers/pipenv/main.ts b/src/managers/pipenv/main.ts
@@ -1,6 +1,9 @@
 import { Disposable } from 'vscode';
 import { PythonEnvironmentApi } from '../../api';
 import { traceInfo } from '../../common/logging';
+import { EventNames } from '../../common/telemetry/constants';
+import { classifyError } from '../../common/telemetry/errorClassifier';
+import { sendTelemetryEvent } from '../../common/telemetry/sender';
 import { getPythonApi } from '../../features/pythonApi';
 import { PythonProjectManager } from '../../internal.api';
 import { NativePythonFinder } from '../common/nativePythonFinder';
@@ -35,13 +38,21 @@ export async function registerPipenvFeatures(
             traceInfo(
                 'Pipenv not found, turning off pipenv features. If you have pipenv installed in a non-standard location, set the "python.pipenvPath" setting.',
             );
+            sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_SKIPPED, undefined, {
+                managerName: 'pipenv',
+                reason: 'tool_not_found',
+            });
             await notifyMissingManagerIfDefault('ms-python.python:pipenv', projectManager, api);
         }
     } catch (ex) {
         traceInfo(
             'Pipenv not found, turning off pipenv features. If you have pipenv installed in a non-standard location, set the "python.pipenvPath" setting.',
             ex,
         );
+        sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
+            managerName: 'pipenv',
+            errorType: classifyError(ex),
+        });
         await notifyMissingManagerIfDefault('ms-python.python:pipenv', projectManager, api);
     }
 }
diff --git a/src/managers/poetry/main.ts b/src/managers/poetry/main.ts
@@ -1,6 +1,9 @@
 import { Disposable, LogOutputChannel } from 'vscode';
 import { PythonEnvironmentApi } from '../../api';
 import { traceInfo } from '../../common/logging';
+import { EventNames } from '../../common/telemetry/constants';
+import { classifyError } from '../../common/telemetry/errorClassifier';
+import { sendTelemetryEvent } from '../../common/telemetry/sender';
 import { getPythonApi } from '../../features/pythonApi';
 import { PythonProjectManager } from '../../internal.api';
 import { NativePythonFinder } from '../common/nativePythonFinder';
@@ -36,10 +39,18 @@ export async function registerPoetryFeatures(
             );
         } else {
             traceInfo('Poetry not found, turning off poetry features.');
+            sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_SKIPPED, undefined, {
+                managerName: 'poetry',
+                reason: 'tool_not_found',
+            });
             await notifyMissingManagerIfDefault('ms-python.python:poetry', projectManager, api);
         }
     } catch (ex) {
         traceInfo('Poetry not found, turning off poetry features.', ex);
+        sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
+            managerName: 'poetry',
+            errorType: classifyError(ex),
+        });
         await notifyMissingManagerIfDefault('ms-python.python:poetry', projectManager, api);
     }
 }
diff --git a/src/managers/pyenv/main.ts b/src/managers/pyenv/main.ts
@@ -1,6 +1,9 @@
 import { Disposable } from 'vscode';
 import { PythonEnvironmentApi } from '../../api';
 import { traceInfo } from '../../common/logging';
+import { EventNames } from '../../common/telemetry/constants';
+import { classifyError } from '../../common/telemetry/errorClassifier';
+import { sendTelemetryEvent } from '../../common/telemetry/sender';
 import { getPythonApi } from '../../features/pythonApi';
 import { PythonProjectManager } from '../../internal.api';
 import { NativePythonFinder } from '../common/nativePythonFinder';
@@ -23,10 +26,18 @@ export async function registerPyenvFeatures(
             disposables.push(mgr, api.registerEnvironmentManager(mgr));
         } else {
             traceInfo('Pyenv not found, turning off pyenv features.');
+            sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_SKIPPED, undefined, {
+                managerName: 'pyenv',
+                reason: 'tool_not_found',
+            });
             await notifyMissingManagerIfDefault('ms-python.python:pyenv', projectManager, api);
         }
     } catch (ex) {
         traceInfo('Pyenv not found, turning off pyenv features.', ex);
+        sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
+            managerName: 'pyenv',
+            errorType: classifyError(ex),
+        });
         await notifyMissingManagerIfDefault('ms-python.python:pyenv', projectManager, api);
     }
 }
