Configuration

The agent is configured from four sources: built-in defaults, a configuration file, NEW_RELIC_* environment variables, and settings sent by New Relic's servers when the agent connects. This page explains where each comes from, how they are combined, how environment variable strings are converted to typed values, and how validation works. Every individual setting is listed in the Configuration Reference.

The Configuration File

A configuration file is a JavaScript module that exports an object named config:

// newrelic.js (CommonJS)
'use strict'
exports.config = {
  app_name: ['Checkout Service'],
  license_key: 'your-license-key',
  logging: { level: 'info' },
  distributed_tracing: { enabled: true }
}
// newrelic.mjs (ES module)
export const config = {
  app_name: ['Checkout Service'],
  license_key: 'your-license-key'
}

Because the file is JavaScript, you can compute values (process.env, fs.readFileSync for certificates). The agent loads it with require(), so CommonJS is the most predictable format.

How the File Is Found

At startup the agent searches a fixed list of directories, and in each directory a fixed list of file names. It uses the first file that exists, checking every name in the first directory before moving to the next directory.

Directories, highest priority first:

  1. The directory in NEW_RELIC_HOME, if set.
  2. The current working directory (process.cwd()).
  3. The user's home directory (HOME), if set.
  4. The directory containing the node_modules folder the agent is installed in (typically your project root).
  5. The directory of the process's main module (the script passed to node), if there is one.

File names, highest priority first:

  1. The name in NEW_RELIC_CONFIG_FILENAME, if set.
  2. newrelic.js
  3. newrelic.cjs
  4. newrelic.mjs

For example, with NEW_RELIC_HOME=/etc/newrelic and NEW_RELIC_CONFIG_FILENAME=agent.js, the first candidates are /etc/newrelic/agent.js, /etc/newrelic/newrelic.js, /etc/newrelic/newrelic.cjs, /etc/newrelic/newrelic.mjs, then <cwd>/agent.js, and so on.

Note: The search happens when the agent loads, so NEW_RELIC_HOME and NEW_RELIC_CONFIG_FILENAME must be set in the environment before the process starts, not later from your code.

Skipping the file

NEW_RELIC_NO_CONFIG_FILE=true skips the search; the agent logs NEW_RELIC_NO_CONFIG_FILE set, deferring to environment variables. and builds its configuration from defaults and environment variables only.

When the file cannot be read

Situation Behavior
No file found Logs Unable to find configuration file. ... Attempting to start agent using environment variables. and continues.
The file throws when required (syntax error, missing module, no read access) Logs the error and Unable to read existing configuration file "<path>". ... Attempting to start agent using environment variables. and continues without the file.
The file loads but has no config export Treated like no file.
The config object fails schema validation The agent is disabled: stderr shows New Relic for Node.js is disabled due to an error: followed by New Relic configuration failed schema validation: and one line per problem.

The asymmetry matters: a file that cannot be loaded is silently skipped (only logged), but a file that loads with an invalid value turns the agent off.

Precedence

Values are applied from lowest to highest priority:

  1. Defaults from the configuration schema.
  2. Configuration file values.
  3. Special values: if no app_name is set and the APP_POOL_ID environment variable exists (Azure App Service), it is used, split on commas.
  4. Feature flag environment variables (NEW_RELIC_FEATURE_FLAG_<NAME>).
  5. NEW_RELIC_* environment variables, then the supported OTEL_* variables when the OpenTelemetry bridge is enabled.
  6. Serverless adjustments when serverless mode is on (see Serverless and Cloud).
  7. Deprecation warnings for deprecated settings you set.
  8. High security mode coercions, when high_security is true.
  9. Server-side configuration, applied after connecting (unless ignore_server_configuration is true).

Objects in the file are merged into the defaults key by key, so you only need to write the settings you change. Arrays are replaced, not merged: setting attributes.exclude: ['request.headers.cookie'] replaces the whole default list.

Unknown keys

The schema allows additional properties, so unknown keys do not fail validation. During merging, unknown keys are copied only at the top level and inside three free-form objects: labels, error_collector.ignore_messages, and error_collector.expected_messages. Anywhere else, a key that does not exist in the defaults is silently dropped — a misspelled nested key such as transaction_tracer.enable simply has no effect. The validator CLI will not flag it either, so double-check spelling against the Configuration Reference.

Environment Variables

Every setting has an environment variable. Most names are derived from the setting's path: NEW_RELIC_ plus the path segments joined with _, upper-cased. For example transaction_events.max_samples_stored is NEW_RELIC_TRANSACTION_EVENTS_MAX_SAMPLES_STORED.

Some older settings keep historical names that do not follow the pattern. The most common ones:

Setting Environment variable
agent_enabled NEW_RELIC_ENABLED
logging.level NEW_RELIC_LOG_LEVEL
logging.filepath NEW_RELIC_LOG
logging.enabled NEW_RELIC_LOG_ENABLED
proxy NEW_RELIC_PROXY_URL
ignore_server_configuration NEW_RELIC_IGNORE_SERVER_SIDE_CONFIG
ssl NEW_RELIC_USE_SSL
transaction_tracer.enabled NEW_RELIC_TRACER_ENABLED
transaction_tracer.transaction_threshold NEW_RELIC_TRACER_THRESHOLD
transaction_tracer.top_n NEW_RELIC_TRACER_TOP_N
transaction_tracer.record_sql NEW_RELIC_RECORD_SQL
transaction_tracer.explain_threshold NEW_RELIC_EXPLAIN_THRESHOLD
slow_sql.max_samples NEW_RELIC_MAX_SQL_SAMPLES
rules.name NEW_RELIC_NAMING_RULES
rules.ignore NEW_RELIC_IGNORING_RULES
error_collector.ignore_status_codes NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERROR_CODES
error_collector.expected_status_codes NEW_RELIC_ERROR_COLLECTOR_EXPECTED_ERROR_CODES
error_collector.ignore_classes NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERRORS
error_collector.expected_classes NEW_RELIC_ERROR_COLLECTOR_EXPECTED_ERRORS
browser_monitoring.enable NEW_RELIC_BROWSER_MONITOR_ENABLE
browser_monitoring.debug NEW_RELIC_BROWSER_MONITOR_DEBUG
api.custom_attributes_enabled NEW_RELIC_API_CUSTOM_ATTRIBUTES
api.custom_events_enabled NEW_RELIC_API_CUSTOM_EVENTS
api.notice_error_enabled NEW_RELIC_API_NOTICE_ERROR
datastore_tracer.instance_reporting.enabled NEW_RELIC_DATASTORE_INSTANCE_REPORTING_ENABLED
datastore_tracer.database_name_reporting.enabled NEW_RELIC_DATASTORE_DATABASE_NAME_REPORTING_ENABLED
process_host.ipv_preference NEW_RELIC_IPV_PREFERENCE
plugins.native_metrics.enabled NEW_RELIC_NATIVE_METRICS_ENABLED
newrelic_home NEW_RELIC_HOME

The Configuration Reference gives the exact variable for every setting.

How values are converted

Environment variables are strings. Only variables starting with NEW_RELIC_ that map to a known setting are applied; unknown ones are logged at debug level (Ignoring unrecognized New Relic environment variable ...) and ignored. Empty values are skipped, so NEW_RELIC_LOG_LEVEL= leaves the configured value unchanged.

Each value is converted according to the setting's schema type:

Setting type Conversion Example
boolean false, f, no, n, disabled, and 0 (case-insensitive) are false. Anything else is true. NEW_RELIC_ENABLED=off → true
integer parseInt(value, 10) NEW_RELIC_PORT=8443
number parseFloat(value) NEW_RELIC_APDEX_T=0.5
array Split on ,, each item trimmed NEW_RELIC_ATTRIBUTES_EXCLUDE=request.headers.cookie, response.headers.*
object (coerce=object) JSON.parse NEW_RELIC_ERROR_COLLECTOR_IGNORE_MESSAGES={"Error":["timeout"]}
object list JSON.parse('[' + value + ']') NEW_RELIC_NAMING_RULES={"pattern":"^/u/.*","name":"/users"}
regex new RegExp(value) NEW_RELIC_URL_OBFUSCATION_REGEX_PATTERN=token=[^&]+
enum (allow list) Kept if it is one of the allowed values, otherwise the first allowed value NEW_RELIC_RECORD_SQL=RAW → off
number or string A number when numeric, otherwise the raw string NEW_RELIC_TRACER_THRESHOLD=apdex_f
other / unions Passed through as the raw string NEW_RELIC_APP_NAME=a;b

Two consequences are easy to miss:

  • A typo in a boolean is treated as true. NEW_RELIC_ENABLED=flase enables the agent.
  • An enum value outside the allowed list is silently replaced by the first allowed value. Allowed values are case-sensitive, so NEW_RELIC_RECORD_SQL=RAW becomes off (the first entry of off, obfuscated, raw), not raw.

If JSON or regex parsing fails, the agent logs New Relic configurator could not deserialize object: (or ... object list: / ... could not validate regex: <value>) and the setting becomes undefined.

Application names

app_name can be an array of strings or a single string. A string from any source (file, NEW_RELIC_APP_NAME, APP_POOL_ID, server) is split on ; and , and each part trimmed, so NEW_RELIC_APP_NAME="Checkout; Checkout (all)" reports to two applications.

Labels

labels accepts an object or a ;-delimited key:value string, for example NEW_RELIC_LABELS="team:payments;env:prod". Names and values are truncated to 255 characters and at most 64 labels are kept. A malformed string (a pair without :, an empty key or value) discards all labels and logs Invalid Label String: ....

Feature flags

Prerelease behaviors are gated by flags under feature_flag. Each can be set in the file (feature_flag: { reverse_naming_rules: true }) or with NEW_RELIC_FEATURE_FLAG_<FLAG_NAME>:

