Breakpad Breakpad logo for BugSplat

Summary


Breakpad is a set of client and server components which implement a crash-reporting system for Windows, OS X and Linux applications. In a few simple steps, your Breakpad-enabled application can be configured to send crash reports to BugSplat. For more information on Breakpad, see the Breakpad page.

Prerequisites


Before continuing with the integration please complete the following tasks:

  • Sign up for BugSplat
  • Create a new database for your application
  • Clone the Breakpad source
  • Build the Breakpad exception_handler and crash_report_sender libraries and integrate them into your application
  • Build the Breakpad dump_syms and symupload tools

Configuring Breakpad


  1. Configure Breakpad to post crashes to https://{database}.bugsplat.com/post/bp/crash/postBP.php. Be sure to specify your own value for the {database} portion of the URL, which corresponds to the BugSplat database used to store your crash reports.

    bool minidumpCallback(const wchar_t* dump_path,
      const wchar_t* minidump_id,
      void* context,
      EXCEPTION_POINTERS* exinfo,
      MDRawAssertionInfo* assertion,
      bool succeeded)
    {
      ...
      wstring bugSplatUrl = L"https://" + database + L".bugsplat.com/post/bp/crash/postBP.php";
      ...
      ReportResult reportResult = reportSender->SendCrashReport(bugSplatUrl, parameters, files, &exceptionCode);
      ...
    }
    

  2. Configure the Breakpad POST parameters prod for the BugSplat application name and ver for the BugSplat application version. You can optionally specify values for the Breakpad POST parameters email and comments, which will be tracked with each crash report. Also, configure the files parameter as shown below.

    bool minidumpCallback(const wchar_t* dump_path,
      const wchar_t* minidump_id,
      void* context,
      EXCEPTION_POINTERS* exinfo,
      MDRawAssertionInfo* assertion,
      bool succeeded)
    {
      ...
      map<wstring, wstring> parameters;
      parameters[L"prod"] = L"MyApp";
      parameters[L"ver"] = L"1.0";
      parameters[L"email"] = L"fred@bedrock.com";
      parameters[L"comments"] = L"BugSplat rocks!";
      files[L"upload_file_minidump"] = MinidumpDescriptor.path();
      ReportResult reportResult = reportSender->SendCrashReport(bugSplatUrl, parameters, files, &exceptionCode);
      ...
    }
    

  3. Create a new symbol store on our Symbols page. You should do this for each released version of your product in order to ensure your crash reports contain function names and line numbers.

  4. Use dump_syms to generate .sym files for your application. You will need to do this for each release version of your product.

  5. Upload your application's .sym files to BugSplat via the symupload tool, or via our manual symbol upload page. To view the manual symbol upload page, select one of your symbol stores on the Symbols page, then click the "Upload new symbol files" link. Alternatively you can use symupload to automate the symbol upload process. Run the following symupload command replacing {database}, {appName} and {appVersion} with values specific to your BugSplat database and symbol store:

    symupload file.sym "https://{database}.bugsplat.com/post/bp/symbol/breakpadsymbols.php?appName={appName}&appVer={appVersion}"

  6. Trigger a crash in your application. The following code snippet can be used to generate an EXCEPTION_ACCESS_VIOLATION_WRITE crash:

    int nullVal;
    void crash()
    {
      *(volatile int *)0 = nullVal;
    }
    

Additional Considerations


Breakpad crashes can be posted manaully using our test page at https://{database}.bugsplat.com/post/bp/crash/Native/index.php. Replace {database} with the name of your BugSplat database. Viewing the source HTML of that page may help with Breakpad configuration.

The BugSplat database for your crash reports is created on the Databases page. Typically you will create a new database for each major release of your product.

It's possible to have BugSplat process Breakpad crashes reported from Windows operating systems with our Windows backend, rather than the Breakpad backend. The advantage to this approach is that you will automatically resolve Windows OS symbols. To do this, create unique AppName/AppVersion combinations for the Windows versions of your application and upload .pdb files (rather than .sym files). The presense of .pdb files in the Symbol Store is what triggers the use of the Windows backend. Uploading Windows symbols can be done via our manual symbol upload page or via our automated tool SendPdbs.

If you are sending symbols from symupload on OS X there is no command line option to increase the upload timeout. We have created a fork of symupload with the timeout increased to 100 seconds (from 10 seconds). You will need to use a modified version of symupload to upload files larger than 100 MB. You can download the modified archive here.