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:
- The directory in
NEW_RELIC_HOME, if set. - The current working directory (
process.cwd()). - The user's home directory (
HOME), if set. - The directory containing the
node_modulesfolder the agent is installed in (typically your project root). - The directory of the process's main module (the script passed to
node), if there is one.
File names, highest priority first:
- The name in
NEW_RELIC_CONFIG_FILENAME, if set. newrelic.jsnewrelic.cjsnewrelic.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_HOMEandNEW_RELIC_CONFIG_FILENAMEmust 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:
- Defaults from the configuration schema.
- Configuration file values.
- Special values: if no
app_nameis set and theAPP_POOL_IDenvironment variable exists (Azure App Service), it is used, split on commas. - Feature flag environment variables (
NEW_RELIC_FEATURE_FLAG_<NAME>). NEW_RELIC_*environment variables, then the supportedOTEL_*variables when the OpenTelemetry bridge is enabled.- Serverless adjustments when serverless mode is on (see Serverless and Cloud).
- Deprecation warnings for deprecated settings you set.
- High security mode coercions, when
high_securityistrue. - Server-side configuration, applied after connecting (unless
ignore_server_configurationistrue).
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=flaseenables 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=RAWbecomesoff(the first entry ofoff,obfuscated,raw), notraw.
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
sslonly acceptstrue. Any other value logsSSL 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.enabledis alwaystrueand...partial_granularity.enabledalwaysfalse; user values are ignored. Otherpartial_granularitysettings are accepted but have no effect. - Load-time defaults:
license_keydefaults to'',logging.filepathto<cwd>/newrelic_agent.log, andserverless_mode.enabledtotrueonly whenAWS_LAMBDA_FUNCTION_NAMEis 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 jsonreturns a machine-readable result and a non-zero exit code on problems. - Use exact values for enum settings (
raw, notRAW) — invalid values are replaced, not rejected. - When you override a default array (such as
attributes.exclude), copy the defaults you still want. - Log to
stdoutin containers, and reservetracelevel for diagnosing issues: it is verbose and has overhead.