feat(local): inject all framework spotlight prefixes; document DSN-less capture and -f ai filter#1034
Merged
Merged
Conversation
`sentry local` worked but a few things were undocumented and bit a user: - No DSN required: with no DSN, events go only to the local server (nothing reaches the user's Sentry org / no production quota); with a DSN set, the SDK sends to both. Make this explicit — it's the main reassurance for using spotlight in local dev. - NEXT_PUBLIC_SENTRY_SPOTLIGHT is injected but the SDK does NOT read it automatically. Server-side SDKs pick up SENTRY_SPOTLIGHT on their own; browser/client SDKs need `spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT` wired into the client config (and other frameworks use VITE_/REACT_APP_). - Document the `-f ai` filter for watching gen_ai/mcp agent spans. Adds an agent-guidance "Capture Events Locally" workflow so the guidance also reaches the generated agent skill (which keeps code blocks, strips prose). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
|
Contributor
Codecov Results 📊✅ Patch coverage is 100.00%. Project has 4420 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 81.86% 81.86% —%
==========================================
Files 341 341 —
Lines 24359 24362 +3
Branches 15915 15915 —
==========================================
+ Hits 19939 19942 +3
- Misses 4420 4420 —
- Partials 1663 1663 —Generated by Codecov Action |
…wiring
Inject SENTRY_SPOTLIGHT under every common framework client prefix
(PUBLIC_, NEXT_PUBLIC_, VITE_, NUXT_PUBLIC_, REACT_APP_, VUE_APP_,
GATSBY_) so the spotlight URL reaches browser bundles regardless of
bundler, not just Next.js.
Reframe the docs: the manual Sentry.init({ spotlight: ... }) wiring is
the current workaround until the browser SDK reads these vars
automatically (getsentry/sentry-javascript#18198). Normalize
'sentry local serve -f ai' to 'sentry local -f ai'.
BYK
changed the title
…wiring
Inject SENTRY_SPOTLIGHT under every common framework client prefix
(PUBLIC_, NEXT_PUBLIC_, VITE_, NUXT_PUBLIC_, REACT_APP_, VUE_APP_,
GATSBY_) so the spotlight URL reaches browser bundles regardless of
bundler, not just Next.js.
Reframe the docs: the manual Sentry.init({ spotlight: ... }) wiring is
the current workaround until the browser SDK reads these vars
automatically (getsentry/sentry-javascript#18198). Normalize
'sentry local serve -f ai' to 'sentry local -f ai'.
MathurAditya724
added a commit
that referenced
this pull request
Jun 5, 2026
## Summary SIGINT/SIGTERM during `--verify` mode or post-init verification was forwarded to the child process but never re-emitted afterward. After cleanup completed, the CLI continued normally instead of terminating — the user's Ctrl+C was silently swallowed. This fix tracks the received signal and re-emits it via `process.kill(process.pid, signal)` after all cleanup (child kill, server shutdown, listener removal) completes, so the default handler terminates the process with the correct exit code. Fixes both `src/commands/local/run.ts` (`runWithVerify`) and `src/lib/init/verify-setup.ts` (`verifySetup`). ## Testing - `vitest run test/commands/local/run.test.ts` — 12 tests pass - `vitest run test/lib/init/wizard-runner.test.ts test/lib/dev-script.test.ts test/lib/dev-script.property.test.ts` — 57 tests pass - `pnpm run lint` — clean - `tsc --noEmit` — no errors (excluding pre-existing generated-file issues) Addresses warden findings from #998. <!-- ## Plan ### Problem Warden flagged (twice, across commits 5c40365 and fc94462) that SIGINT is swallowed in verify-setup.ts: signal handlers forward SIGINT to the child but don't re-emit or exit, so the wizard continues after verifySetup returns. The same pattern exists in runWithVerify in run.ts. ### Fix (2 files) 1. `src/lib/init/verify-setup.ts` - Add `signalReceived: NodeJS.Signals | null` variable - Update onSigint/onSigterm to set signalReceived before forwarding - After cleanup, check signalReceived and re-emit via process.kill(process.pid, signal) 2. `src/commands/local/run.ts` (runWithVerify function) - Same pattern: track signal, re-emit after cleanup ### Verification - PR #1034's CLIENT_SPOTLIGHT_PREFIXES work confirmed intact on main - All existing tests pass - Lint and typecheck clean -->
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
sentry localworks well, but a few behaviors were undocumented and tripped up a user debugging logs/traces locally. This started as a docs fix and now also closes a real gap in client-side wiring.No DSN required. With no DSN configured, events flow only to the local server — nothing reaches the user's Sentry org and no production quota is used. With a DSN set, the SDK sends to both. This is the main reassurance for using spotlight in local dev and wasn't stated.
Inject every framework client prefix (behavior change).
sentry local runpreviously injected onlyNEXT_PUBLIC_SENTRY_SPOTLIGHT. It now injects the spotlight URL under all common framework client prefixes so the URL is inlined into the browser bundle regardless of bundler:PUBLIC_(SvelteKit, Astro, Qwik)NEXT_PUBLIC_(Next.js)VITE_(Vite)NUXT_PUBLIC_(Nuxt)REACT_APP_(Create React App)VUE_APP_(Vue CLI)GATSBY_(Gatsby)This mirrors the prefix set from getsentry/sentry-javascript#18198.
SENTRY_SPOTLIGHT(read by server-side SDKs) is still set and is applied last so the base name is never shadowed by a client variant.Client-side wiring caveat, reframed. No
@sentry/*package reads these client vars yet — only@sentry/node-corereadsSENTRY_SPOTLIGHT(server-side). The previous docs framed manual wiring as a permanent requirement; it's actually the current workaround until the browser SDK reads these vars automatically (#18198, which this PR is a good opportunity to revive). Until then, reference the variable for your framework:-f aifilter. Documented for watchinggen_ai/mcpagent spans while iterating on an agent. Normalizedsentry local serve -f ai→sentry local -f aifor consistency.Where it lands
src/commands/local/run.ts→CLIENT_SPOTLIGHT_PREFIXESconstant + env injection loop; updated module JSDoc andfullDescription.test/commands/local/run.test.ts→ asserts every<PREFIX>SENTRY_SPOTLIGHTvariant plus the base name are injected with the spotlight URL.docs/src/fragments/commands/local.md→ thelocaldocs page + generated skill reference.docs/src/content/docs/agent-guidance.md→ the "Capture Events Locally" workflow. Since the skill generator keeps code blocks but strips prose, the key facts are encoded as comments in a bash snippet so they reach the agent skill too.SKILL.md. Unrelated date-based reference drift left out; CI auto-commit handles that.Notes
--verify/--timeout/dev-script auto-detect tolocal run).check:fragments,check:docs-sections,lint,typecheck, and thetest/commands/localsuite (29 tests) pass locally.🤖 Generated with Claude Code