WebFrameworkShim

WebFrameworkShim

A helper class for wrapping web framework modules.

Constructor

new WebFrameworkShim(agent, moduleName, resolvedName, frameworkIdopt)

Constructs a shim associated with the given agent instance, specialized for instrumenting web frameworks.

Source:
See:
Parameters:
Name Type Attributes Description
agent Agent

The agent this shim will use.

moduleName string

The name of the module being instrumented.

resolvedName string

The full path to the loaded module.

frameworkId string <optional>

The name of the web framework being instrumented. If available, use one of the values from WebFrameworkShim.FRAMEWORK_NAMES.

Extends

Members

(static, readonly) FRAMEWORK_NAMES :string

An enumeration of well-known web frameworks so that new instrumentations can use the same names we already use for first-party instrumentation.

Each of these values is also exposed directly on the WebFrameworkShim class as static members.

Properties:
Name Type Description
CONNECT string
DIRECTOR string
EXPRESS string
HAPI string
KOA string
RESTIFY string
Source:
Type:
  • string

(readonly) agent :Agent

The agent associated with this shim.

Inherited From:
Source:
Type:
  • Agent

(readonly) logger :Logger

The logger for this shim.

Inherited From:
Source:
Type:
  • Logger

(constant) SYMBOLS :Symbol

Enumeration of symbols used by shims.

Properties:
Name Type Description
DISABLE_DT Symbol

Indicates distributed tracing should be disabled for a single request.

Inherited From:
Source:
Type:
  • Symbol

(readonly) tracer :Tracer

The tracer in use by the agent for the shim.

Inherited From:
Source:
Type:
  • Tracer

Methods

argsToArray() → {Array}

Like Shim#toArray, but converts arguments to an array.

This is the preferred function, when used with .apply, for converting the arguments object into an actual Array as it will not cause deopts.

Inherited From:
Source:
See:
Returns:
Type:
Array

An array containing the elements of arguments.

bindCallbackSegment(args, cbIdx, parentSegmentopt)

Replaces the callback in an arguments array with one that has been bound to the given segment.

  • bindCallbackSegment(args, cbIdx [, segment])
  • bindCallbackSegment(obj, property [, segment])
Inherited From:
Source:
See:
Parameters:
Name Type Attributes Description
args Array | Object

The arguments array to pull the cb from.

cbIdx number | string

The index of the callback.

parentSegment TraceSegment <optional>

The segment to use as the callback segment's parent. Defaults to the currently active segment.

bindCreateTransaction(nodule, propertyopt, spec) → {Object|function}

Wraps one or more functions such that new transactions are created when invoked.

  • bindCreateTransaction(nodule, property, spec)
  • bindCreateTransaction(func, spec)
Inherited From:
Source:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the property to wrap, or a single function to wrap.

property string <optional>

The property to wrap. If omitted, the nodule parameter is assumed to be the function to wrap.

spec TransactionSpec

The spec for creating the transaction.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its property.

bindPromise(promisenon-null, segmentnon-null) → {Promise}

Binds the given segment to the completion of the Promise. Updates segment timing and resets opaque state.

Inherited From:
Source:
Parameters:
Name Type Description
promise Promise

The Promise to bind.

segment TraceSegment

The segment to bind to the Promise.

Returns:
Type:
Promise

The promise to continue with.

bindSegment(nodule, propertyopt, segmentopt, nullable, fullopt) → {Object|function}

Binds the execution of a function to a single segment.

  • bindSegment(nodule , property [, segment [, full]])
  • bindSegment(func [, segment [, full]])

If called with a nodule and a property, the wrapped property will be put back on the nodule. Otherwise, the wrapped function is just returned.

Inherited From:
Source:
Parameters:
Name Type Attributes Default Description
nodule Object | function

The source for the property or a single function to bind to a segment.

property string <optional>

The property to bind. If omitted, the nodule parameter is assumed to be the function to bind the segment to.

segment TraceSegment <optional>
<nullable>
null

The segment to bind the execution of the function to. If omitted or null the currently active segment will be bound instead.

full bool <optional>
false

Indicates if the full lifetime of the segment is bound to this function.

Returns:
Type:
Object | function

The first parameter after wrapping.

captureUrlParams(params)

Capture URL parameters from a request object as attributes of the current segment.

Source:
Parameters:
Name Type Description
params Object

An object with key-value pairs.

createSegment(name, recorderopt, nullable, parentopt) → (nullable) {TraceSegment}

Creates a new segment.

  • createSegment(opts)
  • createSegment(name [, recorder] [, parent])
