newrelic 8.4.0 → 8.6.0

package/lib/instrumentation/fastify/spec-builders.js

@@ -1,19 +1,43 @@
 /*
- * Copyright 2020 New Relic Corporation. All rights reserved.
+ * Copyright 2021 New Relic Corporation. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
 'use strict'
 
-const getRawRequestFromFastifyRequest = (shim, fn, fnName, args) => {
-  const request = args[0]
+/**
+ * Retrieves the IncomingMessage from a Fastify request.  Depending on the
+ * context of this function it either exists on `request.raw` or just `request`
+ *
+ * @param {WebFrameworkShim} shim
+ * @param {Function} fn middleware function executing
+ * @param {string} fnName name of middleware executing
+ * @param {args} args that are passed to middleware
+ * @returns {IncomingMessage}
+ */
+const getRequestFromFastify = (shim, fn, fnName, args) => {
+  const [request] = args
+
+  // request is Fastify request
+  // object, get IncomingMessage from .raw
   if (request && request.raw) {
     return request.raw
   }
+
+  return request
 }
 
+/**
+ * Retrieves the params from the Fastify request.
+ *
+ * @param {WebFrameworkShim} shim
+ * @param {Function} fn middleware function executing
+ * @param {string} fnName name of middleware executing
+ * @param {args} args that are passed to middleware
+ * @returns {object} URL params on a Fastify request
+ */
 const getParamsFromFastifyRequest = (shim, fn, fnName, args) => {
-  const req = args[0]
+  const [req] = args
   return req && req.params
 }
 
