PM2 Production Process Manager

Cluster mode allows you to start multiple instances of a Node.js application to load-balance HTTP/TCP/UDP queries across multiple CPU cores. This increases throughput and improves reliability.

To start an application in cluster mode, use the -i flag. The <processes> argument can be:

• 'max': Uses all available CPUs.
• '-1': Uses all CPUs minus one.
• A specific integer: The exact number of instances to spawn.

Zero Downtime Reload: Use pm2 reload instead of restart to update applications without dropping connections.

# Start with max CPU instances
$ pm2 start api.js -i max

# Start with 2 instances
$ pm2 start api.js -i 2

# Zero downtime reload
$ pm2 reload all

PM2 automatically handles source maps for your applications. When an error occurs in minified or transpiled code, PM2 resolves the stack trace to the original source files, making debugging significantly easier by showing the actual line numbers and file paths where the error originated rather than the minified versions.

$ pm2 start process.config.js

Custom Metrics allow you to gain real-time visibility into a running application by monitoring specific variables, action counts, or latency. By integrating the @pm2/io library, you can track different types of data points that are then exposed through PM2's monitoring tools.

Supported metric types include:

• io.metric: General metric values.
• io.counter: Incremental counters (e.g., number of requests).
• io.meter: Rates of change.
• io.histogram: Distribution of values (e.g., latency).

You can view these metrics using:

• The terminal via pm2 monit or pm2 describe.
• The PM2+ Web interface via pm2 open.

For Node.js applications, PM2 can run multiple instances in Cluster Mode to load balance network queries across processes. This enables zero-downtime reloads and scaling.

• Start cluster: Use -i followed by the number of instances.
• Scale: Use pm2 scale [app-name] [number] to change the instance count.
• Zero-downtime reload: Use pm2 reload all to restart all instances without dropping connections.

$ pm2 start app.js -i 4         # Start 4 instances in cluster mode
$ pm2 scale [app-name] 10       # Scale Cluster app to 10 processes
$ pm2 reload all                # Zero Second Downtime Reload

Transporters are the mechanisms used to move data between the agent and PM2.io servers.

• WebsocketTransporter: Uses the websocket library to send and receive data from a websocket server.
• AxonTransporter: The default transporter used for push and reverse bucket communication.

Use pm2 start to daemonize an application (Node.js, Bun, Python, Ruby, or binaries in $PATH). Once started, you can manage processes using their name, namespace, or ID.

Common management commands:

• pm2 list: List all running applications.
• pm2 stop <target>: Stop a specific application.
• pm2 restart <target>: Restart a specific application.
• pm2 delete <target>: Remove an application from the list.
• pm2 describe <id|app_name>: View detailed information about a specific application.

<target> can be an app_name, namespace, id, 'all', or a json_conf.

$ pm2 start app.js
$ pm2 list
$ pm2 stop app_name
$ pm2 restart 0
$ pm2 delete all
$ pm2 describe my-app

To run PM2 within a containerized environment, use the official PM2 image and the pm2-runtime command. pm2-runtime is specifically designed for container environments to ensure the process stays in the foreground and handles signals correctly.

To use this example, build the image, list your local images to verify, and then run the container.

# build image
$ docker build -t docker-pm2-test .

# list images
$ docker images

# run image
$ docker run docker-pm2-test

To test the full suite of Keymetrics features, you must first register your PM2 instance with your Keymetrics account, start the applications using the provided configuration file, and then open the dashboard.

Note: Ensure you have already created a Keymetrics account before running the registration command.

# Register your PM2 instance with Keymetrics
$ pm2 register

# Start all applications using the config file
$ pm2 start process.config.js

# Open the Keymetrics dashboard
$ pm2 open

Once a module is generated, you can manage it using standard PM2 commands. To run the module in development mode, navigate to the module directory and use pm2 install .. You can view its logs, restart it, or uninstall it using the following commands:

# Start module in development mode
cd module-test/
pm2 install .

# View module logs
pm2 logs module-test

# Force restart the module
pm2 restart module-test

# Uninstall the module
pm2 uninstall module-test

To run LiveScript files, install the livescript interpreter via PM2 and then start your .ls file.

$ pm2 install livescript
$ pm2 start echo.ls

For production environments like Docker, use pm2-runtime. It is a drop-in replacement for the node command designed to run in a single foreground process, making it suitable for container lifecycles.

RUN npm install pm2 -g
CMD [ "pm2-runtime", "npm", "--", "start" ]