Skip to content
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

Jump to bottom

feat(native): add a compressed minidump endpoint example #11304

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

feat(native): add a compressed minidump endpoint example #11304

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9f350bd
feat(native): add a compressed minidump endpoint example
supervacuus Sep 10, 2024
6e4e7d0
link the limits section instead of only referring to it
supervacuus Sep 10, 2024
46f5111
replace recycled sentence start
supervacuus Sep 10, 2024
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
53 changes: 53 additions & 0 deletions docs/platforms/native/guides/minidumps/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,59 @@ curl -X POST \
For the full list of supported values, see [_Event Payloads_](https://develop.sentry.dev/sdk/event-payloads/) and linked
documents.

## Uploading a Compressed Minidump

You can compress your minidump using `gzip` if its size exceeds the [limits](#size-limits) in the next section.

In this case, you would `POST` the minidump as a gzip-encoded binary:

```bash
gzip mini.dmp

curl -X POST \
'___MINIDUMP_URL___' \
-H 'content-type:application/x-dmp' \
-H 'content-encoding: gzip' \
--data-binary @mini.dmp.gz
```

Since `curl` doesn't allow adding multipart form fields to "data" `POST` requests, you can't easily pass additional data as fields as in the previous section's examples.

To get around this, you must construct the multipart content manually and compress it as a whole:

```bash
# Use a consistent multipart boundary throughout the example
# and ensure it is a unique string inside the entire multipart body
printf -- '--boundary_minidumpXYZ\r\n' > multipart_body.txt

# Add additional data via JSON or using the bracket syntax (the latter requiring a field for each entry)
printf -- 'Content-Disposition: form-data; name="sentry"\r\n\r\n' >> multipart_body.txt
printf -- '{"release":"my-project-name@2.3.12","tags":{"mytag":"value"}}\r\n' >> multipart_body.txt
Copy link
Member

Choose a reason for hiding this comment

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

My first time going through these steps I didn't change this "release" to the actual version that the .dmp file was built for, which I think is the reason I got an {"detail":"invalid minidump"}% result.

Not sure if the advanced users that would use this method of sending minidumps would make the same mistake, but still might be something worth highlighting.

Other than that, these instructions seem fine as a beginner's guide.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

My first time going through these steps I didn't change this "release" to the actual version that the .dmp file was built for, which I think is the reason I got an {"detail":"invalid minidump"}% result.

The main reason you could get an "invalid minidump" (besides the obvious attaching an invalid minidump file 😅) is probably due to bad escaping or delimiting characters because those could prevent the receiving parser from "seeing" the minidump field.

Correctly formed meta-data shouldn't affect the validity of the minidump (i.e., Sentry doesn't cross-check the release in the sentry field with the contents of the minidump).

This is why documenting this as a solution is a double-edged sword. Manually constructing a multipart body can quickly introduce encoding errors like turns out I used ” instead of ". Thankfully, that error appeared when parsing the JSON metadata (with a slightly better error message).

But if the encoding error appears beyond the field value boundary (forgetting the correct number of \r\n and similar), you might get the results of a wrongly parsed HTTP request.

I think the best solution to the problem would be to let relay

  • check if the file uploaded as upload_file_minidump is a gzip and in that case
  • unzip the file and then validate it as a minidump and continue processing as it does now

This would allow users to apply the same upload methods as described in the previous sections, but instead of uploading a mini.dmp, they would upload a mini.dmp.gz (identified via the first n-byte header).

Until that solution is implemented and deployed, users have a documented approach for uploading minidumps manually.


# Add the boundary before each field (in this case the minidump)
printf -- '--boundary_minidumpXYZ\r\n' >> multipart_body.txt

# Add the minidump field header
printf -- 'Content-Disposition: form-data; name="upload_file_minidump"; filename="mini.dmp"\r\n' >> multipart_body.txt
printf -- 'Content-Type: application/x-dmp\r\n\r\n' >> multipart_body.txt

# Append the minidump content
cat mini.dmp >> multipart_body.txt

# Add the closing boundary
printf -- '\r\n--boundary_minidumpXYZ--\r\n' >> multipart_body.txt

# Compress the entire multipart body
gzip multipart_body.txt

# Send the compressed multipart body with curl
curl -X POST \
'___MINIDUMP_URL___' \
-H 'Content-Type: multipart/form-data; boundary=boundary_minidumpXYZ' \
-H 'Content-Encoding: gzip' \
--data-binary @multipart_body.txt.gz
```

## Size Limits

Event ingestion imposes limits on the size and number of fields in multipart
Expand Down
Loading