newrelic 8.5.2 → 8.6.0

package/lib/instrumentation/promise.js

@@ -11,28 +11,22 @@ const shimmer = require('../shimmer')
 
 /**
  * @namespace Library.Spec
- *
  * @property {string} name
  *  The name of this promise library.
- *
  * @property {?string} constructor
  *  Optional. The name of the property that is the Promise constructor. Default
  *  is to use the library itself as the Promise constructor.
- *
  * @property {?bool} executor
  *  Optional. If true, the Promise constructor itself will be wrapped for the
  *  executor. If false then `_proto`, `_static`, or `_library` must have an
  *  `executor` field whose value is the name of the executor function. Default
  *  is false.
- *
  * @property {Library.Spec.Mapping} $proto
  *  The mapping for Promise instance method concepts (i.e. `then`). These are
  *  mapped on the Promise class' prototype.
- *
  * @property {Library.Spec.Mapping} $static
  *  The mapping for Promise static method concepts (i.e. `all`, `race`). These
  *  are mapped on the Promise class itself.
- *
  * @property {?Library.Spec.Mapping} $library
  *  The mapping for library-level static method concepts (i.e. `fcall`, `when`).
  *  These are mapped on the library containing the Promise class. NOTE: in most
@@ -42,35 +36,23 @@ const shimmer = require('../shimmer')
 
 /**
  * @namespace Library.Spec.Mapping
- *
- * @desc
+ * @description
  *   A mapping of promise concepts (i.e. `then`) to this library's implementation
  *   name(s) (i.e. `["then", "chain"]`). Each value can by either a single string
  *   or an array of strings if the concept exists under multiple keys. If any
  *   given concept doesn't exist in this library, it is simply skipped.
- *
- * @property {array} $copy
+ * @property {Array} $copy
  *  An array of properties or methods to just directly copy without wrapping.
  *  This field only matters when `Library.Spec.executor` is `true`.
- *
- * @property {string|array} executor
- *
- *
- * @property {string|array} then
- *
- *
- * @property {string|array} all
- *
- *
- * @property {string|array} race
- *
- *
- * @property {string|array} resolve
+ * @property {string | Array} executor
+ * @property {string | Array} then
+ * @property {string | Array} all
+ * @property {string | Array} race
+ * @property {string | Array} resolve
  *  Indicates methods to wrap which are resolve factories. This method only
  *  requires wrapping if the library doesn't use an executor internally to
  *  implement it.
- *
- * @property {string|array} reject
+ * @property {string | Array} reject
  *  Indicates methods to wrap which are reject factories. Like `resolve`, this
  *  method only requires wrapping if the library doesn't use an executor
  *  internally to implement it.
@@ -80,11 +62,13 @@ const shimmer = require('../shimmer')
  * Instruments a promise library.
  *
  * @param {Agent}         agent   - The New Relic APM agent.
- * @param {function}      library - The promise library.
+ * @param {Function}      library - The promise library.
  * @param {?Library.Spec} spec    - Spec for this promise library mapping.
  */
 /* eslint-disable camelcase */
 module.exports = function initialize(agent, library, spec) {
+  const contextManager = agent._contextManager
+
   if (spec.useFinally == null) {
     spec.useFinally = true
   }
@@ -144,7 +128,7 @@ module.exports = function initialize(agent, library, spec) {
       return Promise(executor) // eslint-disable-line new-cap
     }
 
-    const parent = agent.tracer.segment
+    const parent = contextManager.getContext()
     let promise = null
     if (
       !parent ||
@@ -170,15 +154,13 @@ module.exports = function initialize(agent, library, spec) {
       const segment = _createSegment(segmentName)
       Contextualizer.link(null, promise, segment, spec.useFinally)
 
-      agent.tracer.segment = segment
       segment.start()
       try {
         // Must run after promise is defined so that `__NR_wrapper` can be set.
-        executor.apply(context.self, context.args)
+        contextManager.runInContext(segment, executor, context.self, context.args)
       } catch (e) {
         context.args[1](e)
       } finally {
-        agent.tracer.segment = parent
         segment.touch()
       }
     }
@@ -259,8 +241,7 @@ module.exports = function initialize(agent, library, spec) {
    * execution.
    *
    * @param {object} context - The object to export the execution context with.
-   *
-   * @return {function} A function which, when executed, will add its context
+   * @returns {Function} A function which, when executed, will add its context
    *  and arguments to the `context` parameter.
    */
   function wrapExecutorContext(context) {
@@ -285,7 +266,9 @@ module.exports = function initialize(agent, library, spec) {
   /**
    * Creates a wrapper for `Promise#then` that extends the transaction context.
    *
-   * @return {function} A wrapped version of `Promise#then`.
+   * @param then
+   * @param name
+   * @returns {Function} A wrapped version of `Promise#then`.
    */
   function wrapThen(then, name) {
     return _wrapThen(then, name, true)
@@ -294,7 +277,9 @@ module.exports = function initialize(agent, library, spec) {
   /**
    * Creates a wrapper for `Promise#catch` that extends the transaction context.
    *
-   * @return {function} A wrapped version of `Promise#catch`.
+   * @param cach
+   * @param name
+   * @returns {Function} A wrapped version of `Promise#catch`.
    */
   function wrapCatch(cach, name) {
     return _wrapThen(cach, name, false)
@@ -303,14 +288,13 @@ module.exports = function initialize(agent, library, spec) {
   /**
    * Creates a wrapper for promise chain extending methods.
    *
-   * @param {function} then
+   * @param {Function} then
    *  The function we are to wrap as a chain extender.
-   *
+   * @param name
    * @param {bool} useAllParams
    *  When true, all parameters which are functions will be wrapped. Otherwise,
    *  only the last parameter will be wrapped.
-   *
-   * @return {function} A wrapped version of the function.
+   * @returns {Function} A wrapped version of the function.
    */
   function _wrapThen(then, name, useAllParams) {
     // Don't wrap non-functions.
@@ -377,6 +361,9 @@ module.exports = function initialize(agent, library, spec) {
 
   /**
    * Creates a wrapper around the static `Promise` factory method.
+   *
+   * @param cast
+   * @param name
    */
   function wrapCast(cast, name) {
     if (typeof cast !== 'function' || cast.name === '__NR_wrappedCast') {
@@ -437,8 +424,8 @@ module.exports = function initialize(agent, library, spec) {
  *
  * @param {object}        obj     - The source of the methods to wrap.
  * @param {string}        name    - The name of this source.
- * @param {string|array}  methods - The names of the methods to wrap.
- * @param {function}      wrapper - The function which wraps the methods.
+ * @param {string | Array}  methods - The names of the methods to wrap.
+ * @param {Function}      wrapper - The function which wraps the methods.
  */
 function _safeWrap(obj, name, methods, wrapper) {
   if (methods && methods.length) {

package/lib/shim/message-shim.js

@@ -62,20 +62,16 @@ const DESTINATION_TYPES = {
 /**
  * Constructs a shim specialized for instrumenting message brokers.
  *
- * @constructor
- * @extends TransactionShim
+ * @class
+ * @augments TransactionShim
  * @classdesc
  *  Used for instrumenting message broker client libraries.
- *
  * @param {Agent} agent
  *  The agent this shim will use.
- *
  * @param {string} moduleName
  *  The name of the module being instrumented.
- *
  * @param {string} resolvedName
  *  The full path to the loaded module.
- *
  * @see Shim
  * @see TransactionShim
  */
@@ -112,124 +108,93 @@ MessageShim.prototype.recordSubscribedConsume = recordSubscribedConsume
 
 /**
  * @callback MessageFunction
- *
  * @summary
  *  Used for determining information about a message either being produced or
  *  consumed.
- *
  * @param {MessageShim} shim
  *  The shim this function was handed to.
- *
  * @param {Function} func
  *  The produce method or message consumer.
- *
  * @param {string} name
  *  The name of the producer or consumer.
- *
  * @param {Array.<*>} args
  *  The arguments being passed into the produce method or consumer.
- *
- * @return {MessageSpec} The specification for the message being produced or
+ * @returns {MessageSpec} The specification for the message being produced or
  *  consumed.
- *
  * @see MessageShim#recordProduce
  * @see MessageShim#recordConsume
  */
 
 /**
  * @callback MessageHandlerFunction
- *
  * @summary
  *  A function that is used to extract properties from a consumed message. This
  *  method is handed the results of a consume call. If the consume used a
  *  callback, then this method will receive the arguments to the callback. If
  *  the consume used a promise, then this method will receive the resolved
  *  value.
- *
  * @param {MessageShim} shim
  *  The shim this function was handed to.
- *
  * @param {Function} func
  *  The produce method or message consumer.
- *
  * @param {string} name
  *  The name of the producer or consumer.
- *
  * @param {Array|*} args
  *  Either the arguments for the consumer callback function or the result of
  *  the resolved consume promise, depending on the mode of the instrumented
  *  method.
- *
- * @return {MessageSpec} The extracted properties of the consumed message.
- *
+ * @returns {MessageSpec} The extracted properties of the consumed message.
  * @see MessageShim#recordConsume
  */
 
 /**
  * @callback MessageConsumerWrapperFunction
- *
  * @summary
  *  Function that is used to wrap message consumer functions. Used along side
  *  the MessageShim#recordSubscribedConsume API method.
- *
  * @param {MessageShim} shim
  *  The shim this function was handed to.
- *
  * @param {Function} consumer
  *  The message consumer to wrap.
- *
  * @param {string} name
  *  The name of the consumer method.
- *
  * @param {string} queue
  *  The name of the queue this consumer is being subscribed to.
- *
- * @return {Function} The consumer method, possibly wrapped.
- *
+ * @returns {Function} The consumer method, possibly wrapped.
  * @see MessageShim#recordSubscribedConsume
  * @see MessageShim#recordConsume
  */
 
 /**
  * @interface MessageSpec
- * @extends RecorderSpec
- *
+ * @augments RecorderSpec
  * @description
  *  The specification for a message being produced or consumed.
- *
  * @property {string} destinationName
  *  The name of the exchange or queue the message is being produced to or
  *  consumed from.
- *
  * @property {MessageShim.DESTINATION_TYPES} [destinationType=null]
  *  The type of the destination. Defaults to `shim.EXCHANGE`.
- *
- * @property {Object} [headers=null]
+ * @property {object} [headers=null]
  *  A reference to the message headers. On produce, more headers will be added
  *  to this object which should be sent along with the message. On consume,
  *  cross-application headers will be read from this object.
- *
  * @property {string} [routingKey=null]
  *  The routing key for the message. If provided on consume, the routing key
  *  will be added to the transaction attributes as `message.routingKey`.
- *
  * @property {string} [queue=null]
  *  The name of the queue the message was consumed from. If provided on
  *  consume, the queue name will be added to the transaction attributes as
  *  `message.queueName`.
- *
  * @property {string} [parameters.correlation_id]
  *  In AMQP, this should be the correlation Id of the message, if it has one.
- *
  * @property {string} [parameters.reply_to]
  *  In AMQP, this should be the name of the queue to reply to, if the message
  *  has one.
- *
  * @property {MessageHandlerFunction} [messageHandler]
  *  An optional function to extract message properties from a consumed message.
  *  This method is only used in the consume case to pull data from the
  *  retrieved message.
- *
  * @see RecorderSpec
  * @see MessageShim#recordProduce
  * @see MessageShim#recordConsume
@@ -238,23 +203,19 @@ MessageShim.prototype.recordSubscribedConsume = recordSubscribedConsume
 
 /**
  * @interface MessageSubscribeSpec
- * @extends MessageSpec
- *
+ * @augments MessageSpec
  * @description
  *  Specification for message subscriber methods. That is, methods which
  *  register a consumer to start receiving messages.
- *
  * @property {number} consumer
  *  The index of the consumer in the method's arguments. Note that if the
  *  consumer and callback indexes point to the same argument, the argument will
  *  be wrapped as a consumer.
- *
  * @property {MessageHandlerFunction} messageHandler
  *  A function to extract message properties from a consumed message.
  *  This method is only used in the consume case to pull data from the
  *  retrieved message. Its return value is combined with the `MessageSubscribeSpec`
  *  to fully describe the consumed message.
- *
  * @see MessageSpec
  * @see MessageConsumerWrapperFunction
  * @see MessageShim#recordSubscribedConsume
@@ -269,11 +230,9 @@ MessageShim.prototype.recordSubscribedConsume = recordSubscribedConsume
  * passed, metric names will be generated using that.
  *
  * @memberof MessageShim.prototype
- *
  * @param {MessageShim.LIBRARY_NAMES|string} library
  *  The name of the message broker library. Use one of the well-known constants
  *  listed in {@link MessageShim.LIBRARY_NAMES} if available for the library.
- *
  * @see MessageShim.LIBRARY_NAMES
  */
 function setLibrary(library) {
@@ -305,20 +264,15 @@ function setLibrary(library) {
  * `PRODUCE` metric.
  *
  * @memberof MessageShim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the properties to wrap, or a single function to wrap.
- *
  * @param {string|Array.<string>} [properties]
  *  One or more properties to wrap. If omitted, the `nodule` parameter is
  *  assumed to be the function to wrap.
- *
  * @param {MessageFunction} recordNamer
  *  A function which specifies details of the message.
- *
- * @return {Object|Function} The first parameter to this function, after
+ * @returns {object | Function} The first parameter to this function, after
  *  wrapping it or its properties.
- *
  * @see Shim#wrap
  * @see Shim#record
  * @see MessageSpec
@@ -374,21 +328,16 @@ function recordProduce(nodule, properties, recordNamer) {
  * consumers see {@link MessageShim#recordSubscribedConsume}
  *
  * @memberof MessageShim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the properties to wrap, or a single function to wrap.
- *
  * @param {string|Array.<string>} [properties]
  *  One or more properties to wrap. If omitted, the `nodule` parameter is
  *  assumed to be the function to wrap.
- *
  * @param {MessageSpec|MessageFunction} spec
  *  The spec for the method or a function which returns the details of the
  *  method.
- *
- * @return {Object|Function} The first parameter to this function, after
+ * @returns {object | Function} The first parameter to this function, after
  *  wrapping it or its properties.
- *
  * @see Shim#wrap
  * @see Shim#record
  * @see MessageShim#recordSubscribedConsume
@@ -411,6 +360,10 @@ function recordConsume(nodule, properties, spec) {
     spec = this.setDefaults(spec, DEFAULT_SPEC)
   }
 
+  // This is using wrap instead of record because the spec allows for a messageHandler
+  // which is being used to handle the result of the callback or promise of the
+  // original wrapped consume function.
+  // TODO: https://github.com/newrelic/node-newrelic/issues/981
   return this.wrap(nodule, properties, function wrapConsume(shim, fn, fnName) {
     if (!shim.isFunction(fn)) {
       shim.logger.debug('Not wrapping %s (%s) as consume', fn, fnName)
@@ -487,15 +440,19 @@ function recordConsume(nodule, properties, spec) {
       // Call the method in the context of our segment.
       let ret = shim.applySegment(fn, segment, true, this, args)
 
-      // Intercept the promise to handle the result.
-      if (resHandler && ret && msgDesc.promise && shim.isPromise(ret)) {
-        ret = ret.then(function interceptValue(res) {
-          const msgProps = resHandler.call(this, shim, fn, fnName, res)
-          if (getParams && msgProps && msgProps.parameters) {
-            shim.copySegmentParameters(segment, msgProps.parameters)
-          }
-          return res
-        })
+      if (ret && msgDesc.promise && shim.isPromise(ret)) {
+        ret = shim.bindPromise(ret, segment)
+
+        // Intercept the promise to handle the result.
+        if (resHandler) {
+          ret = ret.then(function interceptValue(res) {
+            const msgProps = resHandler.call(this, shim, fn, fnName, res)
+            if (getParams && msgProps && msgProps.parameters) {
+              shim.copySegmentParameters(segment, msgProps.parameters)
+            }
+            return res
+          })
+        }
       }
 
       return ret
@@ -510,23 +467,17 @@ function recordConsume(nodule, properties, spec) {
  * - `recordPurgeQueue(func, spec)`
  *
  * @memberof MessageShim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the properties to wrap, or a single function to wrap.
- *
  * @param {string|Array.<string>} [properties]
  *  One or more properties to wrap. If omitted, the `nodule` parameter is
  *  assumed to be the function to wrap.
- *
  * @param {RecorderSpec} spec
  *  The specification for this queue purge method's interface.
- *
  * @param {string} spec.queue
  *  The name of the queue being purged.
- *
- * @return {Object|Function} The first parameter to this function, after
+ * @returns {object | Function} The first parameter to this function, after
  *  wrapping it or its properties.
- *
  * @see Shim#wrap
  * @see Shim#record
  * @see RecorderSpec
@@ -598,20 +549,15 @@ function recordPurgeQueue(nodule, properties, spec) {
  * `spec.wrapper` method even if no transaction is active.
  *
  * @memberof MessageShim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the properties to wrap, or a single function to wrap.
- *
  * @param {string|Array.<string>} [properties]
  *  One or more properties to wrap. If omitted, the `nodule` parameter is
  *  assumed to be the function to wrap.
- *
  * @param {MessageSubscribeSpec} spec
  *  The specification for this subscription method's interface.
- *
- * @return {Object|Function} The first parameter to this function, after
+ * @returns {object | Function} The first parameter to this function, after
  *  wrapping it or its properties.
- *
  * @see Shim#wrap
  * @see Shim#record
  * @see MessageShim#recordConsume
@@ -702,6 +648,10 @@ function recordSubscribedConsume(nodule, properties, spec) {
     }
   })
 
+  /**
+   * @param queue
+   * @param destinationName
+   */
   function makeWrapConsumer(queue, destinationName) {
     const msgDescDefaults = copy.shallow(spec)
     if (destNameIsArg && destinationName != null) {
@@ -810,6 +760,9 @@ function recordSubscribedConsume(nodule, properties, spec) {
 
           return ret
 
+          /**
+           *
+           */
           function endTransaction() {
             tx.finalizeName(null) // Use existing partial name.
             tx.end()
@@ -830,12 +783,10 @@ function recordSubscribedConsume(nodule, properties, spec) {
  * Constructs a message segment name from the given message descriptor.
  *
  * @private
- *
  * @param {MessageShim} shim    - The shim the segment will be constructed by.
  * @param {MessageSpec} msgDesc - The message descriptor.
  * @param {string}      action  - Produce or consume?
- *
- * @return {string} The generated name of the message segment.
+ * @returns {string} The generated name of the message segment.
  */
 function _nameMessageSegment(shim, msgDesc, action) {
   let name =
@@ -855,6 +806,10 @@ function _nameMessageSegment(shim, msgDesc, action) {
   return name
 }
 
+/**
+ * @param shim
+ * @param msgDesc
+ */
 function _nameMessageTransaction(shim, msgDesc) {
   let name = shim._metrics.LIBRARY + '/' + (msgDesc.destinationType || shim.EXCHANGE) + '/'