feat: enrich telemetry with pythonVersion and dbtCoreVersion customAttributes

Production telemetry currently carries `common.os` / `common.nodeArch` /
`common.extversion` etc. on every event but **not** the user's Python
interpreter version or installed dbt-core distribution version. That's a
real blindspot — App Insights can't split error clusters by Python
version (e.g. is `pythonBridgeInitPythonError "mashumaro
UnserializableField"` a Python 3.13 + mashumaro 3.14 incompat or
something else?) and we can't tell whether `catalogPythonError "missing
used_schemas"` correlates with a specific dbt-core minor.

Adds two customAttributes that get merged into every event going
forward via `TelemetryService.setTelemetryCustomAttribute`:

- `pythonVersion` — sourced from `PythonEnvironment.pythonVersion`
  (already populated via the VS Code Python extension's API on
  interpreter activation, no additional probe needed).
- `dbtCoreVersion` — sourced from a small `child_process.spawn` probe
  in `src/telemetry/versionProbes.ts` that runs
  `python -c "from importlib.metadata import version; print(version('dbt-core'))"`.
  Reads dist-info directly so it survives even when dbt's own import
  chain is broken (the failure mode PR #96 targeted) — the bridge can
  be dead and we still get the version.

Both are best-effort: probe failure → no customAttribute set rather
than blocking activation. Wired into `DBTPowerUserExtension.activate`
after `initializeDBTProjects` (when the Python interpreter is known)
plus a refresh on `pythonEnvironment.onPythonEnvironmentChanged` so the
dimensions track interpreter changes.

`probeDbtCoreVersion` accepts an injectable `SpawnFn` parameter
defaulted to `child_process.spawn`. `import * as childProcess` produces
ESM-style bindings that resist `jest.spyOn` / `jest.mock` redefinition
under ts-jest, so the tests pass their own spawner directly. Adds 6
unit tests covering: success, empty stdout (PackageNotFoundError),
non-zero exit, error event, sync throw, and timeout.

After this ships and rolls out, App Insights queries can split by
`customDimensions.pythonVersion == "3.13.0"` or
`customDimensions.dbtCoreVersion startswith "1.10"` on every event,
not just the wrapper-failure events. Dashboards become diagnostic by
construction without per-event injection.

Tests: 33 suites / 486 passed (32 prior + 1 new).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ralphstodomingo

src/dbtPowerUserExtension.ts

@@ -13,6 +13,7 @@ import { DbtPowerUserMcpServer } from "./mcp";
 import { DbtPowerUserActionsCenter } from "./quickpick";
 import { StatusBars } from "./statusbar";
 import { TelemetryService } from "./telemetry";
+import { probeDbtCoreVersion } from "./telemetry/versionProbes";
 import { TreeviewProviders } from "./treeview_provider";
 import { ValidationProvider } from "./validation_provider";
 import { WebviewViewProviders } from "./webview_provider";
@@ -99,6 +100,22 @@ export class DBTPowerUserExtension implements Disposable {
       await this.dbtProjectContainer.detectDBT();
       await this.dbtProjectContainer.initializeDBTProjects();
       await this.statusBars.initialize();
+
+      // Enrich every telemetry event with the active Python interpreter version
+      // and dbt-core dist version. Without these dimensions, App Insights can't
+      // split error clusters by Python or dbt-core version — e.g. we can't
+      // tell whether a `pythonBridgeInitPythonError "mashumaro
+      // UnserializableField"` is a Python 3.13 + mashumaro 3.14 incompat or
+      // something else. Both probes are best-effort: failure → no
+      // customAttribute set rather than blocking activation. Re-runs on
+      // interpreter change so the dimensions track the user's selection.
+      void this.refreshVersionTelemetryAttributes();
+      const pythonEnv = this.dbtProjectContainer.getPythonEnvironment();
+      this.disposables.push(
+        pythonEnv.onPythonEnvironmentChanged(() => {
+          void this.refreshVersionTelemetryAttributes();
+        }),
+      );
       // Ask to reload the window if the dbt integration changes
       const dbtIntegration = workspace
         .getConfiguration("dbt")
@@ -121,4 +138,38 @@ export class DBTPowerUserExtension implements Disposable {
       this.telemetry.sendTelemetryError("extensionActivationError", error);
     }
   }
+
+  /**
+   * Populate `pythonVersion` and `dbtCoreVersion` customAttributes on the
+   * telemetry service so every event from this point forward carries them.
+   * Best-effort: if either probe fails (interpreter missing, dbt-core not
+   * installed in this venv, probe timeout), the attribute simply isn't set.
+   * Idempotent — wired both at activation and from the
+   * `onPythonEnvironmentChanged` listener.
+   */
+  private async refreshVersionTelemetryAttributes(): Promise<void> {
+    try {
+      const pythonEnv = this.dbtProjectContainer.getPythonEnvironment();
+      const pythonVersion = pythonEnv.pythonVersion;
+      if (pythonVersion) {
+        this.telemetry.setTelemetryCustomAttribute(
+          "pythonVersion",
+          pythonVersion,
+        );
+      }
+      const pythonPath = pythonEnv.pythonPath;
+      if (pythonPath) {
+        const dbtCoreVersion = await probeDbtCoreVersion(pythonPath);
+        if (dbtCoreVersion) {
+          this.telemetry.setTelemetryCustomAttribute(
+            "dbtCoreVersion",
+            dbtCoreVersion,
+          );
+        }
+      }
+    } catch {
+      // Telemetry-enrichment failures must never block activation or
+      // surface as an error — by design these dimensions are best-effort.
+    }
+  }
 }

src/telemetry/versionProbes.ts

@@ -0,0 +1,94 @@
+/**
+ * Best-effort probes for the user's Python interpreter version and dbt-core
+ * distribution version. Both feed `TelemetryService.setTelemetryCustomAttribute`
+ * so every telemetry event from the session carries them as `pythonVersion`
+ * and `dbtCoreVersion` customDimensions.
+ *
+ * Production telemetry today carries `common.os` / `common.nodeArch` /
+ * `common.extversion` etc. but **not** the Python interpreter version or the
+ * installed dbt-core version. That blindspot is what motivated the version
+ * suffix discussion on PR #96 — without these dimensions, App Insights can't
+ * split error clusters by Python or dbt-core version, and we can't tell
+ * whether `pythonBridgeInitPythonError "mashumaro UnserializableField"` is
+ * a Python 3.13 + mashumaro 3.14 incompatibility or something else.
+ */
+import * as childProcess from "child_process";
+
+const PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * Injectable spawn for tests — defaulted to the real `child_process.spawn`.
+ * `import * as childProcess` produces ESM-style bindings that resist
+ * `jest.spyOn` / `jest.mock` redefinition under ts-jest, so we accept the
+ * spawner as a parameter and let tests pass a stub directly.
+ */
+export type SpawnFn = (
+  command: string,
+  args: string[],
+  options: childProcess.SpawnOptions,
+) => childProcess.ChildProcess;
+
+/**
+ * Spawn the user's Python interpreter to read dbt-core's distribution version
+ * via `importlib.metadata`. Reads dist-info directly so it survives even when
+ * dbt's own import chain is broken — exactly the failure mode our wrapper at
+ * the top of `dbt_core_integration.py` is built around. Returns `undefined`
+ * when:
+ *   - the spawn fails (interpreter missing / permission error)
+ *   - dbt-core isn't installed in this Python env
+ *   - the probe doesn't finish within {@link PROBE_TIMEOUT_MS}
+ *
+ * Best-effort by design — the caller treats `undefined` as "skip the
+ * customAttribute" rather than logging an error.
+ */
+export function probeDbtCoreVersion(
+  pythonPath: string,
+  spawn: SpawnFn = childProcess.spawn,
+): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    const probeScript =
+      "from importlib.metadata import version, PackageNotFoundError\n" +
+      "try:\n" +
+      "    print(version('dbt-core'))\n" +
+      "except PackageNotFoundError:\n" +
+      "    pass\n";
+
+    let proc: childProcess.ChildProcess;
+    try {
+      proc = spawn(pythonPath, ["-c", probeScript], {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch {
+      // spawn synchronously throws on a missing executable on some platforms
+      resolve(undefined);
+      return;
+    }
+
+    let stdout = "";
+    proc.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+
+    let settled = false;
+    const settle = (value: string | undefined) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      try {
+        proc.kill();
+      } catch {
+        // already exited
+      }
+      resolve(value);
+    };
+
+    proc.on("close", (code) => {
+      const trimmed = stdout.trim();
+      settle(code === 0 && trimmed.length > 0 ? trimmed : undefined);
+    });
+    proc.on("error", () => settle(undefined));
+
+    setTimeout(() => settle(undefined), PROBE_TIMEOUT_MS);
+  });
+}

