newrelic 8.5.0 → 8.7.0

package/lib/shim/transaction-shim.js

@@ -16,15 +16,13 @@ const TRANSACTION_TYPES_SET = Transaction.TYPES_SET
 /**
  * Constructs a transaction managing shim.
  *
- * @constructor
- * @extends Shim
+ * @class
+ * @augments Shim
  * @classdesc
  *  A helper class for working with transactions.
- *
  * @param {Agent}   agent         - The agent the shim will use.
  * @param {string}  moduleName    - The name of the module being instrumented.
  * @param {string}  resolvedName  - The full path to the loaded module.
- *
  * @see Shim
  * @see WebFrameworkShim
  */
@@ -75,22 +73,18 @@ TransactionShim.prototype.insertCATRequestHeaders = insertCATRequestHeaders
 
 /**
  * @interface TransactionSpec
- *
  * @description
  *  Describes the type of transaction to be created by the function being
  *  wrapped by {@link Shim#bindCreateTransaction}.
- *
  * @property {string} type
  *  The type of transaction to create. Must be one of the values from
  *  {@link Shim#TRANSACTION_TYPES}.
- *
  * @property {bool} [nest=false]
  *  Indicates if the transaction being created is allowed to be nested within
  *  another transaction of the same type. If `false`, the default, the transaction
  *  will only be created if there is no existing transaction, or the current
  *  transaction is of a different type. If `true`, the transaction will be
  *  created regardless of the current transaction's type.
- *
  * @see Shim#bindCreateTransaction
  * @see Shim#TRANSACTION_TYPES
  */
@@ -105,18 +99,14 @@ TransactionShim.prototype.insertCATRequestHeaders = insertCATRequestHeaders
  * - `bindCreateTransaction(func, spec)`
  *
  * @memberof TransactionShim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the property to wrap, or a single function to wrap.
- *
  * @param {string} [property]
  *  The property to wrap. If omitted, the `nodule` parameter is assumed to be
  *  the function to wrap.
- *
  * @param {TransactionSpec} spec
  *  The spec for creating the transaction.
- *
- * @return {Object|Function} The first parameter to this function, after
+ * @returns {object | Function} The first parameter to this function, after
  *  wrapping it or its property.
  */
 function bindCreateTransaction(nodule, property, spec) {
@@ -164,7 +154,6 @@ function bindCreateTransaction(nodule, property, spec) {
  * back off when resolution exits the item.
  *
  * @memberof TransactionShim.prototype
- *
  * @param {string} pathSegment - The path segment to add to the naming stack.
  */
 function pushTransactionName(pathSegment) {
@@ -183,7 +172,6 @@ function pushTransactionName(pathSegment) {
  * this function, but we do not live in an ideal world.
  *
  * @memberof TransactionShim.prototype
- *
  * @param {string} [pathSegment]
  *  Optional. Path segment to pop the stack repeatedly until a segment matching
  *  `pathSegment` is removed.
@@ -203,7 +191,6 @@ function popTransactionName(pathSegment) {
  * Either this _or_ the naming stack should be used. Do not use them together.
  *
  * @memberof TransactionShim.prototype
- *
  * @param {string} name - The name to use for the transaction.
  */
 function setTransactionName(name) {
@@ -222,14 +209,11 @@ function setTransactionName(name) {
  *
  * This will check for either header naming style, and both request and reply
  * CAT headers.
- *
  * @param {object} headers
  *  The request/response headers object to look in.
- *
  * @param {TraceSegment} [segment=null]
  *  The trace segment to associate the header data with. If no segment is
  *  provided then the currently active segment is used.
- *
  * @param {string} [transportType='Unknown']
  *  The transport type that brought the headers. Usually `HTTP` or `HTTPS`.
  */
@@ -282,10 +266,8 @@ function handleCATHeaders(headers, segment, transportType) {
  * - `insertCATRequestHeaders(headers [, useAlternateHeaderNames])`
  *
  * @memberof TransactionShim.prototype
- *
  * @param {object} headers
  *  The outbound request headers object to inject our CAT headers into.
- *
  * @param {bool} [useAlternateHeaderNames=false]
  *  Indicates if HTTP-style headers should be used or alternate style. Some
  *  transport protocols are more strict on the characters allowed in headers
@@ -327,10 +309,8 @@ function insertCATRequestHeaders(headers, useAlternateHeaderNames) {
  * - `insertCATReplyHeaders(headers [, useAlternateHeaderNames])`
  *
  * @memberof TransactionShim.prototype
- *
  * @param {object} headers
  *  The outbound response headers object to inject our CAT headers into.
- *
  * @param {bool} [useAlternateHeaderNames=false]
  *  Indicates if HTTP-style headers should be used or alternate style. Some
  *  transport protocols are more strict on the characters allowed in headers
@@ -388,20 +368,15 @@ function insertCATReplyHeader(headers, useAlternateHeaderNames) {
  * `spec.type` is not the same as the current transaction's type.
  *
  * @private
- *
  * @param {Shim} shim
  *  The shim used for the binding.
- *
- * @param {function} fn
+ * @param {Function} fn
  *  The function link with the transaction.
- *
  * @param {string} name
  *  The name of the wrapped function.
- *
  * @param {TransactionSpec} spec
  *  The spec for the transaction to create.
- *
- * @return {function} A function which wraps `fn` and creates potentially nested
+ * @returns {Function} A function which wraps `fn` and creates potentially nested
  *  transactions linked to its execution.
  */
 function _makeNestedTransWrapper(shim, fn, name, spec) {
@@ -412,7 +387,7 @@ function _makeNestedTransWrapper(shim, fn, name, spec) {
 
     // Reuse existing transactions only if the type matches.
     let transaction = shim.tracer.getTransaction()
-    let segment = shim.tracer.segment
+    let segment = shim.getSegment()
 
     // Only create a new transaction if we either do not have a current
     // transaction _or_ the current transaction is not of the type we want.
@@ -433,20 +408,15 @@ function _makeNestedTransWrapper(shim, fn, name, spec) {
  * A transaction will only be created if there is not a currently active one.
  *
  * @private
- *
  * @param {Shim} shim
  *  The shim used for the binding.
- *
- * @param {function} fn
+ * @param {Function} fn
  *  The function link with the transaction.
- *
  * @param {string} name
  *  The name of the wrapped function.
- *
  * @param {TransactionSpec} spec
  *  The spec for the transaction to create.
- *
- * @return {function} A function which wraps `fn` and potentially creates a new
+ * @returns {Function} A function which wraps `fn` and potentially creates a new
  *  transaction linked to the function's execution.
  */
 function _makeTransWrapper(shim, fn, name, spec) {

package/lib/shimmer.js

@@ -6,12 +6,15 @@
 'use strict'
 
 const path = require('path')
+const semver = require('semver')
 const fs = require('./util/unwrapped-core').fs
 const logger = require('./logger').child({ component: 'shimmer' })
 const INSTRUMENTATIONS = require('./instrumentations')()
 const properties = require('./util/properties')
 const shims = require('./shim')
 
+const NAMES = require('./metrics/names')
+
 const MODULE_TYPE = shims.constants.MODULE_TYPE
 
 const CORE_INSTRUMENTATION = {
@@ -90,9 +93,8 @@ const shimmer = (module.exports = {
   /**
    * Detects if the given function has already been wrapped.
    *
-   * @param {function} fn - The function to look for a wrapper on.
-   *
-   * @return {bool} True if `fn` exists and has an attached original, else false.
+   * @param {Function} fn - The function to look for a wrapper on.
+   * @returns {bool} True if `fn` exists and has an attached original, else false.
    */
   isWrapped: function isWrapped(fn) {
     return !!(fn && fn.__NR_original)
@@ -111,7 +113,7 @@ const shimmer = (module.exports = {
    *                            helpful than you'd think.
    * @param {string} methods One or more names of methods or functions to extract
    *                         and wrap.
-   * @param {function} wrapper A generator that, when called, returns a
+   * @param {Function} wrapper A generator that, when called, returns a
    *                           wrapped version of the original function.
    */
   wrapMethod: function wrapMethod(nodule, noduleName, methods, wrapper) {
@@ -177,8 +179,7 @@ const shimmer = (module.exports = {
    * @param {object}   noduleName Human-readable module / Class name. More
    *                              helpful than you'd think.
    * @param {string}   property   The property to replace with the accessor.
-   * @param {function} options    Optional getter and setter to use for the accessor.
-   *
+   * @param {Function} options    Optional getter and setter to use for the accessor.
    * @returns {object} The original value of the property.
    */
   wrapDeprecated: function wrapDeprecated(nodule, noduleName, property, options) {
@@ -275,6 +276,8 @@ const shimmer = (module.exports = {
   /**
    * Patch the module.load function so that we see modules loading and
    * have an opportunity to patch them with instrumentation.
+   *
+   * @param agent
    */
   patchModule: function patchModule(agent) {
     logger.trace('Wrapping module loader.')
@@ -286,7 +289,14 @@ const shimmer = (module.exports = {
         // This is triggered by the load call, so record the path that has been seen so
         // we can examine it after the load call has returned.
         const resolvedFilepath = resolve.apply(this, arguments)
-        filepathMap[file] = resolvedFilepath
+
+        // Only fire the first time we see a specific module resolved
+        if (filepathMap[file] !== resolvedFilepath) {
+          filepathMap[file] = resolvedFilepath
+
+          _onResolveFileName(agent, file, resolvedFilepath)
+        }
+
         return resolvedFilepath
       }
     })
@@ -306,6 +316,7 @@ const shimmer = (module.exports = {
      * their parent has already been loaded/cached by Node.
      * Provides a fall-back for unexpected cases that may occur.
      * Also provides flexibility for testing now that node 11+ caches these.
+     *
      * @param {*} request
      * @param {*} parent
      * @param {*} isMain
@@ -398,6 +409,10 @@ const shimmer = (module.exports = {
   },
 
   registerInstrumentation: function registerInstrumentation(opts) {
+    if (!hasValidRegisterOptions(opts)) {
+      return
+    }
+
     shimmer.registeredInstrumentations[opts.moduleName] = opts
   },
 
@@ -419,6 +434,9 @@ const shimmer = (module.exports = {
    * re-wrap them.
    *
    * Use this to re-apply any applicable instrumentation.
+   *
+   * @param agent
+   * @param modulePath
    */
   reinstrument: function reinstrument(agent, modulePath) {
     return _postLoad(agent, require(modulePath), modulePath)
@@ -428,6 +446,8 @@ const shimmer = (module.exports = {
    * Given a NodeJS module name, return the name/identifier of our
    * instrumentation.  These two things are usually, but not always,
    * the same.
+   *
+   * @param moduleName
    */
   getInstrumentationNameFromModuleName(moduleName) {
     let instrumentation
@@ -445,6 +465,14 @@ const shimmer = (module.exports = {
       instrumentation = moduleName
     }
     return instrumentation
+  },
+
+  instrumentPostLoad(agent, module, moduleName, resolvedName) {
+    const result = _postLoad(agent, module, moduleName, resolvedName)
+    // This is to not break the public API
+    // previously it would just call instrumentation
+    // and not check the result
+    return !!result.__NR_instrumented
   }
 })
 
@@ -467,8 +495,13 @@ function applyDebugState(shim, nodule) {
  * All instrumentation files must export the same interface: a single
  * initialization function that takes the agent and the module to be
  * instrumented.
+ *
+ * @param agent
+ * @param nodule
+ * @param moduleName
+ * @param resolvedName
  */
-function instrument(agent, nodule, moduleName, resolvedName) {
+function instrumentPostLoad(agent, nodule, moduleName, resolvedName) {
   const instrumentation = shimmer.registeredInstrumentations[moduleName]
   if (
     properties.hasOwn(nodule, '__NR_instrumented') ||
@@ -484,6 +517,7 @@ function instrument(agent, nodule, moduleName, resolvedName) {
   const shim = shims.createShimFromType(instrumentation.type, agent, moduleName, resolvedName)
 
   applyDebugState(shim, nodule)
+  trackInstrumentationUsage(agent, shim, moduleName, NAMES.FEATURES.INSTRUMENTATION.ON_REQUIRE)
 
   try {
     if (instrumentation.onRequire(shim, nodule, moduleName) !== false) {
@@ -536,11 +570,137 @@ function _firstPartyInstrumentation(agent, fileName, shim, nodule, moduleName) {
 function _postLoad(agent, nodule, name, resolvedName) {
   const instrumentation = shimmer.getInstrumentationNameFromModuleName(name)
 
+  const registeredInstrumentation = shimmer.registeredInstrumentations[instrumentation]
+  const hasPostLoadInstrumentation =
+    registeredInstrumentation && registeredInstrumentation.onRequire
+
   // Check if this is a known instrumentation and then run it.
-  if (shimmer.registeredInstrumentations[instrumentation]) {
-    logger.trace('Instrumenting %s.', name)
-    return instrument(agent, nodule, instrumentation, resolvedName)
+  if (hasPostLoadInstrumentation) {
+    logger.trace('Instrumenting %s with onRequire (module loaded) hook.', name)
+    return instrumentPostLoad(agent, nodule, instrumentation, resolvedName)
   }
 
   return nodule
 }
+
+function _onResolveFileName(agent, requiredNameOrPath, resolvedFilepath) {
+  const instrumentation = shimmer.getInstrumentationNameFromModuleName(requiredNameOrPath)
+
+  const registeredInstrumentation = shimmer.registeredInstrumentations[instrumentation]
+  const hasResolvedFileInstrumentation =
+    registeredInstrumentation && registeredInstrumentation.onResolved
+
+  // Check if this is a known instrumentation and then run it.
+  if (hasResolvedFileInstrumentation) {
+    logger.trace('Instrumenting %s with onResolved hook.', requiredNameOrPath)
+    _instrumentOnResolved(agent, instrumentation, resolvedFilepath)
+  }
+}
+
+/**
+ * Invokes the onResolved handler with a shim instance.
+ *
+ * Given Node.js caches resolvedFilePaths in versions we support and we cache as well
+ * for the cases we force resolution, we should not run into the case of multiple
+ * invocations for the same module. As such, this function does not defend against multiple runs.
+ *
+ * @param agent
+ * @param moduleName
+ * @param resolvedFilepath
+ */
+function _instrumentOnResolved(agent, moduleName, resolvedFilepath) {
+  const instrumentation = shimmer.registeredInstrumentations[moduleName]
+
+  const shim = shims.createShimFromType(instrumentation.type, agent, moduleName, resolvedFilepath)
+
+  trackInstrumentationUsage(agent, shim, moduleName, NAMES.FEATURES.INSTRUMENTATION.ON_RESOLVED)
+
+  try {
+    instrumentation.onResolved(shim, moduleName, resolvedFilepath)
+  } catch (instrumentationError) {
+    if (instrumentation.onError) {
+      try {
+        instrumentation.onError(instrumentationError)
+      } catch (error) {
+        logger.warn(
+          error,
+          instrumentationError,
+          'OnResolved instrumentation for %s failed, then the onError handler threw an error',
+          moduleName
+        )
+      }
+    } else {
+      logger.warn(
+        instrumentationError,
+        'OnResolved instrumentation for %s failed. Please report this to the ' +
+          'maintainers of the custom instrumentation.',
+        moduleName
+      )
+    }
+  }
+}
+
+function hasValidRegisterOptions(opts) {
+  if (!opts) {
+    logger.warn('Instrumentation registration failed, no options provided')
+    return false
+  }
+
+  if (!opts.moduleName) {
+    logger.warn(`Instrumentation registration failed, 'moduleName' not provided`)
+    return false
+  }
+
+  if (!opts.onRequire && !opts.onResolved) {
+    logger.warn(
+      'Instrumentation registration for %s failed, no require hooks provided.',
+      opts.moduleName
+    )
+
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Adds metrics to indicate instrumentation was used for a particular module and
+ * what major version the module was at, if possible.
+ *
+ * @param {*} agent The agent instance.
+ * @param {*} shim The instance of the shim used to instrument the module.
+ * @param {string} moduleName The name of the required module.
+ * @param {string} metricPrefix Support metric prefix to prepend to the metrics. Will indicate onRequire or onResolved
+ * from NAMES.FEATURES.INSTRUMENTATION.
+ */
+function trackInstrumentationUsage(agent, shim, moduleName, metricPrefix) {
+  try {
+    const version = tryGetVersion(shim)
+    const instrumentationMetricName = `${metricPrefix}/${moduleName}`
+
+    agent.metrics.getOrCreateMetric(instrumentationMetricName).incrementCallCount()
+
+    if (version) {
+      const majorVersion = semver.major(version)
+      const versionMetricName = `${instrumentationMetricName}/Version/${majorVersion}`
+
+      agent.metrics.getOrCreateMetric(versionMetricName).incrementCallCount()
+    }
+  } catch (error) {
+    logger.debug('Unable to track instrumentation usage for: ', moduleName, error)
+  }
+}
+
+function tryGetVersion(shim) {
+  // Global module (i.e. domain) or finding root failed
+  if (shim._moduleRoot === '.') {
+    return
+  }
+
+  const packageInfo = shim.require('./package.json')
+  if (!packageInfo) {
+    return
+  }
+
+  return packageInfo.version
+}

package/lib/transaction/tracer/index.js

@@ -16,13 +16,13 @@ const SEGMENT = '__NR_segment'
 
 module.exports = Tracer
 
-function Tracer(agent) {
+function Tracer(agent, contextManager) {
   if (!agent) {
     throw new Error('Must be initialized with an agent.')
   }
 
   this.agent = agent
-  this._segment = null
+  this._contextManager = contextManager
 }
 
 Tracer.prototype.getTransaction = getTransaction
@@ -45,35 +45,28 @@ Tracer.prototype.wrapFunctionFirst = wrapFunctionFirst
 Tracer.prototype.wrapSyncFunction = wrapSyncFunction
 Tracer.prototype.wrapCallback = wrapCallback
 
-Object.defineProperty(Tracer.prototype, 'segment', {
-  get: function segmentGetter() {
-    return this._segment
-  },
-  set: function segmentSetter(segment) {
-    this._segment && this._segment.probe('Segment removed from tracer')
-    segment && segment.probe('Set tracer.segment')
-    return (this._segment = segment)
-  }
-})
-
 function getTransaction() {
-  if (this.segment && this.segment.transaction && this.segment.transaction.isActive()) {
-    return this.segment.transaction
+  const currentSegment = this._contextManager.getContext()
+  if (currentSegment && currentSegment.transaction && currentSegment.transaction.isActive()) {
+    return currentSegment.transaction
   }
 
   return null
 }
 
+// TODO: Remove/replace external uses to tracer.getSegment()
 function getSegment() {
-  return this.segment
+  return this._contextManager.getContext()
 }
 
+// TODO: Remove/replace external uses to tracer.getSpanContext()
 function getSpanContext() {
-  return this.segment && this.segment.getSpanContext()
+  const currentSegment = this.getSegment()
+  return currentSegment && currentSegment.getSpanContext()
 }
 
 function createSegment(name, recorder, _parent) {
-  const parent = _parent || this.segment
+  const parent = _parent || this.getSegment()
   if (!parent || !parent.transaction.isActive()) {
     logger.trace(
       {
@@ -111,7 +104,7 @@ function transactionProxy(handler) {
     }
 
     // don't nest transactions, reuse existing ones
-    const segment = tracer.segment
+    const segment = tracer.getSegment()
     if (segment) {
       if (segment.transaction.traceStacks) {
         segment.probe('!!! Nested transaction creation !!!')
@@ -143,9 +136,9 @@ function transactionProxy(handler) {
  * if there is an in play segment and uses that as the root instead of
  * transaction.trace.root.
  *
- * @param {Function} handler - Generator to be proxied.
- *
- * @return {Function} Proxy.
+ * @param {string} type - Type of transaction to create. 'web' or 'bg'.
+ * @param {Function} handler - Generator to proxy.
+ * @returns {Function} Proxy.
  */
 function transactionNestProxy(type, handler) {
   if (handler === undefined && typeof type === 'function') {
@@ -165,7 +158,7 @@ function transactionNestProxy(type, handler) {
 
     // don't nest transactions, reuse existing ones
     let transaction = tracer.getTransaction()
-    let segment = tracer.segment
+    let segment = tracer.getSegment()
 
     let createNew = false
 
@@ -192,7 +185,7 @@ function bindFunction(handler, segment, full) {
     return handler
   }
 
-  return _makeWrapped(this, handler, segment || this.segment, !!full)
+  return _makeWrapped(this, handler, segment || this.getSegment(), !!full)
 }
 function _makeWrapped(tracer, handler, active, full) {
   wrapped[ORIGINAL] = getOriginal(handler)
@@ -201,18 +194,19 @@ function _makeWrapped(tracer, handler, active, full) {
   return wrapped
 
   function wrapped() {
-    const prev = tracer.segment
-    tracer.segment = active
+    const prev = tracer.getSegment()
+
     if (active && full) {
       active.start()
     }
+
     try {
-      return handler.apply(this, arguments)
+      return tracer._contextManager.runInContext(active, handler, this, arguments)
     } catch (err) {
       logger.trace(err, 'Error from wrapped function:')
 
       if (prev === null && process.domain != null) {
-        process.domain.__NR_transactionSegment = tracer.segment
+        process.domain.__NR_transactionSegment = tracer.getSegment()
       }
 
       throw err // Re-throwing application error, this is not an agent error.
@@ -220,7 +214,6 @@ function _makeWrapped(tracer, handler, active, full) {
       if (active && full) {
         active.touch()
       }
-      tracer.segment = prev
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "newrelic",
-  "version": "8.5.0",
+  "version": "8.7.0",
   "author": "New Relic Node.js agent team <nodejs@newrelic.com>",
   "license": "Apache-2.0",
   "contributors": [
@@ -148,9 +148,11 @@
     "update-cross-agent-tests": "./bin/update-cats.sh",
     "versioned-tests": "./bin/run-versioned-tests.sh",
     "update-changelog-version": "node ./bin/update-changelog-version",
+    "checkout-external-versioned": "node ./test/versioned-external/checkout-external-tests.js",
     "versioned": "npm run versioned:npm7",
-    "versioned:npm6": "npm run prepare-test && time ./bin/run-versioned-tests.sh",
-    "versioned:npm7": "npm run prepare-test && NPM7=1 time ./bin/run-versioned-tests.sh",
+    "versioned:major": "npm run checkout-external-versioned && npm run prepare-test && VERSIONED_MODE=--major NPM7=1 time ./bin/run-versioned-tests.sh",
+    "versioned:npm6": "npm run checkout-external-versioned && npm run prepare-test && time ./bin/run-versioned-tests.sh",
+    "versioned:npm7": "npm run checkout-external-versioned && npm run prepare-test && NPM7=1 time ./bin/run-versioned-tests.sh",
     "prepare": "husky install"
   },
   "bin": {
@@ -177,8 +179,9 @@
     "@newrelic/eslint-config": "^0.0.3",
     "@newrelic/newrelic-oss-cli": "^0.1.2",
     "@newrelic/proxy": "^2.0.0",
-    "@newrelic/test-utilities": "^6.0.0",
+    "@newrelic/test-utilities": "^6.1.1",
     "@octokit/rest": "^18.0.15",
+    "@slack/bolt": "^3.7.0",
     "ajv": "^6.12.6",
     "architect": "*",
     "benchmark": "^2.1.4",