Attachments API

[smeubank]

Problem Statement

The JavaScript SDK does not have proper Attachments API support

Today the JavaScript SDK asks the user to call the API endpoint on Sentry

https://docs.sentry.io/platforms/javascript/enriching-events/attachments/

we should have something similar to other SDKs

https://docs.sentry.io/platforms/java/enriching-events/attachments/

Solution Brainstorm

we should have something similar to other SDKs

https://docs.sentry.io/platforms/java/enriching-events/attachments/

Work

• PR adding attachments API: feat: Add attachments API #5004
• Ensure attachments are attached to envelopes correctly: ref(core): Actually ensure attachments are added to the envelope #5159
• Testing mutability: ref(core): Test mutation of attachments in hint #5140

[timfish]

We send minidumps from the Electron SDK as attachments but this is currently hacked through additional methods on the transport.

My only concern with how many of the existing SDKs handle attachments is that they read them into memory at the point of attaching:

SentrySdk.ConfigureScope(scope =>
{
    // Add an in-memory attachment to the current scope
    scope.AddAttachment(bytes, "file.log");
});

This has the downside that you can't automatically add an attachment when a global error is caught.

You could periodically add screenshots as attachments but do attachments with the same file name get overwritten or do they get added to an ever growing list?

It looks like the native SDK monitors a file path and only loads it on crash/error:

sentry_options_add_attachment(options, "/var/server.log");

You could add attachments to the Event and then transport would be responsible for pulling them out when creating the envelope payload. This has the advantage that attachments can be added/modified in event processors and beforeSend. Allowing integrations to add attachments would be handy.

What API considerations need to be made for platforms where file paths do not exist (ie. browser). Do we allow adding Blob and ArrayBuffer too?

[philipphofmann]

Hey @timfish, @vladanpaunovic asked me to answer your questions.

Question 1

My only concern with how many of the existing SDKs handle attachments is that they read them into memory at the point
of attaching

On Cocoa and Java, you can create an attachment with a path. The SDK will read the contents of the file each time it prepares an event or transaction, then adds the attachment to the same envelope, see https://docs.sentry.io/platforms/apple/guides/ios/enriching-events/attachments/#creating-attachments

let attachment = Attachment(path: "your/path/file.log")

Question 2

You could periodically add screenshots as attachments but do attachments with the same file name get overwritten or do they get added to an ever growing list?

On Cocoa and on Java, the attachments on the scope are a list, so you can add multiple attachments with the same name. Sentry can handle that, see

Question 3

You could add attachments to the Event and then transport would be responsible for pulling them out when creating the envelope payload.

We don't add attachments to events, as an event gets serialized to its own envelope item, and attachments end up in a different envelope item. Yes, from a user's perspective, it would be nice if events could also contain attachments and, for example, user reports, but the idea was that events can survive a serialization roundtrip which doesn't work with attachments since it can be some stream or whatever.
For event processors and beforeSend, we can use hints to either add or discard attachments. I created an issue to document this in the develop docs getsentry/develop#566.

Question 4

What API considerations need to be made for platforms where file paths do not exist (ie. browser). Do we allow adding Blob and ArrayBuffer too?

If this makes sense on JavaScript, yes of course. Please discuss this with your JavaScript buddies, as I'm not an expert on JavaScript. Whatever you decide, please then either ping me with the outcome or update the develop docs here https://develop.sentry.dev/sdk/features/#attachments.

[philipphofmann]

@timfish and @AbhiPrasad, I added why we don't have attachments on events but use hints instead. ⬆️

[mitsuhiko]

My only concern with how many of the existing SDKs handle attachments is that they read them into memory at the point of attaching:

So for what it's worth i'm pretty sure the python SDK also supports delayed reads. That said, the big issue is that since captures are async changes to the file after attaching are iffy. When people attach logfiles and they are read async they contain stuff that wasn't there yet at the time of report.

Generally speaking I would prefer the JS SDK mirrors the Python SDK for attachments and if we decide to diverge, we also consider this for Python. JS should not be much different than the Python SDK with regards to requirements.

[philipphofmann]

Yes, @mitsuhiko, Python supports delayed reads with a file path. Are you suggesting we should consider dropping support for delayed reads as the file contents can be iffy?

As pointed out by @timfish, on JS browser you don't have file paths, so on JS, we might have to use something like Blobs instead of a file path for delayed reads.

[AbhiPrasad]

The initial version of the attachments API (#5004) is available with the v7 release candidate, so closing this issue. We can open new issues as we iterate on in further.

[philipphofmann]

@AbhiPrasad, it would be nice to link the related PR(s).

[AbhiPrasad]

PRs linked in description @philipphofmann