bug 1339019 - Caution against recording Telemetry in hot paths. r=gfritzsche

Histograms, Scalars, and Events are cheap but not free. Expect performance
impacts if you use them in tight loops or hot paths.

MozReview-Commit-ID: 2nrdHXrbN9i

--HG--
extra : rebase_source : fa2a7f81ac00218898fc1b6e0c77a3de23ab3f88

toolkit/components/telemetry/docs/collection/events.rst

@@ -138,6 +138,10 @@ Record a registered event.
 Throws if the combination of ``category``, ``method`` and ``object`` is unknown.
 Recording an expired event will not throw, but print a warning into the browser console.
 
+.. warning::
+
+  Event Telemetry recording is designed to be cheap, not free. If you wish to record events in a performance-sensitive piece of code, store the events locally and record them only after the performance-sensitive piece ("hot path") has completed.
+
 Example:
 
 .. code-block:: js

toolkit/components/telemetry/docs/collection/histograms.rst

@@ -256,6 +256,10 @@ The histogram names declared in ``Histograms.json`` are translated into constant
 
   mozilla::Telemetry::Accumulate(mozilla::Telemetry::STARTUP_CRASH_DETECTED, true);
 
+.. warning::
+
+  Telemetry accumulations are designed to be cheap, not free. If you wish to accumulate values in a performance-sensitive piece of code, store the accumualtions locally and accumulate after the performance-sensitive piece ("hot path") has completed.
+
 The ``Telemetry.h`` header also declares the helper classes ``AutoTimer`` and ``AutoCounter``. Objects of these types automatically record a histogram value when they go out of scope:
 
 .. code-block:: cpp

toolkit/components/telemetry/docs/collection/scalars.rst

@@ -51,6 +51,10 @@ Probes in native code can use the more convenient helper functions declared in `
     void ScalarSet(mozilla::Telemetry::ScalarID aId, const nsAString& aKey, bool aValue);
     void ScalarSetMaximum(mozilla::Telemetry::ScalarID aId, const nsAString& aKey, uint32_t aValue);
 
+.. warning::
+
+  Scalar operations are designed to be cheap, not free. If you wish to manipulate Scalars in a performance-sensitive piece of code, store the operations locally and change the Scalar only after the performance-sensitive piece ("hot path") has completed.
+
 The YAML definition file
 ========================
 Scalar probes are required to be registered, both for validation and transparency reasons,