Stack capture

While studying behavior of Firefox in the wild it is sometimes useful to inspect call stacks without causing the browser to crash. Historically we could only obtain stacks for inspection from crash reports. Now stacks can be captured on demand and annotated with a unique key for further inspection.

Capturing stacks is only supported on official builds with --enable-profiling switch enabled, such as Nightly builds, for example. The feature is available on Windows, Linux and macOS builds of Firefox.

Captured stacks are grouped by a user-defined key. Identical stacks captured under the same key are combined in order to reduce their memory footprint. A counter is used to reflect the frequency of identical stacks.

The serialized stack data is submitted with the main pings.

The API

Capturing stacks is available either via the nsITelemetry interface or the C++ API. Note that current implementation of the API is not thread safe. Also, capturing stacks in the content process is not supported yet.

JS API

Privileged JavaScript code can capture stacks using the following function:

Services.telemetry.captureStack(aKey);

captureStack(aKey) instructs Telemetry to take a snapshot of the current call stack and store it under the given key (aKey). The actual stack capturing will only take place once for each key. Every consequent calls for the identical key will increase stack frequency counter without performing expensive stack walking.

aKey is a string used primarily as an identifier for a captured stack. It can be used to identify stacks down the data processing pipeline and on about:telemetry.

For more technical information please refer to the code documentation .

C++ API

Capturing stacks in native code can be achieved by calling:

void CaptureStack(const nsCString& aKey);

The behavior of CaptureStack is identical to its JavaScript counterpart.

Limits and restrictions

Keys used for capturing stacks are meant to be unique among API users. Detection of collisions, however, is left to the users themselves. In its current implementation the API does not provide any means for key registration.

To prevent abuses, the content of a key is limited to 50 characters in length. Additionally, keys may only contain alphanumeric characters or -.

Both the depth of the captured stacks and the total number of keys in the dictionary are limited to 50.