WebFrameworkShim

The agent associated with this shim.

The logger for this shim.

The transaction tracer in use by the agent for the shim.

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.

Sets the given segment as the active one for the duration of the function's execution.

• applySegment(func, segment, full, context, args[, inContextCB])

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.

Assigns id to shim instance. If shimName is present it will reuse an id otherwise it'll create a unique id.

Assigns the shim id and original on the wrapped item. TODO: Once all wrapping is converted to proxies, we won't need to set this property as the trap on 'get' will return the original for symbols.original. For now, we have to prevent setting this on original.

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

• bindCallbackSegment(spec, args, cbIdx [, segment])
• bindCallbackSegment(spec, obj, property [, segment])

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

• bindCreateTransaction(nodule, property, spec)
• bindCreateTransaction(func, spec)

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

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.

Copies the given parameters onto the segment, respecting the current agent configuration.

Creates a new segment.

• createSegment(opts)
• createSegment(name [, recorder] [, parent])

Adds several properties to the given object.

Defines a read-only property on the given object.

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

Entry point for executing a spec.

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).

Determine the name of an object.

Retrieves the original method for a wrapped function.

• getOriginal(nodule, property)
• getOriginal(func)

Retrieves the value of symbols.original on the wrapped function. Unlike getOriginal this just looks in the direct wrapped function

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

• getSegment([obj])

Adds CAT headers for an outbound response.

• insertCATReplyHeaders(headers [, useAlternateHeaderNames])

Adds CAT headers for an outbound request.

• insertCATRequestHeaders(headers [, useAlternateHeaderNames])

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

Determines if the given object exists and is an array.

Determines if function is an async function. Note it does not test if the return value of function is a promise or async function

Determines if the given object is a boolean literal.

Determines if the given object exists and is a function.

Determines if the given value is null.

Determines if the given object is a number literal.

Determines if the given object is an Object.

Determines if the given object is a promise instance.

Determines if the given object exists and is a string.

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

• isWrapped(nodule, property)
• isWrapped(func)

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.

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.

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

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.

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.

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

Pushes a new path segment onto the transaction naming stack.

• pushTransactionName(pathSegment)

Transactions are named for the middlware that sends the response. 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.

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.

Records the provided function as a middleware.

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

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.

Records calls to methods used for rendering views.

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

Marks the current path as a potential responder.

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)

Performs a shallow copy of each property from defaults only if obj does not already have that property, or the value of the key on obj is null.

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

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.

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

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

• setRouteParser(parser)

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.

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

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

Associates a segment with the given object.

• storeSegment(obj [, segment])

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

Converts an array-like object into an array.

Unwraps one item, revealing the underlying value. If item is wrapped multiple times, the unwrap will not occur as we cannot safely unwrap.

• unwrap(nodule, property)
• unwrap(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.

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.

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

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

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

• wrapExport(nodule, spec)

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.