Sentry Spotlight

Sentry Spotlight is an open-source local development tool that captures errors, traces, and logs from all three app layers (web, API, worker) and displays them in a browser UI on http://localhost:8969. It requires no Sentry account and no remote DSN — everything stays on your machine.

Why use Spotlight?

• Zero signup: No Sentry project or account needed for local dev.
• Full-stack visibility: Errors, traces, and logs from web, API, and worker all appear in one place.
• AI-assisted debugging: An MCP server exposes Spotlight data to AI agents for automated triage.
• No production overhead: Spotlight is local-only. Production deployments are unaffected.

Quick start

Spotlight starts automatically as part of the local infrastructure. If you have SENTRY_SPOTLIGHT=true in your .env (the default in .env.example), everything works out of the box:

pnpm infra:ensure   # starts Spotlight alongside Postgres, Jaeger, etc.
pnpm dev            # apps detect SENTRY_SPOTLIGHT=true and forward events

Open the UI at http://localhost:8969 or via pnpm dev:open.

Using the native desktop app instead

If you prefer the Spotlight desktop app over the Docker container, stop the container first to free port 8969:

docker compose -p tx-agent-kit stop spotlight

Then run the native app — it listens on the same port, so no config changes are needed.

How it works

Browser (web)  ──┐
API server     ──┼──▶  Spotlight sidecar (port 8969)  ──▶  Browser UI
Worker         ──┘         /stream endpoint

Each app layer initializes Sentry with spotlight: true. The Sentry SDK sends event envelopes to the Spotlight sidecar's /stream HTTP endpoint. Spotlight stores them in memory and renders them in its web UI.

Dual-path delivery

When both Spotlight and a real Sentry DSN are configured, events flow to both destinations. This lets you test production Sentry integration while still seeing events locally:

Trace sampling

When Spotlight is enabled, tracesSampleRate is set to 1.0 (100% of traces captured). When disabled, it defaults to 0 — no trace overhead in production unless explicitly configured via DSN.

Environment variables

When SENTRY_SPOTLIGHT=true and no layer-specific DSN is set, each layer uses the placeholder DSN https://spotlight@local/0 so Sentry initializes and forwards events to the local sidecar.

Per-layer wiring

All three layers follow the same pattern: lazy-load the Sentry module, check for Spotlight/DSN, and initialize with spotlight: true when enabled.

Each initializer is idempotent and safe to call multiple times. When neither Spotlight nor a DSN is configured, initialization is a no-op.

MCP server for AI debugging

Spotlight exposes an MCP server for programmatic access by AI agents:

pnpm mcp:spotlight

This runs @spotlightjs/spotlight mcp against http://localhost:8969 and provides four tools:

The MCP server is configured in .mcp.json as spotlight-local and runs via scripts/mcp/spotlight.sh.

Integration tests

The Spotlight integration is tested at packages/infra/observability/src/spotlight.integration.test.ts. Tests verify HTTP connectivity to port 8969, Sentry envelope POST to /stream, and batch envelope handling. Tests auto-skip when the sidecar is not running.

Each app layer also has its own Sentry integration tests that verify Spotlight placeholder DSN initialization and dual-path delivery.

Relationship to OpenTelemetry

Spotlight and the OpenTelemetry stack (Jaeger, Prometheus, Grafana) serve complementary roles:

Spotlight captures Sentry-specific error context (breadcrumbs, stack traces, user context) that the OTEL pipeline does not. Use Spotlight for error triage and Jaeger for latency analysis.

Related pages