Module System

What is a module?

A module is a simple Node.js application that will connect to a technology (database, utility) to both retrieve metrics (memory, entries…) and expose actions (restart, flush…).

A module is published on NPM.

Getting started: Installing a module

1- Install PM2

$ npm install pm2 -g

2- Go to Keymetrics and create a new account

3- Create a bucket and then follow the instructions to link your local PM2 to Keymetrics

4- Install a simple module

# Install a module that will monitor your current machine
$ pm2 install pm2-server-monit

Now you can see in the Keymetrics dashboard the module interface you just installed.

The source code of this pm2-server-monit module is here.

Here are some additional modules:

Getting started: Creating your own module

Creating your own module is straightforward.

To generate a sample module:

$ pm2 module:generate <module-name>

Now let’s run this module with PM2:

$ cd <module-name>
$ pm2 install .

You can now edit the source, once you change something, pm2 will automatically restart the module.

To remove the module:

$ pm2 uninstall <module-name>

API

Package.json: Declare options, widget aspect and module behavior

A package.json must be present with some extra fields like config for configuration variables and apps to declare the behavior of this module:

{
  "name": "pm2-logrotate",  // Used as the module name
  "version": "1.0.0",       // Used as the module version
  "description": "my desc", // Used as the module comment
  "dependencies": {
    "pm2": "latest",
    "pmx": "latest"         // Common dependencies to communiate with Keymetrics
  },
  "config": {              // Default configuration value
                           // These values can be modified via Keymetrics or PM2 configuration system

     "days_interval" : 7,  // -> this value is returned once you call pmx.initModule()
     "max_size" : 5242880
  },
  "apps" : [{              // Application configuration
    "merge_logs"         : true,
    "max_memory_restart" : "200M",
    "script"             : "index.js"
  }],
  "author": "Keymetrics Inc.", // Optional
  "license": "AGPL-3.0"        // Optional
}

Module entry point

This is the index.js file (declared in the package.json in the apps section): The pmx.initModule takes a range of options to configure the module display in Keymetrics or to override the PID monitored by PM2:

var pmx     = require('pmx');

// Initialize the module
var conf    = pmx.initModule({

    // Override PID to be monitored (for CPU and Memory blocks)
    pid              : pmx.resolvePidPaths(['/var/run/redis.pid', '/var/run/redis/redis-server.pid']),

    widget : {

      // Module display type. Currently only 'generic' is available
      type : 'generic',

      // Logo to be displayed on the top left block
      // Must be https
      logo : 'https://image.url',

      // 0 = main element
      // 1 = secondary
      // 2 = main border
      // 3 = secondary border
      // 4 = text color (not implemented yet)
      theme : ['#9F1414', '#591313', 'white', 'white'],

      // Toggle horizontal blocks above main widget
      el : {
        probes : false,
        actions: false
      },

      block : {
        // Display remote action block
        actions : true,

        // Display CPU / Memory
        cpu     : true,
        mem     : true,

        // Issues count display
        issues  : true,

        // Display meta block
        meta    : true,

        // Display metadata about the probe (restart nb, interpreter...)
        meta_block : true,

        // Name of custom metrics to be displayed as a "major metrics"
        main_probes : ['Processes']
      },
    },
}, function(err, conf) {
  // The module has been initiated
  // Now you can require all files
  console.log(conf);
});

Module configuration

In the package.json you can declare default options accessible in the module under the attribute config. These values can be overriden by PM2 or Keymetrics.

Default values

Add default configuration values in package.json under the “config” attribute:

{
 [...]
 "config": {             // Default configuration value
    "days_interval" : 7,  // -> returned from var ret = pmx.initModule()
    "max_size" : 5242880  // -> e.g. ret.max_size
 }
 [...]
}

Then these values are accessible via the data returned by pmx.initModule().

Example:

pmx.initModule({[...]}, function(err, conf) {
 // Now we can read these values
 console.log(conf.days_interval);
});

Override configuration values

With PM2

With PM2 the process is straightforward. Just call this command:

$ pm2 set module_name:option_name <new_value>

Example:

$ pm2 set server-monitoring:days_interval 2
  • NOTE These variables are written in ~/.pm2/module_conf.json, so if you prefer, you can directly edit these variables in this file.
  • NOTE2 You can display configuration variable via pm2 conf [module-name]
  • NOTE3 When you set a new value the target module is restarted
  • NOTE4 You have to typecast yourself values, it is always strings!

With Keymetrics

In the main Keymetrics Dashboard, the module will have a button called “Configure”. Once you click on it you will be able to access/modify all configuration variables exposed on the package.json!

Publishing a module

Publishing or updating a module is also straightforward! The pm2 publish command will increment the minor version of the module, will git add . ; git commit -m "VERSION"; git push origin master then it will npm publish.

$ cd my-module
$ pm2 publish