@newrelic/browser-agent 1.297.0-rc.2 → 1.297.0-rc.3

package/src/features/session_replay/instrument/index.js

@@ -16,9 +16,11 @@ import { setupPauseReplayAPI } from '../../../loaders/api/pauseReplay'
 
 export class Instrument extends InstrumentBase {
   static featureName = FEATURE_NAME
+  /** @type {Promise|undefined} A promise that resolves when the recorder module is imported and added to the class. Undefined if the recorder has never been staged to import with `importRecorder`. */
+  #stagedImport
+  /** The RRWEB recorder instance, if imported */
+  recorder
 
-  #mode
-  #agentRef
   constructor (agentRef) {
     super(agentRef, FEATURE_NAME)
 
@@ -27,7 +29,6 @@ export class Instrument extends InstrumentBase {
     setupPauseReplayAPI(agentRef)
 
     let session
-    this.#agentRef = agentRef
     try {
       session = JSON.parse(localStorage.getItem(`${PREFIX}_${DEFAULT_KEY}`))
     } catch (err) { }
@@ -37,15 +38,17 @@ export class Instrument extends InstrumentBase {
     }
 
     if (this.#canPreloadRecorder(session)) {
-      this.#mode = session?.sessionReplayMode
-      this.#preloadStartRecording()
-    } else {
-      this.importAggregator(this.#agentRef, () => import(/* webpackChunkName: "session_replay-aggregate" */ '../aggregate'))
+      this.importRecorder().then(recorder => {
+        recorder.startRecording(TRIGGERS.PRELOAD, session?.sessionReplayMode)
+      }) // could handle specific fail-state behaviors with a .catch block here
     }
 
+    this.importAggregator(this.agentRef, () => import(/* webpackChunkName: "session_replay-aggregate" */ '../aggregate'), this)
+
     /** If the recorder is running, we can pass error events on to the agg to help it switch to full mode later */
     this.ee.on('err', (e) => {
-      if (this.#agentRef.runtime.isRecording) {
+      if (this.blocked) return
+      if (this.agentRef.runtime.isRecording) {
         this.errorNoticed = true
         handle(SR_EVENT_EMITTER_TYPES.ERROR_DURING_REPLAY, [e], undefined, this.featureName, this.ee)
       }
@@ -57,54 +60,50 @@ export class Instrument extends InstrumentBase {
     if (!session) { // this might be a new session if entity initializes: conservatively start recording if first-time config allows
       // Note: users with SR enabled, as well as these other configs enabled by-default, will be penalized by the recorder overhead EVEN IF they don't actually have or get
       // entitlement or sampling decision, or otherwise intentionally opted-in for the feature.
-      return isPreloadAllowed(this.#agentRef.init)
+      return isPreloadAllowed(this.agentRef.init)
     } else if (session.sessionReplayMode === MODE.FULL || session.sessionReplayMode === MODE.ERROR) {
       return true // existing sessions get to continue recording, regardless of this page's configs or if it has expired (conservatively)
     } else { // SR mode was OFF but may potentially be turned on if session resets and configs allows the new session to have replay...
-      return isPreloadAllowed(this.#agentRef.init)
+      return isPreloadAllowed(this.agentRef.init)
     }
   }
 
-  #alreadyStarted = false
   /**
-   * This func is use for early pre-load recording prior to replay feature (agg) being loaded onto the page. It should only setup once, including if already called and in-progress.
+   * Returns a promise that imports the recorder module. Only lets the recorder module be imported and instantiated once. Rejects if failed to import/instantiate.
+   * @returns {Promise}
    */
-  async #preloadStartRecording (trigger) {
-    if (this.#alreadyStarted) return
-    this.#alreadyStarted = true
-
-    try {
-      const { Recorder } = (await import(/* webpackChunkName: "recorder" */'../shared/recorder'))
+  importRecorder () {
+    /** if we already have a recorder fully set up, just return it */
+    if (this.recorder) return Promise.resolve(this.recorder)
+    /** conditional -- if we have never started importing, stage the import and store it in state */
+    this.#stagedImport ??= import(/* webpackChunkName: "recorder" */'../shared/recorder')
+      .then(({ Recorder }) => {
+        this.recorder = new Recorder(this)
+        /** return the recorder for promise chaining */
+        return this.recorder
+      })
+      .catch(err => {
+        this.ee.emit('internal-error', [err])
+        this.blocked = true
+        /** return the err for promise chaining */
+        throw err
+      })
 
-      // If startReplay() has been used by this point, we must record in full mode regardless of session preload:
-      // Note: recorder starts here with w/e the mode is at this time, but this may be changed later (see #apiStartOrRestartReplay else-case)
-      this.recorder ??= new Recorder({ ...this, mode: this.#mode, agentRef: this.#agentRef, trigger, timeKeeper: this.#agentRef.runtime.timeKeeper }) // if TK exists due to deferred state, pass it
-      this.recorder.startRecording()
-      this.abortHandler = this.recorder.stopRecording
-    } catch (err) {
-      this.parent.ee.emit('internal-error', [err])
-    }
-    this.importAggregator(this.#agentRef, () => import(/* webpackChunkName: "session_replay-aggregate" */ '../aggregate'), { recorder: this.recorder, errorNoticed: this.errorNoticed })
+    return this.#stagedImport
   }
 
   /**
    * Called whenever startReplay API is used. That could occur any time, pre or post load.
    */
   #apiStartOrRestartReplay () {
+    if (this.blocked) return
     if (this.featAggregate) { // post-load; there's possibly already an ongoing recording
-      if (this.featAggregate.mode !== MODE.FULL) this.featAggregate.initializeRecording(MODE.FULL, true)
-    } else { // pre-load
-      this.#mode = MODE.FULL
-      this.#preloadStartRecording(TRIGGERS.API)
-      // There's a race here wherein either:
-      // a. Recorder has not been initialized, and we've set the enforced mode, so we're good, or;
-      // b. Record has been initialized, possibly with the "wrong" mode, so we have to correct that + restart.
-      if (this.recorder && this.recorder.parent.mode !== MODE.FULL) {
-        this.recorder.parent.mode = MODE.FULL
-        this.recorder.stopRecording()
-        this.recorder.startRecording()
-        this.abortHandler = this.recorder.stopRecording
-      }
+      if (this.featAggregate.mode !== MODE.FULL) this.featAggregate.initializeRecording(MODE.FULL, true, TRIGGERS.API)
+    } else {
+      this.importRecorder()
+        .then(() => {
+          this.recorder.startRecording(TRIGGERS.API, MODE.FULL)
+        }) // could handle specific fail-state behaviors with a .catch block here
     }
   }
 }

package/src/features/session_replay/shared/recorder.js

@@ -12,7 +12,7 @@ import { handle } from '../../../common/event-emitter/handle'
 import { SUPPORTABILITY_METRIC_CHANNEL } from '../../metrics/constants'
 import { FEATURE_NAMES } from '../../../loaders/features/features'
 import { customMasker } from './utils'
-import { IDEAL_PAYLOAD_SIZE } from '../../../common/constants/agent-constants'
+import { IDEAL_PAYLOAD_SIZE, SESSION_ERROR } from '../../../common/constants/agent-constants'
 import { warn } from '../../../common/util/console'
 import { single } from '../../../common/util/invoke'
 import { registerHandler } from '../../../common/event-emitter/register-handler'
@@ -25,11 +25,21 @@ export class Recorder {
 
   #warnCSSOnce = single(() => warn(47)) // notifies user of potential replayer issue if fix_stylesheets is off
 
-  constructor (parent) {
-    /** The parent class that instantiated the recorder */
-    this.parent = parent
+  #canRecord = true
+
+  triggerHistory = [] // useful for debugging
+
+  constructor (srInstrument) {
+    /** The parent classes that share the recorder */
+    this.srInstrument = srInstrument
+    // --- shortcuts
+    this.ee = srInstrument.ee
+    this.srFeatureName = srInstrument.featureName
+    this.agentRef = srInstrument.agentRef
+
+    this.isErrorMode = false
     /** A flag that can be set to false by failing conversions to stop the fetching process */
-    this.shouldFix = this.parent.agentRef.init.session_replay.fix_stylesheets
+    this.shouldFix = this.agentRef.init.session_replay.fix_stylesheets
 
     /** Each page mutation or event will be stored (raw) in this array. This array will be cleared on each harvest */
     this.events = new RecorderEvents(this.shouldFix)
@@ -40,9 +50,18 @@ export class Recorder {
     /** Hold on to the last meta node, so that it can be re-inserted if the meta and snapshot nodes are broken up due to harvesting */
     this.lastMeta = false
     /** The method to stop recording. This defaults to a noop, but is overwritten once the recording library is imported and initialized */
-    this.stopRecording = () => { this.parent.agentRef.runtime.isRecording = false }
+    this.stopRecording = () => { this.agentRef.runtime.isRecording = false }
 
-    registerHandler(RRWEB_DATA_CHANNEL, (event, isCheckout) => { this.audit(event, isCheckout) }, this.parent.featureName, this.parent.ee)
+    registerHandler(SESSION_ERROR, () => {
+      this.#canRecord = false
+      this.stopRecording()
+    }, this.srFeatureName, this.ee)
+
+    registerHandler(RRWEB_DATA_CHANNEL, (event, isCheckout) => { this.audit(event, isCheckout) }, this.srFeatureName, this.ee)
+  }
+
+  get trigger () {
+    return this.triggerHistory[this.triggerHistory.length - 1]
   }
 
   getEvents () {
@@ -60,21 +79,29 @@ export class Recorder {
 
   /** Clears the buffer (this.events), and resets all payload metadata properties */
   clearBuffer () {
-    this.backloggedEvents = (this.parent.mode === MODE.ERROR) ? this.events : new RecorderEvents(this.shouldFix)
+    this.backloggedEvents = (this.isErrorMode) ? this.events : new RecorderEvents(this.shouldFix)
     this.events = new RecorderEvents(this.shouldFix)
   }
 
   /** Begin recording using configured recording lib */
-  startRecording () {
-    this.parent.agentRef.runtime.isRecording = true
-    const { block_class, ignore_class, mask_text_class, block_selector, mask_input_options, mask_text_selector, mask_all_inputs, inline_images, collect_fonts } = this.parent.agentRef.init.session_replay
+  startRecording (trigger, mode) {
+    if (!this.#canRecord) return
+    this.triggerHistory.push(trigger) // keep track of all triggers, useful for lifecycle debugging.  "this.trigger" returns the latest entry
+
+    this.isErrorMode = mode === MODE.ERROR
+
+    /** if the recorder is already recording... lets stop it before starting a new one */
+    this.stopRecording()
+
+    this.agentRef.runtime.isRecording = true
+    const { block_class, ignore_class, mask_text_class, block_selector, mask_input_options, mask_text_selector, mask_all_inputs, inline_images, collect_fonts } = this.agentRef.init.session_replay
 
     // set up rrweb configurations for maximum privacy --
     // https://newrelic.atlassian.net/wiki/spaces/O11Y/pages/2792293280/2023+02+28+Browser+-+Session+Replay#Configuration-options
     let stop
     try {
       stop = recorder({
-        emit: (event, isCheckout) => { handle(RRWEB_DATA_CHANNEL, [event, isCheckout], undefined, this.parent.featureName, this.parent.ee) },
+        emit: (event, isCheckout) => { handle(RRWEB_DATA_CHANNEL, [event, isCheckout], undefined, this.srFeatureName, this.ee) },
         blockClass: block_class,
         ignoreClass: ignore_class,
         maskTextClass: mask_text_class,
@@ -87,15 +114,15 @@ export class Recorder {
         inlineStylesheet: true,
         inlineImages: inline_images,
         collectFonts: collect_fonts,
-        checkoutEveryNms: CHECKOUT_MS[this.parent.mode],
+        checkoutEveryNms: CHECKOUT_MS[mode],
         recordAfter: 'DOMContentLoaded'
       })
     } catch (err) {
-      this.parent.ee.emit('internal-error', [err])
+      this.ee.emit('internal-error', [err])
     }
 
     this.stopRecording = () => {
-      this.parent.agentRef.runtime.isRecording = false
+      this.agentRef.runtime.isRecording = false
       stop?.()
     }
   }
@@ -108,14 +135,14 @@ export class Recorder {
    */
   audit (event, isCheckout) {
     /** An count of stylesheet objects that were blocked from accessing contents via JS */
-    const incompletes = this.parent.agentRef.init.session_replay.fix_stylesheets ? stylesheetEvaluator.evaluate() : 0
+    const incompletes = this.agentRef.init.session_replay.fix_stylesheets ? stylesheetEvaluator.evaluate() : 0
     const missingInlineSMTag = 'SessionReplay/Payload/Missing-Inline-Css/'
     /** only run the full fixing behavior (more costly) if fix_stylesheets is configured as on (default behavior) */
     if (!this.shouldFix) {
       if (incompletes > 0) {
         this.events.inlinedAllStylesheets = false
         this.#warnCSSOnce()
-        handle(SUPPORTABILITY_METRIC_CHANNEL, [missingInlineSMTag + 'Skipped', incompletes], undefined, FEATURE_NAMES.metrics, this.parent.ee)
+        handle(SUPPORTABILITY_METRIC_CHANNEL, [missingInlineSMTag + 'Skipped', incompletes], undefined, FEATURE_NAMES.metrics, this.ee)
       }
       return this.store(event, isCheckout)
     }
@@ -128,8 +155,8 @@ export class Recorder {
           this.events.inlinedAllStylesheets = false
           this.shouldFix = false
         }
-        handle(SUPPORTABILITY_METRIC_CHANNEL, [missingInlineSMTag + 'Failed', failedToFix], undefined, FEATURE_NAMES.metrics, this.parent.ee)
-        handle(SUPPORTABILITY_METRIC_CHANNEL, [missingInlineSMTag + 'Fixed', incompletes - failedToFix], undefined, FEATURE_NAMES.metrics, this.parent.ee)
+        handle(SUPPORTABILITY_METRIC_CHANNEL, [missingInlineSMTag + 'Failed', failedToFix], undefined, FEATURE_NAMES.metrics, this.ee)
+        handle(SUPPORTABILITY_METRIC_CHANNEL, [missingInlineSMTag + 'Fixed', incompletes - failedToFix], undefined, FEATURE_NAMES.metrics, this.ee)
         this.takeFullSnapshot()
       })
       /** Only start ignoring data if got a faulty snapshot */
@@ -141,10 +168,10 @@ export class Recorder {
 
   /** Store a payload in the buffer (this.events).  This should be the callback to the recording lib noticing a mutation */
   store (event, isCheckout) {
-    if (!event || this.parent.blocked) return
+    if (!event || this.srInstrument.featAggregate?.blocked) return
 
     /** because we've waited until draining to process the buffered rrweb events, we can guarantee the timekeeper exists */
-    event.timestamp = this.parent.timeKeeper.correctAbsoluteTimestamp(event.timestamp)
+    event.timestamp = this.agentRef.runtime.timeKeeper.correctAbsoluteTimestamp(event.timestamp)
     event.__serialized = stringify(event)
     const eventBytes = event.__serialized.length
     /** The estimated size of the payload after compression */
@@ -153,7 +180,7 @@ export class Recorder {
     // 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.
     // we need to check for meta because rrweb will flag it as checkout twice, once for meta, then once for snapshot
-    if (this.parent.mode === MODE.ERROR && isCheckout && event.type === RRWEB_EVENT_TYPES.Meta) {
+    if (this.isErrorMode && isCheckout && event.type === RRWEB_EVENT_TYPES.Meta) {
       // we are still waiting for an error to throw, so keep wiping the buffer over time
       this.clearBuffer()
     }
@@ -168,16 +195,16 @@ export class Recorder {
 
     // 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 (((this.events.hasSnapshot && this.events.hasMeta) || payloadSize > IDEAL_PAYLOAD_SIZE) && this.parent.mode === MODE.FULL) {
+    if (((this.events.hasSnapshot && this.events.hasMeta) || payloadSize > IDEAL_PAYLOAD_SIZE) && !this.isErrorMode) {
       // if we've made it to the ideal size of ~16kb before the interval timer, we should send early.
-      this.parent.agentRef.runtime.harvester.triggerHarvestFor(this.parent)
+      this.agentRef.runtime.harvester.triggerHarvestFor(this.srInstrument.featAggregate)
     }
   }
 
   /** force the recording lib to take a full DOM snapshot.  This needs to occur in certain cases, like visibility changes */
   takeFullSnapshot () {
     try {
-      if (!this.parent.agentRef.runtime.isRecording) return
+      if (!this.agentRef.runtime.isRecording) return
       recorder.takeFullSnapshot()
     } catch (err) {
       // in the off chance we think we are recording, but rrweb does not, rrweb's lib will throw an error.  This catch is just a precaution
@@ -199,7 +226,7 @@ export class Recorder {
    * https://staging.onenr.io/037jbJWxbjy
    * */
   estimateCompression (data) {
-    if (!!this.parent.gzipper && !!this.parent.u8) return data * AVG_COMPRESSION
+    if (!!this.srInstrument.featAggregate?.gzipper && !!this.srInstrument.featAggregate?.u8) return data * AVG_COMPRESSION
     return data
   }
 }

package/src/features/utils/instrument-base.js

@@ -18,6 +18,8 @@ import { FEATURE_NAMES } from '../../loaders/features/features'
 import { hasReplayPrerequisite } from '../session_replay/shared/utils'
 import { canEnableSessionTracking } from './feature-gates'
 import { single } from '../../common/util/invoke'
+import { SESSION_ERROR } from '../../common/constants/agent-constants'
+import { handle } from '../../common/event-emitter/handle'
 
 /**
  * Base class for instrumenting a feature.
@@ -32,6 +34,8 @@ export class InstrumentBase extends FeatureBase {
   constructor (agentRef, featureName) {
     super(agentRef.agentIdentifier, featureName)
 
+    this.agentRef = agentRef
+
     /** @type {Function | undefined} This should be set by any derived Instrument class if it has things to do when feature fails or is killed. */
     this.abortHandler = undefined
 
@@ -74,7 +78,7 @@ export class InstrumentBase extends FeatureBase {
    * @param {Object} agentRef - reference to the base agent ancestor that this feature belongs to
    * @param {Function} fetchAggregator - a function that returns a promise that resolves to the aggregate module
    * @param {Object} [argsObjFromInstrument] - any values or references to pass down to aggregate
-   * @returns void
+   * @returns
    */
   importAggregator (agentRef, fetchAggregator, argsObjFromInstrument = {}) {
     if (this.featAggregate) return
@@ -99,7 +103,7 @@ export class InstrumentBase extends FeatureBase {
       } catch (e) {
         warn(20, e)
         this.ee.emit('internal-error', [e])
-        if (this.featureName === FEATURE_NAMES.sessionReplay) this.abortHandler?.() // SR should stop recording if session DNE
+        handle(SESSION_ERROR, [e], undefined, this.featureName, this.ee)
       }
 
       /**
@@ -140,6 +144,7 @@ export class InstrumentBase extends FeatureBase {
  * @returns
  */
   #shouldImportAgg (featureName, session, agentInit) {
+    if (this.blocked) return false
     switch (featureName) {
       case FEATURE_NAMES.sessionReplay: // the session manager must be initialized successfully for Replay & Trace features
         return hasReplayPrerequisite(agentInit) && !!session