PM2 API

PM2 API

PM2 can be used programmatically, allowing to manage processes straight from the code.

Quickstart

Note: To release connection to PM2 and make your application auto exit, make sure to disconnect from pm2 with pm2.disconnect()

First add PM2 as a dependency:

npm install pm2 --save

Then create a script called app.js and pm2-control.js containing this:

const pm2 = require('pm2')

pm2.connect(function(err) {
  if (err) {
    console.error(err)
    process.exit(2)
  }

  pm2.start({
    script    : 'api.js',
    name      : 'api'
  }, function(err, apps) {
    if (err) {
      console.error(err)
      return pm2.disconnect()
    }

    pm2.list((err, list) => {
      console.log(err, list)

      pm2.restart('api', (err, proc) => {
        // Disconnects from PM2
        pm2.disconnect()
      })
    })
  })
})

• This will spawn or connect to local PM2
• Then start app.js with name api
• Display all applications managed with PM2
• Then restart the app with name api
• And disconnect from PM2

API Methods

pm2.connect([no_daemon_mode], fn)

Connect to local PM2 or spawn a new PM2 instance.

• noDaemonMode: If true is passed for the first argument, pm2 will not be run as a daemon and will die when the related script exits. By default, pm2 stays alive after your script exits. If pm2 is already running, your script will link to the existing daemon but will die once your process exits.

pm2.disconnect()

Disconnect from local PM2

pm2.start(process, fn)

Start a process

pm2.stop(process, fn)

Stop a process

pm2.restart(process, [options], fn)

Restart a process

pm2.reload(process, fn)

Reload a process

pm2.delete(process, fn)

Delete a process

pm2.killDaemon(fn)

Kills the pm2 daemon (same as pm2 kill). Note that when the daemon is killed, all its processes are also killed. Also note that you still have to explicitly disconnect from the daemon even after you kill it.

pm2.describe(process, fn)

Get all metadata from a target process

pm2.list(fn)

Retrieve all processes managed with PM2

Advanced Methods

pm2.sendDataToProcessId(packet)

Send data to target process.

Data will be received by target process via:

process.on('message', function(packet) {})

pm2.launchBus(fn)

This allow to receive message from process managed with PM2.

const pm2 = require('pm2')

pm2.launchBus(function(err, pm2_bus) {
  pm2_bus.on('process:msg', function(packet) {
    console.log(packet)
  })
})

Then from a process managed with PM2:

process.send({
  type : 'process:msg',
  data : {
    success : true
  }
})

pm2.sendSignalToProcessName(signal, process, fn)

Send custom system signal to target process name

pm2.sendSignalToProcessId(signal, process, fn)

Send custom system signal to target process id

Process structure

When calling any of the above methods, a mutated process array is returned. This object contains:

• processDescription - An array of objects with information about the process. Each object contains the properties:
  • name - The name given in the original start command.
  • pid - The pid of the process.
  • pm_id - The pid for the pm2 God daemon process.
  • monit - An object containing:
    • memory - The number of bytes the process is using.
    • cpu - The percent of CPU being used by the process at the moment.
  • pm2_env - The list of path variables in the process’s environment. These variables include:
    • pm_cwd - The working directory of the process.
    • pm_out_log_path - The stdout log file path.
    • pm_err_log_path - The stderr log file path.
    • exec_interpreter - The interpreter used.
    • pm_uptime - The uptime of the process.
    • unstable_restarts - The number of unstable restarts the process has been through.
    • restart_time
    • status - “online”, “stopping”, “stopped”, “launching”, “errored”, or “one-launch-status”
    • instances - The number of running instances.
    • pm_exec_path - The path of the script being run in this process.

Examples

Send message to process

pm2-call.js:

const pm2 = require('pm2')

pm2.connect(function() {
  pm2.sendDataToProcessId({
    // id of procces from "pm2 list" command or from pm2.list(errback) method
    id   : 1,

    // process:msg will be send as 'message' on target process
    type : 'process:msg',

    // Data to be sent
    data : {
      some : 'data'
    },

    topic: true
  }, function(err, res) {
  })
})

// Listen to messages from application
pm2.launchBus(function(err, pm2_bus) {
  pm2_bus.on('process:msg', function(packet) {
    console.log(packet)
  })
})

pm2-app.js:

process.on('message', function(packet) {
  process.send({
    type : 'process:msg',
    data : {
     success : true
    }
 });
});