Node.js release notes

Monday, June 11, 2018 - 12:39


  • Make require() statements explicitly reference package.json as a .json file.

This solves a problem when requiring/importing newrelic from a Typescript file.

  • Check if process.mainModule.filename exists before using in missing config file check.

When the agent is preloaded with Node's --require flag, mainModule is not yet defined when the agent checks for a config file, resulting in a TypeError in the event that no config file exists. Defaulting to the file path being executed in process.argv ensures that the app will not crash when preloaded without a config file.

  • Updated dev dependency tap to v12.0.1.

  • Fixed identification of errors with express.

Previously the call next('router') was considered an error. This is actually valid usage of express and will no longer generate an error.

  • Removed debug.internal_metrics configuration.

This legacy debug configuration was never used since trace-level logging provides everything this did and more.

  • Upgraded optional dependency @newrelic/native-metrics to v3.

With this update comes pre-built binaries for Node 5 and 7. GC metrics are also now aggregated in C++ until the agent is ready to harvest them instead of hopping into JS for each event.

  • Added additional checks to uninstrumented ensuring that files with names matching instrumented modules do not result in a false uninstrumented status.

For example, some users load config/env info before the agent. In that case, a file responsible for exporting DB config information (config/redis.js), may result in a false uninstrumented status, because the agent would interpret redis.js as the module itself.

Tuesday, May 29, 2018 - 15:21


  • Fixed metric merging when using debug.internal_metrics.

    The debug metrics cache would cause timestamps for harvested metrics to get stuck at agent startup. This will no longer happen, and the debug cache is reset each harvest.


  • Modularized configuration constants to improve readability.
Tuesday, May 22, 2018 - 14:13


  • Updated use of fs.unlink without a callback to fs.unlinkSync.

    As of Node v10, the callback is no longer optional, which was causing a false test failure.

  • Fixed access to properties on promisified methods.

Tuesday, May 15, 2018 - 13:40 Download


  • Optimized unhandledRejection reporting when using async_hooks.

  • Replaced all uses of util._extend with Object.assign.

  • Completed TODOs regarding the Node 0.10 and 0.12 deprecation.

  • Added PriorityQueue serialization benchmarks.

Bug fixes

  • The agent no longer resizes the metric timeslice start time to be the earliest start time of the transactions that finish during the timeslice.

  • Background transactions created may now be named through API#setTransactionName.

    Previously, the agent didn't respect the transaction naming precedence for background transactions. Background transaction naming behavior is now in line with web transaction behavior.

  • Logger no longer tries to create very large log messages.

    When a message is created that would be too large to log, a process warning is emitted.

  • The agent will now respect event count limits when merging data from a failed send.

    Previously, when merging data into an event pool the agent wouldn't maintain the size limit of the reservoir.

  • Added check for a route prefix when wrapping Hapi route handlers.

    Previously, route prefixes specified via plugin options weren't being included in transaction names. Now, if the agent finds a route prefix associated with a given realm, it is prepended to the route path in the transaction name.

Monday, April 23, 2018 - 15:06


  • Added PriorityQueue class for collecting events.

    This replaces the Reservoir class for event sampling. Using priority sampling allows the agent to maintain randomness across a given time period while improving the chances that events will be coordinated across Transaction, Error, and Custom event pools.

  • The agent will now allow external instrumentation modules to fail in a safe way.

    Previously, the agent would stop running if an externally loaded instrumentation failed for any reason. Due to the way external instrumentations can be updated independently, the agent should allow them to fail and carry on after logging a warning.

  • Added the strip_exception_messages.enabled config option.

    The agent can now be configured to redact error messages on collected errors.

  • Added the attributes.include_enabled config option.

    The agent can now be configured to disallow attribute include patterns to be specified.


  • Updated logic around wrapping route handlers when config object is present.

    Before, the agent would only attempt to wrap config.handler when any config object was present, without defaulting to the root handler if it didn't exist.

