Crash Reporting Guide for Firefox OS Partners

  • Revision slug: Crash_Reporting_Guide_for_Firefox_OS_Partners
  • Revision title: Crash Reporting Guide for Firefox OS Partners
  • Revision id: 450175
  • Created:
  • Creator: Benjamin Smedberg
  • Is current revision? No
  • Comment

Revision Content

Mozilla has a world-class system for collecting, analyzing, and fixing crashes and other stability issues such as hangs. Firefox OS partners need to work with Mozilla to correctly enable crash reporting and upload symbols.

For general information about crash reporting, how it works, and how data is used, see the Crash reporting article.

Enable Firefox OS Crash Reporting

It is essential that any device with Firefox branding have crash reporting enabled. This must be enabled by including the following line in the `mozconfig` file used to build the release build:

export MOZILLA_OFFICIAL=1

Crash reports contain key/value metadata and a minidump file. This file contains only the stack memory and memory mapping information, and does not contain any proprietary information such as symbols. Non-private data from crash reports are processed and displayed on crash-stats.mozilla.org. Because the actual minidump files may contain personal data if it is stored on the binary stack, these files remain private and are available only to Mozilla employees and certain partners who have a non-disclosure and privacy agreement for user data.

Upload Symbols to Mozilla

Symbol files allow Mozilla to process crash report minidumps. The symbol files are text files which are extracted from the binary debug information. For more information about the format of symbols files, see the breakpad documentation.

The symbols files for open-source code including all of gecko files must be available for crash processing. Partners should request an SSH account to upload symbols. See the symbol upload instructions for specific details. Symbols from multiple builds will not overwrite eachother on the server, because each symbol file is keyed against a unique debug identifier.

Firefox OS partners may also have binaries such as drivers which are not open-source. For Firefox OS partners as well as other partners such as plugin and extension vendors, Mozilla has a tool for encrypting symbol files so that they can still be used to produce backtraces and correlate crashes, without revealing the function or file names. Partners should take care that symbols for proprietary binaries are encrypted before being uploaded.

Qualcomm currently does not allow Firefox OS partners to upload Qualcomm-proprietary symbols, usually built from the vendor/qcom/proprietary subtree of the Firefox OS build. The symbols from this subtree should be archived by parterns; at the present time they should not be uploaded to Mozilla.

Release Channels

While originally created for updates (displayed as "Update channel" in the Settings app under "Device Information" > "More Information" and available to use in the app.update.url preference of the prouct), the release channel plays an important role in determining what kind of build a crash comes from. Therefore, if you want to get useful crash statistics out of Mozilla's tools and want Mozilla's stability team to recognize and fix crashes, you need to set that channel according to the following rules:

  • For release builds, the release channel should be set to release-<vendor>, e.g. release-zte, depending on the vendor that generates builds. Note that this is the same as update channel. If different (gecko) binaries are created for different regions, the region should be appended as well, e.g. release-zte-spain (or similar, the important point is release-<something> for release builds, in a way that the Mozilla stability can decipher the <something> part, and different channel names for individual builds that could be on the same device).
  • For preview/pre-release/pre-certification builds, set the release channel to "nightly" on unstable of "beta" on stable branches, and in case there's changes to binary code outside kernel/driver space, also add the vendor suffix, i.e. nightly-<vendor> or beta-<vendor>, following the release build model, in this case.

To set the channel, use the B2G_UPDATE_CHANNEL environment variable when building:

export B2G_UPDATE_CHANNEL=release-myvendor

Revision Source

