Configuring Node.js with environment variables

All of the configuration variables in newrelic.js have counterparts that can be set as environment variables. Environment variables are useful, for example, if your agent runs in a PaaS environment such as Heroku or Microsoft Azure. You can freely mix and match variables in the configuration file.

Note: Server-side configuration settings override all other settings unless you specifically turn them off in your config file or environment variables. Then:

  • Environment variables override your newrelic.js configuration file's settings. Environment variable always start with NEW_RELIC_.
  • Your newrelic.js configuration file's settings override your config file's default values in config.default.js.

Main configuration settings

Here is a summary of the most important Node.js agent configuration variables in your app's newrelic.js configuration file. For your convenience, these are listed in alphabetical order.


The name of this application, for reporting to New Relic's servers. This value can also be a comma-delimited list of names. If used, this overrides app_name.

Note: As a convenience to 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.


When set to true, this enables high security V2 mode. (Default is false.) If used, this overrides high_security.

You must also enable NEW_RELIC_USE_SSL and enable high security in the user interface. When high security V2 mode is turned on, it does not allow capturing request parameters and custom parameters.


Path to the directory where you placed newrelic.js.


Your New Relic license key. Required for your app's configuration file. If used, this overrides license_key.


Complete path to the New Relic agent log, including the filename. By default this uses process.cwd + newrelic_agent.log. The agent will shut down the process if it cannot create this file, and it creates the log file with the same mask of the process. Setting this to stdout will write all logging to stdout, and stderr will write all logging to stderr. If used, this overrides filepath.


How verbose the logging is for the New Relic Node.js agent. This module uses bunyan. Values can be fatal, error, warn, info, debug, or trace. If used, this overrides level.

Avoid using debug and trace unless you are helping New Relic identify irregularities or track any bugs with the agent. For most situations, use info or higher.


Inhibit loading of the configuration file altogether. Use with care. This presumes that all important configurations will be available via environment variables, and some log messages assume that a config file exists.


Use SSL to connect to newrelic. Default is true. If used, this overrides ssl.

By default the Node.js agent is high-security compliant. However, if you disable ssl and enable capture_params or NEW_RELIC_CAPTURE_PARAMS, this may cause the Node.js agent to go out of high security mode, which will prevent the agent from connecting with high-security accounts. If high security mode fails, the log files will show an error message such as "ERROR Account Security Violation."

Other configuration options

Here is a summary of additional options to configure your Node.js agent. For your convenience, these are listed in alphabetical order.


Sets the default Apdex tolerating / threshold values for applications, in seconds. Typically this is set from the server. Defaults to 100ms. (This is lower than standard New Relic Apdex settings, but Node.js apps tend to be more latency-sensitive than others.) Transactions slower than this value will generate slow transaction traces. If used, this overrides apdex_t.


Generate JavaScript headers for page load timing (sometimes referred to as real user monitoring or RUM). Default is TRUE. There is no auto-instrumentation, but you can prevent the browser monitoring JavaScript from being embedded by setting this to false.


Whether to capture request parameters in the request URL for slow transaction traces and error traces. This can pass sensitive data, so it defaults to false. If used, this overrides capture_params. See also NEW_RELIC_USE_SSL and NEW_RELIC_IGNORED_PARAMS.


Whether or not the agent should run. Defaults to true. Good for temporarily disabling the agent while debugging other issues with your code. It does not prevent the agent from bootstrapping its instrumentation or setting up all its pieces; it just prevents it from starting up or connecting to New Relic's servers. If used, this overrides agent_enabled.


