Bug 1555172 - Allow annotating experiments with Enrollment Ids. r=janerik,mythmon
authorChris H-C <chutten@mozilla.com>
Mon, 15 Jul 2019 13:00:55 +0000
changeset 482823 acd1ffd459f7c0b15fca1d7fef312dab1d34513e
parent 482822 95ba49af920094ac7d154d38bf5142297189eea7
child 482824 975c468c465be8154d9efe61dca3fc2da12ac387
push id36297
push usermalexandru@mozilla.com
push dateTue, 16 Jul 2019 04:07:00 +0000
treeherdermozilla-central@677619325444 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjanerik, mythmon
bugs1555172
milestone70.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1555172 - Allow annotating experiments with Enrollment Ids. r=janerik,mythmon This id, to be generated at runtime by the client, will be used to distinguish when a client enrolls multiple times in the same id/branch/type. Differential Revision: https://phabricator.services.mozilla.com/D37774
toolkit/components/telemetry/app/TelemetryEnvironment.jsm
toolkit/components/telemetry/docs/collection/experiments.rst
toolkit/components/telemetry/docs/data/environment.rst
--- a/toolkit/components/telemetry/app/TelemetryEnvironment.jsm
+++ b/toolkit/components/telemetry/app/TelemetryEnvironment.jsm
@@ -53,16 +53,17 @@ ChromeUtils.defineModuleGetter(
 // The maximum length of a string (e.g. description) in the addons section.
 const MAX_ADDON_STRING_LENGTH = 100;
 // The maximum length of a string value in the settings.attribution object.
 const MAX_ATTRIBUTION_STRING_LENGTH = 100;
 // The maximum lengths for the experiment id and branch in the experiments section.
 const MAX_EXPERIMENT_ID_LENGTH = 100;
 const MAX_EXPERIMENT_BRANCH_LENGTH = 100;
 const MAX_EXPERIMENT_TYPE_LENGTH = 20;
+const MAX_EXPERIMENT_ENROLLMENT_ID_LENGTH = 40;
 
 /**
  * This is a policy object used to override behavior for testing.
  */
 // eslint-disable-next-line no-unused-vars
 var Policy = {
   now: () => new Date(),
   _intlLoaded: false,
@@ -120,16 +121,17 @@ var TelemetryEnvironment = {
    * Add an experiment annotation to the environment.
    * If an annotation with the same id already exists, it will be overwritten.
    * This triggers a new subsession, subject to throttling.
    *
    * @param {String} id The id of the active experiment.
    * @param {String} branch The experiment branch.
    * @param {Object} [options] Optional object with options.
    * @param {String} [options.type=false] The specific experiment type.
+   * @param {String} [options.enrollmentId=undefined] The id of the enrollment.
    */
   setExperimentActive(id, branch, options = {}) {
     if (gGlobalEnvironment) {
       gGlobalEnvironment.setExperimentActive(id, branch, options);
     } else {
       gActiveExperimentStartupBuffer.set(id, { branch, options });
     }
   },
@@ -1172,23 +1174,40 @@ EnvironmentCache.prototype = {
       if (type.length != options.type.length) {
         options.type = type;
         this._log.warn(
           "setExperimentActive - the experiment type was truncated."
         );
       }
     }
 
+    // Truncate the enrollment id if present.
+    if (options.hasOwnProperty("enrollmentId")) {
+      let enrollmentId = limitStringToLength(
+        options.enrollmentId,
+        MAX_EXPERIMENT_ENROLLMENT_ID_LENGTH
+      );
+      if (enrollmentId.length != options.enrollmentId.length) {
+        options.enrollmentId = enrollmentId;
+        this._log.warn(
+          "setExperimentActive - the enrollment id was truncated."
+        );
+      }
+    }
+
     let oldEnvironment = Cu.cloneInto(this._currentEnvironment, myScope);
     // Add the experiment annotation.
     let experiments = this._currentEnvironment.experiments || {};
     experiments[saneId] = { branch: saneBranch };
     if (options.hasOwnProperty("type")) {
       experiments[saneId].type = options.type;
     }
+    if (options.hasOwnProperty("enrollmentId")) {
+      experiments[saneId].enrollmentId = options.enrollmentId;
+    }
     this._currentEnvironment.experiments = experiments;
     // Notify of the change.
     this._onEnvironmentChange("experiment-annotation-changed", oldEnvironment);
   },
 
   setExperimentInactive(id) {
     this._log.trace("setExperimentInactive");
     let experiments = this._currentEnvironment.experiments || {};
--- a/toolkit/components/telemetry/docs/collection/experiments.rst
+++ b/toolkit/components/telemetry/docs/collection/experiments.rst
@@ -5,17 +5,17 @@ This API allows privileged JavaScript to
 
 The experiment annotations are sent with any ping that includes the :doc:`../data/environment` data.
 
 The JS API
 ==========
 Privileged JavaScript code can annotate experiments using the functions exposed by ``TelemetryEnvironment.jsm``.
 
 The following function adds an annotation to the environment for the provided ``id``, ``branch`` and ``options``. Calling this function repeatedly with the same ``id`` will overwrite the state and trigger new subsessions (subject to throttling).
-``options`` is an object that currently may contain ``type``, to tag the experiment with a specific type.
+``options`` is an object that may contain ``type`` to tag the experiment with a specific type or ``enrollmentId`` to tag the enrollment in this experiment with an identifier.
 
 .. code-block:: js
 
     TelemetryEnvironment.setExperimentActive(id, branch, [options={}}])
 
 This removes the annotation for the experiment with the provided ``id``.
 
 .. code-block:: js
@@ -30,11 +30,12 @@ This synchronously returns a dictionary 
 
 .. note::
 
     Both ``setExperimentActive`` and ``setExperimentInactive`` trigger a new subsession. However
     the latter only does so if there was an active experiment with the provided ``id``.
 
 Limits and restrictions
 -----------------------
-To prevent abuses, the content of both the experiment ``id`` and ``branch`` is limited to
+To prevent abuses, the content of the experiment ``id`` and ``branch`` is limited to
 100 characters in length.
 ``type`` is limited to a length of 20 characters.
+``enrollmentId`` is limited to 40 characters (chosen to be just a little longer than the 36-character long GUID text representation).
--- a/toolkit/components/telemetry/docs/data/environment.rst
+++ b/toolkit/components/telemetry/docs/data/environment.rst
@@ -279,17 +279,17 @@ Structure:
                 version: <string>,
                 userDisabled: <bool>,
                 applyBackgroundUpdates: <integer>,
             },
             ...
         },
       },
       experiments: {
-        "<experiment id>": { branch: "<branch>" },
+        "<experiment id>": { branch: "<branch>", type: "<type>", enrollmentId: "<id>" },
         // ...
       }
     }
 
 build
 -----
 
 buildId
