feat: enhance telemetry for global scope handling and process restart reasons

Author: eleanorjboyd

src/common/telemetry/constants.ts

@@ -86,6 +86,15 @@ export enum EventNames {
      * - errorType: string (classified error category, on failure only)
      */
     PET_INIT_DURATION = 'PET.INIT_DURATION',
+    /**
+     * Telemetry event fired once per activation reporting the version of the bundled
+     * PET (Python Environment Tools) binary in use. Used to slice other PET telemetry
+     * by binary version when investigating regressions/improvements.
+     * Properties:
+     * - version: string (e.g. '0.1.0' from `pet --version`; 'unknown' if the lookup failed)
+     * - source: 'envs_extension' | 'python_extension' (which extension shipped the binary)
+     */
+    PET_VERSION = 'PET.VERSION',
     /**
      * Telemetry event fired when applyInitialEnvironmentSelection begins.
      * Signals that all managers are registered and env selection is starting.
@@ -398,8 +407,14 @@ export interface IEventNamePropertyMapping {
     */
     [EventNames.SETUP_HANG_DETECTED]: {
         failureStage: string;
-        /** Whether the global Python scope search was deferred to background at time of hang. undefined = hang fired before env-selection stage. */
-        globalScopeDeferred: boolean | undefined;
+        /**
+         * State of the global Python scope search at the time of hang:
+         * - 'deferred': workspace env resolved and global scope was pushed to background.
+         * - 'not_deferred': no workspace env resolved, global scope was awaited as primary fallback.
+         * - 'unknown': hang fired before the env-selection stage reached the global-scope decision
+         *   (i.e. before/during env selection, prior to the workspace-resolution branch).
+         */
+        globalScopeDeferred: 'deferred' | 'not_deferred' | 'unknown';
     };
 
     /* __GDPR__
@@ -425,6 +440,19 @@ export interface IEventNamePropertyMapping {
         errorType?: string;
     };
 
+    /* __GDPR__
+        "pet.version": {
+            "version": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "source": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" }
+        }
+    */
+    [EventNames.PET_VERSION]: {
+        /** Version string reported by `pet --version` (e.g. '0.1.0'), or 'unknown' if the lookup failed. */
+        version: string;
+        /** Which extension shipped the PET binary that's being used. */
+        source: 'envs_extension' | 'python_extension';
+    };
+
     /* __GDPR__
         "env_selection.started": {
             "registeredManagerCount": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" },

src/extension.ts

@@ -96,7 +96,12 @@ import { collectEnvironmentInfo, getEnvManagerAndPackageManagerConfigLevels, run
 import { EnvironmentManagers, ProjectCreators, PythonProjectManager } from './internal.api';
 import { registerSystemPythonFeatures } from './managers/builtin/main';
 import { SysPythonManager } from './managers/builtin/sysPythonManager';
-import { createNativePythonFinder, NativePythonFinder } from './managers/common/nativePythonFinder';
+import {
+    createNativePythonFinder,
+    getNativePythonToolsPathAndSource,
+    getNativePythonToolsVersion,
+    NativePythonFinder,
+} from './managers/common/nativePythonFinder';
 import { IDisposable } from './managers/common/types';
 import { registerCondaFeatures } from './managers/conda/main';
 import { registerPipenvFeatures } from './managers/pipenv/main';
@@ -555,7 +560,7 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
         const stageWatch = new StopWatch();
         // Mutable ref so the hang watchdog can report whether global scope was deferred
         // even if it fires mid-envSelection before applyInitialEnvironmentSelection returns.
-        const globalScopeDeferredRef: { value: boolean | undefined } = { value: undefined };
+        const globalScopeDeferredRef: { value: 'deferred' | 'not_deferred' | 'unknown' } = { value: 'unknown' };
         // Watchdog: fires if setup hasn't completed within 120s, indicating a likely hang
         const SETUP_HANG_TIMEOUT_MS = 120_000;
         let hangWatchdogActive = true;
@@ -586,6 +591,19 @@ export async function activate(context: ExtensionContext): Promise<PythonEnviron
             try {
                 nativeFinder = await createNativePythonFinder(outputChannel, api, context);
                 sendTelemetryEvent(EventNames.PET_INIT_DURATION, petStart.elapsedTime, { result: 'success' });
+                // Fire-and-forget: report the bundled PET binary version so other PET telemetry
+                // can be sliced by version. Don't block activation on this.
+                void getNativePythonToolsPathAndSource()
+                    .then(async ({ toolPath, source }) => {
+                        const version = await getNativePythonToolsVersion(toolPath);
+                        sendTelemetryEvent(EventNames.PET_VERSION, undefined, { version, source });
+                    })
+                    .catch(() => {
+                        sendTelemetryEvent(EventNames.PET_VERSION, undefined, {
+                            version: 'unknown',
+                            source: 'python_extension',
+                        });
+                    });
             } catch (petError) {
                 sendTelemetryEvent(
                     EventNames.PET_INIT_DURATION,

src/features/interpreterSelection.ts

@@ -284,7 +284,7 @@ export async function applyInitialEnvironmentSelection(
     nativeFinder: NativePythonFinder,
     api: PythonEnvironmentApi,
     activationToReadyDurationMs?: number,
-    globalScopeDeferredRef?: { value: boolean | undefined },
+    globalScopeDeferredRef?: { value: 'deferred' | 'not_deferred' | 'unknown' },
 ): Promise<void> {
     const folders = getWorkspaceFolders() ?? [];
     traceInfo(
@@ -379,7 +379,7 @@ export async function applyInitialEnvironmentSelection(
         // Defer global scope so it doesn't block post-selection startup.
         traceInfo('[interpreterSelection] Workspace env resolved, deferring global scope to background');
         if (globalScopeDeferredRef) {
-            globalScopeDeferredRef.value = true;
+            globalScopeDeferredRef.value = 'deferred';
         }
         resolveGlobalScope()
             .then(async (globalErrors) => {
@@ -391,7 +391,7 @@ export async function applyInitialEnvironmentSelection(
     } else {
         // No workspace folder resolved — global scope is the primary fallback, must await.
         if (globalScopeDeferredRef) {
-            globalScopeDeferredRef.value = false;
+            globalScopeDeferredRef.value = 'not_deferred';
         }
         const globalErrors = await resolveGlobalScope();
         allErrors.push(...globalErrors);

src/managers/common/nativePythonFinder.ts

@@ -85,12 +85,21 @@ export class ConfigureRetryState {
     }
 }
 
+export type NativePythonToolsSource = 'envs_extension' | 'python_extension';
+
 export async function getNativePythonToolsPath(): Promise<string> {
+    return (await getNativePythonToolsPathAndSource()).toolPath;
+}
+
+export async function getNativePythonToolsPathAndSource(): Promise<{
+    toolPath: string;
+    source: NativePythonToolsSource;
+}> {
     const envsExt = getExtension(ENVS_EXTENSION_ID);
     if (envsExt) {
         const petPath = path.join(envsExt.extensionPath, 'python-env-tools', 'bin', isWindows() ? 'pet.exe' : 'pet');
         if (await fs.pathExists(petPath)) {
-            return petPath;
+            return { toolPath: petPath, source: 'envs_extension' };
         }
     }
 
@@ -99,7 +108,54 @@ export async function getNativePythonToolsPath(): Promise<string> {
         throw new Error('Python extension not found');
     }
 
-    return path.join(python.extensionPath, 'python-env-tools', 'bin', isWindows() ? 'pet.exe' : 'pet');
+    return {
+        toolPath: path.join(python.extensionPath, 'python-env-tools', 'bin', isWindows() ? 'pet.exe' : 'pet'),
+        source: 'python_extension',
+    };
+}
+
+/**
+ * Runs `pet --version` and returns the parsed version string (e.g. '0.1.0').
+ * Returns 'unknown' if the command fails, times out, or the output can't be parsed.
+ */
+export async function getNativePythonToolsVersion(toolPath: string, timeoutMs: number = 5_000): Promise<string> {
+    return new Promise<string>((resolve) => {
+        let settled = false;
+        const settle = (value: string) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(value);
+        };
+        try {
+            const proc = spawnProcess(toolPath, ['--version'], { stdio: 'pipe' });
+            let stdout = '';
+            const timer = setTimeout(() => {
+                try {
+                    proc.kill('SIGTERM');
+                } catch {
+                    // ignore
+                }
+                settle('unknown');
+            }, timeoutMs);
+            proc.stdout?.on('data', (data: Buffer) => {
+                stdout += data.toString();
+            });
+            proc.on('error', () => {
+                clearTimeout(timer);
+                settle('unknown');
+            });
+            proc.on('close', () => {
+                clearTimeout(timer);
+                // Output looks like "pet 0.1.0\n" — extract the version token.
+                const match = stdout.match(/\b\d+\.\d+\.\d+\S*/);
+                settle(match ? match[0] : 'unknown');
+            });
+        } catch {
+            settle('unknown');
+        }
+    });
 }
 
 export interface NativeEnvInfo {
@@ -545,20 +601,23 @@ class NativePythonFinderImpl implements NativePythonFinder {
             // Handle process exit - mark as exited so pending requests fail fast
             this.proc.on('exit', (code, signal) => {
                 this.processExited = true;
-                if (code !== 0) {
+                // Preserve a more-specific reason (e.g. rpc_*) if one was already recorded before the kill.
+                if (this.processExitReason === undefined) {
                     this.processExitReason = `process_exit:${code ?? 'null'}:${signal ?? 'none'}`;
+                }
+                if (code !== 0) {
                     this.outputChannel.error(
                         `[pet] Python Environment Tools exited unexpectedly with code ${code}, signal ${signal}`,
                     );
-                } else {
-                    this.processExitReason = 'process_exit:0';
                 }
             });
 
             // Handle process errors (e.g., ENOENT if executable not found)
             this.proc.on('error', (err) => {
                 this.processExited = true;
-                this.processExitReason = 'process_error';
+                if (this.processExitReason === undefined) {
+                    this.processExitReason = 'process_error';
+                }
                 this.outputChannel.error('[pet] Process error:', err);
             });