newrelic 8.5.2 → 8.6.0

package/NEWS.md

@@ -1,3 +1,15 @@
+### v8.6.0 (2021-11-17)
+
+* Added `onResolved` instrumentation hook to apply instrumentation prior to module load.
+
+  This hook fires after the module filepath has been resolved just prior to the module being loaded by the CommonJS module loader.
+
+* Fixed issue where `recordConsume` was not binding consumer if it was a promise
+
+* Pinned mongo versioned tests to `<4.2.0` until we can address https://github.com/newrelic/node-newrelic/issues/982
+
+* Introduced a context management API to be used in place of manually calling tracer.segment get/set.
+
 ### v8.5.2 (2021-11-09)
 
 * Fixed issue where unhandled promise rejections were not getting logged as errors in a lambda execution

package/api.js

@@ -55,7 +55,8 @@ const CUSTOM_EVENT_TYPE_REGEX = /^[a-zA-Z0-9:_ ]+$/
  * You do not need to directly instantiate this class, as an instance of this is
  * the return from `require('newrelic')`.
  *
- * @constructor
+ * @param agent
+ * @class
  */
 function API(agent) {
   this.agent = agent
@@ -139,6 +140,7 @@ API.prototype.getTransaction = function getTransaction() {
  *   utilization.full_hostname. If utilization.full_hostname is null or empty,
  *   this will be the hostname specified in the connect request as host.
  *
+ * @param omitSupportability
  * @returns {LinkingMetadata} The linking object with the data above
  */
 API.prototype.getLinkingMetadata = function getLinkingMetadata(omitSupportability) {
@@ -186,7 +188,6 @@ API.prototype.getLinkingMetadata = function getLinkingMetadata(omitSupportabilit
  *
  * @param {string} name The string you would like to report to New Relic
  *                      as the dispatcher.
- *
  * @param {string} [version] The dispatcher version you would like to
  *                           report to New Relic
  */
@@ -414,7 +415,6 @@ API.prototype.addCustomSpanAttribute = function addCustomSpanAttribute(key, valu
  *
  * @param {Error} error
  *  The error to be traced.
- *
  * @param {object} [customAttributes]
  *  Optional. Any custom attributes to be displayed in the New Relic UI.
  */
@@ -526,7 +526,7 @@ API.prototype.addIgnoringRule = function addIgnoringRule(pattern) {
  * Do *not* reuse the headers between users, or even between requests.
  *
  * @param {string} [options.nonce] - Nonce to inject into `<script>` header.
- *
+ * @param options
  * @returns {string} The `<script>` header to be injected.
  */
 API.prototype.getBrowserTimingHeader = function getBrowserTimingHeader(options) {
@@ -545,7 +545,7 @@ API.prototype.getBrowserTimingHeader = function getBrowserTimingHeader(options)
    *
    * @param {number} num          - Error code from `RUM_ISSUES`.
    * @param {bool} [quite=false]  - Be quiet about this failure.
-   *
+   * @param quiet
    * @see RUM_ISSUES
    */
   function _gracefail(num, quiet) {
@@ -687,9 +687,9 @@ API.prototype.getBrowserTimingHeader = function getBrowserTimingHeader(options)
 
 /**
  * @callback startSegmentCallback
- * @param {function} cb
+ * @param {Function} cb
  *   The function to time with the created segment.
- * @return {Promise=} Returns a promise if cb returns a promise.
+ * @returns {Promise=} Returns a promise if cb returns a promise.
  */
 
 /**
@@ -701,23 +701,18 @@ API.prototype.getBrowserTimingHeader = function getBrowserTimingHeader(options)
  *    // The returned promise here will signify the end of the segment.
  *    return myAsyncTask().then(myNextTask)
  *  })
- *
  * @param {string} name
  *  The name to give the new segment. This will also be the name of the metric.
- *
  * @param {bool} record
  *  Indicates if the segment should be recorded as a metric. Metrics will show
  *  up on the transaction breakdown table and server breakdown graph. Segments
  *  just show up in transaction traces.
- *
  * @param {startSegmentCallback} handler
  *  The function to track as a segment.
- *
- * @param {function} [callback]
+ * @param {Function} [callback]
  *  An optional callback for the handler. This will indicate the end of the
  *  timing if provided.
- *
- * @return {*} Returns the result of calling `handler`.
+ * @returns {*} Returns the result of calling `handler`.
  */
 API.prototype.startSegment = function startSegment(name, record, handler, callback) {
   this.agent.metrics
@@ -775,11 +770,9 @@ API.prototype.startSegment = function startSegment(name, record, handler, callba
  *     transaction.end()
  *   }, 100)
  * })
- *
  * @param {string} url
  *  The URL of the transaction.  It is used to name and group related transactions in APM,
  *  so it should be a generic name and not iclude any variable parameters.
- *
  * @param {Function}  handle
  *  Function that represents the transaction work.
  */
@@ -862,20 +855,16 @@ API.prototype.startBackgroundTransaction = startBackgroundTransaction
  *     transaction.end()
  *   }, 100)
  * })
- *
  * @param {string} name
  *  The name of the transaction. It is used to name and group related
  *  transactions in APM, so it should be a generic name and not iclude any
  *  variable parameters.
- *
  * @param {string} [group]
  *  Optional, used for grouping background transactions in APM. For more
  *  information see:
  *  https://docs.newrelic.com/docs/apm/applications-menu/monitoring/transactions-page#txn-type-dropdown
- *
  * @param {Function} handle
  *  Function that represents the background work.
- *
  * @memberOf API#
  */
 function startBackgroundTransaction(name, group, handle) {
@@ -972,9 +961,9 @@ API.prototype.endTransaction = function endTransaction() {
  * Record a custom metric, usually associated with a particular duration.
  * The `name` must be a string following standard metric naming rules. The `value` will
  * usually be a number, but it can also be an object.
- *   * When `value` is a numeric value, it should represent the magnitude of a measurement
+ *   When `value` is a numeric value, it should represent the magnitude of a measurement
  *     associated with an event; for example, the duration for a particular method call.
- *   * When `value` is an object, it must contain count, total, min, max, and sumOfSquares
+ *   When `value` is an object, it must contain count, total, min, max, and sumOfSquares
  *     keys, all with number values. This form is useful to aggregate metrics on your own
  *     and report them periodically; for example, from a setInterval. These values will
  *     be aggregated with any previously collected values for the same metric. The names
@@ -1151,18 +1140,15 @@ API.prototype.recordCustomEvent = function recordCustomEvent(eventType, attribut
  *  - `newrelic.instrument(moduleName, onRequire [,onError])`
  *  - `newrelic.instrument(options)`
  *
- * @param {object} options
- *  The options for this custom instrumentation.
- *
- * @param {string} options.moduleName
- *  The module name given to require to load the module
- *
- * @param {function}  options.onRequire
- *  The function to call when the module is required
- *
- * @param {function} [options.onError]
- *  If provided, should `onRequire` throw an error, the error will be passed to
+ * @param {object} options The options for this custom instrumentation.
+ * @param {string} options.moduleName The module name given to require to load the module
+ * @param {Function}  options.onResolved The function to call prior to module load after the filepath has been resolved
+ * @param {Function}  options.onRequire The function to call when the module has been loaded
+ * @param {Function} [options.onError] If provided, should `onRequire` throw an error, the error will be passed to
  *  this function.
+ * @param moduleName
+ * @param onRequire
+ * @param onError
  */
 API.prototype.instrument = function instrument(moduleName, onRequire, onError) {
   const metric = this.agent.metrics.getOrCreateMetric(NAMES.SUPPORTABILITY.API + '/instrument')
@@ -1187,18 +1173,15 @@ API.prototype.instrument = function instrument(moduleName, onRequire, onError) {
  * - `newrelic.instrumentConglomerate(moduleName, onRequire [, onError])`
  * - `newrelic.isntrumentConglomerate(options)`
  *
- * @param {object} options
- *  The options for this custom instrumentation.
- *
- * @param {string} options.moduleName
- *  The module name given to require to load the module
- *
- * @param {function} options.onRequire
- *  The function to call when the module is required
- *
- * @param {function} [options.onError]
- *  If provided, should `onRequire` throw an error, the error will be passed to
+ * @param {object} options The options for this custom instrumentation.
+ * @param {string} options.moduleName The module name given to require to load the module
+ * @param {Function}  options.onResolved The function to call prior to module load after the filepath has been resolved
+ * @param {Function}  options.onRequire The function to call when the module has been loaded
+ * @param {Function} [options.onError] If provided, should `onRequire` throw an error, the error will be passed to
  *  this function.
+ * @param moduleName
+ * @param onRequire
+ * @param onError
  */
 API.prototype.instrumentConglomerate = function instrumentConglomerate(
   moduleName,
@@ -1224,18 +1207,15 @@ API.prototype.instrumentConglomerate = function instrumentConglomerate(
  *  - `newrelic.instrumentDatastore(moduleName, onRequire [,onError])`
  *  - `newrelic.instrumentDatastore(options)`
  *
- * @param {object} options
- *  The options for this custom instrumentation.
- *
- * @param {string} options.moduleName
- *  The module name given to require to load the module
- *
- * @param {function} options.onRequire
- *  The function to call when the module is required
- *
- * @param {function} [options.onError]
- *  If provided, should `onRequire` throw an error, the error will be passed to
+ * @param {object} options The options for this custom instrumentation.
+ * @param {string} options.moduleName The module name given to require to load the module
+ * @param {Function}  options.onResolved The function to call prior to module load after the filepath has been resolved
+ * @param {Function}  options.onRequire The function to call when the module has been loaded
+ * @param {Function} [options.onError] If provided, should `onRequire` throw an error, the error will be passed to
  *  this function.
+ * @param moduleName
+ * @param onRequire
+ * @param onError
  */
 API.prototype.instrumentDatastore = function instrumentDatastore(moduleName, onRequire, onError) {
   const metric = this.agent.metrics.getOrCreateMetric(
@@ -1256,77 +1236,21 @@ API.prototype.instrumentDatastore = function instrumentDatastore(moduleName, onR
   shimmer.registerInstrumentation(opts)
 }
 
-/**
- * Applies an instrumentation to an already loaded module.
- *
- *    // oh no, express was loaded before newrelic
- *    const express   = require('express')
- *    const newrelic  = require('newrelic')
- *
- *    // phew, we can use instrumentLoadedModule to make
- *    // sure express is still instrumented
- *    newrelic.instrumentLoadedModule('express', express)
- *
- * @param {string} moduleName
- *  The module's name/identifier.  Will be normalized
- *  into an instrumentation key.
- *
- * @param {object} module
- *  The actual module object or function we're instrumenting
- */
-API.prototype.instrumentLoadedModule = function instrumentLoadedModule(moduleName, module) {
-  const metric = this.agent.metrics.getOrCreateMetric(
-    NAMES.SUPPORTABILITY.API + '/instrumentLoadedModule'
-  )
-  metric.incrementCallCount()
-  try {
-    const instrumentationName = shimmer.getInstrumentationNameFromModuleName(moduleName)
-    if (!shimmer.registeredInstrumentations[instrumentationName]) {
-      logger.warn("No instrumentation registered for '%s'.", instrumentationName)
-      return false
-    }
-
-    const instrumentation = shimmer.registeredInstrumentations[instrumentationName]
-    if (!instrumentation.onRequire) {
-      logger.warn("No onRequire function registered for '%s'.", instrumentationName)
-      return false
-    }
-
-    const resolvedName = require.resolve(moduleName)
-
-    const shim = shims.createShimFromType(
-      instrumentation.type,
-      this.agent,
-      moduleName,
-      resolvedName
-    )
-
-    instrumentation.onRequire(shim, module, moduleName)
-
-    return true
-  } catch (error) {
-    logger.error('instrumentLoadedModule encountered an error, module not instrumentend: %s', error)
-  }
-}
-
 /**
  * Registers an instrumentation function.
  *
  *  - `newrelic.instrumentWebframework(moduleName, onRequire [,onError])`
  *  - `newrelic.instrumentWebframework(options)`
  *
- * @param {object} options
- *  The options for this custom instrumentation.
- *
- * @param {string} options.moduleName
- *  The module name given to require to load the module
- *
- * @param {function}  options.onRequire
- *  The function to call when the module is required
- *
- * @param {function} [options.onError]
- *  If provided, should `onRequire` throw an error, the error will be passed to
+ * @param {object} options The options for this custom instrumentation.
+ * @param {string} options.moduleName The module name given to require to load the module
+ * @param {Function}  options.onResolved The function to call prior to module load after the filepath has been resolved
+ * @param {Function}  options.onRequire The function to call when the module has been loaded
+ * @param {Function} [options.onError] If provided, should `onRequire` throw an error, the error will be passed to
  *  this function.
+ * @param moduleName
+ * @param onRequire
+ * @param onError
  */
 API.prototype.instrumentWebframework = function instrumentWebframework(
   moduleName,
@@ -1357,18 +1281,15 @@ API.prototype.instrumentWebframework = function instrumentWebframework(
  *  - `newrelic.instrumentMessages(moduleName, onRequire [,onError])`
  *  - `newrelic.instrumentMessages(options)`
  *
- * @param {object} options
- *  The options for this custom instrumentation.
- *
- * @param {string} options.moduleName
- *  The module name given to require to load the module
- *
- * @param {function}  options.onRequire
- *  The function to call when the module is required
- *
- * @param {function} [options.onError]
- *  If provided, should `onRequire` throw an error, the error will be passed to
+ * @param {object} options The options for this custom instrumentation.
+ * @param {string} options.moduleName The module name given to require to load the module
+ * @param {Function}  options.onResolved The function to call prior to module load after the filepath has been resolved
+ * @param {Function}  options.onRequire The function to call when the module has been loaded
+ * @param {Function} [options.onError] If provided, should `onRequire` throw an error, the error will be passed to
  *  this function.
+ * @param moduleName
+ * @param onRequire
+ * @param onError
  */
 API.prototype.instrumentMessages = function instrumentMessages(moduleName, onRequire, onError) {
   const metric = this.agent.metrics.getOrCreateMetric(
@@ -1389,6 +1310,58 @@ API.prototype.instrumentMessages = function instrumentMessages(moduleName, onReq
   shimmer.registerInstrumentation(opts)
 }
 
+/**
+ * Applies an instrumentation to an already loaded module.
+ *
+ *    // oh no, express was loaded before newrelic
+ *    const express   = require('express')
+ *    const newrelic  = require('newrelic')
+ *
+ *    // phew, we can use instrumentLoadedModule to make
+ *    // sure express is still instrumented
+ *    newrelic.instrumentLoadedModule('express', express)
+ *
+ * @param {string} moduleName
+ *  The module's name/identifier.  Will be normalized
+ *  into an instrumentation key.
+ * @param {object} module
+ *  The actual module object or function we're instrumenting
+ */
+API.prototype.instrumentLoadedModule = function instrumentLoadedModule(moduleName, module) {
+  const metric = this.agent.metrics.getOrCreateMetric(
+    NAMES.SUPPORTABILITY.API + '/instrumentLoadedModule'
+  )
+  metric.incrementCallCount()
+  try {
+    const instrumentationName = shimmer.getInstrumentationNameFromModuleName(moduleName)
+    if (!shimmer.registeredInstrumentations[instrumentationName]) {
+      logger.warn("No instrumentation registered for '%s'.", instrumentationName)
+      return false
+    }
+
+    const instrumentation = shimmer.registeredInstrumentations[instrumentationName]
+    if (!instrumentation.onRequire) {
+      logger.warn("No onRequire function registered for '%s'.", instrumentationName)
+      return false
+    }
+
+    const resolvedName = require.resolve(moduleName)
+
+    const shim = shims.createShimFromType(
+      instrumentation.type,
+      this.agent,
+      moduleName,
+      resolvedName
+    )
+
+    instrumentation.onRequire(shim, module, moduleName)
+
+    return true
+  } catch (error) {
+    logger.error('instrumentLoadedModule encountered an error, module not instrumented: %s', error)
+  }
+}
+
 /**
  * Returns the current trace and span id.
  *
@@ -1424,19 +1397,16 @@ API.prototype.getTraceMetadata = function getTraceMetadata() {
  *
  * @param {object} [options]
  *  Object with shut down options.
- *
  * @param {boolean} [options.collectPendingData=false]
  *  If true, the agent will send any pending data to the collector before
  *  shutting down.
- *
  * @param {number} [options.timeout=0]
  *  Time in milliseconds to wait before shutting down.
- *
  * @param {boolean} [options.waitForIdle=false]
  *  If true, the agent will not shut down until there are no active transactions.
- *
- * @param {function} [callback]
+ * @param {Function} [callback]
  *  Callback function that runs when agent stops.
+ * @param cb
  */
 API.prototype.shutdown = function shutdown(options, cb) {
   this.agent.metrics.getOrCreateMetric(`${NAMES.SUPPORTABILITY.API}/shutdown`).incrementCallCount()
@@ -1458,6 +1428,11 @@ API.prototype.shutdown = function shutdown(options, cb) {
   _doShutdown(this, options, callback)
 }
 
+/**
+ * @param api
+ * @param options
+ * @param callback
+ */
 function _doShutdown(api, options, callback) {
   const agent = api.agent
 
@@ -1473,6 +1448,9 @@ function _doShutdown(api, options, callback) {
     return
   }
 
+  /**
+   * @param error
+   */
   function afterHarvest(error) {
     if (error) {
       logger.error(error, 'An error occurred while running last harvest before shutdown.')
@@ -1506,6 +1484,10 @@ function _doShutdown(api, options, callback) {
   }
 }
 
+/**
+ * @param object
+ * @param maxLength
+ */
 function _checkKeyLength(object, maxLength) {
   const keys = Object.keys(object)
   let badKey = false
@@ -1534,6 +1516,10 @@ API.prototype.setLambdaHandler = function setLambdaHandler(handler) {
   return this.awsLambda.patchLambdaHandler(handler)
 }
 
+/**
+ * @param attributes
+ * @param name
+ */
 function _filterAttributes(attributes, name) {
   const filteredAttributes = Object.create(null)
   Object.keys(attributes).forEach((attributeKey) => {

package/lib/agent.js

@@ -29,6 +29,7 @@ const TxSegmentNormalizer = require('./metrics/normalizer/tx_segment')
 const uninstrumented = require('./uninstrumented')
 const util = require('util')
 const createSpanEventAggregator = require('./spans/create-span-event-aggregator')
+const createContextManager = require('./context-manager/create-context-manager')
 
 // Map of valid states to whether or not data collection is valid
 const STATES = {
@@ -53,6 +54,8 @@ const DEFAULT_HARVEST_INTERVAL_MS = 60000
  * This constructor can throw if, for some reason, the configuration isn't
  * available. Don't try to recover here, because without configuration the
  * agent can't be brought up to a useful state.
+ *
+ * @param config
  */
 function Agent(config) {
   EventEmitter.call(this)
@@ -136,8 +139,9 @@ function Agent(config) {
 
   this.errors = new ErrorCollector(config, errorTraceAggregator, errorEventAggregator, this.metrics)
 
+  this._contextManager = createContextManager(this.config)
   // Transaction tracing.
-  this.tracer = new Tracer(this)
+  this.tracer = new Tracer(this, this._contextManager)
   this.traces = new TransactionTraceAggregator(
     {
       periodMs: DEFAULT_HARVEST_INTERVAL_MS,
@@ -185,7 +189,6 @@ util.inherits(Agent, EventEmitter)
  * the configuration.
  *
  * @config {boolean} agent_enabled Whether to start up the agent.
- *
  * @param {Function} callback Continuation and error handler.
  */
 Agent.prototype.start = function start(callback) {
@@ -248,6 +251,7 @@ Agent.prototype.start = function start(callback) {
 
 /**
  * Forces all aggregators to send the data collected.
+ *
  * @param {Function} callback The callback to invoke when all data types have been sent.
  */
 Agent.prototype.forceHarvestAll = function forceHarvestAll(callback) {
@@ -416,6 +420,9 @@ Agent.prototype.startAggregators = function startAggregators() {
 /**
  * Completes any final setup upon full connection to New Relic
  * servers and sets the agent state to 'started'.
+ *
+ * @param shouldImmediatelyHarvest
+ * @param callback
  */
 Agent.prototype.onConnect = function onConnect(shouldImmediatelyHarvest, callback) {
   this._reconfigureAggregators(this.config)
@@ -485,6 +492,8 @@ Agent.prototype._serverlessModeStart = function _serverlessModeStart(callback) {
  * FIXME: make it possible to dispose of the agent, as well as do a
  * "hard" restart. This requires working with shimmer to strip the
  * current instrumentation and patch to the module loader.
+ *
+ * @param callback
  */
 Agent.prototype.stop = function stop(callback) {
   if (!callback) {

package/lib/context-manager/create-context-manager.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2021 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const logger = require('../logger')
+
+/**
+ * Factory function to create context manager implementations used by the
+ * ContextManager class.
+ *
+ * @param {object} config New Relic config instance.
+ * @returns {*} The appropriate underlying context manager implementation based on
+ * the current configuration.
+ */
+function createContextManager(config) {
+  if (config.logging.diagnostics) {
+    logger.info('Using LegacyDiagnosticContextManager')
+
+    const LegacyDiagnosticContextManager = require('./diagnostics/legacy-diagnostic-context-manager')
+    return new LegacyDiagnosticContextManager(config)
+  }
+
+  logger.info('Using LegacyContextManager')
+
+  const LegacyContextManager = require('./legacy-context-manager')
+  return new LegacyContextManager(config)
+}
+
+module.exports = createContextManager

package/lib/context-manager/diagnostics/legacy-diagnostic-context-manager.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2021 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const LegacyContextManager = require('../legacy-context-manager')
+
+/**
+ * Overrides setContext to add diagnostic logging around setting and removing
+ * from context. Currently just supports the segment.probe().
+ *
+ * Exists in own class to keep default context management as minimal/efficient as possible
+ * given we wrap pretty much every functions execution.
+ */
+class LegacyDiagnosticContextManager extends LegacyContextManager {
+  setContext(newContext) {
+    this._logDiagnostic(this._context, 'Removed from context')
+
+    this._context = newContext
+
+    this._logDiagnostic(newContext, 'Set in context')
+  }
+
+  _logDiagnostic(context, message) {
+    // This is to currently support diagnostic logging of segments which gets attached to
+    // transactions with a stack trace. All of this is output at once at the end of a transaction
+    // when enabled for clear tracing.
+    if (context && context.probe) {
+      context.probe(message)
+    }
+  }
+}
+
+module.exports = LegacyDiagnosticContextManager

package/lib/context-manager/legacy-context-manager.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2021 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+/**
+ * Class for managing state in the agent.
+ * Keeps track of a single context instance.
+ *
+ * Given current usage with every instrumented function, the functions in this
+ * class should do as little work as possible to avoid unnecessary overhead.
+ *
+ * @class
+ */
+class LegacyContextManager {
+  /**
+   * @param {object} config New Relic config instance
+   */
+  constructor(config) {
+    this._config = config
+    this._context = null
+  }
+
+  /**
+   * Get the currently active context.
+   *
+   * @returns {object} The current active context.
+   */
+  getContext() {
+    return this._context
+  }
+
+  /**
+   * Set a new active context. Not bound to function execution.
+   *
+   * @param {object} newContext The context to set as active.
+   */
+  setContext(newContext) {
+    this._context = newContext
+  }
+
+  /**
+   * Run a function with the passed in context as the active context.
+   * Restores the previously active context upon completion.
+   *
+   * @param {object} context The context to set as active during callback execution.
+   * @param {Function} callback The function to execute in context.
+   * @param {Function} [cbThis] Optional `this` to apply to the callback.
+   * @param {Array<*>} [args] Optional arguments object or args array to invoke the callback with.
+   * @returns {*} Returns the value returned by the callback function.
+   */
+  runInContext(context, callback, cbThis, args) {
+    const oldContext = this.getContext()
+    this.setContext(context)
+
+    try {
+      return callback.apply(cbThis, args)
+    } finally {
+      this.setContext(oldContext)
+    }
+  }
+}
+
+module.exports = LegacyContextManager