Skip to content

Latest commit

 

History

History
271 lines (188 loc) · 11.3 KB

Migration Guide.md

File metadata and controls

271 lines (188 loc) · 11.3 KB
Raw

Migration Guide

This guide is intended to help with upgrading major versions of the Node Agent. This information can also be found on our documentation website.

Upgrading to Agent v5

Breaking Changes

Removed deprecated API methods: The following API methods had been marked as deprecated since agent v2, and have now been fully removed from the codebase:

  • newrelic.addCustomParameter()

    Replace with newrelic.addCustomAttribute().

  • newrelic.addCustomParameters()

    Replace with newrelic.addCustomAttributes().

  • newrelic.createWebTransaction()

    Replace with newrelic.startWebTransaction() and newrelic.getTransaction().

  • newrelic.createBackgroundTransaction()

    Replace with newrelic.startBackgroundTransaction() and newrelic.getTransaction().

  • newrelic.createTracer()

    Replace with newrelic.startSegment().

Removed ignore_server_configuration setting: This setting was only implemented by the Node agent, so removing it improves parity with other language agents.

Removed node-cassandra-cql instrumentation: This library has not been updated in 5 years, and has since been superseded by cassandra-driver, which is supported by the agent.

Removed deprecated configuration settings: The following configuration settings have been deprecated since agent v3, and have now been removed from the codebase:

  • capture_params

    Replaced with attributes.enabled. By default, request attributes are not sent to New Relic. Set attributes.enabled: true to include agent-defined or custom attributes in traces.

  • ignored_params

    Replaced with attributes.exclude. Add any request attribute keys to the attributes.exclude list. Now, instead of having to be an exact match, wildcards (*) may be appended to each item for broader filtering.

Updated custom metric naming: Custom metrics are now prefixed with Custom/. Existing insights queries may need to be addressed moving forward.

Node Version Support

The agent now only supports Node version 6 and above, which brings it up to date with Node's LTS schedule. Customers running Node 4.x or 5.x will need to upgrade to a supported version of Node or remain on the v4 agent.

Released Feature Flags

  • custom_instrumentation: This feature is no longer configurable.
  • custom_metrics: This feature is no longer configurable.
  • synthetics: This feature is no longer configurable.
  • native_metrics: This feature is now controlled by the plugins.native_metrics.enabled configuration value.

Upgrading to Agent v4

Breaking Changes

Upgraded https-proxy-agent from v0 to v2: This dependency has been updated due to a security issue in the version of https-proxy-agent the New Relic Node.js agent used. https-proxy v2 is incompatible with node v0.10 and v0.12, requiring deprecation of those versions for the agent. There is no required action to migrate from v3 to v4 of New Relic's Node.js agent.

Node Version Support

The earliest version of Node supported by the v4 agent is 4. Node 0.10 and 0.12, which have not been updated since February of 2017, are not supported by v4. Customers running Node 0.10 or 0.12 will need to upgrade to a supported version of Node or remain on the v3 agent.

Node 4 is also no longer receiving updates, but we will continue to support this version of Node for the time being. We highly recommend moving to a newer version of Node as soon as possible. The next major version of the New Relic Node Agent will likely remove support for it.

Upgrading to Agent v3

Breaking Changes

Removed SSL configuration: The agent will always connect to New Relic servers using TLS to encrypt communications. The ssl configuration value and NEW_RELIC_USE_SSL environment value are ignored. If set to any value other than true, a warning is logged and the value is ignored.

Request parameters now prefixed with request.parameters.: Any request parameters, such as route (/user/:userId) or query (/user?userId=123) parameters will now be prefixed with request.parameters. when collected. For example, the route parameter from /user/:userId would be collected as request.parameters.userId.

Any Insights dashboards, Alerts, or other NRQL queries using these attributes must be updated to look for the new attributes instead.

Released Feature Flags

  • send_request_uri_attribute: This feature is no longer configurable.

Upgrading to Agent v2

Breaking Changes

Reversed naming and ignore rules: Previously, rules defined in the config properties rules.name and rules.ignore were applied in reverse order, the first rule in the list was applied last. Agent v2 now applies rules in the order they are defined, so the first rule in the list is applied first.

Users of naming rules in the v1 agent will need to reverse the order of their rules in the configuration if they're noticing any issues.

De-duplicated HTTP request transactions: The v1 agent starts a new transaction for each listener on an HTTP server's request event. In applications with multiple listeners on the request event this would result in extraneous transactions being created that almost always did not get named correctly. In v2 the agent only creates a single transaction for each request event emitted.

Any users who utilized multiple request event listeners and added a call to newrelic.ignoreTransaction() to remove the extra transactions should remove those calls.

Stopped swallowing outbound request errors: In v1 the Node Agent swallows unhandled error events emitted by outbound HTTP request objects. Agent v2 removed this behavior in favor of not changing normal Node execution, meaning the error event will always be emitted.

If you are making outbound requests and currently do not listen for the error event, add a listener and handle the error as appropriate for your application.

Updated configuration options

In newrelic.js, edit the configuration properties you use for compatibility with the latest versions:

  • capture_params

    Replaced with attributes.enabled. By default, request attributes are not sent to New Relic. Set attributes.enabled: true to include agent-defined or custom attributes in traces.

  • ignored_params

    Replaced with attributes.exclude. Add any request attribute keys to the attributes.exclude list. Now, instead of having to be an exact match, wildcards (*) may be appended to each item for broader filtering.

NOTE: The new properties also have overrides for specific destinations (transaction_tracer, transaction_events, error_collector, and browser_monitoring). For example, setting transaction_tracer.attributes.enabled: false, would restrict attributes from being collected in transaction traces, while still allowing them for all others, assuming the root attributes.enabled is true. Please see Node.js agent configuration for more details.

Deprecated API Methods

These methods have been marked as deprecated in Agent v2 and will be removed in v3.

  • newrelic.createWebTransaction()

    Replace with newrelic.startWebTransaction() and newrelic.getTransaction().

  • newrelic.createBackgroundTransaction()

    Replace with newrelic.startBackgroundTransaction() and newrelic.getTransaction().

  • newrelic.addCustomParameter()

    Replace with newrelic.addCustomAttribute().

  • newrelic.addCustomParameters()

    Replace with newrelic.addCustomAttributes().

New API Methods

Node Version Support

The earliest version of Node supported by the v2 agent is 0.10. Node 0.8, which has not been updated since July of 2014, is not supported by v2. Customers running Node 0.8 will need to upgrade to a supported version of Node or remain on the v1 agent. Node 0.10 is also no longer receiving updates, but we will continue to support this version of Node for the time being. We highly recommend moving to a newer version of Node as soon as possible. The next major version of the New Relic Node Agent will likely remove support for it.

npm Version Support

The agent now requires npm version 2.0.0 or higher. This version of npm comes packaged with Node 0.10.44 or higher. If you are using an earlier version of Node 0.10 you will need to first install npm 2.0.0 or higher or upgrade to a newer version of Node. Version 2 of npm can be installed with:

$ npm install --global npm@2

Released Feature Flags

  • express_segments: This feature is no longer configurable.
  • cat: This feature is now controlled by the cross_application_tracer.enabled configuration value.

New Framework Minimum Versions

Module Old Minimum New Minimum
express 2.0.0 4.6.0
mysql 0.9.0 2.0.0