Breakpad symbol upload

Upload Breakpad symbol files to allow BugSnag to symbolicate minidumps.

Overview

For minidump files (generated when using Electron, Breakpad or Crashpad) the stacktrace contains raw address details for each frame.

In order to see the original file, line and method BugSnag requires Breakpad symbol files for the relevant modules.

If your application uses native libraries (aside from Electron and its helper libraries), you will need to generate and upload symbol files for each library and platform supported to see full stack traces for native crashes.

Generating symbol files

To be able to generate symbol files, firstly download the Breakpad source code (GitHub mirror) and then build the dump_syms tool in the src/tools/{platform} directory.

Run the built dump_syms tool with a path to the native library or generated symbol files. Generated symbol files include *.pdb files on Windows and LLVM debug symbol maps (*.dSYM/**/DWARF/*) files on macOS.

You will need to generate symbol files for each of your native libraries on each of the platforms that you support, including for different CPU architectures.

Linux example

<path/to/dump_syms> <path/to/my/lib> > mylib.sym

macOS example

<path/to/dump_syms> -g <path/to/dsym> -a x86_64 > mylib.sym

Use the -a option if your library is built for contains multiple architectures.

Windows example

<path\to\dump_syms>.exe <\path\to\my\lib>.pdb > mylib.sym

Uploading symbol files

The symbol files can either be uploaded to BugSnag using Breakpad’s symupload tool or manually via the API.

Using Breakpad’s symupload tool

Breakpad provides a symupload tool for uploading Breakpad symbol files to a target endpoint.

The symupload tool can be used to upload Breakpad symbol files to BugSnag by setting the upload URL to the API endpoint (including the project’s API key as a query parameter).

symupload example

Here’s an example request with symupload:

symupload </path/to/symbol/file> \
    "https://upload.bugsnag.com/breakpad-symbol?api_key=<YOUR_API_KEY_HERE>&overwrite=true&project_root=C%3A%5Cworkspace%5Cmy_app"

Using the Breakpad Symbol Upload API

To send symbol mapping files to BugSnag, POST them to https://upload.bugsnag.com/breakpad-symbol (or the address of your upload server, if using BugSnag On-premise) with the following parameters:

Query Parameters:

• api_key - your BugSnag integration API key for this application.
• overwrite (optional) - whether to overwrite any existing mappings for this version of your app.
• project_root (optional) - URL encoded string representing the root path of the project on the filesystem where the application was built. This improves error grouping.

Form Fields:

• symbol_file - the path to the Breakpad symbol file.
• version (optional) - the file version of the module.
• os (optional) - the operating system that the module was built for.
• cpu (optional) - the CPU that the module was built for.
• debug_file (optional) - the basename of the debug file.
• code_file (optional) - the basename of the module.
• debug_identifier (optional) - the debug file’s identifier.
• product (optional) - the product name.

cURL example

Here’s an example request with curl:

$ curl --http1.1 \
    "https://upload.bugsnag.com/breakpad-symbol?api_key=<YOUR_API_KEY_HERE>&overwrite=true&project_root=C%3A%5Cworkspace%5Cmy_app" \
    -F symbol_file=@/path/to/symbol/file \
    -F version=1.2.3 \
    -F os=windows \
    -F cpu=x86 \
    -F debug_file=app.pdb \
    -F code_file=app.exe \
    -F debug_identifier=11111111BBBB3333DDDD555555555555F \
    -F product=MyApp

Response codes

If the file is accepted then an HTTP 200 response will be returned with the body “OK”.

If not, there are several possible problems which will be indicated with an HTTP 4XX response:

• duplicate Breakpad symbols file - indicates that BugSnag already has a file. You can ignore this error by using the overwrite parameter.
• invalid api_key - indicates that the provided api_key doesn’t correspond to a BugSnag project.
• missing api_key - indicates that the api_keyparameter is missing.
• missing symbol_file - indicates that the symbol_fileparameter is missing.