@newrelic/browser-agent 1.260.1 → 1.261.0

package/src/common/config/state/init.js

@@ -1,3 +1,4 @@
+import { LOG_LEVELS } from '../../../features/logging/constants'
 import { isValidSelector } from '../../dom/query-selector'
 import { DEFAULT_EXPIRES_MS, DEFAULT_INACTIVE_MS } from '../../session/constants'
 import { warn } from '../../util/console'
@@ -31,12 +32,6 @@ const model = () => {
     }
   }
   return {
-    feature_flags: [],
-    proxy: {
-      assets: undefined, // if this value is set, it will be used to overwrite the webpack asset path used to fetch assets
-      beacon: undefined // likewise for the url to which we send analytics
-    },
-    privacy: { cookies_enabled: true }, // *cli - per discussion, default should be true
     ajax: { deny_list: undefined, block_internal: true, enabled: true, harvestTimeSeconds: 10, autoStart: true },
     distributed_tracing: {
       enabled: undefined,
@@ -45,19 +40,24 @@ const model = () => {
       cors_use_tracecontext_headers: undefined,
       allowed_origins: undefined
     },
-    session: {
-      expiresMs: DEFAULT_EXPIRES_MS,
-      inactiveMs: DEFAULT_INACTIVE_MS
-    },
-    ssl: undefined,
-    obfuscate: undefined,
+    feature_flags: [],
+    harvest: { tooManyRequestsDelay: 60 },
     jserrors: { enabled: true, harvestTimeSeconds: 10, autoStart: true },
+    logging: { enabled: true, harvestTimeSeconds: 10, autoStart: true, level: LOG_LEVELS.INFO },
     metrics: { enabled: true, autoStart: true },
+    obfuscate: undefined,
     page_action: { enabled: true, harvestTimeSeconds: 30, autoStart: true },
     page_view_event: { enabled: true, autoStart: true },
     page_view_timing: { enabled: true, harvestTimeSeconds: 30, long_task: false, autoStart: true },
-    session_trace: { enabled: true, harvestTimeSeconds: 10, autoStart: true },
-    harvest: { tooManyRequestsDelay: 60 },
+    privacy: { cookies_enabled: true }, // *cli - per discussion, default should be true
+    proxy: {
+      assets: undefined, // if this value is set, it will be used to overwrite the webpack asset path used to fetch assets
+      beacon: undefined // likewise for the url to which we send analytics
+    },
+    session: {
+      expiresMs: DEFAULT_EXPIRES_MS,
+      inactiveMs: DEFAULT_INACTIVE_MS
+    },
     session_replay: {
       // feature settings
       autoStart: true,
@@ -100,8 +100,10 @@ const model = () => {
         else warn('An invalid session_replay.mask_input_option was provided and will not be used', val)
       }
     },
+    session_trace: { enabled: true, harvestTimeSeconds: 10, autoStart: true },
+    soft_navigations: { enabled: true, harvestTimeSeconds: 10, autoStart: true },
     spa: { enabled: true, harvestTimeSeconds: 10, autoStart: true },
-    soft_navigations: { enabled: true, harvestTimeSeconds: 10, autoStart: true }
+    ssl: undefined
   }
 }
 

package/src/common/deny-list/deny-list.js

