@newrelic/browser-agent 1.252.0 → 1.253.0

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

@@ -0,0 +1,254 @@
+import { getConfigurationValue } from '../../../common/config/config'
+import { handle } from '../../../common/event-emitter/handle'
+import { registerHandler } from '../../../common/event-emitter/register-handler'
+import { HarvestScheduler } from '../../../common/harvest/harvest-scheduler'
+import { single } from '../../../common/util/invoke'
+import { timeToFirstByte } from '../../../common/vitals/time-to-first-byte'
+import { FEATURE_NAMES } from '../../../loaders/features/features'
+import { SUPPORTABILITY_METRIC_CHANNEL } from '../../metrics/constants'
+import { AggregateBase } from '../../utils/aggregate-base'
+import { API_TRIGGER_NAME, FEATURE_NAME, INTERACTION_STATUS } from '../constants'
+import { AjaxNode } from './ajax-node'
+import { InitialPageLoadInteraction } from './initial-page-load-interaction'
+import { Interaction } from './interaction'
+
+export class Aggregate extends AggregateBase {
+  static featureName = FEATURE_NAME
+  constructor (agentIdentifier, aggregator, { domObserver }) {
+    super(agentIdentifier, aggregator, FEATURE_NAME)
+
+    const harvestTimeSeconds = getConfigurationValue(agentIdentifier, 'soft_navigations.harvestTimeSeconds') || 10
+    this.interactionsToHarvest = []
+    this.interactionsAwaitingRetry = []
+    this.domObserver = domObserver
+
+    this.scheduler = new HarvestScheduler('events', {
+      onFinished: this.onHarvestFinished.bind(this),
+      retryDelay: harvestTimeSeconds,
+      onUnload: () => this.interactionInProgress?.done() // return any held ajax or jserr events so they can be sent with EoL harvest
+    }, { agentIdentifier, ee: this.ee })
+    this.scheduler.harvest.on('events', this.onHarvestStarted.bind(this))
+
+    this.initialPageLoadInteraction = new InitialPageLoadInteraction(agentIdentifier)
+    timeToFirstByte.subscribe(({ entries }) => {
+      const loadEventTime = entries[0].loadEventEnd
+      this.initialPageLoadInteraction.forceSave = true
+      this.initialPageLoadInteraction.done(loadEventTime)
+      this.interactionsToHarvest.push(this.initialPageLoadInteraction)
+      this.initialPageLoadInteraction = null
+      // Report metric on the initial page load time
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/InitialPageLoad/Duration/Ms', Math.round(loadEventTime)], undefined, FEATURE_NAMES.metrics, this.ee)
+    })
+
+    this.latestRouteSetByApi = null
+    this.interactionInProgress = null // aside from the "page load" interaction, there can only ever be 1 ongoing at a time
+
+    this.blocked = false
+    this.waitForFlags(['spa']).then(([spaOn]) => {
+      if (spaOn) this.scheduler.startTimer(harvestTimeSeconds, 0)
+      else this.blocked = true // if rum response determines that customer lacks entitlements for spa endpoint, this feature shouldn't harvest
+    })
+
+    // By default, a complete UI driven interaction requires event -> URL change -> DOM mod in that exact order.
+    registerHandler('newUIEvent', (event) => this.startUIInteraction(event.type, event.timeStamp, event.target), this.featureName, this.ee)
+    registerHandler('newURL', (timestamp, url) => this.interactionInProgress?.updateHistory(timestamp, url), this.featureName, this.ee)
+    registerHandler('newDom', timestamp => {
+      this.interactionInProgress?.updateDom(timestamp)
+      if (this.interactionInProgress?.seenHistoryAndDomChange()) this.interactionInProgress.done()
+    }, this.featureName, this.ee)
+
+    this.#registerApiHandlers()
+
+    registerHandler('ajax', this.#handleAjaxEvent.bind(this), this.featureName, this.ee)
+    registerHandler('jserror', this.#handleJserror.bind(this), this.featureName, this.ee)
+
+    this.drain()
+  }
+
+  onHarvestStarted (options) {
+    if (this.interactionsToHarvest.length === 0 || this.blocked) return
+
+    // The payload depacker takes the first ixn of a payload (if there are multiple ixns) and positively offset the subsequent ixns timestamps by that amount.
+    // In order to accurately portray the real start & end times of the 2nd & onward ixns, we hence need to negatively offset their start timestamps with that of the 1st ixn.
+    let firstIxnStartTime = 0 // the very 1st ixn does not require any offsetting
+    const serializedIxnList = []
+    for (const interaction of this.interactionsToHarvest) {
+      serializedIxnList.push(interaction.serialize(firstIxnStartTime))
+      if (!firstIxnStartTime) firstIxnStartTime = Math.floor(interaction.start)
+    }
+    const payload = `bel.7;${serializedIxnList.join(';')}`
+
+    if (options.retry) this.interactionsAwaitingRetry.push(...this.interactionsToHarvest)
+    this.interactionsToHarvest = []
+
+    return { body: { e: payload } }
+  }
+
+  onHarvestFinished (result) {
+    if (result.sent && result.retry && this.interactionsAwaitingRetry.length > 0) {
+      this.interactionsToHarvest = [...this.interactionsAwaitingRetry, ...this.interactionsToHarvest]
+      this.interactionsAwaitingRetry = []
+    }
+  }
+
+  startUIInteraction (eventName, startedAt, sourceElem) { // this is throttled by instrumentation so that it isn't excessively called
+    if (this.interactionInProgress?.createdByApi) return // api-started interactions cannot be disrupted aka cancelled by UI events (and the vice versa applies as well)
+    if (this.interactionInProgress?.done() === false) return
+
+    this.interactionInProgress = new Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi)
+    if (eventName === 'click') {
+      const sourceElemText = getActionText(sourceElem)
+      if (sourceElemText) this.interactionInProgress.customAttributes.actionText = sourceElemText
+    }
+    this.interactionInProgress.cancellationTimer = setTimeout(() => {
+      this.interactionInProgress.done()
+      // Report metric on frequency of cancellation due to timeout for UI ixn
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ['SoftNav/Interaction/TimeOut'], undefined, FEATURE_NAMES.metrics, this.ee)
+    }, 30000) // UI ixn are disregarded after 30 seconds if it's not completed by then
+    this.setClosureHandlers()
+  }
+
+  setClosureHandlers () {
+    this.interactionInProgress.on('finished', () => {
+      const ref = this.interactionInProgress
+      this.interactionsToHarvest.push(this.interactionInProgress)
+      this.interactionInProgress = null
+      this.domObserver.disconnect() // can stop observing whenever our interaction logic completes a cycle
+
+      // Report metric on the ixn duration
+      handle(SUPPORTABILITY_METRIC_CHANNEL, [
+        `SoftNav/Interaction/${ref.newURL !== ref.oldURL ? 'RouteChange' : 'Custom'}/Duration/Ms`,
+        Math.round(ref.end - ref.start)
+      ], undefined, FEATURE_NAMES.metrics, this.ee)
+    })
+    this.interactionInProgress.on('cancelled', () => {
+      this.interactionInProgress = null
+      this.domObserver.disconnect()
+    })
+  }
+
+  /**
+   * Find the active interaction (current or past) for a given timestamp. Note that historic lookups mostly only go as far back as the last harvest for this feature.
+   * Also, the caller should check the status of the interaction returned if found via {@link Interaction.status}, if that's pertinent.
+   * TIP: Cancelled (status) interactions are NOT returned!
+   * IMPORTANT: Finished interactions are in queue for next harvest! It's highly recommended that consumer logic be synchronous for safe reference.
+   * @param {DOMHighResTimeStamp} timestamp
+   * @returns An {@link Interaction} or undefined, if no active interaction was found.
+   */
+  getInteractionFor (timestamp) {
+    /* In the sole case wherein there can be two "interactions" overlapping (initialPageLoad + regular route-change),
+      the regular interaction should get precedence in being assigned the "active" interaction in regards to our one-at-a-time model.
+    */
+    if (this.interactionInProgress?.isActiveDuring(timestamp)) return this.interactionInProgress
+    let saveIxn
+    for (let idx = this.interactionsToHarvest.length - 1; idx >= 0; idx--) { // reverse search for the latest completed interaction for efficiency
+      const finishedInteraction = this.interactionsToHarvest[idx]
+      if (finishedInteraction.isActiveDuring(timestamp)) {
+        if (finishedInteraction.trigger !== 'initialPageLoad') return finishedInteraction
+        // It's possible that a complete interaction occurs before page is fully loaded, so we need to consider if a route-change ixn may have overlapped this iPL
+        else saveIxn = finishedInteraction
+      }
+    }
+    if (saveIxn) return saveIxn // if an iPL was determined to be active and no route-change was found active for the same time, then iPL is deemed the one
+    if (this.initialPageLoadInteraction?.isActiveDuring(timestamp)) return this.initialPageLoadInteraction // lowest precedence and also only if it's still in-progress
+    // Time must be when no interaction is happening, so return undefined.
+  }
+
+  /**
+   * Handles or redirect ajax event based on the interaction, if any, that it's tied to.
+   * @param {Object} event see Ajax feature's storeXhr function for object definition
+   */
+  #handleAjaxEvent (event) {
+    const associatedInteraction = this.getInteractionFor(event.startTime)
+    if (!associatedInteraction) { // no interaction was happening when this ajax started, so give it back to Ajax feature for processing
+      handle('returnAjax', [event], undefined, FEATURE_NAMES.ajax, this.ee)
+    } else {
+      if (associatedInteraction.status === INTERACTION_STATUS.FIN) processAjax(this.agentIdentifier, event, associatedInteraction) // tack ajax onto the ixn object awaiting harvest
+      else { // same thing as above, just at a later time -- if the interaction in progress is cancelled, just send the event back to ajax feat unmodified
+        associatedInteraction.on('finished', () => processAjax(this.agentIdentifier, event, associatedInteraction))
+        associatedInteraction.on('cancelled', () => handle('returnAjax', [event], undefined, FEATURE_NAMES.ajax, this.ee))
+      }
+    }
+
+    function processAjax (agentId, event, parentInteraction) {
+      const newNode = new AjaxNode(agentId, event)
+      parentInteraction.addChild(newNode)
+    }
+  }
+
+  /**
+   * Decorate the passed-in params obj with properties relating to any associated interaction at the time of the timestamp.
+   * @param {Object} params reference to the local var instance in Jserrors feature's storeError
+   * @param {DOMHighResTimeStamp} timestamp time the jserror occurred
+   */
+  #handleJserror (params, timestamp) {
+    const associatedInteraction = this.getInteractionFor(timestamp)
+    if (!associatedInteraction) return // do not need to decorate this jserror params
+
+    // Whether the interaction is in-progress or already finished, the id will let jserror buffer it under its index, until it gets the next step instruction.
+    params.browserInteractionId = associatedInteraction.id
+    if (associatedInteraction.status === INTERACTION_STATUS.FIN) {
+      // This information cannot be relayed back via handle() that flushes buffered errs because this is being called by a jserror's handle() per se and before the err is buffered.
+      params._softNavFinished = true // instead, signal that this err can be processed right away without needing to be buffered aka wait for an in-progress ixn
+      params._softNavAttributes = associatedInteraction.customAttributes
+    } else {
+      // These callbacks may be added multiple times for an ixn, but just a single run will deal with all jserrors associated with the interaction.
+      // As such, be cautious not to use the params object since that's tied to one specific jserror and won't affect the rest of them.
+      associatedInteraction.on('finished', single(() =>
+        handle('softNavFlush', [associatedInteraction.id, true, associatedInteraction.customAttributes], undefined, FEATURE_NAMES.jserrors, this.ee)))
+      associatedInteraction.on('cancelled', single(() =>
+        handle('softNavFlush', [associatedInteraction.id, false, undefined], undefined, FEATURE_NAMES.jserrors, this.ee))) // don't take custom attrs from cancelled ixns
+    }
+  }
+
+  #registerApiHandlers () {
+    const INTERACTION_API = 'api-ixn-'
+    const thisClass = this
+
+    registerHandler(INTERACTION_API + 'get', function (time, { waitForEnd } = {}) {
+      // In here, 'this' refers to the EventContext specific to per InteractionHandle instance spawned by each .interaction() api call.
+      // Each api call aka IH instance would therefore retain a reference to either the in-progress interaction *at the time of the call* OR a new api-started interaction.
+      this.associatedInteraction = thisClass.getInteractionFor(time)
+      if (!this.associatedInteraction) {
+        // This new api-driven interaction will be the target of any subsequent .interaction() call, until it is closed by EITHER .end() OR the regular seenHistoryAndDomChange process.
+        this.associatedInteraction = thisClass.interactionInProgress = new Interaction(thisClass.agentIdentifier, API_TRIGGER_NAME, time, thisClass.latestRouteSetByApi)
+        thisClass.setClosureHandlers()
+      }
+      if (waitForEnd === true) this.associatedInteraction.keepOpenUntilEndApi = true
+    }, thisClass.featureName, thisClass.ee)
+    registerHandler(INTERACTION_API + 'end', function (timeNow) { this.associatedInteraction.done(timeNow) }, thisClass.featureName, thisClass.ee)
+    registerHandler(INTERACTION_API + 'save', function () { this.associatedInteraction.forceSave = true }, thisClass.featureName, thisClass.ee)
+    registerHandler(INTERACTION_API + 'ignore', function () { this.associatedInteraction.forceIgnore = true }, thisClass.featureName, thisClass.ee)
+
+    registerHandler(INTERACTION_API + 'getContext', function (time, callback) {
+      if (typeof callback !== 'function') return
+      setTimeout(() => callback(this.associatedInteraction.customDataByApi), 0)
+    }, thisClass.featureName, thisClass.ee)
+    registerHandler(INTERACTION_API + 'onEnd', function (time, callback) {
+      if (typeof callback !== 'function') return
+      this.associatedInteraction.onDone.push(callback)
+    }, thisClass.featureName, thisClass.ee)
+
+    registerHandler(INTERACTION_API + 'actionText', function (time, newActionText) {
+      if (newActionText) this.associatedInteraction.customAttributes.actionText = newActionText
+    }, thisClass.featureName, thisClass.ee)
+    registerHandler(INTERACTION_API + 'setName', function (time, name, trigger) {
+      if (name) this.associatedInteraction.customName = name
+      if (trigger) this.associatedInteraction.trigger = trigger
+    }, thisClass.featureName, thisClass.ee)
+    registerHandler(INTERACTION_API + 'setAttribute', function (time, key, value) { this.associatedInteraction.customAttributes[key] = value }, thisClass.featureName, thisClass.ee)
+
+    registerHandler(INTERACTION_API + 'routeName', function (time, newRouteName) { // notice that this fn tampers with the ixn IP, not with the linked ixn
+      thisClass.latestRouteSetByApi = newRouteName
+      if (thisClass.interactionInProgress) thisClass.interactionInProgress.newRoute = newRouteName
+    }, thisClass.featureName, thisClass.ee)
+  }
+}
+
+function getActionText (elem) {
+  const tagName = elem.tagName.toLowerCase()
+  const elementsOfInterest = ['a', 'button', 'input']
+  if (elementsOfInterest.includes(tagName)) {
+    return elem.title || elem.value || elem.innerText
+  }
+}

