fix(telemetry): exclude OutputError from Sentry exception capture (CLI-PK) (#629)

## Summary

- **Exclude `OutputError` from `Sentry.captureException()`** in
`withTelemetry`'s outer catch block. `OutputError` is an intentional
non-zero exit mechanism (e.g., `sentry api` got a 4xx/5xx response), not
a CLI bug. This eliminates ~1,335 noise events across 160 users
([CLI-PK](https://sentry.sentry.io/issues/7367976863/)).
- **Add structured `api_error.*` span attributes** (`status`,
`endpoint`, `method`) on the active telemetry span before throwing
`OutputError` in the `sentry api` command, preserving Discover
queryability for API error rates.
- **Add tests** verifying `OutputError` is not captured as a Sentry
exception.

## Changes

| File | Change |
|------|--------|
| `src/lib/telemetry.ts` | Add `OutputError` to exclusion check
alongside `AuthError` and client `ApiError` |
| `src/commands/api.ts` | Add `recordApiErrorAttributes()` helper;
record span attributes on 4xx/5xx |
| `test/lib/telemetry.test.ts` | Add 2 tests for `OutputError` exclusion
(null data + object data) |

Fixes CLI-PK

Author: BYK

src/commands/api.ts

@@ -5,6 +5,8 @@
  * Similar to 'gh api' for GitHub.
  */
 
+// biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
+import * as Sentry from "@sentry/node-core/light";
 import type { SentryContext } from "../context.js";
 import { buildSearchParams, rawApiRequest } from "../lib/api-client.js";
 import { buildCommand } from "../lib/command.js";
@@ -1036,6 +1038,28 @@ export async function resolveBody(
 
 // Command Definition
 
+/**
+ * Record API error attributes on the active telemetry span.
+ *
+ * Since `OutputError` is excluded from `Sentry.captureException` (it signals
+ * an intentional non-zero exit, not a CLI bug), these span attributes are the
+ * only telemetry signal for `sentry api` HTTP errors. They're queryable in
+ * Discover via `api_error.status`, matching the pattern used by
+ * `recordApiErrorOnSpan` for `ApiError`-based errors in other commands.
+ */
+function recordApiErrorAttributes(
+  status: number,
+  endpoint: string,
+  method: string
+): void {
+  const span = Sentry.getActiveSpan();
+  if (span) {
+    span.setAttribute("api_error.status", status);
+    span.setAttribute("api_error.endpoint", endpoint);
+    span.setAttribute("api_error.method", method);
+  }
+}
+
 /** Log outgoing request details in `> ` curl-verbose style. */
 function logRequest(
   method: string,
@@ -1217,6 +1241,17 @@ export const apiCommand = buildCommand({
       logResponse(response);
     }
 
+    // Record API error attributes on the active span for Discover queryability.
+    // OutputError is excluded from Sentry.captureException (it's an intentional
+    // non-zero exit, not a bug), so span attributes are the only telemetry signal.
+    if (isError) {
+      recordApiErrorAttributes(
+        response.status,
+        normalizedEndpoint,
+        flags.method
+      );
+    }
+
     // Silent mode — no output, just exit code
     if (flags.silent) {
       if (isError) {

src/lib/telemetry.ts

@@ -20,7 +20,7 @@ import {
 } from "./constants.js";
 import { isReadonlyError, tryRepairAndRetry } from "./db/schema.js";
 import { getEnv } from "./env.js";
-import { ApiError, AuthError } from "./errors.js";
+import { ApiError, AuthError, OutputError } from "./errors.js";
 import { attachSentryReporter } from "./logger.js";
 import { getSentryBaseUrl, isSentrySaasUrl } from "./sentry-urls.js";
 import { getRealUsername } from "./utils.js";
@@ -150,7 +150,12 @@ export async function withTelemetry<T>(
       (e.reason === "not_authenticated" || e.reason === "expired");
     // 4xx API errors are user errors (wrong ID, no access), not CLI bugs.
     // They're recorded as span attributes above for volume-spike detection.
-    if (!(isExpectedAuthState || isClientApiError(e))) {
+    // OutputError is an intentional non-zero exit (e.g., `sentry api` got a
+    // 4xx/5xx response) — not a CLI bug. Error details are recorded as span
+    // attributes by the command itself.
+    if (
+      !(isExpectedAuthState || isClientApiError(e) || e instanceof OutputError)
+    ) {
       Sentry.captureException(e);
       markSessionCrashed();
     }

test/lib/telemetry.test.ts

@@ -17,7 +17,7 @@ import {
 import { chmodSync, mkdirSync, rmSync } from "node:fs";
 // biome-ignore lint/performance/noNamespaceImport: needed for spyOn mocking
 import * as Sentry from "@sentry/node-core/light";
-import { ApiError, AuthError } from "../../src/lib/errors.js";
+import { ApiError, AuthError, OutputError } from "../../src/lib/errors.js";
 import {
   createTracedDatabase,
   getSentryTracePropagationTargets,
@@ -208,6 +208,30 @@ describe("withTelemetry", () => {
       const result = await withTelemetry(() => 42);
       expect(result).toBe(42);
     });
+
+    test("does not capture OutputError (intentional exit-code mechanism)", async () => {
+      const captureSpy = spyOn(Sentry, "captureException");
+      const error = new OutputError(null);
+      await expect(
+        withTelemetry(() => {
+          throw error;
+        })
+      ).rejects.toThrow(error);
+      expect(captureSpy).not.toHaveBeenCalled();
+      captureSpy.mockRestore();
+    });
+
+    test("does not capture OutputError with data", async () => {
+      const captureSpy = spyOn(Sentry, "captureException");
+      const error = new OutputError({ error: "not found" });
+      await expect(
+        withTelemetry(() => {
+          throw error;
+        })
+      ).rejects.toThrow(error);
+      expect(captureSpy).not.toHaveBeenCalled();
+      captureSpy.mockRestore();
+    });
   });
 });