Breakpad

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 Slack and Spotify. 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 minidumps. 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.

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.

Note: 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<string, string> &parameters,
                          const map<string, string> &files,
                          const string &proxy, const string &proxy_user_pwd, const string &ca_certificate_file, string *response_body,
                          long *response_code,
                          string *error_description);
...

Mac OSX

Note: We highly recommend using Crashpad on OSX

Objective-C

On Mac OSX, HTTPMultipartUpload() interface is provided for Objective-C users in src/common/mac/HTTPUploadMultipartUpload.m

@interface HTTPMultipartUpload : NSObject {
 @protected
  NSURL *url_;                  // The destination URL (STRONG)
  NSDictionary *parameters_;    // The key/value pairs for sending data (STRONG)
  NSMutableDictionary *files_;  // Dictionary of name/file-path (STRONG)
  NSString *boundary_;          // The boundary string (STRONG)
  NSHTTPURLResponse *response_; // The response from the send (STRONG)
}

Otherwise, google_breakpad::LaunchReporter() is provided as a mechanism to launch a child process to upload the generated minidump file.

// Launch the crash dump sender app.
// |reporter_executable_path| is the path to the sender executable.
// |config_file_path| is the path to the config 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

...
  // 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 <input type="file">.
  // 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).
  static bool SendRequest(const wstring &url,
                          const map<wstring, wstring> &parameters,
                          const map<wstring, wstring> &files,
                          int *timeout,
                          wstring *response_body,
                          int *response_code);
...

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

https://team.sp.backtrace.io:6098/post?format=minidump&token=7c102b2432f6c57eb879db2008820a88031fefc08d8e7faccabc23a917e7db08

Adding 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:

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.

Note: 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();

Sample

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;

        // See above for the URL section for how to generate the proper url for your server
        std::string url("http://yourcompany.sp.backtrace.io:6097/post?format=minidump&token=57f2126dcef18bb0d2af35ec1d813f3775ee8228d1d886de522b2aedceff8b87");

        // Add any attributes to the parameters map.
        // Attributes such as uname.sysname, uname.version, cpu.count are
        // extracted from minidump files automatically.
        parameters["product_name"] = "foo";
        parameters["version"] = "0.1.0";
        // parameters["uptime"] uptime_sec;

        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 symbolification guide.