@newrelic/browser-agent 1.232.1 → 1.233.0

package/dist/esm/features/session_replay/aggregate/index.js

@@ -0,0 +1,327 @@
+/*
+ * Copyright 2023 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file Records, aggregates, and harvests session replay data.
+ *
+ * NOTE: This code is under development and dormant. It will not download to instrumented pages or record any data.
+ * It is not production ready, and is not intended to be imported or implemented in any build of the browser agent until
+ * functionality is validated and a full user experience is curated.
+ */
+
+import { drain } from '../../../common/drain/drain';
+import { registerHandler } from '../../../common/event-emitter/register-handler';
+import { HarvestScheduler } from '../../../common/harvest/harvest-scheduler';
+import { FEATURE_NAME } from '../constants';
+import { stringify } from '../../../common/util/stringify';
+import { getConfigurationValue, getInfo, getRuntime } from '../../../common/config/config';
+import { SESSION_EVENTS } from '../../../common/session/session-entity';
+import { AggregateBase } from '../../utils/aggregate-base';
+
+// would be better to get this dynamically in some way
+export const RRWEB_VERSION = '2.0.0-alpha.8';
+let recorder, gzipper, u8;
+
+/** The "mode" with which the session replay is recording */
+const MODE = {
+  OFF: 0,
+  FULL: 1,
+  ERROR: 2
+};
+/** Vortex caps payload sizes at 1MB */
+const MAX_PAYLOAD_SIZE = 1000000;
+/** Unloading caps around 64kb */
+const IDEAL_PAYLOAD_SIZE = 64000;
+/** Interval between forcing new full snapshots in "error" mode */
+const CHECKOUT_MS = 30000;
+export class Aggregate extends AggregateBase {
+  static featureName = FEATURE_NAME;
+  constructor(agentIdentifier, aggregator) {
+    super(agentIdentifier, aggregator, FEATURE_NAME);
+
+    /** Each page mutation or event will be stored (raw) in this array. This array will be cleared on each harvest */
+    this.events = [];
+    /** The interval to harvest at.  This gets overridden if the size of the payload exceeds certain thresholds */
+    this.harvestTimeSeconds = getConfigurationValue(this.agentIdentifier, 'session_replay.harvestTimeSeconds') || 60;
+    /** Set once the recorder has fully initialized after flag checks and sampling */
+    this.initialized = false;
+    /** Set once an error has been detected on the page. */
+    this.errorNoticed = false;
+    /** The "mode" to record in.  Defaults to "OFF" until flags and sampling are checked. See "MODE" constant. */
+    this.mode = MODE.OFF;
+    /** Set once the feature has been "aborted" to prevent other side-effects from continuing */
+    this.blocked = false;
+
+    /** Payload metadata -- Should indicate that the payload being sent is the first of a session */
+    this.isFirstChunk = false;
+    /** Payload metadata -- Should indicate that the payload being sent has a full DOM snapshot. This can happen
+     * -- When the recording library begins recording, it starts by taking a DOM snapshot
+     * -- When visibility changes from "hidden" -> "visible", it must capture a full snapshot for the replay to work correctly across tabs
+    */
+    this.hasSnapshot = false;
+    /** Payload metadata -- Should indicate that the payload being sent contains an error.  Used for query/filter purposes in UI */
+    this.hasError = false;
+
+    /** A value which increments with every new mutation node reported. Resets after a harvest is sent */
+    this.payloadBytesEstimation = 0;
+
+    /** The method to stop recording. This defaults to a noop, but is overwritten once the recording library is imported and initialized */
+    this.stopRecording = () => {/* no-op until set by rrweb initializer */};
+
+    // The SessionEntity class can emit a message indicating the session was cleared and reset (expiry, inactivity). This feature must abort and never resume if that occurs.
+    this.ee.on('session-reset', () => {
+      this.abort();
+    });
+
+    // The SessionEntity class can emit a message indicating the session was paused (visibility change). This feature must stop recording if that occurs.
+    this.ee.on(SESSION_EVENTS.PAUSE, () => {
+      this.stopRecording();
+    });
+    // The SessionEntity class can emit a message indicating the session was resumed (visibility change). This feature must start running again (if already running) if that occurs.
+    this.ee.on(SESSION_EVENTS.RESUME, () => {
+      if (!this.initialized || this.mode === MODE.OFF) return;
+      this.startRecording();
+      this.takeFullSnapshot();
+    });
+
+    // Bespoke logic for new endpoint.  This will change as downstream dependencies become solidified.
+    this.scheduler = new HarvestScheduler('blob', {
+      onFinished: this.onHarvestFinished.bind(this),
+      retryDelay: this.harvestTimeSeconds,
+      getPayload: this.prepareHarvest.bind(this),
+      // TODO -- this stuff needs a better way to be handled
+      includeBaseParams: false,
+      customUrl: 'https://vortex-alb.stg-single-tooth.cell.us.nr-data.net/blob',
+      raw: true,
+      gzip: true
+    }, this);
+
+    // Wait for an error to be reported.  This currently is wrapped around the "Error" feature.  This is a feature-feature dependency.
+    // This was to ensure that all errors, including those on the page before load and those handled with "noticeError" are accounted for. Needs evalulation
+    registerHandler('errorAgg', e => {
+      this.hasError = true;
+      // run once
+      if (this.mode === MODE.ERROR) {
+        this.mode = MODE.FULL;
+        // if the error was noticed AFTER the recorder was already imported....
+        if (recorder && this.initialized) {
+          this.stopRecording();
+          this.startRecording();
+          this.scheduler.startTimer(this.harvestTimeSeconds);
+          const {
+            session
+          } = getRuntime(this.agentIdentifier);
+          session.state.sessionReplay = this.mode;
+        }
+      }
+    }, this.featureName, this.ee);
+
+    // new handler for waiting for multiple flags.  will be useful if/when backend designs multiple flags, or for evaluating multiple feature flags simultaneously (stn vs sr)
+    this.waitForFlags(['sr']).then(_ref => {
+      let [{
+        value
+      }] = _ref;
+      this.initializeRecording(value, Math.random() < getConfigurationValue(this.agentIdentifier, 'session_replay.errorSampleRate'), Math.random() < getConfigurationValue(this.agentIdentifier, 'session_replay.sampleRate'));
+    });
+    drain(this.agentIdentifier, this.featureName);
+  }
+
+  /**
+   * Evaluate entitlements and sampling before starting feature mechanics, importing and configuring recording library, and setting storage state
+   * @param {boolean} entitlements - the true/false state of the "sr" flag from RUM response
+   * @param {boolean} errorSample - the true/false state of the error sampling decision
+   * @param {boolean} fullSample - the true/false state of the full sampling decision
+   * @returns {void}
+   */
+  async initializeRecording(entitlements, errorSample, fullSample) {
+    this.initialized = true;
+    if (!entitlements) return;
+    const {
+      session
+    } = getRuntime(this.agentIdentifier);
+    // if theres an existing session replay in progress, there's no need to sample, just check the entitlements response
+    // if not, these sample flags need to be checked
+    // if this isnt the FIRST load of a session AND
+    // we are not actively recording SR... DO NOT import or run the recording library
+    // session replay samples can only be decided on the first load of a session
+    // session replays can continue if already in progress
+    if (!session.isNew) {
+      // inherit the mode of the existing session
+      this.mode = session.state.sessionReplay;
+    } else {
+      // The session is new... determine the mode the new session should start in
+      if (fullSample) this.mode = MODE.FULL; // full mode has precedence over error mode
+      else if (errorSample) this.mode = MODE.ERROR;
+      // If neither are selected, then don't record (early return)
+      return;
+    }
+
+    // FULL mode records AND reports from the beginning, while ERROR mode only records (but does not report).
+    // ERROR mode will do this until an error is thrown, and then switch into FULL mode.
+    // If an error happened in ERROR mode before we've gotten to this stage, it will have already set the mode to FULL
+    if (this.mode === MODE.FULL) {
+      // We only report (harvest) in FULL mode
+      this.scheduler.startTimer(this.harvestTimeSeconds);
+    }
+    // We record in FULL or ERROR mode
+
+    recorder = (await import( /* webpackChunkName: "recorder" */'rrweb')).record;
+    this.startRecording();
+    const {
+      gzipSync,
+      strToU8
+    } = await import( /* webpackChunkName: "compressor" */'fflate');
+    gzipper = gzipSync;
+    u8 = strToU8;
+    this.isFirstChunk = !!session.isNew;
+    session.state.sessionReplay = this.mode;
+  }
+  prepareHarvest(options) {
+    if (this.events.length === 0) return;
+    const payload = this.getHarvestContents();
+    try {
+      payload.body = gzipper(u8(stringify(payload.body)));
+      this.scheduler.opts.gzip = true;
+    } catch (err) {
+      // failed to gzip
+      this.scheduler.opts.gzip = false;
+    }
+    // TODO -- Gracefully handle the buffer for retries.
+    this.clearBuffer();
+    return [payload];
+  }
+  getHarvestContents() {
+    const agentRuntime = getRuntime(this.agentIdentifier);
+    const info = getInfo(this.agentIdentifier);
+    return {
+      qs: {
+        protocol_version: '0'
+      },
+      body: {
+        type: 'SessionReplay',
+        appId: Number(info.applicationID),
+        timestamp: Date.now(),
+        blob: JSON.stringify(this.events),
+        // this needs to be a stringified JSON array of rrweb nodes
+        attributes: {
+          session: agentRuntime.session.state.value,
+          hasSnapshot: this.hasSnapshot,
+          hasError: this.hasError,
+          agentVersion: agentRuntime.version,
+          isFirstChunk: this.isFirstChunk,
+          'nr.rrweb.version': RRWEB_VERSION
+        }
+      }
+    };
+  }
+  onHarvestFinished(result) {
+    // The mutual decision for now is to stop recording and clear buffers if ingest is experiencing 429 rate limiting
+    if (result.status === 429) {
+      this.abort();
+    }
+    if (this.blocked) this.scheduler.stopTimer(true);
+  }
+
+  /** Clears the buffer (this.events), and resets all payload metadata properties */
+  clearBuffer() {
+    this.events = [];
+    this.isFirstChunk = false;
+    this.hasSnapshot = false;
+    this.hasError = false;
+    this.payloadBytesEstimation = 0;
+  }
+
+  /** Begin recording using configured recording lib */
+  startRecording() {
+    if (!recorder) {
+      warn('Recording library was never imported');
+      return this.abort();
+    }
+    const {
+      blockClass,
+      ignoreClass,
+      maskTextClass,
+      blockSelector,
+      maskInputOptions,
+      maskTextSelector,
+      maskAllInputs
+    } = getConfigurationValue(this.agentIdentifier, 'session_replay');
+    this.hasSnapshot = true;
+    // set up rrweb configurations for maximum privacy --
+    // https://newrelic.atlassian.net/wiki/spaces/O11Y/pages/2792293280/2023+02+28+Browser+-+Session+Replay#Configuration-options
+    this.stopRecording = recorder({
+      emit: this.store.bind(this),
+      blockClass,
+      ignoreClass,
+      maskTextClass,
+      blockSelector,
+      maskInputOptions,
+      maskTextSelector,
+      maskAllInputs,
+      ...(this.mode === MODE.ERROR && {
+        checkoutEveryNms: CHECKOUT_MS
+      })
+    });
+  }
+
+  /** Store a payload in the buffer (this.events).  This should be the callback to the recording lib noticing a mutation */
+  store(event, isCheckout) {
+    if (this.blocked) return;
+    const eventBytes = stringify(event).length;
+    /** The estimated size of the payload after compression */
+    const payloadSize = this.getPayloadSize(eventBytes);
+    // Vortex will block payloads at a certain size, we might as well not send.
+    if (payloadSize > MAX_PAYLOAD_SIZE) {
+      return this.abort();
+    }
+    // Checkout events are flags by the recording lib that indicate a fullsnapshot was taken every n ms. These are important
+    // to help reconstruct the replay later and must be included.  While waiting and buffering for errors to come through,
+    // each time we see a new checkout, we can drop the old data.
+    if (this.mode === MODE.ERROR && isCheckout) {
+      // we are still waiting for an error to throw, so keep wiping the buffer over time
+      this.clearBuffer();
+    }
+    this.events.push(event);
+    this.payloadBytesEstimation += eventBytes;
+
+    // We are making an effort to try to keep payloads manageable for unloading.  If they reach the unload limit before their interval,
+    // it will send immediately.  This often happens on the first snapshot, which can be significantly larger than the other payloads.
+    if (payloadSize > IDEAL_PAYLOAD_SIZE) {
+      // if we've made it to the ideal size of ~64kb before the interval timer, we should send early.
+      this.scheduler.runHarvest();
+    }
+  }
+
+  /** force the recording lib to take a full DOM snapshot.  This needs to occur in certain cases, like visibility changes */
+  takeFullSnapshot() {
+    if (!recorder) return;
+    recorder.takeFullSnapshot();
+    this.hasSnapshot = true;
+  }
+
+  /** Estimate the payload size */
+  getPayloadSize() {
+    let newBytes = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 0;
+    // the 1KB gives us some padding for the other metadata
+    return this.estimateCompression(this.payloadBytesEstimation + newBytes) + 1000;
+  }
+
+  /** Abort the feature, once aborted it will not resume */
+  abort() {
+    this.blocked = true;
+    this.stopRecording();
+    const {
+      session
+    } = getRuntime(this.agentIdentifier);
+    session.state.sessionReplay = this.mode;
+  }
+
+  /** Extensive research has yielded about an 88% compression factor on these payloads.
+   * This is an estimation using that factor as to not cause performance issues while evaluating
+   * https://staging.onenr.io/037jbJWxbjy
+   * */
+  estimateCompression(data) {
+    return data * 0.12;
+  }
+}