src/test/suite/versionProbes.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Unit tests for the dbt-core version probe used by
+ * `DBTPowerUserExtension.refreshVersionTelemetryAttributes` to populate the
+ * `dbtCoreVersion` customAttribute on every telemetry event.
+ *
+ * Covers the four outcomes the probe needs to distinguish: success (exit 0
+ * with a non-empty version line on stdout), unrecognised dist (exit 0 with
+ * empty stdout), spawn failure / non-zero exit, and timeout. Each maps to
+ * either a returned version string or `undefined` (best-effort skip).
+ *
+ * Uses dependency injection on the spawn function (`SpawnFn` parameter)
+ * rather than mocking `child_process` — `import * as childProcess` produces
+ * ESM-style bindings that resist redefinition under ts-jest, so the test
+ * passes its own spawner directly.
+ */
+import { describe, expect, it, jest } from "@jest/globals";
+import { ChildProcess } from "child_process";
+import { EventEmitter } from "events";
+
+import { probeDbtCoreVersion, SpawnFn } from "../../telemetry/versionProbes";
+
+interface FakeProcOptions {
+  exitCode?: number | null;
+  stdoutChunks?: string[];
+  emitError?: Error;
+  closeDelayMs?: number;
+}
+
+function makeFakeProc(opts: FakeProcOptions = {}): ChildProcess {
+  const proc = new EventEmitter() as unknown as ChildProcess;
+  // Install null-stream stdout/stderr that the probe's optional-chained
+  // listeners can attach to.
+  (proc as any).stdout = new EventEmitter();
+  (proc as any).stderr = new EventEmitter();
+
+  const eventTimer = setTimeout(() => {
+    if (opts.emitError) {
+      proc.emit("error", opts.emitError);
+      return;
+    }
+    for (const chunk of opts.stdoutChunks ?? []) {
+      (proc as any).stdout.emit("data", Buffer.from(chunk, "utf8"));
+    }
+    proc.emit("close", opts.exitCode ?? 0);
+  }, opts.closeDelayMs ?? 0);
+
+  // The probe under test calls `proc.kill()` when it times out — make sure
+  // the fake's inner timer is cleared too so jest doesn't hang waiting on
+  // the still-scheduled `setTimeout(...60_000)` in the timeout-path test.
+  (proc as any).kill = jest.fn(() => {
+    clearTimeout(eventTimer);
+  });
+
+  return proc;
+}
+
+describe("probeDbtCoreVersion", () => {
+  it("returns the trimmed version string when Python prints it on exit 0", async () => {
+    const spawnSpy = jest.fn(() =>
+      makeFakeProc({ exitCode: 0, stdoutChunks: ["1.10.20\n"] }),
+    ) as unknown as SpawnFn;
+    const result = await probeDbtCoreVersion("/usr/bin/python3", spawnSpy);
+    expect(result).toBe("1.10.20");
+    // Argv check: probe script must use importlib.metadata so it works even
+    // when dbt-core's import chain is broken (the bug we're targeting).
+    expect(spawnSpy as unknown as jest.Mock).toHaveBeenCalledWith(
+      "/usr/bin/python3",
+      ["-c", expect.stringContaining("from importlib.metadata import version")],
+      expect.any(Object),
+    );
+  });
+
+  it("returns undefined when stdout is empty (PackageNotFoundError swallowed by the probe script)", async () => {
+    const spawnSpy = jest.fn(() =>
+      makeFakeProc({ exitCode: 0, stdoutChunks: [] }),
+    ) as unknown as SpawnFn;
+    const result = await probeDbtCoreVersion("/usr/bin/python3", spawnSpy);
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined on non-zero exit (probe script crashed)", async () => {
+    const spawnSpy = jest.fn(() =>
+      makeFakeProc({ exitCode: 2, stdoutChunks: ["something\n"] }),
+    ) as unknown as SpawnFn;
+    const result = await probeDbtCoreVersion("/usr/bin/python3", spawnSpy);
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined when spawn emits an error event (interpreter missing)", async () => {
+    const spawnSpy = jest.fn(() =>
+      makeFakeProc({ emitError: new Error("ENOENT: no such file") }),
+    ) as unknown as SpawnFn;
+    const result = await probeDbtCoreVersion("/nonexistent/python", spawnSpy);
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined when spawn synchronously throws", async () => {
+    const spawnSpy = jest.fn(() => {
+      throw new Error("EACCES");
+    }) as unknown as SpawnFn;
+    const result = await probeDbtCoreVersion("/etc/passwd", spawnSpy);
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined and kills the process if the probe runs longer than the timeout", async () => {
+    // closeDelayMs is far past the 5s timeout; the timeout fires first.
+    const proc = makeFakeProc({
+      exitCode: 0,
+      stdoutChunks: ["never delivered\n"],
+      closeDelayMs: 60_000,
+    });
+    const spawnSpy = jest.fn(() => proc) as unknown as SpawnFn;
+    const result = await probeDbtCoreVersion("/usr/bin/python3", spawnSpy);
+    expect(result).toBeUndefined();
+    expect((proc as any).kill).toHaveBeenCalled();
+  }, 10_000);
+});