Inherited From:
Source:
Parameters:
Name Type Attributes Default Description
name string

The name to give the new segment.

recorder function <optional>
<nullable>
null

Optional. A function which will record the segment as a metric. Default is to not record the segment.

parent TraceSegment <optional>

Optional. The segment to use as the parent. Default is to use the currently active segment.

Returns:
Type:
TraceSegment

A new trace segment if a transaction is active, else null is returned.

defineProperties(obj, props)

Adds several properties to the given object.

Inherited From:
Source:
See:
Parameters:
Name Type Description
obj object

The object to add the properties to.

props object

A mapping of properties to values to add.

defineProperty(obj, name, value)

Defines a read-only property on the given object.

Inherited From:
Source:
Parameters:
Name Type Description
obj object

The object to add the property to.

name string

The name of the property to add.

value * | function

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.

errorHandled(req, err)

Indicates that the given error has been handled for this request.

Source:
See:
Parameters:
Name Type Description
req Request

The request which caused the error.

err *

The error which has been handled.

execute()

Entry point for executing a spec.

Inherited From:
Source:

getActiveSegment(objopt) → (nullable) {TraceSegment}

Retrieves the segment associated with the given object, or the currently active segment if no object is given.

  • getActiveSegment([obj])

An active segment is one whose transaction is still active (e.g. has not ended yet).

Inherited From:
Source:
Parameters:
Name Type Attributes Description
obj * <optional>

The object to retrieve a segment from.

Returns:
Type:
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.

getName(obj) → {string}

Determine the name of an object.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to get a name for.

Returns:
Type:
string

The name of the object if it has one, else <anonymous>.

getOriginal(nodule, propertyopt) → {Object|function}

Retrieves the original method for a wrapped function.

  • getOriginal(nodule, property)
  • getOriginal(func)
Inherited From:
Source:
Parameters:
Name Type Attributes Description
nodule Object | function

The source of the property to get the original of, or a function to unwrap.

property string <optional>

A property on nodule to get the original value of.

Returns:
Type:
Object | function

The original value for the given item.

getSegment(objopt) → (nullable) {TraceSegment}

Retrieves the segment associated with the given object, or the current segment if no object is given.

  • getSegment([obj])
Inherited From:
Source:
Parameters:
Name Type Attributes Description
obj * <optional>

The object to retrieve a segment from.

Returns:
Type:
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.

insertCATReplyHeader(headers, useAlternateHeaderNamesopt)

Adds CAT headers for an outbound response.

  • insertCATReplyHeaders(headers [, useAlternateHeaderNames])
Inherited From:
Source:
Parameters:
Name Type Attributes Default Description
headers object

The outbound response headers object to inject our CAT headers into.

useAlternateHeaderNames bool <optional>
false

Indicates if HTTP-style headers should be used or alternate style. Some transport protocols are more strict on the characters allowed in headers and this option can be used to toggle use of pure-alpha header names.

insertCATRequestHeaders(headers, useAlternateHeaderNamesopt)

Adds CAT headers for an outbound request.

  • insertCATRequestHeaders(headers [, useAlternateHeaderNames])
Inherited From:
Source:
Parameters:
Name Type Attributes Default Description
headers object

The outbound request headers object to inject our CAT headers into.

useAlternateHeaderNames bool <optional>
false

Indicates if HTTP-style headers should be used or alternate style. Some transport protocols are more strict on the characters allowed in headers and this option can be used to toggle use of pure-alpha header names.

interceptPromise(prom, cb) → {Promise}

Executes the given callback when the promise is finalized, whether it is resolved or rejected.

Inherited From:
Source:
Parameters:
Name Type Description
prom Promise

Some kind of promise. Must have a then method.

cb function

A function to call when the promise resolves.

Returns:
Type:
Promise

A new promise to replace the original one.

isArray(obj) → {bool}

Determines if the given object exists and is an array.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to check.

Returns:
Type:
bool

True if the object is an array, else false.

isBoolean(obj) → {bool}

Determines if the given object is a boolean literal.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to check.

Returns:
Type:
bool

True if the object is a boolean literal, else false.

isFunction(obj) → {bool}

Determines if the given object exists and is a function.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to check.

Returns:
Type:
bool

True if the object is a function, else false.

isNull(val) → {bool}

Determines if the given value is null.

Inherited From:
Source:
Parameters:
Name Type Description
val *

The value to check.

Returns:
Type:
bool

True if the value is null, else false.

isNumber(obj) → {bool}

Determines if the given object is a number literal.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to check.

Returns:
Type:
bool

True if the object is a number literal, else false.

