@newrelic/browser-agent 1.301.0 → 1.302.0-alpha.0

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

@@ -10,15 +10,12 @@ import { drain } from '../../common/drain/drain'
 import { activatedFeatures } from '../../common/util/feature-flags'
 import { Obfuscator } from '../../common/util/obfuscate'
 import { FEATURE_NAMES } from '../../loaders/features/features'
-import { EventStoreManager } from './event-store-manager'
 import { Harvester } from '../../common/harvest/harvester'
-import { warn } from '../../common/util/console'
-import { EntityManager } from './entity-manager'
 import { EventBuffer } from './event-buffer'
 import { handle } from '../../common/event-emitter/handle'
 import { SUPPORTABILITY_METRIC_CHANNEL } from '../metrics/constants'
 import { EventAggregator } from '../../common/aggregate/event-aggregator'
-import { IDEAL_PAYLOAD_SIZE } from '../../common/constants/agent-constants'
+import { MAX_PAYLOAD_SIZE, IDEAL_PAYLOAD_SIZE, SUPPORTS_REGISTERED_ENTITIES } from '../../common/constants/agent-constants'
 
 export class AggregateBase extends FeatureBase {
   /**
@@ -41,16 +38,9 @@ export class AggregateBase extends FeatureBase {
 
     this.harvestOpts = {} // features aggregate classes can define custom opts for when their harvest is called
 
-    const agentEntityGuid = this.agentRef?.runtime?.appMetadata?.agents?.[0]?.entityGuid
-    this.#setupEventStore(agentEntityGuid)
-    if (!agentEntityGuid) {
-      /** wait for the entity guid from the rum response and use to it to further configure things to set the default entity to share an indexed entity with entityGuid */
-      this.ee.on('entity-added', entity => {
-        // not all event managers have this fn, like ST and SR
-        // this allows the lookup to work for the default and an entityGuid without creating two separate buffers
-        this.events?.setEventStore?.(entity.entityGuid)
-      })
-    }
+    this.#setupEventStore()
+
+    this.waitForDrain()
   }
 
   /**
@@ -58,7 +48,7 @@ export class AggregateBase extends FeatureBase {
    * @param {string} entityGuid
    * @returns {void}
    */
-  #setupEventStore (entityGuid) {
+  #setupEventStore () {
     if (this.events) return
     switch (this.featureName) {
     // SessionReplay has its own storage mechanisms.
@@ -67,17 +57,40 @@ export class AggregateBase extends FeatureBase {
         // Jserror and Metric features uses a singleton EventAggregator instead of a regular EventBuffer.
       case FEATURE_NAMES.jserrors:
       case FEATURE_NAMES.metrics:
-        this.events = this.agentRef.sharedAggregator ??= new EventStoreManager(this.agentRef, EventAggregator, entityGuid, { featureName: 'shared_aggregator' })
+        this.events = this.agentRef.sharedAggregator ??= new EventAggregator()
         break
-        /** All other features get EventBuffer in the ESM by default. Note: PVE is included here, but event buffer will always be empty so future harvests will still not happen by interval or EOL.
+        /** All other features get EventBuffer by default. Note: PVE is included here, but event buffer will always be empty so future harvests will still not happen by interval or EOL.
     This was necessary to prevent race cond. issues where the event buffer was checked before the feature could "block" itself.
     Its easier to just keep an empty event buffer in place. */
       default:
-        this.events = new EventStoreManager(this.agentRef, EventBuffer, entityGuid, this)
+        this.events = new EventBuffer(MAX_PAYLOAD_SIZE, this)
         break
     }
   }
 
+  /** @type {Boolean} indicates if the feature supports registered entities and the harvest requirements therein. Also read by getter "harvestEndpointVersion". Controlled by feature flag in pre-release phase. */
+  get supportsRegisteredEntities () {
+    return this.featureName in SUPPORTS_REGISTERED_ENTITIES && (SUPPORTS_REGISTERED_ENTITIES[this.featureName] || this.agentRef.init.feature_flags.includes('register.' + this.featureName))
+  }
+
+  /**
+   * the endpoint version the feature uses during harvests
+   * @type {number}
+   * @returns {boolean}
+   */
+  get harvestEndpointVersion () {
+    return (this.supportsRegisteredEntities && !!this.agentRef.runtime.registeredEntities.length) ? 2 : 1
+  }
+
+  waitForDrain () {
+    /** emitted when the feature successfully drains */
+    this.ee.on('drain-' + this.featureName, () => {
+      /** make an immediate harvest for all the features to help with harvestability for pre-load dervied data on short lived pages */
+      if (!this.drained) setTimeout(() => this.agentRef.runtime.harvester.triggerHarvestFor(this), 1)
+      this.drained = true
+    })
+  }
+
   /**
    * Evaluates whether a harvest should be made early by estimating the size of the current payload.  Currently, this only happens if the event storage is EventBuffer, since that triggers this method directly.
    * If conditions are met, a new harvest will be triggered immediately.
@@ -125,7 +138,6 @@ export class AggregateBase extends FeatureBase {
    */
   drain () {
     drain(this.agentIdentifier, this.featureName)
-    this.drained = true
   }
 
   preHarvestChecks (opts) {
@@ -136,44 +148,39 @@ export class AggregateBase extends FeatureBase {
    * Return harvest payload. A "serializer" function can be defined on a derived class to format the payload.
    * @param {Boolean} shouldRetryOnFail - harvester flag to backup payload for retry later if harvest request fails; this should be moved to harvester logic
    * @param {object|undefined} opts - opts passed from the harvester to help form the payload
-   * @param {string} opts.targetEntityGuid - the entity guid of the target app
+   * @param {string} opts.target - the target app metadata
    * @returns {Array} Final payload tagged with their targeting browser app. The value of `payload` can be undefined if there are no pending events for an app. This should be a minimum length of 1.
    */
   makeHarvestPayload (shouldRetryOnFail = false, opts = {}) {
-    if (!this.events || this.events.isEmpty(this.harvestOpts, opts.targetEntityGuid)) return
+    if (!this.events || this.events.isEmpty(this.harvestOpts)) return
     // Other conditions and things to do when preparing harvest that is required.
     if (this.preHarvestChecks && !this.preHarvestChecks(opts)) return
 
-    if (shouldRetryOnFail) this.events.save(this.harvestOpts, opts.targetEntityGuid)
-    const returnedDataArr = this.events.get(this.harvestOpts, opts.targetEntityGuid)
-    if (!returnedDataArr.length) return warn(52)
-    this.events.clear(this.harvestOpts, opts.targetEntityGuid)
-
-    return returnedDataArr.map(({ targetApp, data }) => {
-      // A serializer or formatter assists in creating the payload `body` from stored events on harvest when defined by derived feature class.
-      const body = this.serializer ? this.serializer(data, targetApp?.entityGuid) : data
-      const payload = {
-        body
-      }
-      // Constructs the payload `qs` for relevant features on harvest.
-      if (this.queryStringsBuilder) payload.qs = this.queryStringsBuilder(data, targetApp?.entityGuid)
+    if (shouldRetryOnFail) this.events.save(this.harvestOpts)
+    const data = this.events.get(this.harvestOpts)
+    if (!data) return
+    this.events.clear(this.harvestOpts)
 
-      return { targetApp, payload }
-    })
+    // A serializer or formatter assists in creating the payload `body` from stored events on harvest when defined by derived feature class.
+    const body = this.serializer ? this.serializer(data) : data
+    const payload = {
+      body
+    }
+    // Constructs the payload `qs` for relevant features on harvest.
+    if (this.queryStringsBuilder) payload.qs = this.queryStringsBuilder(data)
+    return payload
   }
 
   /**
    * Cleanup task after a harvest.
    * @param {object} result - the cbResult object from the harvester's send method
-   * @param {object=} result.targetApp - the target app object that was used to point the harvest to the correct app
-   * @param {string=} result.targetApp.entityGuid - the entity guid of the target app
    * @param {boolean=} result.sent - whether the harvest was sent successfully
    * @param {boolean=} result.retry - whether the harvest should be retried
    */
   postHarvestCleanup (result = {}) {
     this.isRetrying = result.sent && result.retry
-    if (this.isRetrying) this.events.reloadSave(this.harvestOpts, result.targetApp?.entityGuid)
-    this.events.clearSave(this.harvestOpts, result.targetApp?.entityGuid)
+    if (this.isRetrying) this.events.reloadSave(this.harvestOpts)
+    this.events.clearSave(this.harvestOpts)
   }
 
   /**
@@ -212,8 +219,6 @@ export class AggregateBase extends FeatureBase {
     if (!agentRef.runtime.obfuscator) agentRef.runtime.obfuscator = new Obfuscator(agentRef)
     this.obfuscator = agentRef.runtime.obfuscator
 
-    if (!agentRef.runtime.entityManager) agentRef.runtime.entityManager = new EntityManager(this.agentRef)
-
     if (!agentRef.runtime.harvester) agentRef.runtime.harvester = new Harvester(agentRef)
   }
 

package/src/loaders/api/addPageAction.js

@@ -12,6 +12,6 @@ export function setupAddPageActionAPI (agent) {
   setupAPI(ADD_PAGE_ACTION, (name, attributes) => addPageAction(name, attributes, agent), agent)
 }
 
-export function addPageAction (name, attributes, agentRef, targetEntityGuid, timestamp = now()) {
-  handle(prefix + ADD_PAGE_ACTION, [timestamp, name, attributes, targetEntityGuid], undefined, FEATURE_NAMES.genericEvents, agentRef.ee)
+export function addPageAction (name, attributes, agentRef, target, timestamp = now()) {
+  handle(prefix + ADD_PAGE_ACTION, [timestamp, name, attributes, target], undefined, FEATURE_NAMES.genericEvents, agentRef.ee)
 }

package/src/loaders/api/log.js

@@ -13,6 +13,6 @@ export function setupLogAPI (agent) {
   setupAPI(LOG, (message, options) => log(message, options, agent), agent)
 }
 
-export function log (message, { customAttributes = {}, level = LOG_LEVELS.INFO } = {}, agentRef, targetEntityGuid, timestamp = now()) {
-  bufferLog(agentRef.ee, message, customAttributes, level, targetEntityGuid, timestamp)
+export function log (message, { customAttributes = {}, level = LOG_LEVELS.INFO } = {}, agentRef, target, timestamp = now()) {
+  bufferLog(agentRef.ee, message, customAttributes, level, target, timestamp)
 }

package/src/loaders/api/noticeError.js

@@ -12,8 +12,8 @@ export function setupNoticeErrorAPI (agent) {
   setupAPI(NOTICE_ERROR, (err, customAttributes) => noticeError(err, customAttributes, agent), agent)
 }
 
-export function noticeError (err, customAttributes, agentRef, targetEntityGuid, timestamp = now()) {
+export function noticeError (err, customAttributes, agentRef, target, timestamp = now()) {
   if (typeof err === 'string') err = new Error(err)
-  handle('err', [err, timestamp, false, customAttributes, agentRef.runtime.isRecording, undefined, targetEntityGuid], undefined, FEATURE_NAMES.jserrors, agentRef.ee)
+  handle('err', [err, timestamp, false, customAttributes, agentRef.runtime.isRecording, undefined, target], undefined, FEATURE_NAMES.jserrors, agentRef.ee)
   handle('uaErr', [], undefined, FEATURE_NAMES.genericEvents, agentRef.ee)
 }

package/src/loaders/api/register-api-types.js

@@ -17,17 +17,17 @@
 /**
  * @typedef {Object} RegisterAPIConstructor
  * @property {Object} opts - The options for the registered entity.
- * @property {string} opts.licenseKey - The license key for the registered entity.
- * @property {string} opts.applicationID - The application ID for the registered entity.
+ * @property {string} opts.id - The unique id for the registered entity. This will be assigned to any synthesized entities.
+ * @property {string} opts.name - The readable name for the registered entity. This will be assigned to any synthesized entities.
  */
 
 /**
  * @typedef {Object} RegisterAPIMetadata
  * @property {Object} customAttributes - The custom attributes for the registered entity.
  * @property {Object} target - The options for the registered entity.
- * @property {string} target.licenseKey - The license key for the registered entity.
- * @property {string} target.applicationID - The application ID for the registered entity.
- * @property {string} target.entityGuid - The entity guid returned for the registered entity.
+ * @property {string} target.licenseKey - The license key for the registered entity. If none was supplied, it will assume the license key from the main agent.
+ * @property {string} target.id - The ID for the registered entity.
+ * @property {string} target.name - The name returned for the registered entity.
  */
 
 export default {}

package/src/loaders/api/register.js

@@ -4,7 +4,7 @@
  */
 import { handle } from '../../common/event-emitter/handle'
 import { warn } from '../../common/util/console'
-import { isContainerAgentTarget, isValidTarget } from '../../common/util/target'
+import { isValidMFETarget } from '../../common/util/mfe'
 import { FEATURE_NAMES } from '../features/features'
 import { now } from '../../common/timing/now'
 import { SUPPORTABILITY_METRIC_CHANNEL } from '../../features/metrics/constants'
@@ -13,6 +13,7 @@ import { REGISTER } from './constants'
 import { log } from './log'
 import { addPageAction } from './addPageAction'
 import { noticeError } from './noticeError'
+import { single } from '../../common/util/invoke'
 
 /**
  * @typedef {import('./register-api-types').RegisterAPI} RegisterAPI
@@ -35,106 +36,80 @@ export function setupRegisterAPI (agent) {
  * @param {Object} agentRef the reference to the base agent instance
  * @param {Object} handlers the shared handlers to be used by both the base agent's API and the external target's API
  * @param {Object} target the target information to be used by the external target's API to send data to the correct location
+ * @param {string} [target.licenseKey] the license key of the target to report data to
+ * @param {string} target.id the entity ID of the target to report data to
+ * @param {string} target.name the entity name of the target to report data to
  * @returns {RegisterAPI} the api object to be returned from the register api method
  */
 export function buildRegisterApi (agentRef, target) {
   const attrs = {}
   warn(54, 'newrelic.register')
 
-  /** @type {Function|undefined} a function that is set and reports when APIs are triggered -- warns the customer of the invalid state  */
-  let invalidApiResponse
+  target ||= {}
+  target.licenseKey ||= agentRef.info.licenseKey // will inherit the license key from the container agent if not provided for brevity. A future state may dictate that we need different license keys to do different things.
+  target.blocked = false
+
+  /** @type {Function} a function that is set and reports when APIs are triggered -- warns the customer of the invalid state  */
+  let invalidApiResponse = () => {}
+  /** @type {Array} the array of registered target APIs */
+  const registeredEntities = agentRef.runtime.registeredEntities
+
+  /** if we have already registered this target, go ahead and re-use it */
+  const preregisteredEntity = registeredEntities.find(({ metadata: { target: { id, name } } }) => id === target.id)
+  if (preregisteredEntity) {
+    if (preregisteredEntity.metadata.target.name !== target.name) preregisteredEntity.metadata.target.name = target.name
+    return preregisteredEntity
+  }
 
   /**
-       * A promise that indicates when all needed connections for the registered child to be ready to report data
-       * 1. The main agent to be ready (made a RUM call and got its entity guid)
-       * 2. The child to be registered with the main agent (made its own RUM call and got its entity guid)
-       * @type {Promise<RegisterAPI>}
-       */
-  let _connected
-  if (!agentRef.init.api.allow_registered_children) invalidApiResponse = () => warn(55)
-  if (!target || !isValidTarget(target)) invalidApiResponse = () => warn(48, target)
+   * Block the API, and supply a warning function to display a message to end users
+   * @param {Function} warning
+   */
+  const block = (warning) => {
+    target.blocked = true
+    invalidApiResponse = warning
+  }
+
+  /** primary cases that can block the register API from working at init time */
+  if (!agentRef.init.api.allow_registered_children) block(single(() => warn(55)))
+  if (!isValidMFETarget(target)) block(single(() => warn(48, target)))
 
   /** @type {RegisterAPI} */
   const api = {
-    addPageAction: (name, attributes = {}) => {
-      report(addPageAction, [name, { ...attrs, ...attributes }, agentRef], target)
-    },
-    log: (message, options = {}) => {
-      report(log, [message, { ...options, customAttributes: { ...attrs, ...(options.customAttributes || {}) } }, agentRef], target)
-    },
-    noticeError: (error, attributes = {}) => {
-      report(noticeError, [error, { ...attrs, ...attributes }, agentRef], target)
-    },
-    setApplicationVersion: (value) => {
-      attrs['application.version'] = value
-    },
-    setCustomAttribute: (key, value) => {
-      attrs[key] = value
-    },
-    setUserId: (value) => {
-      attrs['enduser.id'] = value
-    },
+    addPageAction: (name, attributes = {}) => report(addPageAction, [name, { ...attrs, ...attributes }, agentRef], target),
+    log: (message, options = {}) => report(log, [message, { ...options, customAttributes: { ...attrs, ...(options.customAttributes || {}) } }, agentRef], target),
+    noticeError: (error, attributes = {}) => report(noticeError, [error, { ...attrs, ...attributes }, agentRef], target),
+    setApplicationVersion: (value) => setLocalValue('application.version', value),
+    setCustomAttribute: (key, value) => setLocalValue(key, value),
+    setUserId: (value) => setLocalValue('enduser.id', value),
     /** metadata */
     metadata: {
       customAttributes: attrs,
-      target,
-      /** set in a getter so that later access of the Promise is not polluted before customer is allowed to set a catch block */
-      get connected () {
-        return _connected || Promise.reject(new Error('Failed to connect'))
-      }
+      target
     }
   }
 
-  if (invalidApiResponse) {
-    invalidApiResponse()
-  } else {
-    _connected = new Promise((resolve, reject) => {
-      try {
-        const entityManager = agentRef.runtime?.entityManager
-        /** check if main agent already has main agent entity guid */
-        let mainAgentReady = !!entityManager?.get().entityGuid
-        /** check if registered target already has entity guid */
-        let registeredEntityGuid = entityManager?.getEntityGuidFor(target.licenseKey, target.applicationID)
-        let registrationReady = !!registeredEntityGuid
-
-        /** check if we can just resolve immediately without making another connect call */
-        if (mainAgentReady && registrationReady) {
-          target.entityGuid = registeredEntityGuid
-          resolve(api)
-        } else {
-          /** we need to make a new connection call since we dont already have a registered entity for this call */
-
-          /** if the connect callback doesnt resolve in 15 seconds... reject */
-          const timeout = setTimeout(() => reject(new Error('Failed to connect - Timeout')), 15000)
-
-          // tell the main agent to send a rum call for this target
-          // when the rum call resolves, it will emit an "entity-added" event, see below
-          agentRef.ee.emit('api-send-rum', [attrs, target])
-
-          // wait for entity events to emit to see when main agent and/or API registration is ready
-          agentRef.ee.on('entity-added', entityEventHandler)
+  /**
+   * Check if the API is blocked and emit a warning message describing the blockage
+   * @returns {boolean}
+   */
+  const isBlocked = () => {
+    if (target.blocked) invalidApiResponse()
+    return target.blocked
+  }
 
-          function entityEventHandler (entity) {
-            if (isContainerAgentTarget(entity, agentRef)) mainAgentReady ||= true
-            else {
-              if (target.licenseKey === entity.licenseKey && target.applicationID === entity.applicationID) {
-                registrationReady = true
-                target.entityGuid = entity.entityGuid
-              }
-            }
+  /** only allow registered APIs to be tracked in the agent runtime */
+  if (!isBlocked()) registeredEntities.push(api)
 
-            if (mainAgentReady && registrationReady) {
-              clearTimeout(timeout)
-              // unsubscribe from the event emitter
-              agentRef.ee.removeEventListener('entity-added', entityEventHandler)
-              resolve(api)
-            }
-          }
-        }
-      } catch (err) {
-        reject(err)
-      }
-    })
+  /**
+   * Sets a value local to the registered API attrs. Will do nothing if APIs are deregistered.
+   * @param {string} key The attribute key
+   * @param {*} value the attribute value
+   * @returns {void}
+   */
+  const setLocalValue = (key, value) => {
+    if (isBlocked()) return
+    attrs[key] = value
   }
 
   /**
@@ -142,23 +117,21 @@ export function buildRegisterApi (agentRef, target) {
      * If the api.duplicate_registered_data configuration value is set to true, the data will be reported to BOTH the container and the external target
      * @param {*} methodToCall the container agent's API method to call
      * @param {*} args the arguments to supply to the container agent's API method
-     * @param {string} targetEntityGuid the target entity guid, which looks up the target to report the data to from the entity manager. If undefined, will report to the container agent's target.
+     * @param {string} target the target to report the data to. If undefined, will report to the container agent's target.
      * @returns
      */
-  const report = async (methodToCall, args, target) => {
-    if (invalidApiResponse) return invalidApiResponse()
+  const report = (methodToCall, args, target) => {
+    if (isBlocked()) return
     /** set the timestamp before the async part of waiting for the rum response for better accuracy */
     const timestamp = now()
     handle(SUPPORTABILITY_METRIC_CHANNEL, [`API/register/${methodToCall.name}/called`], undefined, FEATURE_NAMES.metrics, agentRef.ee)
     try {
-      await _connected
-      // target should be decorated with entityGuid by the rum resp at this point
       const shouldDuplicate = agentRef.init.api.duplicate_registered_data
-      if (shouldDuplicate === true || (Array.isArray(shouldDuplicate) && shouldDuplicate.includes(target.entityGuid))) {
+      if (shouldDuplicate === true || Array.isArray(shouldDuplicate)) {
         // also report to container by providing undefined target
         methodToCall(...args, undefined, timestamp)
       }
-      methodToCall(...args, target.entityGuid, timestamp) // always report to target
+      return methodToCall(...args, target, timestamp) // always report to target
     } catch (err) {
       warn(50, err)
     }

package/dist/cjs/common/util/target.js

@@ -1,34 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.isContainerAgentTarget = isContainerAgentTarget;
-exports.isValidTarget = isValidTarget;
-/**
- * Copyright 2020-2025 New Relic, Inc. All rights reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * @param {Object} [target] - the target to be validated
- * @param {boolean} [allowUndefined=true]
- * @returns {boolean}
- */
-function isValidTarget(target) {
-  /** target can be undefined to support legacy/default behaviors - main agent does not supply a target */
-  if (!target) return true;
-  /** if not undefined, we require specific values */
-  return !!(target.licenseKey && target.applicationID);
-}
-
-/**
- * Checks if the target matches the container agent target
- * @param {*} target the target to be validated
- * @param {*} agentRef the agent reference to be validated
- * @returns {boolean}
- */
-function isContainerAgentTarget(target, agentRef) {
-  if (!target) return true;
-  return target.licenseKey === agentRef.info.licenseKey && target.applicationID === agentRef.info.applicationID;
-}

package/dist/cjs/features/utils/entity-manager.js

@@ -1,46 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.EntityManager = void 0;
-var _agentConstants = require("../../common/constants/agent-constants");
-/**
- * Copyright 2020-2025 New Relic, Inc. All rights reserved.
- * SPDX-License-Identifier: Apache-2.0
- */
-
-class EntityManager {
-  #entities = new Map();
-  #entityGuidLookup = {};
-  constructor(agentRef) {
-    this.agentRef = agentRef;
-    this.#entities.set(_agentConstants.DEFAULT_KEY, {
-      licenseKey: agentRef.info.licenseKey,
-      applicationID: agentRef.info.applicationID
-    });
-  }
-  get(entityGuid = _agentConstants.DEFAULT_KEY) {
-    return this.#entities.get(entityGuid);
-  }
-  getEntityGuidFor(licenseKey, applicationID) {
-    if (!this.#entityGuidLookup[licenseKey] || !this.#entityGuidLookup[applicationID]) return;
-    return this.#entityGuidLookup[licenseKey].filter(x => this.#entityGuidLookup[applicationID].includes(x))[0];
-  }
-  set(entityGuid, entity) {
-    if (this.#entities.has(entityGuid)) return;
-    this.#entities.set(entityGuid, entity);
-    this.#entityGuidLookup[entity.licenseKey] ??= [];
-    this.#entityGuidLookup[entity.licenseKey].push(entityGuid);
-    this.#entityGuidLookup[entity.applicationID] ??= [];
-    this.#entityGuidLookup[entity.applicationID].push(entityGuid);
-    this.agentRef.ee.emit('entity-added', [entity]);
-  }
-  clear() {
-    this.#entities.clear();
-  }
-  setDefaultEntity(entity) {
-    this.#entities.set(_agentConstants.DEFAULT_KEY, entity);
-  }
-}
-exports.EntityManager = EntityManager;