package/src/features/soft_navigations/aggregate/initial-page-load-interaction.js

@@ -0,0 +1,53 @@
+import { navTimingValues } from '../../../common/timing/nav-timing'
+import { Interaction } from './interaction'
+import { numeric } from '../../../common/serialize/bel-serializer'
+import { firstPaint } from '../../../common/vitals/first-paint'
+import { firstContentfulPaint } from '../../../common/vitals/first-contentful-paint'
+import { getInfo } from '../../../common/config/config'
+
+export class InitialPageLoadInteraction extends Interaction {
+  constructor (agentIdentifier) {
+    super(agentIdentifier, 'initialPageLoad', 0, null)
+    const agentInfo = getInfo(agentIdentifier)
+    this.queueTime = agentInfo.queueTime
+    this.appTime = agentInfo.applicationTime
+  }
+
+  get firstPaint () { return firstPaint.current.value }
+  get firstContentfulPaint () { return firstContentfulPaint.current.value }
+
+  /**
+   * Build the navTiming node. This assumes the navTimingValues array in nav-timing.js has already been filled with values via the PageViewEvent feature having
+   * executed the addPT function first and foremost.
+   */
+  get navTiming () {
+    if (!navTimingValues.length) return
+    /*
+    1. we initialize the seperator to ',' (seperates the nodeType id from the first value)
+    2. we initialize the navTiming node to 'b' (the nodeType id)
+    3. if the value is present, we add the seperator followed by the value;
+       otherwise:
+        - we add null seperator ('!') to the navTimingNode
+        - we set the seperator to an empty string since we already wrote it above
+      the reason for writing the null seperator instead of setting the seperator
+      is to ensure we still write it if the null is the last navTiming value.
+    */
+    let seperator = ','
+    let navTimingNode = 'b'
+    let prev = 0
+
+    // Get all navTiming values except offset aka timeOrigin since we just consider that (this.start) 0.
+    // These are the latter 20 of the 21 timings appended by addPT:
+    navTimingValues.slice(1, 21).forEach(v => {
+      if (v !== undefined) {
+        navTimingNode += seperator + numeric(v - prev)
+        seperator = ','
+        prev = v
+      } else {
+        navTimingNode += seperator + '!'
+        seperator = ''
+      }
+    })
+    return navTimingNode
+  }
+}