Thursday, April 12, 2018 - 00:00


  • BREAKING: Updated the version of https-proxy-agent to v2.x - Dropped support for v0.10 and v0.12 of node.

    The version of https-proxy-agent used in the agent has a known security issue you can read about here: In order to resolve this issue, the dependency had to be updated to at least v2.2.0, which only supported node versions >=4. The update to this dependency forces the incompatibility of the agent with versions 0.10 and 0.12 of node.

    In order to use use the Node.js agent, please upgrade node to version >=4, or you can continue to use the agent on node versions 0.10 and 0.12 by pinning the agent to v3.

    You can read more about the issue here:

Tuesday, April 10, 2018 - 00:00


  • Added a type check to attribute validation, restricting values to primitive types (but not undefined).

    Previously the agent was only enforcing byte limits on string values, resulting in overly large arrays being collected. This brings the agent in line with other language agents.

  • The DatastoreShim will now respect specified after handlers.

    Previously on methods like DatastoreShim#recordQuery the after handler would be dropped. The property is now correctly propagated to the underlying Shim#record call.

  • The agent will now check that a specified parent segment is part of an active segment before running a method under instrumentation.

    Previously the agent would unconditionally run a method under a specified parent. The shim expects the parent to exist and be active, and will throw errors in the case where the parent belongs to an inactive transaction.

Tuesday, March 27, 2018 - 15:04

New features

  • Added newrelic.startSegment(), which replaces newrelic.createTracer().

    This new API method allows you to create custom segments using either callbacks or promises.

Bug fixes

  • Fixed bug in pre route config option in Hapi instrumentation.

    Only applies to Hapi v16 and below. The pre handler wrapping was not properly returning in cases when the element was a string referring to a registered server method, and as a result these elements would be replaced with undefined.

Wednesday, March 14, 2018 - 12:41

New features

  • Added @newrelic/koa as a dependency.

    This introduces instrumentation for Koa v2.0.0 or higher. It will be treated as first-party instrumentation within the agent, but publishing it as a separate module allows it to be installed independently according to users' needs.


  • Refactored instrumentation hooks to work with modules.

    With this change it is now possible to link against external instrumentation modules.

Tuesday, March 13, 2018 - 15:10 Download


  • Promise based web framework middleware instrumentation now supports callback based sequencing.

    Previously, a promise based middleware was assumed to continue to the next middleware once the promise it returned resolved. This assumption has been relaxed to allow for a callback to be supplied to the middleware to invoke the next middleware.

Wednesday, March 7, 2018 - 10:44 Download


  • Removed the ssl configuration option.

    TLS is now always used in communication with New Relic Servers. The ssl configuration value and NEW_RELIC_USE_SSL environment value are no longer used. Setting either value to anything other than true will result in a warning.

  • Security bulletin NR18-05:

    Fixes issue introduced in 2.8.0 where the agent may have captured all transaction attributes, even with High Security Mode enabled on the account. This may have included sensitive data attached to transactions.

  • All request parameters now prefixed with request.parameters..

    Previously request parameters such as route and query parameters were added as attributes without any name changes. For example /foo?bar=value would add the attribute bar to the transaction. Now this attribute would be named

    Any Insights dashboards, alerts, or other NRQL queries using these attributes must be updated to use the new attribute names.

  • Adds support for EU Datacenter

Monday, March 5, 2018 - 10:51 Download

Bug fixes

  • Security bulletin NR18-06:

    Fixes issue introduced in 2.8.0 where the agent may have captured all transaction attributes, even with High Security Mode enabled on the account. This may have included sensitive data attached to transactions.

  • Removed support for agent attributes include/exclude rules.

    These will be coming back in Node Agent v3.0.0. The fix for the above security bulletin required a backwards incompatible change to our attributes.

  • Fixed bug in Bluebird instrumentation.

    Some methods were not instrumented correctly. This would cause a problem if a function was passed to these methods.

    Special thanks to Andreas Lind (@papandreou) for helping us find this bug.

