newrelic 8.4.0 → 8.5.0

package/NEWS.md

@@ -1,37 +1,53 @@
-### v8.4.0 (2021-09-28)
-
+### v8.5.0 (2021-10-12)
+
+* Added full support for Fastify v2 and v3. Fastify instrumentation is now GA.
+  * Removed fastify feature flag.
+  * Instrumented Fastify routes by wrapping `addHook`.
+  * Added middleware mounting for fastify v3.
+  * Fixed capturing of mount point for middleware naming.
+  * Fixed the WebFramework spec definitions for Fastify middleware and route handlers to properly retrieve the IncomingMessage from a request object.
+  * Added proper definition to middleware handlers so that the relationship to consecutive middleware and route handler are siblings and not direct children.
+
+* Added experimental instrumentation for the [undici](https://github.com/nodejs/undici) http client behind a feature flag.
+
+  To enable undici support, add the following into your config: `{ feature_flag: { undici_instrumentation: true } }`.  The support for undici client is Node.js 16.x as it takes advantage of the [diagnostics_channel](https://nodejs.org/dist/latest-v16.x/docs/api/diagnostics_channel.html). Lastly, you must be using [v4.7.0+](https://github.com/nodejs/undici/releases/tag/v4.7.0) of the undici client for any of the instrumentation to work.
+
+  Note: There are currently some state issues if requests to an app are made with keep alive and you have multiple undici requests being made in parallel. In this case, set feature_flag: `{ undici_async_tracking: false }` which avoids these state issues at the cost of some broken segment nesting.
+
+### v8.4.0 (2021-09-28)
+
 * **Deprecation Warning**: Cross Application Tracing (CAT) has been deprecated and will be removed in a future major release. For applications that explicitly disable Distributed Tracing (DT) to leverage CAT, we recommend migrating to DT to avoid loss of cross-service visibility.
   * Disables CAT by default. You must explicitly enable CAT along with turning off DT.
-  * Adds a deprecation warning when CAT is enabled and active (DT disabled).
-
+  * Adds a deprecation warning when CAT is enabled and active (DT disabled).
+
 * Fixed issue with `clearTimeout` that could result in dropping parent segments or spans.
 
-  This bug resulted in some MongoDB calls being dropped from Transaction Traces and Distributed Traces (spans): https://github.com/newrelic/node-newrelic/issues/922.
-
-* Removed warnings from agent tests for `no-var` eslint rule.
-
-* Added support for Cassandra driver v4.0.0 and above.
-
-* Fixed issue where DT headers would not be processed by `transaction-shim.handleCATHeaders()` when CAT was explicitly disabled. This primarily impacts `amqplib` instrumentation.
-
-* Transitioned aws-lambda.test.js to use Tap over Mocha.
-
-* Removed warnings from agent for `no-var` eslint rule.
-
-* Refactored `transaction-shim`, `http` and `http-outbound` to use centralized CAT methods in `util/cat`
-
-* Replaced http-outbound test call to use example.com to avoid unpredictable connection resets.
-
-* Migrated sql query parser tests to tap
-
+  This bug resulted in some MongoDB calls being dropped from Transaction Traces and Distributed Traces (spans): https://github.com/newrelic/node-newrelic/issues/922.
+
+* Removed warnings from agent tests for `no-var` eslint rule.
+
+* Added support for Cassandra driver v4.0.0 and above.
+
+* Fixed issue where DT headers would not be processed by `transaction-shim.handleCATHeaders()` when CAT was explicitly disabled. This primarily impacts `amqplib` instrumentation.
+
+* Transitioned aws-lambda.test.js to use Tap over Mocha.
+
+* Removed warnings from agent for `no-var` eslint rule.
+
+* Refactored `transaction-shim`, `http` and `http-outbound` to use centralized CAT methods in `util/cat`
+
+* Replaced http-outbound test call to use example.com to avoid unpredictable connection resets.
+
+* Migrated sql query parser tests to tap
+
 * Added more API usage examples.
-
-* Added a README to the `examples/` folder discussing how to use the examples.
-
-* Fixed `message-shim` test assertion to avoid flakiness based on precision differences(ms vs ns)
-
-* Applied new lint rules barring the use of `var` and preferring the use of `const` wherever possible.
-
+
+* Added a README to the `examples/` folder discussing how to use the examples.
+
+* Fixed `message-shim` test assertion to avoid flakiness based on precision differences(ms vs ns)
+
+* Applied new lint rules barring the use of `var` and preferring the use of `const` wherever possible.
+
 ### v8.3.0 (2021-09-09)
 
 * Enabled Distributed Tracing (DT) by default.

package/THIRD_PARTY_NOTICES.md

@@ -41,7 +41,9 @@ code, the source code can be found at [https://github.com/newrelic/node-newrelic
 * [chai](#chai)
 * [commander](#commander)
 * [eslint-config-prettier](#eslint-config-prettier)
+* [eslint-plugin-disable](#eslint-plugin-disable)
 * [eslint-plugin-header](#eslint-plugin-header)
+* [eslint-plugin-jsdoc](#eslint-plugin-jsdoc)
 * [eslint-plugin-node](#eslint-plugin-node)
 * [eslint-plugin-prettier](#eslint-plugin-prettier)
 * [eslint](#eslint)
@@ -49,7 +51,6 @@ code, the source code can be found at [https://github.com/newrelic/node-newrelic
 * [generic-pool](#generic-pool)
 * [glob](#glob)
 * [got](#got)
-* [http-errors](#http-errors)
 * [husky](#husky)
 * [jsdoc](#jsdoc)
 * [lint-staged](#lint-staged)
@@ -2210,6 +2211,33 @@ THE SOFTWARE.
 
 ```
 
+### eslint-plugin-disable
+
+This product includes source derived from [eslint-plugin-disable](https://github.com/mradionov/eslint-plugin-disable) ([v2.0.1](https://github.com/mradionov/eslint-plugin-disable/tree/v2.0.1)), distributed under the [MIT License](https://github.com/mradionov/eslint-plugin-disable/blob/v2.0.1/LICENSE):
+
+```
+Copyright (c) 2015 Michael Radionov (https://github.com/mradionov)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+```
+
 ### eslint-plugin-header
 
 This product includes source derived from [eslint-plugin-header](https://github.com/Stuk/eslint-plugin-header) ([v3.1.1](https://github.com/Stuk/eslint-plugin-header/tree/v3.1.1)), distributed under the [MIT License](https://github.com/Stuk/eslint-plugin-header/blob/v3.1.1/README.md):
@@ -2226,6 +2254,38 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+### eslint-plugin-jsdoc
+
+This product includes source derived from [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc) ([v36.1.0](https://github.com/gajus/eslint-plugin-jsdoc/tree/v36.1.0)), distributed under the [BSD-3-Clause License](https://github.com/gajus/eslint-plugin-jsdoc/blob/v36.1.0/LICENSE):
+
+```
+Copyright (c) 2018, Gajus Kuizinas (http://gajus.com/)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Gajus Kuizinas (http://gajus.com/) nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL ANUARY BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+```
+
 ### eslint-plugin-node
 
 This product includes source derived from [eslint-plugin-node](https://github.com/mysticatea/eslint-plugin-node) ([v11.1.0](https://github.com/mysticatea/eslint-plugin-node/tree/v11.1.0)), distributed under the [MIT License](https://github.com/mysticatea/eslint-plugin-node/blob/v11.1.0/LICENSE):
@@ -2409,37 +2469,6 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 ```
 
-### http-errors
-
-This product includes source derived from [http-errors](https://github.com/jshttp/http-errors) ([v1.8.0](https://github.com/jshttp/http-errors/tree/v1.8.0)), distributed under the [MIT License](https://github.com/jshttp/http-errors/blob/v1.8.0/LICENSE):
-
-```
-
-The MIT License (MIT)
-
-Copyright (c) 2014 Jonathan Ong me@jongleberry.com
-Copyright (c) 2016 Douglas Christopher Wilson doug@somethingdoug.com
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
-```
-
 ### husky
 
 This product includes source derived from [husky](https://github.com/typicode/husky) ([v6.0.0](https://github.com/typicode/husky/tree/v6.0.0)), distributed under the [MIT License](https://github.com/typicode/husky/blob/v6.0.0/LICENSE):

package/lib/feature_flags.js

@@ -7,13 +7,14 @@
 
 // unreleased flags gating an active feature
 exports.prerelease = {
-  express5: false,
   await_support: true,
-  promise_segments: false,
-  reverse_naming_rules: false,
-  fastify_instrumentation: false,
   certificate_bundle: false,
+  express5: false,
   new_promise_tracking: false,
+  promise_segments: false,
+  reverse_naming_rules: false,
+  undici_instrumentation: false,
+  undici_async_tracking: true,
   unresolved_promise_cleanup: true
 }
 
@@ -29,7 +30,8 @@ exports.released = [
   'serverless_mode',
   'send_request_uri_attribute',
   'synthetics',
-  'dt_format_w3c'
+  'dt_format_w3c',
+  'fastify_instrumentation'
 ]
 
 // flags that are no longer used for unreleased features

package/lib/instrumentation/core/http-outbound.js

@@ -96,7 +96,7 @@ module.exports = function instrumentOutbound(agent, opts, makeRequest) {
     } else if (agent.config.cross_application_tracer.enabled) {
       cat.addCatHeaders(agent.config, transaction, outboundHeaders)
     } else {
-      logger.trace('CAT disabled, not adding headers!')
+      logger.trace('Both DT and CAT are disabled, not adding headers!')
     }
 
     if (Array.isArray(opts.headers)) {

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/undici.js

@@ -0,0 +1,242 @@
+/*
+ * Copyright 2021 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const cat = require('../util/cat')
+const recordExternal = require('../metrics/recorders/http_external')
+const logger = require('../logger').child({ component: 'undici' })
+const NAMES = require('../metrics/names')
+const NEWRELIC_SYNTHETICS_HEADER = 'x-newrelic-synthetics'
+const SYMBOLS = {
+  SEGMENT: Symbol('__NR_segment'),
+  PARENT_SEGMENT: Symbol('__NR_parent_segment')
+}
+const { executionAsyncResource } = require('async_hooks')
+
+let diagnosticsChannel = null
+try {
+  diagnosticsChannel = require('diagnostics_channel')
+} catch (e) {
+  // quick check to see if module exists
+  // module was not added until v15.x
+}
+
+module.exports = function addUndiciChannels(agent, undici, modName, shim) {
+  if (!diagnosticsChannel || !agent.config.feature_flag.undici_instrumentation) {
+    logger.warn(
+      'diagnostics_channel or feature_flag.undici_instrumentation = false. Skipping undici instrumentation.'
+    )
+    return
+  }
+
+  /**
+   * Retrieves the current segment in transaction(parent in our context) from executionAsyncResource
+   * or from `shim.getSegment()` then adds to the executionAsyncResource for future
+   * undici requests within same async context.
+   *
+   * It was found that when running concurrent undici requests
+   * within a transaction that the parent segment would get out of sync
+   * depending on the async context of the transaction.  By using
+   * `async_hooks.executionResource` it is more reliable.
+   *
+   * Note: However, if you have concurrent undici requests in a transaction
+   * and the request to the transaction is using a keep alive there is a chance the
+   * executionAsyncResource may be incorrect because of shared connections.  To revert to a more
+   * naive tracking of parent set `config.feature_flag.undici_async_tracking: false` and
+   * it will just call `shim.getSegment()`
+   */
+  function getParentSegment() {
+    if (agent.config.feature_flag.undici_async_tracking) {
+      const resource = executionAsyncResource()
+
+      if (!resource[SYMBOLS.PARENT_SEGMENT]) {
+        const parent = shim.getSegment()
+        resource[SYMBOLS.PARENT_SEGMENT] = parent
+      }
+      return resource[SYMBOLS.PARENT_SEGMENT]
+    }
+    return shim.getSegment()
+  }
+
+  /**
+   * This event occurs after the Undici Request is created
+   * We will check current segment for opaque and also attach
+   * relevant headers to outgoing http request
+   *
+   * @param {object} params
+   * @param {object} params.request undici request object
+   */
+  diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
+    const parent = getParentSegment()
+    request[SYMBOLS.PARENT_SEGMENT] = parent
+    if (!parent || (parent && parent.opaque)) {
+      logger.trace(
+        'Not capturing data for outbound request (%s) because parent segment opaque (%s)',
+        request.path,
+        parent && parent.name
+      )
+
+      return
+    }
+
+    const transaction = parent.transaction
+    const outboundHeaders = Object.create(null)
+    if (agent.config.encoding_key && transaction.syntheticsHeader) {
+      outboundHeaders[NEWRELIC_SYNTHETICS_HEADER] = transaction.syntheticsHeader
+    }
+
+    if (agent.config.distributed_tracing.enabled) {
+      transaction.insertDistributedTraceHeaders(outboundHeaders)
+    } else if (agent.config.cross_application_tracer.enabled) {
+      cat.addCatHeaders(agent.config, transaction, outboundHeaders)
+    } else {
+      logger.trace('Both DT and CAT are disabled, not adding headers!')
+    }
+
+    // eslint-disable-next-line guard-for-in
+    for (const key in outboundHeaders) {
+      request.addHeader(key, outboundHeaders[key])
+    }
+  })
+
+  /**
+   * This event occurs right before the data is written to the socket.
+   * Undici has some abstracted headers that are only created at this time, one
+   * is the `host` header which we need to name the Undici segment. So in this
+   * handler we create, start and set the segment active, name it, and
+   * attach the url/procedure/request.parameters
+   *
+   * @param {object} params
+   * @param {object} params.request undicie request object
+   * @param {TLSSocket | net.Socket} socket active socket connection
+   */
+  diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, socket }) => {
+    const parentSegment = request[SYMBOLS.PARENT_SEGMENT]
+    if (!parentSegment || (parentSegment && parentSegment.opaque)) {
+      return
+    }
+
+    const port = socket.remotePort
+    const isHttps = socket.servername
+    let urlString
+    if (isHttps) {
+      urlString = `https://${socket.servername}`
+      urlString += port === 443 ? request.path : `:${port}${request.path}`
+    } else {
+      urlString = `http://${socket._host}`
+      urlString += port === 80 ? request.path : `:${port}${request.path}`
+    }
+
+    const url = new URL(urlString)
+
+    const name = NAMES.EXTERNAL.PREFIX + url.host + url.pathname
+    const segment = shim.createSegment(name, recordExternal(url.host, 'undici'), parentSegment)
+    if (segment) {
+      segment.start()
+      shim.setActiveSegment(segment)
+      segment.addAttribute('url', `${url.protocol}//${url.host}${url.pathname}`)
+
+      url.searchParams.forEach((value, key) => {
+        segment.addSpanAttribute(`request.parameters.${key}`, value)
+      })
+      segment.addAttribute('procedure', request.method || 'GET')
+      request[SYMBOLS.SEGMENT] = segment
+    }
+  })
+
+  /**
+   * This event occurs after the response headers have been received.
+   * We will add the relevant http response attributes to active segment.
+   * Also add CAT specific keys to active segment.
+   *
+   * @param {object} params
+   * @param {object} params.request undici request object
+   * @param {object} params.response { statusCode, headers, statusText }
+   */
+  diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {
+    const activeSegment = request[SYMBOLS.SEGMENT]
+    if (!activeSegment) {
+      return
+    }
+
+    activeSegment.addSpanAttribute('http.statusCode', response.statusCode)
+    activeSegment.addSpanAttribute('http.statusText', response.statusText)
+
+    if (
+      agent.config.cross_application_tracer.enabled &&
+      !agent.config.distributed_tracing.enabled
+    ) {
+      try {
+        const { appData } = cat.extractCatHeaders(response.headers)
+        const decodedAppData = cat.parseAppData(agent.config, appData)
+        const attrs = activeSegment.getAttributes()
+        const url = new URL(attrs.url)
+        cat.assignCatToSegment(decodedAppData, activeSegment, url.host)
+      } catch (err) {
+        logger.warn(err, 'Cannot add CAT data to segment')
+      }
+    }
+  })
+
+  /**
+   * This event occurs after the response body has been received.
+   * We will end the active segment and set the active back to parent before request
+   *
+   * @param {object} params.request undici request object
+   */
+  diagnosticsChannel.channel('undici:request:trailers').subscribe(({ request }) => {
+    endAndRestoreSegment(request)
+  })
+
+  /**
+   * This event occurs right before the request emits an error.
+   * We will end the active segment and set the active back to parent before request.
+   * We will also log errors to NR
+   *
+   * Note: This event occurs before the error handler so we will always log it for now.
+   */
+  diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {
+    endAndRestoreSegment(request, error)
+  })
+
+  /**
+   * Gets the active and parent from given ctx(request, client connector)
+   * and ends active and restores parent to active.  If an error exists
+   * it will add the error to the transaction
+   *
+   * @param {object} ctx request or client connector
+   * @param {Error} error
+   */
+  function endAndRestoreSegment(ctx, error) {
+    const activeSegment = ctx[SYMBOLS.SEGMENT]
+    const parentSegment = ctx[SYMBOLS.PARENT_SEGMENT]
+    if (activeSegment) {
+      activeSegment.end()
+
+      if (error) {
+        handleError(activeSegment, error)
+      }
+
+      if (parentSegment) {
+        shim.setActiveSegment(parentSegment)
+      }
+    }
+  }
+
+  /**
+   * Adds the error to the active transaction
+   *
+   * @param {TraceSegment} activeSegment
+   * @param {Error} error
+   */
+  function handleError(activeSegment, error) {
+    logger.trace(error, 'Captured outbound error on behalf of the user.')
+    const tx = activeSegment.transaction
+    shim.agent.errors.add(tx, error)
+  }
+}
+
+module.exports.SYMBOLS = SYMBOLS

package/lib/instrumentations.js

@@ -31,6 +31,7 @@ module.exports = function instrumentations() {
     'redis': { type: MODULE_TYPE.DATASTORE },
     'restify': { type: MODULE_TYPE.WEB_FRAMEWORK },
     'superagent': { module: '@newrelic/superagent' },
+    'undici': { type: MODULE_TYPE.TRANSACTION },
     'oracle': { type: null },
     'vision': { type: MODULE_TYPE.WEB_FRAMEWORK },
     'when': { type: null }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [
@@ -134,8 +134,8 @@
     "docs": "npm ci && jsdoc -c ./jsdoc-conf.json --private -r .",
     "integration": "npm run prepare-test && npm run sub-install && time tap test/integration/**/**/*.tap.js --timeout=180 --no-coverage --reporter classic",
     "prepare-test": "npm run ca-gen && npm run ssl && npm run docker-env",
-    "lint": "eslint ./*.js lib test bin",
-    "lint:fix": "eslint --fix, ./*.js lib test bin",
+    "lint": "eslint ./*.js lib test bin examples",
+    "lint:fix": "eslint --fix, ./*.js lib test bin examples",
     "public-docs": "npm ci && jsdoc -c ./jsdoc-conf.json --tutorials examples/shim api.js lib/shim/ lib/transaction/handle.js && cp examples/shim/*.png out/",
     "publish-docs": "./bin/publish-docs.sh",
     "services": "./bin/docker-services.sh",
@@ -187,14 +187,15 @@
     "commander": "^7.0.0",
     "eslint": "^7.32.0",
     "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-disable": "^2.0.1",
     "eslint-plugin-header": "^3.1.1",
+    "eslint-plugin-jsdoc": "^36.1.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^3.4.0",
     "express": "*",
     "generic-pool": "^3.6.1",
     "glob": "^7.1.2",
     "got": "^8.0.1",
-    "http-errors": "^1.7.3",
     "husky": "^6.0.0",
     "jsdoc": "^3.6.3",
     "lint-staged": "^11.0.0",