---
title: Node.js agent general settings
source: https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration-general-settings
---

This page covers the core Node.js agent settings including app name, license key, proxy configuration, and how configuration methods interact.

> #### 💡 TIP
>
> Back to the full settings index: [Node.js agent configuration](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration)

## Get started [#requirements]

You'll be able to configure our Node.js agent to suit your environment after you [create a New Relic account](https://newrelic.com/signup) (it's free, forever) and [install the Node.js agent](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/install-nodejs-agent/).

The [`license_key`](#license) setting is required. Also, we highly recommend setting the [`app_name`](#app_name) so that your app has a [meaningful name](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/name-your-application) instead of the default `My Application`.

## Configuration methods and precedence [#methods-and-precedence]

The primary method to configure the Node.js agent is the agent configuration file (`newrelic.js`). You can also configure most settings with [environment variables](#environment). You can also adjust some settings with [server-side configuration](#server-side).

The Node.js agent uses this order of precedence for configuration methods:

![Node.js agent configuration precedence](https://docs.newrelic.com/images/apm_diagram_nodejs-agent-configuration-hierarchy.webp "Node.js agent configuration precedence")

**Node.js configuration hierarchy:** Server-side configuration settings override environment variables. Environment variables override the agent config file. The config file overrides the agent defaults.

Here are detailed descriptions of each configuration method:

**Agent configuration file**

The config file (`newrelic.js`) contains every Node.js agent setting. When you [install the Node.js agent](https://docs.newrelic.com/docs/agents/nodejs-agent/installation-configuration/installing-maintaining-nodejs#installing), 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`.

If your application is running on CommonJS, simply change the configuration file type to (`newrelic.cjs`). This filetype is supported as of [v7.5.0](https://docs.newrelic.com/docs/release-notes/agent-release-notes/nodejs-release-notes/node-agent-7-5-0/) of the Node.js agent.

**Environment variables**

All 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_`.

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](#environment-variable-overrides). If you are unsure how to specify more complex types as environment variables, [use the reference guide](#environment-variable-type-reference-guide).

If you're using New Relic CodeStream to monitor performance from your IDE, you may also want to [associate repositories with your services](https://docs.newrelic.com/docs/codestream/observability/repo-association) and [associate build SHAs or release tags with errors](https://docs.newrelic.com/docs/codestream/observability/error-investigation/#buildsha).

**Server-side configuration**

Owners and Admins can view and configure a few settings [directly in New Relic](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/server-side-agent-configuration). Where available, the UI labels for server-side config are listed in this document under individual config options as the **Server-side label**.

## Exports variables [#exports_config]

This section defines the Node.js agent variables in the order they typically appear in the `exports.config = {` section of your app's `newrelic.js` configuration file.

**app_name (REQUIRED)**

| Type                             | String               |
| -------------------------------- | -------------------- |
| Default                          | `"My Application"`   |
| [Environ variable](#environment) | `NEW_RELIC_APP_NAME` |

The [name New Relic uses to identify your app](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/name-your-application). For example, `app_name: ['MyNodeApp']`. To [use multiple names for your app](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/use-multiple-names-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.

> #### 💡 TIP
>
> For [Azure users](https://docs.newrelic.com/docs/agents/nodejs-agent/hosting-services/nodejs-agent-microsoft-azure), 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.

**license_key (REQUIRED)**

| Type                             | String                  |
| -------------------------------- | ----------------------- |
| Default                          | (none)                  |
| [Environ variable](#environment) | `NEW_RELIC_LICENSE_KEY` |

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

**agent_enabled**

| Type                             | Boolean             |
| -------------------------------- | ------------------- |
| Default                          | `true`              |
| [Environ variable](#environment) | `NEW_RELIC_ENABLED` |

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.

**allow_all_headers**

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](https://docs.newrelic.com/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-attributes).

| Type                             | Boolean                       |
| -------------------------------- | ----------------------------- |
| Default                          | `false`                       |
| [Environ variable](#environment) | `NEW_RELIC_ALLOW_ALL_HEADERS` |

> #### ⚠️ CAUTION
>
> Any header-related include/exclude rules must be in camelCase form to be filtered.

**compressed_content_encoding**

If the data compression threshold is reached in the payload, the agent compresses data, using gzip compression by default. The config option `compressed_content_encoding` can be set to `deflate` to use deflate compression.

| Type                             | String                                  |
| -------------------------------- | --------------------------------------- |
| Default                          | `gzip`                                  |
| [Environ variable](#environment) | `NEW_RELIC_COMPRESSED_CONTENT_ENCODING` |

**apdex_t (DEPRECATED)**

| Type                              | Number              |
| --------------------------------- | ------------------- |
| Default                           | `0.100`             |
| [Server-side label](#server-side) | `Apdex T`           |
| [Environ variable](#environment)  | `NEW_RELIC_APDEX_T` |

Set your Apdex T [via the New Relic UI](https://docs.newrelic.com/docs/apm/new-relic-apm/apdex/apdex-measure-user-satisfaction/#apm-apdex).

**certificates**

| Type                             | Array of strings         |
| -------------------------------- | ------------------------ |
| Default                          | `[]`                     |
| [Environ variable](#environment) | `NEW_RELIC_CERTIFICATES` |

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.

> #### 💡 TIP
>
> You can also configure the agent to read its certificates from a file:
>
> ````js
> certificates: [ fs.readFileSync('myca.crt', {encoding: 'utf8'}) ]
> ```
>
> ````

**high_security**

| Type                             | Boolean                   |
| -------------------------------- | ------------------------- |
| Default                          | `false`                   |
| [Environ variable](#environment) | `NEW_RELIC_HIGH_SECURITY` |

When set to `true`, enables [high security v2](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security#version2description). You must also enable the [`ssl`](#ssl) setting and [enable high security in the UI](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security#version2enabled).

**host**

| Type                             | String                   |
| -------------------------------- | ------------------------ |
| Default                          | `collector.newrelic.com` |
| [Environ variable](#environment) | `NEW_RELIC_HOST`         |

> #### ⚠️ IMPORTANT
>
> Do not edit this value unless New Relic Support asks you to change it.

Hostname for the [New Relic collector](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#collector) to connect to the Internet; for example, `host: 'collector.newrelic.com'`.

**labels**

Adds [tags](https://docs.newrelic.com/docs/apm/new-relic-apm/maintenance/labels-categories-organize-your-apps-servers). Specify your tags as objects or a semicolon-delimited string of colon-separated pairs (for example, `Server:One;Data Center:Primary`).

| Type                             | Object or string   |
| -------------------------------- | ------------------ |
| Default                          | (none)             |
| [Environ variable](#environment) | `NEW_RELIC_LABELS` |

**port**

| Type                             | Integer          |
| -------------------------------- | ---------------- |
| Default                          | `443`            |
| [Environ variable](#environment) | `NEW_RELIC_PORT` |

> #### ⚠️ IMPORTANT
>
> Do not edit this value unless New Relic Support asks you to change it.

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

**proxy**

| Type                             | String                |
| -------------------------------- | --------------------- |
| Default                          | (none)                |
| [Environ variable](#environment) | `NEW_RELIC_PROXY_URL` |

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](https://docs.newrelic.com/docs/distributed-tracing/infinite-tracing/introduction-infinite-tracing): [see how to configure a proxy for Infinite Tracing](https://docs.newrelic.com/docs/distributed-tracing/infinite-tracing/infinite-tracing-configure-proxy-support/#node-php-python-ruby).

**proxy_host**

| Type                             | String                 |
| -------------------------------- | ---------------------- |
| Default                          | (none)                 |
| [Environ variable](#environment) | `NEW_RELIC_PROXY_HOST` |

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

**proxy_pass**

| Type                             | String                 |
| -------------------------------- | ---------------------- |
| Default                          | (none)                 |
| [Environ variable](#environment) | `NEW_RELIC_PROXY_PASS` |

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

**proxy_port**

| Type                             | String                 |
| -------------------------------- | ---------------------- |
| Default                          | (none)                 |
| [Environ variable](#environment) | `NEW_RELIC_PROXY_PORT` |

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

**proxy_user**

| Type                             | String                 |
| -------------------------------- | ---------------------- |
| Default                          | (none)                 |
| [Environ variable](#environment) | `NEW_RELIC_PROXY_USER` |

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