@newrelic/browser-agent 1.249.0 → 1.250.0

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

@@ -9,6 +9,7 @@
  * 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 { MODE } from '../../../common/session/constants'
 import { InstrumentBase } from '../../utils/instrument-base'
 import { FEATURE_NAME } from '../constants'
 
@@ -16,6 +17,22 @@ export class Instrument extends InstrumentBase {
   static featureName = FEATURE_NAME
   constructor (agentIdentifier, aggregator, auto = true) {
     super(agentIdentifier, aggregator, FEATURE_NAME, auto)
-    this.importAggregator()
+    try {
+      const session = JSON.parse(localStorage.getItem('NRBA_SESSION'))
+      if (session.sessionReplayMode !== MODE.OFF) {
+        this.#startRecording(session.sessionReplayMode)
+      } else {
+        this.importAggregator({})
+      }
+    } catch (err) {
+      this.importAggregator({})
+    }
+  }
+
+  async #startRecording (mode) {
+    const { Recorder } = (await import(/* webpackChunkName: "recorder" */'../shared/recorder'))
+    this.recorder = new Recorder({ mode, agentIdentifier: this.agentIdentifier })
+    this.recorder.startRecording()
+    this.importAggregator({ recorder: this.recorder })
   }
 }

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

@@ -0,0 +1,25 @@
+export class RecorderEvents {
+  constructor () {
+    /** The buffer to hold recorder event nodes */
+    this.events = []
+    /** Payload metadata -- Should indicate when a replay blob started recording.  Resets each time a harvest occurs.
+     * cycle timestamps are used as fallbacks if event timestamps cannot be used
+     */
+    this.cycleTimestamp = Date.now()
+    /** A value which increments with every new mutation node reported. Resets after a harvest is sent */
+    this.payloadBytesEstimation = 0
+    /** 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 has a meta node. The meta node should always precede a snapshot node. */
+    this.hasMeta = false
+    /** Payload metadata -- Should indicate that the payload being sent contains an error.  Used for query/filter purposes in UI */
+    this.hasError = false
+  }
+
+  add (event) {
+    this.events.push(event)
+  }
+}

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