isObject(obj) → {bool}

Determines if the given object is an Object.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to check.

Returns:
Type:
bool

True if the object is an Object, else false.

isPromise(obj) → {bool}

Determines if the given object is a promise instance.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to check.

Returns:
Type:
bool

True if the object is a promise, else false.

isString(obj) → {bool}

Determines if the given object exists and is a string.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The object to check.

Returns:
Type:
bool

True if the object is a string, else false.

isWrapped(nodule, propertyopt) → {bool}

Determines if the specified function or property exists and is wrapped.

  • isWrapped(nodule, property)
  • isWrapped(func)
Inherited From:
Source:
See:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the property or a single function to check.

property string <optional>

The property to check. If omitted, the nodule parameter is assumed to be the function to check.

Returns:
Type:
bool

True if the item exists and has been wrapped.

listenerCount(emitter, event) → {number}

Retrieves the number of listeners for the given event.

Inherited From:
Source:
Parameters:
Name Type Description
emitter object

The emitter to count the listeners on.

event string

The event to count.

Returns:
Type:
number

The number of listeners on the given event for this emitter.

normalizeIndex(arrayLength, idx) → (nullable) {number}

Ensures the given index is a valid index inside the array.

A negative index value is converted to a positive one by adding it to the array length before checking it.

Inherited From:
Source:
Parameters:
Name Type Description
arrayLength number

The length of the array this index is for.

idx number

The index to normalize.

Returns:
Type:
number

The adjusted index value if it is valid, else null.

noticeError(req, errnullable)

Tells the shim that the given request has caused an error.

The given error will be checked for truthiness and if it passes the error predicate check before being held onto.

Use WebFrameworkShim#errorHandled to unnotice an error if it is later caught by the user.

Source:
See:
Parameters:
Name Type Attributes Description
req Request

The request which caused the error.

err * <nullable>

The error which has occurred.

once(fn) → {function}

Wraps a function such that it will only be executed once.

Inherited From:
Source:
Parameters:
Name Type Description
fn function

The function to wrap in an execution guard.

Returns:
Type:
function

A function which will execute fn at most once.

popTransactionName(pathSegmentopt)

Pops one or more elements off the transaction naming stack.

  • popTransactionName([pathSegment])

Ideally it is not necessary to ever provide the pathSegment parameter for this function, but we do not live in an ideal world.

Inherited From:
Source:
Parameters:
Name Type Attributes Description
pathSegment string <optional>

Optional. Path segment to pop the stack repeatedly until a segment matching pathSegment is removed.

proxy(source, properties, dest)

Proxies all set/get actions for each given property on dest onto source.

Inherited From:
Source:
Parameters:
Name Type Description
source *

The object on which all the set/get actions will actually occur.

properties string | Array.<string>

All of the properties to proxy.

dest *

The object which is proxying the source's properties.

pushTransactionName(pathSegment)

Pushes a new path segment onto the transaction naming stack.

  • pushTransactionName(pathSegment)

Transactions are named for the middlware that sends the reponse. Some web frameworks are capable of mounting middlware in complex routing stacks. In order to maintain the correct name, transactions keep a stack of mount points for each middlware/router/app/whatever. The instrumentation should push on the mount path for wrapped things when route resolution enters and pop it back off when resolution exits the item.

Inherited From:
Source:
Parameters:
Name Type Description
pathSegment string

The path segment to add to the naming stack.

record(nodule, propertiesopt, recordNamer) → {Object|function}

Wraps a function with segment creation and binding.

  • record(nodule, properties, recordNamer)
  • record(func, recordNamer)

This is shorthand for calling Shim#wrap and manually creating a segment.

Inherited From:
Source:
See:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the properties to record, or a single function to record.

properties string | Array.<string> <optional>

One or more properties to record. If omitted, the nodule parameter is assumed to be the function to record.

recordNamer RecorderFunction

A function which returns a record descriptor that gives the name and type of record we'll make.

Returns:
Type:
Object | function

The first parameter, possibly wrapped.

recordMiddleware(nodule, propertiesopt, specopt) → {Object|function}

Records the provided function as a middleware.

  • recordMiddleware(nodule, properties [, spec])
  • recordMiddleware(func [, spec])
Source:
See:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the properties to wrap, or a single function to wrap.

properties string | Array.<string> <optional>

One or more properties to wrap. If omitted, the nodule parameter is assumed to be the function to wrap.

spec MiddlewareSpec <optional>

The spec for wrapping the middleware.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its properties.

recordParamware(nodule, propertiesopt, specopt) → {Object|function}

Records the provided function as a paramware.

  • recordParamware(nodule, properties [, spec])
  • recordParamware(func [, spec])

Paramware are specialized middleware that execute when certain route parameters are encountered. For example, the route /users/:userId could trigger a paramware hooked to userId.

For every new request that comes in, this should be called as early in the processing as possible.

Source:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the properties to wrap, or a single function to wrap.

properties string | Array.<string> <optional>

One or more properties to wrap. If omitted, the nodule parameter is assumed to be the function to wrap.

spec MiddlewareSpec <optional>

The spec for wrapping the middleware.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its properties.

recordRender(nodule, propertiesopt, specopt) → {Object|function}

Records calls to methods used for rendering views.

  • recordRender(nodule, properties [, spec])
  • recordRender(func [, spec])
Source:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the properties to wrap, or a single function to wrap.

properties string | Array.<string> <optional>

One or more properties to wrap. If omitted, the nodule parameter is assumed to be the function to wrap.

spec RenderSpec <optional>

The spec for wrapping the render method.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its properties.

savePossibleTransactionName(req)

Marks the current path as a potential responder.

Source:
Parameters:
Name Type Description
req Request

The request which caused the error.

setActiveSegment(segment)

Explicitly sets the active segment to the one passed in. This method should only be used if there is no function to tie a segment's timing to.

  • setActiveSegment(segment)
Inherited From:
Source:
Parameters:
Name Type Description
segment TraceSegment

The segment to set as the active segment.

setDefaults(objnullable, defaults) → {object}

Performs a shallow copy of each property from defaults only if obj does not already have that property.

Inherited From:
Source:
Parameters:
Name Type Attributes Description
obj object <nullable>

The object to copy the defaults onto.

defaults object

A mapping of keys to default values.

Returns:
Type:
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.

setErrorPredicate(pred)

Sets a function to call when an error is noticed to determine if it is really an error.

Source:
See:
Parameters:
Name Type Description
pred function

Function which should return true if the object passed to it is considered an error.

setFramework(framework)

Sets the name of the web framework in use by the server to the one given.

  • setFramework(framework)

This should be the first thing the instrumentation does.

Source:
See:
Parameters:
Name Type Description
framework WebFrameworkShim.FRAMEWORK_NAMES | string

The name of the framework.

setInternalProperty(objnon-null, namenon-null, val) → {object}

Sets a property to the given value. If the property doesn't exist yet it will be made writable and non-enumerable.

Inherited From:
Source:
Parameters:
Name Type Description
obj object

The object to add the property to.

name string

The name for this property.

val *

The value to set the property as.

Returns:
Type:
object

The obj value.

setResponsePredicate(pred)

Sets a function to call with the result of a middleware to determine if it has responded.

Source:
Parameters:
Name Type Description
pred function

Function which should return true if the object passed to it is considered a response.

setRouteParser(parser)

Sets the function used to convert the route handed to middleware-adding methods into a string.

  • setRouteParser(parser)
Source:
Parameters:
Name Type Description
parser RouteParserFunction

The parser function to use.

setTransactionName(name)

Sets the name to be used for this transaction.

  • setTransactionName(name)

Either this or the naming stack should be used. Do not use them together.

Inherited From:
Source:
Parameters:
Name Type Description
name string

The name to use for the transaction.

setTransactionUri(uri)

Sets the URI path to be used for naming the transaction currenty in scope.

Source:
Parameters:
Name Type Description
uri string

The URI path to use for the transaction.

shimRequire(filePath) → (nullable) {*}

Loads a node module from the instrumented library's own root directory.

Inherited From:
Source:
Parameters:
Name Type Description
filePath string

A relative path inside the module's directory.

Returns:
Type:
*

The result of loading the given module. If the module fails to load, null is returned instead.

storeSegment(objnon-null, segmentopt)

Associates a segment with the given object.

  • storeSegment(obj [, segment])

If no segment is provided, the currently active segment is used.

Inherited From:
Source:
Parameters:
Name Type Attributes Description
obj *

The object to retrieve a segment from.

segment TraceSegment <optional>

The segment to link the object to.

toArray(obj) → {Array.<*>}

Converts an array-like object into an array.

Inherited From:
Source:
Parameters:
Name Type Description
obj *

The array-like object (i.e. arguments).

Returns:
Type:
Array.<*>

An instance of Array containing the elements of the array-like.

unwrap(nodule, propertiesopt) → {Object|function}

Unwraps one or more items, revealing the original value.

  • unwrap(nodule, property)
  • unwrap(func)

If called with a nodule and properties, the unwrapped values will be put back on the nodule. Otherwise, the unwrapped function is just returned.

Inherited From:
Source:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the properties to unwrap, or a single function to unwrap.

properties string | Array.<string> <optional>

One or more properties to unwrap. If omitted, the nodule parameter is assumed to be the function to unwrap.

Returns:
Type:
Object | function

The first parameter after unwrapping.

unwrapOnce(nodule, propertiesopt) → {Object|function}

Unwraps one item, revealing the underlying value.

  • unwrapOnce(nodule, property)
  • unwrapOnce(func)

If called with a nodule and properties, the unwrapped value will be put back on the nodule. Otherwise, the unwrapped function is just returned.

Inherited From:
Source:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the properties to unwrap, or a single function to unwrap.

properties string | Array.<string> <optional>

One or more properties to unwrap. If omitted, the nodule parameter is assumed to be the function to unwrap.

Returns:
Type:
Object | function

The first parameter after unwrapping.

wrap(nodule, propertiesopt, spec, argsopt) → {Object|function}

Executes the provided spec on one or more objects.

  • wrap(nodule, properties, spec [, args])
  • wrap(func, spec [, args])

When called with a nodule and one or more properties, the spec will be executed on each property listed and the return value put back on the nodule.

When called with just a function, the spec will be executed on the function and the return value of the spec simply passed back.

The wrapped version will have the same prototype as the original method.

Inherited From:
Source:
See:
Parameters:
Name Type Attributes Default Description
nodule Object | function

The source for the properties to wrap, or a single function to wrap.

properties string | Array.<string> <optional>

One or more properties to wrap. If omitted, the nodule parameter is assumed to be the function to wrap.

spec Spec | WrapFunction

The spec for wrapping these items.

args Array.<*> <optional>
[]

Optional extra arguments to be sent to the spec when executing it.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its properties.

wrapClass(nodule, propertiesopt, spec, argsopt) → {Object|function}

Wraps a class constructor using a subclass with pre- and post-construction hooks.

  • wrapClass(nodule, properties, spec [, args])
  • wrapClass(func, spec [, args])
Inherited From:
Source:
See:
Parameters:
Name Type Attributes Default Description
nodule Object | function

The source for the properties to wrap, or a single function to wrap.

properties string | Array.<string> <optional>

One or more properties to wrap. If omitted, the nodule parameter is assumed to be the constructor to wrap.

spec ClassWrapSpec | ConstructorHookFunction

The spec for wrapping the returned value from the properties or a post hook.

args Array.<*> <optional>
[]

Optional extra arguments to be sent to the spec when executing it.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its properties.

wrapExport(nodule, spec) → {*}

Wraps the actual module being instrumented to change what require returns.

  • wrapExport(nodule, spec)
Inherited From:
Source:
Parameters:
Name Type Description
nodule *

The original export to replace with our new one.

spec WrapFunction

A wrapper function. The return value from this spec is what will replace the export.

Returns:
Type:
*

The return value from spec.

wrapMiddlewareMounter(nodule, propertiesopt, specopt) → {Object|function}

Wraps a method that is used to add middleware to a server. The middleware can then be recorded as metrics.

  • wrapMiddlewareMounter(nodule, properties [, spec])
  • wrapMiddlewareMounter(func [, spec])
Source:
See:
Parameters:
Name Type Attributes Description
nodule Object | function

The source for the properties to wrap, or a single function to wrap.

properties string | Array.<string> <optional>

One or more properties to wrap. If omitted, the nodule parameter is assumed to be the function to wrap.

spec MiddlewareMounterSpec <optional>

Spec describing the parameters for this middleware mount point.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its properties.

wrapReturn(nodule, propertiesopt, spec, argsopt) → {Object|function}

Executes the provided spec with the return value of the given properties.

  • wrapReturn(nodule, properties, spec [, args])
  • wrapReturn(func, spec [, args])

If the wrapper is executed with new then the wrapped function will also be called with new. This feature should only be used with factory methods disguised as classes. Normally Shim#wrapClass should be used to wrap constructors instead.

Inherited From:
Source:
See:
Parameters:
Name Type Attributes Default Description
nodule Object | function

The source for the properties to wrap, or a single function to wrap.

properties string | Array.<string> <optional>

One or more properties to wrap. If omitted, the nodule parameter is assumed to be the function to wrap.

spec Spec | WrapReturnFunction

The spec for wrapping the returned value from the properties.

args Array.<*> <optional>
[]

Optional extra arguments to be sent to the spec when executing it.

Returns:
Type:
Object | function

The first parameter to this function, after wrapping it or its properties.