Envelope Items

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 headers. It is worth noting that the list of Item types doesn't match the data categories used for rate limiting and client reports.

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 MUST NOT combine different types of telemetry data in the same envelope, because Relay enforces rate limits per data category, and mixing types makes this enforcement more expensive. The exceptions to this rule are listed below.

The following constraints apply:

1. Mutual exclusivity of event types: event, transaction, and feedback are mutually exclusive; an envelope MUST contain at most one. The envelope header's event_id MUST match the contained event, and other items such as attachments are implicitly scoped to it.
2. Spans: An envelope MUST contain at most one envelope item containing spans. The envelope MUST include a DSC header, and all spans MUST belong to the trace identified by that DSC; see Span Buffer.
3. Logs: An envelope MUST contain at most one envelope item containing logs. SDKs MAY mix logs from different traces in the same envelope item. The envelope MUST NOT include a DSC header; see Logs.
4. Metrics: An envelope MUST contain at most one envelope item containing metrics. SDKs MAY mix metrics from different traces in the same envelope item. The envelope MUST NOT include a DSC header; see Metrics.
5. Sessions: Multiple envelope items containing sessions MAY appear in a single envelope. SDKs SHOULD send session updates in the same envelope as their associated error or crash event; see Sessions.
6. Attachments: Multiple envelope items containing attachments MAY appear in a single envelope. SDKs SHOULD send attachments in the same envelope as their associated event, so that if the event is filtered, the attachments are also filtered. For minidump and Apple crash report attachments, this is a MUST; see Attachments.
7. Check-ins: An envelope MUST contain at most one envelope item containing a check-in; see Check-Ins.
8. Client reports: Multiple envelope items containing client reports MAY appear in a single envelope; see Client Reports.
9. Replays: SDKs MUST send the replay_event and replay_recording envelope items together in the same envelope; see Replay.
10. User reports (deprecated): SDKs SHOULD send user_report envelope items in the same envelope as their associated event; see User Reports.

Envelope Item Types

Event

Item type "event". This Item contains an error or default event payload encoded in JSON.

Constraints:

• This Item may occur at most once per Envelope.
• This Item is mutually exclusive with "transaction" Items.

Envelope Headers:

event_id

UUID String, required. Corresponds to the event_id field of the event

payload. Clients are required to generate an event identifier ahead of time

and set it at least in the Envelope headers. If the identifier mismatches

between the Envelope and payload, the Envelope header takes precedence.

Additional Item Headers:

None

Transaction

Item type "transaction". This Item contains a transaction payload encoded in JSON.

Constraints:

• This Item may occur at most once per Envelope.
• This Item is mutually exclusive with "event" Items.

Envelope Headers:

event_id

UUID String, required. Corresponds to the event_id field of the

transaction payload. Clients are required to generate an event identifier

ahead of time and set it at least in the Envelope headers. If the identifier

mismatches between the Envelope and payload, the Envelope header takes

precedence.

trace

Dynamic sampling context, optional Transaction events can optionally provide a

Dynamic sampling context.

Additional Item Headers:

None

Attachment

Item type "attachment". See the Attachments spec for full documentation of standard attachments, attachment placeholders, and trace attachments.

Check-Ins

Item type "check_in" contains a check-in payload encoded as JSON.

See the Check-Ins documentation for the payload details.

Constraints:

• This Item may occur at most once per Envelope.
• This Item can either be included in an Envelope with other Items, or it may be sent by itself.

Envelope Headers:

None

Additional Item Headers:

None

Reserved Types

Reserved types may not be written by any implementation. They are reserved for future or internal use. This is the exhaustive list of reserved Item types:

• security
• unreal_report
• form_data