Node.js Release Notes

Node.js Agent Release Notes

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.

Improvements

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.

Notes

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.

Improvements

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.

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.

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.

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.

Improvements

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.

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.

Improvements

Bug fixes

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.

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.

Improvements

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.

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.

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.

Bug fixes

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.

Improvements

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

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!

New features

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.

Notes

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.

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.

Fixes

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.