feat: add distributed tracing to connect CLI invocations to Sentry backend

Inject sentry-trace and baggage headers into all outgoing Sentry API
requests so CLI traces are connected to backend traces.

Manual injection in prepareHeaders() is required because Bun's fetch
does not fire undici diagnostics channels, so the SDK's
nativeNodeFetchIntegration auto-injection cannot work.

Changes:
- telemetry.ts: Add getSentryTracePropagationTargets() matching
  *.sentry.io, sentry.io, and self-hosted URLs. Update
  tracePropagationTargets from [] to use the new function.
- sentry-client.ts: Import getTraceData from @sentry/bun and inject
  sentry-trace/baggage headers in prepareHeaders(). When telemetry is
  disabled, getTraceData() returns {} so no headers are injected.
- telemetry.test.ts: Add tests for URL pattern matching (SaaS regional,
  bare sentry.io, non-sentry URLs, self-hosted, no SaaS duplication).

Closes #389

Author: BYK

src/lib/sentry-client.ts

@@ -8,6 +8,7 @@
  * through the SDK function options (baseUrl, fetch, headers).
  */
 
+import { getTraceData } from "@sentry/bun";
 import {
   DEFAULT_SENTRY_URL,
   getConfiguredSentryUrl,
@@ -80,6 +81,19 @@ function prepareHeaders(
   if (!headers.has("User-Agent")) {
     headers.set("User-Agent", getUserAgent());
   }
+
+  // Inject distributed tracing headers to connect CLI spans to backend traces.
+  // Manual injection is required because Bun's fetch doesn't fire undici
+  // diagnostics channels, so the SDK's nativeNodeFetchIntegration cannot work.
+  // When telemetry is disabled, getTraceData() returns {} — no headers injected.
+  const traceData = getTraceData();
+  if (traceData["sentry-trace"]) {
+    headers.set("sentry-trace", traceData["sentry-trace"]);
+  }
+  if (traceData.baggage) {
+    headers.set("baggage", traceData.baggage);
+  }
+
   return headers;
 }
 

src/lib/telemetry.ts

@@ -12,7 +12,11 @@
 import { chmodSync, statSync } from "node:fs";
 // biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
 import * as Sentry from "@sentry/bun";
-import { CLI_VERSION, SENTRY_CLI_DSN } from "./constants.js";
+import {
+  CLI_VERSION,
+  getConfiguredSentryUrl,
+  SENTRY_CLI_DSN,
+} from "./constants.js";
 import { isReadonlyError, tryRepairAndRetry } from "./db/schema.js";
 import { ApiError, AuthError } from "./errors.js";
 import { attachSentryReporter } from "./logger.js";
@@ -245,6 +249,37 @@ const EXCLUDED_INTEGRATIONS = new Set([
 /** Current beforeExit handler, tracked so it can be replaced on re-init */
 let currentBeforeExitHandler: (() => void) | null = null;
 
+/** Match all SaaS regional URLs (us.sentry.io, de.sentry.io, o1234.ingest.us.sentry.io, etc.) */
+const SENTRY_SAAS_SUBDOMAIN_RE = /^https:\/\/[^/]*\.sentry\.io(\/|$)/;
+
+/** Match the bare sentry.io domain itself */
+const SENTRY_SAAS_ROOT_RE = /^https:\/\/sentry\.io(\/|$)/;
+
+/**
+ * Build trace propagation targets for Sentry API URLs.
+ *
+ * Matches:
+ * - SaaS: *.sentry.io (all regional URLs like us.sentry.io, de.sentry.io)
+ * - SaaS: sentry.io itself
+ * - Self-hosted: the configured SENTRY_HOST/SENTRY_URL if non-SaaS
+ *
+ * @internal Exported for testing
+ */
+export function getSentryTracePropagationTargets(): (string | RegExp)[] {
+  const targets: (string | RegExp)[] = [
+    SENTRY_SAAS_SUBDOMAIN_RE,
+    SENTRY_SAAS_ROOT_RE,
+  ];
+
+  // Also match self-hosted Sentry instances
+  const customUrl = getConfiguredSentryUrl();
+  if (customUrl && !isSentrySaasUrl(customUrl)) {
+    targets.push(customUrl);
+  }
+
+  return targets;
+}
+
 /**
  * Initialize Sentry for telemetry.
  *
@@ -272,8 +307,8 @@ export function initSentry(enabled: boolean): Sentry.BunClient | undefined {
     tracesSampleRate: 1,
     sampleRate: 1,
     release: CLI_VERSION,
-    // Don't propagate traces to external services
-    tracePropagationTargets: [],
+    // Propagate traces to Sentry API for distributed tracing
+    tracePropagationTargets: getSentryTracePropagationTargets(),
 
     beforeSendTransaction: (event) => {
       // Remove server_name which may contain hostname (PII)

test/lib/telemetry.test.ts

@@ -12,6 +12,7 @@ import * as Sentry from "@sentry/bun";
 import { ApiError, AuthError } from "../../src/lib/errors.js";
 import {
   createTracedDatabase,
+  getSentryTracePropagationTargets,
   initSentry,
   isClientApiError,
   recordApiErrorOnSpan,
@@ -927,3 +928,114 @@ describe("createTracedDatabase", () => {
     });
   });
 });
+
+describe("getSentryTracePropagationTargets", () => {
+  const SENTRY_URL_ENV = "SENTRY_URL";
+  const SENTRY_HOST_ENV = "SENTRY_HOST";
+  let originalSentryUrl: string | undefined;
+  let originalSentryHost: string | undefined;
+
+  beforeEach(() => {
+    originalSentryUrl = process.env[SENTRY_URL_ENV];
+    originalSentryHost = process.env[SENTRY_HOST_ENV];
+    delete process.env[SENTRY_URL_ENV];
+    delete process.env[SENTRY_HOST_ENV];
+  });
+
+  afterEach(() => {
+    if (originalSentryUrl === undefined) {
+      delete process.env[SENTRY_URL_ENV];
+    } else {
+      process.env[SENTRY_URL_ENV] = originalSentryUrl;
+    }
+    if (originalSentryHost === undefined) {
+      delete process.env[SENTRY_HOST_ENV];
+    } else {
+      process.env[SENTRY_HOST_ENV] = originalSentryHost;
+    }
+  });
+
+  test("matches SaaS regional URLs", () => {
+    const targets = getSentryTracePropagationTargets();
+    const regexTargets = targets.filter(
+      (t): t is RegExp => t instanceof RegExp
+    );
+    expect(
+      regexTargets.some((r) => r.test("https://us.sentry.io/api/0/"))
+    ).toBe(true);
+    expect(
+      regexTargets.some((r) => r.test("https://de.sentry.io/api/0/"))
+    ).toBe(true);
+    expect(
+      regexTargets.some((r) =>
+        r.test("https://o1234.ingest.us.sentry.io/api/0/")
+      )
+    ).toBe(true);
+  });
+
+  test("matches bare sentry.io", () => {
+    const targets = getSentryTracePropagationTargets();
+    const regexTargets = targets.filter(
+      (t): t is RegExp => t instanceof RegExp
+    );
+    expect(regexTargets.some((r) => r.test("https://sentry.io/api/0/"))).toBe(
+      true
+    );
+  });
+
+  test("does not match non-sentry URLs", () => {
+    const targets = getSentryTracePropagationTargets();
+    const regexTargets = targets.filter(
+      (t): t is RegExp => t instanceof RegExp
+    );
+    expect(regexTargets.some((r) => r.test("https://example.com/api/0/"))).toBe(
+      false
+    );
+    expect(
+      regexTargets.some((r) => r.test("https://not-sentry.io/api/0/"))
+    ).toBe(false);
+  });
+
+  test("does not match domains beyond sentry.io TLD boundary", () => {
+    const targets = getSentryTracePropagationTargets();
+    const regexTargets = targets.filter(
+      (t): t is RegExp => t instanceof RegExp
+    );
+    // sentry.io.evil.com should NOT match
+    expect(
+      regexTargets.some((r) => r.test("https://sentry.io.evil.com/api/0/"))
+    ).toBe(false);
+    // us.sentry.io.evil.com should NOT match
+    expect(
+      regexTargets.some((r) => r.test("https://us.sentry.io.evil.com/api/0/"))
+    ).toBe(false);
+  });
+
+  test("includes self-hosted URL when configured", () => {
+    process.env[SENTRY_URL_ENV] = "https://sentry.mycompany.com";
+    const targets = getSentryTracePropagationTargets();
+    const stringTargets = targets.filter(
+      (t): t is string => typeof t === "string"
+    );
+    expect(stringTargets).toContain("https://sentry.mycompany.com");
+  });
+
+  test("does not include SaaS URL as string target", () => {
+    // Default (no SENTRY_URL) → only RegExp targets, no string targets
+    const targets = getSentryTracePropagationTargets();
+    const stringTargets = targets.filter(
+      (t): t is string => typeof t === "string"
+    );
+    expect(stringTargets).toHaveLength(0);
+  });
+
+  test("does not duplicate SaaS URL when SENTRY_URL is sentry.io", () => {
+    process.env[SENTRY_URL_ENV] = "https://sentry.io";
+    const targets = getSentryTracePropagationTargets();
+    // SaaS URLs are already covered by regex — no string target should be added
+    const stringTargets = targets.filter(
+      (t): t is string => typeof t === "string"
+    );
+    expect(stringTargets).toHaveLength(0);
+  });
+});