feat(spans): Document trace attachments (#15705)

Author: jjbayer

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), 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 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
+  "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

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](/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.