package/src/features/soft_navigations/aggregate/interaction.js

@@ -0,0 +1,159 @@
+import { getInfo } from '../../../common/config/config'
+import { globalScope, initialLocation } from '../../../common/constants/runtime'
+import { generateUuid } from '../../../common/ids/unique-id'
+import { addCustomAttributes, getAddStringContext, nullable, numeric } from '../../../common/serialize/bel-serializer'
+import { cleanURL } from '../../../common/url/clean-url'
+import { NODE_TYPE, INTERACTION_STATUS, INTERACTION_TYPE, API_TRIGGER_NAME } from '../constants'
+import { BelNode } from './bel-node'
+
+/**
+ * link https://github.com/newrelic/nr-querypack/blob/main/schemas/bel/7.qpschema
+ **/
+export class Interaction extends BelNode {
+  id = generateUuid() // unique id that is serialized and used to link interactions with errors
+  initialPageURL = initialLocation
+  oldURL = '' + globalScope?.location
+  newURL = '' + globalScope?.location
+  customName
+  customAttributes = {}
+  customDataByApi = {}
+  queueTime // only used by initialPageLoad interactions
+  appTime // only used by initialPageLoad interactions
+  newRoute
+  /** Internal state of this interaction: in-progress, finished, or cancelled. */
+  status = INTERACTION_STATUS.IP
+  domTimestamp = 0
+  historyTimestamp = 0
+  createdByApi = false
+  keepOpenUntilEndApi = false
+  onDone = []
+  cancellationTimer
+
+  constructor (agentIdentifier, uiEvent, uiEventTimestamp, currentRouteKnown) {
+    super(agentIdentifier)
+    this.belType = NODE_TYPE.INTERACTION
+    this.trigger = uiEvent
+    this.start = uiEventTimestamp
+    this.oldRoute = currentRouteKnown
+    this.eventSubscription = new Map([
+      ['finished', []],
+      ['cancelled', []]
+    ])
+    this.forceSave = this.forceIgnore = false
+    if (this.trigger === API_TRIGGER_NAME) this.createdByApi = true
+  }
+
+  updateDom (timestamp) {
+    this.domTimestamp = (timestamp || performance.now()) // default timestamp should be precise for accurate isActiveDuring calculations
+  }
+
+  updateHistory (timestamp, newUrl) {
+    this.newURL = newUrl || '' + globalScope?.location
+    this.historyTimestamp = (timestamp || performance.now())
+  }
+
+  seenHistoryAndDomChange () {
+    return this.historyTimestamp > 0 && this.domTimestamp > this.historyTimestamp // URL must change before DOM does
+  }
+
+  on (event, cb) {
+    if (!this.eventSubscription.has(event)) throw new Error('Cannot subscribe to non pre-defined events.')
+    if (typeof cb !== 'function') throw new Error('Must supply function as callback.')
+    this.eventSubscription.get(event).push(cb)
+  }
+
+  done (customEndTime) {
+    // User could've mark this interaction--regardless UI or api started--as "don't close until .end() is called on it". Only .end provides a timestamp; the default flows do not.
+    if (this.keepOpenUntilEndApi && customEndTime === undefined) return false
+    this.onDone.forEach(apiProvidedCb => apiProvidedCb(this.customDataByApi)) // this interaction's .save or .ignore can still be set by these user provided callbacks for example
+
+    if (this.forceIgnore) this.#cancel() // .ignore() always has precedence over save actions
+    else if (this.seenHistoryAndDomChange()) this.#finish(customEndTime) // then this should've already finished while it was the interactionInProgress, with a natural end time
+    else if (this.forceSave) this.#finish(customEndTime || performance.now()) // a manually saved ixn (did not fulfill conditions) must have a specified end time, if one wasn't provided
+    else this.#cancel()
+    return true
+  }
+
+  #finish (customEndTime = 0) {
+    if (this.status !== INTERACTION_STATUS.IP) return // disallow this call if the ixn is already done aka not in-progress
+    clearTimeout(this.cancellationTimer)
+    this.end = Math.max(this.domTimestamp, this.historyTimestamp, customEndTime)
+    this.customAttributes = { ...getInfo(this.agentIdentifier).jsAttributes, ...this.customAttributes } // attrs specific to this interaction should have precedence over the general custom attrs
+    this.status = INTERACTION_STATUS.FIN
+
+    // Run all the callbacks awaiting this interaction to finish.
+    const callbacks = this.eventSubscription.get('finished')
+    callbacks.forEach(fn => fn())
+  }
+
+  #cancel () {
+    if (this.status !== INTERACTION_STATUS.IP) return // disallow this call if the ixn is already done aka not in-progress
+    clearTimeout(this.cancellationTimer)
+    this.status = INTERACTION_STATUS.CAN
+
+    // Run all the callbacks listening to this interaction's potential cancellation.
+    const callbacks = this.eventSubscription.get('cancelled')
+    callbacks.forEach(fn => fn())
+  }
+
+  /**
+   * Given a timestamp, determine if it falls within this interaction's span, i.e. if this was the active interaction during that time.
+   * For in-progress interactions, this only compares the time with the start of span. Cancelled interactions are not considered active at all.
+   * @param {DOMHighResTimeStamp} timestamp
+   * @returns True or false boolean.
+   */
+  isActiveDuring (timestamp) {
+    if (this.status === INTERACTION_STATUS.IP) return this.start <= timestamp
+    return (this.status === INTERACTION_STATUS.FIN && this.start <= timestamp && this.end >= timestamp)
+  }
+
+  // Following are virtual properties overridden by a subclass:
+  get firstPaint () {}
+  get firstContentfulPaint () {}
+  get navTiming () {}
+
+  serialize (firstStartTimeOfPayload) {
+    const addString = getAddStringContext(this.agentIdentifier)
+    const nodeList = []
+    let ixnType
+    if (this.trigger === 'initialPageLoad') ixnType = INTERACTION_TYPE.INITIAL_PAGE_LOAD
+    else if (this.newURL !== this.oldURL) ixnType = INTERACTION_TYPE.ROUTE_CHANGE
+    else ixnType = INTERACTION_TYPE.UNSPECIFIED
+
+    // IMPORTANT: The order in which addString is called matters and correlates to the order in which string shows up in the harvest payload. Do not re-order the following code.
+    const fields = [
+      numeric(this.belType),
+      0, // this will be overwritten below with number of attached nodes
+      numeric(Math.floor(this.start - firstStartTimeOfPayload)), // relative to first node
+      numeric(Math.floor(this.end - this.start)), // end -- relative to start
+      numeric(this.callbackEnd), // cbEnd -- relative to start; not used by BrowserInteraction events
+      numeric(this.callbackDuration), // not relative
+      addString(this.trigger),
+      addString(cleanURL(this.initialPageURL, true)),
+      addString(cleanURL(this.oldURL, true)),
+      addString(cleanURL(this.newURL, true)),
+      addString(this.customName),
+      ixnType,
+      nullable(this.queueTime, numeric, true) + nullable(this.appTime, numeric, true) +
+      nullable(this.oldRoute, addString, true) + nullable(this.newRoute, addString, true) +
+      addString(this.id),
+      addString(this.nodeId),
+      nullable(this.firstPaint, numeric, true) + nullable(this.firstContentfulPaint, numeric)
+    ]
+    const allAttachedNodes = addCustomAttributes(this.customAttributes || {}, addString) // start with all custom attributes
+    if (getInfo(this.agentIdentifier).atts) allAttachedNodes.push('a,' + addString(getInfo(this.agentIdentifier).atts)) // add apm provided attributes
+    /* Querypack encoder+decoder quirkiness:
+       - If first ixn node of payload is being processed, we use this node's start to offset. (firstStartTime should be 0--or undefined.)
+       - Else for subsequent ixn nodes, we use the first ixn node's start to offset. */
+    this.children.forEach(node => allAttachedNodes.push(node.serialize(firstStartTimeOfPayload || this.start))) // recursively add the serialized string of every child of this (ixn) bel node
+
+    fields[1] = numeric(allAttachedNodes.length)
+    nodeList.push(fields)
+    if (allAttachedNodes.length) nodeList.push(allAttachedNodes.join(';'))
+    if (this.navTiming) nodeList.push(this.navTiming)
+    else nodeList.push('')
+    // nodeList = [<fields array>, <serialized string of all attributes and children>, <serialized nav timing info> || '']
+
+    return nodeList.join(';')
+  }
+}

