Breakpad is an open-source library initially developed by Google for cross-platform C/C++ crash reporting. It is used in popular software such as Google Chrome, and by companies such as Valve. For existing users of Breakpad, Backtrace has plug-and-play support.
Initial Integration
If you have yet to integrate Breakpad into your application, we recommend you integrate Crashpad instead. Crashpad is the successor to Breakpad with many improvements and up-to-date integration instructions.
Breakpad's official integration instructions can be found here. If you would like additional assistance, you can reach out to us at support@backtrace.io
Upload Methods
The rest of this guide assumes that you have Breakpad integrated into your application and are able to generate minidump files. Please see Breakpad's official integration instructions to get to this point.
The method to upload Breakpad crash reports in your application differs across operating systems.
- Linux
- Mac OS
- Windows
Have your own method to upload generated minidumps? Skip ahead to Upload Settings.
Linux
On Linux, google_breakpad::HTTPUpload::SendRequest() can be used to upload generated minidumps to Backtrace. This method's declaration is found in src/common/linux/http_upload.h.
There are other convenience methods provided for Linux users of Breakpad but HTTPUpload::SendRequest() is recommended for use with Backtrace.
static bool SendRequest(const string &url,
const map
Mac OS
For crash reporting on Mac OS, we highly recommend using Crashpad
On Mac OS, HTTPMultipartUpload() interface is provided for Objective-C users in:
src/common/mac/HTTPUploadMultipartUpload.m
@interface HTTPMultipartUpload : NSObject {
@protected
NSURL *url_; // Submission URL (STRONG)
NSDictionary *parameters_; // Crash attributes (STRONG)
NSMutableDictionary *files_; // Files to send (STRONG)
NSString *boundary_; // The boundary string (STRONG)
NSHTTPURLResponse *response_; // Server reponse (STRONG)
}
Otherwise, google_breakpad::LaunchReporter() is provided as a mechanism to launch a child process to upload the generated minidump file.
void LaunchReporter(const char *reporter_executable_path,
const char *config_file_path);
Windows
On Windows, google_breakpad::HTTPUpload::SendRequest() can be used to upload generated minidumps to Backtrace. This method's declaration can be found in src/common/windows/http_upload.h
static bool SendRequest(const wstring &url,
const map
Sends the given sets of parameters and files as a multipart POST request to the given URL. Each key in |files| is the name of the file part of the request (i.e. it corresponds to the name=attribute on an .
Parameter names must contain only printable ASCII characters, and may not contain a quote character. Only HTTP(S) URLs are currently supported. Returns true on success. If the request is successful and response_body is non-NULL, the response body will be returned in response_body. If response_code is non-NULL, it will be set to the HTTP response code received (or 0 if the request failed before getting an HTTP response).
Settings
Once you have a method set in place to upload generated minidumps, you can now configure your upload settings to send data to Backtrace.
URL
Change the url parameter in your call to point to your server dump submission port (labeled as http/writer in the listener configuration pane). Preferably, the SSL enabled port should be used. If Backtrace is hosting your instance, the default port will be 6098.
The URL parameter for the methods above follow the format:
<protocol>://<instance_url>:<port>/post?format=minidump&token=<project_token>
Instructions on retrieving your project token can be found here.
For example, if Backtrace is hosting your instance at team.sp.backtrace.io and your project token is 7c102b2432f6c57eb879db2008820a88031fefc08d8e7faccabc23a917e7db08 then set the url argument to:
Attributes
The parameters parameter specifies a set of key-value pairs that map directly to Backtrace's flexible key-value attribute system. Backtrace's key-value attribute system can be used in searches and can be represented visually in graphical form.
Some example attributes are:
- application
- version
- client_id/hostname
- resolution
- operating_system
Parameters must contain only printable ASCII characters and may not contain a quote " character. In order to have your attributes searchable by the Backtrace object store, please refer to the product guide.
The methods above all use a multipart POST request. Parameters are pushed as input forms.
File Path
The files parameter is used to specify a set of names and file paths that the method will upload.
Set the upload_file_minidump key to the path of the generated minidump. The path of the generated minidump can be retrieved from google_breakpad::MinidumpDescriptorparameter in your google_breakpad::ExceptionHandler() callback function.
files["upload_file_minidump"] = descriptor.path();
Example
The following code example demonstrates how to upload Breakpad reports from your application on a Linux system.
#include <breakpad/client/linux/handler/exception_handler.h>
#include "common/linux/http_upload.h"
static bool
dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor,
void* context, bool succeeded)
{
(void) context;
if (succeeded == true) {
std::map<string, string> parameters;
std::map<string, string> files;
std::string proxy_host;
std::string proxy_userpasswd;
std::string url("http://yourcompany.sp.backtrace.io:6097/post?format=minidump&token=57f2126dcef18bb0d2af35ec1d813f3775ee8228d1d886de522b2aedceff8b87");
// Add any attributes to the parameters map.
// Note that several attributes are automatically extracted.
parameters["product_name"] = "foo";
parameters["version"] = "0.1.0";
files["upload_file_minidump"] = descriptor.path();
std::string response, error;
bool success = HTTPUpload::SendRequest(url,
parameters,
files,
proxy_host,
proxy_userpasswd,
"",
&response,
NULL,
&error);
}
return succeeded;
}Manage Symbols
Symbols must be uploaded to have Backtrace determine source-code mapping of incoming crashes, including source file and line number. In order for Backtrace to effectively group and analyze your incoming crashes, you must provide application debug symbols.
To learn more about how to upload and manage symbols with Backtrace, please see the symbolication guide.