PM2 Javascript API

Source: https://pm2.keymetrics.io/docs/usage/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()
      })
    })
  })
})

API Methods

pm2.connect([no_daemon_mode], fn)

Connect to local PM2 or spawn a new PM2 instance.

Param Type Default Description
[no_daemon_mode] boolean false if true, it will run an independent PM2 that will auto exit at end
fn function   Callback

Disconnect from local PM2

pm2.start(process, fn)

Start a process

Param Type Description
process string/object script path (relative) or object via options
fn function Callback

pm2.stop(process, fn)

Stop a process

Param Type Description
process string/number target process ID or Name
fn function Callback

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

Restart a process

Param Type Description
process string/number target process ID or Name
[options] object options (also add updateEnv: true to force update)
fn function Callback

pm2.reload(process, fn)

Reload a process

Param Type Description
process string/number target process ID or Name
fn function Callback

pm2.delete(process, fn)

Delete a process

Param Type Description
process string/number target process ID or Name
fn function Callback

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

Param Type Description
process string/number target process ID or Name
fn function Callback

pm2.list(fn)

Retrieve all processes managed with PM2

Advanced Methods

pm2.sendDataToProcessId(packet)

Send data to target process.

Param Type Description
packet.id number target process ID
packet.type string must be process:msg
packet.topic boolean must be true
packet.data object object data that will be sent 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

Param Type Description
signal string system signal name
process string target process Name
fn function Callback(err, process)

pm2.sendSignalToProcessId(signal, process, fn)

Send custom system signal to target process id

Param Type Description
signal string system signal name
process number target process id
fn function Callback(err, process)

Process structure

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

Examples

Send message to process

pm2-call.js:

const pm2 = require('pm2')

pm2.connect(function() {
  pm2.sendDataToProcessId({
    // id of process 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'
    },
    id   : 0, // id of process from "pm2 list" command or from pm2.list(errback) method
    topic: 'some topic'
  }, 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
    }
 });
});