Node.js agent configuration

You can tailor New Relic's 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 the New Relic UI, or use New Relic's Node.js agent API.

The license_key setting is required. New Relic highly recommends 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 agent configuration precedence
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.

Most configuration settings in newrelic.js have equivalent environment variables. These are useful, for example, if your agent runs in a PaaS enviornment such as Heroku or Microsoft Azure. Node.js agent environment variables always start with NEW_RELIC_.

Where available, 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.

Owner or Admins

Owners and Admins can view and configure a few settings directly in the New Relic UI. Where available, the UI labels for server-side config are listed in this document under individual config options as the Server-side label. To ignore server-side configuration, use the ignore_server_configuration setting.

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.

app_name (HIGHLY RECOMMENDED)
Type String
Default "My Application"
Environ variable NEW_RELIC_APP_NAME

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. New Relic highly recommends that you replace the default name with a descriptive name to avoid confusion and unintended aggregation of data.

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.

license_key (REQUIRED)
Type String
Default (none)
Environ variable NEW_RELIC_LICENSE_KEY

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

host
Type String
Default collector.newrelic.com
Environ variable NEW_RELIC_HOST

Do not edit this value unless New Relic Support asks you to change it.

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

port
Type Integer
Default 443
Environ variable NEW_RELIC_PORT

Do not edit this value unless New Relic Support asks you to change it.

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

proxy
Type String
Default (none)
Environ variable NEW_RELIC_PROXY_URL

A URL specifying the proxy server to connect to the Internet. For example, proxy: 'http://user:pass@10.0.0.1:8000/'.

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.

proxy_host
Type String
Default (none)
Environ variable NEW_RELIC_PROXY_HOST

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

proxy_port
Type String
Default (none)
Environ variable NEW_RELIC_PROXY_PORT

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

proxy_user
Type String
Default (none)
Environ variable NEW_RELIC_PROXY_USER

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

proxy_pass
Type String
Default (none)
Environ variable NEW_RELIC_PROXY_PASS

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

ignore_server_configuration
Type Boolean
Default false
Environ variable NEW_RELIC_IGNORE_SERVER_CONFIGURATION

When enabled, the agent ignores server-side configuration for this app.

agent_enabled
Type Boolean
Default true
Environ variable NEW_RELIC_ENABLED

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.

apdex_t DEPRECATED
Type Number
Default 0.100
Server-side label Apdex T

Set your Apdex T via the New Relic UI.

capture_params DEPRECATED
Type Boolean
Default false
Environ variable NEW_RELIC_CAPTURE_PARAMS

This option has been deprecated in favor of attributes.enabled.

When enabled, the agent captures request parameters with transaction traces and error traces depending on include/exclude filtering rules. Because this can pass sensitive data, it defaults to false. See also ssl and ignored_params.

ignored_params DEPRECATED
Type Array
Default []
Environ variable NEW_RELIC_IGNORED_PARAMS

This option has been deprecated in favor of attributes.exclude.

Comma-delimited list of parameter names to ignore that otherwise would be captured from request URLs in transaction traces and error traces. For example, some parameters may contain sensitive values you do not want sent out of your application. Defaults to ignored_params: [] (empty).

certificates
Type Array of strings
Default (none)

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.

You can also configure the agent to read its certificates from a file:

certificates: [ fs.readFileSync('myca.crt', {encoding: 'utf8'}) ]
high_security
Type Boolean
Default false
Environ variable NEW_RELIC_HIGH_SECURITY

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

labels
Type Object or string
Default (none)
Environ variable NEW_RELIC_LABELS

Use labels and categories to organize your apps. Specify your labels as objects or a semicolon-delimited string of colon-separated pairs (for example, Server:One;Data Center:Primary).

allow_all_headers
Type Boolean
Default true

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.

ssl (DEPRECATED)
Type Boolean
Default true
Environ variable NEW_RELIC_USE_SSL

The agent communicates with New Relic via HTTPS by default, and New Relic requires HTTPS for all traffic to New Relic APM and the New Relic REST API. When enabled, the agent uses SSL to connect to the New Relic collector. Must be true to enable high_security.

By default the agent is compliant with high security v1. However, if you disable ssl and enable capture_params, the agent can exit high security mode, which prevents the agent from connecting with high-security accounts. If high security mode fails, the log files show an error message such as ERROR Account Security Violation.

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.

level
Type String
Default info
Environ variable NEW_RELIC_LOG_LEVEL