@@ -21,32 +45,17 @@ const getParamsFromFastifyRequest = (shim, fn, fnName, args) => {
  * Builds the recordMiddleware Spec for the route handler
  *
  * A spec is basically a specification -- or a list
- * of insrtuctions to the recordMiddleware function
+ * of instructions to the recordMiddleware function
  * that provide it with the information it needs to
  * do its job.  You could also think of it as a
  * mini-DSL
+ *
+ * @param {WebFrameworkShim} shim
+ * @param {string} path URL route being executed
+ * @returns {object} spec for Fastify route handler
  */
 function buildMiddlewareSpecForRouteHandler(shim, path) {
   return {
-    /**
-     * The path to use for transaction naming
-     */
-    route: path,
-
-    /**
-     * A function the returns the NodeJS Request Object
-     *
-     * The job of the `req` callback is to return the current NodeJS
-     * IncomingMessage object for this particular handler.  Most NodeJS
-     * frameworks will pass the request to each handler -- sometimes (as
-     * is the case here) wrapped by another object.
-     *
-     * @param {any} shim the Webframework Shim
-     * @param {any} fn the handler function passed to buildMiddlewareSpec
-     * @param {any} fnName the handler function's name
-     * @param {any} args the arguments passed to the handler function
-     */
-    req: getRawRequestFromFastifyRequest,
     /**
      * A function where we can wrap next, reply send, etc. methods
      *
@@ -66,6 +75,12 @@ function buildMiddlewareSpecForRouteHandler(shim, path) {
      * The isFinal param determines whether or not a path is appended for
      * this particular piece of middleware. (i.e. if this is the final handler
      * that is actually handling the request, the path is actually left on)
+     *
+     * @param shim
+     * @param fn
+     * @param fnName
+     * @param args
+     * @param bindSegment
      */
     next: function wrapNext(shim, fn, fnName, args, bindSegment) {
       const reply = args[1]
@@ -75,33 +90,28 @@ function buildMiddlewareSpecForRouteHandler(shim, path) {
       const isFinal = true
       bindSegment(reply, 'send', isFinal)
     },
-
-    /**
-     * A function that returns the request paramates
-     *
-     * @param {any} shim the Webframework Shim
-     * @param {any} fn the handler function passed to buildMiddlewareSpec
-     * @param {any} fnName the handler function's name
-     * @param {any} args the arguments passed to the handler function
-     */
-    params: getParamsFromFastifyRequest
+    params: getParamsFromFastifyRequest,
+    req: getRequestFromFastify,
+    route: path
   }
 }
 
-function buildMiddlewareSpecForMiddlewareFunction() {
+/**
+ * Spec for all Fastify middleware(excluding route handlers)
+ *
+ * @param {WebFrameworkShim} shim
+ * @param {string} name metric name for middleware being executed
+ * @param route
+ * @returns {object} spec for Fastify middleware
+ */
+function buildMiddlewareSpecForMiddlewareFunction(shim, name, route) {
   return {
-    req: getRawRequestFromFastifyRequest,
-
-    next: function wrapNext(shim, fn, fnName, args, bindSegment) {
-      const next = args[2]
-      if (!shim.isFunction(next)) {
-        return
-      }
-      const isFinal = false
-      bindSegment(next, null, isFinal)
-    },
-
-    params: getParamsFromFastifyRequest
+    name,
+    route,
+    next: shim.LAST,
+    params: getParamsFromFastifyRequest,
+    req: getRequestFromFastify,
+    type: shim.MIDDLEWARE
   }
 }
 

package/lib/instrumentation/fastify.js

@@ -4,11 +4,33 @@
  */
 
 'use strict'
+
 const semver = require('semver')
 const {
   buildMiddlewareSpecForRouteHandler,
   buildMiddlewareSpecForMiddlewareFunction
 } = require('./fastify/spec-builders')
+
+/**
+ * These are the events that occur during a fastify
+ * request
+ * see: https://www.fastify.io/docs/latest/Lifecycle/
+ *
+ * Note: preSerialization and onSend happen after the route handler
+ * executes.  `onResponse` does not execute until after the client
+ * sends the response so it'll never be in scope of the transaction
+ */
+const REQUEST_HOOKS = [
+  'onRequest',
+  'preParsing',
+  'preValidation',
+  'preHandler',
+  'preSerialization',
+  'onSend',
+  'onResponse',
+  'onError'
+]
+
 /**
  * Sets up fastify route handler
  *
@@ -20,6 +42,9 @@ const {
  * those private implementations from access, and getting
  * at them would require a lot of gymnastics and hard to
  * maintain code
+ *
+ * @param shim
+ * @param fastify
  */
 const setupRouteHandler = (shim, fastify) => {
   fastify.addHook('onRoute', (routeOptions) => {
@@ -27,10 +52,10 @@ const setupRouteHandler = (shim, fastify) => {
       return
     }
     /**
-     * recordMiddlware handler call
+     * recordMiddleware handler call
      *
      * The WebFramework shim treats the main route handler like any other
-     * i.e. dont be confused by the call to recordMiddlware -- we don't
+     * i.e. dont be confused by the call to recordMiddleware -- we don't
      * have a recordRouteHandler, everything goes through recordMiddleware
      */
     const newRouteHandler = shim.recordMiddleware(
@@ -40,29 +65,25 @@ const setupRouteHandler = (shim, fastify) => {
 
     routeOptions.handler = newRouteHandler
   })
-}
 
-const setupMiddlewareHandlers = (shim, fastify) => {
-  shim.wrap(fastify, 'use', function wrapFastifyUse(shim, fn) {
-    return function wrappedFastifyUser() {
+  shim.wrap(fastify, 'addHook', function addWrapHook(shim, fn) {
+    return function wrappedAddHook() {
       const args = shim.argsToArray.apply(shim, arguments)
-      const middlewareFunction = args[0]
-      const newMiddlewareFunction = shim.recordMiddleware(
-        middlewareFunction,
-        buildMiddlewareSpecForMiddlewareFunction(shim)
-      )
-      // replace original function with our function
-      args[0] = newMiddlewareFunction
+      const hookName = args[0]
+      if (REQUEST_HOOKS.includes(hookName)) {
+        const middlewareFunction = args[1]
+        const name = `${hookName}/${shim.getName(middlewareFunction)}`
+        const middlewareSpec = buildMiddlewareSpecForMiddlewareFunction(shim, name)
+        const newMiddlewareFunction = shim.recordMiddleware(middlewareFunction, middlewareSpec)
 
+        args[1] = newMiddlewareFunction
+      }
       return fn.apply(this, args)
     }
   })
 }
 
 module.exports = function initialize(agent, fastify, moduleName, shim) {
-  if (!agent.config.feature_flag.fastify_instrumentation) {
-    return
-  }
   shim.setFramework(shim.FASTIFY)
 
   const fastifyVersion = shim.require('./package.json').version
@@ -73,18 +94,12 @@ module.exports = function initialize(agent, fastify, moduleName, shim) {
    */
   const wrappedExport = shim.wrapExport(fastify, function wrapFastifyModule(shim, fn) {
     return function wrappedFastifyModule() {
-      // normalize arguments
-      const args = shim.argsToArray.apply(shim, arguments)
-
       // call original function get get fastify object (which is singleton-ish)
-      const fastifyForWrapping = fn.apply(this, args)
+      const fastifyForWrapping = fn.apply(this, arguments)
 
       setupRouteHandler(shim, fastifyForWrapping)
 
-      // Don't wrap use() in fastify v3+
-      if (!isv3Plus) {
-        setupMiddlewareHandlers(shim, fastifyForWrapping)
-      }
+      setupMiddlewareHandlers(shim, fastifyForWrapping, isv3Plus)
 
       return fastifyForWrapping
     }
@@ -95,10 +110,56 @@ module.exports = function initialize(agent, fastify, moduleName, shim) {
   }
 }
 
+function setupMiddlewareHandlers(shim, fastify, isv3Plus) {
+  const mounterSpec = {
+    route: shim.FIRST,
+    wrapper: wrapMiddleware
+  }
+
+  if (isv3Plus) {
+    // Fastify v3+ does not ship with traditional Node.js middleware mounting.
+    // This style is accomplished leveraging decorators. Both middie (which was built-in in v2)
+    // and fastify-express mount a 'use' function for mounting middleware.
+    shim.wrap(fastify, 'decorate', function wrapDecorate(shim, fn) {
+      return function wrappedDecorate() {
+        const name = arguments[0]
+        if (name !== 'use') {
+          return fn.apply(this, arguments)
+        }
+
+        const args = shim.argsToArray.apply(shim, arguments)
+        args[1] = shim.wrapMiddlewareMounter(args[1], mounterSpec)
+
+        return fn.apply(this, args)
+      }
+    })
+  } else {
+    shim.wrapMiddlewareMounter(fastify, 'use', mounterSpec)
+  }
+}
+
+function wrapMiddleware(shim, middleware, name, route) {
+  if (shim.isWrapped(middleware)) {
+    return middleware
+  }
+
+  // prefixing the segment name for middleware execution
+  // with the Fastify lifecycle hook
+  const segmentName = `onRequest/${name}`
+  const spec = buildMiddlewareSpecForMiddlewareFunction(shim, segmentName, route)
+
+  const newMiddlewareFunction = shim.recordMiddleware(middleware, spec)
+
+  return newMiddlewareFunction
+}
+
 /**
  * module.exports = fastify
  * module.exports.fastify = fastify
  * module.exports.default = fastify
+ *
+ * @param original
+ * @param wrappedExport
  */
 function setupExports(original, wrappedExport) {
   wrappedExport.fastify = original.fastify

package/lib/instrumentation/mongodb/common.js

@@ -47,9 +47,11 @@ common.instrumentCollection = function instrumentCollection(shim, Collection) {
  * Instruments all methods from constants.DB_OPS on
  * the Db class.
  *
- * @param {Object} params
+ * @param {object} params
  * @param {Shim} params.shim
  * @param {Db} params.Db
+ * @param shim
+ * @param Db
  */
 common.instrumentDb = function instrumentDb(shim, Db) {
   if (Db && Db.prototype) {
@@ -62,6 +64,7 @@ common.instrumentDb = function instrumentDb(shim, Db) {
 
 /**
  * Sets up the desc for all instrumented query methods
+ *
  * @param {Shim} shim
  * @param {string} methodName
  */
@@ -123,7 +126,7 @@ common.captureAttributesOnStarted = function captureAttributesOnStarted(shim, in
  * @param {Shim} shim
  * @param {string} connStr
  * @param {string} db database name
- * @param {Object} client mongo client instance
+ * @param {object} client mongo client instance
  */
 function setHostPort(shim, connStr, db, client) {
   const parts = connStr.split(':')
@@ -153,6 +156,9 @@ function setHostPort(shim, connStr, db, client) {
  * for the query segment. v4 refactored where the toplogy is stored.
  * You can now get the details via the client obj that's deeply nested
  * See: https://github.com/mongodb/node-mongodb-native/pull/2594/files#diff-1d214e57ddda9095d296e5700ebce701333bfefcf417e234c584d14091b2f50dR168
+ *
+ * @param shim
+ * @param obj
  */
 function getInstanceAttributeParameters(shim, obj) {
   if (obj.s && obj.s.db && obj.s.topology) {
@@ -197,8 +203,10 @@ function getInstanceAttributeParameters(shim, obj) {
   }
 
   function doCapture(conf, database) {
-    let host = null
-    let port = null
+    // in older versions of 3.x the host/port
+    // lived directly on the topology.s.options
+    let host = conf.host
+    let port = conf.port
 
     // servers is an array but we will always pull the first for consistency
     if (conf.servers && conf.servers.length) {

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) {