Node.js agent configuration

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; they inherit their values from config/default.js.

Most configuration settings in newrelic.js have equivalent environment variables. These are useful, for example, if your agent runs in a PaaS environment 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.

If you're using New Relic APM and CodeStream, see how to associate repositories and how to associate build SHAs or release tags with errors inbox.

Owners and Admins can view and configure a few settings directly in New Relic. Where available, the UI labels for server-side config are listed in this document under individual config options as the Server-side label.

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.

Data for all applications with the same name will be merged in the New Relic UI, so set this carefully. We highly recommend that you replace the default name with a descriptive name to avoid confusion and unintended aggregation of data.

This setting is required. Your New Relic license key. For example, license_key: '40HexadecimalCharacters'.

Set to false to stop the agent from starting up. This is useful when debugging your code requires temporarily disabling the agent. It prevents the agent from bootstrapping its instrumentation or setting up all its pieces, which prevents the agent from starting up and connecting to New Relic's servers.

If true, enables capture of all HTTP headers, except for those filtered by exclude rules. If false, collected headers are limited to those defined in Node.js agent attributes.

Set your Apdex T via the New Relic UI.

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.

certificates: [ fs.readFileSync('myca.crt', {encoding: 'utf8'}) ]

When set to true, enables high security v2. You must also enable the ssl setting and enable high security in the UI.

Hostname for the New Relic collector to connect to the Internet; for example, host: 'collector.newrelic.com'.

Adds tags. Specify your tags as objects or a semicolon-delimited string of colon-separated pairs (for example, Server:One;Data Center:Primary).

Port number to connect to the New Relic collector; for example, port: 443.

A URL specifying the proxy server to connect to the Internet. For example, proxy: 'http://user:pass@10.0.0.1:8000/'. Important considerations:

• 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.
• If you're using Infinite Tracing: see how to configure a proxy for Infinite Tracing.

Hostname or IP address of the proxy server to connect to the Internet.

Password for authenticating to the proxy server. The agent supports only basic HTTP authentication.

Port number of the proxy server to connect to the Internet.

User name for authenticating to the proxy server. The agent supports only basic HTTP authentication.

Enables or disables agent specific logging.

Defines the level of detail recorded in the agent logs. From least detail to most detail, possible values are fatal, error, warn, info, debug, or trace.

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.

When enabled, the agent logs the payloads it sends to the collector. This data is included in the main log file even when logging level is set to the lowest level.

The agent sends several different types of data to the collector in separate payloads. By default, all of them are included in the log file. This option makes it possible to limit logging only to specific types of data.

Valid values include:

• agent_settings
• analytic_event_data
• connect
• custom_event_data
• error_data
• error_event_data
• metric_data
• preconnect
• shutdown
• span_event_data
• sql_trace_data
• transaction_sample_data

This option enables newrelic.addCustomAttribute and newrelic.addCustomAttributes.

This option enables recordCustomEvent.

This option enables newrelic.noticeError.

If true, enables capture of attributes for all destinations.

Prefix of attributes to exclude from all destinations. Allows * as wildcard at end.

Prefix of attributes to include from all destinations. Allows * as wildcard at end.

When true, patterns may be added to the attributes.include list.

When enabled, the agent collects error traces from your app.

Comma-delimited list of HTTP status codes for the error collector to ignore.

Comma-delimited list of javascript error types/classes for the error collector to ignore.

The following configuration

/* ... */
    error_collector: {
        ignore_classes: ["ReferenceError"]
    }
    /* ... */

Would ignore all reference errors.

A javascript object describing a list of javascript classes tied to javascript error messages for the collector to ignore. The following configuration.

/* ... */
    error_collector: {
        /* ... */
        ignore_messages: {"Error":["Undefined", "Out of time"]}
        /* ... */
    }
    /* ... */

Would ignore all errors of type Error, with the exact (case-sensitive) message strings of Undefined and Out of time.

Comma-delimited list of HTTP status codes for the error collector to mark as expected.

The following configuration

/* ... */
    error_collector: {
        expected_classes: ["ReferenceError"]
    }
    /* ... */

Would mark all reference errors as expected.

A javascript object describing a list of javascript classes tied to javascript error messages for the collector to ignore. The following configuration.

/* ... */
    error_collector: {
        /* ... */
        expected_messages: {"Error":["Undefined", "Out of time"]}
        /* ... */
    }
    /* ... */

Would mark all errors of type Error, with the exact (case-sensitive) message strings of Undefined and Out of time.

If true, the agent captures attributes from error collection.

Prefix of attributes to exclude from error collection. Allows * as wildcard at end.

