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.

NEW_RELIC_APP_NAME

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.

NEW_RELIC_HOME
Path to the directory where you placed newrelic.js.
NEW_RELIC_LICENSE_KEY (required)
Your New Relic license key. Required for your app's configuration file. If used, this overrides LICENSE_KEY.
NEW_RELIC_LOG
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.
NEW_RELIC_LOG_LEVEL

How verbose is the logging priority 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.

Caution: 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.

NEW_RELIC_NO_CONFIG_FILE
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.
NEW_RELIC_USE_SSL

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

Caution: 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.

NEW_RELIC_APDEX
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.
NEW_RELIC_BROWSER_MONITOR_ENABLE
Generate JavaScript headers for page load timing (sometimes referred to as real user monitoring or RUM). Default is TRUE. It does not auto-instrument, but you can disable the JavaScript from being embedded by setting this to FALSE.
NEW_RELIC_CAPTURE_PARAMS
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.
NEW_RELIC_ENABLED
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.
NEW_RELIC_ERROR_COLLECTOR_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.
NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERROR_CODES
Comma-delimited list of HTTP status codes for the error collector to ignore. Defaults to 404 NOT FOUND. If used, this overrides IGNORE_STATUS_CODES.
NEW_RELIC_IGNORE_SERVER_CONFIGURATION
Whether to ignore server-side configuration for this application. Defaults to FALSE. If used, this overrides IGNORE_SERVER_CONFIGURATION.
NEW_RELIC_IGNORED_PARAMS
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.
NEW_RELIC_IGNORING_RULES
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:

NEW_RELIC_IGNORING_RULES='^/socket\.io/\*/xhr-polling,ignore_me'

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

NEW_RELIC_NAMING_RULES

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

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

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

NEW_RELIC_TRACER_ENABLED
Whether to collect and submit slow transaction traces to New Relic. Values are TRUE (default) or FALSE. If used, this overrides transaction_tracer : { ENABLED.
NEW_RELIC_TRACER_THRESHOLD
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 ApdexT. For example, the default APDEX value for Node.js is 100 milliseconds. If this is set to APDEX_F, a slow transaction trace is 400 milliseconds, or approximately half a minute. If used, this overrides TRANSACTION_THRESHOLD.
NEW_RELIC_TRACER_TOP_N

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.

Rarely changed options

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

NEW_RELIC_DEBUG_METRICS
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.
NEW_RELIC_DEBUG_TRACER
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.
NEW_RELIC_ENFORCE_BACKSTOP

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.

Caution: 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.

NEW_RELIC_HOST
Host name for the New Relic collector to connect to the internet. You should not need to change this. If used, this overrides HOST.
NEW_RELIC_PORT
Port number on which the New Relic collector will be listening. You should not need to change this. If used, this overrides PORT.
NEW_RELIC_PROXY_HOST

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

Note: Proxy authentication currently is not supported. For more information, see Known Node.js limitations.

NEW_RELIC_PROXY_PORT

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.

Note: Proxy authentication currently is not supported. For more information, see Known Node.js limitations.

For more help

Additional documentation resources include:

  • Node.js configuration options (hierarchy of configuration options and an explanation of server-side and configuration file options)
  • Customizing your Node.js config file (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)

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