@atlaskit/insm 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @atlaskit/insm
 
+## 0.1.0
+
+### Minor Changes
+
+- [`87ddd90aaae7b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/87ddd90aaae7b) -
+  Add INP period measurer
+
 ## 0.0.2
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,206 @@
-# Insm
+# insm — Interactivity Session Measurement
 
-INSM tooling measures user-perceived interactivity of a page
+A lightweight, session-based way to measure how interactive your experience feels to users. insm
+summarizes interactivity quality for the time a user spends on a page or specific view, and emits a
+single analytics event when the session ends.
 
-## Usage
+## What insm measures
 
-Detailed docs and example usage can be found
-[here](https://atlaskit.atlassian.com/packages/editor/insm).
+- Interactivity quality during periods of user activity within a session
+- Both active time (when users are interacting) and overall session time
+- Excludes explicitly-marked heavy/expected work so it doesn’t skew results
+- A single, session-completion event with summary statistics and optional custom properties
+
+## Common insm measurement tasks
+
+### Instrumenting "heavy tasks"
+
+Heavy tasks which are known to cause interactivity regressions can be explicitly opted out of the
+interactivity measurement via explicitly marking the period of heavy work.
+
+Use with care—prefer reducing the cost of heavy tasks over opting out of measurement. As a general
+rule, only initialization and non-core actions should be marked heavy.
+
+Examples of "heavy task" periods are
+
+- page initialisation
+  - when first loading a page — significant work will often be triggered to collect, arrange and
+    present the page content to the user
+- paste handling
+  - for the edit-page paste handler — paste handling is currently known to be computationally
+    expensive (and for large clipboard items, can lock up the UI for seconds). Given this is a non
+    core experience — excluding this from interactivity monitoring ensures we have signal on the
+    core experience.
+
+```ts
+insm.session.startHeavyTask('paste-handler');
+// ... perform paste work ...
+insm.session.endHeavyTask('paste-handler');
+```
+
+### Adding additional information to the session
+
+Additional session information can be added through the `addProperties` api.
+
+```ts
+type ValidProperty = string | number | boolean;
+insm.session.addProperties(
+  propsOrFactory: Record<string, ValidProperty> | (() => Record<string, ValidProperty>)
+): void
+```
+
+This api takes either a static single-level key-value object, or callbacks which return the same and
+will be evaluated on session end.
+
+When ending a session, all properties received via this api are merged, in order, into the resulting
+insm event’s properties; last write wins.
+
+Callback values are evaluated at session end.
+
+For example, for the following
+
+```ts
+insm.session.addProperties({ one: 1, two: 2 });
+insm.session.addProperties(() => ({ one: 'one' }));
+insm.session.addProperties({ three: 3 });
+```
+
+The resulting added properties will be
+
+```ts
+{ one: 'one', two: 2, three: 3 }
+```
+
+### Getting current insm session details
+
+```ts
+insm.session.details;
+```
+
+This can be used to gate changes based on an individual experience.
+
+ie.
+
+```ts
+if (insm.session.details.experienceKey === 'cc.edit-page' && gateCheck()) {
+	insm.session.addProperties(() => ({
+		/*potentially large or computationally large property bag */
+	}));
+}
+```
+
+### Flagging when a feature is being used
+
+```ts
+insm.session.startFeature(featureName: string): void
+insm.session.endFeature(featureName: string): void
+```
+
+```ts
+useEffect(() => {
+	insm.session.startFeature('comment notification');
+	return () => {
+		insm.session.endFeature('comment notification');
+	};
+}, []);
+```
+
+In the resulting insm event;
+
+- Long Animation frames will have any active features identified on them
+- The slowest active sessions will have any features used during the active session identified on
+  them
+
+## How to instrument insm measurement
+
+### Prerequisites
+
+Your product must have the insm library installed — insm has the same prerequisites as UFO tooling
+https://developer.atlassian.com/platform/ufo/react-ufo/react-ufo/getting-started/#prerequisites.
+
+### Installation
+
+```sh
+yarn add @atlaskit/insm
+```
+
+### Initialisation
+
+To begin instrumentation, initialise insm via invoking the init function and passing a config object
+as defined by your instrumentation requirements.
+
+```ts
+import { init } from '@atlaskit/insm';
+
+export function initialiseINSM(config) {
+	/* logic to get/initialise your app's analytics client */
+	init(config);
+}
+```
+
+As early as possible in the application mount timeline (ideally, before the application is mounted),
+initialise the insm client via the initialiseINSM function.
+
+**Important**: insm will only track interactivity for explicitly allow-listed experiences — these
+must be configured in the `config` passed.
+
+```ts
+{
+	getAnalyticsWebClient,
+	experiences: {
+		['experience key']: {enabled: true}
+	}
+}
+```
+
+If an experience key is missing or not enabled, no session event will be emitted.
+
+### Starting the page session
+
+On route change/start call the insm start api.
+
+```ts
+insm.start(experienceKey, {
+	contentId,
+	initial,
+});
+```
+
+Note: calling this will end any existing experience (unless the experience key and properties
+match - in which case no session change will occur).
+
+#### Naming guidance
+
+Choose an `experienceKey` that reflects the product and content type you want to analyze.
+
+Examples: `cc.view-page`, `cc.edit-page`, `cc.live-doc`
+
+### Stop interactivity tracking for the page session
+
+Ending a page session interactivity tracking is done by either;
+
+- starting a new session.
+- or when a tab session ends (ie. closing tab, refreshing page)
+
+In some scenarios (ie. when a page error boundary is hit), you will want to exit early. This is
+achieved by calling the following.
+
+```ts
+insm.stopEarly(reasonKey: string, description: string);
+```
+
+Sessions closed early are identifiable by their end details
+`"endDetails": { stoppedBy: "early-stop", reasonKey, description }`.
+
+**Note**: The session is ended as soon as stopEarly is called, any `addProperties` handlers will
+called at this point.
+
+### Tracking gate access
+
+Call gateAccess whenever a gate is evaluated or changes during the session.
+
+```ts
+insm.gateAccess('gate key', 'gate rule');
+```
+
+This should be wired up to any gate access libraries/tools used by your product.

package/dist/cjs/index.js

@@ -4,7 +4,61 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.init = init;
+exports.insm = void 0;
+var _insm = require("./insm");
+var initialisedInsm;
+
 /**
  * Initializes the INSM (Interactivity Session Measurement) tooling
  */
-function init() {}
+function init(options) {
+  initialisedInsm = new _insm.INSM(options);
+}
+function insmInitialised() {
+  if (!initialisedInsm) {
+    // eslint-disable-next-line no-console
+    console.error('INSM used when not initialised');
+    return false;
+  }
+  return true;
+}
+
+/**
+ * **In**teractivity **s**ession **m**onitoring
+ */
+var insm = exports.insm = {
+  startHeavyTask: function startHeavyTask(heavyTaskName) {
+    if (insmInitialised()) {
+      initialisedInsm.startHeavyTask(heavyTaskName);
+    }
+  },
+  endHeavyTask: function endHeavyTask(heavyTaskName) {
+    if (insmInitialised()) {
+      initialisedInsm.endHeavyTask(heavyTaskName);
+    }
+  },
+  start: function start(experienceKey, experienceProperties) {
+    if (insmInitialised()) {
+      initialisedInsm.start(experienceKey, experienceProperties);
+    }
+  },
+  stopEarly: function stopEarly(reasonKey, description) {
+    if (insmInitialised()) {
+      initialisedInsm.stopEarly(reasonKey, description);
+    }
+  },
+  // We only expose details and feature start/stop to consumers
+  // as the other properties are internals for the insm and InsmPeriod
+  // to interact with the running session.
+  get session() {
+    if (insmInitialised()) {
+      return initialisedInsm.runningSession;
+    }
+  },
+  // @ts-expect-error Private method for testing purposes
+  __setAnalyticsWebClient: function __setAnalyticsWebClient(analyticsWebClient) {
+    if (initialisedInsm) {
+      initialisedInsm.analyticsWebClient = analyticsWebClient;
+    }
+  }
+};

package/dist/cjs/inp-measurers/inp.js

@@ -0,0 +1,184 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.INPTracker = void 0;
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var INPTracker = exports.INPTracker = /*#__PURE__*/function () {
+  function INPTracker(options) {
+    (0, _classCallCheck2.default)(this, INPTracker);
+    /**
+     * INP stands for Interaction to Next Paint
+     */
+    (0, _defineProperty2.default)(this, "name", 'inp');
+    this.includedInteractions = (options === null || options === void 0 ? void 0 : options.includedInteractions) || ['pointerdown', 'pointerup', 'click', 'keydown', 'keyup'];
+    this.monitor = new InteractionTracker(this.includedInteractions);
+  }
+  return (0, _createClass2.default)(INPTracker, [{
+    key: "start",
+    value: function start(paused) {
+      var result = this.monitor.start(paused);
+      return result;
+    }
+  }, {
+    key: "end",
+    value: function end() {
+      var result = this.monitor.end();
+      return result;
+    }
+  }, {
+    key: "pause",
+    value: function pause() {
+      this.monitor.pause();
+    }
+  }, {
+    key: "resume",
+    value: function resume() {
+      this.monitor.resume();
+    }
+  }]);
+}();
+var InteractionResult = /*#__PURE__*/function () {
+  function InteractionResult() {
+    (0, _classCallCheck2.default)(this, InteractionResult);
+    this.min = Infinity;
+    this.max = 0;
+    this.average = 0;
+    this.numerator = 0;
+    this.count = 0;
+  }
+  return (0, _createClass2.default)(InteractionResult, [{
+    key: "update",
+    value: function update(duration) {
+      if (duration > this.max) {
+        this.max = duration;
+      }
+      if (duration < this.min) {
+        this.min = duration;
+      }
+      this.numerator += this.average * (this.count - 1) + duration;
+      this.count += 1;
+      this.average = this.numerator / this.count;
+    }
+  }, {
+    key: "toMeasure",
+    value: function toMeasure() {
+      return {
+        min: this.count === 0 ? 0 : this.min,
+        max: this.max,
+        average: this.average,
+        numerator: this.numerator,
+        denominator: this.count
+      };
+    }
+  }]);
+}();
+var InteractionTracker = /*#__PURE__*/function () {
+  function InteractionTracker(includedInteractions) {
+    (0, _classCallCheck2.default)(this, InteractionTracker);
+    (0, _defineProperty2.default)(this, "paused", false);
+    this.performanceObserver = null;
+    this.interactionResult = new InteractionResult();
+    this.includedInteractions = includedInteractions;
+  }
+  return (0, _createClass2.default)(InteractionTracker, [{
+    key: "stopTracking",
+    value: function stopTracking() {
+      var _this$performanceObse;
+      (_this$performanceObse = this.performanceObserver) === null || _this$performanceObse === void 0 || _this$performanceObse.disconnect();
+      this.performanceObserver = null;
+    }
+  }, {
+    key: "startTracking",
+    value: function startTracking() {
+      var _this = this;
+      this.performanceObserver = new PerformanceObserver(function (list) {
+        // Note: find link to actual safari issue .. good to get rid of this if Safari has fixed this
+        // Delay by a microtask to workaround a bug in Safari where the
+        // callback is invoked immediately, rather than in a separate task.
+        // See: https://github.com/GoogleChrome/web-vitals/issues/277
+        Promise.resolve().then(function () {
+          var entries = list.getEntries();
+          entries.forEach(function (entry) {
+            // Skip further processing for entries that cannot be INP candidates.
+            //
+            // When a user interacts with a web page, a user interaction (for example a click) usually triggers a sequence of events.
+            // To measure the latency of this series of events, the events share the same interactionId.
+            // An interactionId is only computed for the following event types belonging to a user interaction. It is 0 otherwise.
+            // * click / tap / drag events: 'pointerdown', 'pointerup', 'click'
+            // * keypress events: 'keydown', 'keyup'
+            //
+            if (!entry.interactionId) {
+              return;
+            }
+            if (_this.includedInteractions.includes(entry.name)) {
+              _this.interactionResult.update(entry.duration);
+            }
+          });
+        });
+      });
+
+      // Event Timing entries have their durations rounded to the nearest 8ms,
+      // so a duration of 40ms would be any event that spans 2.5 or more frames
+      // at 60Hz. This threshold is chosen to strike a balance between usefulness
+      // and performance. Running this callback for any interaction that spans
+      // just one or two frames is likely not worth the insight that could be
+      // gained.
+      if (PerformanceObserver.supportedEntryTypes.includes('event')) {
+        this.performanceObserver.observe({
+          type: 'event',
+          buffered: true,
+          durationThreshold: 40
+        });
+      }
+    }
+  }, {
+    key: "reset",
+    value: function reset() {
+      this.stopTracking();
+      this.interactionResult = new InteractionResult();
+    }
+  }, {
+    key: "start",
+    value: function start(paused) {
+      var lastResult = this.interactionResult.toMeasure();
+      this.reset();
+      this.paused = paused;
+      if (!paused) {
+        this.startTracking();
+      }
+      return lastResult;
+    }
+  }, {
+    key: "end",
+    value: function end() {
+      try {
+        return this.interactionResult.toMeasure();
+      } finally {
+        this.reset();
+      }
+    }
+  }, {
+    key: "pause",
+    value: function pause() {
+      if (this.paused) {
+        return;
+      }
+      this.paused = true;
+      this.stopTracking();
+    }
+  }, {
+    key: "resume",
+    value: function resume() {
+      if (!this.paused) {
+        return;
+      }
+      this.paused = false;
+      this.startTracking();
+    }
+  }]);
+}();