feat(envelopes): Add envelope item constraints summary#16666
Open
philipphofmann wants to merge 2 commits intomasterfrom
Open
feat(envelopes): Add envelope item constraints summary#16666philipphofmann wants to merge 2 commits intomasterfrom
philipphofmann wants to merge 2 commits intomasterfrom
Conversation
Add "Envelope Item Constraints" section to envelope-items.mdx documenting which envelope item types can be combined in a single envelope, covering mutual exclusivity, spans, logs, metrics, sessions, attachments, check-ins, client reports, replays, and user reports. Link to the new section from the telemetry processor page. Closes #16188 Co-Authored-By: Claude <noreply@anthropic.com> Agent transcript: https://claudescope.sentry.dev/share/UKe0VPmx1a4bth6nObnlSXkEfwtSCJg2kMCkDvFnubo
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Co-Authored-By: Claude <noreply@anthropic.com>
philipphofmann
commented
Mar 4, 2026
| 1. **Mutual exclusivity**: | ||
| - [`event`](#event) and [`transaction`](#transaction) envelope items are mutually exclusive. | ||
| - [`feedback`](/sdk/telemetry/feedbacks/#envelope-item-constraints) and [`transaction`](#transaction) envelope items are mutually exclusive. | ||
| 2. **Spans**: An envelope **MUST** contain at most one envelope item containing spans, and all spans **MUST** share a single traceID; see [Span Buffer](/sdk/telemetry/spans/span-buffer/). |
Member
Author
There was a problem hiding this comment.
@cleptric I'm not 100% sure if that's actually the case that you can only send one envelope item containing spans per envelope. If not, I will adjust the docs here accordingly.
philipphofmann
commented
Mar 4, 2026
|
|
||
| ## Envelope Item Constraints | ||
|
|
||
| SDKs **SHOULD NOT** combine different types of telemetry data in the same envelope, because Relay enforces [rate limits](/sdk/foundations/transport/rate-limiting/) per [data category](/sdk/foundations/transport/rate-limiting/#definitions), and mixing types makes this enforcement more expensive. Exceptions to this rule are listed below (e.g., sessions, client reports, and attachments **MAY** be combined with other items). |
Member
Author
There was a problem hiding this comment.
@cleptric, I added a comment for this on the initial GitHub issue #16188 (comment), but I'm not 100% sure if this is actually the case.
And maybe we should even change this to: SDKs MUST NOT combine different types of telemetry data in the same envelope. Please let me know.
philipphofmann
changed the title
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
1 participant
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.
DESCRIBE YOUR PR
Add an "Envelope Item Constraints" section to the envelope items spec documenting which envelope item types can be combined in a single envelope. This addresses a gap in SDK developer guidance for telemetry processor design.
Closes #16188
IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
Co-Authored-By: Claude noreply@anthropic.com