feat(dev): App reference Spotlight specs for SDKs #15493
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
) ## 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.): <!-- ENTER DATE HERE --> - [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 <!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## 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.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [ ] 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 <!-- Sentry employees and contractors can delete or ignore this section. --> 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/)
Bundle ReportChanges will increase total bundle size by 1.78kB (0.01%) ⬆️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: sentry-docs-client-array-pushAssets Changed:
view changes for bundle: sentry-docs-server-cjsAssets Changed:
|
Bundle ReportChanges will increase total bundle size by 1.19kB (0.01%) ⬆️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: sentry-docs-server-cjsAssets Changed:
view changes for bundle: sentry-docs-client-array-pushAssets Changed:
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| - `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 |
There was a problem hiding this comment.
how will this work when someone runs spotlight run and it chooses a dynamic port?
There was a problem hiding this comment.
See below? If this is explicitly set, we assume it's for a reason and ignore the env variabl.
philipphofmann
left a comment
philipphofmann
left a comment
There was a problem hiding this comment.
Thanks for adding the docs for Spotlight. I left a few comments.
|
|
||
| ## Configuration Options | ||
|
|
||
| SDKs should support Spotlight configuration through one of two approaches: |
There was a problem hiding this comment.
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
| SDKs should support Spotlight configuration through one of two approaches: | |
| 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: |
There was a problem hiding this comment.
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
| 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 | ||
| - This should **not affect** the upstream Sentry sample rates |
There was a problem hiding this comment.
This really must not impact the other sample rates, or do we have any uses cases or SDKs for which that is acceptable?
| - This should **not affect** the upstream Sentry sample rates | |
| - This **MUST NOT affect** the upstream Sentry sample rates |
| ### PII Data Collection | ||
|
|
||
| - Enable **all PII data collection** for Spotlight (equivalent to `sendDefaultPii: true`) | ||
| - This should **not affect** upstream Sentry PII settings | ||
| - Spotlight is intended for local development, so full data visibility is expected |
There was a problem hiding this comment.
This might be a bit tricky depending on the features sending PII and it could also be a bit risky. Is this a hard requirement for all SDKs? I think in most SDKs, we have two transports forwarding data to both spotlight and Sentry. All the PII collecting stuff happens before the envelope ends up in the transport.
|
|
||
| ### Sampling | ||
|
|
||
| - Enable **100% sample rate** for the Spotlight pipeline |
There was a problem hiding this comment.
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.
| ### Default Behavior | ||
|
|
||
| - Spotlight is **disabled by default** | ||
| - SDKs should only enable Spotlight when explicitly configured or when the environment variable is set |
There was a problem hiding this comment.
| - SDKs should only enable Spotlight when explicitly configured or when the environment variable is set | |
| - SDKs MUST only enable Spotlight when explicitly configured or when the environment variable is set. |
|
|
||
| - If the Spotlight server is unreachable, SDKs should: | ||
| - Log an error message (ideally once, not per-envelope) | ||
| - Implement exponential backoff retry logic |
There was a problem hiding this comment.
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.
Fixes getsentry/spotlight#545