newrelic 8.7.1 → 8.9.1

package/NEWS.md

@@ -1,3 +1,97 @@
+### v8.9.1 (2022-03-22)
+
+* Fixed `shim.wrapReturn` to call `Reflect.construct` in construct Proxy trap.  Also including `newTarget` to work with inherited classes.
+
+* Added link to New Relic Node.js Examples repository.
+
+* Excluded installing dependencies in `versioned-external` folders when running integration tests.
+
+### v8.9.0 (2022-03-15)
+
+* Added support for `initializeUnorderedBulkOp`, and `initializeOrderedBulkOp` in mongodb v3 instrumentation.
+
+  Thanks to Denis Lantsman (@dlants) for the contribution.
+
+* Updated logger to delay logging until configuration is parsed. The logger will now queue all log entries that occur before the agent can parse the configuration.
+
+  Thanks to Cody Landry (@codylandry) for the contribution.
+
+* Added `NEW_RELIC_ALLOW_ALL_HEADERS` as a boolean environment variable, same behavior as existing `allow_all_headers`.
+
+* Updated the AWS IMDBS v2 endpoint to use `latest` to align with the internal agent specification.
+
+* Bumped `@newrelic/koa` to ^6.1.1.
+
+* Added Next.js to External Modules list in README.
+
+* Updated mysql and mysql2 versioned tests to run against their own databases on the MySQL instance.
+
+* Removed upper-bound testing from restify versioned tests so future major versions will be covered.
+
+* Removed upper-bound testing from mysql2 versioned tests to cover existing and future major versions. 
+
+  Continues to skip version 1.6.2 which had a bug that broke tests which was resolved in 1.6.3.
+
+* Updated @hapi/hapi Node 16 versioned test runs to run against @hapi/hapi >=20.1.2 so future major releases will be ran.
+
+* Fixed sparse checkout of non-default branch for external versioned tests.
+
+* Added external versioned tests for the Apollo Server plugin instrumentation.
+
+* Added nock delay to test timeouts in utilization integration tests.
+
+* Added newrelic-node-nextjs to external versioned tests to be run on every PR.
+
+* Updated external version test running to support more test scenarios.
+  * Adds `test/versioned-external` to lint ignore to avoid issues for scripts in tests that auto run linting tools (next/react).
+  * Adds `index.js` and `nr-hooks.js` to files automatically checked-out for test runs.
+
+### v8.8.0 (2022-02-23)
+
+* Updated AWS metadata capture to utilize IMDSv2.
+
+* Fixed link to discuss.newrelic.com in README
+
+* Updated minimum Node version warning to output current Node version from process.
+
+* Bumped `@newrelic/native-metrics` to ^7.1.1.
+
+* Added `Nextjs` to a framework constant within the webframework-shim.
+
+* Updated shim to pass active segment to inContext callback.
+
+* Bumped `@grpc/grpc-js` to ^1.5.5.
+
+* Bumped `@grpc/proto-loader` to ^0.6.9.
+
+* Bumped `@newrelic/superagent` to ^5.1.0.
+
+* Bumped `@newrelic/koa` to ^6.1.0.
+
+* Bumped `async` to ^3.2.3.
+
+* Resolved several npm audit warnings for dev deps.
+
+* Fixed Post Release workflow by properly configuring git credentials so it can push API docs to branch
+ * Added `set -e` in publish docs script to exit on possible failures
+ * Removed redundant `npm ci` in publish API docs script
+
+* Added ability to ignore certain PRs in `bin/pending-prs.js` report to slack
+
+* Updated README to include `@newrelic/pino-enricher` as an external module.
+
+* Fixed documentation in a sample of the Datastore Instrumentation for Node.js.
+
+* Added a new `mongo:5` container to `npm run sevices` to test mongodb driver >=4.2.0.
+
+* Fixed conditions in post release workflow to function when triggered via successful release and manual invoked.
+
+* Updated method for retrieving agent version from repository by using `cat package.json | jq .version`
+
+* Fixed minor formatting and spelling issues in `create-docs-pr.js`.
+
+* Fixed an issue with the docs PR script that assumed `\n` in the NEWS.md file when extract version and release date
+
 ### v8.7.1 (2022-01-18)
 
 * Bumped @newrelic/aws-sdk to ^4.1.1.

package/README.md

