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

--HG--
extra : moz-landing-system : lando

toolkit/components/telemetry/app/TelemetryEnvironment.jsm

@@ -58,6 +58,7 @@ const MAX_ATTRIBUTION_STRING_LENGTH = 100;
 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.
@@ -125,6 +126,7 @@ var TelemetryEnvironment = {
    * @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) {
@@ -1177,6 +1179,20 @@ EnvironmentCache.prototype = {
       }
     }
 
+    // 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 || {};
@@ -1184,6 +1200,9 @@ EnvironmentCache.prototype = {
     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);

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

@@ -10,7 +10,7 @@ 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
 
@@ -35,6 +35,7 @@ This synchronously returns a dictionary containing the information for each acti
 
 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).

toolkit/components/telemetry/docs/data/environment.rst

@@ -284,7 +284,7 @@ Structure:
         },
       },
       experiments: {
-        "<experiment id>": { branch: "<branch>" },
+        "<experiment id>": { branch: "<branch>", type: "<type>", enrollmentId: "<id>" },
         // ...
       }
     }
@@ -465,15 +465,25 @@ Just like activePlugins, this will report dummy values until the blocklist is lo
 
 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: