# Install APM Insight Node.js Agent

For seamless onboarding, you can use the [APM Insight AutoProfiler](https://www.manageengine.com/products/applications_manager/help/apm-insight-autoprofiler-overview.html) to automatically discover and instrument Node.js applications running on your server.

- [APM Insight Node.js agent version 4.0.0 and above](https://www.manageengine.com/products/applications_manager/help/apm-insight-nodejs-agent-install.html#4.0.0andabove)
- [APM Insight Node.js agent versions above 1.7.2 and below 4.0.0](https://www.manageengine.com/products/applications_manager/help/apm-insight-nodejs-agent-install.html#above1.7.2andbelow4.0.0)
- [APM Insight Node.js agent versions 1.7.2 and below](https://www.manageengine.com/products/applications_manager/help/apm-insight-nodejs-agent-install.html#1.7.2andbelow)

## APM Insight Node.js agent version 4.0.0 and above

**Prerequisite:** Ensure that your Node.js application is running version v18 or later before proceeding to install the APM Insight Node.js Agent.

1. To add a new Node.js Agent monitor in Applications Manager, go to the **APM** tab → **Add New Monitor** → **Node.js**

![Applications Manager Installing APM Insight Node.js Agent: Adding Node.js monitor](https://www.manageengine.com/products/applications_manager/help/images/apm-insight-nodejs-agent-add-monitor-1.png)

![Applications Manager Installing APM Insight Node.js Agent: Add monitor steps for Node.js agent v4 and above](https://www.manageengine.com/products/applications_manager/help/images/apm-insight-nodejs-agent-add-monitor-3.png)

2. Download the [APM Insight Node.js Agent](https://www.manageengine.com/products/applications_manager/apm-insight-agent-installation.html#nodejsAgent) (*apm_insight_agent_nodejs.zip*) file and extract it on the Node.js server.

3. Use the following command to install an APM Insight Node.js agent from the agent directory.

```bash
npm install <Node.js-Agent-unzipped-path>/agent_minified
```

**Example:**

```bash
npm install /users/joe/agent_minified
```

If you want to deploy the APM Insight agent to all the Node.js applications on the computer, use the global option via the **-g** flag.

```bash
npm install -g <Node.js-Agent-unzipped-path>/agent_minified
```

**Example:**

```bash
npm install -g /users/joe/agent_minified
```

This will create an APM Insight directory under **node_modules**.

4. Use the following command to install an APM Insight Node.js agent from the application-installed directory.

```bash
npm install <Node.js-Agent-unzipped-path>/agent_minified
```

**Example:**

```bash
npm install /users/joe/agent_minified
```

5. You can either [create a file and add the configuration values](https://www.manageengine.com/products/applications_manager/help/apm-insight-nodejs-agent-install.html#addconfigurationvalues) to it or you can [set the configuration values as environment variables](https://www.manageengine.com/products/applications_manager/help/apm-insight-nodejs-agent-install.html#environmentvariables).

### Create a file and add configuration values

Create a new file named **apminsightnode.json** and place it in the directory where you run the application. Add the below code snippet to the file:

```json
{
  "licenseKey": "[LICENSE-KEY]",
  "appName": "[APPLICATION-NAME]",
  "port": "[APPLICATION-PORT]",
  "apmHost": "[APM-HOST-NAME]",
  "apmPort": "[APM-SSL-PORT]"
}
```

**Example:**

```json
{
  "licenseKey": "APMI_ee42094f83dd841d16b9c56796c22b63bef00ac6918f547280947d1f6c2be1ea",
  "appName": "APMInsight_NodeJSapp",
  "port": "3000",
  "apmHost": "localhost",
  "apmPort": "8443"
}
```

If you are using a proxy, add the below code snippet:

```json
{
  "licenseKey": "[LICENSE-KEY]",
  "appName": "[APPLICATION-NAME]",
  "port": "[APPLICATION-PORT]",
  "apmHost": "[APM-HOST-NAME]",
  "apmPort": "[APM-SSL-PORT]",
  "proxyServerHost": "[PROXY-SERVER]",
  "proxyServerPort": "[PROXY-PORT]",
  "proxyAuthUser": "[PROXY-USERNAME]",
  "proxyAuthPassword": "[PROXY-PASSWORD]"
}
```

**Note:** If Applications Manager is configured with failover support, add multiple hosts in the `apmHost` column using the full URL.  
**For example:** *https://apm-prod-1:8443,https://apm-prod-2:8443*  
(Only HTTPS URLs are supported, and this feature is available from agent version 4.4.1.)

### Set configuration values as environment variables

You can set configuration values as environment variables using the following keys:

- `licenseKey` - **APMINSIGHT_LICENSE_KEY**
- `appName` - **APMINSIGHT_APP_NAME**
- `port` - **APMINSIGHT_APP_PORT**
- `proxyServerHost` - **APMINSIGHT_PROXYSERVER_HOST**
- `proxyServerPort` - **APMINSIGHT_PROXYSERVER_PORT**
- `proxyAuthUser` - **APMINSIGHT_PROXYAUTH_USER**
- `proxyAuthPassword` - **APMINSIGHT_PROXYAUTH_PASSWORD**
- `apm hostname` - **APMINSIGHT_APM_HOST**
- `apm port` - **APMINSIGHT_APM_PORT**

6. Include the given code in the first line of your Node.js application start file, before any other require statements.

| JavaScript | Code snippet |
|---|---|
| Common JS | `require('apminsight');` |
| ECMAScript | `import apminsight from 'apminsight';` |
| TypeScript | `import AgentAPI from 'apminsight';`<br>`AgentAPI.config();` |

Alternatively, you can follow either of the methods given below, which are common across all JavaScript types:

- Using environmental variable:  
  *export NODE_OPTIONS="-r apminsight"*
- Include the **require** statement in the start script or when you start your application:  
  *node -r apminsight my-start-file.js*

**Note:** `-r` is used to pre-load the specified module (`apminsight` module here) at startup. Only CommonJS modules support `-r`. Use `--import` to pre-load a TypeScript or ECMAScript module.

7. **Optional:** You can install [Applications Manager Data Exporter](https://www.manageengine.com/products/applications_manager/help/apm-insight-data-exporter.html) on both Windows and Linux. You can set it up in either of these ways:

- Enable the Data Exporter using:
  - **apminsightnode.json** file: `dataExporterEnabled` - `true`
  - Environment variable: `APMINSIGHT_DATA_EXPORTER_ENABLED` - `true`
- Setting custom Data Exporter configurations for the host, status, and data port in:
  - **apminsightnode.json** file:

| `dataExporterHost` | String |
|---|---|
| `dataExporterDataPort` | Int |
| `dataExporterStatusPort` | Int |

  - Environment variables:

| `APMINSIGHT_DATA_EXPORTER_HOST` | String |
|---|---|
| `APM_EXPORTER_DATA_PORT` | Int |
| `APM_EXPORTER_STATUS_PORT` | Int |

Below are the default configurations:

| Variable | Default value |
|---|---|
| Host | localhost |
| DataPort | 20022 |
| StatusPort | 20021 |

**Example:**

```json
{
  ...
  "dataExporterHost": "localhost",
  "dataExporterStatusPort": "20021",
  "dataExporterDataPort": "20022"
  ...
}
```

**Note:** Applications Manager Data Exporter is supported from agent version 5.4.1.

8. Lastly, restart the application and carry out a few transactions to see data in the web client.

## APM Insight Node.js agent versions above 1.7.2 and below 4.0.0

**Note:** We highly recommend downloading the latest version of the APM Insight Node.js agent. However, if you need to download agent versions below 4.0.0 for any specific reason, refer to the steps below.

To install APM Insight Node.js agent versions 1.7.2 to versions below 4.0.0:

1. To add a new Node.js Agent monitor in Applications Manager, go to the **APM** tab → **Add New Monitor** → **Node.js**

![Applications Manager Installing APM Insight Node.js Agent: Adding the monitor](https://www.manageengine.com/products/applications_manager/help/images/apm-insight-nodejs-agent-add-monitor-1.png)

![Applications Manager Installing APM Insight Node.js Agent: Add monitor steps for Node.js agent v1.7.2 to v4](https://www.manageengine.com/products/applications_manager/help/images/apm-insight-nodejs-agent-add-monitor-2.png)

2. Download the APM Insight Node.js Agent file (*apm_insight_agent_nodejs.zip*) from the [download page](https://www.manageengine.com/products/applications_manager/apm-insight-agent-installation.html) and extract it on the Node.js server.

3. Use the following command to install an APM Insight Node.js agent from NPM.

```bash
npm install <Node.js-Agent-unzipped-path>/agent_minified
```

**Example:**

```bash
npm install /users/joe/agent_minified
```

If you want to deploy the APM Insight agent to all Node.js applications on the computer, use the global option via the **-g** flag.

```bash
npm install -g <Node.js-Agent-unzipped-path>/agent_minified
```

**Example:**

```bash
npm install -g /users/joe/agent_minified
```

This will create an APM Insight directory under **node_modules**.

4. Create a new file named **apminsightnode.json** in the same directory as your application start file. Add the below code snippet to the file:

```json
{
  "licenseKey": "[LICENSE-KEY]",
  "appName": "[APPLICATION-NAME]",
  "port": "[APPLICATION-PORT]",
  "apmHost": "[APM-HOST-NAME]",
  "apmPort": "[APM-SSL-PORT]"
}
```

**Example:**

```json
{
  "licenseKey": "APMI_ee42094f83dd841d16b9c56796c22b63bef00ac6918f547280947d1f6c2be1ea",
  "appName": "APMInsight_NodeJSapp",
  "port": "3000",
  "apmHost": "localhost",
  "apmPort": "8443"
}
```

5. If you use proxy connections, enter this code instead:

```json
{
  "licenseKey": "[LICENSE-KEY]",
  "appName": "[APPLICATION-NAME]",
  "port": "[APPLICATION-PORT]",
  "apmHost": "[APM-HOST-NAME]",
  "apmPort": "[APM-SSL-PORT]",
  "proxyServerHost": "[PROXY-SERVER]",
  "proxyServerPort": "[PROXY-PORT]",
  "proxyAuthUser": "[PROXY-USERNAME]",
  "proxyAuthPassword": "[PROXY-PASSWORD]"
}
```

6. Include the following code in the first line of your Node.js application start file.

```javascript
// If using Common JS:
require('apminsight')()

// If using ES:
import apminsight from 'apminsight';
apminsight.config()
```

7. Save the file and restart your application.

**Note:**

- The APM Insight Node.js Agent is incompatible with other profiling tools, such as running the node process with the debugger mode (`--inspect` switch).
- If your application uses the cluster module, place the require statement in both the master and worker processes.
- If you are unable to add the application port in the **apminsightnode.json** file, you can add it in your application start file as mentioned below:

```javascript
require('apminsight')
(
  { port: <application port> }
)
```

However, other parameters like license key and app name should be added only in the **apminsightnode.json** file.

- You can also set configuration values like license key, app name, and port as environment variables using the following keys:
  - **License key** - *APMINSIGHT_LICENSE_KEY*
  - **App Name** - *APMINSIGHT_APP_NAME*
  - **Port** - *APMINSIGHT_APP_PORT*
  - **APM Host** - *APMINSIGHT_APM_HOST*
  - **APM Port** - *APMINSIGHT_APM_PORT*

## APM Insight Node.js agent version 1.7.2 and below

**Note:** We highly recommend downloading the latest version of the APM Insight Node.js agent. However, if you need to download agent versions below 1.7.2 for any specific reason, refer to the steps below.

1. To add a new Node.js Agent monitor in Applications Manager, go to the **APM** tab → **Add New Monitor** → **Node.js**.
2. Download the APM Insight Node.js Agent file (*apm_insight_agent_nodejs.zip*) from the [download page](https://www.manageengine.com/products/applications_manager/apm-insight-agent-installation.html) and extract it on the Node.js server.
3. Open your Node.js application.
4. Access the Node Package Manager (NPM).
5. Use the following command to install an APM Insight Node.js agent from NPM.

```bash
npm install <Node.js-Agent-unzipped-path>/agent_minified
```

**Example:**

```bash
npm install /users/joe/agent_minified
```

If you want to deploy the APM Insight agent to all Node.js applications on the computer, use the global option via the **-g** flag.

```bash
npm install -g <Node.js-Agent-unzipped-path>/agent_minified
```

**Example:**

```bash
npm install -g /users/joe/agent_minified
```

This will create an APM Insight directory under **node_modules**.

6. Include the following code in the first line of your Node.js application source code, before any other require statement. Replace the variables with the values for your setup.

```javascript
require('apminsight')({
  licenseKey: '[LICENSE-KEY]',
  appName: '[APPLICATION-NAME]',
  port: [APPLICATION-PORT],
  apmHost: '[APM-HOST-NAME]',
  apmPort: [APM-SSL-PORT]
})
```

**Example:**

```javascript
require('apminsight')({
  licenseKey: 'APMI_ee42094f83dd841d16b9c56796c22b63bef00ac6918f547280947d1f6c2be1ea',
  appName: 'Insight_NodeJS',
  port: 3000,
  apmHost: 'localhost',
  apmPort: 8443
})
```

7. If you use proxy connections, enter this code instead:

```javascript
require('apminsight')({
  licenseKey: '[LICENSE-KEY]',
  appName: '[APPLICATION-NAME]',
  port: [APPLICATION-PORT],
  apmHost: '[APM-HOST-NAME]',
  apmPort: [APM-SSL-PORT],
  proxyServerHost: '[PROXY-SERVER]',
  proxyServerPort: [PROXY-PORT],
  proxyAuthUser: '[PROXY-USERNAME]',
  proxyAuthPassword: '[PROXY-PASSWORD]'
})
```

8. Save the file and restart your application.