PM2-Zabbix 連携ガイド（Zabbix で PM2 を監視する）

参考ドキュメント:
https://github.com/greatcare/pm2-zabbix

公式リポジトリの手順でもインストールは可能だが、Node のバージョン・パス・権限周りで失敗するケースが多い。
以下の内容は実運用環境で検証済みの実務向けバージョンである。
テンプレート（XML）は GitHub の install/zabbix-server/ からダウンロードし、Zabbix UI で Import すればよい。

---

1. 概要

pm2-zabbix は、PM2 プロセス状態を Zabbix に送信する Node.js ベースのモジュールである。
Zabbix の LLD（Low-Level Discovery）を利用して 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 のバージョンにより、修正なしでも正常動作する場合はこの作業は不要。

① グローバルインストールパスの確認

$ 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

⚠️ この作業内容はアップデート時に上書きされる可能性があるため、
同様の問題が出た場合のみ再度実施する。

---

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 のホスト名と OS の 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 サーバ側テンプレート適用

GitHub → install/zabbix-server/ の XML をダウンロード。
Zabbix UI → Configuration → Templates → Import
対象ホストへテンプレートをリンク。
pm2-zabbix --discover の結果が自動反映されるか確認。

---

9. 概念整理

🔹 PM2 God Daemon

PM2 のマスタープロセス。
アプリのフォークと監視を行う上位 PID。
pm2-zabbix はこの Daemon も監視するため、
PM2 内ではなく systemd で起動しなければならない。

🔹 zabbix_sender

--monitor モードで Zabbix へデータを送信する実行ファイル。
接続先アドレス・認証情報は /etc/zabbix/zabbix_agentd.conf を参照。

🔹 アカウントカスタマイズ

app は例示にすぎない。
環境に合わせて User、sudo -u、パスを変更すること。
また、Node バージョン管理ツールによりグローバルモジュールパスは異なるため
npm root -g が最も確実。

---

10. サービス検証

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

• active (running) であれば正常
• Zabbix UI に PM2 プロセスの LLD 項目が生成されているか確認

---

まとめ

項目	目的
pm2-zabbix –discover	PM2 プロセス自動登録（JSON）
pm2-zabbix –monitor	定期的な状態送信
zabbix_sender	実際に Zabbix へデータ送信
PM2 God Daemon	PM2 のマスタープロセス（systemd で監視が必要）

🛠 마지막 수정일: 2025.11.27