Attachments

Trace attachments use item type "attachment" with content type "application/vnd.sentry.trace-attachment" (since 1.5.1). Unlike standard attachments, trace attachments are associated with a trace rather than an event. They are only optionally associated with other trace items (spans, logs).

Envelope headers:

• trace (optional): If the envelope containing the trace attachment has a Dynamic Sampling Context, it will be subject to trace-based dynamic sampling rules and potentially dropped.

Attachment placeholders use item type "attachment" with content type "application/vnd.sentry.attachment-ref+json". A placeholder contains a reference to an attachment uploaded elsewhere — it does not contain the actual attachment payload. The purpose is for the attachment to be handled (rate limited, filtered, etc.) together with the event payload, even if it was uploaded separately.

SDKs SHOULD send placeholders in the same envelope as the event the file is attached to.

Workflow:

1. If an attachment is larger than ~100 MiB, upload it to the TUS-conformant upload endpoint:

   1. Create the upload:

      Shell

      Copied

      curl -X POST https://o0.ingest.sentry.io/api/0/upload/ \
        --header "Tus-Resumable: 1.0.0" \
        --header "Upload-Length: ${FILE_SIZE}" \
        --header "Upload-Metadata: sentry $(echo -n '{"attachment_type":"event.attachment"}' | base64)"
      

      The Upload-Metadata header follows the TUS metadata format. Sentry recognizes a single key, sentry, the value of which MUST be the Base64 encoding of a UTF-8 JSON object describing the attachment:

      JSON

      Copied

      {
        "attachment_type": "event.attachment"
      }
      

      Field	Type	Required	Description
      attachment_type	String	REQUIRED	One of the values listed in Attachment Types.

   2. Get the location response header:

      Bash

      Copied

      HTTP/1.1 201 Created
      Location: https://o0.ingest.sentry.io/api/0/upload/24e533e02ec3bc40c387f1a0e460e216/
      Tus-Resumable: 1.0.0
      

   3. Upload the file:

      Shell

      Copied

      curl -X PATCH https://o0.ingest.sentry.io/api/0/upload/24e533e02ec3bc40c387f1a0e460e216/ \
        --header "Tus-Resumable: 1.0.0" \
        --header "Content-Type: application/offset+octet-stream" \
        --header "Upload-Offset: 0" \
        --data @myfile.log
      

2. Upon successful upload, attach a placeholder item to the event envelope, using the Location header from the upload response.

Envelope headers:

Item headers:

The item header MUST also contain the original file's attachment_type if it was set. The item payload MUST contain the original file's content_type as a field in the JSON object (see Standard Attachment Item).

Item payload:

{
  "location": "/api/42/upload/019c7a950dd376a1817a9ced5cb7c4b5/?length=212341234&signature=Zct1IMmM3BIJrzDOwG3tUn5AlrLhqIJFBu8Kd59dXCz",
  "content_type": "text/plain"
}

{
  "location": "/api/42/upload/019c7a950dd376a1817a9ced5cb7c4b5/?length=212341234&signature=Zct1IMmM3BIJrzDOwG3tUn5AlrLhqIJFBu8Kd59dXCz",
  "content_type": "text/plain"
}

Item headers:

Item payload:

The trace attachment payload consists of a JSON metadata object immediately followed by the raw attachment body:

{
  "trace_id": "12312012123120121231201212312012",
  "attachment_id": "019a72d07ffe77208c013ac888b38d9e",
  "timestamp": 1760520026.781239,
  "filename": "myfile.txt",
  "content_type": "text/plain",
  "attributes": {
    "foo": {"type": "string", "value": "bar"}
  }
}helloworld

{
  "trace_id": "12312012123120121231201212312012",
  "attachment_id": "019a72d07ffe77208c013ac888b38d9e",
  "timestamp": 1760520026.781239,
  "filename": "myfile.txt",
  "content_type": "text/plain",
  "attributes": {
    "foo": {"type": "string", "value": "bar"}
  }
}helloworld

Metadata fields: