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 are Windows and Visual Studio, look ahead to the Visual Studio section to for a step-by-step guide to integrating into Visual Studio.

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/. The URL needs to have a proper canonical form (the trailing slash shall not be omitted), as the Windows Crashpad uploader uses WinHttpCrackUrl internally.

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 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 in the product guide.

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. Preferably, 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.

Visual Studio

Obtain Crashpad

You can build Crashpad from source or download Backtrace-provided versions of the library.

Build from source

It is always possible to build Crashpad from source. In order to do this, please see the build guide on the Crashpad website. Backtrace's branch is available here.

Download built libraries

Backtrace provides updated builds of Crashpad. It is recommended to use the latest version to take advantage of the latest improvements in Crashpad. These archives contain the complete source archive of the snapshot to make it easier to manage in-place updates.

The latest release of Crashpad is available at http://get.backtrace.io/crashpad/builds/.

The stable debug-x86 has a checksum of 9cbd08e06e721be93f78580a8f56b2db3196c451d41d5f8ef1564a78a355759b
The stable debug-x86-64 has a checksum of af0eb7277b8fa1f9190d1b77e8944b052075500b8a8d5e0298fa854b8d9cb14d
The stable release-x86 has a checksum of f42df71153422e2870cd8a1411b908ed0caa494a2abe6e6d44eda60478149a14
The stable release-x86-64 has a checksum of ea97da8dccdced8717d340244c667d3beabc3a26b6029ea706db962905ef3c6b 

Integrate Crashpad

Once you have built Crashpad or download the pre-built libraries, you will now need to integrate the library into your application. The library is statically linked into your project, so you will not need to distribute any additional projects.

There are two versions of Crashpad provided in the Backtrace archive.

lib_mt contains the crashpad libraries built with the /MT  switch for static linking. lib_md contains the crashpad libraries built with the /MD swtich for dynamic linking.

Use the appropriate version for your application.

Integrate into your build process

This section outlines how to import the Crashpad library into your Visual Studio project.

Add the header files

First, you'll need to add the Crashpad directory in the include path for your application. The header files for Crashpad in the provided .zip file are in the include directory.

Go to the project configuration menu (Project > Properties > VC++ Directories) and set Include Directories to point to the include  and include\mini_chromium  folders of the extracted archive.

Add the libraries

Static Linking

Now, you'll need to add the relevant release path (see the table above) to your Library Directories(Project > Properties > VC++ Directories). For example, if I am deploying a 32-bit Windows application, then after downloading the appropriate crashpad build, the lib_mt sub-directory is added to Library Directories.

Once that is done, you'll need to add the actual set of static libraries for Crashpad. Navigate to your linker input settings (Project > Properties > Linker > Input), and add crashpad_client.lib;crashpad_util.lib;mini_chroumium_base.lib  as an additional dependencies. See the screenshot below for an example.

Remember to use the build of the Crashpad library that corresponds with your build configuration. For example, if you are building a 32-bit Debug build, then ensure that you are referencing the .lib files from the debug build. If you encounter errors involving ITERATOR_DEBUG_LEVEL, then there is likely a mismatch between your build configuration and the build of Crashpad. In order to change the build settings, go to Build > Configuration Manager then change your Active solution configuration.

Dynamic Linking

If you are using dynamic linking (the \MD flag), then make sure to use the lib_md sub-directory rather than lib_mt. For example, crashpad\lib_md rather than crashpad\lib_mt.

Verify Linker Settings

Static Linking

Last but not least, ensure that you have code generation runtime settings set to a mode compatible with static libraries, such as Multi-threaded (/MT). Go to Project > Properties > C/C++ > Code Generationand update the  Runtime Library setting.

Dynamic Linking

If you are using dynamic linking, then ensure that you use the /MD option instead of /MT.

Ensure symbol generation

It is required to upload symbols into Backtrace for intelligent deduplication and classification. This section explains how to enable debug symbols for your application.

Go to Project > Properties > Linker and update the Generate Debug Info setting. You'll want to set it to either Generate Debug Information (/DEBUG) orGenerate Debug Information optimized for sharing and publishing (/DEBUG:FULL). The /DEBUGoption is recommended if you would like to avoid the possibility of a performance impact.

With this setting, a .pdb file will be generated for your application in the build output directory. You are able to upload .sym, .pdb and archive files containing .pdb or .sym files into Backtrace manually or through the command line. It is also possible to hook up Visual Studio to automatically upload symbols as they are generated. You should be good to send crash reports at this point. Simply ensure that you've uploaded your symbols (click on Symbols tab under the Project Configuration page).

For more details, please refer to the symbolification guide.

Send crash reports

Congratulations, now you're ready to integrate Crashpad into your application. In order to do this, you'll need to add the following to your source-code.

#include "client/crashpad_client.h"

using namespace crashpad;

Once that's done, it's time to initialize the Crashpad library. For this, you will use the crashpad::CrashpadClient::StartHandler function as defined below.

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
)

handler is a path to an external program responsible for generating and uploading dumps. This is the recommended for uploading crashes as it's reliable. Look for bin/crashpad_handler.exe, which is suitable as a default crash handler. See below for a complete example.

For applications deployed to customers, the handler executable should be bundled with the application, and the path should be a relative one to the application binary.

[...]

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

using namespace crashpad;

[...]

static bool
startCrashHandler()
{
    CrashpadClient client;
    bool rc;

    std::map<std::string, std::string> annotations;
    std::vector<std::string> arguments;

    /*
     * 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.
     * Preferably, 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;
}

Enable automated crash upload

If you haven't done so with the Crashpad API, enable automated upload of crashes with crashpad_database_util. On Windows, for example:

C:\Project>crashpad_database_util.exe -d C:\my_crash_repo --set-uploads-enabled=TRUE

Finish

At this point, crashes should be automatically submitted into Backtrace. As crashes generate, refresh the Project page of the associated project to see faults in real-time.

Windows 7, Windows Server 2008 R2 and Windows Server 2012 support (adding TLS 1.1/1.2 support)

The default Crashpad crash handler binary uses WinHttp to upload crashes. On those systems, TLS 1.1 and TLS 1.2 are in the default protocol set, and only TLS 1.0, and SSL 3.0 are available by default, which are not accepted by Backtrace.

This should be fixed by KB 3140245, but you may want to add them to the default list manually via the registry. We suggest doing it in your application installer.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp]
"DefaultSecureProtocols"=dword:00000a00

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.

Did this answer your question?