Bug 1277806 - Update the docs. r=gfritzsche, a=gchang
authorAlessio Placitelli <alessio.placitelli@gmail.com>
Wed, 14 Sep 2016 02:59:00 +0200
changeset 358701 5474dd7024a36e244a4e36ca5eb0b26afe1f8ffe
parent 358700 a799212022f7f7458cb2f972d31a0b0e8fa31037
child 358702 58cf57f2c147a9a52c8075d5b6bf1a769616c69b
push id1324
push usermtabara@mozilla.com
push dateMon, 16 Jan 2017 13:07:44 +0000
treeherdermozilla-release@a01c49833940 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersgfritzsche, gchang
bugs1277806
milestone51.0a2
Bug 1277806 - Update the docs. r=gfritzsche, a=gchang
toolkit/components/telemetry/docs/collection/scalars.rst
--- a/toolkit/components/telemetry/docs/collection/scalars.rst
+++ b/toolkit/components/telemetry/docs/collection/scalars.rst
@@ -18,32 +18,41 @@ JS API
 Probes in privileged JavaScript code can use the following functions to manipulate scalars:
 
 .. code-block:: js
 
   Services.telemetry.scalarAdd(aName, aValue);
   Services.telemetry.scalarSet(aName, aValue);
   Services.telemetry.scalarSetMaximum(aName, aValue);
 
+  Services.telemetry.keyedScalarAdd(aName, aKey, aValue);
+  Services.telemetry.keyedScalarSet(aName, aKey, aValue);
+  Services.telemetry.keyedScalarSetMaximum(aName, aKey, aValue);
+
 These functions can throw if, for example, an operation is performed on a scalar type that doesn't support it
-(e.g. calling scalarSetMaximum on a scalar of the string kind). Please look at the code documentation for
-additional informations.
+(e.g. calling scalarSetMaximum on a scalar of the string kind). Please look at the `code documentation <https://dxr.mozilla.org/mozilla-central/search?q=regexp%3ATelemetryScalar%3A%3A(Set%7CAdd)+file%3ATelemetryScalar.cpp&redirect=false>`_ for
+additional information.
 
 C++ API
 -------
 Probes in native code can use the more convenient helper functions declared in `Telemetry.h <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Telemetry.h>`_:
 
 .. code-block:: cpp
 
     void ScalarAdd(mozilla::Telemetry::ScalarID aId, uint32_t aValue);
     void ScalarSet(mozilla::Telemetry::ScalarID aId, uint32_t aValue);
     void ScalarSet(mozilla::Telemetry::ScalarID aId, const nsAString& aValue);
     void ScalarSet(mozilla::Telemetry::ScalarID aId, bool aValue);
     void ScalarSetMaximum(mozilla::Telemetry::ScalarID aId, uint32_t aValue);
 
+    void ScalarAdd(mozilla::Telemetry::ScalarID aId, const nsAString& aKey, uint32_t aValue);
+    void ScalarSet(mozilla::Telemetry::ScalarID aId, const nsAString& aKey, uint32_t aValue);
+    void ScalarSet(mozilla::Telemetry::ScalarID aId, const nsAString& aKey, bool aValue);
+    void ScalarSetMaximum(mozilla::Telemetry::ScalarID aId, const nsAString& aKey, uint32_t aValue);
+
 The YAML definition file
 ========================
 Scalar probes are required to be registered, both for validation and transparency reasons,
 in the `Scalars.yaml <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_
 definition file.
 
 The probes in the definition file are represented in a fixed-depth, two-level structure:
 
@@ -92,22 +101,29 @@ Required Fields
 - ``kind``: A string representing the scalar type. Allowed values are ``uint``, ``string`` and ``boolean``.
 - ``notification_emails``: A list of email addresses to notify with alerts of expiring probes. More importantly, these are used by the data steward to verify that the probe is still useful.
 
 Optional Fields
 ---------------
 
 - ``cpp_guard``: A string that gets inserted as an ``#ifdef`` directive around the automatically generated C++ declaration. This is typically used for platform-specific scalars, e.g. ``ANDROID``.
 - ``release_channel_collection``: This can be either ``opt-in`` (default) or ``opt-out``. With the former the scalar is submitted by default on pre-release channels; on the release channel only if the user opted into additional data collection. With the latter the scalar is submitted by default on release and pre-release channels, unless the user opted out.
+- ``keyed``: A boolean that determines whether this is a keyed scalar. It defaults to ``False``.
 
 String type restrictions
 ------------------------
 To prevent abuses, the content of a string scalar is limited to 50 characters in length. Trying
 to set a longer string will result in an error and no string being set.
 
+Keyed Scalars
+-------------
+Keyed scalars are collections of one of the available scalar types, indexed by a string key that can contain UTF8 characters and cannot be longer than 70 characters. Keyed scalars can contain up to 100 keys. This scalar type is for example useful when you want to break down certain counts by a name, like how often searches happen with which search engine.
+
+Keyed scalars should only be used if the set of keys are not known beforehand. If the keys are from a known set of strings, other options are preferred if suitable, like categorical histograms or splitting measurements up into separate scalars.
+
 The processor scripts
 =====================
 The scalar definition file is processed and checked for correctness at compile time. If it
 conforms to the specification, the processor scripts generate two C++ headers files, included
 by the Telemetry C++ core.
 
 gen-scalar-data.py
 ------------------