Node.js agent configuration

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.

If you're using New Relic CodeStream to monitor performance from your IDE, you may also want to associate repositories with your services and associate build SHAs or release tags with errors.

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.

The name New Relic uses to identify your app. For example, app_name: ['MyNodeApp']. To use multiple names for your app, specify a comma-delimited list of names.

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.

This setting is required. Your New Relic license key. For example, license_key: '40HexadecimalCharacters'.

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.

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.

Set your Apdex T via the New Relic UI.

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.

certificates: [ fs.readFileSync('myca.crt', {encoding: 'utf8'}) ]

When set to true, enables high security v2. You must also enable the ssl setting and enable high security in the UI.

Hostname for the New Relic collector to connect to the Internet; for example, host: 'collector.newrelic.com'.

Adds tags. Specify your tags as objects or a semicolon-delimited string of colon-separated pairs (for example, Server:One;Data Center:Primary).

Port number to connect to the New Relic collector; for example, port: 443.

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.
• If you're using Infinite Tracing: see how to configure a proxy for Infinite Tracing.

Hostname or IP address of the proxy server to connect to the Internet.

Password for authenticating to the proxy server. The agent supports only basic HTTP authentication.

Port number of the proxy server to connect to the Internet.

User name for authenticating to the proxy server. The agent supports only basic HTTP authentication.

Enables or disables agent specific logging.

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.

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.

When set to true, enables AI monitoring. Allows the agent to capture LLM event data.

When set to false, disables instrumentation for streamed LLM data. Set to true, captures streamed data for LLM events.

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.

The AWS account ID for the AWS account associated with this app.

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

This option enables newrelic.addCustomAttribute and newrelic.addCustomAttributes.

This option enables recordCustomEvent.

This option enables newrelic.noticeError.

If true, enables capture of attributes for all destinations.

Prefix of attributes to exclude from all destinations. Allows * as wildcard at end. For example, in the config file, this would include all parameters except somethingSecret:

attributes: { 
  include: [ 'request.parameters.*' ],
  exclude: [ 'request.parameters.somethingSecret' ]
}

Prefix of attributes to include from all destinations. Allows * as wildcard at end.

For example, in the config file, this would include all parameters:

attributes: { 
  include: [ 'request.parameters.*' ]
}

Using this example Express route definition and request URL:

app.get('/api/users/:id', myMiddleware, myController)

$
curl http://localhost:3000/api/users/abc123?id=true

The route parameter is id, and has a value of abc123. This becomes the attribute request.parameters.route.id: abc123 on the Transaction, root Segment, and Span. This example also has a query parameter of id, which has a value of true. This would become the attribute request.parameters.id: true on the Transaction, root Segment, and Span.

When true, patterns may be added to the attributes.include list.

When enabled, the agent collects error traces from your app.

Comma-delimited list of HTTP status codes for the error collector to ignore.

Comma-delimited list of javascript error types/classes for the error collector to ignore.

The following configuration

error_collector: {
    /* ... */
    ignore_classes: ["ReferenceError"]
}

Would ignore all reference errors.

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.

Comma-delimited list of HTTP status codes for the error collector to mark as expected.

The following configuration

error_collector: {
    /* ... */
    expected_classes: ["ReferenceError"]
}

Would mark all reference errors as expected.

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.

If true, the agent captures attributes from error collection.

Prefix of attributes to exclude from error collection. Allows * as wildcard at end.

Prefix of attributes to include in error collection. Allows * as wildcard at end.

Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.

When enabled, the agent collects slow transaction traces.

Minimum query duration (in milliseconds) for a transaction to be eligible for slow queries in transaction traces.

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.

Defines the maximum number of requests eligible for transaction traces.

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.

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.

If true, the agent captures attributes from transaction traces.

Prefix of attributes to exclude from transaction traces. Allows * as wildcard at end.

Prefix of attributes to include in transaction traces. Allows * as wildcard at end.

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:

NEW_RELIC_NAMING_RULES='{"pattern":"^t","name":"u"},{"pattern":"^u","name":"t"}'

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.

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.

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.

Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.

If true, the agent captures attributes from transaction events.

Prefix of attributes to exclude from transaction events. Allows * as wildcard at end.

Prefix of attributes to include in transaction events. Allows * as wildcard at end.

Generate JavaScript headers for browser instrumentation. If set to true the agent does not automatically inject the browser JS code unless you have manually enabled browser monitoring. Even if you have enabled it and added the browser timing header, you can disable browser monitoring for your app by setting this to false.

If true, request un-minified sources from the server.

If true, the agent sends custom attributes to browser monitoring.

Prefix of attributes to exclude from browser monitoring. Allows * as wildcard at end.

Prefix of attributes to include in browser monitoring. Allows * as wildcard at end.

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.

When enabled, the agent collects slow query details.

Defines the maximum number of slow queries the agent collects per minute. The agent discards additional queries after the limit is reached.

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.

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.

When set to true, allows tracing of transactions across more than one New Relic-monitored applications.

When true, the agent will redact the messages of captured errors.

Set this to false to disable distributed tracing. For example, in the config file, you would use:

distributed_tracing: {
    enabled: false
}

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
}

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.

Turns reporting of span events on or off.

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.

All attribute keys found in this list will not be sent with spans. For more information, see the agent attribute rules.

For help getting a valid Infinite Tracing trace observer host entry, see Find or create a trace observer endpoint.

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.

Enables automatically generating logs in context.

For example, to disable this feature in the config file, you would use:

application_logging: {
    enabled: false
}

Toggles whether the agent gathers Logging Metrics used in the Logs chart on the APM Summary page.

Toggles whether the agent gathers log records for sending to New Relic.

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 the agent will add labels to log records for sending to New Relic.

A case-insensitive list of label names to exclude when you enable including labels in logs. This attribute does not support wildcards or regex.

Toggles whether the agent performs Local Log Decoration on standard log output.

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.

Enables regex based node agent url obfuscation.

Specifies the regex pattern to use for url obfuscation. If this is not set, no url obfuscation will be performed.

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.

Toggles whether the New Relic Security agent is loaded. This property is read only once at application start.

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.

Enable RCI security event detection.

Enable RXSS security event detection.

Enable deserialization security event detection.

If true, the agent uses Heroku dyno names as the hostname.

If true, the agent will load when in a worker thread if specified.

Path to the directory containing newrelic.js. This is available only as an environment variable. You cannot set it in your config file.

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.

Array types are defined as comma-delimited strings.

NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERROR_CODES=404,500,429

Object types are defined as a json string.

NEW_RELIC_ERROR_COLLECTOR_EXPECTED_MESSAGES='{"Error":["Undefined", "No soup for you!"]}'