@@ -67,8 +67,10 @@ For more information on getting started, [check the Node.js docs](https://docs.n
 There are several modules that can be installed and configured to accompany the Node.js agent:
 
  * [@newrelic/apollo-server-plugin](https://github.com/newrelic/newrelic-node-apollo-server-plugin): New Relic's official Apollo Server plugin for use with the Node.js agent.
- * [@newrelic/winston-enricher](https://github.com/newrelic/newrelic-winston-logenricher-node): Provides distributed trace and span information output as JSON-formatted log messages.  This is most commonly used with the New Relic Logs product.
+ * [@newrelic/winston-enricher](https://github.com/newrelic/newrelic-node-log-extensions/tree/main/packages/winston-log-enricher): Provides distributed trace and span information output as JSON-formatted log messages in Winston.  This is most commonly used with the New Relic Logs product.
+ * [@newrelic/pino-enricher](https://github.com/newrelic/newrelic-node-log-extensions/tree/main/packages/pino-log-enricher): Provides distributed trace and span information output as JSON-formatted log messages in Pino.  This is most commonly used with the New Relic Logs product.
  * [@newrelic/mysql](https://github.com/newrelic/node-newrelic-mysql)(**Experimental**): Standalone instrumentation for [mysql2](https://github.com/sidorares/node-mysql2#readme) and [mysql2/promise](https://github.com/sidorares/node-mysql2/blob/master/documentation/Promise-Wrapper.md) as well as the same instrumentation for [mysql](https://github.com/mysqljs/mysql#readme) within the Node.js agent.
+ * [@newrelic/next](https://github.com/newrelic/newrelic-node-nextjs): Provides instrumentation for the [Next.js](https://github.com/vercel/next.js/) npm package.
 
 There are several modules included within the Node.js agent to add more instrumentation for 3rd party modules:
 
@@ -143,6 +145,8 @@ Here are some resources for learning more about the agent:
 
 - [The changelog](https://github.com/newrelic/node-newrelic/blob/main/NEWS.md)
 
+- [Example applications](https://github.com/newrelic/newrelic-node-examples) - Working examples of New Relic features in Node.js.
+
 ## Support
 
 Should you need assistance with New Relic products, you are in good hands with several support channels.
@@ -152,7 +156,7 @@ If the issue has been confirmed as a bug or is a feature request, please file a
 **Support Channels**
 
 * [New Relic Documentation](https://docs.newrelic.com/docs/agents/nodejs-agent/getting-started/introduction-new-relic-nodejs): Comprehensive guidance for using our platform
-* [New Relic Community](https://discuss.newrelic.com/c/support-products-agents/node-js-agent/): The best place to engage in troubleshooting questions
+* [New Relic Community](https://discuss.newrelic.com/tags/c/telemetry-data-platform/agents/nodeagent): The best place to engage in troubleshooting questions
 * [New Relic Developer](https://developer.newrelic.com/): Resources for building a custom observability applications
 * [New Relic University](https://learn.newrelic.com/): A range of online training for New Relic users of every level
 * [New Relic Technical Support](https://support.newrelic.com/) 24/7/365 ticketed support. Read more about our [Technical Support Offerings](https://docs.newrelic.com/docs/licenses/license-information/general-usage-licenses/support-plan).

package/THIRD_PARTY_NOTICES.md

@@ -86,7 +86,7 @@ code, the source code can be found at [https://github.com/newrelic/node-newrelic
 
 ### @grpc/grpc-js
 
-This product includes source derived from [@grpc/grpc-js](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js) ([v1.3.7](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/tree/v1.3.7)), distributed under the [Apache-2.0 License](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/blob/v1.3.7/LICENSE):
+This product includes source derived from [@grpc/grpc-js](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js) ([v1.5.5](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/tree/v1.5.5)), distributed under the [Apache-2.0 License](https://github.com/grpc/grpc-node/tree/master/packages/grpc-js/blob/v1.5.5/LICENSE):
 
 ```
                                  Apache License
@@ -295,7 +295,7 @@ This product includes source derived from [@grpc/grpc-js](https://github.com/grp
 
 ### @grpc/proto-loader
 
-This product includes source derived from [@grpc/proto-loader](https://github.com/grpc/grpc-node) ([v0.5.6](https://github.com/grpc/grpc-node/tree/v0.5.6)), distributed under the [Apache-2.0 License](https://github.com/grpc/grpc-node/blob/v0.5.6/LICENSE):
+This product includes source derived from [@grpc/proto-loader](https://github.com/grpc/grpc-node) ([v0.6.9](https://github.com/grpc/grpc-node/tree/v0.6.9)), distributed under the [Apache-2.0 License](https://github.com/grpc/grpc-node/blob/v0.6.9/LICENSE):
 
 ```
                                  Apache License
@@ -712,7 +712,7 @@ This product includes source derived from [@newrelic/aws-sdk](https://github.com
 
 ### @newrelic/koa
 
-This product includes source derived from [@newrelic/koa](https://github.com/newrelic/node-newrelic-koa) ([v6.0.1](https://github.com/newrelic/node-newrelic-koa/tree/v6.0.1)), distributed under the [Apache-2.0 License](https://github.com/newrelic/node-newrelic-koa/blob/v6.0.1/LICENSE):
+This product includes source derived from [@newrelic/koa](https://github.com/newrelic/node-newrelic-koa) ([v6.1.0](https://github.com/newrelic/node-newrelic-koa/tree/v6.1.0)), distributed under the [Apache-2.0 License](https://github.com/newrelic/node-newrelic-koa/blob/v6.1.0/LICENSE):
 
 ```
 Apache License
@@ -921,7 +921,7 @@ Apache License
 
 ### @newrelic/superagent
 
-This product includes source derived from [@newrelic/superagent](https://github.com/newrelic/node-newrelic-superagent) ([v5.0.1](https://github.com/newrelic/node-newrelic-superagent/tree/v5.0.1)), distributed under the [Apache-2.0 License](https://github.com/newrelic/node-newrelic-superagent/blob/v5.0.1/LICENSE):
+This product includes source derived from [@newrelic/superagent](https://github.com/newrelic/node-newrelic-superagent) ([v5.1.0](https://github.com/newrelic/node-newrelic-superagent/tree/v5.1.0)), distributed under the [Apache-2.0 License](https://github.com/newrelic/node-newrelic-superagent/blob/v5.1.0/LICENSE):
 
 ```
                                  Apache License
@@ -1159,7 +1159,7 @@ THE SOFTWARE.
 
 ### async
 
-This product includes source derived from [async](https://github.com/caolan/async) ([v3.2.1](https://github.com/caolan/async/tree/v3.2.1)), distributed under the [MIT License](https://github.com/caolan/async/blob/v3.2.1/LICENSE):
+This product includes source derived from [async](https://github.com/caolan/async) ([v3.2.3](https://github.com/caolan/async/tree/v3.2.3)), distributed under the [MIT License](https://github.com/caolan/async/blob/v3.2.3/LICENSE):
 
 ```
 Copyright (c) 2010-2018 Caolan McMahon
@@ -2531,7 +2531,7 @@ SOFTWARE.
 
 ### jsdoc
 
-This product includes source derived from [jsdoc](https://github.com/jsdoc/jsdoc) ([v3.6.7](https://github.com/jsdoc/jsdoc/tree/v3.6.7)), distributed under the [Apache-2.0 License](https://github.com/jsdoc/jsdoc/blob/v3.6.7/LICENSE.md):
+This product includes source derived from [jsdoc](https://github.com/jsdoc/jsdoc) ([v3.6.10](https://github.com/jsdoc/jsdoc/tree/v3.6.10)), distributed under the [Apache-2.0 License](https://github.com/jsdoc/jsdoc/blob/v3.6.10/LICENSE.md):
 
 ```
 # License
@@ -3377,7 +3377,7 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ### @newrelic/native-metrics
 
-This product includes source derived from [@newrelic/native-metrics](https://github.com/newrelic/node-native-metrics) ([v7.0.1](https://github.com/newrelic/node-native-metrics/tree/v7.0.1)), distributed under the [Apache-2.0 License](https://github.com/newrelic/node-native-metrics/blob/v7.0.1/LICENSE):
+This product includes source derived from [@newrelic/native-metrics](https://github.com/newrelic/node-native-metrics) ([v7.1.1](https://github.com/newrelic/node-native-metrics/tree/v7.1.1)), distributed under the [Apache-2.0 License](https://github.com/newrelic/node-native-metrics/blob/v7.1.1/LICENSE):
 
 ```
                                  Apache License

package/index.js

@@ -45,10 +45,9 @@ function initialize() {
     logger.debug('Process was running %s seconds before agent was loaded.', preAgentTime)
 
     if (!psemver.satisfies(pkgJSON.engines.node)) {
-      // TODO: Update this message when Node v12 is deprecated.
       message =
-        'New Relic for Node.js requires a version of Node equal to or\n' +
-        'greater than 12.0.0. Not starting!'
+        `New Relic for Node.js requires a version of Node ${pkgJSON.engines.node}. \n` +
+        `Please upgrade from your current Node version: ${process.version}. Not starting!`
 
       logger.error(message)
       throw new Error(message)

package/lib/config/default.js

@@ -134,6 +134,8 @@ exports.config = () => ({
    * When true, all request headers except for those listed in attributes.exclude
    * will be captured for all traces, unless otherwise specified in a destination's
    * attributes include/exclude lists.
+   *
+   * @env NEW_RELIC_ALLOW_ALL_HEADERS
    */
   allow_all_headers: false,
 

package/lib/config/env.js

@@ -21,6 +21,7 @@ const ENV_MAPPING = {
   proxy_user: 'NEW_RELIC_PROXY_USER',
   proxy_pass: 'NEW_RELIC_PROXY_PASS',
   agent_enabled: 'NEW_RELIC_ENABLED',
+  allow_all_headers: 'NEW_RELIC_ALLOW_ALL_HEADERS',
   attributes: {
     enabled: 'NEW_RELIC_ATTRIBUTES_ENABLED',
     exclude: 'NEW_RELIC_ATTRIBUTES_EXCLUDE',
@@ -206,6 +207,7 @@ const OBJECT_LIST_VARS = new Set(['NEW_RELIC_NAMING_RULES'])
 // fancy--just use 'true' and 'false', everybody.
 const BOOLEAN_VARS = new Set([
   'NEW_RELIC_ENABLED',
+  'NEW_RELIC_ALLOW_ALL_HEADERS',
   'NEW_RELIC_ATTRIBUTES_ENABLED',
   'NEW_RELIC_ERROR_COLLECTOR_ENABLED',
   'NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_ENABLED',

package/lib/config/index.js

@@ -1623,7 +1623,8 @@ function initialize(config) {
   /**
    * When the logger is required here, it bootstraps itself and then
    * injects itself into this module's closure via setLogger on the
-   * instance of the logger it creates.
+   * instance of the logger it creates.  Logs are queued until config
+   * has been loaded to apply logging settings to bootstrapping logs
    */
   logger = require('../logger')
 
@@ -1712,7 +1713,14 @@ function getOrCreateInstance() {
 
       // Config construction has potential to throw due to invalid settings.
       // This allows the agent to return a stub api without crashing the process.
-      _configInstance = Object.assign(defaultConfig(), { agent_enabled: false })
+      _configInstance = Object.assign(defaultConfig(), {
+        agent_enabled: false,
+        logging: {
+          enabled: true,
+          filepath: 'stdout'
+        }
+      })
+
       _configInstance.setLogger = Config.prototype.setLogger
     }
   }

package/lib/instrumentation/mongodb/common.js

@@ -43,6 +43,23 @@ common.instrumentCollection = function instrumentCollection(shim, Collection) {
   }
 }
 
+/**
+ * Instruments the execute method on
+ * the BulkOperationBase class
+ *
+ * @param {Shim} shim
+ * @param {BulkOperationModule} bulk operation module, typically from mongodb/lib/bulk/common
+ * @param BulkOperationModule
+ */
+common.instrumentBulkOperation = function instrumentBulkOperation(shim, BulkOperationModule) {
+  const BulkOperationBase = BulkOperationModule && BulkOperationModule.BulkOperationBase
+
+  if (BulkOperationBase && BulkOperationBase.prototype) {
+    const proto = BulkOperationBase.prototype
+    shim.recordBatchQuery(proto, 'execute', common.makeBulkDescFunc(shim, 'execute'))
+  }
+}
+
 /**
  * Instruments all methods from constants.DB_OPS on
  * the Db class.
@@ -84,6 +101,25 @@ common.makeQueryDescFunc = function makeQueryDescFunc(shim, methodName) {
   }
 }
 
+/**
+ * Sets up the desc for all instrumented bulk operations
+ *
+ * @param {Shim} shim
+ * @param {string} methodName
+ */
+common.makeBulkDescFunc = function makeBulkDescFunc(shim) {
+  return function bulkDescFunc() {
+    const parameters = getInstanceAttributeParameters(shim, this)
+    return {
+      query: this.isOrdered ? 'orderedBulk' : 'unorderedBulk',
+      parameters,
+      promise: true,
+      callback: shim.LAST,
+      opaque: true
+    }
+  }
+}
+
 /**
  * Sets up a listener for `started` on instrumenter(mongo APM). This applies to
  * mongo <4. The listener adds the following attributes to the active segment:
@@ -161,9 +197,10 @@ function setHostPort(shim, connStr, db, client) {
  * @param obj
  */
 function getInstanceAttributeParameters(shim, obj) {
-  if (obj.s && obj.s.db && obj.s.topology) {
+  if (obj.s && obj.s.topology) {
     shim.logger.trace('Adding datastore instance attributes from obj.s.db + obj.s.topology')
-    const databaseName = obj.s.db.databaseName || null
+    const databaseName =
+      (obj.s.db && obj.s.db.databaseName) || (obj.s.namespace && obj.s.namespace.db) || null
     const topology = obj.s.topology
     if (topology.s && topology.s.options) {
       return doCapture(topology.s.options, databaseName)

package/lib/instrumentation/mongodb/v3-mongo.js

@@ -7,6 +7,7 @@
 
 const {
   captureAttributesOnStarted,
+  instrumentBulkOperation,
   instrumentCollection,
   instrumentCursor,
   instrumentDb,
@@ -27,6 +28,8 @@ function queryParser(operation) {
     collection = this.operation.target
   } else if (this.ns) {
     collection = this.ns.split(/\./)[1] || collection
+  } else if (this.s && this.s.collection && this.s.collection.collectionName) {
+    collection = this.s.collection.collectionName
   }
   return { operation, collection }
 }
@@ -68,6 +71,7 @@ module.exports = function instrument(shim, mongodb) {
   instrumentCursor(shim, mongodb.Cursor)
   instrumentCursor(shim, shim.require('./lib/aggregation_cursor'))
   instrumentCursor(shim, shim.require('./lib/command_cursor'))
+  instrumentBulkOperation(shim, shim.require('./lib/bulk/common'))
   instrumentCollection(shim, mongodb.Collection)
   instrumentDb(shim, mongodb.Db)
 

package/lib/logger.js

@@ -9,12 +9,16 @@ const Logger = require('./util/logger')
 const fs = require('./util/unwrapped-core').fs
 
 // create bootstrapping logger
-module.exports = new Logger({
+const logger = new Logger({
   name: 'newrelic_bootstrap',
-  stream: process.stdout,
-  level: 'info'
+  level: 'info',
+
+  // logger is configured below.  Logs are queued until configured
+  configured: false
 })
 
+module.exports = logger
+
 /**
  * Don't load config until this point, because it requires this
  * module, and if it gets loaded too early, module.exports will have no
@@ -28,8 +32,8 @@ if (config) {
     enabled: config.logging.enabled
   }
 
-  // create the "real" logger
-  module.exports = new Logger(options)
+  // configure logger
+  logger.configure(options)
 
   if (config.logging.enabled) {
     let stream
@@ -52,9 +56,6 @@ if (config) {
           /* eslint-enable no-console */
         })
     }
-    module.exports.pipe(stream)
+    logger.pipe(stream)
   }
-
-  // now tell the config module to switch to the real logger
-  config.setLogger(module.exports)
 }

package/lib/shim/shim.js

@@ -639,10 +639,9 @@ function wrapReturn(nodule, properties, spec, args) {
         }
         return true
       },
-      construct: function constructTrap(Target, proxyArgs) {
-        // Call the underlying function. If this was called as a constructor, call
-        // the wrapped function as a constructor too.
-        let ret = new Target(...proxyArgs)
+      construct: function constructTrap(target, proxyArgs, newTarget) {
+        // Call the underlying function via Reflect.
+        let ret = Reflect.construct(target, proxyArgs, newTarget)
 
         // Assemble the arguments to hand to the spec.
         const _args = [shim, fn, fnName, ret]
@@ -1307,7 +1306,7 @@ function applySegment(func, segment, full, context, args, inContextCB) {
     }
 
     if (typeof inContextCB === 'function') {
-      inContextCB()
+      inContextCB(segment)
     }
 
     try {

package/lib/shim/webframework-shim.js

@@ -29,10 +29,11 @@ const FRAMEWORK_NAMES = {
   CONNECT: 'Connect',
   DIRECTOR: 'Director',
   EXPRESS: 'Expressjs',
+  FASTIFY: 'Fastify',
   HAPI: 'Hapi',
   KOA: 'Koa',
-  RESTIFY: 'Restify',
-  FASTIFY: 'Fastify'
+  NEXT: 'Nextjs',
+  RESTIFY: 'Restify'
 }
 
 const MIDDLEWARE_TYPE_DETAILS = {
@@ -64,24 +65,19 @@ const TRANSACTION_INFO_KEY = '__NR_transactionInfo'
  * Constructs a shim associated with the given agent instance, specialized for
  * instrumenting web frameworks.
  *
- * @constructor
- * @extends TransactionShim
+ * @class
+ * @augments TransactionShim
  * @classdesc
  *  A helper class for wrapping web framework modules.
- *
  * @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.
- *
  * @param {string} [frameworkId]
  *  The name of the web framework being instrumented. If available, use one of
  *  the values from {@link WebFrameworkShim.FRAMEWORK_NAMES}.
- *
  * @see TransactionShim
  * @see WebFrameworkShim.FRAMEWORK_NAMES
  */
@@ -130,123 +126,93 @@ WebFrameworkShim.prototype.captureUrlParams = captureUrlParams
 
 /**
  * @callback RouteParserFunction
- *
  * @summary
  *  Called whenever new middleware are mounted using the instrumented framework,
  *  this method should pull out a representation of the mounted path.
- *
  * @param {WebFrameworkShim} shim
  *  The shim in use for this instrumentation.
- *
- * @param {function} fn
+ * @param {Function} fn
  *  The function which received this route string/RegExp.
- *
  * @param {string} fnName
  *  The name of the function to which this route was given.
- *
  * @param {string|RegExp} route
  *  The route that was given to the function.
- *
- * @return {string|RegExp} The mount point from the given route.
+ * @returns {string|RegExp} The mount point from the given route.
  */
 
 /**
  * @callback RouteRequestFunction
- *
  * @summary
  *  Extracts the request object from the arguments to the middleware function.
- *
  * @param {WebFrameworkShim}  shim    - The shim used for instrumentation.
- * @param {function}          fn      - The middleware function.
+ * @param {Function}          fn      - The middleware function.
  * @param {string}            fnName  - The name of the middleware function.
  * @param {Array}             args    - The arguments to the middleware function.
- *
- * @return {Object} The request object.
+ * @returns {object} The request object.
  */
 
 /**
  * @callback RouteNextFunction
- *
  * @summary
  *  Used to wrap functions that users can call to continue to the next middleware.
- *
  * @param {WebFrameworkShim}    shim    - The shim used for instrumentation.
- * @param {function}            fn      - The middleware function.
+ * @param {Function}            fn      - The middleware function.
  * @param {string}              fnName  - The name of the middleware function.
  * @param {Array}               args    - The arguments to the middleware function.
  * @param {NextWrapperFunction} wrap    - A function to wrap an individual next function.
- *
- * @return {Object} The request object.
+ * @returns {object} The request object.
  */
 
 /**
  * @callback RouteParameterFunction
- *
  * @summary
  *  Extracts the route parameters from the arguments to the middleware function.
- *
  * @param {WebFrameworkShim}  shim    - The shim used for instrumentation.
- * @param {function}          fn      - The middleware function.
+ * @param {Function}          fn      - The middleware function.
  * @param {string}            fnName  - The name of the middleware function.
  * @param {Array}             args    - The arguments to the middleware function.
- *
- * @return {Object} A map of route parameter names to values.
+ * @returns {object} A map of route parameter names to values.
  */
 
 /**
  * @callback MiddlewareWrapperFunction
- *
  * @summary
  *  Called for each middleware passed to a mounting method. Should perform the
  *  wrapping of the middleware.
- *
  * @param {WebFrameworkShim} shim
  *  The shim used for instrumentation.
- *
- * @param {function} middleware
+ * @param {Function} middleware
  *  The middleware function to wrap.
- *
  * @param {string} fnName
  *  The name of the middleware function.
- *
  * @param {string} [route=null]
  *  The route the middleware is mounted on if one was found.
- *
  * @see WebFrameworkShim#recordMiddleware
  * @see WebFrameworkShim#recordParamware
  */
 
 /**
  * @interface MiddlewareSpec
- *
  * @description
  *  Describes the interface for middleware functions with this instrumentation.
- *
  * @property {number|RouteRequestFunction} [req=shim.FIRST]
  *  Indicates which argument to the middleware is the request object. It can also be
  *  a function to extract the request object from the middleware arguments.
- *
  * @property {number} [res=shim.SECOND]
  *  Indicates which argument to the middleware is the response object.
- *
  * @property {number|RouteNextFunction} [next=shim.THIRD]
  *  Indicates which argument to the middleware function is the callback.  When it is
  *  a function, it will be called with the arguments of the middleware and a function
  *  for wrapping calls that represent continuation from the current middleware.
- *
  * @property {string} [name]
  *  The name to use for this middleware. Defaults to `middleware.name`.
- *
  * @property {RouteParameterFunction} [params]
  *  A function to extract the route parameters from the middleware arguments.
  *  Defaults to using `req.params`.
- *
  * @property {string} [type='MIDDLEWARE']
- *
- * @property {string|function} [route=null]
+ * @property {string | Function} [route=null]
  *  Route/path used for naming segments and transaction name candidates. If a function,
  *  will be invoked just before segment creation with middleware invocation.
- *
  * @property {boolean} [appendPath=true]
  *  Indicates that the path associated with the middleware should be appended
  *  and popped from the stack of name candidates.
@@ -254,31 +220,25 @@ WebFrameworkShim.prototype.captureUrlParams = captureUrlParams
 
 /**
  * @interface MiddlewareMounterSpec
- *
  * @description
  *  Describes the arguments provided to mounting methods (e.g. `app.post()`).
- *
  * @property {number|string} [route=null]
  *  Tells which argument may be the mounting path for the other arguments. If
  *  the indicated argument is a function it is assumed the route was not provided
  *  and the indicated argument is a middleware function. If a string is provided
  *  it will be used as the mounting path.
- *
  * @property {MiddlewareWrapperFunction} [wrapper]
  *  A function to call for each middleware function passed to the mounter.
  */
 
 /**
  * @interface RenderSpec
- * @extends RecorderSpec
- *
+ * @augments RecorderSpec
  * @description
  *  Describes the interface for render methods.
- *
  * @property {number} [view=shim.FIRST]
  *  Identifies which argument is the name of the view being rendered. Defaults
  *  to {@link Shim#ARG_INDEXES shim.FIRST}.
- *
  * @see SegmentSpec
  * @see RecorderSpec
  */
@@ -292,7 +252,6 @@ WebFrameworkShim.prototype.captureUrlParams = captureUrlParams
  * - `setRouteParser(parser)`
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {RouteParserFunction} parser - The parser function to use.
  */
 function setRouteParser(parser) {
@@ -310,10 +269,8 @@ function setRouteParser(parser) {
  * This should be the first thing the instrumentation does.
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {WebFrameworkShim.FRAMEWORK_NAMES|string} framework
  *  The name of the framework.
- *
  * @see WebFrameworkShim.FRAMEWORK_NAMES
  */
 function setFramework(framework) {
@@ -332,7 +289,6 @@ function setFramework(framework) {
  * Sets the URI path to be used for naming the transaction currently in scope.
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {string} uri - The URI path to use for the transaction.
  */
 function setTransactionUri(uri) {
@@ -351,18 +307,14 @@ function setTransactionUri(uri) {
  * - `recordRender(func [, spec])`
  *
  * @memberof WebFrameworkShim.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 {RenderSpec} [spec]
  *  The spec for wrapping the render 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.
  */
 function recordRender(nodule, properties, spec) {
@@ -407,20 +359,15 @@ function recordRender(nodule, properties, spec) {
  * - `wrapMiddlewareMounter(func [, spec])`
  *
  * @memberof WebFrameworkShim.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 {MiddlewareMounterSpec} [spec]
  *  Spec describing the parameters for this middleware mount point.
- *
- * @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 WebFrameworkShim#recordMiddleware
  */
 function wrapMiddlewareMounter(nodule, properties, spec) {
@@ -470,6 +417,10 @@ function wrapMiddlewareMounter(nodule, properties, spec) {
         }
 
         _wrapMiddlewares.call(this, routeIdx, args)
+        /**
+         * @param _routeIdx
+         * @param middlewares
+         */
         function _wrapMiddlewares(_routeIdx, middlewares) {
           for (let i = 0; i < middlewares.length; ++i) {
             // If this argument is the route argument skip it.
@@ -512,20 +463,15 @@ function wrapMiddlewareMounter(nodule, properties, spec) {
  * - `recordMiddleware(func [, spec])`
  *
  * @memberof WebFrameworkShim.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 {MiddlewareSpec} [spec]
  *  The spec for wrapping the middleware.
- *
- * @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 WebFrameworkShim#wrapMiddlewareMounter
  */
 function recordMiddleware(nodule, properties, spec) {
@@ -560,18 +506,14 @@ function recordMiddleware(nodule, properties, spec) {
  * processing as possible.
  *
  * @memberof WebFrameworkShim.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 {MiddlewareSpec} [spec]
  *  The spec for wrapping the middleware.
- *
- * @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.
  */
 function recordParamware(nodule, properties, spec) {
@@ -610,10 +552,8 @@ function recordParamware(nodule, properties, spec) {
  * caught by the user.
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {Request} req - The request which caused the error.
  * @param {*?}      err - The error which has occurred.
- *
  * @see WebFrameworkShim#errorHandled
  * @see WebFrameworkShim#setErrorPredicate
  */
@@ -628,10 +568,8 @@ function noticeError(req, err) {
  * Indicates that the given error has been handled for this request.
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {Request} req - The request which caused the error.
  * @param {*}       err - The error which has been handled.
- *
  * @see WebFrameworkShim#noticeError
  * @see WebFrameworkShim#setErrorPredicate
  */
@@ -647,11 +585,9 @@ function errorHandled(req, err) {
  * an error.
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {function(object): bool} pred
  *  Function which should return true if the object passed to it is considered
  *  an error.
- *
  * @see WebFrameworkShim#noticeError
  * @see WebFrameworkShim#errorHandled
  */
@@ -663,7 +599,6 @@ function setErrorPredicate(pred) {
  * Marks the current path as a potential responder.
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {Request} req - The request which caused the error.
  */
 function savePossibleTransactionName(req) {
@@ -678,7 +613,6 @@ function savePossibleTransactionName(req) {
  * responded.
  *
  * @memberof WebFrameworkShim.prototype
- *
  * @param {function(args, object): bool} pred
  *  Function which should return true if the object passed to it is considered
  *  a response.
@@ -691,8 +625,7 @@ function setResponsePredicate(pred) {
  * Capture URL parameters from a request object as attributes of the current segment.
  *
  * @memberof WebFrameworkShim.prototype
- *
- * @param {Object} params
+ * @param {object} params
  *  An object with key-value pairs.
  */
 function captureUrlParams(params) {
@@ -708,19 +641,14 @@ function captureUrlParams(params) {
  * Default route parser function if one is not provided.
  *
  * @private
- *
  * @param {WebFrameworkShim} shim
  *  The shim in use for this instrumentation.
- *
- * @param {function} fn
+ * @param {Function} fn
  *  The function which received this route string/RegExp.
- *
  * @param {string} fnName
  *  The name of the function to which this route was given.
- *
  * @param {string|RegExp} route
  *  The route that was given to the function.
- *
  * @see RouteParserFunction
  */
 function _defaultRouteParser(shim, fn, fnName, route) {
@@ -737,8 +665,7 @@ function _defaultRouteParser(shim, fn, fnName, route) {
  * Default error predicate just returns true.
  *
  * @private
- *
- * @return {bool} True. Always.
+ * @returns {bool} True. Always.
  */
 function _defaultErrorPredicate() {
   return true
@@ -748,8 +675,7 @@ function _defaultErrorPredicate() {
  * Default response predicate just returns false.
  *
  * @private
- *
- * @return {bool} False. Always.
+ * @returns {bool} False. Always.
  */
 function _defaultResponsePredicate() {
   return false
@@ -759,19 +685,18 @@ function _defaultResponsePredicate() {
  * Wraps the given function in a middleware recorder function.
  *
  * @private
- *
  * @param {WebFrameworkShim} shim
  *  The shim used for this instrumentation.
- *
- * @param {function} middleware
+ * @param {Function} middleware
  *  The middleware function to record.
- *
  * @param {MiddlewareSpec} spec
  *  The spec describing the middleware.
- *
- * @return {function} The middleware function wrapped in a recorder.
+ * @returns {Function} The middleware function wrapped in a recorder.
  */
 function _recordMiddleware(shim, middleware, spec) {
+  /**
+   *
+   */
   function getRoute() {
     let route = spec.route || '/'
 
@@ -797,6 +722,9 @@ function _recordMiddleware(shim, middleware, spec) {
     metricName = shim._metrics.MIDDLEWARE + metricName + name
   }
 
+  /**
+   * @param route
+   */
   function getSegmentName(route) {
     let segmentName = metricName
     if (typeDetails.path) {
@@ -817,6 +745,12 @@ function _recordMiddleware(shim, middleware, spec) {
   )
 
   // TODO: let's please break these out
+  /**
+   * @param shim
+   * @param fn
+   * @param fnName
+   * @param args
+   */
   function middlewareWithCallbackRecorder(shim, fn, fnName, args) {
     const route = getRoute()
 
@@ -909,6 +843,12 @@ function _recordMiddleware(shim, middleware, spec) {
     }
   }
 
+  /**
+   * @param shim
+   * @param fn
+   * @param fnName
+   * @param args
+   */
   function middlewareWithPromiseRecorder(shim, fn, fnName, args) {
     const route = getRoute()
 
@@ -1007,6 +947,10 @@ function _recordMiddleware(shim, middleware, spec) {
   }
 }
 
+/**
+ * @param shim
+ * @param req
+ */
 function _makeGetReq(shim, req) {
   return function getReqFromArgs(shim, fn, name, args) {
     const reqIdx = shim.normalizeIndex(args.length, req)
@@ -1018,6 +962,10 @@ function _makeGetReq(shim, req) {
   }
 }
 
+/**
+ * @param nextDetails
+ * @param txInfo
+ */
 function _makeNextBinder(nextDetails, txInfo) {
   return function bindNext(shim, fn, _name, segment, args) {
     if (!segment) {
@@ -1029,6 +977,11 @@ function _makeNextBinder(nextDetails, txInfo) {
 
     // Called from outside to wrap functions that could be called to continue
     // to the next middleware
+    /**
+     * @param nodule
+     * @param property
+     * @param isFinal
+     */
     function nextWrapper(nodule, property, isFinal) {
       shim.wrap(nodule, property, function wrapper(shim, original) {
         const parentSegment = segment || shim.getSegment()
@@ -1077,11 +1030,9 @@ function _makeNextBinder(nextDetails, txInfo) {
  * available.
  *
  * @private
- *
  * @param {WebFrameworkShim}      shim  - The shim used for this instrumentation.
  * @param {http.IncomingMessage}  req   - The incoming request object.
- *
- * @return {object?} The transaction information if available, otherwise null.
+ * @returns {object?} The transaction information if available, otherwise null.
  */
 function _getTransactionInfo(shim, req) {
   try {
@@ -1096,8 +1047,8 @@ function _getTransactionInfo(shim, req) {
  * Creates a recorder for middleware metrics.
  *
  * @private
- *
- *
+ * @param shim
+ * @param metricName
  * @param {string}  path    - The mounting path of the middleware.
  * @param {Segment} segment - The segment generated for this middleware.
  * @param {string}  scope   - The scope of the metric to record.
@@ -1119,13 +1070,10 @@ function _makeMiddlewareRecorder(shim, metricName) {
  * Adds the given error to the transaction information if it is actually an error.
  *
  * @private
- *
  * @param {WebFrameworkShim} shim
  *  The shim used for this web framework.
- *
  * @param {TransactionInfo} txInfo
  *  The transaction context information for the request.
- *
  * @param {*} err
  *  The error to notice.
  */
@@ -1138,14 +1086,11 @@ function _noticeError(shim, txInfo, err) {
  * Determines if the given object is an error according to the shim.
  *
  * @private
- *
  * @param {WebFrameworkShim} shim
  *  The shim used for this web framework.
- *
  * @param {?*} err
  *  The object to check for error-ness.
- *
- * @return {bool} True if the given object is an error according to the shim.
+ * @returns {bool} True if the given object is an error according to the shim.
  */
 function _isError(shim, err) {
   return err && shim._errorPredicate(err)
@@ -1155,11 +1100,9 @@ function _isError(shim, err) {
  * Copy the keys expected from source to destination.
  *
  * @private
- *
- * @param {Object} destination
+ * @param {object} destination
  *   The spec object receiving the expected values
- *
- * @param {Object} source
+ * @param {object} source
  *   The spec object the values are coming from
  */
 function _copyExpectedSpecParameters(destination, source) {

package/lib/util/logger.js

@@ -39,7 +39,8 @@ function Logger(options, extra) {
   const passedInLevel = this.coerce(options.level)
   this.options = {
     _level: passedInLevel,
-    enabled: options.enabled === undefined ? true : options.enabled
+    enabled: options.enabled === undefined ? true : options.enabled,
+    configured: options.configured === undefined ? true : !!options.configured
   }
   this._nestedLog = false
   this.name = options.name
@@ -47,12 +48,30 @@ function Logger(options, extra) {
   this.extra = extra || Object.create(null)
   this.buffer = ''
   this.reading = false
+  this.logQueue = []
   if (options.stream) {
     this.pipe(options.stream)
   }
 }
 Logger.MAX_LOG_BUFFER = MAX_LOG_BUFFER
 
+Logger.prototype.configure = function configure(options) {
+  if (options.name !== undefined) {
+    this.name = options.name
+  }
+
+  if (options.enabled !== undefined) {
+    this.options.enabled = options.enabled
+  }
+
+  if (options.level !== undefined) {
+    this.options._level = this.coerce(options.level)
+  }
+
+  this.options.configured = true
+  this._flushQueuedLogs()
+}
+
 Logger.prototype.coerce = function coerce(value) {
   if (!isNaN(parseInt(value, 10)) && isFinite(value)) {
     // value is numeric
@@ -74,6 +93,11 @@ Object.keys(LEVELS).forEach(function buildLevel(_level) {
   const level = Logger.prototype.coerce(LEVELS[_level])
 
   function log(extra) {
+    if (!this.options.configured) {
+      this.logQueue.unshift({ level: _level, args: arguments })
+      return
+    }
+
     if (!this.options.enabled) {
       return false
     }
@@ -149,6 +173,13 @@ Object.keys(LEVELS).forEach(function buildLevel(_level) {
   }
 })
 
+Logger.prototype._flushQueuedLogs = function _flushQueuedLogs() {
+  while (this.logQueue.length) {
+    const { level, args } = this.logQueue.shift()
+    this[level].apply(this, args)
+  }
+}
+
 Object.assign(Logger.prototype, loggingFunctions)
 
 Logger.prototype.child = function child(extra) {
@@ -196,6 +227,10 @@ Logger.prototype._read = function _read() {
  * already converted the objects to strings.
  * Returns a boolean representing the status of the write
  * (success/failure)
+ *
+ * @param level
+ * @param args
+ * @param extra
  */
 Logger.prototype.write = function write(level, args, extra) {
   if (this._nestedLog) {

package/lib/utilization/aws-info.js

@@ -9,6 +9,7 @@ const logger = require('../logger.js').child({ component: 'aws-info' })
 const common = require('./common')
 const NAMES = require('../metrics/names.js')
 let results = null
+const INSTANCE_HOST = '169.254.169.254'
 
 module.exports = fetchAWSInfo
 module.exports.clearCache = function clearAWSCache() {
@@ -24,27 +25,45 @@ function fetchAWSInfo(agent, callback) {
     return setImmediate(callback, null, results)
   }
 
-  const instanceHost = '169.254.169.254'
-  const apiVersion = '2016-09-02'
-  const endpoint = 'dynamic/instance-identity/document'
-  const url = 'http://' + instanceHost + '/' + apiVersion + '/' + endpoint
-  common.request(url, agent, function getMetadata(err, data) {
+  const authTokenOpts = {
+    headers: { 'X-aws-ec2-metadata-token-ttl-seconds': '21600' },
+    host: INSTANCE_HOST,
+    method: 'PUT',
+    path: '/latest/api/token',
+    timeout: 500
+  }
+  common.request(authTokenOpts, agent, function getAuthToken(err, authToken) {
     if (err) {
+      logger.debug('Failed to get AWS auth token.')
       return callback(err)
     }
 
-    try {
-      data = JSON.parse(data)
-    } catch (e) {
-      logger.debug(e, 'Failed to parse AWS metadata.')
-      data = null
+    const metadataOpts = {
+      headers: { 'X-aws-ec2-metadata-token': authToken },
+      host: INSTANCE_HOST,
+      method: 'GET',
+      path: '/latest/dynamic/instance-identity/document',
+      timeout: 500
     }
 
-    results = common.getKeys(data, ['availabilityZone', 'instanceId', 'instanceType'])
-    if (results == null) {
-      logger.debug('AWS metadata was invalid.')
-      agent.metrics.getOrCreateMetric(NAMES.UTILIZATION.AWS_ERROR).incrementCallCount()
-    }
-    callback(null, results)
+    common.request(metadataOpts, agent, function getMetadata(metaErr, data) {
+      if (metaErr) {
+        return callback(metaErr)
+      }
+
+      try {
+        data = JSON.parse(data)
+      } catch (e) {
+        logger.debug(e, 'Failed to parse AWS metadata.')
+        data = null
+      }
+
+      results = common.getKeys(data, ['availabilityZone', 'instanceId', 'instanceType'])
+      if (results == null) {
+        logger.debug('AWS metadata was invalid.')
+        agent.metrics.getOrCreateMetric(NAMES.UTILIZATION.AWS_ERROR).incrementCallCount()
+      }
+      callback(null, results)
+    })
   })
 }

package/lib/utilization/common.js

@@ -65,6 +65,12 @@ exports.request = function request(opts, agent, cb) {
 
   opts.timeout = opts.timeout || 1000
 
+  // This can make more that GET requests if you pass in an object
+  // Node.js just pass this method into ClientRequest which accepts
+  // any valid HTTP Method
+  // see: https://github.com/nodejs/node/blob/master/lib/http.js#L106
+  // Technically this wouldn't work for a PUT/POST with a body
+  // but works fine in all cases where this is being used.
   const req = http.get(opts, function awsRequest(res) {
     res.pipe(concat(respond))
     function respond(data) {
@@ -89,9 +95,7 @@ exports.request = function request(opts, agent, cb) {
     }
   })
 
-  req.setTimeout(1000, function requestTimeout() {
-    req.abort()
-  })
+  req.on('timeout', abortRequest)
 
   req.on('error', function requestError(err) {
     if (err.code === 'ECONNRESET') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "8.7.1",
+  "version": "8.9.1",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [
@@ -136,7 +136,7 @@
     "prepare-test": "npm run ca-gen && npm run ssl && npm run docker-env",
     "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/",
+    "public-docs": "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",
     "smoke": "npm run ssl && time tap test/smoke/**/**/*.tap.js --timeout=180 --no-coverage",
@@ -159,13 +159,13 @@
     "newrelic-naming-rules": "./bin/test-naming-rules.js"
   },
   "dependencies": {
-    "@grpc/grpc-js": "^1.2.11",
-    "@grpc/proto-loader": "^0.5.6",
+    "@grpc/grpc-js": "^1.5.5",
+    "@grpc/proto-loader": "^0.6.9",
     "@newrelic/aws-sdk": "^4.1.1",
-    "@newrelic/koa": "^6.0.1",
-    "@newrelic/superagent": "^5.0.1",
+    "@newrelic/koa": "^6.1.1",
+    "@newrelic/superagent": "^5.1.0",
     "@tyriar/fibonacci-heap": "^2.0.7",
-    "async": "^3.2.0",
+    "async": "^3.2.3",
     "concat-stream": "^2.0.0",
     "https-proxy-agent": "^5.0.0",
     "json-stringify-safe": "^5.0.0",
@@ -173,7 +173,7 @@
     "semver": "^5.3.0"
   },
   "optionalDependencies": {
-    "@newrelic/native-metrics": "^7.0.1"
+    "@newrelic/native-metrics": "^7.1.1"
   },
   "devDependencies": {
     "@newrelic/eslint-config": "^0.0.3",