package/src/features/soft_navigations/constants.js

@@ -0,0 +1,29 @@
+import { FEATURE_NAMES } from '../../loaders/features/features'
+
+export const INTERACTION_TRIGGERS = [
+  'click', // e.g. user clicks link or the page back/forward buttons
+  'keydown', // e.g. user presses left and right arrow key to switch between displayed photo gallery
+  'submit' // e.g. user clicks submit butotn or presses enter while editing a form field
+]
+export const API_TRIGGER_NAME = 'api'
+
+export const FEATURE_NAME = FEATURE_NAMES.softNav
+
+export const INTERACTION_TYPE = {
+  INITIAL_PAGE_LOAD: '',
+  ROUTE_CHANGE: 1,
+  UNSPECIFIED: 2
+}
+
+export const NODE_TYPE = {
+  INTERACTION: 1,
+  AJAX: 2,
+  CUSTOM_END: 3,
+  CUSTOM_TRACER: 4
+}
+
+export const INTERACTION_STATUS = {
+  IP: 'in progress',
+  FIN: 'finished',
+  CAN: 'cancelled'
+}

package/src/features/soft_navigations/index.js

@@ -0,0 +1 @@
+export { Instrument as SoftNav } from './instrument/index'

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

@@ -0,0 +1,67 @@
+import { originals } from '../../../common/config/config'
+import { isBrowserScope } from '../../../common/constants/runtime'
+import { handle } from '../../../common/event-emitter/handle'
+import { windowAddEventListener } from '../../../common/event-listener/event-listener-opts'
+import { now } from '../../../common/timing/now'
+import { debounce } from '../../../common/util/invoke'
+import { wrapEvents, wrapHistory } from '../../../common/wrap'
+import { InstrumentBase } from '../../utils/instrument-base'
+import { FEATURE_NAME, INTERACTION_TRIGGERS } from '../constants'
+
+/** The minimal time after a UI event for which no further events will be processed - i.e. a throttling rate to reduce spam.
+ * This also give some time for the new interaction to complete without being discarded by a subsequent UI event and wrongly attributed.
+ * This value is still subject to change and critique, as it is derived from beyond worst case time to next frame of a page.
+ */
+const UI_WAIT_INTERVAL = 1 / 10 * 1000 // assume 10 fps
+
+export class Instrument extends InstrumentBase {
+  static featureName = FEATURE_NAME
+  constructor (agentIdentifier, aggregator, auto = true) {
+    super(agentIdentifier, aggregator, FEATURE_NAME, auto)
+    if (!isBrowserScope || !originals.MO) return // soft navigations is not supported outside web env or browsers without the mutation observer API
+
+    const historyEE = wrapHistory(this.ee)
+    const eventsEE = wrapEvents(this.ee)
+
+    const trackURLChange = () => handle('newURL', [now(), '' + window.location], undefined, this.featureName, this.ee)
+    historyEE.on('pushState-end', trackURLChange)
+    historyEE.on('replaceState-end', trackURLChange)
+
+    try {
+      this.removeOnAbort = new AbortController()
+    } catch (e) {}
+    const trackURLChangeEvent = (evt) => handle('newURL', [evt.timeStamp, '' + window.location], undefined, this.featureName, this.ee)
+    windowAddEventListener('popstate', trackURLChangeEvent, true, this.removeOnAbort?.signal)
+
+    let oncePerFrame = false // attempt to reduce dom noice since the observer runs very frequently with below options
+    const domObserver = new originals.MO((domChanges, observer) => {
+      if (oncePerFrame) return
+      oncePerFrame = true
+      requestAnimationFrame(() => { // waiting for next frame to time when any visuals are supposedly updated
+        handle('newDom', [now()], undefined, this.featureName, this.ee)
+        oncePerFrame = false
+      })
+    })
+
+    const processUserInteraction = debounce((event) => {
+      handle('newUIEvent', [event], undefined, this.featureName, this.ee)
+      domObserver.observe(document.body, { attributes: true, childList: true, subtree: true, characterData: true })
+    }, UI_WAIT_INTERVAL, { leading: true })
+
+    eventsEE.on('fn-start', ([evt]) => { // set up a new user ixn before the callback for the triggering event executes
+      if (INTERACTION_TRIGGERS.includes(evt?.type)) {
+        processUserInteraction(evt)
+      }
+    })
+    for (let eventType of INTERACTION_TRIGGERS) document.addEventListener(eventType, () => { /* no-op, this ensures the UI events are monitored by our callback above */ })
+
+    this.abortHandler = abort
+    this.importAggregator({ domObserver })
+
+    function abort () {
+      this.removeOnAbort?.abort()
+      domObserver.disconnect()
+      this.abortHandler = undefined // weakly allow this abort op to run only once
+    }
+  }
+}

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

