--- a/toolkit/components/telemetry/docs/collection/index.rst
+++ b/toolkit/components/telemetry/docs/collection/index.rst
@@ -14,25 +14,26 @@ The current data collection possibilitie
 
 * :doc:`scalars` allow recording of a single value (string, boolean, a number)
 * :doc:`histograms` can efficiently record multiple data points
 * ``environment`` data records information about the system and settings a session occurs in
 * :doc:`events` can record richer data on individual occurences of specific actions
 * ``TelemetryLog`` allows collecting ordered event entries (note: this does not have supporting analysis tools)
 * :doc:`measuring elapsed time <measuring-time>`
 * :doc:`custom pings <custom-pings>`
+* :doc:`stack capture <stack-capture>` allow recording application call stacks
 
 .. toctree::
    :maxdepth: 2
    :titlesonly:
    :hidden:
    :glob:
 
    scalars
    histograms
    events
    measuring-time
    custom-pings
-   *
+   stack-capture
 
 Browser Usage Telemetry
 ~~~~~~~~~~~~~~~~~~~~~~~
 For more information, see :ref:`browserusagetelemetry`.

new file mode 100644
--- /dev/null
+++ b/toolkit/components/telemetry/docs/collection/stack-capture.rst
@@ -0,0 +1,67 @@
+=============
+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 OSX. Capturing stacks is only available in the extended set
+of measures.
+
+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 :doc:`main pings <../data/main-ping>`.
+
+The API
+=======
+Capturing stacks is available either via the `nsITelemetry interface <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/nsITelemetry.idl>`_
+or the `C++ API <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Telemetry.h>`_.
+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:
+
+.. code-block:: js
+
+  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 <https://dxr.mozilla.org/mozilla-central/search?q=regexp%3ATelemetryScalar%3A%3A(Set%7CAdd)+file%3ATelemetryScalar.cpp&redirect=false>`_ .
+
+C++ API
+-------
+Capturing stacks in native code can be achieved by calling:
+
+.. code-block:: cpp
+
+    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 alpha-numeric characters or ``-``.
+
+Both the depth of the captured stacks and the total number of keys in the
+dictionary to  are limited to ``50``.

--- a/toolkit/components/telemetry/docs/data/main-ping.rst
+++ b/toolkit/components/telemetry/docs/data/main-ping.rst
@@ -284,17 +284,19 @@ Structure:
           },
         ],
       },
       ... other threads ...
      ]
 
 capturedStacks
 --------------
-Contains information about stacks captured on demand via Telemetry API. This is similar to `chromeHangs`, but only stacks captured on the main thread of the parent process are reported. It reports precise C++ stacks are reported and is only available on Windows, either in Firefox Nightly or in builds using "--enable-profiling" switch.
+Contains information about stacks captured on demand via Telemetry API. For more see :doc:`stack capture <../collection/stack-capture>`.
+
+This is similar to `chromeHangs`, but only stacks captured on the main thread of the parent process are reported. It reports precise C++ stacks are reported and is only available on Windows, either in Firefox Nightly or in builds using ``--enable-profiling`` switch.
 
 Limits for captured stacks are the same as for chromeHangs (see below). Furthermore:
 
 * the key length is limited to 50 characters,
 * keys are restricted to alpha-numeric characters and `-`.
 
 Structure: