Getting Started with Keymetrics and PM2. Part 1
by Alexandre Strzelewicz -

Tutorial on how to set up Keymetrics and PM2 properly and get everything up and running.

Introduction

Since the official launch of Keymetrics 2 months ago, we got several questions and issues from the users about how to install Keymetrics and synchronize it with the NodeJS servers and PM2 processes running on them.
As a matter of fact, we were a bit puzzled to see users struggling with the installation of PM2 and the synchronization thereof. That's why we thought it may be useful to make a clear and comprehensive tutorial.
This article is intended to be as detailed as possible but, however, if you ever come across any issue that, after hours and hours of reading and debugging, doesn't seem to have any solution, please don't hesitate to contact our team via the intercom button on the dashboard, on our github or by email : contact@keymetrics.io.
Enough said, let's get started with this tutorial.

Installing PM2

If you haven't installed PM2 yet, then launch this command:

$ npm install pm2@latest -g

First steps

Creating and linking a Bucket

Let's start by logging into https://app.keymetrics.io in order to create your first bucket.
After naming and creating your bucket, you will be prompted to the setup instruction page.
The first step is to make PM2 on your server interact with your keymetrics bucket. For the sole purpose of this tutorial, we're going to use a very basic http server, configured as follows (make sure it's up and running on the machine before launching any command):

var http = require('http');

http.createServer(function(req, res) {  
  res.writeHead(200);
  res.end("hello world");
}).listen(8080);

You just have to launch the PM2 interact command with the public and the secret keys displayed on the dashboard.
The "machine_name" value is optional.

$ pm2 interact secret_key public_key [machine_name]

Once you've performed the PM2 interact command, simply reload the Keymetrics page, the server should appear on your dashboard.

Hold on. Why does it say that no application has been launched?

Because no app is present on your server, it's as simple as that. However, if you don't have any time or inspiration to make one, we created a mock application called "app-playground" just to let you see and play around with the features.
Just do as per indicated below (also in the textbox on your dashboard):

$ git clone https://github.com/keymetrics/app-playground.git

$ cd app-playground

$ pm2 start app.js

[PM2] Process app.js launched
● Agent online - public key: 8i3bqh6lvn5avaq - machine name: keymetrics-ZBOX-OI520 - Web access: https://app.keymetrics.io/
┌──────────┬────┬──────┬───────┬────────┬─────────┬────────┬─────────────┬──────────┐
│ App name │ id │ mode │ pid   │ status │ restart │ uptime │ memory      │ watching │
├──────────┼────┼──────┼───────┼────────┼─────────┼────────┼─────────────┼──────────┤
│ app      │ 0  │ fork │ 32591 │ online │ 0       │ 0s     │ 14.211 MB   │ disabled │
└──────────┴────┴──────┴───────┴────────┴─────────┴────────┴─────────────┴──────────┘
 Use `pm2 show <id|name>` to get more details about an app

Now go back to your Keymetrics dashboard and, if everything went fine, you should see the following stuff on screen:

If you need to have a detailed list of all the apps being monitored, pm2 l will do the trick:

$ pm2 l

● Agent online - public key: 8i3bqh6lvn5avaq - machine name: keymetrics-ZBOX-OI520 - Web access: https://app.keymetrics.io/
┌──────────┬────┬──────┬──────┬────────┬─────────┬────────┬─────────────┬──────────┐
│ App name │ id │ mode │ pid  │ status │ restart │ uptime │ memory      │ watching │
├──────────┼────┼──────┼──────┼────────┼─────────┼────────┼─────────────┼──────────┤
│ app      │ 7  │ fork │ 4100 │ online │ 0       │ 6s     │ 16.844 MB   │ disabled │
└──────────┴────┴──────┴──────┴────────┴─────────┴────────┴─────────────┴──────────┘
 Use `pm2 show <id|name>` to get more details about an app

Once you've done those steps, the funny part begins...

Monitoring your applications

As we did in the previous example with the app-playground, you must first start your app with PM2 on the current folder where the main js file of the application is located. Example:

$ pm2 start app.js

If you are encountering issues, don't forget to execute the stream log command to help you debugging.

$ pm2 logs

This is what the output of pm2 logs usually looks like:

If you want to display more details about an app, use the following command :

$ pm2 show appName

The command will show all the paths to the log files, information about versionning and other other useful data such as probes value.


Tip: using the --watch flag to automatically restart your app when changes have been applied

This option makes developement a lot easier. You shouldn't use it in a production environment because it consumes more CPU and it's meant to be used for development purposes.
Just add the --watch flag when you start your app with PM2. By doing that, PM2 will automatically restart and reload the application when you save any change in any of the application files.

$ pm2 start app.js --watch

Now the application is running with the watch flag on and will wait for any change to reload the app and keep your keymetrics dashboard automatically up-to-date.


How to delete, stop and restart your app

Pretty straight-forward, just enter this command with the app name :

$ pm2 delete appName

Otherwise, you can easily stop your app with this command :

$ pm2 stop appName

And, last but not least, restarting your app :

$ pm2 restart appName

Nothing too difficult here. Bear in mind that you will have to delete and start (not restart, be careful) again the instance of your app running on your server if you want to change its working mode or options.

For more information about the different pm2 commands and options, type

$ pm2

Easy.


Boosting your application's performance with the cluster functionality

Clustering your application in multiple instances throughout all the CPU cores turns out to be pretty convenient when facing, for example, a high amount of traffic. The cluster mode acts as a load balancer between the different instances and, in fact, allows you to get rid of NodeJS single-thread limitation.

Launch the app in cluster mode with this command :

$ pm2 start app.js -i 0

[PM2] Process app.js launched
● Agent online - public key: 8i3bqh6lvn5avaq - machine name: keymetrics-ZBOX-OI520 - Web access: https://app.keymetrics.io/
┌──────────┬────┬─────────┬──────┬────────┬─────────┬────────┬─────────────┬──────────┐
│ App name │ id │ mode    │ pid  │ status │ restart │ uptime │ memory      │ watching │
├──────────┼────┼─────────┼──────┼────────┼─────────┼────────┼─────────────┼──────────┤
│ app      │ 8  │ cluster │ 5075 │ online │ 0       │ 0s     │ 19.531 MB   │ disabled │
│ app      │ 9  │ cluster │ 5080 │ online │ 0       │ 0s     │ 19.563 MB   │ disabled │
│ app      │ 10 │ cluster │ 5103 │ online │ 0       │ 0s     │ 19.246 MB   │ disabled │
│ app      │ 11 │ cluster │ 5126 │ online │ 0       │ 0s     │ 15.078 MB   │ disabled │
└──────────┴────┴─────────┴──────┴────────┴─────────┴────────┴─────────────┴──────────┘
 Use `pm2 show <id|name>` to get more details about an app

You can see in the example above that your app has indeed been instanciated in all your CPU cores.

To find more about clustering, please read this very well written article : https://keymetrics.io/2015/03/26/pm2-clustering-made-easy/

Conclusion

That's it for the first part. The interaction between Keymetrics and PM2 is really simple and powerful and requires only 3 commands to complete the integration with Keymetrics. Stay tuned for the second part of our tutorial covering in details all the functionalities of the Keymetrics dashboard.