express-status-monitor

Realtime Monitoring solution for Node.js/Express.js apps, inspired by statu...

README

express-status-monitor

express-status-monitor on npm npm CircleCI Open Source Helpers

Simple, self-hosted module based on Socket.io and Chart.js to report realtime server metrics for Express-based node servers.

Monitoring Page

Demo



Support for other Node.js frameworks


koa-monitor for Koa

Installation & setup


1. Run npm install express-status-monitor --save
2. Before any other middleware or router add following line:
app.use(require('express-status-monitor')());
3. Run server and go to /status

Note: This plugin works on Node versions > 4.x

Run examples


1. Go to cd examples/
2. Run npm i
3. Run server npm start
4. Go to http://0.0.0.0:3000

Options


Monitor can be configured by passing options object into expressMonitor constructor.

Default config:
  1. ``` js
  2. title: 'Express Status',  // Default title
  3. theme: 'default.css',     // Default styles
  4. path: '/status',
  5. socketPath: '/socket.io', // In case you use a custom path
  6. websocket: existingSocketIoInstance,
  7. spans: [{
  8.   interval: 1,            // Every second
  9.   retention: 60           // Keep 60 datapoints in memory
  10. }, {
  11.   interval: 5,            // Every 5 seconds
  12.   retention: 60
  13. }, {
  14.   interval: 15,           // Every 15 seconds
  15.   retention: 60
  16. }],
  17. chartVisibility: {
  18.   cpu: true,
  19.   mem: true,
  20.   load: true,
  21.   eventLoop: true,
  22.   heap: true,
  23.   responseTime: true,
  24.   rps: true,
  25.   statusCodes: true
  26. },
  27. healthChecks: [],
  28. ignoreStartsWith: '/admin'

  29. ```

Health Checks


You can add a series of health checks to the configuration that will appear below the other stats. The health check will be considered successful if the endpoint returns a 200 status code.

  1. ``` js
  2. // config
  3. healthChecks: [{
  4.   protocol: 'http',
  5.   host: 'localhost',
  6.   path: '/admin/health/ex1',
  7.   port: '3000'
  8. }, {
  9.   protocol: 'http',
  10.   host: 'localhost',
  11.   path: '/admin/health/ex2',
  12.   port: '3000'
  13. }]
  14. ```

Health Checks

Securing endpoint


The HTML page handler is exposed as a pageRoute property on the main
middleware function.  So the middleware is mounted to intercept all requests
while the HTML page handler will be authenticated.

Example using https://www.npmjs.com/package/connect-ensure-login
  1. ``` js
  2. const ensureLoggedIn = require('connect-ensure-login').ensureLoggedIn()

  3. const statusMonitor = require('express-status-monitor')();
  4. app.use(statusMonitor);
  5. app.get('/status', ensureLoggedIn, statusMonitor.pageRoute)
  6. ```

Credits to @mattiaerre

Example using http-auth
  1. ``` js
  2. const auth = require('http-auth');
  3. const basic = auth.basic({realm: 'Monitor Area'}, function(user, pass, callback) {
  4.   callback(user === 'username' && pass === 'password');
  5. });

  6. // Set '' to config path to avoid middleware serving the html page (path must be a string not equal to the wanted route)
  7. const statusMonitor = require('express-status-monitor')({ path: '' });
  8. app.use(statusMonitor.middleware); // use the "middleware only" property to manage websockets
  9. app.get('/status', basic.check(statusMonitor.pageRoute)); // use the pageRoute property to serve the dashboard html page
  10. ```

Using module with socket.io in project


If you're using socket.io in your project, this module could break your project because this module by default will spawn its own socket.io instance. To mitigate that, fill websocket parameter with your main socket.io instance as well as port parameter.

Tests and coverage


In order to run test and coverage use the following npm commands:
  1. ```
  2. npm test
  3. npm run coverage
  4. ```

License