Node.js Release Notes

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.
Tuesday, November 28, 2017 - 12:28 Download


  • Added promise benchmarks to test non-async_hooks instrumentation.

  • Added logging for external calls made outside of a transaction.

  • Added logging for when unhandledRejection is noticed.

  • Improved performance of creating and merging metrics.

  • Improved performance of tracer.bindFunction.

  • Removed try-catch around internal property setting on older versions of Node.

Bug fixes

  • Moved require calls for vendor metadata to module-level.
Wednesday, November 15, 2017 - 10:21 Download

New features

  • Instrumentation will now only modify the arity of wrapped functions when needed.

    This can be controlled with the matchArity property on a WrapSpec. Disabling arity matching has a significant, positive impact on the performance of instrumentation.


  • Added benchmarks for shimmer methods.

  • Pinned hapi tests at v16 due to incompatibility in hapi v17 with Node.js versions <8.

  • The agent's parsed queries will now only hold onto the stack that the query was made at, instead of an error object instance.

    Previously, the parsed query objects would hold onto an error instance, which would in turn hold onto references to all the functions in the stack when the error was created. This could cause memory issues if the functions were holding onto references to other pieces of data.

Bug fixes

  • Revert wrapping of https for Node ^8.9.1.

    The original cause for this problem was reverted by Node.

Thursday, November 2, 2017 - 10:20 Download


  • Added Node 9 to test suite.

  • Removed problematic tests for ancient version of Hapi (7.1).

  • Document purpose of throw in tracer to prevent developer confusion.

  • Added script for running agent micro benchmarks.

  • Added benchmarks for all the Shim and Tracer methods.

Bug fixes

  • Fixed a bug with Node >=8.9 that prevented https externals from being recorded.
Tuesday, October 24, 2017 - 10:20 Download


  • Agent will attempt to reconnect to the collector forever after backing off to 5 minute delays.

Bug fixes

  • Refactored environment scan to improve startup time and fix cyclical symlink resolving.
Monday, October 16, 2017 - 12:56 Download

New features


  • Added benchmark for performance of function wrapping.

  • Added Garbage Collection information to async_hooks benchmark.

  • Improved trace-level logging for capturing queries.

  • Added cases for omitting the agent with and without async hooks to the async hooks microbenchmark.

Bug fixes

  • Pinned version of Mocha to 3.x due to the incompatibility of Mocha v4 and Node v0.10 and v0.12.
Tuesday, September 26, 2017 - 14:45 Download

Bug fixes

  • Hapi handlers will now preserve the defaults associated with them.

    Previously when wrapping handlers, the agent would drop the associated defaults on the ground, these are now properly forwarded to the wrapper. Big thanks to Sean Parmelee (@seanparmelee) for finding the root cause of this bug and reporting it!

  • Fixed starting the agent with an invalid process version.

  • Pinned request version for testing old versions of Node.

  • Added tests for feature flags created at agent initialization.

Monday, September 11, 2017 - 13:40 Download


  • Added metrics for enabled/disabled feature flags.

Bug fixes

  • Fixed transaction naming for Hapi plugins.

Thanks to Marc Höffl (@KeKs0r) for providing a reproduction!

Wednesday, August 23, 2017 - 11:17 Download

New features

  • Added support for ignoring ranges of status codes.

    The configuration error_collector.ignore_status_codes can now take ranges of numbers. For example, ignore_status_codes: ['400-404'] would ignore 400, 401, 402, 403, and 404.

  • Experimental instrumentation for async/await

    This is experimental instrumentation and has not yet been tested in a wide array of production environments. The feature is currently off by default behind a feature flag. To enable this experimental instrumentation, add await_support: true to the feature_flag setting in your agent config file.


  • Updated examples and documentation regarding custom transaction creation.

    All examples and documentation now point at the newrelic.start*Transaction methods.

  • Transaction state is now maintained in ChildProcess event listeners.

  • Reducing logging verbosity in the SQL query obfuscator.

Bug fixes

  • Fixed a bug when a custom collector port was provided in the configuration that prevented redirected connections from working.

  • Fixed a bug in Shim#record that could cause an exception when trying to create a new segment as part of an ended/inactive transaction.

  • Fixed issue with custom Hapi handlers causing an error.

    Previously custom Hapi handlers defined using the server.handler() method were causing the Hapi server to return a 500 error. Now they are correctly handled and recorded as middleware functions.

Tuesday, August 8, 2017 - 11:28 Download


  • Improved metadata collection for AWS, Azure, GCE, and Pivotal Cloud Foundry.

