From 1e18cb3611754e031b4076acb729fffd1681d42e Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Tue, 11 Nov 2025 15:26:22 +0100 Subject: [PATCH 1/3] feat(spans): Attachment V2 envelope item --- .../sdk/telemetry/spans/span-protocol.mdx | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/develop-docs/sdk/telemetry/spans/span-protocol.mdx b/develop-docs/sdk/telemetry/spans/span-protocol.mdx index cd40147ffdd76e..0e9c8dfcb89f37 100644 --- a/develop-docs/sdk/telemetry/spans/span-protocol.mdx +++ b/develop-docs/sdk/telemetry/spans/span-protocol.mdx @@ -223,3 +223,50 @@ Example: trace_id: "6cf173d587eb48568a9b2e12dcfbea52" 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 +``` + +- `attachment_id` must be a [Version 7 UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_7_(timestamp_and_random)) generated by the SDK. It should be formatted as a 32 character hexidecimal string without dashes, though it may also contain dashes (e.g. `019a72d0-7ffe-7720-8c01-3ac888b38d9e`). +- `timestamp` must be a UNIX timestamp corresponding to the attachment's occurence. It may be the same as the start or end timestamp of the owner span. +- `filename` may be omitted. +- `content_type` should be the content type of the attachment body (the content type of the envelope item is always `application/vnd.sentry.attachment.v2`). +- `attributes` are arbitrary attributes that will be queryable on the attachment trace item, similar to spans, logs, and trace metrics. + + + From 9cf2bab99b3a445e3623496e96b13c63cb53caca Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Tue, 11 Nov 2025 15:41:15 +0100 Subject: [PATCH 2/3] table --- develop-docs/sdk/telemetry/spans/span-protocol.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/span-protocol.mdx b/develop-docs/sdk/telemetry/spans/span-protocol.mdx index 0e9c8dfcb89f37..6c19b885e797bd 100644 --- a/develop-docs/sdk/telemetry/spans/span-protocol.mdx +++ b/develop-docs/sdk/telemetry/spans/span-protocol.mdx @@ -262,11 +262,13 @@ The attachment item payload consists of JSON object containing metadata followed }helloworld ``` -- `attachment_id` must be a [Version 7 UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_7_(timestamp_and_random)) generated by the SDK. It should be formatted as a 32 character hexidecimal string without dashes, though it may also contain dashes (e.g. `019a72d0-7ffe-7720-8c01-3ac888b38d9e`). -- `timestamp` must be a UNIX timestamp corresponding to the attachment's occurence. It may be the same as the start or end timestamp of the owner span. -- `filename` may be omitted. -- `content_type` should be the content type of the attachment body (the content type of the envelope item is always `application/vnd.sentry.attachment.v2`). -- `attributes` are arbitrary attributes that will be queryable on the attachment trace item, similar to spans, logs, and trace metrics. +| 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` | arbitrary attributes that will be queryable on the attachment trace item, similar to spans, logs, and trace metrics. | From 763e3f13e5805456700c6bfa281ea022d78e6579 Mon Sep 17 00:00:00 2001 From: Joris Bayer Date: Tue, 11 Nov 2025 15:48:12 +0100 Subject: [PATCH 3/3] fix table --- 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 6c19b885e797bd..053269681a2c95 100644 --- a/develop-docs/sdk/telemetry/spans/span-protocol.mdx +++ b/develop-docs/sdk/telemetry/spans/span-protocol.mdx @@ -268,7 +268,7 @@ The attachment item payload consists of JSON object containing metadata followed | `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` | arbitrary attributes that will be queryable on the attachment trace item, similar to spans, logs, and trace metrics. | +| `attributes` | object | No | arbitrary attributes that will be queryable on the attachment trace item, similar to spans, logs, and trace metrics. |