Skip to content

feat(spans): Attachment V2 envelope item #15466

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
merged 3 commits into from
Nov 14, 2025
Merged

feat(spans): Attachment V2 envelope item #15466

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1e18cb3
feat(spans): Attachment V2 envelope item
jjbayer Nov 11, 2025
9cf2bab
table
jjbayer Nov 11, 2025
763e3f1
fix table
jjbayer Nov 11, 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
49 changes: 49 additions & 0 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 @@ -223,3 +223,52 @@ 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,
Copy link

@sentry sentry bot Nov 11, 2025

Choose a reason for hiding this comment

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

Bug: Incorrect meta_length example in documentation for Attachment v2 envelope item header.
Severity: CRITICAL | Confidence: 1.00

🔍 Detailed Analysis

The documentation specifies "meta_length": 123 as an example value for the Attachment v2 envelope item header, but the actual byte count of the provided example metadata JSON is approximately 190+ bytes when minified. This meta_length field is critical for correctly parsing the envelope by defining the boundary between metadata and the binary attachment body. This discrepancy in the specification for a new feature (INGEST-624) will lead to incorrect SDK implementations and subsequent parsing failures or data corruption.

💡 Suggested Fix

Update the meta_length example value in span-protocol.mdx from 123 to approximately 234 to accurately reflect the byte count of the example metadata JSON.

🤖 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/telemetry/spans/span-protocol.mdx#L240

Potential issue: The documentation specifies `"meta_length": 123` as an example value
for the Attachment v2 envelope item header, but the actual byte count of the provided
example metadata JSON is approximately 190+ bytes when minified. This `meta_length`
field is critical for correctly parsing the envelope by defining the boundary between
metadata and the binary attachment body. This discrepancy in the specification for a new
feature (INGEST-624) will lead to incorrect SDK implementations and subsequent parsing
failures or data corruption.

Did we get this right? 👍 / 👎 to inform future reviews.

"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. |



Loading