Add PET version, build ID, and commit SHA to telemetry (microsoft#1574)

StellaHuang95 · Copilot · eleanorjboyd · web-flow · commit 7fb4c0651d29 · 2026-06-10T14:50:56.000-07:00
## Context PET (Python Environment Tools) is the Rust JSON-RPC service this extension uses to discover Python environments. PET ships independently of the extension and is bundled as a binary inside the VSIX, so the PET version a user is running can drift from the extension version. When we see a performance regression or a failure in PET telemetry today, we have no way to map it back to the **exact PET source code** the user is running — we know `pet --version` (already telemetered via `PET.VERSION`) but a single PET version line can correspond to many commits across multiple builds. This PR closes that gap by stamping every PET telemetry event with the binary's `petVersion`, `petBuildId`, and `petCommitSha`, sourced directly from the running PET process via a new `info` JSON-RPC request. We can then `summarize by petCommitSha` in Kusto and join straight to git log to find the offending change. ## Related PRs PET side (both merged): - microsoft/python-environment-tools#470 — adds the `info` JSON-RPC request returning `petVersion` and optional `buildId` - microsoft/python-environment-tools#473 — extends the `info` response with optional `commitSha` baked in from CI env vars (`PET_COMMIT_SHA` / `BUILD_SOURCEVERSION` / `GITHUB_SHA`) Supersedes / replaces: - microsoft#1548 — earlier draft that only added `petVersion` + `petBuildId` and accidentally corrupted the enum docstring for `PET_RESOLVE` / `MIGRATION_SYSTEM_ENV_MANAGER`. Please close. ## What this PR does 1. **Defines a typed `NativePetInfo` interface** matching PET's `info` response shape (`petVersion: string`, `buildId?: string`, `commitSha?: string`). 2. **Sends one `info` RPC per PET process start** in `kickoffInfoFetch(connection)`, called immediately after `connection.listen()` inside `start()`. The call is **fire-and-forget** with a 2 s timeout — `start()` does not await it, so discovery is never blocked. The response is cached in `this.petInfo` for the lifetime of that PET process. `this.petInfo` is reset to `undefined` on every `start()` (initial spawn + every crash-recovery restart). 3. **Guards against stale responses** via `connection !== this.connection` checks in both `.then` and `.catch`, so a late reply from a previous PET process can't clobber the cache of a newer one after a restart. 4. **Spreads `getPetInfoProperties()` into the six existing PET telemetry call sites** (success + error paths of `PET_RESOLVE`, `PET_REFRESH`, `PET_PROCESS_RESTART`). The helper always returns concrete strings, defaulting each field to `'unknown'`, so Kusto group-bys work without null handling. 5. **Adds GDPR comments + TypeScript types** for the three new fields on `PET_RESOLVE`, `PET_REFRESH`, `PET_PROCESS_RESTART`. All classified as `SystemMetaData` / `PerformanceAndHealth`. ## Files changed | File | Why | |---|---| | `src/managers/common/nativePythonFinder.ts` | `INFO_TIMEOUT_MS` constant, `NativePetInfo` interface, `petInfo` field, `kickoffInfoFetch` + `getPetInfoProperties` helpers, kickoff wiring in `start()`, payload spread at six telemetry sites | | `src/common/telemetry/constants.ts` | New `petVersion` / `petBuildId` / `petCommitSha` properties on `PET_RESOLVE`, `PET_REFRESH`, `PET_PROCESS_RESTART` (GDPR blocks + TS types) | ## Compatibility with older PET binaries The extension currently ships PET as a bundled binary (downloaded by the Azure pipelines from PET CI artifacts). Until the PET release branch picks up microsoft#470 / microsoft#473, the bundled binary won't have the `info` handler. In that case: - PET responds with JSON-RPC error code `-1` (`Failed to find handler for request info`) - `sendRequestWithTimeout` rejects → `.catch` swallows → `petInfo` stays `undefined` - All three telemetry properties report `'unknown'` - One harmless `[pet] Failed to find handler for method: info` line surfaces from PET's stderr into the Python Environments output channel Discovery, refresh, resolve, and restart all continue to work normally. No crash, no functional regression — just `'unknown'` values in telemetry until PET catches up. ## Crash attribution semantics A subtle but important detail of where the spread is placed: the crashing PET's commit hash **is** captured in `PET_REFRESH` / `PET_RESOLVE` error events because we call `sendTelemetryEvent(..., ...this.getPetInfoProperties())` **before** killing the process and resetting the cache. So when a user reports "PET crashed during refresh", we can identify which exact commit was running. The `PET_PROCESS_RESTART` success event itself reports `'unknown'` for the **new** PET (its `info` reply usually hasn't landed in the few ms between `start()` and the telemetry call), but the new binary's identity surfaces on the very next refresh/resolve. ## Performance impact - One extra JSON-RPC roundtrip **per PET process lifetime** (typically once per VS Code session), not per telemetry event - ~3 string allocations per telemetry event from the spread — invisible against existing payload assembly - `kickoffInfoFetch` returns `void` synchronously; the response runs on the microtask queue and never blocks refresh/resolve - 2 s timeout caps the worst case if PET hangs entirely ## Validation - `npm run lint` ✅ - `npx tsc -p . --noEmit` ✅ - `npm run compile-tests` ✅ - `npm run unittest` — 1141 passing, 2 pending (unchanged from baseline) ✅ - `npm run compile` (webpack production bundle) ✅ ## Manual testing To get non-`'unknown'` values locally, build PET from main and drop the binary into `python-env-tools/bin/`: ```powershell # In the PET repo: $env:PET_COMMIT_SHA = (git rev-parse HEAD) $env:PET_BUILD_ID = "local-dev" cargo build --release --package pet # In this repo: Copy-Item <pet-repo>\target\release\pet.exe .\python-env-tools\bin\pet.exe -Force ``` Then F5 → open the Python Environments view → run `Python Environments: Refresh Environments`. Set the Python Environments output channel to Debug level to see the `[pet] info: { petVersion, buildId, commitSha }` line confirming the cache was populated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Eleanor Boyd <26030610+eleanorjboyd@users.noreply.github.com>
diff --git a/src/common/telemetry/constants.ts b/src/common/telemetry/constants.ts
@@ -593,6 +593,9 @@ export interface IEventNamePropertyMapping {
             "breakdownGlobalVirtualEnvs": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "isMeasurement": true, "owner": "eleanorjboyd" },
             "breakdownWorkspaces": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "isMeasurement": true, "owner": "eleanorjboyd" },
             "locatorsJson": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
+            "petVersion": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
+            "petBuildId": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
+            "petCommitSha": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
             "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
         }
     */
@@ -615,6 +618,12 @@ export interface IEventNamePropertyMapping {
         breakdownWorkspaces?: number;
         /** JSON-serialized Record<locatorName, ms>. Parse with parse_json() in Kusto. */
         locatorsJson?: string;
+        /** PET crate version reported by the `info` RPC. 'unknown' if the call failed or the PET binary doesn't implement it. */
+        petVersion?: string;
+        /** PET build identifier (CI build run ID) reported by the `info` RPC. 'unknown' if unavailable. */
+        petBuildId?: string;
+        /** PET source git commit SHA reported by the `info` RPC. 'unknown' if unavailable. */
+        petCommitSha?: string;
     };
 
     /* __GDPR__
@@ -639,6 +648,9 @@ export interface IEventNamePropertyMapping {
             "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
             "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
             "triggerReason": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "petVersion": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
+            "petBuildId": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
+            "petCommitSha": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
             "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
         }
     */
@@ -654,18 +666,33 @@ export interface IEventNamePropertyMapping {
          * start_failed | unknown.
          */
         triggerReason: string;
+        /** PET crate version reported by the `info` RPC. 'unknown' if the call failed or the PET binary doesn't implement it. */
+        petVersion?: string;
+        /** PET build identifier (CI build run ID) reported by the `info` RPC. 'unknown' if unavailable. */
+        petBuildId?: string;
+        /** PET source git commit SHA reported by the `info` RPC. 'unknown' if unavailable. */
+        petCommitSha?: string;
     };
 
     /* __GDPR__
         "pet.resolve": {
             "result": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
             "errorType": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "owner": "eleanorjboyd" },
+            "petVersion": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
+            "petBuildId": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
+            "petCommitSha": { "classification": "SystemMetaData", "purpose": "PerformanceAndHealth", "owner": "eleanorjboyd" },
             "<duration>": { "classification": "SystemMetaData", "purpose": "FeatureInsight", "isMeasurement": true, "owner": "eleanorjboyd" }
         }
     */
     [EventNames.PET_RESOLVE]: {
         result: 'success' | 'timeout' | 'error';
         errorType?: string;
+        /** PET crate version reported by the `info` RPC. 'unknown' if the call failed or the PET binary doesn't implement it. */
+        petVersion?: string;
+        /** PET build identifier (CI build run ID) reported by the `info` RPC. 'unknown' if unavailable. */
+        petBuildId?: string;
+        /** PET source git commit SHA reported by the `info` RPC. 'unknown' if unavailable. */
+        petCommitSha?: string;
     };
 
     /* __GDPR__
diff --git a/src/managers/common/nativePythonFinder.ts b/src/managers/common/nativePythonFinder.ts
@@ -24,6 +24,7 @@ const CONFIGURE_TIMEOUT_MS = 30_000; // 30 seconds for configuration
 const MAX_CONFIGURE_TIMEOUT_MS = 60_000; // Max configure timeout after retries (60s)
 const REFRESH_TIMEOUT_MS = 30_000; // 30 seconds for full refresh (with 1 retry = 60s max)
 const RESOLVE_TIMEOUT_MS = 30_000; // 30 seconds for single resolve
+const INFO_TIMEOUT_MS = 2_000; // `info` is a const lookup on PET; 2s is generous
 
 // CLI fallback timeout: generous budget since it's a full process spawn doing a full scan
 const CLI_FALLBACK_TIMEOUT_MS = 120_000; // 2 minutes
@@ -265,6 +266,17 @@ interface PetTelemetryNotification {
     };
 }
 
+/**
+ * Response shape of the PET `info` JSON-RPC request.
+ * `buildId` / `commitSha` are populated only when the PET binary was built by CI
+ * with the appropriate env vars set; local dev builds omit them.
+ */
+interface NativePetInfo {
+    petVersion: string;
+    buildId?: string;
+    commitSha?: string;
+}
+
 /**
  * Error thrown when a JSON-RPC request times out.
  */