@@ -0,0 +1,145 @@
+import { record as recorder } from 'rrweb'
+import { stringify } from '../../../common/util/stringify'
+import { AVG_COMPRESSION, CHECKOUT_MS, IDEAL_PAYLOAD_SIZE, QUERY_PARAM_PADDING, RRWEB_EVENT_TYPES } from '../constants'
+import { getConfigurationValue } from '../../../common/config/config'
+import { RecorderEvents } from './recorder-events'
+import { MODE } from '../../../common/session/constants'
+
+export class Recorder {
+  /** Each page mutation or event will be stored (raw) in this array. This array will be cleared on each harvest */
+  #events = new RecorderEvents()
+  /** Backlog used for a 2-part sliding window to guarantee a 15-30s buffer window */
+  #backloggedEvents = new RecorderEvents()
+  /** array of recorder events -- Will be filled only if forced harvest was triggered and harvester does not exist */
+  #preloaded = [new RecorderEvents()]
+
+  constructor (parent) {
+    /** True when actively recording, false when paused or stopped */
+    this.recording = false
+    this.currentBufferTarget = this.#events
+    /** 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
+
+    this.parent = parent
+
+    /** 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 */ }
+  }
+
+  getEvents () {
+    if (this.#preloaded[0]?.events.length) return { ...this.#preloaded[0], type: 'preloaded' }
+    return {
+      events: [...this.#backloggedEvents.events, ...this.#events.events].filter(x => x),
+      type: 'standard',
+      cycleTimestamp: Math.min(this.#backloggedEvents.cycleTimestamp, this.#events.cycleTimestamp),
+      payloadBytesEstimation: this.#backloggedEvents.payloadBytesEstimation + this.#events.payloadBytesEstimation,
+      hasError: this.#backloggedEvents.hasError || this.#events.hasError,
+      hasMeta: this.#backloggedEvents.hasMeta || this.#events.hasMeta,
+      hasSnapshot: this.#backloggedEvents.hasSnapshot || this.#events.hasSnapshot
+    }
+  }
+
+  /** Clears the buffer (this.#events), and resets all payload metadata properties */
+  clearBuffer () {
+    if (this.#preloaded[0]?.events.length) this.#preloaded.shift()
+    else if (this.parent.mode === MODE.ERROR) this.#backloggedEvents = this.#events
+    else this.#backloggedEvents = new RecorderEvents()
+    this.#events = new RecorderEvents()
+  }
+
+  /** Begin recording using configured recording lib */
+  startRecording () {
+    this.recording = true
+    const { block_class, ignore_class, mask_text_class, block_selector, mask_input_options, mask_text_selector, mask_all_inputs, inline_stylesheet, inline_images, collect_fonts } = getConfigurationValue(this.parent.agentIdentifier, '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
+    const stop = recorder({
+      emit: this.store.bind(this),
+      blockClass: block_class,
+      ignoreClass: ignore_class,
+      maskTextClass: mask_text_class,
+      blockSelector: block_selector,
+      maskInputOptions: mask_input_options,
+      maskTextSelector: mask_text_selector,
+      maskAllInputs: mask_all_inputs,
+      inlineStylesheet: inline_stylesheet,
+      inlineImages: inline_images,
+      collectFonts: collect_fonts,
+      checkoutEveryNms: CHECKOUT_MS[this.parent.mode]
+    })
+
+    this.stopRecording = () => {
+      this.recording = false
+      stop()
+    }
+  }
+
+  /** Store a payload in the buffer (this.#events).  This should be the callback to the recording lib noticing a mutation */
+  store (event, isCheckout) {
+    event.__serialized = stringify(event)
+
+    if (!this.parent.scheduler) this.currentBufferTarget = this.#preloaded[this.#preloaded.length - 1]
+    else this.currentBufferTarget = this.#events
+
+    if (this.parent.blocked) return
+    const eventBytes = event.__serialized.length
+    /** The estimated size of the payload after compression */
+    const payloadSize = this.getPayloadSize(eventBytes)
+    // 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.
+    // 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) {
+      // we are still waiting for an error to throw, so keep wiping the buffer over time
+      this.clearBuffer()
+    }
+
+    // meta event
+    if (event.type === RRWEB_EVENT_TYPES.Meta) {
+      this.currentBufferTarget.hasMeta = true
+    }
+    // snapshot event
+    if (event.type === RRWEB_EVENT_TYPES.FullSnapshot) {
+      this.currentBufferTarget.hasSnapshot = true
+    }
+
+    this.currentBufferTarget.add(event)
+    this.currentBufferTarget.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 && this.parent.mode !== MODE.ERROR) {
+      // if we've made it to the ideal size of ~64kb before the interval timer, we should send early.
+      if (this.parent.scheduler) {
+        this.parent.scheduler.runHarvest()
+      } else {
+        // we are still in "preload" and it triggered a "stop point".  Make a new set, which will get pointed at on next cycle
+        this.#preloaded.push(new RecorderEvents())
+      }
+    }
+  }
+
+  /** force the recording lib to take a full DOM snapshot.  This needs to occur in certain cases, like visibility changes */
+  takeFullSnapshot () {
+    recorder.takeFullSnapshot()
+  }
+
+  clearTimestamps () {
+    this.currentBufferTarget.cycleTimestamp = undefined
+  }
+
+  /** Estimate the payload size */
+  getPayloadSize (newBytes = 0) {
+    // the query param padding constant gives us some padding for the other metadata to be safely injected
+    return this.estimateCompression(this.currentBufferTarget.payloadBytesEstimation + newBytes) + QUERY_PARAM_PADDING
+  }
+
+  /** 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) {
+    if (this.shouldCompress) return data * AVG_COMPRESSION
+    return data
+  }
+}

package/src/features/session_replay/{replay-mode.js → shared/replay-mode.js}

@@ -1,7 +1,7 @@
-import { getConfigurationValue } from '../../common/config/config'
-import { MODE } from '../../common/session/session-entity'
-import { gosNREUM } from '../../common/window/nreum'
-import { sharedChannel } from '../../common/constants/shared-channel'
+import { getConfigurationValue } from '../../../common/config/config'
+import { gosNREUM } from '../../../common/window/nreum'
+import { sharedChannel } from '../../../common/constants/shared-channel'
+import { MODE } from '../../../common/session/constants'
 
 /**
  * Figure out if the Replay feature is running (what mode it's in).

package/src/features/session_trace/aggregate/index.js

@@ -9,9 +9,9 @@ import { getConfigurationValue, getRuntime } from '../../../common/config/config
 import { now } from '../../../common/timing/now'
 import { FEATURE_NAME } from '../constants'
 import { HandlerCache } from '../../utils/handler-cache'
-import { MODE, SESSION_EVENTS } from '../../../common/session/session-entity'
-import { getSessionReplayMode } from '../../session_replay/replay-mode'
+import { getSessionReplayMode } from '../../session_replay/shared/replay-mode'
 import { AggregateBase } from '../../utils/aggregate-base'
+import { MODE, SESSION_EVENTS } from '../../../common/session/constants'
 
 const ignoredEvents = {
   // we find that certain events make the data too noisy to be useful

package/dist/types/features/session_replay/replay-mode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"replay-mode.d.ts","sourceRoot":"","sources":["../../../../src/features/session_replay/replay-mode.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,oEAUC"}