Add failureStage to MANAGER_REGISTRATION_FAILED telemetry for granular error diagnosis (#1405)

StellaHuang95 · eleanorjboyd · web-flow · commit f8d3243b9768 · 2026-03-27T08:55:02.000-07:00
## Problem

When `MANAGER_REGISTRATION.FAILED` fires, we only know which manager
failed and the classified error type. We do not know where in the
registration flow the error occurred, such as settings lookup,
persistent state access, path validation, native finder refresh, or
manager registration. That makes telemetry harder to use for diagnosis
and prioritization.

## Changes

This PR adds a `failureStage` property to `MANAGER_REGISTRATION.FAILED`
telemetry so we can identify the exact stage where the error occurred.

- Added `failureStage` to the telemetry event definition and GDPR
mapping.
- Updated `safeRegister()` to read `failureStage` from caught errors and
fall back to `unknown`.
- Added stage tracking in `getPipenv()`, `hasPipenvEnvironments()`,
`getPyenv()`, and `getPoetry()`.
- Added stage tracking in the pipenv, pyenv, poetry, and conda
registration flows.
- Propagated detailed stage information by attaching `failureStage` to
rethrown errors.

## Why this is needed

Manager registration failures currently lack enough detail to determine
which step is failing. Adding stage-level telemetry makes it much easier
to identify whether failures are happening during discovery, state
lookup, file validation, native finder refresh, sourcing setup, or
registration with the API. This should improve investigation speed and
help target fixes more accurately.

## Example values

- `getPipenv:nativeFinderRefresh`
- `getPoetry:validateCachePath`
- `constructCondaSourcingStatus`
- `registerManager`
- `unknown`

## Verification

- Ran `npx tsc --noEmit`
- No compile errors
- Changes are telemetry-only and do not change feature behavior

Co-authored-by: Eleanor Boyd &lt;26030610+eleanorjboyd@users.noreply.github.com&gt;
diff --git a/src/common/telemetry/constants.ts b/src/common/telemetry/constants.ts
@@ -56,6 +56,7 @@ export enum EventNames {
      * Properties:
      * - managerName: string (e.g. 'system', 'conda', 'pyenv', 'pipenv', 'poetry', 'shellStartupVars')
      * - errorType: string (classified error category from classifyError)
+     * - failureStage: string (hierarchical stage indicator, e.g. 'getPipenv:nativeFinderRefresh')
      */
     MANAGER_REGISTRATION_FAILED = 'MANAGER_REGISTRATION.FAILED',
     /**
@@ -300,12 +301,14 @@ export interface IEventNamePropertyMapping {
     /* __GDPR__
         "manager_registration.failed": {
             "managerName": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
-            "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" }
+            "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" },
+            "failureStage": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "StellaHuang95" }
         }
     */
     [EventNames.MANAGER_REGISTRATION_FAILED]: {
         managerName: string;
         errorType: string;
+        failureStage: string;
     };
 
     /* __GDPR__
diff --git a/src/common/utils/asyncUtils.ts b/src/common/utils/asyncUtils.ts
@@ -16,9 +16,14 @@ export async function safeRegister(name: string, task: Promise<void>): Promise<v
         await task;
     } catch (error) {
         traceError(`Failed to register ${name} features:`, error);
+        const failureStage =
+            error instanceof Error
+                ? ((error as Error & { failureStage?: string }).failureStage ?? 'unknown')
+                : 'unknown';
         sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
             managerName: name,
             errorType: classifyError(error),
+            failureStage,
         });
     }
 }
diff --git a/src/managers/conda/main.ts b/src/managers/conda/main.ts
@@ -18,11 +18,13 @@ export async function registerCondaFeatures(
     log: LogOutputChannel,
     projectManager: PythonProjectManager,
 ): Promise<void> {
+    let stage = 'getPythonApi';
     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
+        stage = 'getConda';
         condaPath = await getConda(nativeFinder);
     } catch (ex) {
         traceInfo('Conda not found, turning off conda features.', ex);
@@ -36,14 +38,18 @@ export async function registerCondaFeatures(
 
     // Conda was found — errors below are real registration failures (let safeRegister handle telemetry)
     try {
+        stage = 'constructCondaSourcingStatus';
         const sourcingStatus: CondaSourcingStatus = await constructCondaSourcingStatus(condaPath);
         traceInfo(sourcingStatus.toString());
 
+        stage = 'createEnvManager';
         const envManager = new CondaEnvManager(nativeFinder, api, log);
+        stage = 'createPkgManager';
         const packageManager = new CondaPackageManager(api, log);
 
         envManager.sourcingInformation = sourcingStatus;
 
+        stage = 'registerManagers';
         disposables.push(
             envManager,
             packageManager,
@@ -52,6 +58,8 @@ export async function registerCondaFeatures(
         );
     } catch (ex) {
         await notifyMissingManagerIfDefault('ms-python.python:conda', projectManager, api);
-        throw ex;
+        const err = ex instanceof Error ? ex : new Error(String(ex));
+        (err as Error & { failureStage?: string }).failureStage = stage;
+        throw err;
     }
 }
diff --git a/src/managers/pipenv/main.ts b/src/managers/pipenv/main.ts
@@ -17,17 +17,22 @@ export async function registerPipenvFeatures(
     disposables: Disposable[],
     projectManager: PythonProjectManager,
 ): Promise<void> {
+    let stage = 'getPythonApi';
     const api: PythonEnvironmentApi = await getPythonApi();
 
     try {
+        stage = 'getPipenv';
         const pipenv = await getPipenv(nativeFinder);
 
         // Register the manager if the CLI is found, or if there are existing pipenv environments.
         // This allows users with existing pipenv environments to still see and use them.
+        stage = 'hasPipenvEnvironments';
         const hasPipenvEnvs = !pipenv && (await hasPipenvEnvironments(nativeFinder));
 
         if (pipenv || hasPipenvEnvs) {
+            stage = 'createManager';
             const mgr = new PipenvManager(nativeFinder, api);
+            stage = 'registerManager';
             disposables.push(mgr, api.registerEnvironmentManager(mgr));
             if (!pipenv) {
                 traceInfo(
@@ -45,13 +50,15 @@ export async function registerPipenvFeatures(
             await notifyMissingManagerIfDefault('ms-python.python:pipenv', projectManager, api);
         }
     } catch (ex) {
+        const failureStage = (ex as Error & { failureStage?: string })?.failureStage ?? stage;
         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),
+            failureStage,
         });
         await notifyMissingManagerIfDefault('ms-python.python:pipenv', projectManager, api);
     }
diff --git a/src/managers/pipenv/pipenvUtils.ts b/src/managers/pipenv/pipenvUtils.ts
@@ -56,10 +56,18 @@ export async function clearPipenvCache(): Promise<void> {
  * This allows the manager to be registered even if the CLI is not found.
  */
 export async function hasPipenvEnvironments(nativeFinder: NativePythonFinder): Promise<boolean> {
-    const data = await nativeFinder.refresh(false);
-    return data
-        .filter((e) => isNativeEnvInfo(e))
-        .some((e) => (e as NativeEnvInfo).kind === NativePythonEnvironmentKind.pipenv);
+    let stage = 'nativeFinderRefresh';
+    try {
+        const data = await nativeFinder.refresh(false);
+        stage = 'filterPipenvEnvs';
+        return data
+            .filter((e) => isNativeEnvInfo(e))
+            .some((e) => (e as NativeEnvInfo).kind === NativePythonEnvironmentKind.pipenv);
+    } catch (ex) {
+        const err = ex instanceof Error ? ex : new Error(String(ex));
+        (err as Error & { failureStage?: string }).failureStage = `hasPipenvEnvironments:${stage}`;
+        throw err;
+    }
 }
 
 function getPipenvPathFromSettings(): string | undefined {
@@ -68,61 +76,78 @@ function getPipenvPathFromSettings(): string | undefined {
 }
 
 export async function getPipenv(native?: NativePythonFinder): Promise<string | undefined> {
-    // Priority 1: Settings (if explicitly set and valid)
-    const settingPath = getPipenvPathFromSettings();
-    if (settingPath) {
-        if (await fs.exists(untildify(settingPath))) {
-            traceInfo(`Using pipenv from settings: ${settingPath}`);
-            return untildify(settingPath);
+    let stage = 'checkSettings';
+    try {
+        // Priority 1: Settings (if explicitly set and valid)
+        const settingPath = getPipenvPathFromSettings();
+        if (settingPath) {
+            stage = 'validateSettingsPath';
+            if (await fs.exists(untildify(settingPath))) {
+                traceInfo(`Using pipenv from settings: ${settingPath}`);
+                return untildify(settingPath);
+            }
+            traceInfo(`Pipenv path from settings does not exist: ${settingPath}`);
         }
-        traceInfo(`Pipenv path from settings does not exist: ${settingPath}`);
-    }
 
-    // Priority 2: In-memory cache
-    if (pipenvPath) {
-        if (await fs.exists(untildify(pipenvPath))) {
-            return untildify(pipenvPath);
+        // Priority 2: In-memory cache
+        stage = 'checkCache';
+        if (pipenvPath) {
+            stage = 'validateCachePath';
+            if (await fs.exists(untildify(pipenvPath))) {
+                return untildify(pipenvPath);
+            }
+            pipenvPath = undefined;
         }
-        pipenvPath = undefined;
-    }
 
-    // Priority 3: Persistent state
-    const state = await getWorkspacePersistentState();
-    const storedPath = await state.get<string>(PIPENV_PATH_KEY);
-    if (storedPath) {
-        if (await fs.exists(untildify(storedPath))) {
-            pipenvPath = storedPath;
-            traceInfo(`Using pipenv from persistent state: ${pipenvPath}`);
-            return untildify(pipenvPath);
+        // Priority 3: Persistent state
+        stage = 'getPersistentState';
+        const state = await getWorkspacePersistentState();
+        stage = 'checkPersistentState';
+        const storedPath = await state.get<string>(PIPENV_PATH_KEY);
+        if (storedPath) {
+            stage = 'validatePersistentStatePath';
+            if (await fs.exists(untildify(storedPath))) {
+                pipenvPath = storedPath;
+                traceInfo(`Using pipenv from persistent state: ${pipenvPath}`);
+                return untildify(pipenvPath);
+            }
+            await state.set(PIPENV_PATH_KEY, undefined);
         }
-        await state.set(PIPENV_PATH_KEY, undefined);
-    }
 
-    // Priority 4: PATH lookup
-    const foundPipenv = await findPipenv();
-    if (foundPipenv) {
-        pipenvPath = foundPipenv;
-        traceInfo(`Found pipenv in PATH: ${foundPipenv}`);
-        return foundPipenv;
-    }
+        // Priority 4: PATH lookup
+        stage = 'pathLookup';
+        const foundPipenv = await findPipenv();
+        if (foundPipenv) {
+            pipenvPath = foundPipenv;
+            traceInfo(`Found pipenv in PATH: ${foundPipenv}`);
+            return foundPipenv;
+        }
 
-    // Priority 5: Native finder as fallback
-    if (native) {
-        const data = await native.refresh(false);
-        const managers = data
-            .filter((e) => !isNativeEnvInfo(e))
-            .map((e) => e as NativeEnvManagerInfo)
-            .filter((e) => e.tool.toLowerCase() === 'pipenv');
-        if (managers.length > 0) {
-            pipenvPath = managers[0].executable;
-            traceInfo(`Using pipenv from native finder: ${pipenvPath}`);
-            await state.set(PIPENV_PATH_KEY, pipenvPath);
-            return pipenvPath;
+        // Priority 5: Native finder as fallback
+        stage = 'nativeFinderRefresh';
+        if (native) {
+            const data = await native.refresh(false);
+            stage = 'filterNativeFinderResults';
+            const managers = data
+                .filter((e) => !isNativeEnvInfo(e))
+                .map((e) => e as NativeEnvManagerInfo)
+                .filter((e) => e.tool.toLowerCase() === 'pipenv');
+            if (managers.length > 0) {
+                pipenvPath = managers[0].executable;
+                traceInfo(`Using pipenv from native finder: ${pipenvPath}`);
+                stage = 'persistNativeFinderResult';
+                await state.set(PIPENV_PATH_KEY, pipenvPath);
+                return pipenvPath;
+            }
         }
-    }
 
-    traceInfo('Pipenv not found');
-    return undefined;
+        traceInfo('Pipenv not found');
+        return undefined;
+    } catch (ex) {
+        const err = ex instanceof Error ? ex : new Error(String(ex));
+        (err as Error & { failureStage?: string }).failureStage = `getPipenv:${stage}`;
+        throw err;
+    }
 }
 
 async function nativeToPythonEnv(
diff --git a/src/managers/poetry/main.ts b/src/managers/poetry/main.ts
@@ -18,19 +18,25 @@ export async function registerPoetryFeatures(
     outputChannel: LogOutputChannel,
     projectManager: PythonProjectManager,
 ): Promise<void> {
+    let stage = 'getPythonApi';
     const api: PythonEnvironmentApi = await getPythonApi();
 
     try {
+        stage = 'getPoetry';
         const poetryPath = await getPoetry(nativeFinder);
         if (poetryPath) {
             traceInfo(
                 'The `shell` command is not available by default in Poetry versions 2.0.0 and above. Therefore all shell activation will be handled by calling `source <path-to-activate>`. If you face any problems with shell activation, please file an issue at https://github.com/microsoft/vscode-python-environments/issues to help us improve this implementation.',
             );
+            stage = 'getPoetryVersion';
             const version = await getPoetryVersion(poetryPath);
             traceInfo(`Poetry found at ${poetryPath}, version: ${version}`);
+            stage = 'createEnvManager';
             const envManager = new PoetryManager(nativeFinder, api);
+            stage = 'createPkgManager';
             const pkgManager = new PoetryPackageManager(api, outputChannel, envManager);
 
+            stage = 'registerManagers';
             disposables.push(
                 envManager,
                 pkgManager,
@@ -46,10 +52,12 @@ export async function registerPoetryFeatures(
             await notifyMissingManagerIfDefault('ms-python.python:poetry', projectManager, api);
         }
     } catch (ex) {
+        const failureStage = (ex as Error & { failureStage?: string })?.failureStage ?? stage;
         traceInfo('Poetry not found, turning off poetry features.', ex);
         sendTelemetryEvent(EventNames.MANAGER_REGISTRATION_FAILED, undefined, {
             managerName: 'poetry',
             errorType: classifyError(ex),
+            failureStage,
         });
         await notifyMissingManagerIfDefault('ms-python.python:poetry', projectManager, api);
     }
diff --git a/src/managers/poetry/poetryUtils.ts b/src/managers/poetry/poetryUtils.ts
diff --git a/src/managers/pyenv/main.ts b/src/managers/pyenv/main.ts
diff --git a/src/managers/pyenv/pyenvUtils.ts b/src/managers/pyenv/pyenvUtils.ts
