From 74ea9e3d328dc47acec31ad728008403ed66c28d Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Wed, 4 Mar 2026 09:40:54 +0100 Subject: [PATCH 1/2] docs(sdk): Add envelope item constraints section 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 Agent transcript: https://claudescope.sentry.dev/share/UKe0VPmx1a4bth6nObnlSXkEfwtSCJg2kMCkDvFnubo --- .../processing/telemetry-processor/index.mdx | 2 ++ .../foundations/transport/envelope-items.mdx | 25 +++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx index 875063216d3c9..8b7653078433d 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx @@ -84,6 +84,8 @@ This exact flow is not enforced for all SDKs. SDKs **MAY** adapt the architectur We aim to standardize requirements so SDKs share consistent logic across platforms. This benefits multi-platform SDKs like Java. However, requirements **MAY** differ where necessary. This page outlines common requirements; platform-specific requirements are listed [below](#platform-specific-requirements). +For rules on which items can be combined in a single envelope, see [Envelope Item Constraints](/sdk/foundations/transport/envelope-items/#envelope-item-constraints). These constraints impact the design — for example, the [span buffer](#span-buffer) organizes spans per traceID because each envelope can only contain spans from a single trace, while logs and metrics can be batched across traces. + # Telemetry Buffer The telemetry buffer batches high-volume data and forwards it to the telemetry scheduler. This section covers the common requirements for all platforms: diff --git a/develop-docs/sdk/foundations/transport/envelope-items.mdx b/develop-docs/sdk/foundations/transport/envelope-items.mdx index 0c6e58d33db2d..9c77a2c0b82c7 100644 --- a/develop-docs/sdk/foundations/transport/envelope-items.mdx +++ b/develop-docs/sdk/foundations/transport/envelope-items.mdx @@ -3,6 +3,12 @@ title: Envelope Items sidebar_order: 80 --- + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined + in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement + levels. + + Each Envelope consists of headers and a potentially empty list of Items, each with their own headers. Which Headers are required depends on the Items in an Envelope. This section describes all Item types and their respective required @@ -14,6 +20,25 @@ The type of an Item is declared in the `type` header, as well as the payload size in `length`. See Serialization Format for a list of common Item headers. The headers described in this section are **in addition to the common headers**. +## Envelope Item Constraints + +Not all envelope item types can be freely combined in a single envelope. The following constraints apply: + +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/). +3. **Logs**: An envelope **MUST** contain at most one envelope item containing logs. Logs from different traces **MAY** be mixed in the same envelope item, but if they are, the envelope **MUST NOT** include a [DSC](/sdk/foundations/trace-propagation/dynamic-sampling-context/) header; see [Logs](/sdk/telemetry/logs/#log-envelope-item). +4. **Metrics**: An envelope **MUST** contain at most one envelope item containing metrics. Metrics from different traces **MAY** be mixed in the same envelope item, but if they are, the envelope **MUST NOT** include a [DSC](/sdk/foundations/trace-propagation/dynamic-sampling-context/) header; see [Metrics](/sdk/telemetry/metrics/#trace_metric-envelope-item). +5. **Sessions**: Multiple envelope items containing sessions **MAY** appear in a single envelope; see [Sessions](/sdk/telemetry/sessions/#session-update-payload). +6. **Attachments**: Multiple envelope items containing attachments **MAY** appear in a single envelope. Minidump and Apple crash report attachment envelope items **MUST** be sent in the same envelope as their event; see [Attachments](/sdk/telemetry/attachments/#standard-attachments). +7. **Check-ins**: An envelope **MUST** contain at most one envelope item containing a check-in; see [Check-Ins](/sdk/telemetry/check-ins/#envelope-constraints). +8. **Client reports**: Multiple envelope items containing client reports **MAY** appear in a single envelope; see [Client Reports](/sdk/telemetry/client-reports/#wire-format). +9. **Replays**: The `replay_event` and `replay_recording` envelope items **MUST** always be sent together in the same envelope; see [Replay](/sdk/telemetry/replays/#replay-event-payload). +10. **User reports (deprecated)**: `user_report` envelope items **SHOULD** be sent in the same envelope as their associated event; see [User Reports](/sdk/telemetry/user-reports/#envelope-item). + +## Envelope Item Types + ### Event Item type `"event"`. This Item contains an error or default [event payload](/sdk/foundations/transport/event-payloads/) From f126fb1561c879fadf456c436938243f365056e6 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Wed, 4 Mar 2026 09:47:08 +0100 Subject: [PATCH 2/2] docs(sdk): Add general rule against mixing telemetry types in envelopes Co-Authored-By: Claude --- develop-docs/sdk/foundations/transport/envelope-items.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/foundations/transport/envelope-items.mdx b/develop-docs/sdk/foundations/transport/envelope-items.mdx index 9c77a2c0b82c7..788318ad09697 100644 --- a/develop-docs/sdk/foundations/transport/envelope-items.mdx +++ b/develop-docs/sdk/foundations/transport/envelope-items.mdx @@ -22,7 +22,9 @@ The headers described in this section are **in addition to the common headers**. ## Envelope Item Constraints -Not all envelope item types can be freely combined in a single envelope. The following constraints apply: +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). + +The following constraints apply: 1. **Mutual exclusivity**: - [`event`](#event) and [`transaction`](#transaction) envelope items are mutually exclusive.