이 장에서는 제니퍼 Node.js 에이전트를 설치하는 방법을 설명한다.

Node.js 에이전트 지원 환경

지원 OS

Linux x64 gnu (GLIBC 2.15+)
Linux x64 musl

지원 Linux 배포 버전 예시

Ubuntu 12.04 이상
CentOS 7 이상
Debian 8 이상
Alpine Linux

지원 Node.js 버전

CommonJS modules (CJS): 18.0 이상
ECMAScript modules (ESM): 18.19 이상 또는 20.6 이상

지원 Jennifer5 서버

Jennifer5 5.6.4.7 이상

에이전트 패키지 설치

Node.js 패키지 관리자(npm, yarn 등)를 이용해 패키지 설치

$ # Node.js 프로젝트 디렉토리에서 아래 명령을 실행 
$ npm install @jennifersoft/jennifer5-instrumentation

OS 전역 설치

package.json 변경을 원하지 않는 경우 /node_modules에 제니퍼 패키지를 복사하는 방법을 고려할 수 있다. 이렇게 하면 한 번의 설치로 동일한 OS 내에 있는 여러 Node.js 애플리케이션이 제니퍼 에이전트 패키지를 참조할 수 있다.

$ 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  3월 10:14 @jennifersoft -> /opt/jennifer/nodejs/current/node_modules/@jennifersoft

Node.js는 node_modules 디렉토리에서 패키지를 검색한다. 찾는 패키지가 없다면 루트 디렉토리에 도달할 때까지 상위 디렉토리의 node_modules를 검색한다. 예를 들어, require("bar")로 호출되었다면 Node.js는 다음 위치에서 bar 패키지를 찾는다.

/home/ry/projects/node_modules/bar
/home/ry/node_modules/bar
/home/node_modules/bar
/node_modules/bar

https://nodejs.org/api/modules.html#loading-from-node-modules-folders 참고

제니퍼 에이전트 설정

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"

제니퍼 에이전트는 아래 파일을 순차적으로 검색한다. 환경변수 JENNIFER_CONFIG_PATH가 설정되어 있으면 해당 경로의 파일을 설정 파일로 사용한다.

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

환경변수를 사용해 설정할 수도 있으며, 환경변수가 존재할 경우 jennifer.toml 의 설정 값은 무시된다.

JENNIFER_SERVER_ADDRESS
JENNIFER_SERVER_PORT
JENNIFER_DOMAIN_ID
JENNIFER_LOG_TO
JENNIFER_LOG_LEVEL
JENNIFER_LOG_DIR

제니퍼 에이전트 구동

제니퍼 에이전트가 Node.js 애플리케이션을 계측하기 위해서는 제니퍼 에이전트 패키지가 가장 먼저 로드되어야 한다.

옵션 1: 명령 인자 사용

CommonJS 애플리케이션

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

ESM 애플리케이션

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

Node.js 권한 모델(--permission)을 사용하는 경우 module.register()에 worker 권한이 필요하므로 --allow-worker를 추가해야 한다.

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

옵션 2: NODE_OPTIONS 환경변수 사용

CommonJS 애플리케이션

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

ESM 애플리케이션

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

Node.js 권한 모델(--permission)을 사용하는 경우 module.register()에 worker 권한이 필요하므로 --allow-worker를 추가해야 한다.

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

옵션 3: 엔트리 파일 코드 최상단에 제니퍼 에이전트 패키지 로드 코드 추가

CommonJS 애플리케이션

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

ESM 애플리케이션

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

ESM에서는 엔트리 파일 본문이 실행되기 전에 모듈 그래프 일부가 해석되거나 로드될 수 있다. 이 경우 엔트리 파일 본문 실행 전에 로드된 모듈은 계측되지 않는다. 따라서 ESM 기반 Node.js 애플리케이션을 안정적으로 계측하려면 옵션 1 또는 옵션 2를 사용할 것을 권장한다.

제니퍼 에이전트 정상 기동 확인

제니퍼 에이전트가 정상 기동되면 아래와 같은 로그를 확인할 수 있다.

[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

제니퍼 에이전트 삭제

Node.js 패키지 관리자를 사용한 경우라면 npm uninstall 와 같은 패키지 삭제 명령을 사용해 제니퍼 에이전트를 삭제한다.

$ npm uninstall @jennifersoft/jennifer5-instrumentation

OS 전역 설치로 제니퍼 에이전트를 설치했다면 /node_modules/@jennifersoft 를 삭제한다.

rm /node_modules/@jennifersoft

PM2(Process Manager 2) 설정

PM2는 Node.js 애플리케이션을 프로덕션 환경에서 효율적으로 관리하기 위한 프로세스 매니저(Process Manager) 도구이다.

PM2의 클러스터 모드를 사용하면 동일한 Node.js 프로젝트가 여러 Node.js 프로세스로 실행된다. 이때 각 Node.js 프로세스마다 실행되는 제니퍼 에이전트 간의 설정 충돌을 막기 위해 데이터 서버 도메인 설정에서 사용하지 않는 Instance ID 재사용을 활성화 해야 한다.

하나의 서버에서 여러 Node.js 애플리케이션을 구동 중이라면 JENNIFER_CONFIG_PATH 환경 변수를 사용해 각 애플리케이션별로 별도의 jennifer.toml 설정 파일을 지정하여 관리할 것을 권장한다.

PM2 설정 예시 (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",
    },
  ],
};