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

[BYK]

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) 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:

{"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

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1015/
Built to branch gh-pages at 2026-05-23 12:39 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

❌ Patch coverage is 75.30%. Project has 4281 uncovered lines.
✅ Project coverage is 81.97%. Comparing base (base) to head (head).

Files with missing lines (4)

File	Patch %	Lines
src/commands/local/server.ts	10.26%	⚠️ 70 Missing and 1 partials
src/lib/formatters/semantic-display.ts	94.09%	⚠️ 15 Missing and 13 partials
src/lib/formatters/local.ts	74.63%	⚠️ 17 Missing and 4 partials
src/commands/local/run.ts	100.00%	⚠️ 2 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.87%    81.97%     +0.1%
==========================================
  Files          328       329        +1
  Lines        23359     23744      +385
  Branches     15114     15500      +386
==========================================
+ Hits         19123     19463      +340
- Misses        4236      4281       +45
- Partials      1621      1644       +23

---

Generated by Codecov Action

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit adcc086. Configure here.}

[sentry-warden]

rpc.system.name is not a valid OTel attribute — should be rpc.system

The code reads rpc.system.name to identify the RPC system, but the OTel semantic conventions define this attribute as rpc.system (values: "grpc", "java_rmi", "dotnet_wcf", etc.). Standard OTel-instrumented RPC spans will never populate rpcSystem, silently dropping the system label from metadata and causing inferSemanticOp to miss spans that only carry rpc.system without rpc.service.

Evidence

• getAttr(attrs, ["rpc.system.name"]) at line 317 will always return undefined for spans instrumented by standard OTel SDKs, which emit rpc.system.
• db.system.name (used for databases at line 247) is the correct newer-semconv attribute, so the *.system.name pattern was incorrectly extended to RPC where no such rename occurred in the spec.
• inferSemanticOp at line 146 also uses "rpc.system.name" as its primary key; a span with only {"rpc.system": "grpc"} would not be tagged as rpc.
• Unit tests at test/lib/formatters/semantic-display.test.ts:285,504 also use rpc.system.name, confirming the wrong key propagated into test coverage rather than catching the mismatch.

_{Identified by Warden find-bugs · LHB-MGA}