Defines the level of detail recorded in the agent logs. This module uses bunyan. From least detail to most detail, possible values are fatal, error, warn, info, debug, or trace.

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.

filepath
Type String
Default process.cwd() plus newrelic_agent.log
Environ variable NEW_RELIC_LOG

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.

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.

enabled
Type Boolean
Default false
Environ variable NEW_RELIC_AUDIT_LOG_ENABLED

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.

endpoints
Type Array
Default Empty array (include all types)
Environ variable NEW_RELIC_AUDIT_LOG_ENDPOINTS

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:

  • metric_data
  • error_data
  • analytic_event_data
  • custom_event_data
  • error_event_data
  • transaction_sample_data
  • sql_trace_data
  • connect
  • agent_settings
  • get_redirect_host
  • shutdown

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.

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

custom_attributes_enabled
Type Boolean
Default true
Environ variable

NEW_RELIC_API_CUSTOM_ATTRIBUTES

This option enables newrelic.addCustomAttribute and newrelic.addCustomAttributes.

custom_parameters_enabled DEPRECATED
Type Boolean
Default true
Environ variable

NEW_RELIC_API_CUSTOM_PARAMETERS

This option enables newrelic.addCustomParameter and newrelic.addCustomParameters.

This option has been deprecated in favor of custom_attributes_enabled.

custom_events_enabled
Type Boolean
Default true
Environ variable NEW_RELIC_API_CUSTOM_EVENTS

This option enables recordCustomEvent.

notice_error_enabled
Type Boolean
Default true
Environ variable NEW_RELIC_API_NOTICE_ERROR

This option enables newrelic.noticeError.

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.

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

enabled
Type Boolean
Default true
Environ variable NEW_RELIC_ATTRIBUTES_ENABLED

If true, enables capture of attributes for all destinations.

exclude
Type Array
Default []
Environ variable NEW_RELIC_ATTRIBUTES_EXCLUDE

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

include
Type Array
Default []
Environ variable NEW_RELIC_ATTRIBUTES_INCLUDE

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

include_enabled
Type Boolean
Default true
Environ variable NEW_RELIC_ATTRIBUTES_INCLUDE_ENABLED

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

Error collector variables

You can manage how error are handled in New Relic APM. 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.

enabled
Type Boolean
Default true
Environ variable NEW_RELIC_ERROR_COLLECTOR_ENABLED
Server-side label Enable error collection?

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

ignore_status_codes
Type Array
Default 404
Environ variable NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERROR_CODES
Server-side label Ignore these status codes

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

Errors recorded using newrelic.noticeError do not obey this configuration value.

attributes.enabled
Type Boolean
Default true
Environ variable NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_ENABLED

If true, the agent captures attributes from error collection.

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

attributes.exclude
Type Array
Default []
Environ variable NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_EXCLUDE

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

attributes.include
Type Array
Default []
Environ variable NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_INCLUDE

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

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.

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.

enabled
Type Boolean
Default true
Environ variable NEW_RELIC_TRACER_ENABLED
Server-side label Enable transaction tracing?

When enabled, the agent collects slow transaction traces.

explain_threshold
Type Integer
Default 500
Environ variable NEW_RELIC_EXPLAIN_THRESHOLD

Minimum query length (in milliseconds) for a transaction to be eligible for slow query and transaction traces.

record_sql
Type String (off, obfuscated, or raw)
Default off
Environ variable NEW_RELIC_RECORD_SQL

This option affects both slow queries and record_sql for transaction traces. It can have one of three 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.

top_n
Type Integer
Default 20
Environ variable NEW_RELIC_TRACER_TOP_N

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.

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.

transaction_threshold
Type Integer or apdex_f
Default apdex_f
Environ variable NEW_RELIC_TRACER_THRESHOLD
Server-side label Threshold

Threshold of web transaction response time in seconds beyond which a transaction is eligible for transaction tracing. The default value is apdex_f; this sets the trace threshold to four times your application's Apdex T. You can also enter a specific time value in milliseconds.

Example: Threshold set to apdex_f

The default apdex_t is 100 milliseconds. If your transaction threshold is set to apdex_f, a "slow" transaction is 400 milliseconds.

hide_internals
Type boolean
Default true
Environ variable NEW_RELIC_HIDE_INTERNALS

The agent uses a small amount of CPU in order to hide internal properties that are attached to the web application. If you change this configuration to false, it may slightly decrease your agent overhead, but it could also have an impact on the performance of the agent.

attributes.enabled
Type Boolean
Default true
Environ variable NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_ENABLED

