The viewer connects to a Local receiver and inspects captured SDK envelopes. Start the receiver and UI in separate terminals from the repository root:
pnpm --filter sentry run cli local serve
pnpm --filter local devOpen the URL printed by Vite and connect to http://localhost:8969.
The receiver can also be a named Local session or an explicitly selected remote
receiver. Capture lifecycle and retention are managed through the existing
Local controls.
With a receiver running, load all bundled examples:
pnpm --filter local sampleThe examples cover correlated errors/logs/traces, repeated database queries, resource loading, Web Vitals, an AI conversation and tool execution, feedback, SDK reports, legacy and continuous profiles, standalone span-v2 telemetry, and text/JSON/HTML/image attachments. All names and content are synthetic. They follow the SDK envelope shapes used in Spotlight's fixture corpus.
Replay any directory of raw SDK envelopes, including Spotlight's _fixtures
directory, recursively:
pnpm --filter local sample /path/to/spotlight/packages/spotlight/_fixtures \
--endpoint http://localhost:8969/stream --compression gzip
pnpm --filter local sample --interval 200 --repeat 3--fixtures is an alternative to the positional path. --endpoint takes
precedence over SENTRY_SPOTLIGHT; otherwise the default is
http://localhost:8969/stream. A named session requires its ingestion endpoint,
not its capability-protected viewer stream URL.
The loader sends .txt, .bin, and .envelope files in sorted order, preserving
raw bytes and captured timestamps. Bundled byte-counted envelopes disable Git
line-ending conversion; preserve the original bytes when checking out external
captures as well. --compression supports none, gzip, and
br; --interval is milliseconds between envelopes and --repeat is a finite
number of passes. It stops with a nonzero exit status when a request is rejected
or times out. The command does not clear existing capture history. Raise the
receiver's envelope retention limit when replaying a large corpus.
- Errors include exception causes, captured source lines and local variables, level, handled state, environment, release, server name, user, breadcrumbs, request/context data, tags, modules, VS Code links for absolute local paths, a copyable Markdown summary for AI assistants, and the attachments the SDK sent for the event (collapsed until previewed).
- AI inspection reads standard
gen_ai.*and Vercel AI fields from both embedded transaction spans and standalone spans. Prompts, responses, token usage and tool arguments/results appear when the SDK captured them. Child AI steps stay linked to their parent interaction. Interaction summaries use captured child metadata, reconcile parent/step token totals, and pair the latest response with its finish reason. Empty or malformed aliases do not hide usable content. - Queries and resources group exact operation/description pairs. Sort by count,
duration or captured resource size and open an execution in its trace.
Browser spans named only by host use the origin and path from
url.full. - Web Vitals groups visits by page and shows individual captured measurements, from pageload transaction measurements or span v2 pageload attributes. LCP, INP, CLS, FCP and TTFB use the Web Vitals thresholds; FID is labelled as a legacy metric. Local samples are not field percentiles.
- Profiles support Sentry sample/stack/frame payloads in legacy
profileitems and continuousprofile_chunkitems. Select a thread, compare inclusive/self time and samples, and explore flame, treemap or sunburst views. Observed time uses adjacent samples on each thread within a captured chunk; no duration is invented across missing chunks or after a final sample. Retained chunks from the same profiler can be viewed together or individually. Sampled functions appear in associated trace waterfalls where captured span timing identifies their parent unambiguously. These rows are labelled as sampled and capped at 5,000 per trace. Charts limit displayed depth/nodes for responsiveness; JSON preserves the selected original payload. - SDKs lists observed names, versions, platforms and last-seen metadata, followed by session/client reports, including server SDK session aggregates. Feedback links to associated errors in the capture.
- Attachments show safe text/JSON/image/video previews and downloads. Captured HTML, SVG and code remain inert; the viewer never executes them or fetches captured resource URLs. Attachments inside a raw envelope stay collapsed and are decoded only when you show their preview.
Use severity/logger filters and sorting in event/log views. Messages hide terminal colour codes; the JSON tab keeps the captured text. The Columns control chooses which metadata appears beside each message. In a trace, search spans, show only matches, collapse branches, or adjust the tree width. Logs that share a trace ID without any spans, such as server startup logs, are marked Logs only and listed after traces with spans.
pnpm --filter local test
pnpm --filter local typecheck
pnpm --filter local buildIntegration tests start an actual receiver, replay the bundled capture through HTTP/SSE, then navigate the analysis and inspector views. Replay tests cover binary bytes, gzip/Brotli, recursive directories, repeated passes and rejected requests. Unknown payloads remain inspectable as JSON.
Envelope decoding and retention live directly in Local and the CLI, without a Spotlight package dependency. Spotlight-compatible health and envelope headers remain supported so existing Sentry SDK transports can keep sending captures.
The receiver accepts gzip, deflate and Brotli with a 10 MiB encoded-body limit and a 32 MiB decoded-body limit. Missing or plain-text content types use the envelope format. Invalid compression returns 400, oversized input 413, unsupported media/encoding 415, and temporary admission overload 503. Malformed envelopes remain listed and downloadable by their receiver ID; downloads retain the original bytes while the text preview is best effort. Retention remains bounded by the configured envelope count.