Uploading symbols to Mozilla's symbol server

As a third-party releasing your own builds of Firefox or Firefox OS, you should consider uploading debug symbols from the builds to Mozilla's symbol server. If you have not disabled crash reporting in your builds, crash reports will be submitted to Mozilla's crash reporting server. Without the debug symbols that match your build the crash reports will not contain actionable information.

There are two upload systems: a legacy upload system uses SSH accounts for direct upload; the newer replacement system allows uploads either via a web browser or a web API.

Building a Symbol Package

To upload symbols, you need to build a symbol package. This is a .tar.bz2 file which contains the symbol files in a specific directory structure.

If you are building Firefox,or a similar application using the Mozilla build system, you can build the symbol package using a make target:

make buildsymbols

This will create a symbol package in dist/ named something like firefox-34.0a1.en-US.win32.crashreporter-symbols.zip .

For Firefox OS, use build.sh:

./build.sh buildsymbols

New Upload System

In the new system, symbols are uploaded via your account on crash-stats.mozilla.org. Visit https://crash-stats.mozilla.com/symbols/ and log in. Then request upload permission by filing a bug in the Socorro component using this template.

After symbol upload is turned on, you can upload the symbol archive directly using the web form at https://crash-stats.mozilla.com/symbols/upload/web/. It is also possible to upload via automated scripts: see the symbol upload API docs for more details.

Old Upload System

Getting Access

In the old system symbols are uploaded using an SSH connection to symbolpush.mozilla.org. In order to connect to this host you will need an account. You should first file a bug in the Server Operations component at bugzilla.mozilla.org requesting an account to upload symbols on symbolpush.mozilla.org. You will need to attach an SSH public key to the bug report that can be used for authentication. If you have a contact at Mozilla you should CC that person for approval.

Uploading Symbols

The build system provides two targets that are required to generate and upload the symbols—buildsymbols and uploadsymbols. If you are building the Firefox browser, you can simply run make buildsymbols and make uploadsymbols in the object directory to execute these targets. If you are building Firefox OS, you simply run ./build.sh buildsymbols and ./build.sh uploadsymbols.

The uploadsymbols target requires several environment variables to be set to provide information about where to upload the symbols. Full documentation for these is in the upload_symbols.sh script.

  • SYMBOL_SERVER_HOST—this should be set to symbolpush.mozilla.org.
  • SYMBOL_SERVER_USER—this should be set to the username that was created for you in the bug where you received access.
  • SYMBOL_SERVER_PATH—this should be set to the path given to you in the bug where you received access. It will be of the form /mnt/netapp/breakpad/symbols_x.
  • SYMBOL_SERVER_SSH_KEY—this should be set to the path to the SSH private key that matches the public key you provided for your account.
  • POST_SYMBOL_UPLOAD_CMD—unused, leave this empty for now

Note: the uploaded symbols should be world-readable. If your build machine has a restrictive umask, it may be necessary to chmod the symbols before or after upload so that they are usable by the crash-reporting system.