If true, the agent captures attributes from transaction traces.

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

attributes.exclude
Type Array
Default []
Environ variable NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_EXCLUDE

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

attributes.include
Type Array
Default []
Environ variable NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_INCLUDE

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.

name
Type Strings or regular expressions
Default (none)
Environ variable NEW_RELIC_NAMING_RULES

A comma-delimited list of rules to match incoming request URLs and name the associated New Relic transaction. Uses the format {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"}'
ignore
Type Strings or regular expressions
Default

Regular expression to match socket.io long-polling requests ("^\/socket\.io\/.*\/xhr-polling/").

Environ variable NEW_RELIC_IGNORING_RULES

Define a list of request URLs you want the agent to ignore. Specify the list as patterns, which can be strings or regular expressions.

enforce_backstop
Type Boolean
Default true
Environ variable NEW_RELIC_ENFORCE_BACKSTOP

Do not change this setting unless you understand metric grouping issues.

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.

enabled
Type Boolean
Default true

When enabled, the agent sends transaction events to New Relic Insights. This event data includes transaction timing, transaction name, and any custom parameters. If this is disabled, the agent does not collect this data or send it to Insights.

max_samples_per_minute
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.

max_samples_stored
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.

attributes.enabled
Type Boolean
Default true
Environ variable NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_ENABLED

If true, the agent captures attributes from transaction events.

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

attributes.exclude
Type Array
Default []
Environ variable NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_EXCLUDE

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

attributes.include
Type Array
Default []
Environ variable NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_INCLUDE

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.

enable
Type Boolean
Default true
Environ variable NEW_RELIC_BROWSER_MONITOR_ENABLE
Server-side label Enable browser monitoring?

Generate JavaScript headers for New Relic Browser instrumentation. Although this defaults to true, the agent doesn't inject the New Relic Browser JavaScript unless you have enabled New Relic Browser. Even if you have enabled New Relic Browser and added the Browser timing header, you can disable Browser for your app by setting this to false.

debug
Type Boolean
Default false
Environ variable NEW_RELIC_BROWSER_MONITOR_DEBUG

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

attributes.enabled
Type Boolean
Default false
Environ variable NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_ENABLED

If true, the agent captures attributes from browser monitoring.

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

attributes.exclude
Type Array
Default []
Environ variable NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_EXCLUDE

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

attributes.include
Type Array
Default []
Environ variable NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_INCLUDE

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

Custom Insights 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. Currently there are no environment variables for custom Insights events.

enabled
Type Boolean
Default true

When enabled, the agent sends custom Insights events recorded with recordCustomEvent() to New Relic Insights. If this is disabled, the agent does not collect this data or send it to New Relic Insights.

max_samples_stored
Type Integer
Default 1000

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.

Increasing this limit increases 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.

enabled
Type Boolean
Default false
Environ variable NEW_RELIC_SLOW_SQL_ENABLED

When enabled, the agent collects slow query details.

max_samples
Type Integer
Default 10
Environ variable NEW_RELIC_MAX_SQL_SAMPLES

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

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 New Relic APM UI.

display_name
Type String of 255 bytes or less
Default (none)
Environ variable NEW_RELIC_PROCESS_HOST_DISPLAY_NAME

Specify a custom hostname for display in the New Relic UI. 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.
ipv_preference
Type Integer (4 or 6)
Default 4
Environ variable NEW_RELIC_IPV_PREFERENCE

Environment variable overrides

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

NEW_RELIC_HOME

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)
NEW_RELIC_NO_CONFIG_FILE

Avoid using NEW_RELIC_NO_CONFIG_FILE because:

  • Environment variables override newrelic.js settings anyway.
  • Most configurations depend on the existence of newrelic.js.
  • Some log messages assume a config file exists.

If used, this prevents the agent from reading configuration settings from newrelic.js. To use this setting, you must configure all key settings by using environment variables.

This is available only as an environment variable. You cannot set it in your config file.

Type Boolean
Default False

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.

instance_reporting.enabled
Type Boolean
Default true

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.

database_name_reporting.enabled
Type Boolean
Default true

When enabled, the agent collects database name on slow query traces and transaction traces for some database drivers.

Cross application tracing

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

enabled
Type Boolean
Default true

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

Error message redaction variables

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

enabled
Type Boolean
Default true
Environ variable NEW_RELIC_ALLOW_RAW_EXCEPTION_MESSAGES_ENABLED

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

For more help

Recommendations for learning more: