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

Node.js 에이전트 지원 환경

지원 OS

• Linux x64/arm64 gnu (GLIBC 2.15+)

• Linux x64/arm64 musl

지원 Node.js 버전

• CommonJS modules (CJS): 18.0 이상

• ECMAScript modules (ESM): 18.19 이상 또는 20.6 이상

지원 Jennifer5 서버

• Jennifer5 5.6.5.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

제니퍼 에이전트 설정

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가 설정되어 있으면 해당 경로의 파일을 설정 파일로 사용한다.

1. ./jennifer.toml

2. /etc/jennifer/jennifer.toml

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

제니퍼 에이전트 구동

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

옵션 1: 명령 인자 사용

CommonJS 애플리케이션

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

ESM 애플리케이션

$ node --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

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

CommonJS 애플리케이션

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

ESM 애플리케이션

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

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

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

[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",
    },
  ],
};

Docker 환경

Docker 환경에서는 애플리케이션 이미지에 제니퍼 에이전트 패키지가 포함되도록 Dockerfile을 변경하고, 환경변수로 Node.js 에이전트를 활성화한다.

에이전트 패키지를 포함하도록 이미지 빌드

Docker 이미지 빌드 시 wget으로 배포 ZIP 파일을 다운로드하고, 압축을 해제한 뒤 install.sh를 실행한다.

Debian, Ubuntu 이미지 예시

FROM node:22-bookworm-slim

# 이미지 빌드 시 root 권한으로 에이전트 설치
USER root
RUN apt-get update \
    && apt-get install -y --no-install-recommends wget unzip ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN wget -O /tmp/jennifer-nodejs.zip \
      https://jennifer5-release-public.s3.ap-northeast-2.amazonaws.com/agent/nodejs/jennifer-nodejs-5.6.5.6-x64.zip \
    && unzip /tmp/jennifer-nodejs.zip -d /tmp/jennifer-nodejs \
    && bash /tmp/jennifer-nodejs/install.sh \
    && rm -rf /tmp/jennifer-nodejs /tmp/jennifer-nodejs.zip

# ...

Alpine Linux 예시

FROM node:22-alpine

# 이미지 빌드 시 root 권한으로 에이전트 설치
USER root
RUN apk add --no-cache bash wget unzip ca-certificates
RUN wget -O /tmp/jennifer-nodejs.zip \
      https://jennifer5-release-public.s3.ap-northeast-2.amazonaws.com/agent/nodejs/jennifer-nodejs-5.6.5.6-x64.zip \
    && unzip /tmp/jennifer-nodejs.zip -d /tmp/jennifer-nodejs \
    && bash /tmp/jennifer-nodejs/install.sh \
    && rm -rf /tmp/jennifer-nodejs /tmp/jennifer-nodejs.zip

멀티 스테이지 빌드 예시

빌드 스테이지와 실행 스테이지가 분리되어 있다면, 빌드 스테이지에 에이전트를 설치한 후 실행 스테이지에서 jennifersoft 패키지를 복사한다.

FROM node:22-bookworm-slim AS jennifer-install

USER root
RUN apt-get update \
    && apt-get install -y --no-install-recommends wget unzip ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN wget -O /tmp/jennifer-nodejs.zip \
      https://jennifer5-release-public.s3.ap-northeast-2.amazonaws.com/agent/nodejs/jennifer-nodejs-5.6.5.6-x64.zip \
    && unzip /tmp/jennifer-nodejs.zip -d /tmp/jennifer-nodejs \
    && bash /tmp/jennifer-nodejs/install.sh

FROM node:22-bookworm-slim AS runtime

# build stage 에서 jennifer agent 패키지를 복사한다
COPY --from=jennifer-install /node_modules/@jennifersoft /node_modules/@jennifersoft

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./

USER node
CMD ["node", "server.js"]

Docker Compose 설정 예시

앞의 Dockerfile로 이미지를 빌드하고, docker-compose.yaml의 환경변수로 에이전트 로드 옵션과 데이터 서버 접속 정보를 지정한다. 아래 주소, 포트, 도메인 ID는 실제 환경에 맞게 변경한다.

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    image: my-node-app:jennifer
    environment:
      NODE_OPTIONS: "--require @jennifersoft/jennifer5-instrumentation/auto" #CommonJS
      #NODE_OPTIONS: "--import @jennifersoft/jennifer5-instrumentation/auto" #ESM
      JENNIFER_SERVER_ADDRESS: "<server-address>"
      JENNIFER_SERVER_PORT: "5000"
      JENNIFER_DOMAIN_ID: "1000"
      JENNIFER_LOG_LEVEL: "info"
      #JENNIFER_LOG_TO: "stdout" # 컨테이너의 표준 출력으로 로그를 내보내고 싶을 때. 기본값은 `file`이다.