Minidumps
Learn about how Sentry processes Minidump crash reports.
Sentry can process Minidump crash reports, a memory dump used on Windows and by open-source libraries like Breakpad or Crashpad.
This page describes standalone usage of Minidumps with Sentry. We strongly encourage you to use our Native SDK, as Minidumps uploads are very limited in functionality.
In order to receive symbolicated stack traces, you have to upload debug information to Sentry. For more information, see Debug Information Files.
Minidumps are files containing the most important memory regions of a crashed process. When the process crashes, the minidump is written to the user's disk and can later be uploaded to Sentry. A minidump typically includes:
- The runtime stack of each thread that was active during the time of the crash. This allows you to reconstruct stack traces for all stacks and even infer variable values in some cases.
- Thread contexts -- that is, register values -- at the time of the crash. This is especially relevant for stack walking.
- Optionally, the process heap. By default, this is not included to keep minidumps at a reasonable size. Sentry does not read the heap so that it can be safely omitted.
- The crash reason and an optional memory address associated to with the crash. For example, memory access violations. In the case of assertions, the assertion message is also included in the dump.
- Meta data about the CPU architecture and the user’s operating system.
A Word on Data Privacy
Minidumps are memory dumps of the process at the moment it crashes. As such, they might contain sensitive information on the target system, such as environment variables, local pathnames or maybe even in-memory representations of input fields, including passwords. Sentry does not store these memory dumps. Once processed, they are removed immediately, and all sensitive information is stripped from the resulting issues.
In addition to this information, you can add further metadata specific to Sentry, which can help in organizing and analyzing issues. For more information, see Passing Additional Data.
Depending on your operating system and programming language, there are various alternatives to create minidumps and upload them to Sentry. See the following resources for libraries that support generating minidump crash reports:
If you have already integrated a library that generates minidumps and would just like to upload them to Sentry, you need to configure the Minidump Endpoint URL, which can be found at Project Settings > Client Keys (DSN). This endpoint expects a POST
request with the minidump in the upload_file_minidump
field:
curl -X POST \
'https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey' \
-F upload_file_minidump=@mini.dmp
To send additional information, add more form fields to this request. For a full description of fields accepted by Sentry, see Passing Additional Data.
You can add more information to crash reports by merely adding more fields to the upload HTTP request. All these fields will be collected in the “Extra Data” section in Sentry:
curl -X POST \
'https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey' \
-F upload_file_minidump=@mini.dmp \
-F custom_field=value
Additionally, you can set all attributes corresponding to the Sentry event interface in a sentry
field. This field either accepts JSON data or its values can be flattened with the bracket syntax. For example, to set the release and add a tag, send:
# As JSON
curl -X POST \
'https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey' \
-F upload_file_minidump=@mini.dmp \
-F 'sentry={"release":"my-project-name@2.3.12","tags":{"mytag":"value"}}'
# flattened
curl -X POST \
'https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey' \
-F upload_file_minidump=@mini.dmp \
-F 'sentry[release]=my-project-name@2.3.12' \
-F 'sentry[tags][mytag]=value'
For the full list of supported values, see Event Payloads and linked documents.
You can compress your minidump using gzip
if its size exceeds the limits in the next section.
In this case, you would POST
the minidump as a gzip-encoded binary:
gzip mini.dmp
curl -X POST \
'https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey' \
-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 cannot easily pass additional data as fields as in the previous section's examples.
In that case, you must construct the multipart content manually and compress it as a whole:
# 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
# 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 \
'https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey' \
-H 'Content-Type: multipart/form-data; boundary=boundary_minidumpXYZ' \
-H 'Content-Encoding: gzip' \
--data-binary @multipart_body.txt.gz
Event ingestion imposes limits on the size and number of fields in multipart uploads. These limits are subject to future change and defined currently as:
- 20MB for a compressed minidump request
- 100MB for the full body after decompression
- 100MB for all files combined
- 100MB for each file individually
- 1MB for event payloads
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").