add custom events api

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.`

src/features/generic_events/aggregate/index.js

@@ -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 { initialLocation, isBrowserScope } from '../../../common/constants/runtime'
 import { AggregateBase } from '../../utils/aggregate-base'
 import { warn } from '../../../common/util/console'
@@ -34,12 +34,21 @@ export class Aggregate extends AggregateBase {
         return
       }
 
+      registerHandler('api-recordCustomEvent', (timestamp, eventType, attributes) => {
+        if (RESERVED_EVENT_TYPES.includes(eventType)) return warn(46)
+        this.addEvent({
+          eventType,
+          timestamp: this.toEpoch(timestamp),
+          ...attributes
+        }, false)
+      }, 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,
@@ -63,7 +72,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],
@@ -105,7 +114,7 @@ export class Aggregate extends AggregateBase {
                   try {
                     this.addEvent({
                       eventType: 'BrowserPerformance',
-                      timestamp: Math.floor(agentRef.runtime.timeKeeper.correctRelativeTimestamp(entry.startTime)),
+                      timestamp: this.toEpoch(entry.startTime),
                       entryName: entry.name,
                       entryDuration: entry.duration,
                       entryType: type,
@@ -147,7 +156,7 @@ export class Aggregate extends AggregateBase {
    * @param {object=} obj the event object for storing in the event buffer
    * @returns void
    */
-  addEvent (obj = {}) {
+  addEvent (obj = {}, shouldAddDefaultAttributes = true) {
     if (!obj || !Object.keys(obj).length) return
     if (!obj.eventType) {
       warn(44)
@@ -171,7 +180,7 @@ export class Aggregate extends AggregateBase {
       /** Agent-level custom attributes */
       ...(this.agentRef.info.jsAttributes || {}),
       /** Fallbacks for required properties in-case the event did not supply them, should take precedence over agent-level custom attrs */
-      ...defaultEventAttributes,
+      ...(shouldAddDefaultAttributes && defaultEventAttributes),
       /** Event-specific attributes take precedence over agent-level custom attributes and fallbacks */
       ...obj
     }
@@ -195,4 +204,8 @@ export class Aggregate extends AggregateBase {
   queryStringsBuilder () {
     return { ua: this.agentRef.info.userAttributes, at: this.agentRef.info.atts }
   }
+
+  toEpoch (timestamp) {
+    return Math.floor(this.agentRef.runtime.timeKeeper.correctRelativeTimestamp(timestamp))
+  }
 }

src/features/generic_events/constants.js

@@ -9,3 +9,5 @@ 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']

src/loaders/api/api-methods.js

@@ -1,7 +1,7 @@
 import { SR_EVENT_EMITTER_TYPES } from '../../features/session_replay/constants'
 
 export const apiMethods = [
-  'setErrorHandler', 'finished', 'addToTrace', 'addRelease',
+  'setErrorHandler', 'finished', 'addToTrace', 'addRelease', 'recordCustomEvent',
   'addPageAction', 'setCurrentRouteName', 'setPageViewName', 'setCustomAttribute',
   'interaction', 'noticeError', 'setUserId', 'setApplicationVersion', 'start',
   SR_EVENT_EMITTER_TYPES.RECORD, SR_EVENT_EMITTER_TYPES.PAUSE, 'log', 'wrapLogger'

src/loaders/api/api.js

@@ -72,6 +72,8 @@ export function setAPI (agentIdentifier, forceDrain, runSoftNavOverSpa = false)
 
   apiInterface.addPageAction = apiCall(prefix, 'addPageAction', true, FEATURE_NAMES.genericEvents)
 
+  apiInterface.recordCustomEvent = apiCall(prefix, 'recordCustomEvent', true, FEATURE_NAMES.genericEvents)
+
   apiInterface.setPageViewName = function (name, host) {
     if (typeof name !== 'string') return
     if (name.charAt(0) !== '/') name = '/' + name

src/loaders/micro-agent-base.js

@@ -30,6 +30,16 @@ export class MicroAgentBase {
     return this.#callMethod('addPageAction', name, attributes)
   }
 
+  /**
+   * Records a custom event with a specified eventType and attributes.
+   * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/recordCustomEvent/}
+   * @param {string} eventType The eventType to store the event as.
+   * @param {object} [attributes] JSON object with one or more key/value pairs. For example: {key:"value"}.
+   */
+  recordCustomEvent (eventType, attributes) {
+    return this.#callMethod('recordCustomEvent', eventType, attributes)
+  }
+
   /**
    * Groups page views to help URL structure or to capture the URL's routing information.
    * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setpageviewname/}

tests/components/api.test.js

@@ -42,12 +42,13 @@ describe('setAPI', () => {
   test('should add expected api methods returned object', () => {
     const apiInterface = setAPI(agentId, true)
 
-    expect(Object.keys(apiInterface).length).toEqual(17)
+    expect(Object.keys(apiInterface).length).toEqual(18)
     expect(typeof apiInterface.setErrorHandler).toEqual('function')
     expect(typeof apiInterface.finished).toEqual('function')
     expect(typeof apiInterface.addToTrace).toEqual('function')
     expect(typeof apiInterface.addRelease).toEqual('function')
     expect(typeof apiInterface.addPageAction).toEqual('function')
+    expect(typeof apiInterface.recordCustomEvent).toEqual('function')
     expect(typeof apiInterface.setCurrentRouteName).toEqual('function')
     expect(typeof apiInterface.setPageViewName).toEqual('function')
     expect(typeof apiInterface.setCustomAttribute).toEqual('function')

tests/specs/ins/harvesting.e2e.js

@@ -32,6 +32,46 @@ describe('ins harvesting', () => {
     expect(estimatedEventTime < receiptTime).toEqual(true) //, 'estimated event time (' + estimatedEventTime + ') < receipt time (' + receiptTime + ')')
   })
 
+  it('should submit Custom Events', async () => {
+    const testUrl = await browser.testHandle.assetURL('instrumented.html')
+    await browser.url(testUrl)
+      .then(() => browser.waitForAgentLoad())
+
+    const [[{ request: { body: { ins: customEventsHarvest } } }]] = await Promise.all([
+      insightsCapture.waitForResult({ totalCount: 1 }),
+      browser.execute(function () {
+        newrelic.recordCustomEvent('event0', { index: 0 })
+        newrelic.recordCustomEvent('event1', { index: 1 })
+      })
+    ])
+
+    expect(customEventsHarvest.length).toEqual(2)
+    customEventsHarvest.forEach((event, i) => {
+      expect(event.eventType).toEqual(`event${i}`)
+      expect(event.index).toEqual(i)
+      expect(event.timestamp).toBeGreaterThan(0)
+      expect(event.timestamp).toBeLessThan(Date.now())
+      expect(Object.keys(event).length).toEqual(3)
+    })
+  })
+
+  it('should not submit reserved Custom Events', async () => {
+    const testUrl = await browser.testHandle.assetURL('instrumented.html')
+    await browser.url(testUrl)
+      .then(() => browser.waitForAgentLoad())
+
+    const [customEventsHarvest] = await Promise.all([
+      insightsCapture.waitForResult({ timeout: 10000 }),
+      browser.execute(function () {
+        newrelic.recordCustomEvent('PageAction', { index: 0 })
+        newrelic.recordCustomEvent('BrowserPerformance', { index: 1 })
+        newrelic.recordCustomEvent('UserAction', { index: 2 })
+      })
+    ])
+
+    expect(customEventsHarvest.length).toEqual(0)
+  })
+
   it('should submit UserAction (when enabled)', async () => {
     const testUrl = await browser.testHandle.assetURL('user-actions.html', { init: { user_actions: { enabled: true } } })
     await browser.url(testUrl).then(() => browser.waitForAgentLoad())

tests/unit/loaders/api/api.test.js

@@ -11,12 +11,13 @@ describe('setTopLevelCallers', () => {
     setTopLevelCallers()
 
     const nreum = gosCDN()
-    expect(Object.keys(nreum).length).toEqual(17)
+    expect(Object.keys(nreum).length).toEqual(18)
     expect(typeof nreum.setErrorHandler).toEqual('function')
     expect(typeof nreum.finished).toEqual('function')
     expect(typeof nreum.addToTrace).toEqual('function')
     expect(typeof nreum.addRelease).toEqual('function')
     expect(typeof nreum.addPageAction).toEqual('function')
+    expect(typeof nreum.recordCustomEvent).toEqual('function')
     expect(typeof nreum.setCurrentRouteName).toEqual('function')
     expect(typeof nreum.setPageViewName).toEqual('function')
     expect(typeof nreum.setCustomAttribute).toEqual('function')