newrelic 8.5.2 → 8.6.0

package/lib/shim/shim.js

@@ -20,10 +20,8 @@ const fnApply = Function.prototype.apply
 /**
  * Constructs a shim associated with the given agent instance.
  *
- * @constructor
- * @classdesc
- *  A helper class for wrapping modules with segments.
- *
+ * @class
+ * @classdesc A helper class for wrapping modules with segments.
  * @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.
@@ -35,6 +33,7 @@ function Shim(agent, moduleName, resolvedName) {
 
   this._logger = logger.child({ module: moduleName })
   this._agent = agent
+  this._contextManager = agent._contextManager
   this._toExport = null
   this._debug = false
   this.defineProperty(this, 'moduleName', moduleName)
@@ -68,6 +67,7 @@ defineProperties(Shim.prototype, {
    *
    * @readonly
    * @member {Agent} Shim.prototype.agent
+   * @returns {Agent} The instance of the agent.
    */
   agent: function getAgent() {
     return this._agent
@@ -78,6 +78,7 @@ defineProperties(Shim.prototype, {
    *
    * @readonly
    * @member {Tracer} Shim.prototype.tracer
+   * @returns {Tracer} The instance of the tracer
    */
   tracer: function getTracer() {
     return this._agent.tracer
@@ -88,6 +89,7 @@ defineProperties(Shim.prototype, {
    *
    * @readonly
    * @member {Logger} Shim.prototype.logger
+   * @returns {Logger} The logger.
    */
   logger: function getLogger() {
     return this._logger
@@ -148,37 +150,28 @@ Shim.prototype.__NR_unwrap = unwrapAll
 
 /**
  * @callback WrapFunction
- *
  * @summary
  *  A function which performs the actual wrapping logic.
- *
  * @description
  *  If the return value of this function is not `original` then the return value
  *  will be marked as a wrapper.
- *
  * @param {Shim} shim
  *  The shim this function was passed to.
- *
- * @param {Object|Function} original
+ * @param {object|Function} original
  *  The item which needs wrapping. Most of the time this will be a function.
- *
  * @param {string} name
  *  The name of `original` if it can be determined, otherwise `'<anonymous>'`.
- *
- * @return {*} The wrapper for the original, or the original value itself.
+ * @returns {*} The wrapper for the original, or the original value itself.
  */
 
 /**
  * @private
  * @callback ArrayWrapFunction
- *
  * @description
  *   A wrap function used on elements of an array. In addition to the parameters
  *   of `WrapFunction`, these also receive an `index` and `total` as described
  *   below.
- *
  * @see WrapFunction
- *
  * @param {number} index - The index of the current element in the array.
  * @param {number} total - The total number of items in the array.
  */
@@ -186,81 +179,59 @@ Shim.prototype.__NR_unwrap = unwrapAll
 /**
  * @private
  * @callback ArgumentsFunction
- *
  * @param {Shim} shim
  *  The shim this function was passed to.
- *
  * @param {Function} func
  *  The function these arguments were passed to.
- *
  * @param {*} context
  *  The context the function is executing under (i.e. `this`).
- *
  * @param {Array.<*>} args
  *  The arguments being passed into the function.
  */
 
 /**
  * @callback SegmentFunction
- *
  * @summary
  *  A function which is called to compose a segment.
- *
  * @param {Shim} shim
  *  The shim this function was passed to.
- *
  * @param {Function} func
  *  The function the segment is created for.
- *
  * @param {string} name
  *  The name of the function.
- *
  * @param {Array.<*>} args
  *  The arguments being passed into the function.
- *
- * @return {string|SegmentSpec} The desired properties for the new segment.
+ * @returns {string|SegmentSpec} The desired properties for the new segment.
  */
 
 /**
  * @callback RecorderFunction
- *
  * @summary
  *  A function which is called to compose a segment for recording.
- *
  * @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.
- *
  * @param {Array.<*>} args
  *  The arguments being passed into the function.
- *
- * @return {string|RecorderSpec} The desired properties for the new segment.
+ * @returns {string|RecorderSpec} The desired properties for the new segment.
  */
 
 /**
  * @callback CallbackBindFunction
- *
  * @summary
  *  Performs segment binding on a callback function. Useful when identifying a
  *  callback is more complex than a simple argument offset.
- *
  * @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.
- *
  * @param {TraceSegment} segment
  *  The segment that the callback should be bound to.
- *
  * @param {Array.<*>} args
  *  The arguments being passed into the function.
  */
@@ -268,47 +239,37 @@ Shim.prototype.__NR_unwrap = unwrapAll
 /**
  * @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.
  */
 
 /**
  * @callback ConstructorHookFunction
- *
  * @summary
  *  Pre/post constructor execution hook for wrapping classes. Used by
  *  {@link ClassWrapSpec}.
- *
  * @param {Shim} shim
  *  The shim performing the wrapping/binding.
- *
  * @param {Function} Base
  *  The class that was wrapped.
- *
  * @param {string} name
  *  The name of the `Base` class.
- *
  * @param {Array.<*>} args
  *  The arguments to the class constructor.
- *
  * @see ClassWrapSpec
  */
 
 /**
  * @private
  * @interface Spec
- *
  * @description
  *  The syntax for declarative instrumentation. It can be used interlaced with
  *  custom, hand-written instrumentation for one-off or hard to simplify
  *  instrumentation logic.
- *
  * @property {Spec|WrapFunction} $return
  *  Changes the context to the return value of the current context. This means
  *  the sub spec will not be executed up front, but instead upon every execution
@@ -318,7 +279,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *  var ret = func.apply(this, args);
  *  return shim.wrap(ret, spec.$return)
  *  ```
- *
  * @property {Spec|WrapFunction} $proto
  *  Changes the context to the prototype of the current context. The prototype
  *  is found using `Object.getPrototypeOf`.
@@ -326,7 +286,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *  ```js
  *  shim.wrap(Object.getPrototypeOf(context), spec.$proto)
  *  ```
- *
  * @property {bool} $once
  *  Ensures that the parent spec will only be executed one time if the value is
  *  `true`. Good for preventing double wrapping of prototype methods.
@@ -337,7 +296,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *  }
  *  spec.__NR_onceExecuted = true
  *  ```
- *
  * @property {ArgumentsFunction} $arguments
  *  Executes the function with all of the arguments passed in. The arguments can
  *  be modified in place. This will execute before `$eachArgument`.
@@ -345,7 +303,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *  ```js
  *  spec.$arguments(args)
  *  ```
- *
  * @property {Spec|ArrayWrapFunction} $eachArgument
  *  Executes `shim.wrap` on each argument passed to the current context. The
  *  returned arguments will then be used to actually execute the function.
@@ -361,7 +318,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *  }
  *  func.apply(this, args)
  *  ```
- *
  * @property {Array.<{$properties: Array.<string>, $spec: Spec}>} $wrappings
  *  Executes `shim.wrap` with the current context as the `nodule` for each
  *  element in the array. The `$properties` sub-key must list one or more
@@ -373,7 +329,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *    shim.wrap(context, $wrap.$properties, $wrap.$spec)
  *  })
  *  ```
- *
  * @property {bool|string|SegmentFunction} $segment
  *  Controls segment creation. If a falsey value (i.e. `undefined`, `false`,
  *  `null`, etc) then no segment will be created. If the value is `true`, then
@@ -395,8 +350,7 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *    segment = shim.createSegment(seg.name, seg.recorder, seg.parent)
  *  }
  *  ```
- *
- * @property {Object.<string, *>} $cache
+ * @property {object.<string, *>} $cache
  *  Adds the value as an extra parameter to all specs in the same context as the
  *  cache. If the current context is a function, the cache will be recreated on
  *  each invocation of the function. This value can be useful for passing a
@@ -408,7 +362,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *    args.push({})
  *  }
  *  ```
- *
  * @property {number} $callback
  *  Indicates that one of the parameters is a callback which should be wrapped.
  *
@@ -421,7 +374,6 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *    args[idx] = shim.bindSegment(args[idx], segment)
  *  }
  *  ```
- *
  * @property {Spec|WrapFunction} property
  *  Any field which does not start with a `$` is assumed to name a property on
  *  the current context which should be wrapped. This is simply shorthand for a
@@ -430,56 +382,45 @@ Shim.prototype.__NR_unwrap = unwrapAll
 
 /**
  * @interface SegmentSpec
- *
  * @description
  *  The return value from a {@link SegmentFunction}, used to set the parameters
  *  of segment creation.
- *
  * @property {string} name
  *  The name for the segment to-be.
- *
  * @property {MetricFunction} [recorder]
  *  A metric recorder for the segment. This is purely for internal use by shim
  *  classes. Instrumentations should never implement their own metric functions.
- *
  * @property {TraceSegment} [parent]
  *  The parent segment. Defaults to the currently active segment.
- *
  * @see RecorderSpec
  * @see SegmentFunction
  */
 
 /**
  * @interface RecorderSpec
- * @extends SegmentSpec
- *
+ * @augments SegmentSpec
  * @description
  *  The return value from a {@link RecorderFunction}, used to set the parameters
  *  of segment creation and lifetime. Extends the {@link SegmentSpec}.
- *
  * @property {bool|string} [stream]
  *  Indicates if the return value from the wrapped function is a stream. If the
  *  value is truthy then the recording will extend to the `end` event of the
  *  stream. If the value is a string it is assumed to be the name of an event to
  *  measure. A segment will be created to record emissions of the event.
- *
  * @property {bool} [promise]
  *  Indicates if the return value from the wrapped function is a Promise. If the
  *  value is truthy then the recording will extend to the completion of the
  *  Promise.
- *
  * @property {number|CallbackBindFunction} [callback]
  *  If this is a number, it identifies which argument is the callback and the
  *  segment will also be bound to the callback. Otherwise, the passed function
  *  should perform the segment binding itself.
- *
  * @property {number|CallbackBindFunction} [rowCallback]
  *  Like `callback`, this identifies a callback function in the arguments. The
  *  difference is that the default behavior for row callbacks is to only create
  *  one segment for all calls to the callback. This is mostly useful for
  *  functions which will be called repeatedly, such as once for each item in a
  *  result set.
- *
  * @property {bool} [internal=false]
  *  Marks this as the boundary point into the instrumented library. If `true`
  *  and the current segment is _also_ marked as `internal` by the same shim,
@@ -489,36 +430,29 @@ Shim.prototype.__NR_unwrap = unwrapAll
  *  methods which simply call other public methods and you only want to record
  *  the method directly called by the user while still instrumenting all
  *  endpoints.
- *
- * @property {function} [after=null]
+ * @property {Function} [after=null]
  *  A function to call after the synchronous execution of the recorded method.
  *  If the function synchronously threw an error, that error will be handed to
  *  this function.
- *
  * @property {bool} [callbackRequired]
  *  When `true`, a recorded method must be called with a callback for a segment
  *  to be created. Does not apply if a custom callback method has been assigned
  *  via {@link callback}.
- *
  * @see SegmentSpec
  * @see RecorderFunction
  */
 
 /**
  * @interface ClassWrapSpec
- *
  * @description
  *  Specifies the style of wrapping and construction hooks for wrapping classes.
- *
  * @property {bool} [es6=false]
  * @property {ConstructorHookFunction} [pre=null]
  *  A function called with the constructor's arguments before the base class'
  *  constructor is executed. The `this` value will be `null`.
- *
  * @property {ConstructorHookFunction} [post=null]
  *  A function called with the constructor's arguments after the base class'
  *  constructor is executed. The `this` value will be the just-constructed object.
- *
  */
 
 // -------------------------------------------------------------------------- //
@@ -526,6 +460,8 @@ Shim.prototype.__NR_unwrap = unwrapAll
 /**
  * Entry point for executing a spec.
  *
+ * @param nodule
+ * @param spec
  * @memberof Shim.prototype
  */
 function execute(nodule, spec) {
@@ -553,23 +489,17 @@ function execute(nodule, spec) {
  * method.
  *
  * @memberof Shim.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 {Spec|WrapFunction} spec
  *  The spec for wrapping these items.
- *
  * @param {Array.<*>} [args=[]]
  *  Optional extra arguments to be sent to the spec when executing it.
- *
- * @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 WrapFunction
  */
 function wrap(nodule, properties, spec, args) {
@@ -644,23 +574,17 @@ function wrap(nodule, properties, spec, args) {
  * constructors instead.
  *
  * @memberof Shim.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 {Spec|WrapReturnFunction} spec
  *  The spec for wrapping the returned value from the properties.
- *
  * @param {Array.<*>} [args=[]]
  *  Optional extra arguments to be sent to the spec when executing it.
- *
- * @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 Shim#wrap
  * @see WrapReturnFunction
  */
@@ -766,23 +690,17 @@ function wrapReturn(nodule, properties, spec, args) {
  * - `wrapClass(func, spec [, args])`
  *
  * @memberof Shim.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 constructor to wrap.
- *
  * @param {ClassWrapSpec|ConstructorHookFunction} spec
  *  The spec for wrapping the returned value from the properties or a post hook.
- *
  * @param {Array.<*>} [args=[]]
  *  Optional extra arguments to be sent to the spec when executing it.
- *
- * @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 Shim#wrap
  */
 function wrapClass(nodule, properties, spec, args) {
@@ -824,15 +742,12 @@ function wrapClass(nodule, properties, spec, args) {
  * - `wrapExport(nodule, spec)`
  *
  * @memberof Shim.prototype
- *
  * @param {*} nodule
  *  The original export to replace with our new one.
- *
  * @param {WrapFunction} spec
  *  A wrapper function. The return value from this spec is what will replace
  *  the export.
- *
- * @return {*} The return value from `spec`.
+ * @returns {*} The return value from `spec`.
  */
 function wrapExport(nodule, spec) {
   return (this._toExport = this.wrap(nodule, null, spec))
@@ -843,12 +758,9 @@ function wrapExport(nodule, spec) {
  *
  * @private
  * @memberof Shim.prototype
- *
  * @param {*} defaultExport - The original export in case it was never wrapped.
- *
- * @return {*} The result from calling {@link Shim#wrapExport} or `defaultExport`
+ * @returns {*} The result from calling {@link Shim#wrapExport} or `defaultExport`
  *  if it was never used.
- *
  * @see Shim.wrapExport
  */
 function getExport(defaultExport) {
@@ -862,16 +774,12 @@ function getExport(defaultExport) {
  * - `isWrapped(func)`
  *
  * @memberof Shim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the property or a single function to check.
- *
  * @param {string} [property]
  *  The property to check. If omitted, the `nodule` parameter is assumed to be
  *  the function to check.
- *
- * @return {bool} True if the item exists and has been wrapped.
- *
+ * @returns {bool} True if the item exists and has been wrapped.
  * @see Shim#wrap
  * @see Shim#bindSegment
  */
@@ -891,20 +799,15 @@ function isWrapped(nodule, property) {
  * This is shorthand for calling {@link Shim#wrap} and manually creating a segment.
  *
  * @memberof Shim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the properties to record, or a single function to record.
- *
  * @param {string|Array.<string>} [properties]
  *  One or more properties to record. If omitted, the `nodule` parameter is
  *  assumed to be the function to record.
- *
  * @param {RecorderFunction} recordNamer
  *  A function which returns a record descriptor that gives the name and type of
  *  record we'll make.
- *
- * @return {Object|Function} The first parameter, possibly wrapped.
- *
+ * @returns {object | Function} The first parameter, possibly wrapped.
  * @see RecorderFunction
  * @see RecorderSpec
  * @see Shim#wrap
@@ -965,6 +868,11 @@ function record(nodule, properties, recordNamer) {
       return _doRecord.call(this, segment, args, segDesc, shouldCreateSegment)
     }
 
+    /**
+     * @param shim
+     * @param args
+     * @param specCallback
+     */
     function _hasValidCallbackArg(shim, args, specCallback) {
       if (shim.isNumber(specCallback)) {
         const cbIdx = normalizeIndex(args.length, specCallback)
@@ -979,6 +887,12 @@ function record(nodule, properties, recordNamer) {
       return true
     }
 
+    /**
+     * @param segment
+     * @param args
+     * @param segDesc
+     * @param shouldCreateSegment
+     */
     function _doRecord(segment, args, segDesc, shouldCreateSegment) {
       // Now bind any callbacks specified in the segment descriptor.
       _bindAllCallbacks.call(this, shim, fn, name, args, {
@@ -1007,6 +921,12 @@ function record(nodule, properties, recordNamer) {
       return ret
     }
 
+    /**
+     * @param segment
+     * @param ctx
+     * @param args
+     * @param segDesc
+     */
     function _applyRecorderSegment(segment, ctx, args, segDesc) {
       let error = null
       let promised = false
@@ -1051,15 +971,12 @@ function record(nodule, properties, recordNamer) {
  * back on the nodule. Otherwise, the unwrapped function is just returned.
  *
  * @memberof Shim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the properties to unwrap, or a single function to unwrap.
- *
  * @param {string|Array.<string>} [properties]
  *  One or more properties to unwrap. If omitted, the `nodule` parameter is
  *  assumed to be the function to unwrap.
- *
- * @return {Object|Function} The first parameter after unwrapping.
+ * @returns {object | Function} The first parameter after unwrapping.
  */
 function unwrap(nodule, properties) {
   // Don't try to unwrap potentially `null` or `undefined` things.
@@ -1093,15 +1010,12 @@ function unwrap(nodule, properties) {
  * back on the nodule. Otherwise, the unwrapped function is just returned.
  *
  * @memberof Shim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the properties to unwrap, or a single function to unwrap.
- *
  * @param {string|Array.<string>} [properties]
  *  One or more properties to unwrap. If omitted, the `nodule` parameter is
  *  assumed to be the function to unwrap.
- *
- * @return {Object|Function} The first parameter after unwrapping.
+ * @returns {object | Function} The first parameter after unwrapping.
  */
 function unwrapOnce(nodule, properties) {
   // Don't try to unwrap potentially `null` or `undefined` things.
@@ -1132,14 +1046,11 @@ function unwrapOnce(nodule, properties) {
  * - `getOriginal(func)`
  *
  * @memberof Shim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source of the property to get the original of, or a function to unwrap.
- *
  * @param {string} [property]
  *  A property on `nodule` to get the original value of.
- *
- * @return {Object|Function} The original value for the given item.
+ * @returns {object | Function} The original value for the given item.
  */
 function getOriginal(nodule, property) {
   if (!nodule) {
@@ -1163,22 +1074,17 @@ function getOriginal(nodule, property) {
  * back on the nodule. Otherwise, the wrapped function is just returned.
  *
  * @memberof Shim.prototype
- *
- * @param {Object|Function} nodule
+ * @param {object | Function} nodule
  *  The source for the property or a single function to bind to a segment.
- *
  * @param {string} [property]
  *  The property to bind. If omitted, the `nodule` parameter is assumed
  *  to be the function to bind the segment to.
- *
  * @param {?TraceSegment} [segment=null]
  *  The segment to bind the execution of the function to. If omitted or `null`
  *  the currently active segment will be bound instead.
- *
  * @param {bool} [full=false]
  *  Indicates if the full lifetime of the segment is bound to this function.
- *
- * @return {Object|Function} The first parameter after wrapping.
+ * @returns {object | Function} The first parameter after wrapping.
  */
 function bindSegment(nodule, property, segment, full) {
   // Don't bind to null arguments.
@@ -1229,17 +1135,13 @@ function bindSegment(nodule, property, segment, full) {
  * - `bindCallbackSegment(obj, property [, segment])`
  *
  * @memberof Shim.prototype
- *
- * @param {Array|Object} args
+ * @param {Array | object} args
  *  The arguments array to pull the cb from.
- *
  * @param {number|string} cbIdx
  *  The index of the callback.
- *
  * @param {TraceSegment} [parentSegment]
  *  The segment to use as the callback segment's parent. Defaults to the
  *  currently active segment.
- *
  * @see Shim#bindSegment
  */
 function bindCallbackSegment(args, cbIdx, parentSegment) {
@@ -1299,10 +1201,8 @@ function bindCallbackSegment(args, cbIdx, parentSegment) {
  * - `getSegment([obj])`
  *
  * @memberof Shim.prototype
- *
  * @param {*} [obj] - The object to retrieve a segment from.
- *
- * @return {?TraceSegment} The trace segment associated with the given object or
+ * @returns {?TraceSegment} The trace segment associated with the given object or
  *  the current segment if no object is provided or no segment is associated
  *  with the object.
  */
@@ -1310,7 +1210,8 @@ function getSegment(obj) {
   if (obj && obj.__NR_segment) {
     return obj.__NR_segment
   }
-  return this.tracer.getSegment()
+
+  return this._contextManager.getContext()
 }
 
 /**
@@ -1323,10 +1224,8 @@ function getSegment(obj) {
  * ended yet).
  *
  * @memberof Shim.prototype
- *
  * @param {*} [obj] - The object to retrieve a segment from.
- *
- * @return {?TraceSegment} The trace segment associated with the given object or
+ * @returns {?TraceSegment} The trace segment associated with the given object or
  *  the currently active segment if no object is provided or no segment is
  *  associated with the object.
  */
@@ -1346,12 +1245,12 @@ function getActiveSegment(obj) {
  * - `setActiveSegment(segment)`
  *
  * @memberof Shim.prototype
- *
  * @param {TraceSegment} segment - The segment to set as the active segment.
- *
+ * @returns {TraceSegment} - The segment set as active on the context.
  */
 function setActiveSegment(segment) {
-  return (this.tracer.segment = segment)
+  this._contextManager.setContext(segment)
+  return segment
 }
 
 /**
@@ -1362,14 +1261,14 @@ function setActiveSegment(segment) {
  * If no segment is provided, the currently active segment is used.
  *
  * @memberof Shim.prototype
- *
  * @param {!*}            obj       - The object to retrieve a segment from.
  * @param {TraceSegment}  [segment] - The segment to link the object to.
  */
 function storeSegment(obj, segment) {
-  this.setInternalProperty(obj, '__NR_segment', segment || this.tracer.getSegment())
+  this.setInternalProperty(obj, '__NR_segment', segment || this.getSegment())
 }
 
+/* eslint-disable max-params */
 /**
  * Sets the given segment as the active one for the duration of the function's
  * execution.
@@ -1377,30 +1276,15 @@ function storeSegment(obj, segment) {
  * - `applySegment(func, segment, full, context, args[, inContextCB])`
  *
  * @memberof Shim.prototype
- *
- * @param {Function} func
- *  The function to execute in the context of the given segment.
- *
- * @param {TraceSegment} segment
- *  The segment to make active for the duration of the function.
- *
- * @param {bool} full
- *  Indicates if the full lifetime of the segment is bound to this function.
- *
- * @param {*} context
- *  The `this` argument for the function.
- *
- * @param {Array.<*>} args
- *  The arguments to be passed into the function.
- *
- * @param {Function} [inContextCB]
- *  The function used to do more instrumentation work. This function is
+ * @param {Function} func The function to execute in the context of the given segment.
+ * @param {TraceSegment} segment The segment to make active for the duration of the function.
+ * @param {bool} full Indicates if the full lifetime of the segment is bound to this function.
+ * @param {*} context The `this` argument for the function.
+ * @param {Array.<*>} args The arguments to be passed into the function.
+ * @param {Function} [inContextCB] The function used to do more instrumentation work. This function is
  *  guaranteed to be executed with the segment associated with.
- *
- *
- * @return {*} Whatever value `func` returned.
+ * @returns {*} Whatever value `func` returned.
  */
-/* eslint-disable max-params */
 function applySegment(func, segment, full, context, args, inContextCB) {
   // Exist fast for bad arguments.
   if (!this.isFunction(func)) {
@@ -1411,35 +1295,35 @@ function applySegment(func, segment, full, context, args, inContextCB) {
     this.logger.trace('No segment to apply to function.')
     return fnApply.call(func, context, args)
   }
+
   this.logger.trace('Applying segment %s', segment.name)
 
-  // Set this segment as the current one on the tracer.
-  const tracer = this.tracer
-  const prevSegment = tracer.segment
-  tracer.segment = segment
-  if (full) {
-    segment.start()
-  }
+  const contextManager = this._contextManager
+  const prevSegment = contextManager.getContext()
 
-  if (typeof inContextCB === 'function') {
-    inContextCB()
-  }
+  return contextManager.runInContext(segment, () => {
+    if (full) {
+      segment.start()
+    }
 
-  // Execute the function and then return the tracer segment to the old one.
-  try {
-    return fnApply.call(func, context, args)
-  } catch (error) {
-    if (prevSegment === null && process.domain != null) {
-      process.domain.__NR_segment = tracer.segment
+    if (typeof inContextCB === 'function') {
+      inContextCB()
     }
 
-    throw error // Rethrowing application error, this is not an agent error.
-  } finally {
-    if (full) {
-      segment.touch()
+    try {
+      return fnApply.call(func, context, args)
+    } catch (error) {
+      if (prevSegment === null && process.domain != null) {
+        process.domain.__NR_segment = contextManager.getContext()
+      }
+
+      throw error // Re-throwing application error, this is not an agent error.
+    } finally {
+      if (full) {
+        segment.touch()
+      }
     }
-    tracer.segment = prevSegment
-  }
+  })
 }
 /* eslint-enable max-params */
 
@@ -1450,19 +1334,15 @@ function applySegment(func, segment, full, context, args, inContextCB) {
  * - `createSegment(name [, recorder] [, parent])`
  *
  * @memberof Shim.prototype
- *
  * @param {string} name
  *  The name to give the new segment.
- *
  * @param {?Function} [recorder=null]
  *  Optional. A function which will record the segment as a metric. Default is
  *  to not record the segment.
- *
  * @param {TraceSegment} [parent]
  *  Optional. The segment to use as the parent. Default is to use the currently
  *  active segment.
- *
- * @return {?TraceSegment} A new trace segment if a transaction is active, else
+ * @returns {?TraceSegment} A new trace segment if a transaction is active, else
  *  `null` is returned.
  */
 function createSegment(name, recorder, parent) {
@@ -1488,6 +1368,10 @@ function createSegment(name, recorder, parent) {
   return _rawCreateSegment(this, opts)
 }
 
+/**
+ * @param shim
+ * @param opts
+ */
 function _rawCreateSegment(shim, opts) {
   // Grab parent segment when none in opts so we can check opaqueness
   opts.parent = opts.parent || shim.getActiveSegment()
@@ -1521,10 +1405,8 @@ function _rawCreateSegment(shim, opts) {
  * Determine the name of an object.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to get a name for.
- *
- * @return {string} The name of the object if it has one, else `<anonymous>`.
+ * @returns {string} The name of the object if it has one, else `<anonymous>`.
  */
 function getName(obj) {
   return String(!obj || obj === true ? obj : obj.name || '<anonymous>')
@@ -1534,10 +1416,8 @@ function getName(obj) {
  * Determines if the given object is an Object.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to check.
- *
- * @return {bool} True if the object is an Object, else false.
+ * @returns {bool} True if the object is an Object, else false.
  */
 function isObject(obj) {
   return obj instanceof Object
@@ -1547,10 +1427,8 @@ function isObject(obj) {
  * Determines if the given object exists and is a function.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to check.
- *
- * @return {bool} True if the object is a function, else false.
+ * @returns {bool} True if the object is a function, else false.
  */
 function isFunction(obj) {
   return typeof obj === 'function'
@@ -1560,10 +1438,8 @@ function isFunction(obj) {
  * Determines if the given object exists and is a string.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to check.
- *
- * @return {bool} True if the object is a string, else false.
+ * @returns {bool} True if the object is a string, else false.
  */
 function isString(obj) {
   return typeof obj === 'string'
@@ -1573,10 +1449,8 @@ function isString(obj) {
  * Determines if the given object is a number literal.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to check.
- *
- * @return {bool} True if the object is a number literal, else false.
+ * @returns {bool} True if the object is a number literal, else false.
  */
 function isNumber(obj) {
   return typeof obj === 'number'
@@ -1586,10 +1460,8 @@ function isNumber(obj) {
  * Determines if the given object is a boolean literal.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to check.
- *
- * @return {bool} True if the object is a boolean literal, else false.
+ * @returns {bool} True if the object is a boolean literal, else false.
  */
 function isBoolean(obj) {
   return typeof obj === 'boolean'
@@ -1599,10 +1471,8 @@ function isBoolean(obj) {
  * Determines if the given object exists and is an array.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to check.
- *
- * @return {bool} True if the object is an array, else false.
+ * @returns {bool} True if the object is an array, else false.
  */
 function isArray(obj) {
   return obj instanceof Array
@@ -1612,10 +1482,8 @@ function isArray(obj) {
  * Determines if the given object is a promise instance.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The object to check.
- *
- * @return {bool} True if the object is a promise, else false.
+ * @returns {bool} True if the object is a promise, else false.
  */
 function isPromise(obj) {
   return obj && typeof obj.then === 'function'
@@ -1625,10 +1493,8 @@ function isPromise(obj) {
  * Determines if the given value is null.
  *
  * @memberof Shim.prototype
- *
  * @param {*} val - The value to check.
- *
- * @return {bool} True if the value is null, else false.
+ * @returns {bool} True if the value is null, else false.
  */
 function isNull(val) {
   return val === null
@@ -1638,10 +1504,8 @@ function isNull(val) {
  * Converts an array-like object into an array.
  *
  * @memberof Shim.prototype
- *
  * @param {*} obj - The array-like object (i.e. `arguments`).
- *
- * @return {Array.<*>} An instance of `Array` containing the elements of the
+ * @returns {Array.<*>} An instance of `Array` containing the elements of the
  *  array-like.
  */
 function toArray(obj) {
@@ -1660,9 +1524,7 @@ function toArray(obj) {
  * `arguments` object into an actual `Array` as it will not cause deopts.
  *
  * @memberof Shim.prototype
- *
- * @return {Array} An array containing the elements of `arguments`.
- *
+ * @returns {Array} An array containing the elements of `arguments`.
  * @see Shim#toArray
  * @see https://github.com/petkaantonov/bluebird/wiki/Optimization-killers
  */
@@ -1682,11 +1544,9 @@ function argsToArray() {
  * array length before checking it.
  *
  * @memberof Shim.prototype
- *
  * @param {number} arrayLength  - The length of the array this index is for.
  * @param {number} idx          - The index to normalize.
- *
- * @return {?number} The adjusted index value if it is valid, else `null`.
+ * @returns {?number} The adjusted index value if it is valid, else `null`.
  */
 function normalizeIndex(arrayLength, idx) {
   if (idx < 0) {
@@ -1699,10 +1559,8 @@ function normalizeIndex(arrayLength, idx) {
  * Wraps a function such that it will only be executed once.
  *
  * @memberof Shim.prototype
- *
- * @param {function} fn - The function to wrap in an execution guard.
- *
- * @return {function} A function which will execute `fn` at most once.
+ * @param {Function} fn - The function to wrap in an execution guard.
+ * @returns {Function} A function which will execute `fn` at most once.
  */
 function once(fn) {
   let called = false
@@ -1719,12 +1577,10 @@ function once(fn) {
  * be made writable and non-enumerable.
  *
  * @memberof Shim.prototype
- *
  * @param {!object} obj   - The object to add the property to.
  * @param {!string} name  - The name for this property.
  * @param {*}       val   - The value to set the property as.
- *
- * @return {object} The `obj` value.
+ * @returns {object} The `obj` value.
  */
 function setInternalProperty(obj, name, val) {
   if (!obj || !name) {
@@ -1744,6 +1600,11 @@ function setInternalProperty(obj, name, val) {
   return obj
 }
 
+/**
+ * @param obj
+ * @param name
+ * @param val
+ */
 function _slowSetInternalProperty(obj, name, val) {
   if (!hasOwnProperty(obj, name)) {
     Object.defineProperty(obj, name, {
@@ -1760,14 +1621,11 @@ function _slowSetInternalProperty(obj, name, val) {
  * Defines a read-only property on the given object.
  *
  * @memberof Shim.prototype
- *
  * @param {object} obj
  *  The object to add the property to.
- *
  * @param {string} name
  *  The name of the property to add.
- *
- * @param {*|function} value
+ * @param {* | Function} value
  *  The value to set. If a function is given, it is used as a getter, otherwise
  *  the value is directly set as an unwritable property.
  */
@@ -1790,10 +1648,8 @@ function defineProperty(obj, name, value) {
  * Adds several properties to the given object.
  *
  * @memberof Shim.prototype
- *
  * @param {object} obj    - The object to add the properties to.
  * @param {object} props  - A mapping of properties to values to add.
- *
  * @see Shim#defineProperty
  */
 function defineProperties(obj, props) {
@@ -1809,11 +1665,9 @@ function defineProperties(obj, props) {
  * not already have that property.
  *
  * @memberof Shim.prototype
- *
  * @param {object?} obj       - The object to copy the defaults onto.
  * @param {object}  defaults  - A mapping of keys to default values.
- *
- * @return {object} The `obj` with the default values copied onto it. If `obj`
+ * @returns {object} The `obj` with the default values copied onto it. If `obj`
  *  was falsey, then a new object with the defaults copied onto it is returned
  *  instead.
  */
@@ -1837,13 +1691,10 @@ function setDefaults(obj, defaults) {
  * Proxies all set/get actions for each given property on `dest` onto `source`.
  *
  * @memberof Shim.prototype
- *
  * @param {*} source
  *  The object on which all the set/get actions will actually occur.
- *
  * @param {string|Array.<string>} properties
  *  All of the properties to proxy.
- *
  * @param {*} dest
  *  The object which is proxying the source's properties.
  */
@@ -1868,10 +1719,8 @@ function proxy(source, properties, dest) {
  * Loads a node module from the instrumented library's own root directory.
  *
  * @memberof Shim.prototype
- *
  * @param {string} filePath - A relative path inside the module's directory.
- *
- * @return {*?} The result of loading the given module. If the module fails to
+ * @returns {*?} The result of loading the given module. If the module fails to
  *  load, `null` is returned instead.
  */
 function shimRequire(filePath) {
@@ -1893,11 +1742,9 @@ function shimRequire(filePath) {
  * resolved or rejected.
  *
  * @memberof Shim.prototype
- *
  * @param {Promise} prom  - Some kind of promise. Must have a `then` method.
  * @param {Function} cb   - A function to call when the promise resolves.
- *
- * @return {Promise} A new promise to replace the original one.
+ * @returns {Promise} A new promise to replace the original one.
  */
 function interceptPromise(prom, cb) {
   if (this.isFunction(prom.finally)) {
@@ -1920,14 +1767,11 @@ function interceptPromise(prom, cb) {
  * Updates segment timing and resets opaque state.
  *
  * @memberof Shim.prototype
- *
  * @param {!Promise} promise
  *  The Promise to bind.
- *
  * @param {!TraceSegment} segment
  *  The segment to bind to the Promise.
- *
- * @return {Promise} The promise to continue with.
+ * @returns {Promise} The promise to continue with.
  */
 function bindPromise(promise, segment) {
   return this.interceptPromise(promise, function thenTouch() {
@@ -1941,7 +1785,6 @@ function bindPromise(promise, segment) {
  * configuration.
  *
  * @memberof Shim.prototype
- *
  * @param {TraceSegment}  segment     - The segment to copy the parameters onto.
  * @param {object}        parameters  - The parameters to copy.
  */
@@ -1991,13 +1834,14 @@ function unwrapAll() {
  * Coerces the given spec into a function which {@link Shim#wrap} can use.
  *
  * @private
- *
  * @param {Spec|WrapFunction} spec - The spec to coerce into a function.
- *
- * @return {WrapFunction} The spec itself if spec is a function, otherwise a
+ * @returns {WrapFunction} The spec itself if spec is a function, otherwise a
  *  function which will execute the spec when called.
  */
 /* eslint-disable no-unused-vars */
+/**
+ * @param spec
+ */
 function _specToFunction(spec) {
   throw new Error('Declarative specs are not implemented yet.')
 }
@@ -2009,23 +1853,17 @@ function _specToFunction(spec) {
  * - `_wrap(shim, original, name, spec [, args])`
  *
  * @private
- *
  * @param {Shim} shim
  *  The shim that is executing the wrapping.
- *
  * @param {*} original
  *  The object being wrapped.
- *
  * @param {string} name
  *  A logical name for the item to be wrapped.
- *
  * @param {WrapFunction} spec
  *  The spec for wrapping these items.
- *
  * @param {Array.<*>} [args=[]]
  *  Optional extra arguments to be sent to the spec when executing it.
- *
- * @return {Function} The return value from `spec` or the original value if it
+ * @returns {Function} The return value from `spec` or the original value if it
  *  did not return anything.
  */
 function _wrap(shim, original, name, spec, args) {
@@ -2062,20 +1900,15 @@ function _wrap(shim, original, name, spec, args) {
  * Creates the `bindSegment` wrapper function in its own, clean closure.
  *
  * @private
- *
  * @param {Shim} shim
  *  The shim used for the binding.
- *
- * @param {function} fn
+ * @param {Function} fn
  *  The function to be bound to the segment.
- *
  * @param {TraceSegment} segment
  *  The segment the function is bound to.
- *
  * @param {boolean} full
  *  Indicates if the segment's full lifetime is bound to the function.
- *
- * @return {function} A function which wraps `fn` and makes the given segment
+ * @returns {Function} A function which wraps `fn` and makes the given segment
  *  active for the duration of its execution.
  */
 function _makeBindWrapper(shim, fn, segment, full) {
@@ -2093,29 +1926,21 @@ function _makeBindWrapper(shim, fn, segment, full) {
  *
  * @this *
  * @private
- *
  * @param {Shim} shim
  *  The shim performing this binding.
- *
  * @param {Function} fn
  *  The function the spec describes.
- *
  * @param {string} name
  *  The name of the function the spec describes.
- *
  * @param {Array} args
  *  The arguments to be passed into `fn`.
- *
  * @param {object} spec
  *  The specification for bind the callbacks.
- *
  * @param {SegmentSpec} spec.spec
  *  The segment specification for the function we're pulling callbacks out of.
- *
  * @param {TraceSegment} spec.segment
  *  The segment measuring the function which will be the parent of any callback
  *  segments that may be created.
- *
  * @param {bool} spec.shouldCreateSegment
  *  Flag indicating if we should create segments for the callbacks. We almost
  *  always do, but in the special case of nested internal methods we do not.
@@ -2135,6 +1960,11 @@ function _bindAllCallbacks(shim, fn, name, args, spec) {
     )
   }
 
+  /**
+   * @param context
+   * @param callback
+   * @param binder
+   */
   function _bindCallback(context, callback, binder) {
     if (shim.isFunction(callback)) {
       callback.call(context, shim, fn, name, spec.segment, args)
@@ -2156,25 +1986,19 @@ function _bindAllCallbacks(shim, fn, name, args, spec) {
  * Binds the given segment to the lifetime of the stream.
  *
  * @private
- *
  * @param {Shim} shim
  *  The shim performing the wrapping/binding.
- *
  * @param {EventEmitter} stream
  *  The stream to bind.
- *
  * @param {?TraceSegment} segment
  *  The segment to bind to the stream.
- *
- * @param {Object} [spec]
+ * @param {object} [spec]
  *  Specification for how to bind the stream. The `end` and `error` events will
  *  always be bound, so if no functionality is desired beyond that, then this
  *  parameter may be omitted.
- *
  * @param {string} [spec.event]
  *  The name of an event to record. If provided, a new segment will be created
  *  for this event and will measure each time the event is emitted.
- *
  * @param {bool} spec.shouldCreateSegment
  *  Indicates if any child segments should be created. This should always be
  *  true unless this segment and its parent are both internal segments.
@@ -2250,23 +2074,17 @@ function _bindStream(shim, stream, segment, spec) {
  * - `_es6WrapClass(shim, Base, fnName, spec, args)`
  *
  * @private
- *
  * @param {Shim} shim
  *  The shim performing the wrapping/binding.
- *
  * @param {class} Base
  *  The es6 class to be wrapped.
- *
  * @param {string} fnName
  *  The name of the base class.
- *
  * @param {ClassWrapSpec} spec
  *  The spec with pre- and post-execution hooks to call.
- *
  * @param {Array.<*>} args
  *  Extra arguments to pass through to the pre- and post-execution hooks.
- *
- * @return {class} A class that extends Base with execution hooks.
+ * @returns {class} A class that extends Base with execution hooks.
  */
 function _es6WrapClass(shim, Base, fnName, spec, args) {
   return class WrappedClass extends Base {
@@ -2293,25 +2111,22 @@ function _es6WrapClass(shim, Base, fnName, spec, args) {
  * - `_es5WrapClass(shim, Base, fnName, spec, args)`
  *
  * @private
- *
  * @param {Shim} shim
  *  The shim performing the wrapping/binding.
- *
  * @param {Function} Base
  *  The class to be wrapped.
- *
  * @param {string} fnName
  *  The name of the base class.
- *
  * @param {ClassWrapSpec} spec
  *  The spec with pre- and post-execution hooks to call.
- *
  * @param {Array.<*>} args
  *  Extra arguments to pass through to the pre- and post-execution hooks.
- *
- * @return {Function} A class that extends Base with execution hooks.
+ * @returns {Function} A class that extends Base with execution hooks.
  */
 function _es5WrapClass(shim, Base, fnName, spec, args) {
+  /**
+   *
+   */
   function WrappedClass() {
     const cnstrctArgs = argsToArray.apply(shim, arguments)
     if (!(this instanceof WrappedClass)) {