PM2-Zabbix Integration Guide (Monitoring PM2 with Zabbix)

Reference: https://github.com/greatcare/pm2-zabbix

The official repository installation generally works,
but installation may fail due to Node.js version, global path, or permission issues.
This guide documents a field-tested, production-validated setup.

The Zabbix XML template is included in the GitHub repository under
install/zabbix-server/ — download and import it through the Zabbix UI.

---

1. Overview

pm2-zabbix is a Node.js module that sends PM2 process metrics to Zabbix.
It uses Zabbix LLD (Low-Level Discovery) to automatically register PM2 processes,
and monitors their status, CPU/memory usage, restart count,
and even the PM2 God Daemon itself.

[PM2] → [pm2-zabbix monitoring daemon] → zabbix_sender → [Zabbix Server]
                               ↑
                 UserParameter (--discover)

---

2. Prerequisites

• Zabbix Agent must be installed.
• Node.js and PM2 must already be running (pm2 list to verify).
• pm2-zabbix must run under systemd, not inside PM2, to avoid self-referencing loops.

---

3. Base Configuration (as 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. Verify Zabbix systemd service account

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

User=zabbix
Group=zabbix

---

4. Switch to the PM2 user (e.g., app)

⚠️ Important: Replace app with the actual user that runs PM2.
Depending on your environment, it could be deploy, node, service, etc.

A. Install pm2-zabbix

$ npm install -g pm2-zabbix

B. Test PM2 process discovery

$ pm2-zabbix --discover

Expected output example:

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

If you see the following warning, proceed to step C:

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

---

C. Modify package.json (optional workaround)

⚠️ Note: This workaround is only needed if installation fails
or the “circular dependency” warning appears.
If installation works normally, skip this step.

① Check the global installation path

The global npm path may vary depending on Node.js managers (e.g., nodenv, nvm, asdf).
Run one of the following commands to find the path:

$ npm root -g
# or
$ which pm2-zabbix
# If the result is a symbolic link, use `ls -l` or `readlink -f` to locate the actual install directory.

For example, if /usr/local/lib/node_modules/pm2-zabbix is shown, navigate there.

② Edit package.json

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

Modify or add the following entries:

"pm2": "^5.3.0",     // match your actual PM2 version (check via pm2 -v)
"shelljs": "^0.8.5"  // add this dependency

③ Reinstall and recheck

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

⚠️ This is an unofficial workaround.
Updates to the module may overwrite your local changes.
Reapply only if the same issue reappears after an upgrade.

---

5. Reconfigure Zabbix Agent (as root)

A. Copy key files

# 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. Create symbolic links (if required)

# 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. Edit the pm2-zabbix systemd unit

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

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

⚠️ Replace app with the correct PM2 user account.

D. Add Zabbix UserParameter

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

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

E. Update sudoers permissions

# visudo

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

---

6. (Optional) Customize Hostname for Zabbix

If the Zabbix hostname differs from the server’s actual hostname,
you can hardcode it in the pm2-zabbix source.

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

var hostname = os.hostname();
// ↓ manually override if needed
var hostname = "Prod-Beta-Api";

---

7. Register and restart services

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

---

8. Apply the Zabbix server-side template

1. Go to https://github.com/greatcare/pm2-zabbix
   → Download the XML template from install/zabbix-server/.
2. In Zabbix UI → Configuration → Templates → Import
3. Link the template to your PM2 host.
4. Confirm that items discovered by pm2-zabbix --discover appear automatically.

---

9. Concept Summary

🔹 PM2 God Daemon

• The master process that forks and monitors all PM2 apps.
• pm2-zabbix monitors this daemon’s PID and health separately.
• Do not run pm2-zabbix under PM2 itself; use systemd instead.

🔹 zabbix_sender

• The binary used by pm2-zabbix (in --monitor mode) to send metrics to Zabbix.
• It reads connection and authentication details from /etc/zabbix/zabbix_agentd.conf.

🔹 Account Customization

• The app username is an example.
• Replace it with the actual PM2 runtime user throughout (User, sudo -u, paths).
• Use npm root -g to find the global module directory;
  it differs depending on Node.js version managers.

---

10. Service Verification

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

• pm2-zabbix should show active (running).
• In the Zabbix UI, check that PM2 process LLD items appear automatically.

---

Summary

Component	Purpose
pm2-zabbix --discover	Auto-discovers PM2 processes (LLD JSON)
pm2-zabbix --monitor	Periodically sends metrics
zabbix_sender	Transmits data to Zabbix server
PM2 God Daemon	PM2 master process monitored by pm2-zabbix

---

👉 Reference Repository:
https://github.com/greatcare/pm2-zabbix

🛠 마지막 수정일: 2025.10.15