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..788318ad09697 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,27 @@ 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 + +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. + - [`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/)