Tuesday, February 27, 2018 - 11:24 Download


This release is deprecated due to an issue where the agent may capture transaction attributes regardless of agent settings. If you are using this release, upgrade your agent to agent version 2.9.1 or higher. For more information, see Security Bulletin NR18-06.


  • Added the WebFrameworkShim#savePossibleTransactionName method.

    This method may be used to mark the current running middleware as a potential responder. savePossibleTransactionName should be used if a middleware can't be determined to be a terminal middleware while it executes, but may be responsible for responding after execution has finished.

  • Fixed dns.resolve results assertion.

  • Expanded async_hooks tests around maintain transaction context.

  • Added Koa to metric naming objects.

  • Added callback prop to middlewareWithPromiseRecorder return spec.

    While we aren't actually wrapping any callback, this is a workaround that gives us access to the active segment. This ensures that all segments inside Koa transaction traces are named correctly, particularly in cases when transaction context may be lost.

  • Updated after prop in middlewareWithPromiseRecorder return spec to set txInfo.errorHandled = true in cases when there is no error.

    Because Koa has no concept of errorware in the same sense as Express or Connect ((err, req, res, next)), the agent now assumes if a middleware resolves, any error that may have occurred can be marked as handled.


  • Added check for parentSegment in async_hooks instrumentation, to help ensure that transaction context is maintained.
Wednesday, February 21, 2018 - 10:00 Download


This release is deprecated due to an issue where the agent may capture transaction attributes regardless of agent settings. If you are using this release, upgrade your agent to agent version 2.9.1 or higher. For more information, see Security Bulletin NR18-06.

New features

  • Added instrumentation support for MongoDB version 3.

    Version 3 of mongodb is now supported. Previously datastore host information (instance metrics) was incorrectly captured by the agent with mongodb v3. This has been fixed and all features should be functional now.


  • Updated documentation for apdex_t setting and removed environment variable.

    This was never configurable on client side and the documentation was misleading.

  • Documented environment variables for slow_sql configurations.

    Thanks to Olivier Tassinari (@oliviertassinari) for the update!

  • Updated hapi/hapi-pre-17/package.json to run errors.tap.js in more versions.

  • Added internal cache to unwrapped core modules for agent use.

  • Improved logging around environment facts gathering.

Bug fixes

  • Enable certain agent attributes when high security mode is enabled.

    During the switch from the old capture_params/ignored_params to the new attribute include/exclude rules, high security mode was over-zealous in what attributes it disallowed. This has been trimmed back to be in line with other agents.

Wednesday, February 7, 2018 - 14:57 Download


  • Changed attributes.enabled to true by default.

    In the previous version we defaulted this to false to maintain parity with capture_params which defaulted to false. However, this is a invalid parity because attribute.enabled controls more attributes than capture_params.


  • Removed unnecessary checks around Timer.unref() calls.

    unref has been supported since Node v0.9, meaning it will always be present in timers set by the agent (with 0.10 being the earliest supported version).

  • Added a split in the node versions for the mysql2 and cassandra versioned tests.

    As of mysql2 v1.3.1 and cassandra v3.4.0 the minimum supported version of Node is 4.

  • Replaced as many instances of {} as possible with Object.create(null).

  • Removed extraneous logger arg in addCustomAttribute call.

Bug fixes

  • The agent will no longer generate browser data for ignored transactions.

  • Expanded Hapi instrumentation to support route pre handlers.

    This is a Hapi route config option that was previously uninstrumented, causing transaction names to become invalid. This expanded instrumentation ensures that all additional handlers are wrapped and associated with the main route.

Thursday, February 1, 2018 - 09:43 Download

New features

  • Added agent attribute filtering via include and exclude rules.

    Agent attributes can now be controlled using fine grained include and exclude rules. These rules, described below, replace capture_params and ignored_params. Any attributes listed in ignored_params will be migrated to attributes.exclude internally, unless attributes.exclude is explicitly set.

    There are three new configuration properties added to the root config and each destination (more on destinations later). These new configurations are:

    • attributes.enabled - Enables collection of attributes for the destination.
    • attributes.include - A list of attributes or wildcard rules to include.
    • attributes.exclude - A list of attributes or wildcard rules to exclude.

    The include and exclude rules can be exact rules (for example request.headers.contentLength), or wildcard rules which match just the beginning of attribute keys (for example request.headers.* would match any request header).

    These rules can be specified globally at the root of the configuration, or for specific destinations. These destinations are:

    • transaction_tracer - Controls transaction trace attributes.
    • transaction_events - Controls transaction event attributes.
    • error_collector - Controls error event attributes.
    • browser_monitoring - Controls browser/RUM transaction attributes.
  • Renamed addCustomParameter to addCustomAttribute.

    The addCustomParameter method is now deprecated and will be removed in a future release of the agent. The addCustomAttribute method is a drop-in replacement for it.

  • Added cache to agent attribute filtering.

    To minimize the overhead of applying attribute rules, the agent caches results of filtering specific attribute keys and destinations. The cache is limited to 1000 destination-key pairs by default but can be configured with attributes.filter_cache_limit. This cache offers a 10x improvement for applying filter rules for cache-hits.

  • Added allow_all_headers to config options and updated http instrumentation.

    When set to true, the agent will collect all request headers. This collection respects the agent attribute include and exclude rules. A default set of exclusion rules are provided in newrelic.js. These rules exclude all cookies and authentication headers.

  • Segments may now be flagged as opaque, causing internal segments to be omitted from the transaction trace.


  • Added limits for agent attributes to keep monitoring overhead down.

    Attribute keys and values are limited to 255 bytes each. Keys which are larger than 255 bytes are dropped, and a warning message is logged. Values larger than 255 bytes are truncated to 255 bytes, respecting multi-byte UTF-8 encoding. Custom attributes are limited to 64 per transaction. Attributes beyond the 64th are silently ignored.

  • Added error to collector connection failure log message.

  • Renamed request_uri attribute to request.uri.

    This brings the attribute name in line with all other request attributes.

  • Updated https-proxy-agent dependency from ^0.3.5 to ^0.3.6.

  • Updated versioned tests where applicable to ensure most minor versions of instrumented modules work as expected.

  • Fixed stalling test for v1 line of Mongo driver.

  • Added tests verifying Hapi 404 transactions result in correctly named metrics.

    The Hapi instrumentation was doing the correct thing, but we did not have tests for this specific case.

Bug fixes

  • The agent will no longer crash when crypto.DEFAULT_ENCODING has been changed.

    Previously, the agent would assume the result of hash.digest() was an instance of a Buffer. If crypto.DEFAULT_ENCODING is changed, hash.digest() will return a string and the agent would crash. The agent now ensures that the value is a Buffer instance before moving on.

  • Fixed error if process.config.variables.node_prefix missing.

    If process.config.variables.node_prefix is falsey (which can happen if using electron, leading to this issue the getGlobalPackages function in lib/environment.js will give an err when it shouldn't.

    Thanks to Jarred Filmer (@BrighTide) for the fix!

Thursday, January 18, 2018 - 10:28 Download


  • Added regression test for promise instrumentation and stack overflows.

Bug fixes

  • Fixed naming bug in Restify instrumentation regarding parameters to next.

    The instrumentation previously considered any truthy value passed to next to be an error. It is possible to pass a string or boolean to next in Restify to control further routing of the request. This would cause the middleware's mounting path to be erroneously appended to the transaction name.

  • Fixed access to bluebird.coroutine.addYieldHandler.

    This was accidentally not copied by our instrumentation making access to the function fail. This has been resolved and tests expanded to ensure no other properties were missed.

Wednesday, January 10, 2018 - 11:27 Download

New features

  • Added transaction_tracer.hide_internals configuration.

    This configuration controls the enumerability of the internal properties of the agent. Making these properties non-enumerable can have an impact on the performance of the agent. Disabling this option may decrease agent overhead.


  • Refactored promise instrumentation.

    This new instrumentation is far more performant than the previous and maintains a more sensible trace structure under a wider range of sequences.

  • Added concurrent environment scanning, limited to 2 reads at a time.

    This improves the performance of dependency scanning at agent startup, allowing the agent to connect to our services more quickly.

  • Refactored instrumentation tests to run against wide range of module versions.

    Instrumentation tests will be run against all supported major versions of every instrumented module. For releases, we will test against every supported minor version of the modules. This vastly improves our test coverage and should reduce the instances of regressions for specific versions of modules.

  • Added tests for all of bluebird's promise methods.

    These tests ensure that we 100% instrument bluebird. Some gaps in instrumentation were found and fixed. Anyone using bluebird should upgrade.

Bug fixes

  • Fixed a crashing error in the hapi instrumentation.

    When recording the execution of an extension listening to a server event (for example, 'onPreStart') the agent would crash due to the lack of a raw property on the first argument passed to the extension handler. The agent now checks the event before wrapping the extension handler and checks for the existence of the raw property before attempting to dereference off of it.

  • Fixed an incompatibility with the npm module mimic-response.

    The agent's HTTP instrumentation previously did not play well with the way mimic-response copied properties from an http.IncomingMessage. This caused modules that relied on that process, such as got, to hang.

  • Fixed naming rule testing tool to use same url scrubbing as the agent itself.

Wednesday, January 3, 2018 - 11:08 Download

New features

  • Added hapi v17 instrumentation

    Hapi v17 added support for promise-based middleware which broke transaction tracking in the agent. This caused issues in naming, as the agent will name the transaction after the path to the middleware that responded to a request.

  • Added instrumentation for vision@5

    Due to the way vision is mounted to the hapi server when using hapi v17.x, the agent's instrumentation would not pick up on the middleware being mounted. This new instrumentation now correctly times rendering done in the vision middleware.

  • Added unwrapOnce method to shim object

    This new method can be used to unwrap a single layer of instrumentation. unwrapOnce is useful in cases where multiple instrumentations wrap the same method and unwrapping of the top level is required.

  • Added isErrorWare checks around nameState.appendPath/nameState.popPath calls to avoid doubling up paths in transaction names

    Previously, the agent would append its transaction name with the path fragment where an error handler middleware was mounted. The extraneous path fragment will now be omitted, and the transaction will be named properly after the middleware that threw the error.

  • Added support for pg 6 on Node 5 or higher


  • Added parent property to webframework-shim segment description

  • Refactored existing hapi instrumentation for different server.ext() invocations

  • Refactored webframework-shim _recordMiddleware to construct different segment descriptions for callback- or promise-based middleware

  • Updated node-postgres@^6 versioned tests to avoid deprecation warning on direct module connect and end calls

  • Fixed running domain tests on Node 9.3.0.

  • Improved logging for CAT headers and transaction name-state management.

  • All json-safe-stringify calls now wrapped in try/catch

  • Removed lib/util/safe-json

Bug fixes

  • Fixed creating supportability metric when mysql2 goes uninstrumented.

  • Added a segmentStack.popto the middleware after in cases when an error is caught and there is no next handler

  • Fixed determining parents for middleware segments when transaction state is lost and reinstated

  • Added check to _recordMiddleware to avoid prepending a slash if original route is an array

  • Changed logic in http instrumentation to attach response.status to the transaction as a string

  • Updated startWebTransaction and startBackgroundTransaction to add nested transactions as segments to parent transactions

Tuesday, December 12, 2017 - 10:28 Download


  • Added Peter Svetlichny to the contributors list!


  • Optimized NameState#getPath.

  • Optimized shim.record.

  • Optimized shim.recordMiddleware.

  • Upgraded eslint to v4.

Bug fixes

  • Fixed parsing SQL for queries containing newlines.