Installation and Configuration of JENNIFER Agent (Node.js)

This chapter describes how to install the JENNIFER Node.js Agent.

Versions Supporting Node.js Agent

Supported OSs

Supported Linux Distribution


Supported Node.js Versions

Supported Jennifer5 Server Version

Agent package installation

Install the package using a Node.js package manager (npm, yarn, etc.)

$ # Run the following command in your Node.js project directory
$ npm install @jennifersoft/jennifer5-instrumentation

OS-wide installation

If you do not want to modify package.json, you can consider copying the Jennifer package to /node_modules. This allows multiple Node.js applications on the same OS to reference the Jennifer agent package with a single installation.

$ mkdir ~/jennifer-nodejs
$ cd ~/jennifer-nodejs
$ 
$ wget https://jennifer5-release-public.s3.ap-northeast-2.amazonaws.com/agent/nodejs/jennifer-nodejs-5.6.5-x64.zip
$ unzip jennifer-nodejs-5.6.5-x64.zip
$
$ sudo ./install.sh
$
$ ls -al /node_modules
lrwxrwxrwx     - root 11  Mar 10:14 @jennifersoft -> /opt/jennifer/nodejs/current/node_modules/@jennifersoft

Node.js searches for packages in the node_modules directory. If the desired package is not found, it continues searching in the node_modules directories of parent directories up to the root directory. For example, if require("bar") is called, Node.js will look for the bar package in the following locations:


See https://nodejs.org/api/modules.html#loading-from-node-modules-folders for reference.

Jennifer agent configuration

Configure the data server connection information and logger in jennifer.toml.

# jennifer5 server address
server_address = "127.0.0.1"

# jennifer5 server port
server_port = 5000

# domain_id
domain_id = 1000

# logger output target: stderr | stdout | file
log_to = "file"

# logger level: trace | debug | info | warn | error
log_level = "info"

# log directory when log_to is "file"
log_dir = "./logs"

The Jennifer agent searches for the following files in order. If the environment variable JENNIFER_CONFIG_PATH is set, the file at that path will be used as the configuration file.

  1. ./jennifer.toml

  2. /etc/jennifer/jennifer.toml

  3. /etc/jennifer/conf/jennifer.toml

You can also configure settings using environment variables; if an environment variable exists, its value will override the value in jennifer.toml.


Starting the Jennifer agent

To instrument a Node.js application, the Jennifer agent package must be loaded first.

Option 1: Using command-line arguments

CommonJS application

$ node --require @jennifersoft/jennifer5-instrumentation/auto your_server.js

ESM application

$ node --import @jennifersoft/jennifer5-instrumentation/auto your_server.js

When using the Node.js permission model (--permission), the worker permission is required for module.register(), so you must add --allow-worker.


$ node --permission --allow-worker --import @jennifersoft/jennifer5-instrumentation/auto your_server.js

Option 2: Using the NODE_OPTIONS environment variable

CommonJS application

$ NODE_OPTIONS="--require @jennifersoft/jennifer5-instrumentation/auto" node your_server.js

ESM application

$ NODE_OPTIONS="--import @jennifersoft/jennifer5-instrumentation/auto" node your_server.js

When using the Node.js permission model (--permission), the worker permission is required for module.register(), so you must add --allow-worker.


$ NODE_OPTIONS="--permission --allow-worker --import @jennifersoft/jennifer5-instrumentation/auto" node your_server.js

Option 3: Add the Jennifer agent package import at the very top of the entry file code

CommonJS application

require("@jennifersoft/jennifer5-instrumentation/auto");

ESM application

import "@jennifersoft/jennifer5-instrumentation/auto";

In ESM, parts of the module graph may be parsed or loaded before the body of the entry file is executed. In this case, modules loaded before the entry file is executed will not be instrumented. Therefore, to reliably instrument ESM-based Node.js applications, it is recommended to use Option 1 or Option 2.

Verifying successful startup of the Jennifer agent

If the Jennifer agent starts successfully, you will see a log similar to the following.

[2026-03-10 13:56:29.401543 +09:00] INFO [pid:1320034] [jennifer5_agent_js::init] start JENNIFER Agent
[2026-03-10 13:56:29.402653 +09:00] INFO [pid:1320034] [jennifer5_agent_js::init] Node.js 25.6.1
[2026-03-10 13:56:29.402665 +09:00] INFO [pid:1320034] [jennifer5_agent_js::init] jennifer-agent 5.6.5 commit:2026-03-10-7066088ed9bca5470b1e10ee2def26fe61ccbb42 build-date:2026-03-10
[2026-03-10 13:56:29.405234 +09:00] INFO [pid:1320034] [jennifer5_agent_js::init]
-----Host Information-----
hostname : hostname
cpu_num : 16
cpu_speed : 1800MHz
os_release : 6.19.6-2-cachyos
linux_id: cachyos
linux_name: CachyOS Linux
glibc_version: ldd (GNU libc) 2.43
--------------------------
[2026-03-10 13:56:29.405238 +09:00] INFO [pid:1320034] [jennifer5_agent_js::napi] Initializing Jennifer Core...
[2026-03-10 13:56:29.406648 +09:00] INFO [pid:1320034] [jennifer5_agent_js::event_processor] Spawning runner: AriesRunner
[2026-03-10 13:56:29.406685 +09:00] INFO [pid:1320034] [jennifer5_agent_js::event_processor] Agent initialized with 1 runner(s): AriesRunner

Uninstalling the Jennifer agent

If you used a Node.js package manager, uninstall the Jennifer agent using a package removal command such as npm uninstall.

$ npm uninstall @jennifersoft/jennifer5-instrumentation

If you installed the Jennifer agent using OS-wide installation, just delete /node_modules/@jennifersoft.

rm /node_modules/@jennifersoft

PM2 (Process Manager 2) settings

PM2 is a process manager tool for efficiently managing Node.js applications in production environments.

When using PM2's cluster mode, the same Node.js project runs as multiple Node.js processes. In this case, to prevent configuration conflicts between Jennifer agents running in each Node.js process, you must enable the reuse of unused Instance IDs in the data server domain settings.

If you are running multiple Node.js applications on a single server, it is recommended to use the JENNIFER_CONFIG_PATH environment variable to specify and manage a separate jennifer.toml configuration file for each application.

PM2 configuration example (ecosystem.config.js)

module.exports = {
  apps: [
    {
      name: "app1",
      script: "/webapp/app1/server.js",
      cwd: "/webapp/app1",
      instances: 2,
      env_production: {
        JENNIFER_CONFIG_PATH: "/opt/jennifer/nodejs/etc/app1.toml",
        JENNIFER_LOG_DIR: "/opt/jennifer/nodejs/logs/app1",
      },
      node_args:
        "--import @jennifersoft/jennifer5-instrumentation/auto",
    },
    {
      name: "app2",
      script: "/webapp/app2/server.js",
      cwd: "/webapp/app2",
      instances: 2,
      env_production: {
        JENNIFER_CONFIG_PATH: "/opt/jennifer/nodejs/etc/app2.toml",
        JENNIFER_LOG_DIR: "/opt/jennifer/nodejs/logs/app2",
      },
      node_args:
        "--import @jennifersoft/jennifer5-instrumentation/auto",
    },
  ],
};