package/dist/esm/features/session_replay/constants.js

@@ -0,0 +1,2 @@
+import { FEATURE_NAMES } from '../../loaders/features/features';
+export const FEATURE_NAME = FEATURE_NAMES.sessionReplay;

package/dist/esm/features/session_replay/index.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2023 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file The top-level entry point for the eventual Session Replay feature.
+ *
+ * NOTE: This code is under development and dormant. It will not download to instrumented pages or record any data.
+ * It is not production ready, and is not intended to be imported or implemented in any build of the browser agent until
+ * functionality is validated and a full user experience is curated.
+ */
+export { Instrument as SessionReplay } from './instrument/index';

package/dist/esm/features/session_replay/instrument/index.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2023 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file Primes the Session Replay feature for lazy loading.
+ *
+ * NOTE: This code is under development and dormant. It will not download to instrumented pages or record any data.
+ * It is not production ready, and is not intended to be imported or implemented in any build of the browser agent until
+ * functionality is validated and a full user experience is curated.
+ */
+import { InstrumentBase } from '../../utils/instrument-base';
+import { FEATURE_NAME } from '../constants';
+export class Instrument extends InstrumentBase {
+  static featureName = FEATURE_NAME;
+  constructor(agentIdentifier, aggregator) {
+    let auto = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
+    super(agentIdentifier, aggregator, FEATURE_NAME, auto);
+    this.importAggregator();
+  }
+}