Installation

Breakpad is a library and tool suite that allows you to distribute an application to users with compiler-provided debugging information removed, record crashes in compact "minidump" files, send them back to your server, and produce C and C++ stack traces from these minidumps.

See the Git repository for more information on Google Breakpad

Step 1 - Installation

Clone the GitHub repository https://github.com/google/breakpad and link the following directories for your platform to your project:

• breakpad/src/client/{platform}
• breakpad/src/client/*.h
• breakpad/src/client/*.cc
• breakpad/src/common/{platform}
• breakpad/src/common/*.h
• breakpad/src/common/*.cc

Step 2 - Configure Breakpad

You need to enable Breakpad in your application by instantiating the ExceptionHandler object and passing it the directory path (_dump_path_) where minidump files will be written to.

#include "exception_handler.h"

google_breakpad::ExceptionHandler *pHandler = new google_breakpad::ExceptionHandler(L"_dump_path_", 0, minidump_callback, 0, google_breakpad::ExceptionHandler::HANDLER_ALL, MiniDumpNormal, L"", 0);

Step 3 - Configure Raygun

Define a callback for when minidumps have been written and use the CrashReportSender class to post minidump files to Raygun.

#include "crash_report_sender.h"

bool minidump_callback(const wchar_t* dump_path, const wchar_t* minidump_id, void* context, EXCEPTION_POINTERS* exinfo, MDRawAssertionInfo* assertion, bool succeeded)

{
google_breakpad::CrashReportSender sender(L"crash.checkpoint");

std::wstring filename = L"_dump_path_";
filename += L"\\";
filename += minidump_id;
filename += L".dmp";

std::map<std::wstring, std::wstring> files;
files.insert(std::make_pair(filename, filename));

// At this point you may include custom data to be part of the crash report.
std::map<std::wstring, std::wstring> userCustomData;
userCustomData.insert(std::make_pair(L"desc", L"Hello World"));

sender.SendCrashReport(L"https://api.raygun.com/entries/breakpad?apikey=paste_your_api_key_here", userCustomData, files, 0);

return true;
}

Release

Deploy Raygun into your production environment for best results, or raise a test exception. Once we detect your first error event, the Raygun app will automatically update.

To upload application symbols, please see the uploading application symbols step in our documentation.

Upload application symbols

We provide the ability to for you to upload your application symbols in the form of PDB files or Breakpad's SYM files. After you have uploaded the symbols, any minidumps processed will use these symbols for symbolicating their stack trace.

1. Inside your Raygun dashboard, navigate to the 'Application settings' in the left hand side menu. Then select 'Symbol center' that appears below:

   

2. Drag and drop a "Release" mode PDB or previously generated Breakpad symbol file. Or click the blue button to select a file to import to the Symbol center. You can use the Breakpad tooling as part of your build toolchain to generate the symbol files yourself.

We also provide support for uploading individual PDB or SYM files automatically as part of your build or deployment process. This can be done by using cURL. For example:

Basic authentication

curl -L
  -H "Host: app.raygun.com"
  -H "Authorization: Basic ${BASIC_AUTH_TOKEN}"
  -F "SymbolFile=@${PDB or SYM filepath}"
  https://app.raygun.com/upload/breakpadsymbols/${APP_ID}

• BASIC_AUTH_TOKEN should be replaced with a basic auth token which can be created by Base64 encoding your Raygun account credentials in the following format (make sure not to forget the colon between them): username:password. We recommend having a separate user account with a strong password for managing this access.
• APP_ID is available in the URL of your app in the Raygun dashboard.

External access token

curl -L
  -H "Host: app.raygun.com"
  -F "SymbolFile=@${PDB or SYM filepath}"
  https://app.raygun.com/upload/breakpadsymbols/${APP_ID}?authToken=${EXTERNAL_ACCESS_TOKEN}

• EXTERNAL_ACCESS_TOKEN can be obtained from Raygun by clicking your name in the top right corner, select "My settings" and then hit "Generate external access token" or copy it if you already have one.
• APP_ID is available in the URL of your app in the Raygun dashboard.

Additional options

If the upload is clearly not working, add the verbose option to get more information about what's wrong.

-v

Note: At this time we do not support uploading zip files, each SYM file will need to be uploaded separately.

Possible results

200 if the upload was successul.

302 if you don't provide any form of authentication.

401 if credentials are incorrect, or you don't have access to the application.

404 if the URL or app id is incorrect.

curl (26) if the path to the SYM or PDB file is incorrect.