Whether or not to collect error traces within your application and submit them to New Relic. Values are true (default) or false. If used, this overrides error_collector : { enabled.


Comma-delimited list of HTTP status codes for the error collector to ignore. Defaults to 404. If used, this overrides ignore_status_codes.


Whether to ignore server-side configuration for this application. Defaults to false. If used, this overrides ignore_server_configuration.


Comma-delimited list of parameter names to ignore that otherwise would be captured from request URLs in slow transaction traces and error traces. For example, some parameters may contain sensitive values you do not want being sent out of your application. Defaults to empty. If used, this overrides ignored_params.


A list of patterns for matching incoming request URLs to be ignored by the agent. If used, this overrides rules : { ignore. Patterns may be strings or regular expressions, with multiple rules passed in as a list of comma-delimited patterns:


Note: Currently there is no way to escape commas in patterns. Defaults to empty. For more information, see Node.js transaction naming API.


Overwrites process_host.ipv_preference. For each agent, a default host name is determined through a call to os.hostname(). Should this call fail, the system's IP address is used instead. Setting NEW_RELIC_IPV_PREFERENCE to 4 or 6 will change the IP address type used (IPv4 or IPv6). The default value is 4.


A list with multiple rules passed in as comma-delimited JSON object literals:


Defaults to empty. If used, this overrides rules : { name. For more information, see Node.js transaction naming API.


Overwrites process_host.display_name. Setting this to some string will set the respective agent's host display name in the New Relic APM UI to the string set. If you do not set both this environment variable and process_host.display_name, New Relic determines the host display name by a call to os.hostname().


Whether to collect and submit slow transaction traces to New Relic. Values are true (default) or false. If used, this overrides transaction_tracer : { enabled.


Duration in seconds at which a transaction trace will count as slow and be sent to New Relic. If this is set to apdex_f, it will set the tracer threshold to 4 times the current Apdex T. For example, the default apdex_t value for Node.js is 100 milliseconds. If NEW_RELIC_TRACER_THRESHOLD is set to apdex_f, a slow transaction trace is 400 milliseconds, or approximately half a second. If used, this overrides transaction_threshold.


How many different named requests to track for transaction tracing to provide slow trace diversity. If used, this overrides top_n.

By default, the agent captures the slowest transaction trace for each harvest cycle. It captures a new trace only if the new trace is slower than the previous slowest trace over the last 5 harvest cycles. Use NEW_RELIC_TRACER_TOP_N if you want to have up to a defined number of different requests (by name) being traced. For more information, see Transaction tracer variables.


Sets the label names and values to associate with the application. The list is a semi-colon delimited list of colon-separated name and value pairs.

Example: "Server:One;Data Center:Primary"

Rarely changed options

Avoid using these configuration variables unless necessary; for example, use them only if New Relic Support requests it. For your convenience, these are listed in alphabetical order.


Whether to collect and submit internal supportability metrics and diagnostics alongside application performance metrics for the agent. Do not change this unless New Relic requests it. If used, this overrides internal_metrics.


Whether to trace the execution of the transaction tracer's internal operation. Requires logging: { level set to trace. Typically used only by New Relic Node.js engineers. If used, this overrides tracer_tracing.


By default (true). Any transactions that are not affected by other naming logic (the API, rules, or metric normalization rules) will have their names set to NormalizedUri/*. If you set this to false, this sets their names to Uri/path/to/resource. If used, this overrides enforce_backstop.

Do not change this setting unless you understand the implications of New Relic's metric grouping issues and are confident your app will not run into any problems with this.


Hostname for the New Relic collector to connect to the internet. You should not need to change this. If used, this overrides host.


Port number on which the New Relic collector will be listening. You should not need to change this. If used, this overrides port.


Hostname for the New Relic collector proxy to connect to the internet. You should not need to change this. If used, this overrides proxy_host.


Password for authenticating to the proxy server. The agent supports only basic HTTP authentication. If used, this overrides proxy_pass.


Port number on which the New Relic collector proxy will be listening. You should not need to change this. If used, this overrides proxy_port.


A URL specifying the proxy server to connect to the internet. If used, this overrides proxy.

Note: This setting overrides any of the other PROXY_ environment variables for proxy settings if used.


User name for authenticating to the proxy server. The agent supports only basic HTTP authentication. If used, this overrides proxy_user.

For more help

Additional documentation resources include:

  • Configuring Node.js (hierarchy of configuration options and an explanation of server-side and configuration file options)
  • Node.js agent configuration (required and recommended values, and definitions of settings in your Node.js agent's newrelic.js configuration file)
  • 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