Crashpad
Overview
Crashpad is the latest open-source crash reporting tool built by Google and is the successor to the popular Breakpad crash reporter. Crashpad allows you to submit minidumps to a configured URL after a crash occurs in your product. The official Crashpad documentation is available here.
Tutorial
To begin, download and unzip the BugSplat Crashpad software development kit. The download contains a sample Crashpad application and a compiled version of Crashpad for Windows.
It's also possible to download and build Crashpad yourself. This step is required if you are targeting an OS other than Windows. See our Building Crashpad doc for our a step-by-step guide to building Crashpad.
To get a feel for the BugSplat service before enabling your application, experiment with the myCrashpadCrasher sample application. You can find the Visual Studio project file located in your download folder at
...\BugSplatCrashpad\BugSplat\samples\myCrashpadCrasher\myCrashpadCrasher.vcxproj.Run the sample application without the debugger attached to post a crash report to our public "[email protected]" database. To view the report, log in to the public database using the account "[email protected]" and the password "Flintstone".
Integrating Crashpad
Follow the myCrashpadCrasher pattern to enable Crashpad in your application.
Step 1
Add the following includes:
1
#include "client/crashpad_client.h"
2
#include "client/crash_report_database.h"
3
#include "client/settings.h"
Copied!
Step 2
Copy the
initializeCrashpad and GetCrashpadHandlerPath methods from the BugSplat sample. The Crashpad url and parameters format, database, product and version are required to successfully upload crash reports to BugSplat. You can optionally specify values for the parameters user, list_annotations, and key which will be tracked with each crash report.1
CrashpadClient *initializeCrashpad(char *dbName, char *appName, char *appVersion)
2
{
3
// Get directory where the crashpad_handler.exe file lives, sample implementation of this method is provided in the myCrashpadCrasher sample
4
std::wstring handlerPath = GetCrashpadHandlerPath();
5
6
if (INVALID_FILE_ATTRIBUTES == GetFileAttributesW(handlerPath.c_str()))
7
{
8
return NULL;
9
}
10
11
// Ensure that handler is shipped with your application
12
base::FilePath handler(handlerPath);
13
14
// Directory where reports will be saved. Important! Must be writable or crashpad_handler will crash.
15
base::FilePath reportsDir(L"./crashpad");
16
17
// Directory where metrics will be saved. Important! Must be writable or crashpad_handler will crash.
18
base::FilePath metricsDir(L"./crashpad");
19
20
// Configure url with your BugSplat database
21
std::string url;
22
url = "https://";
23
url += dbName;
24
url += ".bugsplat.com/post/bp/crash/crashpad.php";
25
26
// Metadata that will be posted to BugSplat
27
std::map<std::string, std::string> annotations;
28
annotations["format"] = "minidump"; // Required: Crashpad setting to save crash as a minidump
29
annotations["database"].assign(dbName); // Required: BugSplat database
30
annotations["product"].assign(appName); // Required: BugSplat application name
31
annotations["version"].assign(appVersion); // Required: BugSplat version number
32
annotations["key"] = "Sample key"; // Optional: BugSplat key field
33
annotations["user"] = "[email protected]"; // Optional: BugSplat user email
34
annotations["list_annotations"] = "Sample comment"; // Optional: BugSplat crash description
35
36
// Disable crashpad rate limiting so that all crashes have dmp files
37
std::vector<std::string> arguments;
38
arguments.push_back("--no-rate-limit");
39
40
// Initialize crashpad database
41
std::unique_ptr<CrashReportDatabase> database = crashpad::CrashReportDatabase::Initialize(reportsDir);
42
if (database == NULL) return false;
43
44
// Enable automated crash uploads
45
Settings *settings = database->GetSettings();
46
if (settings == NULL) return false;
47
settings->SetUploadsEnabled(true);
48
49
// Files to upload with the crash report - default bundle size limit is 20MB
50
std::vector<base::FilePath> attachments;
51
base::FilePath attachment(L"./attachment.txt");
52
attachments.push_back(attachment);
53
54
// Start crash handler
55
CrashpadClient *client = new CrashpadClient();
56
bool status = client->StartHandler(handler, reportsDir, metricsDir, url, annotations, arguments, true, true, attachments);
57
if (status == false) return NULL;
58
59
// Wait for handler to initialize
60
status = client->WaitForHandlerStart(INFINITE);
61
if (status == false) return NULL;
62
63
return client;
64
}
Copied!
Step 3
Call
initializeCrashpad using your own parameters for the BugSplat dbName, appName, and appVersion.1
char *dbName = (char *)"fred";
2
char *appName = (char *)"myCrashpadCrasher";
3
char *appVersion = (char *)"1.0";
4
5
initializeCrashpad(dbName, appName, appVersion);
Copied!
Step 4
Link your application with the appropriate version of the Crashpad libraries
client.lib, base.lib, andutil.lib. BugSplat supplies builds for Debug/Release (x86) and Debug_x64/Release_x64 versions of the Crashpad libraries.Step 5
Upload symbols for your application to generate symbolic call stacks. Our sample project uses the BugSplat
SendPdbs utility to upload .exe, .dll and .pdb files. This is the preferred approach for Windows products. Additional information can be found on our SendPdbs page.Step 6
BugSplat also supports symbol files using the Crashpad
.sym file format. This format is required for platforms other than Windows. To upload your application's .sym files manually please see this doc. Alternatively, you can use the Breakpad symupload utility to automate the symbol upload process. Run the following command replacing {database}, {appName} and {appVersion} with values specific to your BugSplat database and symbol store.Ensure the
pathandurlare wrapped in double quotes when usingsymupload1
symupload "file.sym" "https://{database}.bugsplat.com/post/bp/symbol/breakpadsymbols.php?appName={appName}&appVer={appVersion}"
Copied!
Step 7
Trigger a crash in your application. The crash report should be available immediately on the BugSplat website.
Additional Considerations
Databases
The BugSplat database for your crash reports is created on the Manage Database page in Settings. Typically you will create a new database for each major release of your product.
Optimizations
Compiler optimizations can cause a mismatch between the line numbers in crash reports and the actual line numbers in your code. BugSplat recommends turning off compiler optimizations to ensure that the line numbers in your crash reports match the line numbers in your code. To turn off optimizations in Visual Studio, right click your project and navigate to Properties > C/C++ > Optimization > Optimization and set the value to Disabled (/Od).
Processing as Windows Native
BugSplat can process Crashpad crashes reported from Windows operating systems with our Windows backend, rather than the Breakpad backend. The advantage of this approach is that BugSplat will be able to automatically resolve Windows OS symbols.
To configure your Breakpad crashes to be processed by our Windows backend, create unique AppName/AppVersion combinations for the Windows versions of your application and upload
.pdb, .dll and .exe files (rather than .sym files). The presence of .pdb, .dll or .exe 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 our automated tool SendPdbs.Last modified 1mo ago