Skip to content

feat(spans): Document trace attachments #15705

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jjbayer merged 5 commits into from
Dec 4, 2025
Merged

feat(spans): Document trace attachments #15705

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7dbd12d
feat(spans): Document trace attachments
jjbayer Dec 3, 2025
c926c1a
link
jjbayer Dec 3, 2025
391d3d2
fix link
jjbayer Dec 3, 2025
5f3a5f3
fix link
jjbayer Dec 3, 2025
91ff542
Update develop-docs/sdk/data-model/envelope-items.mdx
jjbayer Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions develop-docs/sdk/data-model/envelope-items.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
```
Comment on lines +128 to +135
Copy link

@sentry sentry bot Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The envelope-items.mdx documentation for trace attachment item headers is incomplete, omitting span_id.
Severity: HIGH | Confidence: High

🔍 Detailed Analysis

The envelope-items.mdx documentation for trace attachment item headers is incomplete. It omits span_id from the example (lines 128-135) and does not mention it as an optional field. This contradicts span-protocol.mdx, which specifies span_id as an additional item header for span attachments. This inconsistency could lead SDK developers to implement trace attachments without span_id support, breaking span attachment functionality.

💡 Suggested Fix

Update envelope-items.mdx to either include span_id in the item header example (lines 128-135) and mark it as optional, or add a note explicitly stating span_id is an optional field.

🤖 Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: develop-docs/sdk/data-model/envelope-items.mdx#L128-L135

Potential issue: The `envelope-items.mdx` documentation for trace attachment item
headers is incomplete. It omits `span_id` from the example (lines 128-135) and does not
mention it as an optional field. This contradicts `span-protocol.mdx`, which specifies
`span_id` as an additional item header for span attachments. This inconsistency could
lead SDK developers to implement trace attachments without `span_id` support, breaking
span attachment functionality.

Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 5130085

Copy link
Member Author

@jjbayer jjbayer Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I deliberately did not document the header here to avoid confusion.


- `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. |
Copy link
Member

@tobias-wilfert tobias-wilfert Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So to send a span attachment one needs to set both the span_id in the header and the trace_id in the meta?

Copy link
Member Author

@jjbayer jjbayer Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes.

| `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
Expand Down
48 changes: 3 additions & 45 deletions develop-docs/sdk/telemetry/spans/span-protocol.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading