From 7dbd12d95eb048aac6e3ceadbb01a1e04152356e Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Wed, 3 Dec 2025 10:20:53 +0100 Subject: [PATCH 1/5] feat(spans): Document trace attachments --- .../sdk/data-model/envelope-items.mdx | 52 +++++++++++++++++++ .../sdk/telemetry/spans/span-protocol.mdx | 48 ++--------------- 2 files changed, 55 insertions(+), 45 deletions(-) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 06bff55a61d88c..f84b66c229774a 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -113,6 +113,58 @@ file. It is always associated to an event or transaction. : _String, optional._ The content type of the attachment payload. Any [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) may be used; the default is `application/octet-stream`. +### Trace Attachment + +Item type `"attachment"` with content type `"application/vnd.sentry.attachment.v2"`. This item contains a raw payload of an attachment together with metadata. Contrary to V1 attachments, trace attachments are only optionally associated with other trace items (spans, logs, ...). Their main association is with the trace itself. + +**Envelope Headers:** + +- `trace` (optional): If the envelope containing the trace attachment has a [Dynamic Sampling Context](/sdk/telemetry/traces/dynamic-sampling-context.md), it will be subject to trace-based dynamic sampling rules, and potentially dropped. + +**Item Headers:** + +The trace attachment item header must contain the following properties: + +```json +{ + "type": "attachment", + "content_type": "application/vnd.sentry.attachment.v2", + "length": 212341234, + "meta_length": 123 +} +``` + +- `meta_length` is the size of the metadata portion of the payload in bytes (see item description below). + + +**Item Payload:** + +The trace attachment item payload consists of JSON object containing metadata followed by the attachment body. For example, for a plain text attachment with the body "helloworld", the item payload would look like this: + +```json +{ // Attachment Metadata + "trace_id": "12312012123120121231201212312012", + "attachment_id": "019a72d07ffe77208c013ac888b38d9e", + "timestamp": 1760520026.781239, + "filename": "myfile.txt", + "content_type": "text/plain", + "attributes": { + // Arbitrary key value pairs that will end up in EAP. + "foo": {"type": "string", "value": "bar"} + } +}helloworld +``` + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `trace_id` | string | Yes | The trace ID. Determines which `trace` the attachment belongs to. 32-character hexadecimal string. | +| `attachment_id` | string | Yes | 32-character hexadecimal string (a valid [Version 7](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_7_(timestamp_and_random)) or Version 4 UUID without dashes) | +| `timestamp` | float | Yes | a UNIX timestamp corresponding to the attachment's occurrence. It may be the same as the start or end timestamp of the owner span. | +| `filename` | string | No | The file name of the attachment. | +| `content_type` | string | Yes | the content type of the attachment body (not to be confused with the content type of the envelope item, which is always `application/vnd.sentry.attachment.v2`). | +| `attributes` | object | No | arbitrary attributes that will be queryable on the attachment trace item, similar to spans, logs, and trace metrics. | + + ### Session Item type `"session"` contains a single session initialization or update to an diff --git a/develop-docs/sdk/telemetry/spans/span-protocol.mdx b/develop-docs/sdk/telemetry/spans/span-protocol.mdx index 1deaa20b6bac12..51150ffa03ba87 100644 --- a/develop-docs/sdk/telemetry/spans/span-protocol.mdx +++ b/develop-docs/sdk/telemetry/spans/span-protocol.mdx @@ -218,49 +218,7 @@ span_id: "438f40bd3b4a41ee" ## Span Attachments -The SDK must implement a new "attachment v2" envelope item, which is used to emit span attachments to Sentry. A span attachment should be emitted in the same envelope as its owner span, so that it can be dropped when the span itself is filtered or rate limited. - -### Attachment v2 Envelope Item Header - -The envelope item header must contain the following properties: - -```json -{ - "type": "attachment", - "content_type": "application/vnd.sentry.attachment.v2", - "length": 212341234, - "meta_length": 123, - "span_id": "abcd1234" // or `null` -} -``` - -- `meta_length` is the size of the metadata portion of the payload in bytes (see item description below). -- `span_id` is the ID of the span that owns the attachment. `span_id: null` is treated as “owned by spans”, but not owned by a specific span. That is, the attachment can be dropped if the span quota is exceeded, but it will not be dropped with a specific span because of e.g. inbound filters. - -## Attachment v2 Envelope Item Payload - -The attachment item payload consists of JSON object containing metadata followed by the attachment body. For example, for a plain text attachment with the body "Hello World!", the item payload would look like this: - -```json -{ // Attachment Metadata - "attachment_id": "019a72d07ffe77208c013ac888b38d9e", - "timestamp": 1760520026.781239, - "filename": "myfile.txt", - "content_type": "text/plain", - "attributes": { - // Arbitrary key value pairs that will end up in EAP. - "foo": {"type": "string", "value": "bar"} - } -}helloworld -``` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| `attachment_id` | string | Yes | 32-character hexadecimal string (a valid [Version 7](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_7_(timestamp_and_random)) or Version 4 UUID without dashes) | -| `timestamp` | float | Yes | a UNIX timestamp corresponding to the attachment's occurrence. It may be the same as the start or end timestamp of the owner span. | -| `filename` | string | No | The file name of the attachment. | -| `content_type` | string | Yes | the content type of the attachment body (not to be confused with the content type of the envelope item, which is always `application/vnd.sentry.attachment.v2`). | -| `attributes` | object | No | arbitrary attributes that will be queryable on the attachment trace item, similar to spans, logs, and trace metrics. | - - +To associate an attachment with a span, submit a trace attachment item with an additional `span_id` item header. The trace attachment _should_ be submitted in the same envelope as the span itself. +- `span_id` is the ID of the span that owns the attachment. If set, the attachment will be dropped with the span if the span is dropped by dynamic sampling, inbound filters or rate limits. That is, Relay treats `span_id` as the owner of the attachment. +- The SDK _may_ set the `span_id` item header to an explicit `null` value. `span_id: null` is treated as “owned by spans”, but not owned by a specific span. That is, the attachment can be dropped if the span quota is exceeded, but it will not be dropped with a specific span because of e.g. inbound filters. From c926c1a54daa0a4bd9a134ebe35c914808f37c19 Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Wed, 3 Dec 2025 10:41:31 +0100 Subject: [PATCH 2/5] link --- develop-docs/sdk/telemetry/spans/span-protocol.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/spans/span-protocol.mdx b/develop-docs/sdk/telemetry/spans/span-protocol.mdx index 51150ffa03ba87..6d9e48c823df14 100644 --- a/develop-docs/sdk/telemetry/spans/span-protocol.mdx +++ b/develop-docs/sdk/telemetry/spans/span-protocol.mdx @@ -218,7 +218,7 @@ span_id: "438f40bd3b4a41ee" ## Span Attachments -To associate an attachment with a span, submit a trace attachment item with an additional `span_id` item header. The trace attachment _should_ be submitted in the same envelope as the span itself. +To associate an attachment with a span, submit a [trace attachment](/sdk/data-model/envelope-items.mdx#trace-attachment) item with an additional `span_id` item header. The trace attachment _should_ be submitted in the same envelope as the span itself. - `span_id` is the ID of the span that owns the attachment. If set, the attachment will be dropped with the span if the span is dropped by dynamic sampling, inbound filters or rate limits. That is, Relay treats `span_id` as the owner of the attachment. - The SDK _may_ set the `span_id` item header to an explicit `null` value. `span_id: null` is treated as “owned by spans”, but not owned by a specific span. That is, the attachment can be dropped if the span quota is exceeded, but it will not be dropped with a specific span because of e.g. inbound filters. From 391d3d2b74f584ff469f634ed522ff7600d876e6 Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Wed, 3 Dec 2025 10:43:51 +0100 Subject: [PATCH 3/5] fix link --- develop-docs/sdk/telemetry/spans/span-protocol.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/spans/span-protocol.mdx b/develop-docs/sdk/telemetry/spans/span-protocol.mdx index 6d9e48c823df14..7a768f1c67c06d 100644 --- a/develop-docs/sdk/telemetry/spans/span-protocol.mdx +++ b/develop-docs/sdk/telemetry/spans/span-protocol.mdx @@ -218,7 +218,7 @@ span_id: "438f40bd3b4a41ee" ## Span Attachments -To associate an attachment with a span, submit a [trace attachment](/sdk/data-model/envelope-items.mdx#trace-attachment) item with an additional `span_id` item header. The trace attachment _should_ be submitted in the same envelope as the span itself. +To associate an attachment with a span, submit a [trace attachment](/sdk/data-model/envelope-items/#trace-attachment) item with an additional `span_id` item header. The trace attachment _should_ be submitted in the same envelope as the span itself. - `span_id` is the ID of the span that owns the attachment. If set, the attachment will be dropped with the span if the span is dropped by dynamic sampling, inbound filters or rate limits. That is, Relay treats `span_id` as the owner of the attachment. - The SDK _may_ set the `span_id` item header to an explicit `null` value. `span_id: null` is treated as “owned by spans”, but not owned by a specific span. That is, the attachment can be dropped if the span quota is exceeded, but it will not be dropped with a specific span because of e.g. inbound filters. From 5f3a5f30177bfe3819e46c021c585c0674076016 Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Wed, 3 Dec 2025 10:54:41 +0100 Subject: [PATCH 4/5] fix link --- develop-docs/sdk/data-model/envelope-items.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index f84b66c229774a..6b5cc058b86b2f 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -119,7 +119,7 @@ Item type `"attachment"` with content type `"application/vnd.sentry.attachment.v **Envelope Headers:** -- `trace` (optional): If the envelope containing the trace attachment has a [Dynamic Sampling Context](/sdk/telemetry/traces/dynamic-sampling-context.md), it will be subject to trace-based dynamic sampling rules, and potentially dropped. +- `trace` (optional): If the envelope containing the trace attachment has a [Dynamic Sampling Context](/sdk/telemetry/traces/dynamic-sampling-context), it will be subject to trace-based dynamic sampling rules, and potentially dropped. **Item Headers:** From 91ff5427d9a85b79a79a7968044dc973149c2d29 Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Wed, 3 Dec 2025 11:32:01 +0100 Subject: [PATCH 5/5] Update develop-docs/sdk/data-model/envelope-items.mdx Co-authored-by: Tobias Wilfert <36408720+tobias-wilfert@users.noreply.github.com> --- develop-docs/sdk/data-model/envelope-items.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 6b5cc058b86b2f..bd555a680269e2 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -139,7 +139,7 @@ The trace attachment item header must contain the following properties: **Item Payload:** -The trace attachment item payload consists of JSON object containing metadata followed by the attachment body. For example, for a plain text attachment with the body "helloworld", the item payload would look like this: +The trace attachment item payload consists of a JSON object containing metadata followed by the attachment body. For example, for a plain text attachment with the body "helloworld", the item payload would look like this: ```json { // Attachment Metadata