Merge branch 'main' into NR-347721-add-delete-experiment-gha

Author: ptang-nr

CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.277.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.276.0...v1.277.0) (2024-12-18)
+
+
+### Features
+
+* Add custom events API ([#1263](https://github.com/newrelic/newrelic-browser-agent/issues/1263)) ([9395415](https://github.com/newrelic/newrelic-browser-agent/commit/9395415d942b55e88e89438aa203c6a1642d9e6b))
+
+
+### Bug Fixes
+
+* Soft navigation bug fixes and new soft navigation tests ([#1268](https://github.com/newrelic/newrelic-browser-agent/issues/1268)) ([7624928](https://github.com/newrelic/newrelic-browser-agent/commit/762492896a7b96564269aab1aadeb6e44a4da242))
+
 ## [1.276.0](https://github.com/newrelic/newrelic-browser-agent/compare/v1.275.0...v1.276.0) (2024-12-16)
 
 

changelog.json

@@ -1,6 +1,31 @@
 {
   "repository": "newrelic/newrelic-browser-agent",
   "entries": [
+    {
+      "changes": [
+        {
+          "type": "feat",
+          "sha": "9395415d942b55e88e89438aa203c6a1642d9e6b",
+          "message": "Add custom events API",
+          "issues": [
+            "1263"
+          ]
+        },
+        {
+          "type": "fix",
+          "sha": "762492896a7b96564269aab1aadeb6e44a4da242",
+          "message": "Soft navigation bug fixes and new soft navigation tests",
+          "issues": [
+            "1268"
+          ]
+        }
+      ],
+      "version": "1.277.0",
+      "language": "JAVASCRIPT",
+      "artifactName": "@newrelic/browser-agent",
+      "id": "e01beb28-b225-4333-9334-f7ac3e63180d",
+      "createTime": "2024-12-18T17:31:02.842Z"
+    },
     {
       "changes": [
         {
@@ -2309,5 +2334,5 @@
       "createTime": "2023-05-08T21:11:35.144Z"
     }
   ],
-  "updateTime": "2024-12-16T20:51:42.875Z"
+  "updateTime": "2024-12-18T17:31:02.842Z"
 }

docs/warning-codes.md

@@ -90,4 +90,6 @@
 ### 44
 `Invalid object passed to generic event aggregate. Missing "eventType".`
 ### 45
-`An internal agent process failed to execute.`
+`An internal agent process failed to execute.`
+### 46
+`A reserved eventType was provided to recordCustomEvent(...) -- The event was not recorded.`

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/browser-agent",
-  "version": "1.276.0",
+  "version": "1.277.0",
   "private": false,
   "author": "New Relic Browser Agent Team <browser-agent@newrelic.com>",
   "description": "New Relic Browser Agent",

package.json

@@ -5,7 +5,7 @@
 import { stringify } from '../../../common/util/stringify'
 import { HarvestScheduler } from '../../../common/harvest/harvest-scheduler'
 import { cleanURL } from '../../../common/url/clean-url'
-import { FEATURE_NAME } from '../constants'
+import { FEATURE_NAME, RESERVED_EVENT_TYPES } from '../constants'
 import { globalScope, initialLocation, isBrowserScope } from '../../../common/constants/runtime'
 import { AggregateBase } from '../../utils/aggregate-base'
 import { warn } from '../../../common/util/console'
@@ -37,12 +37,21 @@ export class Aggregate extends AggregateBase {
 
       this.trackSupportabilityMetrics()
 
+      registerHandler('api-recordCustomEvent', (timestamp, eventType, attributes) => {
+        if (RESERVED_EVENT_TYPES.includes(eventType)) return warn(46)
+        this.addEvent({
+          eventType,
+          timestamp: this.toEpoch(timestamp),
+          ...attributes
+        })
+      }, this.featureName, this.ee)
+
       if (agentRef.init.page_action.enabled) {
         registerHandler('api-addPageAction', (timestamp, name, attributes) => {
           this.addEvent({
             ...attributes,
             eventType: 'PageAction',
-            timestamp: Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timestamp)),
+            timestamp: this.toEpoch(timestamp),
             timeSinceLoad: timestamp / 1000,
             actionName: name,
             referrerUrl: this.referrerUrl,
@@ -66,7 +75,7 @@ export class Aggregate extends AggregateBase {
               const { target, timeStamp, type } = aggregatedUserAction.event
               this.addEvent({
                 eventType: 'UserAction',
-                timestamp: Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timeStamp)),
+                timestamp: this.toEpoch(timeStamp),
                 action: type,
                 actionCount: aggregatedUserAction.count,
                 actionDuration: aggregatedUserAction.relativeMs[aggregatedUserAction.relativeMs.length - 1],
@@ -118,7 +127,7 @@ export class Aggregate extends AggregateBase {
                     handle(SUPPORTABILITY_METRIC_CHANNEL, ['Generic/Performance/' + type + '/Seen'])
                     this.addEvent({
                       eventType: 'BrowserPerformance',
-                      timestamp: Math.floor(agentRef.runtime.timeKeeper.correctRelativeTimestamp(entry.startTime)),
+                      timestamp: this.toEpoch(entry.startTime),
                       entryName: cleanURL(entry.name),
                       entryDuration: entry.duration,
                       entryType: type,
@@ -250,6 +259,10 @@ export class Aggregate extends AggregateBase {
     return { ua: this.agentRef.info.userAttributes, at: this.agentRef.info.atts }
   }
 
+  toEpoch (timestamp) {
+    return Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timestamp))
+  }
+
   trackSupportabilityMetrics () {
     /** track usage SMs to improve these experimental features */
     const configPerfTag = 'Config/Performance/'

src/features/generic_events/aggregate/index.js

@@ -10,6 +10,8 @@ export const OBSERVED_WINDOW_EVENTS = ['focus', 'blur']
 export const RAGE_CLICK_THRESHOLD_EVENTS = 4
 export const RAGE_CLICK_THRESHOLD_MS = 1000
 
+export const RESERVED_EVENT_TYPES = ['PageAction', 'UserAction', 'BrowserPerformance']
+
 export const FEATURE_FLAGS = {
   MARKS: 'experimental.marks',
   MEASURES: 'experimental.measures',

src/features/generic_events/constants.js

@@ -6,7 +6,7 @@ import { timeToFirstByte } from '../../../common/vitals/time-to-first-byte'
 import { FEATURE_NAMES, FEATURE_TO_ENDPOINT } 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 { API_TRIGGER_NAME, FEATURE_NAME, INTERACTION_STATUS, INTERACTION_TRIGGERS, IPL_TRIGGER_NAME } from '../constants'
 import { AjaxNode } from './ajax-node'
 import { InitialPageLoadInteraction } from './initial-page-load-interaction'
 import { Interaction } from './interaction'
@@ -21,18 +21,21 @@ export class Aggregate extends AggregateBase {
     this.domObserver = domObserver
 
     this.initialPageLoadInteraction = new InitialPageLoadInteraction(agentRef.agentIdentifier)
+    this.initialPageLoadInteraction.onDone.push(() => { // this ensures the .end() method also works with iPL
+      this.initialPageLoadInteraction.forceSave = true // unless forcibly ignored, iPL always finish by default
+      this.interactionsToHarvest.add(this.initialPageLoadInteraction)
+      this.initialPageLoadInteraction = null
+    })
     timeToFirstByte.subscribe(({ attrs }) => {
       const loadEventTime = attrs.navigationEntry.loadEventEnd
-      this.initialPageLoadInteraction.forceSave = true
       this.initialPageLoadInteraction.done(loadEventTime)
-      this.interactionsToHarvest.add(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.latestHistoryUrl = null
 
     this.blocked = false
     this.waitForFlags(['spa']).then(([spaOn]) => {
@@ -53,7 +56,11 @@ export class Aggregate extends AggregateBase {
 
     // By default, a complete UI driven interaction requires event -> URL change -> DOM mod in that exact order.
     registerHandler('newUIEvent', (event) => this.startUIInteraction(event.type, Math.floor(event.timeStamp), event.target), this.featureName, this.ee)
-    registerHandler('newURL', (timestamp, url) => this.interactionInProgress?.updateHistory(timestamp, url), this.featureName, this.ee)
+    registerHandler('newURL', (timestamp, url) => {
+      // In the case of 'popstate' trigger, by the time the event fires, the URL has already changed, so we need to store what-will-be the *previous* URL for oldURL of next popstate ixn.
+      this.latestHistoryUrl = url
+      this.interactionInProgress?.updateHistory(timestamp, url)
+    }, this.featureName, this.ee)
     registerHandler('newDom', timestamp => {
       this.interactionInProgress?.updateDom(timestamp)
       if (this.interactionInProgress?.seenHistoryAndDomChange()) this.interactionInProgress.done()
@@ -68,21 +75,23 @@ export class Aggregate extends AggregateBase {
   serializer (eventBuffer) {
     // 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
+    let firstIxnStartTime
     const serializedIxnList = []
     for (const interaction of eventBuffer) {
       serializedIxnList.push(interaction.serialize(firstIxnStartTime))
-      if (!firstIxnStartTime) firstIxnStartTime = Math.floor(interaction.start)
+      if (firstIxnStartTime === undefined) firstIxnStartTime = Math.floor(interaction.start) // careful not to match or overwrite on 0 value!
     }
     return `bel.7;${serializedIxnList.join(';')}`
   }
 
   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
+    if (this.interactionInProgress?.done() === false) return // current in-progress is blocked from closing, e.g. by 'waitForEnd' api option
+
+    const oldURL = eventName === INTERACTION_TRIGGERS[3] ? this.latestHistoryUrl : undefined // see related comment in 'newURL' handler above, 'popstate'
+    this.interactionInProgress = new Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi, oldURL)
 
-    this.interactionInProgress = new Interaction(this.agentIdentifier, eventName, startedAt, this.latestRouteSetByApi)
-    if (eventName === 'click') {
+    if (eventName === INTERACTION_TRIGGERS[0]) { // 'click'
       const sourceElemText = getActionText(sourceElem)
       if (sourceElemText) this.interactionInProgress.customAttributes.actionText = sourceElemText
     }
@@ -131,7 +140,7 @@ export class Aggregate extends AggregateBase {
     for (let idx = interactionsBuffer.length - 1; idx >= 0; idx--) { // reverse search for the latest completed interaction for efficiency
       const finishedInteraction = interactionsBuffer[idx]
       if (finishedInteraction.isActiveDuring(timestamp)) {
-        if (finishedInteraction.trigger !== 'initialPageLoad') return finishedInteraction
+        if (finishedInteraction.trigger !== IPL_TRIGGER_NAME) 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
       }
@@ -196,9 +205,11 @@ export class Aggregate extends AggregateBase {
       // 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?.trigger === IPL_TRIGGER_NAME) this.associatedInteraction = null // the api get-interaction method cannot target IPL
       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.domObserver.observe(document.body, { attributes: true, childList: true, subtree: true, characterData: true }) // start observing for DOM changes like a regular UI-driven interaction
         thisClass.setClosureHandlers()
       }
       if (waitForEnd === true) this.associatedInteraction.keepOpenUntilEndApi = true

src/features/soft_navigations/aggregate/index.js

@@ -4,10 +4,11 @@ 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/info'
+import { IPL_TRIGGER_NAME } from '../constants'
 
 export class InitialPageLoadInteraction extends Interaction {
   constructor (agentIdentifier) {
-    super(agentIdentifier, 'initialPageLoad', 0, null)
+    super(agentIdentifier, IPL_TRIGGER_NAME, 0, null)
     const agentInfo = getInfo(agentIdentifier)
     this.queueTime = agentInfo.queueTime
     this.appTime = agentInfo.applicationTime