@newrelic/browser-agent 1.260.1 → 1.261.0

package/dist/esm/common/wrap/wrap-logger.js

@@ -0,0 +1,48 @@
+/*
+ * 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/dist/esm/features/logging/aggregate/index.js

@@ -0,0 +1,95 @@
+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/dist/esm/features/logging/constants.js

@@ -0,0 +1,14 @@
+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/dist/esm/features/logging/index.js

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

package/dist/esm/features/logging/instrument/index.js

@@ -0,0 +1,21 @@
+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) {
+    let auto = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
+    super(agentIdentifier, aggregator, FEATURE_NAME, auto);
+    const instanceEE = this.ee;
+    /** emitted by wrap-logger function */
+    this.ee.on('wrap-logger-end', function handleLog(_ref) {
+      let [message] = _ref;
+      const {
+        level,
+        customAttributes
+      } = this;
+      bufferLog(instanceEE, message, customAttributes, level);
+    });
+    this.importAggregator();
+  }
+}

package/dist/esm/features/logging/shared/log.js

@@ -0,0 +1,32 @@
+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) {
+    let attributes = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    let level = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : LOG_LEVELS.INFO;
+    /** @type {long} */
+    this.timestamp = timestamp;
+    this.message = message;
+    this.attributes = {
+      ...attributes,
+      pageUrl: cleanURL('' + globalScope.location)
+    };
+    this.level = level.toUpperCase();
+  }
+}

package/dist/esm/features/logging/shared/utils.js