@@ -10,7 +10,7 @@ var denyList = []
  * @returns {boolean} `true` if request does not match any entries of {@link denyList|deny list}; else `false`
  */
 export function shouldCollectEvent (params) {
-  if (hasUndefinedHostname(params)) return false
+  if (!params || hasUndefinedHostname(params)) return false
 
   if (denyList.length === 0) return true
 

package/src/common/session/session-entity.js

@@ -3,7 +3,7 @@ import { warn } from '../util/console'
 import { stringify } from '../util/stringify'
 import { ee } from '../event-emitter/contextual-ee'
 import { Timer } from '../timer/timer'
-import { isBrowserScope } from '../constants/runtime'
+import { isBrowserScope, isIE } from '../constants/runtime'
 import { DEFAULT_EXPIRES_MS, DEFAULT_INACTIVE_MS, MODE, PREFIX, SESSION_EVENTS, SESSION_EVENT_TYPES } from './constants'
 import { InteractionTimer } from '../timer/interaction-timer'
 import { wrapEvents } from '../wrap'
@@ -52,7 +52,12 @@ export class SessionEntity {
     wrapEvents(this.ee)
     this.setup(opts)
 
-    if (isBrowserScope) {
+    /**
+     * Do not emit session storage events for IE11, because IE11 is unable to determine
+     * if the event was spawned on the current page or an adjacent page, and the behavior tied
+     * to storage events is critical to apply only to cross-tab behavior
+     * */
+    if (isBrowserScope && !isIE) {
       windowAddEventListener('storage', (event) => {
         if (event.key === this.lookupKey) {
           const obj = typeof event.newValue === 'string' ? JSON.parse(event.newValue) : event.newValue

package/src/common/wrap/wrap-logger.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file Wraps native timeout and interval methods for instrumentation.
+ * This module is used by: jserrors, spa.
+ */
+
+import { ee as baseEE, contextId } from '../event-emitter/contextual-ee'
+import { EventContext } from '../event-emitter/event-context'
+import { createWrapperWithEmitter as wfn } from './wrap-function'
+
+/**
+ * Wraps a supplied function and adds emitter events under the `-wrap-logger-` prefix
+ * @param {Object} sharedEE - The shared event emitter on which a new scoped event emitter will be based.
+ * @param {Object} parent - The parent object housing the logger function
+ * @param {string} loggerFn - The name of the function in the parent object to wrap
+ * @returns {Object} Scoped event emitter with a debug ID of `logger`.
+ */
+// eslint-disable-next-line
+export function wrapLogger(sharedEE, parent, loggerFn, context) {
+  const ee = scopedEE(sharedEE)
+  const wrapFn = wfn(ee)
+
+  /**
+   * This section contains the context that will be shared across all invoked calls of the wrapped function,
+   * which will be used to decorate the log data later at agg time
+  */
+  const ctx = new EventContext(contextId)
+  ctx.level = context.level
+  ctx.customAttributes = context.customAttributes
+
+  /** observe calls to <loggerFn> and emit events prefixed with `wrap-logger-` */
+  wrapFn.inPlace(parent, [loggerFn], 'wrap-logger-', ctx)
+
+  return ee
+}
+
+/**
+ * Returns an event emitter scoped specifically for the `logger` context. This scoping is a remnant from when all the
+ * features shared the same group in the event, to isolate events between features. It will likely be revisited.
+ * @param {Object} sharedEE - Optional event emitter on which to base the scoped emitter.
+ *     Uses `ee` on the global scope if undefined).
+ * @returns {Object} Scoped event emitter with a debug ID of 'logger'.
+ */
+export function scopedEE (sharedEE) {
+  return (sharedEE || baseEE).get('logger')
+}

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

@@ -0,0 +1,101 @@
+import { getConfigurationValue, getInfo, getRuntime } 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 { warn } from '../../../common/util/console'
+import { stringify } from '../../../common/util/stringify'
+import { SUPPORTABILITY_METRIC_CHANNEL } from '../../metrics/constants'
+import { AggregateBase } from '../../utils/aggregate-base'
+import { FEATURE_NAME, LOGGING_EVENT_EMITTER_CHANNEL, LOGGING_IGNORED, MAX_PAYLOAD_SIZE } from '../constants'
+import { Log } from '../shared/log'
+
+export class Aggregate extends AggregateBase {
+  static featureName = FEATURE_NAME
+  #agentRuntime
+  #agentInfo
+  constructor (agentIdentifier, aggregator) {
+    super(agentIdentifier, aggregator, FEATURE_NAME)
+
+    /** held logs before sending */
+    this.bufferedLogs = []
+    /** held logs during sending, for retries */
+    this.outgoingLogs = []
+    /** the estimated bytes of log data waiting to be sent -- triggers a harvest if adding a new log will exceed limit  */
+    this.estimatedBytes = 0
+
+    this.#agentRuntime = getRuntime(this.agentIdentifier)
+    this.#agentInfo = getInfo(this.agentIdentifier)
+
+    this.harvestTimeSeconds = getConfigurationValue(this.agentIdentifier, 'logging.harvestTimeSeconds')
+
+    this.waitForFlags([]).then(() => {
+      this.scheduler = new HarvestScheduler('browser/logs', {
+        onFinished: this.onHarvestFinished.bind(this),
+        retryDelay: this.harvestTimeSeconds,
+        getPayload: this.prepareHarvest.bind(this),
+        raw: true
+      }, this)
+      /** harvest immediately once started to purge pre-load logs collected */
+      this.scheduler.startTimer(this.harvestTimeSeconds, 0)
+      /** emitted by instrument class (wrapped loggers) or the api methods directly */
+      registerHandler(LOGGING_EVENT_EMITTER_CHANNEL, this.handleLog.bind(this), this.featureName, this.ee)
+      this.drain()
+    })
+  }
+
+  handleLog (timestamp, message, attributes, level) {
+    if (this.blocked) return
+    const log = new Log(
+      this.#agentRuntime.timeKeeper.convertRelativeTimestamp(timestamp),
+      message,
+      attributes,
+      level
+    )
+    const logBytes = log.message.length + stringify(log.attributes).length + log.level.length + 10 // timestamp == 10 chars
+    if (logBytes > MAX_PAYLOAD_SIZE) {
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ['Logging/Harvest/Failed/Seen', logBytes])
+      return warn(LOGGING_IGNORED + '> ' + MAX_PAYLOAD_SIZE + ' bytes', log.message.slice(0, 25) + '...')
+    }
+
+    if (this.estimatedBytes + logBytes >= MAX_PAYLOAD_SIZE) {
+      handle(SUPPORTABILITY_METRIC_CHANNEL, ['Logging/Harvest/Early/Seen', this.estimatedBytes + logBytes])
+      this.scheduler.runHarvest({})
+    }
+    this.estimatedBytes += logBytes
+    this.bufferedLogs.push(log)
+  }
+
+  prepareHarvest () {
+    if (this.blocked || !(this.bufferedLogs.length || this.outgoingLogs.length)) return
+    /** populate outgoing array while also clearing main buffer */
+    this.outgoingLogs.push(...this.bufferedLogs.splice(0))
+    this.estimatedBytes = 0
+    /** see https://source.datanerd.us/agents/rum-specs/blob/main/browser/Log for logging spec */
+    return {
+      qs: {
+        browser_monitoring_key: this.#agentInfo.licenseKey
+      },
+      body: [{
+        common: {
+          /** Attributes in the `common` section are added to `all` logs generated in the payload */
+          attributes: {
+            'entity.guid': this.#agentRuntime.appMetadata?.agents?.[0]?.entityGuid, // browser entity guid as provided from RUM response
+            session: this.#agentRuntime?.session?.state.value || '0', // The session ID that we generate and keep across page loads
+            hasReplay: this.#agentRuntime?.session?.state.sessionReplayMode === 1, // True if a session replay recording is running
+            hasTrace: this.#agentRuntime?.session?.state.sessionTraceMode === 1, // True if a session trace recording is running
+            ptid: this.#agentRuntime.ptid, // page trace id
+            appId: this.#agentInfo.applicationID, // Application ID from info object,
+            standalone: Boolean(this.#agentInfo.sa), // copy paste (true) vs APM (false)
+            agentVersion: this.#agentRuntime.version // browser agent version
+          }
+        },
+        /** logs section contains individual unique log entries */
+        logs: this.outgoingLogs
+      }]
+    }
+  }
+
+  onHarvestFinished (result) {
+    if (!result.retry) this.outgoingLogs = []
+  }
+}

package/src/features/logging/constants.js

@@ -0,0 +1,19 @@
+import { FEATURE_NAMES } from '../../loaders/features/features'
+
+export const LOG_LEVELS = {
+  ERROR: 'ERROR',
+  WARN: 'WARN',
+  INFO: 'INFO',
+  DEBUG: 'DEBUG',
+  TRACE: 'TRACE'
+}
+
+export const LOGGING_EVENT_EMITTER_CHANNEL = 'log'
+
+export const FEATURE_NAME = FEATURE_NAMES.logging
+
+export const MAX_PAYLOAD_SIZE = 1000000
+
+export const LOGGING_FAILURE_MESSAGE = 'failed to wrap logger: '
+export const LOGGING_LEVEL_FAILURE_MESSAGE = 'invalid log level: '
+export const LOGGING_IGNORED = 'ignored log: '

package/src/features/logging/index.js

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

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

@@ -0,0 +1,18 @@
+import { InstrumentBase } from '../../utils/instrument-base'
+import { FEATURE_NAME } from '../constants'
+import { bufferLog } from '../shared/utils'
+
+export class Instrument extends InstrumentBase {
+  static featureName = FEATURE_NAME
+  constructor (agentIdentifier, aggregator, auto = true) {
+    super(agentIdentifier, aggregator, FEATURE_NAME, auto)
+
+    const instanceEE = this.ee
+    /** emitted by wrap-logger function */
+    this.ee.on('wrap-logger-end', function handleLog ([message]) {
+      const { level, customAttributes } = this
+      bufferLog(instanceEE, message, customAttributes, level)
+    })
+    this.importAggregator()
+  }
+}

package/src/features/logging/shared/log.js

@@ -0,0 +1,28 @@
+import { globalScope } from '../../../common/constants/runtime'
+import { cleanURL } from '../../../common/url/clean-url'
+import { LOG_LEVELS } from '../constants'
+
+export class Log {
+  /** @type {long} the unix timestamp of the log event */
+  timestamp
+  /** @type {string} the log message */
+  message
+  /** @type {object} the object of attributes to be parsed by logging ingest into top-level properties */
+  attributes
+  /** @type {'ERROR'|'TRACE'|'DEBUG'|'INFO'|'WARN'} the log type of the log */
+  level
+
+  /**
+   * @param {number} timestamp - Unix timestamp
+   * @param {string} message - message string
+   * @param {object} attributes - other log event attributes
+   * @param {enum} level - Log level
+   */
+  constructor (timestamp, message, attributes = {}, level = LOG_LEVELS.INFO) {
+    /** @type {long} */
+    this.timestamp = timestamp
+    this.message = message
+    this.attributes = { ...attributes, pageUrl: cleanURL('' + globalScope.location) }
+    this.level = level.toUpperCase()
+  }
+}

package/src/features/logging/shared/utils.js

@@ -0,0 +1,43 @@
+import { handle } from '../../../common/event-emitter/handle'
+import { now } from '../../../common/timing/now'
+import { warn } from '../../../common/util/console'
+import { stringify } from '../../../common/util/stringify'
+import { FEATURE_NAMES } from '../../../loaders/features/features'
+import { SUPPORTABILITY_METRIC_CHANNEL } from '../../metrics/constants'
+import { LOGGING_EVENT_EMITTER_CHANNEL, LOG_LEVELS } from '../constants'
+
+/**
+   * @param {ContextualEE} ee - The contextual ee tied to the instance
+   * @param {string} message - the log message string
+   * @param {{[key: string]: *}} customAttributes - The log's custom attributes if any
+   * @param {enum} level - the log level enum
+   */
+export function bufferLog (ee, message, customAttributes = {}, level = LOG_LEVELS.INFO) {
+  try {
+    if (typeof message !== 'string') {
+      const stringified = stringify(message)
+      /**
+       * Error instances convert to `{}` when stringified
+       * Symbol converts to '' when stringified
+       * other cases tbd
+       * */
+      if (!!stringified && stringified !== '{}') message = stringified
+      else message = String(message)
+    }
+  } catch (err) {
+    warn('could not cast log message to string', message)
+    return
+  }
+  handle(SUPPORTABILITY_METRIC_CHANNEL, [`API/logging/${level.toLowerCase()}/called`], undefined, FEATURE_NAMES.metrics, ee)
+  handle(LOGGING_EVENT_EMITTER_CHANNEL, [now(), message, customAttributes, level], undefined, FEATURE_NAMES.logging, ee)
+}
+
+/**
+ * Checks if a supplied log level is acceptable for use in generating a log event
+ * @param {string} level
+ * @returns {boolean}
+ */
+export function isValidLogLevel (level) {
+  if (typeof level !== 'string') return false
+  return Object.values(LOG_LEVELS).some(logLevel => logLevel.toUpperCase() === level.toUpperCase())
+}

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

@@ -42,7 +42,6 @@ export class Aggregate extends AggregateBase {
     registerHandler('docHidden', msTimestamp => this.endCurrentSession(msTimestamp), this.featureName, this.ee)
     registerHandler('winPagehide', msTimestamp => this.recordPageUnload(msTimestamp), this.featureName, this.ee)
 
-    const initialHarvestSeconds = getConfigurationValue(this.agentIdentifier, 'page_view_timing.initialHarvestSeconds') || 10
     const harvestTimeSeconds = getConfigurationValue(this.agentIdentifier, 'page_view_timing.harvestTimeSeconds') || 30
 
     this.waitForFlags(([])).then(() => {
@@ -69,7 +68,7 @@ export class Aggregate extends AggregateBase {
         onFinished: (...args) => this.onHarvestFinished(...args),
         getPayload: (...args) => this.prepareHarvest(...args)
       }, this)
-      scheduler.startTimer(harvestTimeSeconds, initialHarvestSeconds)
+      scheduler.startTimer(harvestTimeSeconds)
 
       this.drain()
     })

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

@@ -282,7 +282,7 @@ export class Aggregate extends AggregateBase {
     }
 
     if (len > MAX_PAYLOAD_SIZE) {
-      this.abort(ABORT_REASONS.TOO_BIG)
+      this.abort(ABORT_REASONS.TOO_BIG, len)
       return
     }
     // TODO -- Gracefully handle the buffer for retries.
@@ -393,9 +393,9 @@ export class Aggregate extends AggregateBase {
   }
 
   /** Abort the feature, once aborted it will not resume */
-  abort (reason = {}) {
+  abort (reason = {}, data) {
     warn(`SR aborted -- ${reason.message}`)
-    handle(SUPPORTABILITY_METRIC_CHANNEL, [`SessionReplay/Abort/${reason.sm}`], undefined, FEATURE_NAMES.metrics, this.ee)
+    handle(SUPPORTABILITY_METRIC_CHANNEL, [`SessionReplay/Abort/${reason.sm}`, data], undefined, FEATURE_NAMES.metrics, this.ee)
     this.blocked = true
     this.mode = MODE.OFF
     this.recorder?.stopRecording?.()

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

@@ -42,15 +42,23 @@ export class Aggregate extends AggregateBase {
     if (this.blocked || !this.entitled) return deregisterDrain(this.agentIdentifier, this.featureName)
 
     if (!this.initialized) {
+      this.initialized = true
+      /** Store session identifiers at initialization time to be cross-checked later at harvest time for session changes that are subject to race conditions */
+      this.ptid = this.agentRuntime.ptid
+      this.sessionId = this.agentRuntime.session?.state.value
       // The SessionEntity class can emit a message indicating the session was cleared and reset (expiry, inactivity). This feature must abort and never resume if that occurs.
       this.ee.on(SESSION_EVENTS.RESET, () => {
-        this.abort()
+        if (this.blocked) return
+        this.abort(1)
       })
       // The SessionEntity can have updates (locally or across tabs for SR mode changes), (across tabs for ST mode changes).
       // Those updates should be sync'd here to ensure this page also honors the mode after initialization
       this.ee.on(SESSION_EVENTS.UPDATE, (eventType, sessionState) => {
+        if (this.blocked) return
         // this will only have an effect if ST is NOT already in full mode
         if (this.mode !== MODE.FULL && (sessionState.sessionReplayMode === MODE.FULL || sessionState.sessionTraceMode === MODE.FULL)) this.switchToFull()
+        // if another page's session entity has expired, or another page has transitioned to off and this one hasn't... we can just abort straight away here
+        if (this.sessionId !== sessionState.value || (eventType === 'cross-tab' && this.scheduler?.started && sessionState.sessionTraceMode === MODE.OFF)) this.abort(2)
       })
     }
 
@@ -59,7 +67,6 @@ export class Aggregate extends AggregateBase {
     if (!this.agentRuntime.session.isNew && !ignoreSession) this.mode = this.agentRuntime.session.state.sessionTraceMode
     else this.mode = stMode
 
-    this.initialized = true
     /** If the mode is off, we do not want to hold up draining for other features, so we deregister the feature for now.
      * If it drains later (due to a mode change), data and handlers will instantly drain instead of waiting for the registry. */
     if (this.mode === MODE.OFF) return deregisterDrain(this.agentIdentifier, this.featureName)
@@ -111,9 +118,8 @@ export class Aggregate extends AggregateBase {
   prepareHarvest (options = {}) {
     this.traceStorage.prevStoredEvents.clear() // release references to past events for GC
     if (!this.timeKeeper?.ready) return // this should likely never happen, but just to be safe, we should never harvest if we cant correct time
-    if (this.mode === MODE.OFF && this.traceStorage.nodeCount === 0) return
-    if (this.mode === MODE.ERROR) return // Trace in this mode should never be harvesting, even on unload
-
+    if (this.blocked || this.mode !== MODE.FULL || this.traceStorage.nodeCount === 0) return
+    if (this.sessionId !== this.agentRuntime.session?.state.value || this.ptid !== this.agentRuntime.ptid) return this.abort(3) // if something unexpected happened and we somehow still got to the point of harvesting after a session identifier changed, we should force-exit instead of harvesting
     /** Get the ST nodes from the traceStorage buffer.  This also returns helpful metadata about the payload. */
     const { stns, earliestTimeStamp, latestTimeStamp } = this.traceStorage.takeSTNs()
     if (!stns) return // there are no trace nodes
@@ -160,8 +166,8 @@ export class Aggregate extends AggregateBase {
           agentVersion: this.agentRuntime.version,
           ...(firstSessionHarvest && { firstSessionHarvest }),
           ...(hasReplay && { hasReplay }),
-          ptid: `${this.agentRuntime.ptid}`,
-          session: `${this.agentRuntime.session?.state.value}`,
+          ptid: `${this.ptid}`,
+          session: `${this.sessionId}`,
           // customer-defined data should go last so that if it exceeds the query param padding limit it will be truncated instead of important attrs
           ...(endUserId && { 'enduser.id': endUserId })
           // The Query Param is being arbitrarily limited in length here.  It is also applied when estimating the size of the payload in getPayloadSize()
@@ -195,7 +201,7 @@ export class Aggregate extends AggregateBase {
   }
 
   /** Stop running for the remainder of the page lifecycle */
-  abort () {
+  abort (reason) {
     this.blocked = true
     this.mode = MODE.OFF
     this.agentRuntime.session.write({ sessionTraceMode: this.mode })

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

@@ -574,7 +574,7 @@ export class Aggregate extends AggregateBase {
       var interaction = this.ixn
       var node = activeNodeFor(interaction)
       setCurrentNode(null)
-      node.child('customEnd', timestamp).finish(timestamp)
+      node.child('customEnd', timestamp)?.finish(timestamp)
       interaction.finish()
     }, this.featureName, baseEE)
 

package/src/features/utils/lazy-feature-loader.js

@@ -18,6 +18,8 @@ export function lazyFeatureLoader (featureName, featurePart) {
         return import(/* webpackChunkName: "ajax-aggregate" */ '../ajax/aggregate')
       case FEATURE_NAMES.jserrors:
         return import(/* webpackChunkName: "jserrors-aggregate" */ '../jserrors/aggregate')
+      case FEATURE_NAMES.logging:
+        return import(/* webpackChunkName: "logging-aggregate" */ '../logging/aggregate')
       case FEATURE_NAMES.metrics:
         return import(/* webpackChunkName: "metrics-aggregate" */ '../metrics/aggregate')
       case FEATURE_NAMES.pageAction:

package/src/loaders/agent-base.js

@@ -53,8 +53,8 @@ export class AgentBase {
    * Adds a user-defined attribute name and value to subsequent events on the page.
    * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/setcustomattribute/}
    * @param {string} name Name of the attribute. Appears as column in the PageView event. It will also appear as a column in the PageAction event if you are using it.
-   * @param {string|number|null} value Value of the attribute. Appears as the value in the named attribute column in the PageView event. It will appear as a column in the PageAction event if you are using it. Custom attribute values cannot be complex objects, only simple types such as Strings and Integers.
-   * @param {boolean} [persist] Default false. f set to true, the name-value pair will also be set into the browser's storage API. Then on the following instrumented pages that load within the same session, the pair will be re-applied as a custom attribute.
+   * @param {string|number|boolean|null} value Value of the attribute. Appears as the value in the named attribute column in the PageView event. It will appear as a column in the PageAction event if you are using it. Custom attribute values cannot be complex objects, only simple types such as Strings, Integers and Booleans. Passing a null value unsets any existing attribute of the same name.
+   * @param {boolean} [persist] Default false. If set to true, the name-value pair will also be set into the browser's storage API. Then on the following instrumented pages that load within the same session, the pair will be re-applied as a custom attribute.
    */
   setCustomAttribute (name, value, persist) {
     return this.#callMethod('setCustomAttribute', name, value, persist)
@@ -181,4 +181,25 @@ export class AgentBase {
   interaction () {
     return this.#callMethod('interaction')
   }
+
+  /**
+   * Capture a single log.
+   * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/loginfo/}
+   * @param {string} message String to be captured as log message
+   * @param {{customAttributes?: object, level?: 'ERROR'|'TRACE'|'DEBUG'|'INFO'|'WARN'}} [options] customAttributes defaults to `{}` if not assigned, level defaults to `info` if not assigned.
+  */
+  log (message, options) {
+    return this.#callMethod('logInfo', message, options)
+  }
+
+  /**
+   * Wrap a logger function to capture a log each time the function is invoked with the message and arguments passed
+   * {@link https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/wraplogger/}
+   * @param {object} parent The parent object containing the logger method
+   * @param {string} functionName The property name of the function in the parent object to be wrapped
+   * @param {{customAttributes?: object, level?: 'ERROR'|'TRACE'|'DEBUG'|'INFO'|'WARN'}} [options] customAttributes defaults to `{}` if not assigned, level defaults to `info` if not assigned.
+  */
+  wrapLogger (parent, functionName, options) {
+    return this.#callMethod('wrapLogger', parent, functionName, options)
+  }
 }

package/src/loaders/api/api-methods.js

@@ -4,7 +4,7 @@ export const apiMethods = [
   'setErrorHandler', 'finished', 'addToTrace', 'addRelease',
   'addPageAction', 'setCurrentRouteName', 'setPageViewName', 'setCustomAttribute',
   'interaction', 'noticeError', 'setUserId', 'setApplicationVersion', 'start',
-  SR_EVENT_EMITTER_TYPES.RECORD, SR_EVENT_EMITTER_TYPES.PAUSE
+  SR_EVENT_EMITTER_TYPES.RECORD, SR_EVENT_EMITTER_TYPES.PAUSE, 'log', 'wrapLogger'
 ]
 
 export const asyncApiMethods = [

package/src/loaders/api/api.js

@@ -16,6 +16,9 @@ import { apiMethods, asyncApiMethods } from './api-methods'
 import { SR_EVENT_EMITTER_TYPES } from '../../features/session_replay/constants'
 import { now } from '../../common/timing/now'
 import { MODE } from '../../common/session/constants'
+import { LOGGING_FAILURE_MESSAGE, LOGGING_IGNORED, LOGGING_LEVEL_FAILURE_MESSAGE, LOG_LEVELS, MAX_PAYLOAD_SIZE } from '../../features/logging/constants'
+import { bufferLog, isValidLogLevel } from '../../features/logging/shared/utils'
+import { wrapLogger } from '../../common/wrap/wrap-logger'
 
 export function setTopLevelCallers () {
   const nr = gosCDN()
@@ -51,6 +54,21 @@ export function setAPI (agentIdentifier, forceDrain, runSoftNavOverSpa = false)
   var prefix = 'api-'
   var spaPrefix = prefix + 'ixn-'
 
+  apiInterface.log = function (message, { customAttributes = {}, level = LOG_LEVELS.INFO } = {}) {
+    if (!customAttributes || typeof customAttributes !== 'object') customAttributes = {}
+    if (typeof message !== 'string' || !message) return warn(LOGGING_IGNORED + 'invalid message')
+    if (!isValidLogLevel(level)) return warn(LOGGING_LEVEL_FAILURE_MESSAGE + level, LOG_LEVELS)
+    if (message.length > MAX_PAYLOAD_SIZE) return warn(LOGGING_IGNORED + '> ' + MAX_PAYLOAD_SIZE + ' bytes: ', message.slice(0, 25) + '...')
+    bufferLog(instanceEE, message, customAttributes, level.toUpperCase())
+  }
+
+  apiInterface.wrapLogger = (parent, functionName, { customAttributes = {}, level = LOG_LEVELS.INFO } = {}) => {
+    if (!customAttributes || typeof customAttributes !== 'object') customAttributes = {}
+    if (!(typeof parent === 'object' && !!parent && typeof functionName === 'string' && !!functionName && typeof parent[functionName] === 'function' && typeof customAttributes === 'object')) return warn(LOGGING_FAILURE_MESSAGE + 'invalid argument(s)')
+    if (!isValidLogLevel(level)) return warn(LOGGING_FAILURE_MESSAGE + LOGGING_LEVEL_FAILURE_MESSAGE + level, LOG_LEVELS)
+    wrapLogger(instanceEE, parent, functionName, { customAttributes, level: level.toUpperCase() })
+  }
+
   // Setup stub functions that queue calls for later processing.
   asyncApiMethods.forEach(fnName => { apiInterface[fnName] = apiCall(prefix, fnName, true, 'api') })
 
@@ -66,7 +84,7 @@ export function setAPI (agentIdentifier, forceDrain, runSoftNavOverSpa = false)
   /**
    * Attach the key-value attribute onto agent payloads. All browser events in NR will be affected.
    * @param {string} key
-   * @param {string|number|null} value - null indicates the key should be removed or erased
+   * @param {string|number|boolean|null} value - null indicates the key should be removed or erased
    * @param {string} apiName
    * @param {boolean} addToBrowserStorage - whether this attribute should be stored in browser storage API and retrieved by the next agent context or initialization
    * @returns @see apiCall

package/src/loaders/features/features.js

@@ -1,6 +1,7 @@
 export const FEATURE_NAMES = {
   ajax: 'ajax',
   jserrors: 'jserrors',
+  logging: 'logging',
   metrics: 'metrics',
   pageAction: 'page_action',
   pageViewEvent: 'page_view_event',
@@ -20,10 +21,11 @@ export const featurePriority = {
   [FEATURE_NAMES.pageViewTiming]: 2,
   [FEATURE_NAMES.metrics]: 3,
   [FEATURE_NAMES.jserrors]: 4,
-  [FEATURE_NAMES.ajax]: 5,
-  [FEATURE_NAMES.sessionTrace]: 6,
-  [FEATURE_NAMES.pageAction]: 7,
-  [FEATURE_NAMES.spa]: 8,
+  [FEATURE_NAMES.spa]: 5,
+  [FEATURE_NAMES.ajax]: 6,
+  [FEATURE_NAMES.sessionTrace]: 7,
+  [FEATURE_NAMES.pageAction]: 8,
   [FEATURE_NAMES.softNav]: 9,
-  [FEATURE_NAMES.sessionReplay]: 10
+  [FEATURE_NAMES.sessionReplay]: 10,
+  [FEATURE_NAMES.logging]: 11
 }