feat(local): render OTel semantic attributes in transaction output (#1015)

## Summary

Enhance `sentry local` for the agent monitoring launch with OTel
semantic attribute rendering, JSON output, SSE reconnection, and several
quality improvements.

### OTel Semantic Display

Port `trace-semantic-display` from sentry-mcp ([PR
#981](getsentry/sentry-mcp#981)) to enrich tail
output with OTel semantic attribute rendering. Transactions with GenAI,
MCP, HTTP, database, and other OTel attributes now show rich labels:

```
[gen_ai] chat anthropic/claude-4-sonnet [1200ms] [5 spans]
[mcp] tools/call search_files [320ms]
[db] SELECT users [postgresql] [12ms]
```

Covers 15 attribute families: GenAI, MCP, HTTP, database, GraphQL,
RPC/cloud, messaging, FaaS, object stores, CloudEvents, CICD, feature
flags, process, exception, and error types. Falls back to existing
behavior when no semantic attributes are present.

### `--format json` (NDJSON)

New `--format json` / `-F json` flag for machine-readable output. Each
envelope item produces one JSON line with structured fields including
semantic labels, stack frames, and source detection:

```json
{"type":"transaction","op":"gen_ai","label":"chat anthropic/claude-4-sonnet","duration_ms":1200,"source":"server"}
{"type":"error","error_type":"TypeError","message":"x is not a function","filename":"app.ts","lineno":42,"source":"server"}
```

### `--filter ai`

New filter value that matches transactions with GenAI or MCP OTel
attributes, so you can focus on agent activity: `sentry local -f ai`

### SSE Reconnection

The SSE consumer now reconnects automatically with exponential backoff
on connection loss, using `Last-Event-ID` to resume from where the
stream left off. Retry counter resets after successful reconnection.
Transient HTTP errors after a previous successful session are retried
rather than treated as fatal.

### Quality Improvements

- **Signal handler leak fixed** in `run.ts` — named handler refs,
cleanup in `finally`, settled flag for close/error race
- **`parsePort` deduplicated** — single implementation exported from
`server.ts`
- **`SENTRY_TRACES_SAMPLE_RATE`** preserved when already set (uses `??`
fallback)
- **Startup banner** with ingest URL, SSE endpoint, and connection hints
- **Agent monitoring docs** with GenAI/MCP examples and JSON output
section

## Files Changed

| File | Change |
|------|--------|
| `src/lib/formatters/semantic-display.ts` | **New** — OTel semantic
attribute rendering (15 families) |
| `src/lib/formatters/local.ts` | Semantic display integration, JSON
formatters, `--filter ai`, `inferSourceName` |
| `src/commands/local/server.ts` | SSE reconnection, `--format json`,
`--filter ai`, `parsePort` export, `feedSSELine` id tracking, startup
banner |
| `src/commands/local/run.ts` | Signal handler fix, `parsePort` import,
env var preservation |
| `docs/src/fragments/commands/local.md` | Agent monitoring section,
JSON output section |
| `test/lib/formatters/semantic-display.test.ts` | **New** — 70+ tests
for all semantic formatters |
| `test/lib/formatters/local.test.ts` | AI transaction tests, JSON
format tests |
| `test/commands/local/server.test.ts` | **New** — parsePort,
feedSSELine, buildApp, CORS, isServerRunning |
| `test/commands/local/run.test.ts` | Expanded — ENOENT, env
preservation, separator handling |

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: BYK

docs/src/fragments/commands/local.md

@@ -34,7 +34,7 @@ Env vars injected into the child process:
 |----------|-------|
 | `SENTRY_SPOTLIGHT` | `http://localhost:<port>/stream` |
 | `NEXT_PUBLIC_SENTRY_SPOTLIGHT` | `http://localhost:<port>/stream` |
-| `SENTRY_TRACES_SAMPLE_RATE` | `1` |
+| `SENTRY_TRACES_SAMPLE_RATE` | `1` (unless already set) |
 
 ## Endpoints
 
@@ -64,3 +64,32 @@ sentry local -f error -f log    # only errors and logs
 ```
 
 Use `--quiet` to suppress tail output entirely if you only need the SSE stream.
+
+## Agent monitoring
+
+`sentry local` shows rich output for AI agent spans when your SDK instruments with [OpenTelemetry semantic attributes](https://opentelemetry.io/docs/specs/semconv/gen-ai/):
+
+```
+14:32:01 [TRACE]   [SERVER]  [gen_ai] chat anthropic/claude-4-sonnet [1200ms] [5 spans]
+14:32:02 [TRACE]   [SERVER]  [mcp] tools/call search_files [320ms]
+14:32:03 [TRACE]   [SERVER]  [db] SELECT users [postgresql] [12ms]
+14:32:04 [ERROR]   [SERVER]  RateLimitError: API quota exceeded [api_client.py:42]
+```
+
+GenAI operations show the model name, MCP tool calls show the tool being invoked, and database queries show the system and query summary. This works automatically when your Sentry SDK is configured with AI/LLM integrations.
+
+## JSON output
+
+Use `--format json` (or `-F json`) for machine-readable NDJSON output, one JSON object per envelope item:
+
+```bash
+sentry local --format json
+```
+
+```json
+{"type":"transaction","timestamp":1700000001,"op":"gen_ai","label":"chat anthropic/claude-4-sonnet","duration_ms":1200,"span_count":5,"source":"server"}
+{"type":"error","timestamp":1700000002,"error_type":"RateLimitError","message":"API quota exceeded","source":"server"}
+{"type":"log","timestamp":1700000003,"level":"info","message":"User logged in","attributes":{"user_id":1234},"source":"server"}
+```
+
+This is useful for AI coding agents and automation tools that need to consume Sentry events programmatically.

plugins/sentry-cli/skills/sentry-cli/references/local.md

@@ -19,7 +19,8 @@ Start the local dev server and tail events
 - `-p, --port <value> - Port to listen on (default 8969) - (default: "8969")`
 - `-H, --host <value> - Hostname to bind to (default localhost) - (default: "localhost")`
 - `-q, --quiet - Suppress per-envelope tail output`
-- `-f, --filter <value>... - Only show items of this type (repeatable: error, transaction, log)`
+- `-f, --filter <value>... - Only show items of this type (repeatable: error, transaction, log, ai)`
+- `-F, --format <value> - Output format: human (default) or json (NDJSON) - (default: "human")`
 
 ### `sentry local run <command...>`
 
@@ -49,6 +50,8 @@ sentry local -f error -f log
 sentry local --quiet
 
 sentry local -f error -f log    # only errors and logs
+
+sentry local --format json
 ```
 
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

src/commands/local/run.ts

@@ -21,6 +21,7 @@ import {
   buildApp,
   DEFAULT_PORT,
   isServerRunning,
+  parsePort,
   tryListen,
 } from "./server.js";
 
@@ -29,18 +30,6 @@ type RunFlags = {
   readonly host: string;
 };
 
-/** Parse and validate a port number. */
-function parsePort(value: string): number {
-  const port = Number(value);
-  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
-    throw new ValidationError(
-      `Invalid port: ${value}. Must be an integer between 0 and 65535.`,
-      "port"
-    );
-  }
-  return port;
-}
-
 /** Buffer size for the auto-started background server. */
 const BUFFER_SIZE = 500;
 
@@ -140,7 +129,8 @@ export const runCommand = buildCommand({
           ...process.env,
           SENTRY_SPOTLIGHT: spotlightUrl,
           NEXT_PUBLIC_SENTRY_SPOTLIGHT: spotlightUrl,
-          SENTRY_TRACES_SAMPLE_RATE: "1",
+          SENTRY_TRACES_SAMPLE_RATE:
+            process.env.SENTRY_TRACES_SAMPLE_RATE ?? "1",
         },
         stdio: "inherit",
       });
@@ -155,23 +145,34 @@ export const runCommand = buildCommand({
     }
 
     // Forward signals to the child so the whole process tree shuts down.
-    const forwardSignal = (signal: NodeJS.Signals) => {
-      child.kill(signal);
-    };
-    process.once("SIGINT", () => forwardSignal("SIGINT"));
-    process.once("SIGTERM", () => forwardSignal("SIGTERM"));
+    // Store references so handlers can be removed in finally.
+    const onSigint = () => child.kill("SIGINT");
+    const onSigterm = () => child.kill("SIGTERM");
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
 
     let exitCode: number;
     try {
       exitCode = await new Promise<number>((resolve, reject) => {
-        child.on("close", (code) => resolve(code ?? 1));
+        let settled = false;
+        child.on("close", (code) => {
+          if (!settled) {
+            settled = true;
+            resolve(code ?? 1);
+          }
+        });
         // If spawn itself fails (e.g. ENOENT), 'close' may never fire.
         child.on("error", (err) => {
           logger.debug(`Child process error: ${err.message}`);
-          reject(err);
+          if (!settled) {
+            settled = true;
+            reject(err);
+          }
         });
       });
     } finally {
+      process.removeListener("SIGINT", onSigint);
+      process.removeListener("SIGTERM", onSigterm);
       if (bgServer) {
         logger.info("Stopping background server...");
         await shutdownServer(bgServer);