Flag Default Effect
reverse_naming_rules false Applies naming rules in reverse order.
unresolved_promise_cleanup true Cleans up context for promises that never resolve. Disabling it can improve performance with many promises, but unresolved promises then leak memory.
kafkajs_instrumentation false Listed as the flag enabling kafkajs instrumentation.
undici_error_tracking true Creates errors when an undici request fails.
internal_test_only false Used only to test the flag mechanism.

Setting a flag that has already been released or removed logs Feature flag <name> has been released or ... has been deprecated.

Validating Your Configuration

The file's config object is validated against a JSON Schema (lib/config/schemas/) before use. The validator coerces simple scalar types in place — high_security: 'true' becomes true, port: '8080' becomes 8080 — so string values from computed configuration are tolerated. Other type mismatches fail validation and disable the agent.

Check a file before deploying with the bundled CLI:

npx newrelic validate-config -c ./newrelic.js

It applies the environment, reports schema errors and startup blockers (agent disabled, missing app name, missing license key, missing OpenTelemetry packages), and can print the fully resolved configuration with --dump. See Command-Line Tools.

Server-Side Configuration

When the agent connects, New Relic's reply carries configuration. Some values describe your account and are always accepted (for example apdex_t, account_id, primary_application_id, trusted_account_key, encoding_key, sampling targets, harvest limits, URL/metric/transaction naming rules, and browser monitoring keys). The reply can also contain an agent_config section holding server-side configuration set for your application in New Relic; its entries are processed with the same rules and can change settings such as error_collector.*, slow_sql.enabled, transaction_tracer.enabled, transaction_tracer.transaction_threshold, ai_monitoring.*, and profiling.enabled.

Set ignore_server_configuration: true (NEW_RELIC_IGNORE_SERVER_SIDE_CONFIG=true) to skip the agent_config section entirely and keep your local values.

Some settings are never taken from the server: the attributes.* include/exclude/enabled lists for every destination, transaction_events.max_samples_stored, and serverless_mode.enabled. A few (attributes.include_enabled, strip_exception_messages.enabled, transaction_tracer.record_sql) are logged as "not supported" when sent.

Note: apdex_t "can not be modified locally" according to its schema description: the server's value replaces it after connecting.

High Security Mode

high_security: true prevents sensitive data from being sent. It must match the setting for your account on the server; on a mismatch the agent logs a message and behaves as if disabled. When enabled, the agent forces these values, logging High Security Mode: <key> was set to <value>, coercing to <forced> for each change:

Setting Forced value
ssl true
strip_exception_messages.enabled true
allow_all_headers false
attributes.include and every <destination>.attributes.include []
transaction_tracer.record_sql obfuscated
slow_sql.enabled false
application_logging.forwarding.enabled false
ai_monitoring.enabled false
profiling.enabled false

It also appends request.parameters.* to attributes.exclude. In addition, the custom attribute, custom span attribute, and custom event API methods refuse to record anything, and noticeError drops custom attributes. See Attributes, Privacy, and Security.

Settings You Cannot Change

  • ssl only accepts true. Any other value logs SSL config key can no longer be disabled, not updating. and is ignored (in the file, the schema rejects it).
  • Core tracing flags: distributed_tracing.sampler.full_granularity.enabled is always true and ...partial_granularity.enabled always false; user values are ignored. Other partial_granularity settings are accepted but have no effect.
  • Load-time defaults: license_key defaults to '', logging.filepath to <cwd>/newrelic_agent.log, and serverless_mode.enabled to true only when AWS_LAMBDA_FUNCTION_NAME is present.

A Complete Example

'use strict'
exports.config = {
  app_name: ['Checkout Service'],
  license_key: process.env.NR_KEY,
  labels: { team: 'payments', env: 'prod' },
  logging: {
    level: 'info',
    filepath: 'stdout'
  },
  allow_all_headers: true,
  attributes: {
    exclude: [
      'request.headers.cookie',
      'request.headers.authorization',
      'request.headers.proxyAuthorization',
      'request.headers.setCookie*',
      'request.headers.x*',
      'response.headers.cookie',
      'response.headers.authorization',
      'response.headers.proxyAuthorization',
      'response.headers.setCookie*',
      'response.headers.x*'
    ]
  },
  distributed_tracing: {
    sampler: {
      root: { trace_id_ratio_based: { ratio: 0.25 } }
    }
  },
  error_collector: {
    ignore_status_codes: [404, 401],
    expected_classes: ['ValidationError']
  },
  application_logging: {
    forwarding: { enabled: true, max_samples_stored: 10000 }
  },
  rules: {
    ignore: ['^/health$']
  }
}

Best Practices

  • Keep secrets (license key, proxy password) in environment variables and out of committed files.
  • Validate in CI: npx newrelic validate-config -c ./newrelic.js -o json returns a machine-readable result and a non-zero exit code on problems.
  • Use exact values for enum settings (raw, not RAW) — invalid values are replaced, not rejected.
  • When you override a default array (such as attributes.exclude), copy the defaults you still want.
  • Log to stdout in containers, and reserve trace level for diagnosing issues: it is verbose and has overhead.

See Also