Merge branch 'master' into development

.bithoundrc

@@ -1,4 +1,9 @@
 {
+  "ignore": [
+    "**/node_modules/**",
+    "**/test/**",
+    "**/examples/**"
+  ],
   "critics": {
     "lint": {"engine": "semistandard"}
   }

README.md

@@ -27,15 +27,21 @@
 <br/>
 </div>
 
-PM2 is a production process manager for Node.js applications with a built-in load balancer. It allows you to keep applications alive forever, to reload them without downtime and to facilitate common system admin tasks.
+PM2 is a General Purpose Process Manager and a Production Runtime for Node.js apps with a built-in Load Balancer.
+
+Key features:
+- Simple and efficient process management (start/stop/restart/delete/monitoring)
+- Keep your application always ONLINE with auto restart and init system script generation
+- Automatically clusterize Node.js applications to increase performance and reliability
+- Allowing 0 seconds downtime reload for Node.js application without extra configuration
 
 Starting an application in production mode is as easy as:
 
 ```bash
 $ pm2 start app.js
 ```
 
-PM2 is constantly assailed by [more than 1400 tests](https://travis-ci.org/Unitech/pm2).
+PM2 is constantly assailed by [more than 1800 tests](https://travis-ci.org/Unitech/pm2).
 
 Official website: [http://pm2.keymetrics.io/](http://pm2.keymetrics.io/)
 
@@ -64,9 +70,10 @@ Your app is now daemonized, monitored and kept alive forever.
 
 ## Container Support
 
-Using Containers? We got your back with pm2-runtime, a dedicated command for running Node.js in containers and our [officialy suported Docker image](https://hub.docker.com/r/keymetrics/pm2/).
+Using Containers? With the dropin replacement command for `node`, called `pm2-runtime`, run your Node.js application in a proper production environment.
+We also offer an [officialy supported Docker image](https://hub.docker.com/r/keymetrics/pm2/).
 
-Using it:
+Using it is seamless:
 
 ```
 FROM keymetrics/pm2:latest-alpine
@@ -76,9 +83,11 @@ CMD [ "pm2-runtime", "ecosystem.config.js" ]
 
 [Read More about the dedicated integration](http://pm2.keymetrics.io/docs/usage/docker-pm2-nodejs/)
 
-## Monitor PM2 and Applications
+## Monitor PM2 and Applications with our SaaS
+
+Once you deploy your application in production you can monitor, debug and profile it externally with our [SaaS Monitoring](https://keymetrics.io).
 
-To monitor your applications just type:
+To start monitoring applications from the terminal:
 
 ```bash
 $ pm2 register
@@ -162,6 +171,8 @@ $ pm2 uninstall pm2-logrotate   # Uninstall module
 $ pm2 publish                   # Increment version, git push and npm publish
 ```
 
+Also check out the [example folder](https://github.com/Unitech/pm2/tree/master/examples) to discover all features.
+
 ### Process management
 
 Once applications are started you can list and manage them easily:
@@ -174,17 +185,13 @@ Listing all running processes:
 $ pm2 list
 ```
 
-Managing your processes is straightforward:
+Managing processes is straightforward:
 
 ```bash
 $ pm2 stop     <app_name|id|'all'|json_conf>
 $ pm2 restart  <app_name|id|'all'|json_conf>
 $ pm2 delete   <app_name|id|'all'|json_conf>
 ```
-To make sure it re-evaluates enviroment variables declared in your `json_conf` pass it as argument, and optionally your custom `env` name from your `json_conf` if any:
-```bash
-$ pm2 restart <json_conf> [--env <env_name>]
-```
 
 To have more details on a specific process:
 
@@ -196,9 +203,9 @@ $ pm2 describe <id|app_name>
 
 ### Load Balancing & Zero second Downtime Reload
 
-When an application is started with the -i <instance_number> option, the **Cluster Mode** is enabled.
+When an application is started with the `-i <instance_number>` parameter, the **Cluster Mode** is activated.
 
-The Cluster Mode starts <instance_number> instances of your app and automatically load balance HTTP/TCP/UDP between each instance. This allows to increase overall performance depending on the number of CPUs available.
+The Cluster Mode starts `<instance_number>` instances of your app and automatically load balance HTTP/TCP/UDP between each instances. This allows to increase overall performance and reliability depending on the number of CPUs available.
 
 Seamlessly supported by all major Node.js frameworks and any Node.js applications without any code change:
 
@@ -207,16 +214,19 @@ Seamlessly supported by all major Node.js frameworks and any Node.js application
 Main commands:
 
 ```bash
-$ pm2 start app.js -i max  # Enable load-balancer and start 'max' instances (cpu nb)
+# Enable load-balancer and start 'max' instances (Depending on CPU number)
+$ pm2 start app.js -i max
 
-$ pm2 reload all           # Zero second dowtime reload
+# Update your application with Zero Downtime Reload (requests are not lost)
+$ pm2 reload all
 
-$ pm2 scale <app_name> <instance_number> # Increase / Decrease process number
+# Increase / Decrease process number
+$ pm2 scale <app_name> <instance_number>
 ```
 
 [More informations about how PM2 make clustering easy](https://keymetrics.io/2015/03/26/pm2-clustering-made-easy/)
 
-### CPU / Memory Monitoring
+### Terminal Based Monitoring
 
 ![Monit](https://github.com/Unitech/pm2/raw/master/pres/pm2-monit.png)
 
@@ -226,16 +236,49 @@ Monitoring all processes launched:
 $ pm2 monit
 ```
 
+### Expose Custom Metrics
+
+To get more insights on how your application behave, plug custom metrics inside your code and monitor them with the `pm2 monit` command:
+
+In your project install [pmx](https://github.com/keymetrics/pmx):
+
+```bash
+$ npm install pmx --save
+```
+
+Then plug a custom metric:
+
+```javascript
+var Probe = require('pmx').probe();
+
+var counter = 1;
+
+var metric = Probe.metric({
+  name    : 'Counter',
+  value   : function() {
+    return counter;
+  }
+});
+
+setInterval(function() {
+  counter++;
+}, 1000);
+```
+
+Metric, Counter, Histogram and Meters are available *[documentation](http://pm2.keymetrics.io/docs/usage/process-metrics/)*
+
 ### Log facilities
 
 ![Monit](https://github.com/unitech/pm2/raw/master/pres/pm2-logs.png)
 
-Displaying logs of a specified process or all processes, in real time. Standard, Raw, JSON and formated output are available.
+Displaying logs of a specified process or all processes, in real time is easy:
 
 ```bash
 $ pm2 logs ['all'|app_name|app_id] [--json] [--format] [--raw]
 ```
 
+Standard, Raw, JSON and formated output are available.
+
 Examples:
 
 ```bash
@@ -251,7 +294,7 @@ $ pm2 reloadLogs          # Reload all logs
 
 ### Startup script generation
 
-PM2 can generate and configure a startup script to keep PM2 and your processes alive at every server restart.
+PM2 can generates and configure a startup script to keep PM2 and your processes alive at every server restart.
 
 Supports init systems like: **systemd** (Ubuntu 16, CentOS, Arch), **upstart** (Ubuntu 14/12), **launchd** (MacOSx, Darwin), **rc.d** (FreeBSD).
 

examples/api-pm2/README.md

@@ -0,0 +1,22 @@
+
+# PM2 API
+
+Here is an example of the PM2 API:
+
+```
+$ node api.js
+```
+
+Will delete all apps, will start http.js, and restart http
+
+Then you will see that the listing shows http app, restarted one time:
+
+```
+$ pm2 list
+┌──────────┬────┬──────┬──────┬────────┬─────────┬────────┬─────┬───────────┬─────────┬──────────┐
+│ App name │ id │ mode │ pid  │ status │ restart │ uptime │ cpu │ mem       │ user    │ watching │
+├──────────┼────┼──────┼──────┼────────┼─────────┼────────┼─────┼───────────┼─────────┼──────────┤
+│ http     │ 0  │ fork │ 7668 │ online │ 1       │ 2s     │ 0%  │ 34.2 MB   │ unitech │ disabled │
+└──────────┴────┴──────┴──────┴────────┴─────────┴────────┴─────┴───────────┴─────────┴──────────┘
+ Use `pm2 show <id|name>` to get more details about an app
+```

examples/api-pm2/api.js

@@ -0,0 +1,29 @@
+
+
+var pm2 = require('../..');
+
+pm2.delete('all', function(err) {
+  if (err) {
+    console.error(err);
+    return pm2.disconnect();
+  }
+
+  pm2.start('http.js', function(err, app) {
+    if (err) {
+      console.error(err);
+      return pm2.disconnect();
+    }
+
+    console.log('Process HTTP has been started');
+
+    pm2.restart('http', function(err, app) {
+      if (err) {
+        console.error(err);
+        return pm2.disconnect();
+      }
+
+      console.log('Process Restarted');
+      return pm2.disconnect();
+    });
+  });
+});

examples/cluster-http/README.md

@@ -0,0 +1,8 @@
+
+To start http application in cluster mode:
+
+```bash
+$ pm2 start ecosystem.config.js
+# OR
+$ pm2 start http.js -i max
+```

examples/cluster-http/ecosystem.config.js

@@ -0,0 +1,17 @@
+module.exports = {
+  apps : [{
+    name   : 'clustered_http',
+    script : './http.js',
+    instances : 'max',
+    exec_mode : 'cluster',
+    env : {
+      PORT : 8002
+    }
+  }, {
+    name : 'forked_app',
+    script : './http.js',
+    env : {
+      PORT : 8001
+    }
+  }]
+}

examples/process-file/http.js → examples/cluster-http/http.js

@@ -5,5 +5,5 @@ var server = http.createServer(function(req, res) {
   res.writeHead(200);
   res.end('hey');
 }).listen(process.env.PORT || 8000, function() {
-  console.log('App listening on port %d in env %s', process.env.PORT || 8000, process.env.NODE_ENV);
+  console.log('App listening on port %d', server.address().port);
 });

examples/cluster-tcp/README.md

@@ -0,0 +1,8 @@
+
+To start tcp application in cluster mode:
+
+```bash
+$ pm2 start ecosystem.config.js
+# OR
+$ pm2 start tcp.js -i max
+```

examples/cluster-tcp/http.js

@@ -0,0 +1,9 @@
+
+var http = require('http');
+
+var server = http.createServer(function(req, res) {
+  res.writeHead(200);
+  res.end('hey');
+}).listen(process.env.PORT || 8000, function() {
+  console.log('App listening on port %d', server.address().port);
+});

examples/cluster-tcp/process.config.js

@@ -0,0 +1,17 @@
+module.exports = {
+  apps : [{
+    name   : 'clustered_tcp',
+    script : './tcp.js',
+    instances : 'max',
+    exec_mode : 'cluster',
+    env : {
+      PORT : 8002
+    }
+  }, {
+    name : 'forked_tcp',
+    script : './tcp.js',
+    env : {
+      PORT : 8001
+    }
+  }]
+}

examples/tcp.js → examples/cluster-tcp/tcp.js

@@ -2,6 +2,6 @@ var net = require('net');
 
 var server = net.createServer(function (socket) {
   socket.write('Welcome to the Telnet server of the process' + (process.env.NODE_APP_INSTANCE || 'must be run on pm2'));
-}).listen(8888, function() {
-  console.log('Listening on port %s', 8888);
+}).listen(process.env.PORT || 8888, function() {
+  console.log('Listening on port %s', server.address().port);
 });

examples/configuration-process-files/README.md

@@ -0,0 +1,24 @@
+
+Here we have 3 applications (apps folder) that we can start with process file.
+These process file can be of different format, javascript, json or yaml:
+
+```
+.
+├── apps
+│   ├── connection_check.sh
+│   ├── http.js
+│   └── worker.js
+├── process.config.js
+├── process.json
+└── process.yml
+```
+
+To start them:
+
+```bash
+$ pm2 start process.config.js
+$ pm2 delete all
+$ pm2 start process.json
+$ pm2 delete all
+$ pm2 start process.yml
+```