Prefix of attributes to include in error collection. Allows * as wildcard at end.

Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.

When enabled, the agent collects slow transaction traces.

Minimum query duration (in milliseconds) for a transaction to be eligible for slow queries in transaction traces.

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.

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.

Threshold of web transaction response time in seconds beyond which a transaction is eligible for transaction tracing. The default value is apdex_f; this sets the trace threshold to four times your application's Apdex T. You can also enter a specific time value in milliseconds.

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.

The agent uses a small amount of CPU in order to hide internal properties that are attached to the web application. If you change this configuration to false, it may slightly decrease your agent overhead, but it could also have an impact on the performance of the agent.

If true, the agent captures attributes from transaction traces.

Prefix of attributes to exclude from transaction traces. Allows * as wildcard at end.

Prefix of attributes to include in transaction traces. Allows * as wildcard at end.

A comma-delimited list of rules to match incoming request URLs and name the associated New Relic transaction. Uses the format:

name: [
    {pattern: 'STRING_OR_REGEX', name: 'NAME'},

    {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"}'

Define a list of request URLs you want the agent to ignore. Specify the list as patterns, which can be strings or regular expressions.

When enabled, the agent renames transactions that are not affected by other naming logic (such as the API, rules, or metric normalization rules) to NormalizedUri/*. If you set this to false, the agent sets transaction names to Uri/path/to/resource.

When enabled, the agent sends transaction events to New Relic. 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 New Relic.

Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.

We do not recommend configuring past 10,000. The server will cap data at 10,000 per-minute.

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

Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.

If true, the agent captures attributes from transaction events.

Prefix of attributes to exclude from transaction events. Allows * as wildcard at end.

Prefix of attributes to include in transaction events. Allows * as wildcard at end.

Generate JavaScript headers for browser instrumentation. Although this defaults to true, the agent doesn't inject the browser JS code unless you have enabled browser monitoring. Even if you have enabled it and added the browser timing header, you can disable browser monitoring for your app by setting this to false.

If true, request un-minified sources from the server.

If true, the agent sends custom attributes to browser monitoring.

Prefix of attributes to exclude from browser monitoring. Allows * as wildcard at end.

Prefix of attributes to include in browser monitoring. Allows * as wildcard at end.

When enabled, the agent sends custom events recorded with recordCustomEvent() to New Relic. If this is disabled, the agent does not collect this data or send it to New Relic.

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.

When enabled, the agent collects slow query details.

Defines the maximum number of slow queries the agent collects per minute. The agent discards additional queries after the limit is reached.

Specify a custom hostname for display in New Relic. If you do not set this field, New Relic will continue to use the default hostname found by calling os.hostname().

• 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 (IPv4 or IPv6) that appears in the New Relic UI.

Path to the directory containing newrelic.js. This is available only as an environment variable. You cannot set it in your config file.

If used, this prevents the agent from reading configuration settings from newrelic.js. Default values and values from environment variables will still be set.

This is available only as an environment variable. You cannot set it in your config file.

When enabled, the agent collects datastore instance metrics (such as host and port) for some database drivers. These are reported on slow query traces and transaction traces.

When enabled, the agent collects database name on slow query traces and transaction traces for some database drivers.

When set to true, allows tracing of transactions across more than one New Relic-monitored applications.

When false, the agent will redact the messages of captured errors.

Set this to false to disable distributed tracing. For example, in the config file, you would use:

distributed_tracing: {
  enabled: false
}

Set this to true to exclude the New Relic header that is attached to outbound requests, and instead only rely on W3C Trace Context Headers for distributed tracing. If this is false then both types of headers are used.

For example, to enable this in the config file, you would use:

distributed_tracing:{
   enabled: true,
   exclude_newrelic_header: true
}

Turns reporting of span events on or off.

This setting can be used to turn reporting of attributes on or off for spans. If attributes.enabled at the root level is false, no attributes will be sent with spans regardless on how this is set.

If attributes are enabled for spans, all attribute keys found in this list will be attached to spans. For more information, see the agent attribute rules.

All attribute keys found in this list will not be sent with spans. For more information, see the agent attribute rules.

For help getting a valid Infinite Tracing trace observer host entry, see Find or create a trace observer endpoint.

Enables automatically generating logs in context.

Toggles whether the agent gathers Logging Metrics used in the Logs chart on the APM Summary page.

Toggles whether the agent gathers log records for sending to New Relic.

Number of log records to send per minute to New Relic. Controls the overall memory consumption when using log forwarding.

Toggles whether the agent performs Local Log Decoration on standard log output.