breakpad/docs/linux_starter_guide.md

How To Add Breakpad To Your Linux Application

This document is an overview of using the Breakpad client libraries on Linux.

Building the Breakpad libraries

Breakpad provides an Autotools build system that will build both the Linux client libraries and the processor libraries. Running ./configure && make in the Breakpad source directory will produce src/client/linux/libbreakpad_client.a, which contains all the code necessary to produce minidumps from an application.

Integrating Breakpad into your Application

First, configure your build process to link libbreakpad_client.a into your binary, and set your include paths to include the src directory in the google-breakpad source tree. Next, include the exception handler header:

#include "client/linux/handler/exception_handler.h"

Now you can instantiate an ExceptionHandler object. Exception handling is active for the lifetime of the ExceptionHandler object, so you should instantiate it as early as possible in your application's startup process, and keep it alive for as close to shutdown as possible. To do anything useful, the ExceptionHandler constructor requires a path where it can write minidumps, as well as a callback function to receive information about minidumps that were written:

static bool dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor,
void* context, bool succeeded) {
  printf("Dump path: %s\n", descriptor.path());
  return succeeded;
}

void crash() { volatile int* a = (int*)(NULL); *a = 1; }

int main(int argc, char* argv[]) {
  google_breakpad::MinidumpDescriptor descriptor("/tmp");
  google_breakpad::ExceptionHandler eh(descriptor, NULL, dumpCallback, NULL, true, -1);
  crash();
  return 0;
}

Compiling and running this example should produce a minidump file in /tmp, and it should print the minidump filename before exiting. You can read more about the other parameters to the ExceptionHandler constructor in the exception_handler.h source file.

Note: You should do as little work as possible in the callback function. Your application is in an unsafe state. It may not be safe to allocate memory or call functions from other shared libraries. The safest thing to do is fork and exec a new process to do any work you need to do. If you must do some work in the callback, the Breakpad source contains some simple reimplementations of libc functions, to avoid calling directly into libc, as well as a header file for making Linux system calls (in src/third_party/lss) to avoid calling into other shared libraries.

Sending the minidump file

In a real application, you would want to handle the minidump in some way, likely by sending it to a server for analysis. The Breakpad source tree contains some HTTP upload source that you might find useful, as well as a minidump upload tool.

Producing symbols for your application

To produce useful stack traces, Breakpad requires you to convert the debugging symbols in your binaries to text-format symbol files. First, ensure that you've compiled your binaries with -g to include debugging symbols. Next, compile the dump_syms tool by running configure && make in the Breakpad source directory. Next, run dump_syms on your binaries to produce the text-format symbols. For example, if your main binary was named test:

$ google-breakpad/src/tools/linux/dump_syms/dump_syms ./test > test.sym

In order to use these symbols with the minidump_stackwalk tool, you will need to place them in a specific directory structure. The first line of the symbol file contains the information you need to produce this directory structure, for example (your output will vary):

$ head -n1 test.sym MODULE Linux x86_64 6EDC6ACDB282125843FD59DA9C81BD830 test
$ mkdir -p ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830
$ mv test.sym ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830

You may also find the symbolstore.py script in the Mozilla repository useful, as it encapsulates these steps.

Processing the minidump to produce a stack trace

Breakpad includes a tool called minidump_stackwalk which can take a minidump plus its corresponding text-format symbols and produce a symbolized stacktrace. It should be in the google-breakpad/src/processor directory if you compiled the Breakpad source using the directions above. Simply pass it the minidump and the symbol path as commandline parameters:

$ google-breakpad/src/processor/minidump_stackwalk minidump.dmp ./symbols

It produces verbose output on stderr, and the stacktrace on stdout, so you may want to redirect stderr.