Perhaps you are have a pre-existing crash reporting facility or are generating dump files using MiniDumpWriteDump on Windows, this guide shows you how to submit these over HTTP or HTTPS. If you are using a supported crash reporting library, please use their preferred submission mechanisms.
Ensure submission token exists
First step is to ensure you have a submission token created. Learn more about submission tokens in the product guide.
Ensure listener exists
Next step is to ensure that a listener exists for submitting crash data. Look for listeners with the http/writer
label. Listener settings are found under the Configuration Organization
menu item.
In the above example, if the server is hosted at testing.company.com
, then we are able to submit dump files to either http://testing.company.com:6097/post or https://testing.company.com:6098/post. These are the first two entries in the above screenshot, with the http/writer
labels.
Note on curl usage
For large files, include the header flag -H "Expect:"
to override some default curl
behavior which can cause issues when uploading to Backtrace. The examples below include this flag.
Submit a dump file
For this example, let us assume that our submission token is 7e7f38ea321471dfdf76adad1bd101c4ec1010dd6eee113d347f6137179ed9c3
and that the http/writer
end-point is https://testing.company.com:6098/post
.
An HTTP POST is used to submit a dump file. See below for an example curl
invocation.
curl -v --data-binary @example_minidump.dmp -H "Expect:" "https://testing.company.com:6098/post?format=minidump&token=7e7f38ea321471dfdf76adad1bd101c4ec1010dd6eee113d347f6137179ed9c3"
Both the token
and format
parameters are required in order for the dump to be submitted.
Attaching Attributes
User-defined attributes can also be passed as additional query string parameters. For example, let's say that we wanted to submit a minidump and set the version
attribute associated with it to 1.0
.
curl -v --data-binary @example_minidump.dmp -H "Expect:" "https://testing.company.com:6098/post?format=minidump&token=7e7f38ea321471dfdf76adad1bd101c4ec1010dd6eee113d347f6137179ed9c3&version=1.0"
For more information on attributes, see the product guide.
Attaching Files
User-supplied files can be passed in multipart post requests. The multipart form must begin with the minidump, and any attachment parts must have a name starting with "attachment_" and ending in the desired name of the attachment. For example, say we want to attach a configuration JSON named config.json
:
curl -v -F "upload_file=@example_minidump.dmp" -H "Expect:" -F "attachment_config.json=@config.json; type=application/json" "https://testing.company.com:6098/post?format=minidump&token=7e7f38ea321471dfdf76adad1bd101c4ec1010dd6eee113d347f6137179ed9c3"
Alternatively, attachments can be submitted afterwards using standard POST, in this case to object 5:
curl -v --data-binary @config.json -H "Expect:" -H "Content-Type:application/json" "https://testing.company.com:6098/post?token=7e7f38ea321471dfdf76adad1bd101c4ec1010dd6eee113d347f6137179ed9c3object=5&attachment_name=config.json"
Note that curl
requires explicitly specifying the Content-Type for attachments, as demonstrated, but a custom client can omit this parameter. In this case, the server will automatically determine the Content-Type based on the attachment's name.
Receive Layer
It is also possible to use the https://submit.backtrace.io receive layer to submit dumps. This is preferred to use over port 6098 for better quality of service. This is only an option for hosted customers. For on-premise, it is possible to customize listeners.
The POST URL is in the following format:
https://submit.backtrace.io/<universe>/<token>/<format>
The token is the submission token. Universe is your tenant name. For example, if your instance is X.sp.backtrace.io
then the universe component is called X
.
Here is an example of submitting a minidump for the backtrace
universe with token:
fd143f0d607b492a1835f3e67dab0dd240dc6976d9ba9de849fe8e1fdf187fb2
The following CURL command is used:
curl -v --data-binary @file.dmp -H "Expect:" "https://submit.backtrace.io/backtrace/fd143f0d607b492a1835f3e67dab0dd240dc6976d9ba9de849fe8e1fdf187fb2/minidump"