Node.js agent configuration

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

The license_key setting is required. New Relic also recommends setting the app_name setting to ensure your app has a meaningful name.

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 via environment variables, and can set some settings with server-side configuration.

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

nodejs-config-order2.png
Server-side config 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, and inherit their values from config.default.js.

Most configuration settings in newrelic.js have equivalent environment variables. These are useful, for exmaple, 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. You can ignore server-side config with the ignore_server_configuration setting.

Where available, the UI labels for server-side config are documented below 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.

app_name (HIGHLY RECOMMENDED)
Type String
Default (none)
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.

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 does not prevent the agent from bootstrapping its instrumentation or setting up all its pieces, it just prevents the agent from starting up or connecting to New Relic's servers.

apdex_t
Type Number
Default 0.100
Environ variable NEW_RELIC_APDEX
Server-side label Apdex T

Sets the default Apdex T for your app, in seconds. Generally, you should set this via server-side config. The 100 milliseconds default is lower than standard New Relic Apdex settings, but Node.js apps tend to be more latency-sensitive than others. See also transaction_threshold.

capture_params
Type Boolean
Default false
Environ variable NEW_RELIC_CAPTURE_PARAMS

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

ignored_params
Type String
Default (none)
Environ variable NEW_RELIC_IGNORED_PARAMS

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

ssl
Type Boolean
Default true
Environ variable NEW_RELIC_USE_SSL

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.

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.

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

Generate JavaScript headers for page load timing (sometimes referred to as real user monitoring or RUM). 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.

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

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.

Error collector variables

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.

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.

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.

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 considered slow and is eligible for transaction traces. If set to apdex_f, the agent sets the trace threshold to four times your Apdex T.

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.

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.

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.

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.

Debug variables

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

internal_metrics
Type Boolean
Default false
Environ variable NEW_RELIC_DEBUG_METRICS

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

When enabled, the agent collects internal supportability metrics and diagnostics alongside performance metrics.

tracer_tracing
Type Boolean
Default false
Environ variable NEW_RELIC_DEBUG_TRACER

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

When enabled, the agent traces the internal operation of the transaction tracer itself. Requires log level set to trace.

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 (none)
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 (the API, rules, or metric normalization rules) to NormalizedUri/*. If you set this to false, the agent sets transaction names to 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.

Currently there are no environment variables for transaction events.

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, twice as much. Consider your memory overhead before increasing this value.

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)

Change the display name of your hostname in the APM UI. If you do not set this field, New Relic will continue to use the default hostname found by calling os.hostname().

ipv_preference
Type Integer (4 or 6)
Default 4
Environ variable NEW_RELIC_IPV_PREFERENCE

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 to be displayed (IPv4 or IPv6).

Environment variable overrides

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

NEW_RELIC_HOME
Type String
Default (none)
Notes Only available as an environment variable; cannot be set in your config file.

Path to the directory containing newrelic.js.

NEW_RELIC_NO_CONFIG_FILE
Type Boolean
Default False
Notes Only available as an environment variable; cannot be set in your config file.

Typically not used, since environment variables override newrelic.js settings anyway and most configurations depend on the existence of newrelic.js. To use this setting, you must configure all key settings via environment variables, and you should be aware that some log messages assume a config file exists.

Prevents the agent from reading configuration settings from newrelic.js.

For more help

Additional documentation resources include:

  • Configuring Node.js (hierarchy of configuration options and an explanation of server-side and configuration file options)
  • Configuring Node.js with environment variables (NEW_RELIC_ variables to override the customized settings in your newrelic.js config file; useful, for example, for PaaS providers)
  • Node.js transaction naming API (API rules to provide the right amount of information, without overwhelming you with data, so that you can identify problem spots in your applications more easily)

Join the discussion about Node.js monitoring in the New Relic Community Forum! The Community Forum is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.