Crashpad

Crashpad is an open-source library initially developed by Google as a successor to the Google Breakpad library. It is used in popular software such as Google Chrome, and by companies such as Slack and Spotify. For existing users of Crashpad, Backtrace has plug-and-play support. It has a robust architecture designed to allow for a high degree of customizability and stability even in the face of most obscure of software crashes.

Initial Integration

If you have yet to integrate crashpad into your application, see below for integration guides for different environments.


Advanced instructions are available at the Crashpad home page if you can't find what you're looking for or prefer to build Crashpad from source. If you would like additional assistance, please don't hesitate to contact support@backtrace.io.

Update your application

Once Crashpad has been integrated into your application, you'll need to specify the right options to crashpad::CrashpadClient::StartHandler. For more advanced information on StartHandler, please refer to the documentation linked here.

bool crashpad::CrashpadClient::StartHandler(const base::FilePath &handler,
    const base::FilePath &database,
    const base::FilePath &metrics_dir,
    const std::string &url,
    const std::map<std::string, std::string> &annotations,
    const std::vector<std::string> &arguments,
    bool restartable,
    bool asynchronous_start 
)

Set the URL parameter

Change the url parameter to crashpad::CrashpadClient::StartHandler to point to your server dump submission port (labeled as http/writer in the listener configuration pane). Preferrably, the SSL enabled port should be used. If Backtrace is hosting your instance, the default port is 6098.

For example, if Backtrace is hosting your instance at team.sp.backtrace.io, then set the url argument to https://team.sp.backtrace.io:6098.

Set annotations

Required Annotations

Two annotations are required to submit faults into Backtrace.

Set token, your submission token value. In the Backtrace user interface, your submission token is retrieved by clicking on the Token menu item in the project configuration page. For more details, please see this page. For example, if my token is b6dd361e5800babc23beb88c5797147c1a06dbe11bf096ed935b59ac42766ec3 and annotations is passed to StartHandler, then the following code suffices:

annotations["token"] = "b6dd361e5800babc23beb88c5797147c1a06dbe11bf096ed935b59ac42766ec3";

Set format to "minidump". Backtrace supports a myriad of dump formats. In order to have Backtrace recognize the incoming object as a minidump, the format annotation must be set.

annotations["format"] = "minidump";
Optional Annotations

The annotations map can also be used to set additional attributes. Attributes allow you to embed relevant context into each crash report and can be any data point of your choosing. Examples include version, directx.version, graphics.card, etc. More information on attributes can be found here

Example code

See below for self-contained example code. The following code is also applicable to macOS applications, just ensure the various file paths are valid.

[...]

#include "client/crashpad_client.h"
#include "client/crash_report_database.h"
#include "client/settings.h"

using namespace crashpad;

[...]

static bool
startCrashHandler()
{
    std::map<std::string, std::string> annotations;
    std::vector<std::string> arguments;
    CrashpadClient client;
    bool rc;

    /*
     * ENSURE THIS VALUE IS CORRECT.
     *
     * This is the directory you will use to store and queue crash data.
     */
    std::wstring db_path(L"my_app_dir\\Crashpad\\db");

    /*
     * ENSURE THIS VALUE IS CORRECT.
     *
     * Crashpad has the ability to support crashes both in-process and out-of-process.
     * The out-of-process handler is significantly more robust than traditional in-process
     * crash handlers. This path may be relative.
     */
    std::wstring handler_path(L"C:\crashpad_042817\\out\\Release\\bin\\crashpad_handler.exe");

    /*
     * YOU MUST CHANGE THIS VALUE.
     *
     * This should point to your server dump submission port (labeled as "http/writer"
     * in the listener configuration pane. Preferrably, the SSL enabled port should
     * be used. If Backtrace is hosting your instance, the default port is 6098.
     */
    std::string url("https://yourteam.sp.backtrace.io:6098");

    /*
     * YOU MUST CHANGE THIS VALUE.
     *
     * Set this to the submission token under the project page.
     * Learn more at https://documentation.backtrace.io/coronerd_setup/#tokens
     */
    annotations["token"] = "b6dd361e5800babc23beb88c5797147c1a06dbe11bf096ed935b59ac42766ec3";

    /*
     * THE FOLLOWING ANNOTATIONS MUST BE SET.
     *
     * Backtrace supports many file formats. Set format to minidump so it knows
     * how to process the incoming dump.
     */
    annotations["format"] = "minidump";

    /*
     * REMOVE THIS FOR ACTUAL BUILD.
     *
     * We disable crashpad rate limiting for this example.
     */
    arguments.push_back("--no-rate-limit");

    base::FilePath db(db_path);
    base::FilePath handler(handler_path);

    std::unique_ptr<CrashReportDatabase> database =
        crashpad::CrashReportDatabase::Initialize(db);

    if (database == nullptr || database->GetSettings() == NULL)
        return false;

    /* Enable automated uploads. */
    database->GetSettings()->SetUploadsEnabled(true);

    rc = client.StartHandler(handler,
        db,
        db,
        url,
        annotations,
        arguments,
        true,
        true);
    if (rc == false)
        return false;

    /* Optional, wait for Crashpad to initialize. */
    rc = client.WaitForHandlerStart(INFINITE);
    if (rc == false)
        return false;

    return true;
}

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.

Additional Documentation

Additional documentation is available at the Crashpad Website. For more information on the crashpad_handler, please see crashpad_handler.md.

If you're still encountering issues, contact us at support@backtrace.io.