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.
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:
The config file (newrelic.js) contains every Node.js agent setting. When you install the Node.js agent, you must copy newrelic.js into your app's root directory. Most settings are empty by default; they inherit their values from config/default.js.
If your application is running on CommonJS, simply change the configuration file type to (newrelic.cjs). This filetype is supported as of v7.5.0 of the Node.js agent.
All configuration settings in newrelic.js have equivalent environment variables. These are useful, for example, if your agent runs in a PaaS environment such as Heroku or Microsoft Azure. Node.js agent environment variables always start with NEW_RELIC_.
These environment variables are documented below under individual config options as the Environ variable. There are also two rarely used settings that can only be configured via environment variables. If you are unsure how to specify more complex types as environment variables, use the reference guide.
Owners and Admins can view and configure a few settings directly in New Relic. Where available, the UI labels for server-side config are listed in this document under individual config options as the Server-side label.
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.
Data for all applications with the same name will be merged in the New Relic UI, so set this carefully. We highly recommend that you replace the default name with a descriptive name to avoid confusion and unintended aggregation of data.
Tip
For Azure users, the Node.js agent will use APP_POOL_ID if it is set, so you can use the name you chose for your Azure Web Server without setting it twice.
Set to false to stop the agent from starting up. This is useful when debugging your code requires temporarily disabling the agent. It prevents the agent from bootstrapping its instrumentation or setting up all its pieces, which prevents the agent from starting up and connecting to New Relic's servers.
If true, enables capture of all HTTP headers, except for those filtered by exclude rules. If false, collected headers are limited to those defined in Node.js agent attributes.
Any header-related include/exclude rules must be in camelCase form to be filtered.
If the data compression threshold is reached in the payload, the agent compresses data, using gzip compression by default. The config option compressed_content_encoding can be set to deflate to use deflate compression.
Additional certificates to trust for SSL connections, specified as an array of strings in PEM format. This affects both connections to an HTTPS proxy and connections to New Relic.
Tip
You can also configure the agent to read its certificates from a file:
A URL specifying the proxy server to connect to the Internet. For example, proxy: 'http://user:pass@10.0.0.1:8000/'. Important considerations:
The proxy config file setting overrides the other config file proxy settings (proxy_host, proxy_port, proxy_user, proxy_pass) if used. Similarly, the NEW_RELIC_PROXY_URL environment variable overrides the other environment variable proxy settings (NEW_RELIC_PROXY_HOST, NEW_RELIC_PROXY_PORT, NEW_RELIC_PROXY_USER, and NEW_RELIC_PROXY_PASS) if used.
User name for authenticating to the proxy server. The agent supports only basic HTTP authentication.
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.
Defines the level of detail recorded in the agent logs. From least detail to most detail, possible values are fatal, error, warn, info, debug, or trace.
Caution
Do not use debug or trace logging unless New Relic Support asks you to use them. These levels of logging can generate excessive overhead. For most situations, use info.
Complete path to the New Relic agent log, including the filename. Defaults to filepath: require('path').join(process.cwd(), 'newrelic_agent.log'). The agent will shut down the process if it cannot create this file. The agent creates a log file with the same permissions as the parent Node.js agent process.
To write all logging to stdout, set this to stdout.
To write all logging to stderr, set this to stderr.
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.
If set to false, agent omits input and output content (like text strings from prompts and responses) captured in LLM events. This is an optional security setting if you don’t want to record sensitive data sent to and received from your LLMs.
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.
When enabled, the agent logs the payloads it sends to the collector. This data is included in the main log file even when logging level is set to the lowest level.
The agent sends several different types of data to the collector in separate payloads. By default, all of them are included in the log file. This option makes it possible to limit logging only to specific types of data.
Valid values include:
agent_settings
analytic_event_data
connect
custom_event_data
error_data
error_event_data
metric_data
preconnect
shutdown
span_event_data
sql_trace_data
transaction_sample_data
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.
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.
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.
A JavaScript object describing a list of classes tied to error messages for the collector to ignore. The following configuration would ignore all errors of the type Error with the exact (case-sensitive) message strings of Undefined and Out of time:
error_collector:{
/* ... */
ignore_messages:{"Error":["Undefined","Out of time"]}
}
Would ignore all errors of type Error, with the exact (case-sensitive) message strings of Undefined and Out of time.
A javascript object describing a list of javascript classes tied to javascript error messages for the collector to ignore. The following configuration.
error_collector:{
/* ... */
expected_messages:{"Error":["Undefined","Out of time"]}
}
Would mark all errors of type Error, with the exact (case-sensitive) message strings of Undefined and Out of time.
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.
This option affects both slow queries and record_sql for transaction traces. It can have these values: off, obfuscated, or raw.
When set to off no slow queries will be captured, and backtraces and SQL will not be included in transaction traces. If set to raw or obfuscated, the agent sends raw or obfuscated SQL and a slow query sample to the collector. The agent may also send SQL when other criteria are met, such as when slow_sql.enabled is set.
Transactions are named based on the request, and top_n refers to the "top n slowest transactions" grouped by these names. The module replaces a recorded trace with a new trace only if the new trace is slower than the previous slowest trace of that name. The default value for this setting is top_n: 20, because the Transactions page also defaults to the 20 slowest transactions.
The Node.js agent captures at least five different slow transactions in the first harvest cycle after start up. It will also reset and capture different transactions if no slow transactions have been captured for the last five harvest cycles. This allows you to see more information about more of your app's request paths, at the possible cost of not focusing on the absolutely slowest request for that harvest cycle.
Tip
To record the absolute slowest transaction over the last minute, you can set top_n: 0 or top_n: 1. However, this causes one very slow route to dominate your transaction traces.
Sets the time, in seconds, for a transaction trace to be considered slow. The default value is apdex_f; this sets the trace threshold to four times your application's Apdex T. If a number is provided, it is set in seconds.
The default apdex_t is 500 milliseconds. If your transaction threshold is set to apdex_f, a "slow" transaction is 2 seconds.
Prefix of attributes to include in transaction traces. Allows * as wildcard at end.
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.
A comma-delimited list of rules to match incoming request URLs and name the associated New Relic transaction. Uses the format:
name:[
{pattern:'STRING_OR_REGEX',name:'NAME'},
{pattern:'STRING_OR_REGEX',name:'NAME'}
]
Both parameters are required. For strings, you must escape control characters. You do not need to escape control characters in regular expressions. Additional attributes are ignored.
Regular expressions support JavaScript-style capture groups, and names use $1-style replacement strings. Regular expressions only find the first matching result; subsequent matches are ignored. For more information, see Node.js transaction naming API.
For the NEW_RELIC_NAMING_RULES environment variable, pass the rules as comma-delimited JSON object literals:
Define a list of request URLs you want the agent to ignore. Specify the list as patterns, which can be strings or regular expressions. The default value is a regular expression to match socket.io long-polling requests
When enabled, the agent renames transactions that are not affected by other naming logic (such as the API, rules, or metric normalization rules) to NormalizedUri/*. If you set this to false, the agent sets transaction names to Uri/path/to/resource.
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.
When enabled, the agent sends transaction events to New Relic. This event data includes transaction timing, transaction name, and any custom attributes. If this is disabled, the agent does not collect this data or send it to New Relic.
Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.
We don't recommend configuring past 10,000. The server will cap data at 10,000 per-minute.
Important
This configuration had different behavior in agent versions lower than 6.0.0. See max_samples_stored (DEPRECATED) for agent versions 5.x or lower.
Type
Integer
Default
20000
Defines the maximum number of events the agent stores if it is unable to communicate with the New Relic collector. The values from the previous harvest cycle will be merged into the next one, with this option limiting the maximum number. Make sure this number is greater than max_samples_per_minute; for example, set it to twice as much. Consider your memory overhead before increasing this value.
Caution
This configuration has different behavior starting with agent version 6.0.0 and a new recommended maximum. See max_samples_stored for agent versions 6.x or higher.
Type
Integer
Default
10000
Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.
Caution
This configuration has been replaced with max_samples_stored starting with version 6.0.0 of the agent. See max_samples_stored for 6.x or later agents.
Prefix of attributes to include in transaction events. Allows * as wildcard at end.
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.
Prefix of attributes to include in browser monitoring. Allows * as wildcard at end.
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.
When enabled, the agent sends custom events recorded with recordCustomEvent() to New Relic. If this is disabled, the agent does not collect this data or send it to New Relic.
Defines the maximum number of custom events the agent collects per minute. If the number of custom events exceeds this limit, the agent collects a statistical sampling.
When configuring the agent for AI monitoring, set to max value 100000. Ensures that the maximum amount of LLM events are captured.
Important
Increasing this limit may increase memory usage.
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.
Defines the maximum number of slow queries the agent collects per minute. The agent discards additional queries after the limit is reached.
Important
Increasing this limit increases memory usage.
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.
Specify a custom hostname for display in New Relic. If you do not set this field, New Relic will continue to use the default hostname found by calling os.hostname().
If you use the default hostname settings, New Relic finds the hostname through os.hostname().
If this call fails, New Relic uses the host's IP as the name.
If you set ipv_preference: 4 or ipv_preference: 6, you can select the type of IP address (IPv4 or IPv6) that appears in the New Relic UI.
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.
When enabled, the agent collects datastore instance metrics (such as host and port) for some database drivers. These are reported on slow query traces and transaction traces.
When enabled, the agent collects database name on slow query traces and transaction traces for some database drivers.
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.
When set to true, allows tracing of transactions across more than one New Relic-monitored applications.
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:
When false, the agent will redact the messages of captured errors.
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.
Set this to true to exclude the New Relic header that is attached to outbound requests, and instead only rely on W3C Trace Context Headers for distributed tracing. If this is false then both types of headers are used.
For example, to enable this in the config file, you would use:
distributed_tracing:{
enabled:true,
exclude_newrelic_header:true
}
gRPC server instrumentation
The grpc section controls the behavior of how the gRPC server is instrumented.
When enabled, the agent will send all error gRPC status codes to New Relic, that is, nonzero status codes. If disabled, the server instrumentation will not send any nonzero status codes to New Relic.
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:
This setting can be used to turn reporting of attributes on or off for spans. If attributes.enabled at the root level is false, no attributes will be sent with spans regardless on how this is set.
If attributes are enabled for spans, all attribute keys found in this list will be attached to spans. For more information, see the agent attribute rules.
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.
The amount of Infinite Tracing spans the agent will hold in memory before dropping them.
This setting should rarely need to changed from the default as the queue is not in use the majority of the time. The queue is in use only during reconnections to the Infinite Tracing endpoint while the agent is unable to stream data. It's possible the agent will drop Infinite Tracing spans during these periods, in that case increasing this number can help.
Number of log records to send per minute to New Relic. Controls the overall memory consumption when using log forwarding.
Set this to a lower value to reduce the amount of log lines sent (may cause log sampling). Set this to a higher value to send more log lines.
Each log receives the same priority as its associated transaction. Logs that occur outside of a transaction will receive a random priority. Some logs may not be included because they are limited by max_samples_stored. For example, if logging max_samples_stored is set to 10,000 and transaction 1 has 10,000 log entries, only log entries for transaction 1 will be recorded. If transaction 1 has less than 10,000 logs you receive all logs for transaction 1. If there is still space, you receive all the logs for transaction 2, and so on.
If after all the logs for sampled transactions are recorded, and they haven't reached the limit in max_samples_stored, then log messages for transactions that were not in our sampling are sent. If there are any left, log messages outside of transactions are recorded.
Toggles whether to capture additional attributes on middleware spans for all Node.js web frameworks that help drive Code level metrics. The additional attributes are: code.filepath, code.function, code.lineno, and code.column.
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.
Specifies the regex flags to use for url obfuscation pattern matching e.g. g for global matching, i for case insensitive matching, etc. Multiple flags can be specified as a string e.g. gi. If this is not set, no flags will be used.
Specifies the replacement string to use for url obfuscation. Can contain refferences to capture groups in the pattern e.g. $1. If this is not set, everything will be replaced with a single empty string.
Toggles whether the New Relic Security agent data is sent to New Relic or not. When this is disabled and security.agent.enabled is true, the security agent be registered but data will not be sent.
New Relic Security provided mode: IAST. Default is IAST. Due to the invasive nature of IAST scanning, DO NOT enable this mode in either a production environment or an environment where production data is processed.
New Relic Security connection URL. This is the endpoint that the security agent sends data to, it should match that environment that you have set for the Node.js agent.
If true, the agent uses Heroku dyno names as the hostname.
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.
If true, the agent will load when in a worker thread if specified.
Environment variable overrides
This section defines two configuration options only available with environment variables. These overrides are not used in most configurations.
Path to the directory containing newrelic.js. This is available only as an environment variable. You cannot set it in your config file.
Type
String
Default
(none)
If used, this prevents the agent from reading configuration settings from newrelic.js. Default values and values from environment variables will still be set.
This is available only as an environment variable. You cannot set it in your config file.
Type
Boolean
Default
false
Environment variable type reference guide
This section describes how to properly format the complex data types.
Array types are defined as comma-delimited strings.