@@ -0,0 +1,44 @@
+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) {
+  let customAttributes = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  let level = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 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/".concat(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/dist/esm/features/page_view_timing/aggregate/index.js

@@ -42,7 +42,6 @@ export class Aggregate extends AggregateBase {
     if (getConfigurationValue(this.agentIdentifier, 'page_view_timing.long_task') === true) longTask.subscribe(this.#handleVitalMetric);
     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(() => {
       /* It's important that CWV api, like "onLCP", is called before the **scheduler** is initialized. The reason is because they listen to the same
@@ -79,7 +78,7 @@ export class Aggregate extends AggregateBase {
           return _this.prepareHarvest(...arguments);
         }
       }, this);
-      scheduler.startTimer(harvestTimeSeconds, initialHarvestSeconds);
+      scheduler.startTimer(harvestTimeSeconds);
       this.drain();
     });
   }

package/dist/esm/features/session_replay/aggregate/index.js

@@ -298,7 +298,7 @@ export class Aggregate extends AggregateBase {
       this.scheduler.opts.gzip = false;
     }
     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.
@@ -415,8 +415,9 @@ export class Aggregate extends AggregateBase {
   /** Abort the feature, once aborted it will not resume */
   abort() {
     let reason = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    let data = arguments.length > 1 ? arguments[1] : undefined;
     warn("SR aborted -- ".concat(reason.message));
-    handle(SUPPORTABILITY_METRIC_CHANNEL, ["SessionReplay/Abort/".concat(reason.sm)], undefined, FEATURE_NAMES.metrics, this.ee);
+    handle(SUPPORTABILITY_METRIC_CHANNEL, ["SessionReplay/Abort/".concat(reason.sm), data], undefined, FEATURE_NAMES.metrics, this.ee);
     this.blocked = true;
     this.mode = MODE.OFF;
     this.recorder?.stopRecording?.();

package/dist/esm/features/session_trace/aggregate/index.js

@@ -42,22 +42,30 @@ export class Aggregate extends AggregateBase {
     this.entitled ??= stEntitled;
     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);
       });
     }
 
     /** ST/SR sampling flow in BCS - https://drive.google.com/file/d/19hwt2oft-8Hh4RrjpLqEXfpP_9wYBLcq/view?usp=sharing */
     /** ST will run in the mode provided by BCS if the session IS NEW.  If not... it will use the state of the session entity to determine what mode to run in */
     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);
@@ -122,9 +130,8 @@ export class Aggregate extends AggregateBase {
     let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
     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,
@@ -180,8 +187,8 @@ export class Aggregate extends AggregateBase {
           ...(hasReplay && {
             hasReplay
           }),
-          ptid: "".concat(this.agentRuntime.ptid),
-          session: "".concat(this.agentRuntime.session?.state.value),
+          ptid: "".concat(this.ptid),
+          session: "".concat(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
@@ -223,7 +230,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({

package/dist/esm/features/spa/aggregate/index.js

@@ -536,7 +536,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);
     register(INTERACTION_API + 'ignore', function (t) {

package/dist/esm/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/dist/esm/loaders/agent-base.js

@@ -55,8 +55,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);
@@ -183,4 +183,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/dist/esm/loaders/api/api-methods.js

@@ -1,3 +1,3 @@
 import { SR_EVENT_EMITTER_TYPES } from '../../features/session_replay/constants';
-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];
+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, 'log', 'wrapLogger'];
 export const asyncApiMethods = ['setErrorHandler', 'finished', 'addToTrace', 'addRelease'];

package/dist/esm/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();
   apiMethods.forEach(f => {
@@ -52,6 +55,30 @@ export function setAPI(agentIdentifier, forceDrain) {
   });
   var prefix = 'api-';
   var spaPrefix = prefix + 'ixn-';
+  apiInterface.log = function (message) {
+    let {
+      customAttributes = {},
+      level = LOG_LEVELS.INFO
+    } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    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 = function (parent, functionName) {
+    let {
+      customAttributes = {},
+      level = LOG_LEVELS.INFO
+    } = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    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 => {
@@ -68,7 +95,7 @@ export function setAPI(agentIdentifier, forceDrain) {
   /**
    * 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/dist/esm/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
 };

package/dist/types/common/config/state/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../../src/common/config/state/init.js"],"names":[],"mappings":"AA8GA,+CAIC;AAED,0DAKC;AAED,+DAYC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../../src/common/config/state/init.js"],"names":[],"mappings":"AAgHA,+CAIC;AAED,0DAKC;AAED,+DAYC"}

package/dist/types/common/drain/drain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../../../src/common/drain/drain.js"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,+CAHW,MAAM,SACN,MAAM,QAQhB;AAED;;;;GAIG;AACH,wEAIC;AAYD;;;;;;GAMG;AACH,wCAJW,MAAM,gBACN,MAAM,UACN,OAAO,QAajB"}
+{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../../../../src/common/drain/drain.js"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,+CAHW,MAAM,SACN,MAAM,QAQhB;AAED;;;;GAIG;AACH,iDAHW,GAAC,SACD,GAAC,QAMX;AAYD;;;;;;GAMG;AACH,wCAJW,MAAM,gBACN,MAAM,UACN,OAAO,QAajB"}

package/dist/types/common/harvest/harvest-scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harvest-scheduler.d.ts","sourceRoot":"","sources":["../../../../src/common/harvest/harvest-scheduler.js"],"names":[],"mappings":"AAWA;;GAEG;AACH;IACE;;;;;;;;;;SAUK;IACL,sBATa,MAAM;QAES,UAAU;QACV,UAAU;QACZ,UAAU,EAAvB,MAAM;QACQ,GAAG,EAAjB,OAAO;QACM,SAAS,EAAtB,MAAM;oBAoBlB;IAfC,iBAAwB;IACxB;;;oBARW,MAAM;aACN,OAAO;mBACP,MAAM;MAMK;IACtB,iBAAoB;IACpB,mBAAyB;IACzB,iBAAoB;IACpB,oBAAuB;IACvB,iBAA8C;IAWhD;;;OAGG;IACH,eAKC;IAED,mDAIC;IAHC,cAAwB;IAK1B,uCAMC;IAED,6CAUC;IAED,yCAgEC;IAED,gDAiBC;CACF;8BAhK6B,2BAA2B;wBACjC,WAAW"}
+{"version":3,"file":"harvest-scheduler.d.ts","sourceRoot":"","sources":["../../../../src/common/harvest/harvest-scheduler.js"],"names":[],"mappings":"AAWA;;GAEG;AACH;IACE;;;;;;;;;;SAUK;IACL,sBATa,MAAM,QAEd;QAAuB,UAAU;QACV,UAAU;QACZ,UAAU,EAAvB,MAAM;QACQ,GAAG,EAAjB,OAAO;QACM,SAAS,EAAtB,MAAM;KACd,UAAQ,GAAC,EAmBb;IAfC,iBAAwB;IACxB;;;oBARW,MAAM;aACN,OAAO;mBACP,MAAM;MAMK;IACtB,iBAAoB;IACpB,mBAAyB;IACzB,iBAAoB;IACpB,oBAAuB;IACvB,iBAA8C;IAWhD;;;OAGG;IACH,eAKC;IAED,mDAIC;IAHC,cAAwB;IAK1B,uCAMC;IAED,6CAUC;IAED,yCAgEC;IAED,gDAiBC;CACF;8BAhK6B,2BAA2B;wBACjC,WAAW"}

package/dist/types/common/harvest/harvest.d.ts

@@ -61,11 +61,11 @@ export class Harvest extends SharedContext {
      */
     on(endpoint: HarvestEndpointIdentifier, listener: FeatureHarvestCallback): void;
 }
-export type NetworkSendSpec = import('./types.js').NetworkSendSpec;
-export type HarvestEndpointIdentifier = import('./types.js').HarvestEndpointIdentifier;
-export type HarvestPayload = import('./types.js').HarvestPayload;
-export type FeatureHarvestCallback = import('./types.js').FeatureHarvestCallback;
-export type FeatureHarvestCallbackOptions = import('./types.js').FeatureHarvestCallbackOptions;
+export type NetworkSendSpec = import("./types.js").NetworkSendSpec;
+export type HarvestEndpointIdentifier = import("./types.js").HarvestEndpointIdentifier;
+export type HarvestPayload = import("./types.js").HarvestPayload;
+export type FeatureHarvestCallback = import("./types.js").FeatureHarvestCallback;
+export type FeatureHarvestCallbackOptions = import("./types.js").FeatureHarvestCallbackOptions;
 import { SharedContext } from '../context/shared-context';
 import { Obfuscator } from '../util/obfuscate';
 //# sourceMappingURL=harvest.d.ts.map

package/dist/types/common/harvest/types.d.ts

@@ -38,7 +38,7 @@
  * @property {boolean} includeBaseParams Enables the use of base query parameters in the beacon url
  */
 export const unused: {};
-export type HarvestEndpointIdentifier = 'rum' | 'jserrors' | 'events' | 'ins' | 'resources' | 'blob';
+export type HarvestEndpointIdentifier = "rum" | "jserrors" | "events" | "ins" | "resources" | "blob";
 export type HarvestPayload = {
     /**
      * Map of values that should be sent as part of the request query string.
@@ -83,7 +83,7 @@ export type NetworkSendSpec = {
     /**
      * The network method to use {@link  ../util/submit-data.js}
      */
-    submitMethod: import('../util/submit-data.js').NetworkMethods;
+    submitMethod: import("../util/submit-data.js").NetworkMethods;
     /**
      * Override the beacon url the data is sent to; must include protocol if defined
      */

package/dist/types/common/harvest/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/common/harvest/types.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAGH,wBAAwB;wCAvCX,KAAK,GAAC,UAAU,GAAC,QAAQ,GAAC,KAAK,GAAC,WAAW,GAAC,MAAM;;;;;QAKjD,MAAM;;;;;QAEO,CAAC,EAAd,MAAM;;;;;;;;;;;WAKN,OAAO;;+CAMV,6BAA6B,KAC3B,cAAc;;;;;cAKb,yBAAyB;;;;aACzB,cAAc;;;;;QAEA,YAAY,EAA1B,OAAO;QACO,MAAM,EAApB,OAAO;QACO,aAAa,EAA3B,OAAO;QACO,KAAK,EAAnB,OAAO;;;;;kBAEP,OAAO,wBAAwB,EAAE,cAAc;;;;eAC/C,MAAM;;;;SACN,OAAO;;;;uBACP,OAAO"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/common/harvest/types.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAGH,wBAAwB;wCAvCX,KAAK,GAAC,UAAU,GAAC,QAAQ,GAAC,KAAK,GAAC,WAAW,GAAC,MAAM;;;;;QAKjD,MAAM;;;;UAEjB;QAAwB,CAAC,EAAd,MAAM;KACnB;;;;;;;;;;WAIa,OAAO;;+CAMV,6BAA6B,KAC3B,cAAc;;;;;cAKb,yBAAyB;;;;aACzB,cAAc;;;;UAEzB;QAAyB,YAAY,EAA1B,OAAO;QACO,MAAM,EAApB,OAAO;QACO,aAAa,EAA3B,OAAO;QACO,KAAK,EAAnB,OAAO;KAElB;;;;kBAAW,OAAO,wBAAwB,EAAE,cAAc;;;;eAC/C,MAAM;;;;SACN,OAAO;;;;uBACP,OAAO"}

package/dist/types/common/ids/id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../../../src/common/ids/id.js"],"names":[],"mappings":"AAaA;;;;;;;;;GASG;AACH,wBAHW,MAAM,mBAAe,GACnB,MAAM,CAUlB"}
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../../../src/common/ids/id.js"],"names":[],"mappings":"AAaA;;;;;;;;;GASG;AACH,wBAHW,MAAM,cAAU,KAAK,GACnB,MAAM,CAUlB"}

package/dist/types/common/ids/unique-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unique-id.d.ts","sourceRoot":"","sources":["../../../../src/common/ids/unique-id.js"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,gCAFa,MAAM,CAwBlB;AAED;;;;;GAKG;AACH,sDAFa,MAAM,CAiBlB;AAED;;;;;GAKG;AACH,kCAFa,MAAM,CAIlB;AAED;;;;;GAKG;AACH,mCAFa,MAAM,CAIlB"}
+{"version":3,"file":"unique-id.d.ts","sourceRoot":"","sources":["../../../../src/common/ids/unique-id.js"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,gCAFa,MAAM,CAwBlB;AAED;;;;;GAKG;AACH,gDAHW,GAAG,GACD,MAAM,CAiBlB;AAED;;;;;GAKG;AACH,kCAFa,MAAM,CAIlB;AAED;;;;;GAKG;AACH,mCAFa,MAAM,CAIlB"}

package/dist/types/common/session/session-entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-entity.d.ts","sourceRoot":"","sources":["../../../../src/common/session/session-entity.js"],"names":[],"mappings":"AA8BA;IACE;;;;;OAKG;IACH,uBA0BC;IApBC,qBAAsC;IACtC,aAAsB;IACtB,UAAe;IAGf,SAAc;IAEd,QAAiC;IAenC;;;;aA4EC;IAnEC,8BAA0B;IAC1B,+BAA4B;IAc1B,gCAOqC;IAUrC,4CAkBsC;IAexC,iCAAuB;IAKzB,wBAEC;IAED,sBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CA6BlB;IAED;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,MAAM,CAkBlB;IAED,gBAuBC;IAED;;OAEG;IACH,gBAIC;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,OAAO,CAKnB;IAED,yDAUC;IAED,6DAIC;IAED;;;OAGG;IACH,6BAHW,MAAM,GACJ,MAAM,CAIlB;IAED,gDAaC;IAHG,YAAuD;CAI5D;sBAzSqB,gBAAgB;iCAGL,4BAA4B"}
+{"version":3,"file":"session-entity.d.ts","sourceRoot":"","sources":["../../../../src/common/session/session-entity.js"],"names":[],"mappings":"AA8BA;IACE;;;;;OAKG;IACH,uBA+BC;IAzBC,qBAAsC;IACtC,aAAsB;IACtB,UAAe;IAGf,SAAc;IAEd,QAAiC;IAoBnC;;;;aA4EC;IAnEC,8BAA0B;IAC1B,+BAA4B;IAc1B,gCAOqC;IAUrC,4CAkBsC;IAexC,iCAAuB;IAKzB,wBAEC;IAED,sBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CA6BlB;IAED;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,MAAM,CAkBlB;IAED,gBAuBC;IAED;;OAEG;IACH,gBAIC;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,OAAO,CAKnB;IAED,yDAUC;IAED,6DAIC;IAED;;;OAGG;IACH,6BAHW,MAAM,GACJ,MAAM,CAIlB;IAED,gDAaC;IAHG,YAAuD;CAI5D;sBA9SqB,gBAAgB;iCAGL,4BAA4B"}

package/dist/types/common/util/console.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../../src/common/util/console.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,8BAJW,MAAM,yBAQhB"}
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../../src/common/util/console.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,8BAJW,MAAM,cACN,GAAC,QAOX"}

package/dist/types/common/util/data-size.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-size.d.ts","sourceRoot":"","sources":["../../../../src/common/util/data-size.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,qCAFa,CAAC,MAAM,GAAC,SAAS,CAAC,CAe9B"}
+{"version":3,"file":"data-size.d.ts","sourceRoot":"","sources":["../../../../src/common/util/data-size.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,+BAHW,GAAC,GACC,CAAC,MAAM,GAAC,SAAS,CAAC,CAe9B"}

package/dist/types/common/util/feature-flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feature-flags.d.ts","sourceRoot":"","sources":["../../../../src/common/util/feature-flags.js"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH;;oBAHW,MAAM,GACJ,IAAI,CAehB;AAvBD,gGAAgG;AAChG,mCAAmC"}
+{"version":3,"file":"feature-flags.d.ts","sourceRoot":"","sources":["../../../../src/common/util/feature-flags.js"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,wCAJW;IAAC,CAAC,GAAG,EAAC,MAAM,GAAE,MAAM,CAAA;CAAC,mBACrB,MAAM,GACJ,IAAI,CAehB;AAvBD,gGAAgG;AAChG,mCAAmC"}

package/dist/types/common/util/get-or-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-or-set.d.ts","sourceRoot":"","sources":["../../../../src/common/util/get-or-set.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,8BALW,MAAM,QACN,MAAM,yBA6BhB"}
+{"version":3,"file":"get-or-set.d.ts","sourceRoot":"","sources":["../../../../src/common/util/get-or-set.js"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,8BALW,MAAM,QACN,MAAM,qBAEJ,GAAC,CA2Bb"}

package/dist/types/common/util/invoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../../../src/common/util/invoke.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,mDATW,MAAM;IAGW,OAAO,EAAxB,OAAO;aAoBjB;AAED;;;;;;;GAOG;AACH,iDAQC"}
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../../../src/common/util/invoke.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,mDATW,MAAM,YAGd;IAAyB,OAAO,EAAxB,OAAO;CAGf,YAiBF;AAED;;;;;;;GAOG;AACH,iDAQC"}

package/dist/types/common/util/stringify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stringify.d.ts","sourceRoot":"","sources":["../../../../src/common/util/stringify.js"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,qCAFa,MAAM,CAYlB"}
+{"version":3,"file":"stringify.d.ts","sourceRoot":"","sources":["../../../../src/common/util/stringify.js"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,+BAHW,GAAC,GACC,MAAM,CAYlB"}