PM2-Zabbix 연동 가이드 (Zabbix로 PM2 모니터링)

참고 문서: https://github.com/greatcare/pm2-zabbix

공식 저장소 기준으로 설치가 가능하지만,
Node 버전·경로·권한 문제로 설치가 실패하는 경우가 많다.
아래 내용은 실제 운영 환경에서 검증된 실무 적용 버전이다.
템플릿(XML)은 위 깃허브의 install/zabbix-server/ 경로에서 다운로드 후 Zabbix UI에서 Import 하면 된다.

---

1. 개요

pm2-zabbix는 PM2 프로세스 상태를 Zabbix로 전송하는 Node.js 기반 모듈이다.
Zabbix의 LLD(저수준 발견)를 이용해 PM2 프로세스를 자동 등록하고,
각 프로세스의 상태·CPU·메모리·재시작 횟수, 그리고 PM2 God Daemon 자체 상태까지 모니터링한다.

[PM2] → [pm2-zabbix 모니터링 데몬] → zabbix_sender → [Zabbix Server]
                             ↑
               UserParameter (--discover)

---

2. 사전 준비

• Zabbix Agent 설치되어 있어야 함
• Node.js / PM2가 정상 동작 중일 것 (pm2 list로 확인)
• pm2-zabbix는 PM2 내부가 아니라 systemd로 실행해야 함 (자기 참조 방지)

---

3. root 계정에서 기본 설정

A. /etc/zabbix/zabbix_agentd.conf

