newrelic 13.3.3 → 13.5.0

package/lib/{adaptive-sampler.js → samplers/adaptive-sampler.js}

@@ -6,6 +6,14 @@
 'use strict'
 
 class AdaptiveSampler {
+  /**
+   *
+   * @param {object} opts Sampler options.
+   * @param {Agent} opts.agent - The New Relic agent instance.
+   * @param {number} opts.period - The time period over which to collect samples (ms).
+   * @param {number} opts.target - The target number of samples (transactions) to collect.
+   * @param {boolean} opts.serverless - Indicates if the environment is serverless.
+   */
   constructor(opts) {
     this._serverless = opts.serverless
     this._seen = 0

package/lib/serverless/aws-lambda.js

@@ -105,8 +105,8 @@ class AwsLambda {
   /**
    * Response-streaming handlers are identified by symbol properties on the function.
    * We propagate any symbols if they're present, so that the handler keeps its signatue for any AWS features that rely on symbols
-   * @param handler
-   * @param nrHandler
+   * @param {object} handler original handler
+   * @param {object} nrHandler our copy of the handler
    */
   propagateSymbols(handler, nrHandler) {
     for (const symbol of Object.getOwnPropertySymbols(handler)) {
@@ -191,7 +191,7 @@ class AwsLambda {
      * **Note**: AWS doesn't support response streaming with API gateway invoked lambdas.
      * This means we do not handle that as it would require intercepting the stream to parse
      * the response code and headers.
-     * @param {...any} args
+     * @param {...any} args Original arguments
      */
     function wrappedStreamHandler(...args) {
       const transaction = shim.tracer.getTransaction()
@@ -229,7 +229,7 @@ class AwsLambda {
      * adds handlers if api gateway to wrap request/response
      * wraps the callback(if present), wraps the context `done`, `succeed`, `fail methods`, intercepts promise
      * and properly ends transaction
-     * @param {...any} args
+     * @param {...any} args Original arguments
      */
     function wrappedHandler(...args) {
       const transaction = shim.tracer.getTransaction()

package/lib/shim/datastore-shim.js

@@ -500,7 +500,7 @@ function captureInstanceAttributes(host, port, database) {
 /**
  * Parses the database name from a `USE` SQL query.
  *
- * @memberof DatastoreShim.prototype
+ * @this DatastoreShim
  * @param {string} query - The SQL query to parse the database name from.
  * @returns {?string} The name of the database if it could be parsed, otherwise
  *  `null`.
@@ -584,7 +584,7 @@ function _recordQuery(suffix, nodule, properties, querySpec) {
  * @param {object} params to function
  * @param {QuerySpec|OperationSpec} params.spec spec for the given shim method
  * @param {DatastoreShim} params.shim instance of shim
- * @param {function} params.fn function being instrumented
+ * @param {Function} params.fn function being instrumented
  * @param {string} params.fnName name of function being instrumented
  * @param {Array} params.args arguments to function being instrumented
  * @returns {QuerySpec|OperationSpec} compiled spec

package/lib/shim/message-shim/consume.js

@@ -19,9 +19,9 @@ module.exports = createRecorder
  * @param {Function} params.fn consumer function
  * @param {string} params.fnName name of function
  * @param {Array} params.args arguments passed to original consume function
- * @param {Object} params.ctx this binding of the original function
- * @param {specs.MessageSpec} params.spec spec for the wrapped consume function
- * @returns {specs.MessageSpec} new spec
+ * @param {object} params.ctx this binding of the original function
+ * @param {MessageSpec} params.spec spec for the wrapped consume function
+ * @returns {MessageSpec} new spec
  */
 function updateSpecFromArgs({ shim, fn, fnName, args, spec, ctx }) {
   let msgDesc = null
@@ -49,7 +49,7 @@ function updateSpecFromArgs({ shim, fn, fnName, args, spec, ctx }) {
  * @param {MessageShim} params.shim instance of shim
  * @param {Function} params.fn function that is being wrapped
  * @param {string} params.fnName name of function
- * @param params.args
+ * @param {Array} params.args arguments passed to original consume function
  * @param {specs.MessageSpec} params.spec spec for the wrapped consume function
  * @returns {specs.MessageSpec} updated spec with logic to name segment and apply the genericRecorder
  */

package/lib/shim/message-shim/subscribe-consume.js

@@ -37,8 +37,7 @@ function _nameMessageTransaction(shim, msgDesc) {
  * @param {MessageShim} params.shim instance of shim
  * @param {Function} params.fn subscriber function
  * @param {specs.MessageSubscribeSpec} params.spec spec for subscriber
- * @param params.name
- * @param {boolean} params.destNameIsArg flag to state if destination is an argument
+ * @param {string} params.name function name
  * @returns {Function} wrapped subscribe function
  */
 function createSubscriberWrapper({ shim, fn, spec, name }) {

package/lib/shim/promise-shim.js

@@ -366,9 +366,7 @@ function _wrapExecutorContext(shim, args) {
 
   /**
    *
-   * @param {Function} resolve function of promise
-   * @param {Function} reject function of promise
-   * @param {...any} args
+   * @param {object} args contains the `resolve` and `reject` functions of a promise
    */
   function contextExporter(...args) {
     const [resolve, reject] = args
@@ -384,7 +382,6 @@ function _wrapExecutorContext(shim, args) {
  * @param {object} context context object
  * @param {Function} fn function that is wrapped
  * @returns {Function} wrapped function
- * @private
  */
 function _wrapResolver(context, fn) {
   return function wrappedResolveReject(val) {

package/lib/shim/shim.js

@@ -242,12 +242,12 @@ Shim.prototype[symbols.unwrap] = unwrapAll
  */
 
 /**
+ * Measures all the necessary metrics for the given segment. This functionality
+ * is meant to be used by Shim subclasses; instrumentations should never create
+ * their own recorders.
+ *
  * @private
  * @callback MetricFunction
- * @summary
- *  Measures all the necessary metrics for the given segment. This functionality
- *  is meant to be used by Shim subclasses, instrumentations should never create
- *  their own recorders.
  * @param {TraceSegment}  segment - The segment to record.
  * @param {string}        [scope] - The scope of the recording.
  */
@@ -1075,7 +1075,7 @@ function bindCallbackSegment(spec, args, cbIdx, parentSegment) {
  * It will also call an after hook with the arguments passed to callback
  *
  * @private
- * @param {Object} params to function
+ * @param {object} params to function
  * @param {Shim} params.shim instance of shim
  * @param {Array | object} params.args
  *  The arguments array to pull the cb from.
@@ -1239,7 +1239,7 @@ function applyContext({ func, context, full, boundThis, args, inContextCB }) {
   this.logger.trace('Applying segment %s', segment.name)
 
   /**
-   *
+   * Callback to be run in the context of the segment.
    */
   function runInContextCb() {
     if (typeof inContextCB === 'function') {
@@ -1453,8 +1453,7 @@ function isPromise(obj) {
  * promise or async function
  *
  * @memberof Shim.prototype
- * @param fn
- * @param (function) function to test if async
+ * @param {Function} fn function to test if async
  * @returns {boolean} True if the function is an async function
  */
 function isAsyncFunction(fn) {
@@ -1871,8 +1870,8 @@ function _makeBindWrapper(shim, func, context, full) {
  * (i.e. `bindRowCallbackSegment` for `rowCallback`), but will fall back to the
  * generic callback binding method, `bindCallbackSegment`, otherwise.
  *
- * @this *
  * @private
+ * @this *
  * @param {Shim} shim
  *  The shim performing this binding.
  * @param {Function} fn
@@ -2129,7 +2128,7 @@ function _es5WrapClass(shim, Base, fnName, spec, args) {
   /**
    * Wraps the es5 class in a function
    *
-   * @param {...any} cnstrctArgs
+   * @param {...any} cnstrctArgs class constructor arguments
    * @returns {Function|undefined} a function if not already wrapped in WrappedClass
    */
   function WrappedClass(...cnstrctArgs) {
@@ -2162,28 +2161,14 @@ function _es5WrapClass(shim, Base, fnName, spec, args) {
 }
 
 /**
- * Method for prefixing Route (aka URL) parameters with `request.parameters.route`
- *
- * Many web frameworks support adding parameters to routes when defining your API structure, and this function
- * updates those parameters names to be prefixed by `request.parameters.route`. This is to avoid collision with reserved
- * attribute names, as parameters used to be blindly stored on router span attributes (see https://github.com/newrelic/node-newrelic/issues/1574)
- * in addition to being prefixed by `request.parameters`.
- *
- * Route parameters used to be stored under `request.parameters.*` just like query parameters pre v10, but we
- * now prefix with `request.parameter.route` to avoid collision in the event an application uses the same name for a query and route
- * parameter. Additionally, we now store the same key on the attributes of the base segment, trace, and router span.
- *
- * Exported on shim to be used in our Next.js instrumentation, as that instrumentation does not follow the same pattern as all the other
- * web frameworks we support.
+ * This method is no longer in use. It still exists to avoid crashing
+ * applications.  The logic of this method has been integrated into
+ * finalizing a web transaction.
  *
  * @param {object} params - Object containing route/url parameter key/value pairs
- * @returns {object|undefined} the updated object, `key` will now be `request.parameters.route.key`, value remains untouched
+ * @returns {void} method is now stubbed and logic ported into `finalizeWebTransaction`
  * @memberof Shim.prototype
  */
 function prefixRouteParameters(params) {
-  if (params && isObject(params)) {
-    return Object.fromEntries(
-      Object.entries(params).map(([key, value]) => [`request.parameters.route.${key}`, value])
-    )
-  }
+  logger.warnOnce('shim.prefixRouteParameters logic has been moved to when a web transaction ends.  This method will be removed in the next upcoming major version v14.0.0.')
 }

package/lib/shim/specs/class.js

@@ -12,14 +12,14 @@ const WrapSpec = require('./wrap')
  * @typedef {object} ClassWrapSpecParams
  * @mixes WrapSpecParams
  * @property {boolean} [es6]
- * @property {function} [pre]
- * @property {function} [post]
+ * @property {Function} [pre]
+ * @property {Function} [post]
  */
 
 /**
  * Pre/post constructor execution hook for wrapping classes.
  *
- * @typedef {function} ConstructorHookFunction
+ * @typedef {Function} ConstructorHookFunction
  * @param {Shim} shim
  *  The shim performing the wrapping/binding.
  * @param {Function} Base

package/lib/shim/specs/middleware-mounter.js

@@ -11,7 +11,7 @@ const MiddlewareSpec = require('./middleware')
  * Called whenever new middleware are mounted using the instrumented framework,
  * this method should pull out a representation of the mounted path.
  *
- * @typedef {function} RouteParserFunction
+ * @typedef {Function} RouteParserFunction
  * @param {WebFrameworkShim} shim
  *  The shim in use for this instrumentation.
  * @param {Function} fn
@@ -27,7 +27,7 @@ const MiddlewareSpec = require('./middleware')
  * Called for each middleware passed to a mounting method. Should perform the
  * wrapping of the middleware.
  *
- * @typedef {function} MiddlewareWrapperFunction
+ * @typedef {Function} MiddlewareWrapperFunction
  * @param {WebFrameworkShim} shim
  *  The shim used for instrumentation.
  * @param {Function} middleware

package/lib/shim/specs/middleware.js

@@ -11,7 +11,7 @@ const RecorderSpec = require('./recorder')
 /**
  * Extracts the request object from the arguments to the middleware function.
  *
- * @typedef {function} RouteRequestFunction
+ * @typedef {Function} RouteRequestFunction
  * @param {WebFrameworkShim} shim The shim used for instrumentation.
  * @param {Function} fn The middleware function.
  * @param {string} fnName The name of the middleware function.
@@ -23,7 +23,7 @@ const RecorderSpec = require('./recorder')
  * Used to wrap functions that users can call to continue to the next
  * middleware.
  *
- * @typedef {function} RouteNextFunction
+ * @typedef {Function} RouteNextFunction
  * @param {WebFrameworkShim} shim The shim used for instrumentation.
  * @param {Function} fn The middleware function.
  * @param {string} fnName The name of the middleware function.
@@ -34,7 +34,7 @@ const RecorderSpec = require('./recorder')
 /**
  * Extracts the route parameters from the arguments to the middleware function.
  *
- * @typedef {function} RouteParameterFunction
+ * @typedef {Function} RouteParameterFunction
  * @param {WebFrameworkShim} shim The shim used for instrumentation.
  * @param {Function} fn The middleware function.
  * @param {string} fnName The name of the middleware function.

package/lib/shim/specs/query.js

@@ -10,7 +10,7 @@ const OperationSpec = require('./operation')
 /**
  * Retrieves the query argument from an array of arguments.
  *
- * @typedef {function} QueryFunction
+ * @typedef {Function} QueryFunction
  * @param {Shim} shim The shim this function was passed to.
  * @param {Function} func The function being recorded.
  * @param {string} name The name of the function.

package/lib/shim/specs/recorder.js

@@ -24,7 +24,7 @@ const WrapSpec = require('./wrap')
  * The instrumented function must have been invoked synchronously.
  *
  * @typedef {Function} SpecAfterFunction
- * @param {Object} params params to function
+ * @param {object} params params to function
  * @param {object} params.shim The shim used to instrument the external library.
  * @param {Function} params.fn The function/method from the external library being
  * instrumented.

package/lib/shim/specs/wrap.js

@@ -12,7 +12,7 @@ const SegmentSpec = require('./segment')
  * @typedef {object} WrapSpecParams
  * @mixes SegmentSpecParams
  * @property {boolean} [matchArity]
- * @property {function} [wrapper]
+ * @property {Function} [wrapper]
  */
 
 /**
@@ -40,7 +40,7 @@ class WrapSpec extends SegmentSpec {
   /**
    * A function that wraps another function.
    *
-   * @type {function}
+   * @type {Function}
    */
   wrapper
 

package/lib/shim/transaction-shim.js

@@ -19,7 +19,6 @@ const TRANSACTION_TYPES_SET = Transaction.TYPES_SET
  * @class
  * @augments Shim
  * @classdesc
- * @param shimName
  *  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.

package/lib/shim/webframework-shim/common.js

@@ -46,8 +46,6 @@ common.getTransactionInfo = function getTransactionInfo(shim, req) {
  * 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
@@ -73,8 +71,8 @@ common.isError = function isError(shim, err) {
 }
 
 /**
- * @param shim
- * @param req
+ * @param {object} shim instance
+ * @param {object} req request
  */
 common.makeGetReq = function makeGetReq(shim, req) {
   return function getReqFromArgs(shim, fn, name, args) {

package/lib/shim/webframework-shim/index.js

@@ -339,12 +339,21 @@ function savePossibleTransactionName(req) {
   }
 }
 
+/**
+ * Predicate used to determine whether a middleware invocation constitutes a response.
+ *
+ * @typedef {Function} ResponsePredicate
+ * @param {object[]} args - The arguments passed into the middleware.
+ * @param {object} res - The value returned from the middleware (if any).
+ * @returns {boolean} True if the invocation should be considered a response.
+ */
+
 /**
  * Sets a function to call with the result of a middleware to determine if it has
  * responded.
  *
  * @memberof WebFrameworkShim.prototype
- * @param {function(args, object): boolean} pred
+ * @param {ResponsePredicate} pred
  *  Function which should return true if the object passed to it is considered
  *  a response.
  */

package/lib/shim/webframework-shim/middleware.js

@@ -51,8 +51,10 @@ function getRoute(spec, shim) {
 }
 
 /**
- * Retrieves the parameters from the spec.params
- * and prefixes them all with `request.parameters.route`
+ * Retrieves the parameters from the spec.params.
+ * When a `transaction.finalizeNameFromWeb` is called, it takes these params
+ * and prefixes `request.parameters.route.` to every route param.
+ * Query params are handled in lib/transaction/index.js#initializeWeb
  *
  * @private
  * @param {object} params object passed to fn
@@ -66,12 +68,9 @@ function getRoute(spec, shim) {
  */
 function copyParams({ spec, shim, fn, fnName, args, req }) {
   // Copy over route parameters onto the transaction root.
-  const params = shim.agent.config.high_security
+  return shim.agent.config.high_security
     ? null
     : spec.params.call(this, shim, fn, fnName, args, req)
-
-  // Route parameters are handled here, query parameters are handled in lib/transaction/index.js#finalizeNameFromWeb as part of finalization
-  return shim.prefixRouteParameters(params)
 }
 
 /**
@@ -81,15 +80,14 @@ function copyParams({ spec, shim, fn, fnName, args, req }) {
  * @param {object} params object passed to fn
  * @param {object} params.txInfo transaction
  * @param {object} params.typeDetails metadata about the middleware type
- * @param {Shim} params.shim instance of shim
  * @param {string} params.metricName metric name for middleware function
  * @returns {Function} recorder for middleware type
  */
-function constructRecorder({ txInfo, typeDetails, shim, metricName }) {
+function constructRecorder({ txInfo, typeDetails, metricName }) {
   let recorder = null
   if (typeDetails.record) {
     const stackPath = txInfo.transaction.nameState.getPath() || ''
-    recorder = makeMiddlewareRecorder(shim, metricName + '/' + stackPath)
+    recorder = makeMiddlewareRecorder(metricName + '/' + stackPath)
   }
   return recorder
 }
@@ -166,7 +164,7 @@ function middlewareWithCallbackRecorder({ spec, typeDetails, metricName, isError
       txInfo.transaction.nameState.appendPath(route, params)
     }
 
-    const recorder = constructRecorder({ txInfo, typeDetails, shim, metricName })
+    const recorder = constructRecorder({ txInfo, typeDetails, metricName })
 
     const segmentName = getSegmentName(metricName, typeDetails, route)
 
@@ -176,7 +174,6 @@ function middlewareWithCallbackRecorder({ spec, typeDetails, metricName, isError
       callback: nextWrapper,
       parent: txInfo.segmentStack[txInfo.segmentStack.length - 1],
       recorder,
-      parameters: params,
       after: function afterExec({ shim, error }) {
         const errIsError = isError(shim, error)
         if (errIsError) {
@@ -224,7 +221,7 @@ function middlewareWithPromiseRecorder({ spec, typeDetails, metricName, isErrorW
       txInfo.transaction.nameState.appendPath(route, params)
     }
 
-    const recorder = constructRecorder({ txInfo, typeDetails, shim, metricName })
+    const recorder = constructRecorder({ txInfo, typeDetails, metricName })
     const nextWrapper = wrapNextHandler({
       shim,
       spec,
@@ -243,7 +240,6 @@ function middlewareWithPromiseRecorder({ spec, typeDetails, metricName, isErrorW
       promise: spec.promise,
       callback: nextWrapper,
       recorder,
-      parameters: params,
       after: function afterExec({ shim, error, result }) {
         if (shim._responsePredicate(args, result)) {
           txInfo.transaction.nameState.freeze()
@@ -331,14 +327,14 @@ module.exports._recordMiddleware = function _recordMiddleware(shim, middleware,
  * push the name state if there is a next so that we can safely remove it
  * if context leaves this middleware.
  *
- * @param root0
- * @param root0.shim
- * @param root0.spec
- * @param root0.route
- * @param root0.args
- * @param root0.isErrorWare
- * @param root0.isPromise
- * @param root0.txInfo
+ * @param {object} params params object
+ * @param {Shim} params.shim shim instance
+ * @param {object} params.spec middleware spec, should contain a next function
+ * @param {string} params.route route
+ * @param {Array} params.args arguments
+ * @param {boolean} params.isErrorWare is this error ware
+ * @param {boolean} params.isPromise is this a promise
+ * @param {object} params.txInfo transaction information
  * @private
  */
 function wrapNextHandler({ shim, spec, route, args, isErrorWare, isPromise, txInfo }) {