The previous published posts within this series, you’ve learned about the built-in features of PM2. This week, we’re going to explore a very handy feature of the utility: a built-in module system. This module system allows you to add custom functionality to PM2 by installing modules to PM2 which are managed aside your actual application processes.
Before moving on, let’s have a look on already published articles within this PM2 series:
PM2 Series Overview
Introduction to PM2 Modules
The first question to answer: what is a PM2 module?
Each PM2 module is a standalone process managed by PM2. Under the hood, PM2 leverages NPM and its installation procedure to make modules available. Therefore, each module is (and needs to be) available on NPM. To be clear: a PM2 module is not a Node.js library, but an actual process encapsulated in a Node.js package available on NPM (we know, it’s kind of confusing).
You can develop everything as an additional PM2 module. There are currently various modules available within the pm2-hive GitHub repository. Precisely, accessible modules are integration with PM2 for logrotate, CouchDB, MySQL, Postgres, Memcached, MongoDB, Redis, Elasticsearch, Docker, and many more! Modules for databases will show metrics of resource utilization. The Docker module will add support to monitor your containers with PM2. There is also a webshell module to access your command line via browser. You see, there is already a ton of helpful modules to improve your PM2 experience.
PM2 Module Management
Since PM2 uses the installation process of NPM to install modules, make sure the module you’re trying to install is available on NPM. The upcoming sections guide you through the process of module installations and how to remove an installed module from PM2.
Install
Actually, the process to install a new module to your PM2 process is straight forward. The build in install command expects the module name as an argument.
pm2 install <module-name>
Within the following example, we install the PM2 module pm2-auto-pull to illustrate the actual installation procedure. The output is almost equal to NPM package installation output.
$ pm2 install pm2-auto-pull
[PM2][Module] Installing module pm2-auto-pull
[PM2][Module] Processing...
.............................
> fsevents@1.0.2 install /Users/marcuspoehls/.pm2/node_modules/fsevents
> node-pre-gyp install --fallback-to-build
....[fsevents] Success: "/Users/marcuspoehls/.pm2/node_modules/fsevents/lib/binding/Release/node-v14-darwin-x64/fse.node" is installed via remote
../Users/marcuspoehls/.pm2
└─┬ pm2-auto-pull@1.14.0
…
[PM2][Module] Module downloaded
[PM2] Process launched
[PM2][Module] Module succesfully installed and launched
[PM2][Module] : To configure module do
[PM2][Module] : $ pm2 conf <key> <value>
--------------------------------------------------------------------------------------
│ App name │ id │ mode │ pid │ status │ restart │ uptime │ memory │ watching │
--------------------------------------------------------------------------------------
Module activated
------------------------------------------------------------------------------------
│ Module │ version │ target PID │ status │ restart │ cpu │ memory │
------------------------------------------------------------------------------------
│ pm2-auto-pull │ 1.14.0 │ 9503 │ online │ 0 │ 0% │ 8.008 MB │
------------------------------------------------------------------------------------
Once the PM2 module is installed, you’ll see a second process overview besides your application processes. Within the example above, we don’t have any apps managed by PM2 yet. There is only the pm2-auto-pull module idling.
Since PM2 uses the NPM installation procedure, you can directly install modules from GitHub repositories. We’ve published an NPM quick tips blog post on how to install packages with NPM describing the procedure.
pm2 install user/repo
Uninstall
Of course you can remove installed modules from PM2 using the uninstall command:
pm2 uninstall <module-name>
This will completely remove the module from PM2.
Module Configuration
If a module requires configuration, there are default values provided and you can customize them using PM2’s conf command. Configuration values always have a key value format. The key consists of two parts: the module name concatenated with the actual key identifier.
pm2 conf <module-name>:key value
Values are always stored as string values. If you write your own module specifying configuration variables, make sure to parse them correctly before applying them for usage.
The following command shows you how to set the interval configuration value for the pm2-auto-pull module:
$ pm2 conf pm2-auto-pull:interval 10000
[PM2] Module pm2-auto-pull restarted
== pm2-auto-pull ==
---------------------
│ key │ value │
---------------------
│ interval │ 10000 │
---------------------
If you want to see the current configurations, just use pm2 conf. Additionally, you can just print out the configuration for a given module by passing the module name as an argument to the conf command.
Module Logs
We published a guide on log management with PM2 earlier showing you the functionality to show logs and how to use options to customize the log output. PM2 also offers the log feature for modules. You can show real-time logs of modules using the logs command followed by the module name as an argument:
pm2 logs <module-name>
If the module logs anything during execution, you’ll see the output in the real-time log stream.
What Comes Next
This tutorial provides information about the built-in module system of PM2 and also shows you how to manage additional modules. The integrated log handling in the PM2 utility applies to application processes as well as to module processes.
This is currently the last planned post on a specific functionality of PM2. Next week, we’ll summarize this series and give an overview of topics covered.
As always, please don’t hesitate to leave a comment or tweet if you run into issues using PM2. Use the comment form below or shout out @futurestud_io.