• EnglishEspañol日本語한국어Português
  • Log inStart now

Node.js agent configuration

You can tailor the Node.js agent to your app's requirements by editing your newrelic.js config file or by setting an environment variable. The config file resides in the root directory of your app. You can also configure a few options from New Relic, or use the Node.js agent API.

Get started

You'll be able to configure our Node.js agent to suit your environment after you create a New Relic account (it's free, forever) and install the Node.js agent.

The license_key setting is required. Also, we highly recommend setting the app_name so that your app has a meaningful name instead of the default My Application.

Configuration methods and precedence

The primary method to configure the Node.js agent is the agent configuration file (newrelic.js). You can also configure most settings with environment variables. You can also adjust some settings with server-side configuration.

The Node.js agent uses this order of precedence for configuration methods:

Node.js configuration hierarchy: Server-side configuration settings override environment variables. Environment variables override the agent config file. The config file overrides the agent defaults.

Here are detailed descriptions of each configuration method:

Exports variables

This section defines the Node.js agent variables in the order they typically appear in the exports.config = { section of your app's newrelic.js configuration file.

Logging variables

This section defines the Node.js agent variables in the order they typically appear in the logging: { section of your app's newrelic.js configuration file.

AI monitoring

This section includes Node.js agent configurations for setting up AI monitoring.

Important

You must enable distributed tracing to capture AI data. It's turned on by default in Node.js agents 8.3.0 and higher. If you've enabled high security mode, AI monitoring will not work.

Audit logging

This section defines the Node.js agent variables in the order they typically appear in the audit_log: { section of your app's newrelic.js configuration file.

API configuration

This section allows you to choose which API methods are enabled. Each configuration option allows you to modularly enable API methods that are responsible for sending custom information to New Relic.

Important

All of these are set to false when the agent is in high-security mode.

Attributes

This section defines the variables for Node.js agent attributes in the order they typically appear in the attributes: { section of your app's newrelic.js configuration file.

Caution

Any header-related include/exclude rules must be in camelCase form to be filtered.

Error collector variables

You can manage how error are handled in New Relic. This section defines the Node.js agent variables in the order they typically appear in the error_collector: { section of your app's newrelic.js configuration file.

Transaction tracer variables

The agent groups your requests into transactions, which are used to:

  • Visualize where your app spends its time (in transaction breakdowns).
  • Identify slow requests.
  • Group metrics.
  • Isolate other issues, such as slow database performance.

This section defines the Node.js agent variables in the order they typically appear in the transaction_tracer: { section of your app's newrelic.js configuration file.

Important

Do not use brackets [suffix] at the end of your transaction name. New Relic automatically strips brackets from the name. Instead, use parentheses (suffix) or other symbols if needed.

Rules variables

This section defines the Node.js agent variables in the order they typically appear in the rules: { section of your app's newrelic.js configuration file.

Transaction events variables

This section defines the Node.js agent variables in the order they typically appear in the transaction_events: { section of your app's newrelic.js configuration file.

Browser monitoring variables

This section defines the Node.js agent variables in the order they typically appear in the browser_monitoring: { section of your app's newrelic.js configuration file.

Custom events variables

This section defines the Node.js agent variables in the order they typically appear in the custom_insights_events: { section of your app's newrelic.js configuration file.

Slow queries variables

This section defines the Node.js agent variables in the order they typically appear in the slow_sql: { section of your app's newrelic.js configuration file. These options control behavior for slow queries, but do not affect SQL nodes in transaction traces.

Custom hostname variables

This section defines the Node.js agent variables in the order they typically appear in the process_host: { section of your app's newrelic.js configuration file. These options control behavior regarding the host display name in the APM UI.

Datastore tracer variables

This section defines the Node.js agent variables in the order they typically appear in the datastore_tracer section of your app's newrelic.js configuration file. These options control behavior for collecting datastore instance metrics.

Cross application tracing (DEPRECATED)

The Node.js agent variables that control cross application tracing typically appear in the cross_application_tracer section of your app's newrelic.js configuration file:

Important

Cross application tracing has been deprecated in favor of Distributed tracing and will be removed in a future agent version.

Important

Cross application tracing (CAT) has been deprecated and will be removed in a future major release. For cross-service visibility, we recommend using distributed tracing, which is enabled by default as of agent version 8.3.0. Before enabling, read the transition guide.

Error message redaction variables

The Node.js agent variables that control error message redaction appear in the strip_exception_messages section of your app's newrelic.js configuration file:

Distributed tracing

Distributed tracing lets you see the path that a request takes as it travels through a distributed system. When configuring via the config file, place the following option in the distributed_tracing section. It is turned on by default in Node.js agents 8.3.0 and higher.

Important

Enabling distributed tracing disables cross application tracing, and has effects on other APM features. Before enabling, read the transition guide. Requires Node.js agent version 4.7.0 or higher.

For more information about setting up distributed tracing, see Enable distributed tracing for your Node.js applications.

gRPC server instrumentation

The grpc section controls the behavior of how the gRPC server is instrumented.

Span events

Span data is reported for distributed tracing. Distributed tracing must be enabled to report spans. Set span configuration in the span_events section. Options include:

Infinite Tracing

To turn on Infinite Tracing, add the settings below. Set Infinite Tracing configuration in the infinite_tracing section. Additionally, distributed tracing must be enabled. Note that distributed tracing is enabled by default for Node.js APM agent versions 8.3.0 and greater.

Application logging

The application logging configuration settings require Node.JS agent version 8.11.0 or higher.

For tips on configuring logs for the Node.js agent, see Configure Node.js logs in context.

Code level metrics

The code-level metrics configuration settings require Node.JS agent version 9.7.5 or higher.

For more details, see our code-level metrics docs.

Errors inbox configuration

Setting one of the following tags will help you identify which versions of your software are producing the errors.

  • NEW_RELIC_METADATA_SERVICE_VERSION will create tags.service.version on event data containing the version of your code that is deployed, in many cases a semantic version such as 1.2.3, but not always.
  • NEW_RELIC_METADATA_RELEASE_TAG will create tags.releaseTag on event data containing the release tag (such as v0.1.209 or release-209).
  • NEW_RELIC_METADATA_COMMIT will create tags.commit on event data containing the commit sha. The entire sha can be used or just the first seven characters (e.g., 734713b).

An upcoming release of errors inbox will automatically track which versions of your software are producing errors. Any version data will also be displayed in CodeStream.

Url obfuscation

The url obfuscation configuration settings require Node.js agent version 9.9.0 or higher.

For a configuration example, see our documentation for the node agent url obfuscation.

Security Agent

New Relic Security agent interactive applications security testing(IAST) tests your applications for any exploitable vulnerability by replaying the generated HTTP request with vulnerable payloads.

Caution

Run IAST with non-production deployments only to avoid exposing vulnerabilities on your production software.

Important

The security agent configuration settings require Node.js agent version 10.3.0 or higher.

Heroku

Worker Threads

In agent versions prior to 11.0.0, the agent ran in both main and worker threads. In version 11.0.0 the agent stopped running in worker threads due to its incompatibility with our async context propagation. The ability to run in worker threads was restored in version 11.3.0 but you must set worker_threads.enabled to true. The behavior of running in the worker threads varies and we do not officially support it. Some things like metrics generation, and self contained transaction traces may work but this is a use at your own risk capability.

Environment variable overrides

This section defines two configuration options only available with environment variables. These overrides are not used in most configurations.

Environment variable type reference guide

This section describes how to properly format the complex data types.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.