Skip to main content

Installation of the Node.js agent

To use the WhaTap monitoring service, after Sign in, create a project and install the agent to the target server. For more information about registration as a member, see the following.

See the following video guide.

To use the Node.js monitoring service, the monitoring agent must be installed on the monitored application. For installation, use NPM (Node Package Manager).

  • Install the WhaTap agent module in the active Node.js application directory.

  • Write the configuration of WhaTap agent (whatap.conf).

  • Run the Node.js service again.

Creating a project

Create a project before installing the agent.

  1. Log in WhaTap monitoring service.

  2. To create a project, on the left of the screen, select All Projects > + Project.

  3. Select a product in Select product for installation.

  4. Configure the settings for Project name, Data server region, and Time zone.

    Create Project

  5. In Notification language setting, select the language for alert messages.

  6. After all settings are finished, select Creating a project.

  • A Data server region refers to a region (a bundle of data centers installed to provide cloud services). Selecting a specific region stores your data in the datacenter that belongs to that region.

  • Time zone is the reference time for generating alerts and reports.

  • To group multiple projects for management, select a group from Project groups or add a group. For more information about grouping, see the following.

  • To add a project with an organization selected, Groups of organization must be set.

Checking the access key

The access key is the unique ID to enable the WhaTap service.

In the installation guide section, select Getting the access key. After the access key has been issued automatically, proceed to the next step.


After a project has been created, the Agent installation page appears automatically. If the Agent installation does not appear, select Management > Agent installation on the left of the screen.

Download agent

  1. Install the agent in the active Node.js application directory.

    $ npm install --save whatap
  2. Copy the whatap.conf file in the node_modules/whatap path and then paste it into the root path of the source code.

  3. Go to the WhaTap Monitoring Service.

  4. Select the created project and then copy the following among the downloaded items from the agent in the Install guide section.

    license={access key}{collection server IP}
  5. Paste it into the whatap.conf file.

The host ( address is the server address in which the WhaTap proxy has been installed. You can use a forward slash (/) as the delimiter to enter all addresses of the servers where the proxy server is running among the WhaTap servers.

Node.js agent configuration file

The roles of each file that makes up the Node.js monitoring service are as follows:

  • whatap.conf: Sample of the agent configuration file. Copy the file and enter the access key.

  • lib: Agent and tracer program

  • Guide to the agent installation

  • package.json: Configuration file for the NPM module environment

  • index.js: Main export declaration file


Server-side rendering (SSR) frameworks such as Next.js and Nuxt.js require the Custom Server settings for application monitoring. It requires an approach different from typical Node.js frameworks (e.g. Express.js, Nest.js). For more information, see the following:


Add the following code at the top of the entry point (main module) file of the application. For example, in the Express.js application, app.js and server.js are the entry points (main module). When using a framework like Nest.js, main.ts is the entry point.

var whatap = require('whatap').NodeAgent;

To use ECMAScript (ES), add the following code together.

import WhatapAgent from 'whatap';

See the following application example:

var WhatapAgent = require('whatap').NodeAgent;
import http from 'http';
import setupApp from '../src/app';
let server = null;
const port = normalizePort(process.env.PORT || '3000');

Because the agent executable code needs to be run first after starting node.js, it must be placed before the first import.

After installation, see the following to make sure there is no problem.

Separating whatap.conf files for each environment

In the following cases, set the file names excluding .conf.

  • In case of separating the projects for each environment

  • In case the agent options are set differently

  • In case of starting by pm2 in Cluster mode

process.env.WHATAP_CONF = 'whatapdev';
process.env.WHATAP_NAME = 'NodeAgent-{ip2}-{ip3}-{cluster}';
var WhatapAgent = require('whatap').NodeAgent;

The arguments that can be set by the WHATAP_NAME option are as follows.

  • ipN: ip0, ip1, ip2, ip3

  • cluster: Cluster ID

  • pid: Process ID

  • hostname: Host name

Using the agent group unit function

Agent group unit function includes group topology and integrated topology. Replace {group identifier} with agent group name in the following code.

process.env.WHATAP_OKIND = '{group identifier}';
var WhatapAgent = require('whatap').NodeAgent;

PaaS application environment

Configuring the default environment variables

When installing the agent in the PaaS application, all settings must be configured in the source file (app.js). The whatap.conf file cannot be used.

Set the access key (WHATAP_LICENSE) and collection server IP (WHATAP_SERVER_HOST) as environment variables.

process.env.WHATAP_LICENSE={Access Key};
process.env.WHATAP_SERVER_HOST={Collection Server IP};
var whatap=require('whatap').NodeAgent;

Options that can be configured as environment variables

Because you cannot use the whatap.conf file, set the WhaTap agent options as environment variables in the source file.





For more information about the options that can be set in Node.js, see the following.

Starting the monitoring

Once the application server has been restarted, the agent starts collecting data.