@@ -460,22 +460,32 @@ Just like activeAddons, up-to-date infor
 
 activeGMPPlugins
 ~~~~~~~~~~~~~~~~
 
 Just like activePlugins, this will report dummy values until the blocklist is loaded.
 
 experiments
 -----------
-For each experiment we collect the ``id`` and the ``branch`` the client is enrolled in. Both fields are truncated to 100 characters and a warning is printed when that happens.
+For each experiment we collect the
 
+- ``id`` (Like ``hotfix-reset-xpi-verification-timestamp-1548973``, max length 100 characters)
+- ``branch`` (Like ``control``, max length 100 characters)
+- ``type`` (Optional. Like ``normandy-exp``, max length 20 characters)
+- ``enrollmentId`` (Optional. Like ``5bae2134-e121-46c2-aa00-232f3f5855c5``, max length 40 characters)
+
+In the event any of these fields are truncated, a warning is printed to the console.
 
 Version History
 ---------------
 
+- Firefox 70:
+
+  - Added ``experiments.<experiment id>.enrollmentId``. (`bug 1555172 <https://bugzilla.mozilla.org/show_bug.cgi?id=1555172>`_)
+
 - Firefox 67:
 
-  - Removed ``persona``. The ``addons.activeAddons`` list should be used instead. (`bug 1525511 https://bugzilla.mozilla.org/show_bug.cgi?id=1525511>`_)
+  - Removed ``persona``. The ``addons.activeAddons`` list should be used instead. (`bug 1525511 <https://bugzilla.mozilla.org/show_bug.cgi?id=1525511>`_)
 
 - Firefox 61:
 
   - Removed empty ``addons.activeExperiment`` (`bug 1452935 <https://bugzilla.mozilla.org/show_bug.cgi?id=1452935>`_).