@@ -706,7 +706,7 @@ export class Aggregate extends AggregateBase {
 
     function saveInteraction (interaction) {
       if (interaction.ignored || (!interaction.save && !interaction.routeChange)) {
-        baseEE.emit('interactionDiscarded', [interaction])
+        baseEE.emit('interactionDone', [interaction, false])
         return
       }
 
@@ -724,12 +724,13 @@ export class Aggregate extends AggregateBase {
         interaction.root.attrs.firstPaint = firstPaint.current.value
         interaction.root.attrs.firstContentfulPaint = firstContentfulPaint.current.value
       }
-      baseEE.emit('interactionSaved', [interaction])
+      baseEE.emit('interactionDone', [interaction, true])
       state.interactionsToHarvest.push(interaction)
 
-      let smCategory = 'RouteChange'
+      let smCategory
       if (interaction.root?.attrs?.trigger === 'initialPageLoad') smCategory = 'InitialPageLoad'
-      else if (interaction.root?.attrs?.trigger === 'api') smCategory = 'Custom'
+      else if (interaction.routeChange) smCategory = 'RouteChange'
+      else smCategory = 'Custom'
       handle(SUPPORTABILITY_METRIC_CHANNEL, [`Spa/Interaction/${smCategory}/Duration/Ms`, Math.max((interaction.root?.end || 0) - (interaction.root?.start || 0), 0)], undefined, FEATURE_NAMES.metrics, baseEE)
 
       scheduler.scheduleHarvest(0)

package/src/features/utils/agent-session.js

@@ -5,6 +5,7 @@ import { registerHandler } from '../../common/event-emitter/register-handler'
 import { SessionEntity } from '../../common/session/session-entity'
 import { LocalStorage } from '../../common/storage/local-storage.js'
 import { FirstPartyCookies } from '../../common/storage/first-party-cookies'
+import { DEFAULT_KEY } from '../../common/session/constants'
 
 let ranOnce = 0
 export function setupAgentSession (agentIdentifier) {
@@ -20,7 +21,7 @@ export function setupAgentSession (agentIdentifier) {
 
   agentRuntime.session = new SessionEntity({
     agentIdentifier,
-    key: 'SESSION',
+    key: DEFAULT_KEY,
     storage: storageTypeInst,
     expiresMs: sessionInit?.expiresMs,
     inactiveMs: sessionInit?.inactiveMs