@@ -322,6 +334,13 @@ class NativePythonFinderImpl implements NativePythonFinder {
     private isRestarting: boolean = false;
     private processExitReason: string | undefined = undefined;
     private readonly configureRetry = new ConfigureRetryState();
+    /**
+     * Cached PET `info` response for the current connection. Reset to undefined on every
+     * `start()` and re-populated asynchronously by `kickoffInfoFetch()`. Telemetry callers
+     * read this via `getPetInfoProperties()`; if the fetch hasn't finished yet (or the PET
+     * binary is too old to implement `info`), telemetry reports 'unknown'.
+     */
+    private petInfo: NativePetInfo | undefined;
 
     constructor(
         private readonly outputChannel: LogOutputChannel,
@@ -353,7 +372,10 @@ class NativePythonFinderImpl implements NativePythonFinder {
                 this.outputChannel.info(`Resolved Python Environment ${environment.executable}`);
                 // Reset restart attempts on successful request
                 this.restartAttempts = 0;
-                sendTelemetryEvent(EventNames.PET_RESOLVE, sw.elapsedTime, { result: 'success' });
+                sendTelemetryEvent(EventNames.PET_RESOLVE, sw.elapsedTime, {
+                    result: 'success',
+                    ...this.getPetInfoProperties(),
+                });
                 return environment;
             } catch (ex) {
                 // On resolve timeout or connection error (not configure — configure handles its own timeout),
@@ -376,6 +398,7 @@ class NativePythonFinderImpl implements NativePythonFinder {
                 {
                     result: errorType === 'spawn_timeout' ? 'timeout' : 'error',
                     errorType,
+                    ...this.getPetInfoProperties(),
                 },
                 ex instanceof Error ? ex : undefined,
             );
@@ -460,6 +483,7 @@ class NativePythonFinderImpl implements NativePythonFinder {
                 attempt,
                 result: 'success',
                 triggerReason,
+                ...this.getPetInfoProperties(),
             });
 
             // Reset restart attempts on successful start (process didn't immediately fail)
@@ -468,7 +492,13 @@ class NativePythonFinderImpl implements NativePythonFinder {
             sendTelemetryEvent(
                 EventNames.PET_PROCESS_RESTART,
                 sw.elapsedTime,
-                { attempt, result: 'error', errorType: classifyError(ex), triggerReason },
+                {
+                    attempt,
+                    result: 'error',
+                    errorType: classifyError(ex),
+                    triggerReason,
+                    ...this.getPetInfoProperties(),
+                },
                 ex instanceof Error ? ex : undefined,
             );
             this.outputChannel.error('[pet] Failed to restart Python Environment Tools:', ex);
@@ -701,9 +731,54 @@ class NativePythonFinderImpl implements NativePythonFinder {
         );
 
         connection.listen();
+
+        // Stamp PET telemetry with version/buildId/commitSha. Fire-and-forget — must not block refresh.
+        this.petInfo = undefined;
+        this.kickoffInfoFetch(connection);
+
         return connection;
     }
 
+    /**
+     * Asks the PET server for its build metadata (version + optional buildId + optional commitSha)
+     * and caches it in `this.petInfo` for downstream telemetry. Runs once per `start()` call.
+     *
+     * Fire-and-forget by design — the response is not awaited so refresh/resolve callers are
+     * never blocked. The 2 s timeout caps the worst case if PET is misbehaving. If a newer
+     * connection has replaced `this.connection` by the time the response arrives, the response
+     * is dropped to avoid clobbering the cache for the newer process.
+     */
+    private kickoffInfoFetch(connection: rpc.MessageConnection): void {
+        sendRequestWithTimeout<NativePetInfo>(connection, 'info', {}, INFO_TIMEOUT_MS)
+            .then((result) => {
+                if (connection !== this.connection) {
+                    return;
+                }
+                this.petInfo = result;
+                this.outputChannel.debug('[pet] info:', result);
+            })
+            .catch((ex) => {
+                if (connection !== this.connection) {
+                    return;
+                }
+                // Older PET binaries don't implement `info`; leave petInfo undefined so telemetry reports 'unknown'.
+                this.outputChannel.debug('[pet] info request failed:', ex);
+            });
+    }
+
+    /**
+     * Builds the petVersion/petBuildId/petCommitSha properties for PET telemetry events.
+     * Always returns concrete strings (defaulting to 'unknown') so Kusto can group by them
+     * without dealing with nulls.
+     */
+    private getPetInfoProperties(): { petVersion: string; petBuildId: string; petCommitSha: string } {
+        return {
+            petVersion: this.petInfo?.petVersion ?? 'unknown',
+            petBuildId: this.petInfo?.buildId ?? 'unknown',
+            petCommitSha: this.petInfo?.commitSha ?? 'unknown',
+        };
+    }
+
     private async doRefresh(options?: NativePythonEnvironmentKind | Uri[]): Promise<NativeInfo[]> {
         let lastError: unknown;
 
@@ -840,6 +915,7 @@ class NativePythonFinderImpl implements NativePythonFinder {
                     searchPathCount,
                     attempt,
                     locatorsJson: refreshPerf ? JSON.stringify(refreshPerf.locators) : undefined,
+                    ...this.getPetInfoProperties(),
                 },
             );
         } catch (ex) {
@@ -853,6 +929,7 @@ class NativePythonFinderImpl implements NativePythonFinder {
                     unresolvedCount,
                     attempt,
                     errorType,
+                    ...this.getPetInfoProperties(),
                 },
                 ex instanceof Error ? ex : undefined,
             );
