feat(dev): App reference Spotlight specs for SDKs #15493

BYK · 2025-11-12T17:10:51Z

vercel · 2025-11-12T17:10:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
develop-docs	Building	Preview	Comment	Nov 14, 2025 9:54am

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
sentry-docs	Ignored	Preview		Nov 14, 2025 9:54am

…5482)

) ## DESCRIBE YOUR PR November 12th we update our retention periods. This updates the doc to match that change. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.):  - [x] Other deadline: November 12 - [ ] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Shannon Anahata <[email protected]>

we shipped this for users during logs GA, spec is locked in now  ## DESCRIBE YOUR PR *Tell us what you're changing and why. If your PR **resolves an issue**, please link it so it closes automatically.* ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.):  - [ ] Other deadline:  - [ ] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [x] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE  Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)

codecov · 2025-11-12T17:21:00Z

Bundle Report

Changes will increase total bundle size by 1.78kB (0.01%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-server-cjs	12.62MB	1.78kB (0.01%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`server/middleware-*.js`	-6.46kB	1.0kB	-86.59%
`server/middleware-*.js`	6.46kB	7.46kB	645.5% ⚠️

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`1729.js`	-3 bytes	1.74MB	-0.0%
`../instrumentation.js`	-3 bytes	1.07MB	-0.0%
`9523.js`	-3 bytes	1.04MB	-0.0%
`../app/[[...path]]/page.js.nft.json`	596 bytes	769.35kB	0.08%
`../app/platform-redirect/page.js.nft.json`	596 bytes	769.27kB	0.08%
`../app/sitemap.xml/route.js.nft.json`	596 bytes	766.5kB	0.08%

codecov · 2025-11-12T17:21:00Z

Bundle Report

Changes will increase total bundle size by 1.19kB (0.01%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-client-array-push	10.17MB	-6 bytes (-0.0%) ⬇️
sentry-docs-server-cjs	12.62MB	1.19kB (0.01%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`1729.js`	-3 bytes	1.74MB	-0.0%
`../instrumentation.js`	-3 bytes	1.07MB	-0.0%
`9523.js`	-3 bytes	1.04MB	-0.0%
`../app/[[...path]]/page.js.nft.json`	401 bytes	769.42kB	0.05%
`../app/platform-redirect/page.js.nft.json`	401 bytes	769.33kB	0.05%
`../app/sitemap.xml/route.js.nft.json`	401 bytes	766.56kB	0.05%

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`static/chunks/pages/_app-*.js`	-3 bytes	882.71kB	-0.0%
`static/chunks/8321-*.js`	-3 bytes	425.87kB	-0.0%
`server/middleware-*.js`	6.46kB	7.46kB	645.5% ⚠️
`server/middleware-*.js`	-6.46kB	1.0kB	-86.59%
`static/pAtU0jRru4Mgc6o5hEGut/_buildManifest.js` (New)	684 bytes	684 bytes	100.0% 🚀
`static/pAtU0jRru4Mgc6o5hEGut/_ssgManifest.js` (New)	77 bytes	77 bytes	100.0% 🚀
~~`static/R2yT8xd_2gH1TfIsmnXSP/_buildManifest.js`~~ (Deleted)	-684 bytes	0 bytes	-100.0% 🗑️
~~`static/R2yT8xd_2gH1TfIsmnXSP/_ssgManifest.js`~~ (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️

develop-docs/sdk/expected-features/spotlight.mdx

betegon · 2025-11-13T11:43:57Z

develop-docs/sdk/expected-features/spotlight.mdx

+- `false` or `undefined`/`null`: Spotlight is disabled
+- `true`: Spotlight is enabled using the default URL (`http://localhost:8969/stream`)
+- `string`: Spotlight is enabled using the provided URL


how will this work when someone runs spotlight run and it chooses a dynamic port?

See below? If this is explicitly set, we assume it's for a reason and ignore the env variabl.

philipphofmann

Thanks for adding the docs for Spotlight. I left a few comments.

philipphofmann · 2025-11-13T12:46:28Z

develop-docs/sdk/expected-features/spotlight.mdx

+
+## Configuration Options
+
+SDKs should support Spotlight configuration through one of two approaches:


This document already uses uppercase for a couple of occurrences or "MUST", "SHOULD", and "MAY". So it seems like we're following: https://www.ietf.org/rfc/rfc2119.txt. Therefore, I would write all occurrences uppercase

Suggested change

SDKs should support Spotlight configuration through one of two approaches:

SDKs SHOULD support Spotlight configuration through one of two approaches:

philipphofmann · 2025-11-13T12:48:34Z

develop-docs/sdk/expected-features/spotlight.mdx

+
+## Environment Variable Handling
+
+SDKs must support the `SENTRY_SPOTLIGHT` environment variable. The value should be parsed according to the following rules:


We don't have that yet on Cocoa. Environment variables are not that common for mobile platforms. I would change this to a SHOULD or MAY

Suggested change

SDKs must support the `SENTRY_SPOTLIGHT` environment variable. The value should be parsed according to the following rules:

SDKs SHOULD support the `SENTRY_SPOTLIGHT` environment variable. The value should be parsed according to the following rules:

Unfortunately, no. Implementation of SENTRY_SPOTLIGHT is non-negotiable. How can we help support this in Cocoa?

Exposing local env vars into the Xcode simulator would still require a developer to do this manually. So mobile SDKs have other constrains that make this work differently than e.g. running a Flask app on your machine.

Implementation of SENTRY_SPOTLIGHT is non-negotiable.

Please elaborate on the reasons.

It's not uncommon to use env vars on mobile in combination with simulators. We already do that for disabling spotlight in our UI tests here https://github.com/getsentry/sentry-cocoa/blob/aa43aea663aa0be90964af89e670f18dc22dc146/Samples/iOS-Swift/iOS-Swift-UITests/BaseUITest.swift#L34-L45

Adding adds value, but I wouldn't give it the highest priority on mobile. If you say non-negiotable, I'd like to know the reasons.

develop-docs/sdk/expected-features/spotlight.mdx

philipphofmann · 2025-11-13T12:58:18Z

develop-docs/sdk/expected-features/spotlight.mdx

+
+### Sampling
+
+- Enable **100% sample rate** for the Spotlight pipeline


I'm pretty sure some SDKs don't meet that requirement. For example, on Cocoa, we have two transports. One sends to Sentry, the other to Spotlight. Sampling happens before the transport. So, currently, the sampling behavior is the same for both Spotlight and Sentry envelopes. I'm unsure if having two different sampling behaviours is actually worth the complexity. This could be tricky to set up in some SDKs. It could also confuse users.

This document is defining the ideal state we should be in, not what the current state of the SDKs are. We will need to try evolving the SDKs towards these goals.

develop-docs/sdk/expected-features/spotlight.mdx

philipphofmann · 2025-11-13T13:02:14Z

develop-docs/sdk/expected-features/spotlight.mdx

+
+- If the Spotlight server is unreachable, SDKs should:
+  - Log an error message (ideally once, not per-envelope)
+  - Implement exponential backoff retry logic


What drove you to add this? I'm unsure if it's worth adding this. Did we have any problems without the backoff retry logic? If yes, I would explain it a bit here, and clearly state it's optional if possible. I don't think we need this for example on mobile or desktop apps.

What's your concern here?

It's some work and complexity that seems not worth the effort on mobile or JS frontend. TLDR; We can add it, but it's work. If it's a SHOULD then I'm OK with it. The logging an error message is a MUST, IMO.

Co-authored-by: Philipp Hofmann <[email protected]>

develop-docs/sdk/expected-features/spotlight.mdx

Co-authored-by: Philipp Hofmann <[email protected]>

develop-docs/sdk/expected-features/spotlight.mdx

philipphofmann

Thanks you @BYK , LGTM

develop-docs/sdk/expected-features/spotlight.mdx

feat(dev): App reference Spotlight specs for SDKs

573e174

[getsentry/action-github-commit] Auto commit

bcb30a9

vercel bot had a problem deploying to Preview – develop-docs November 12, 2025 17:17 Failure

Lms24 and others added 5 commits November 12, 2025 17:18

ref(develop): Clarify telemetry data > scope attribute precedence (#1…

54a89d9

…5482)

feat(docs): Bump min version for metrics (#15490)

3998f7a

fix(Unity): Expanded on known limitations when targeting WebGL (#15485)

f6a0966

codeowner-assignment bot requested a review from a team November 12, 2025 17:19

vercel bot had a problem deploying to Preview – develop-docs November 12, 2025 17:24 Failure

BYK added 2 commits November 12, 2025 17:32

revert silly changes

5b167db

Merge branch 'master' into byk/feat/spotlight-specs

88e6675

vercel bot deployed to Preview – develop-docs November 12, 2025 17:42 View deployment

tighten things up a bit

b38e3b3

BYK mentioned this pull request Nov 12, 2025

Implement spotlight plan to dos #15492

Closed

6 tasks

vercel bot deployed to Preview – develop-docs November 12, 2025 20:15 View deployment

BYK marked this pull request as ready for review November 13, 2025 11:40

cursor bot reviewed Nov 13, 2025

View reviewed changes

develop-docs/sdk/expected-features/spotlight.mdx Show resolved Hide resolved

betegon reviewed Nov 13, 2025

View reviewed changes

sentrivana approved these changes Nov 13, 2025

View reviewed changes

philipphofmann reviewed Nov 13, 2025

View reviewed changes

Apply suggestion from @philipphofmann

8748525

Co-authored-by: Philipp Hofmann <[email protected]>

cursor bot reviewed Nov 13, 2025

View reviewed changes

develop-docs/sdk/expected-features/spotlight.mdx Show resolved Hide resolved

Apply suggestion from @philipphofmann

37fd74d

Co-authored-by: Philipp Hofmann <[email protected]>

cursor bot reviewed Nov 13, 2025

View reviewed changes

develop-docs/sdk/expected-features/spotlight.mdx Show resolved Hide resolved

vercel bot deployed to Preview – develop-docs November 13, 2025 22:05 View deployment

tidy up language according to RFC 2119

01c2d40

vercel bot deployed to Preview – develop-docs November 13, 2025 22:25 View deployment

philipphofmann approved these changes Nov 14, 2025

View reviewed changes

develop-docs/sdk/expected-features/spotlight.mdx Outdated Show resolved Hide resolved

BYK added 2 commits November 14, 2025 09:52

address review comments

ac3e098

fix typos

e3aefbe


		## Configuration Options

		SDKs should support Spotlight configuration through one of two approaches:


		## Environment Variable Handling

		SDKs must support the `SENTRY_SPOTLIGHT` environment variable. The value should be parsed according to the following rules:

	SDKs must support the `SENTRY_SPOTLIGHT` environment variable. The value should be parsed according to the following rules:
	SDKs SHOULD support the `SENTRY_SPOTLIGHT` environment variable. The value should be parsed according to the following rules:


		### Sampling

		- Enable 100% sample rate for the Spotlight pipeline

Uh oh!

feat(dev): App reference Spotlight specs for SDKs #15493

Are you sure you want to change the base?

feat(dev): App reference Spotlight specs for SDKs #15493

Conversation

BYK commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Nov 12, 2025

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Assets Changed:

Uh oh!

codecov bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Assets Changed:

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

philipphofmann left a comment

Choose a reason for hiding this comment

Uh oh!

philipphofmann Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

philipphofmann Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

philipphofmann left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

BYK commented Nov 12, 2025 •

edited

Loading

vercel bot commented Nov 12, 2025 •

edited

Loading

codecov bot commented Nov 12, 2025 •

edited

Loading

philipphofmann Nov 13, 2025 •

edited

Loading

philipphofmann Nov 13, 2025 •

edited

Loading