<p>Mozilla has a world-class system for collecting, analyzing, and fixing crashes and other stability issues such as hangs. Firefox OS partners need to work with Mozilla to correctly enable crash reporting and upload symbols.</p>
<p>For general information about crash reporting, how it works, and how data is used, see the <a href="/en-US/docs/Crash_reporting" title="/en-US/docs/Crash_reporting">Crash reporting </a>article.</p>
<h2 id="Enable_Firefox_OS_Crash_Reporting">Enable Firefox OS Crash Reporting</h2>
<p>It is essential that any device with Firefox branding have crash reporting enabled. This must be enabled by including the following line in the `mozconfig` file used to build the release build:</p>
<pre>
export MOZILLA_OFFICIAL=1</pre>
<p>Crash reports contain key/value metadata and a minidump file. This file contains only the stack memory and memory mapping information, and does not contain any proprietary information such as symbols. Non-private data from crash reports are processed and displayed on crash-stats.mozilla.org. Because the actual minidump files may contain personal data if it is stored on the binary stack, these files remain private and are available only to Mozilla employees and certain partners who have a non-disclosure and privacy agreement for user data.</p>
<h2 id="Upload_Symbols_to_Mozilla">Upload Symbols to Mozilla</h2>
<p>Symbol files allow Mozilla to process crash report minidumps. The symbol files are text files which are extracted from the binary debug information. For more information about the format of symbols files, see the <a href="http://code.google.com/p/google-breakpad/wiki/SymbolFiles" title="http://code.google.com/p/google-breakpad/wiki/SymbolFiles">breakpad documentation</a>.</p>
<p>The symbols files for open-source code including all of gecko files must be available for crash processing. Partners should request an SSH account to upload symbols. See the <a href="/en-US/docs/Uploading_symbols_to_Mozillas_symbol_server" title="/en-US/docs/Uploading_symbols_to_Mozillas_symbol_server">symbol upload instructions</a> for specific details. Symbols from multiple builds will not overwrite eachother on the server, because each symbol file is keyed against a unique debug identifier.</p>
<p>Firefox OS partners may also have binaries such as drivers which are not open-source. For Firefox OS partners as well as other partners such as plugin and extension vendors, Mozilla has a <a href="https://github.com/bsmedberg/breakpad-symbol-encryption" title="https://github.com/bsmedberg/breakpad-symbol-encryption">tool for encrypting symbol files</a> so that they can still be used to produce backtraces and correlate crashes, without revealing the function or file names. Partners should take care that symbols for proprietary binaries are encrypted before being uploaded.</p>
<div class="geckoVersionNote">
  <div class="warning">
    <p>Qualcomm currently does not allow Firefox OS partners to upload Qualcomm-proprietary symbols, usually built from the vendor/qcom/proprietary subtree of the Firefox OS build. The symbols from this subtree should be archived by parterns; at the present time they should not be uploaded to Mozilla.</p>
  </div>
</div>
<h2 id="Release_Channels">Release Channels</h2>
<p>While originally created for updates (displayed as "Update channel" in the Settings app under "Device Information" &gt; "More Information" and available to use in the app.update.url preference of the prouct), the release channel plays an important role in determining what kind of build a crash comes from. Therefore, if you want to get useful crash statistics out of Mozilla's tools and want Mozilla's stability team to recognize and fix crashes, you need to set that channel according to the following rules:</p>
<ul>
  <li>For release builds, the release channel should be set to release-&lt;vendor&gt;, e.g. release-zte, depending on the vendor that generates builds. Note that this is the same as update channel. If different (gecko) binaries are created for different regions, the region should be appended as well, e.g. release-zte-spain (or similar, the important point is release-&lt;something&gt; for release builds, in a way that the Mozilla stability can decipher the &lt;something&gt; part, and different channel names for individual builds that could be on the same device).</li>
  <li>For preview/pre-release/pre-certification builds, set the release channel to "nightly" on unstable of "beta" on stable branches, and in case there's changes to binary code outside kernel/driver space, also add the vendor suffix, i.e. nightly-&lt;vendor&gt; or beta-&lt;vendor&gt;, following the release build model, in this case.</li>
</ul>
<p>To set the channel, use the B2G_UPDATE_CHANNEL environment variable when building:</p>
<pre>
export B2G_UPDATE_CHANNEL=release-myvendor</pre>
Revert to this revision