--- a/toolkit/components/telemetry/docs/collection/index.rst
+++ b/toolkit/components/telemetry/docs/collection/index.rst
@@ -14,25 +14,27 @@ 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 with extended Telemetry
+enabled.
+
+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 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,22 @@ 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
+information see :doc:`stack capture <../collection/stack-capture>`.
+
+This is similar to :ref:`chromeHangs`, but only Precise C++ stacks on the main thread of
+the parent process are reported. This data 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:
 
@@ -315,16 +320,18 @@ Structure:
            [1, 2540075],
            // ... other frames ...
         ],
         // ... other stacks ...
       ],
       "captures": [["string-key", stack-index, count], ... ]
     }
 
+.. _chromeHangs:
+
 chromeHangs
 -----------
 Contains the statistics about the hangs happening exclusively on the main thread of the parent process. Precise C++ stacks are reported. This is only available on Nightly Release on Windows, when building using "--enable-profiling" switch.
 
 Some limits are applied:
 
 * Reported chrome hang stacks are limited in depth to 50 entries.
 * The maximum number of reported stacks is 50.