Bug fixes

  • Fixed a bug in PG query obfuscation for $ placeholders.

    The agent used to mis-detect $1 value placeholders as unmatched dollar-quoted strings causing the whole query to be obfuscated to just ?. These placeholders are now correctly detected and obfuscated.

Tuesday, August 1, 2017 - 13:01 Download


  • Improved documentation for newrelic.start*Transaction and TransactionHandle.

    Formatting for the startWebTransaction and startBackgroundTransaction methods was fixed and documentation for the TransactionHandle class which getTransaction returns was added.

Bug fixes

  • Fixed parsing the table name from SQL queries.

    Quotes around the table name are now stripped after parsing the query and before constructing the metrics.

  • Fixed unhandled rejection error caused by ioredis instrumentation.

Tuesday, July 25, 2017 - 14:34 Download

Bug fixes

  • Fixed issue with transaction events not including correct duration values.

    This issue was introduced in v2.0.0, and it has affected web transactions histogram and percentile charts.

  • Fixed issue with Redis instrumentation causing the agent to crash in some cases.

    Previously, the Redis instrumentation would crash the agent when Redis commands were called without a callback and after the transaction has ended.

  • Fixed issue with the agent crashing on Node v4.0-4.4 and v5.0-5.9.

    This issue was caused by incorrect shim for Buffer.from(), and it affected older minor versions of Node v4 and v5.

Tuesday, July 18, 2017 - 01:00 Download


  • The New Relic Node Agent v2 is here!

    This release contains major changes to the agent instrumentation API, making it easier to create and distribute your own instrumentation for third party modules. Check out Upgrade the Node agent or the Migration Guide for more information on upgrading your application to this version.

  • BREAKING: Reversed naming and ignore rules.

    Naming rules are now applied in the order they are defined.

  • BREAKING: De-duplicated HTTP request transactions.

    Only one transaction is created per request event emitted by an HTTP server. Previously this was one transaction per listener per event emitted.

  • BREAKING: Stopped swallowing outbound request errors.

    Errors emitted by outbound HTTP requests will no longer be swallowed by the agent.

  • BREAKING: Node v0.8 is no longer supported. Minimum version is now v0.10.

    The v1 agent will continue to support Node 0.8 but will no longer receive updates.

  • BREAKING: npm v1 is no longer supported. Minimum version is now v2.0.0.

New features

  • Added API for writing messaging framework instrumentation.

    Introduced new MessageShim class for writing instrumentation. This shim can be accessed using the newrelic.instrumentMessages() API method.

  • Added amqplib instrumentation.

    Applications driven by amqplib consumers will now have transactions automatically created for consumed messages. See Troubleshoot message consumers for more information on this instrumentation and its limitations.

  • Advanced instrumentation API is now generally available.

    New methods for instrumenting common modules were introduced during the Agent v2 beta. These APIs are now available to everyone:

    • newrelic.instrument()/Shim: This method can be used to instrument generic modules, such as connection pooling libraries, task schedulers, or anything else not covered by a specialized class.

    • newrelic.instrumentDatastore()/DatastoreShim: This method is good for instrumenting datastore modules such as mongodb, mysql, or pg.

    • newrelic.instrumentWebframework()/WebFrameworkShim: This method is used for instrumenting web frameworks like restify or express.

    Documentation and tutorials for the new API can be found on our GitHub documentation page:


  • Rewrote built-in instrumentation using the new Shim classes.

    The following instrumentations have been rewritten:

    • Datastores
      • cassandra-driver
      • ioredis
      • memcached
      • mongodb
      • mysql
      • node-cassandra-cql
      • pg
      • redis
    • Web frameworks
      • director
      • express
      • hapi
      • restify
  • The @newrelic/native-metrics module is now included as an optional dependency.

    This module will be installed automatically with Agent v2. If it fails to install the agent will still function.

Wednesday, June 7, 2017 - 11:00 Download

New features

  • Node v8 is officially supported with the exception of async/await.

    Support for the new async/await keywords is coming in a future release. Until this support is added, New Relic does not support and highly discourages using the Node.js agent with applications that utilize async/await, as it could result in transaction state loss and data being mixed between transactions.


  • Fixed issues related to changes in the core networking modules that resulted in transaction state loss. Also instrumented new asynchronous API methods in crypto and inspector.
Thursday, May 11, 2017 - 14:15 Download

Bug fixes

  • Fixed a transaction state loss introduced in Node 7.10.0 when using net.createConnection.

    Added a new segment for net.connect, net.createConnection, and http.Agent#createConnection. Sockets created within a transaction also have their emit bound to the segment.

  • Fixed a typo about the name of the default configuration file. Thanks Jacob LeGrone (@jlegrone)!