ServerActive=10.3.1.141
User=zabbix
UnsafeUserParameters=1
Include=/etc/zabbix/zabbix_agentd.conf.d/*.conf

B. systemd 서비스 계정 확인

vi /usr/lib/systemd/system/zabbix_agent.service

User=zabbix
Group=zabbix

---

4. PM2 실행 사용자 계정으로 전환 (예: app)

⚠️ 중요: 아래의 app은 PM2를 실제로 실행 중인 사용자로 바꿔야 한다.
환경에 따라 deploy, service, node 등으로 다를 수 있다.

A. pm2-zabbix 설치

$ npm install -g pm2-zabbix

B. PM2 프로세스 자동 발견 테스트

$ pm2-zabbix --discover

정상 출력 예시:

{
  "data": [
    {"{#PROCESS_ID}": "pm2-logrotate-1", "{#PROCESS_NAME}": "pm2-logrotate"},
    {"{#PROCESS_ID}": "whalex_api-3", "{#PROCESS_NAME}": "whalex_api"}
  ]
}

아래와 같은 경고가 나오면 C단계로 이동:

Warning: Accessing non-existent property 'cat' of module exports inside circular dependency

---

C. package.json 수정 (선택적 실무 우회 조치)

⚠️ 주의: 아래 내용은 공식 설치가 실패하거나 “순환 참조 경고”가 발생하는 환경에서만 적용한다.
Node 버전·pm2 버전에 따라 정상 설치가 가능한 경우 수정 없이 진행해도 된다.

① 전역 설치 경로 확인

환경별 Node.js 관리자(nodenv, nvm, asdf 등)에 따라 설치 경로가 다르므로,
다음 명령 중 하나로 전역 모듈 경로를 찾는다.

$ npm root -g
# 또는
$ which pm2-zabbix
# 출력된 경로가 심볼릭 링크인 경우, ls -l 또는 readlink -f 명령으로 실제 설치 디렉토리를 확인한다.

예를 들어 /usr/local/lib/node_modules/pm2-zabbix가 나왔다면 해당 경로로 이동한다.

② package.json 수정

$ cd $(npm root -g)/pm2-zabbix
$ vi package.json

아래 항목을 수정·추가한다.

"pm2": "^5.3.0",     // pm2 -v 로 확인한 버전으로 맞춤
"shelljs": "^0.8.5", // 신규 추가

③ 재설치 및 재확인

$ npm install -g pm2-zabbix
$ pm2-zabbix --discover

⚠️ 이 과정은 비공식 수정이다.
Node 모듈이 업데이트되면 덮어써질 수 있으므로, 이후 버전에서 동일 문제 발생 시만 반복한다.

---

5. root 계정으로 전환하여 Zabbix Agent 연동 구성

A. 주요 파일 복사

# cd $(npm root -g)/pm2-zabbix
# cp install/zabbix-agent/pm2-zabbix.conf /etc/zabbix/zabbix_agentd.conf.d/
# cp install/init/systemd/pm2-zabbix.service /usr/lib/systemd/system/

B. 실행 파일 심볼릭 링크 (필요 시)

# ln -s $(which pm2-zabbix) /usr/local/bin/pm2-zabbix
# ln -s $(which node) /usr/local/bin/node
# ln -s $(which npm) /usr/local/bin/npm

C. systemd 서비스 수정

# vi /usr/lib/systemd/system/pm2-zabbix.service

User=app
ExecStart=sudo -u app pm2-zabbix --monitor

⚠️ 각자의 PM2 실행 사용자로 변경 필요.

D. Zabbix Agent UserParameter 설정

# vi /etc/zabbix/zabbix_agentd.conf.d/pm2-zabbix.conf

UserParameter=pm2.processes,sudo -u app /usr/local/bin/pm2-zabbix --discover

E. sudoers 권한 추가

# visudo

zabbix ALL=(ALL:ALL) NOPASSWD: /usr/local/bin/pm2-zabbix

---

6. PM2 사용자 계정으로 hostname 커스터마이징 (선택)

대부분 필요 없지만, Zabbix 호스트명과 서버 실제 Hostname이 다를 경우에만 수정한다.

$ cd $(npm root -g)/pm2-zabbix
$ vi monitor.js

var hostname = os.hostname();
// ↓ 필요시 직접 지정
var hostname = "Prod-Beta-Api";

---

7. 서비스 등록 및 재시작

# systemctl daemon-reload
# systemctl restart zabbix-agent
# systemctl enable pm2-zabbix
# systemctl restart pm2-zabbix

---

8. Zabbix 서버 측 템플릿 적용

1. https://github.com/greatcare/pm2-zabbix
   → install/zabbix-server/ 폴더의 XML 템플릿 다운로드
2. Zabbix UI → Configuration → Templates → Import
3. 대상 호스트에 템플릿 연결
4. pm2-zabbix --discover 결과가 자동 반영되는지 확인

---

9. 개념 정리

🔹 PM2 God Daemon

• PM2의 마스터 프로세스.
• 개별 앱을 포크하고 감시하는 상위 PID.
• pm2-zabbix는 이 Daemon 상태도 감시하므로, pm2 내부에서 돌리지 말고 systemd로 분리해야 한다.

🔹 zabbix_sender

• pm2-zabbix의 --monitor 모드에서 실제로 데이터를 Zabbix 서버로 전송하는 실행 파일.
• 서버 주소와 인증 정보는 /etc/zabbix/zabbix_agentd.conf에서 읽는다.

🔹 계정 커스터마이징

• app은 단순 예시.
• 환경마다 PM2를 실행하는 사용자 이름으로 User, sudo -u, 경로 전부 변경해야 한다.
• Node 버전 관리자별로 전역 모듈 위치가 다르므로 npm root -g 명령으로 확인하는 것이 가장 확실하다.

---

10. 서비스 검증

# systemctl status pm2-zabbix
# tail -f /var/log/zabbix/zabbix_agentd.log

• pm2-zabbix 상태가 active (running)이면 정상
• Zabbix UI에서 PM2 프로세스 LLD 항목이 자동으로 생성되는지 확인

---

요약

항목	목적
pm2-zabbix --discover	PM2 프로세스 자동 등록(JSON)
pm2-zabbix --monitor	주기적 상태 전송
zabbix_sender	Zabbix로 실제 데이터 전송
PM2 God Daemon	PM2의 마스터 프로세스 (systemd로 감시 필요)

---

👉 참고 저장소:
https://github.com/greatcare/pm2-zabbix

🛠 마지막 수정일: 2025.10.15