1 | # express-status-monitor
|
2 |
|
3 | [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/express-status-monitor/Lobby/?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
4 | [![express-status-monitor on npm](https://img.shields.io/npm/v/express-status-monitor.svg)](https://www.npmjs.com/express-status-monitor)
|
5 | [![npm](https://img.shields.io/npm/dt/express-status-monitor.svg)](https://img.shields.io/npm/dt/express-status-monitor.svg)
|
6 | [![CircleCI](https://img.shields.io/circleci/project/github/RafalWilinski/express-status-monitor/master.svg)](https://circleci.com/gh/RafalWilinski/express-status-monitor)
|
7 | [![Open Source Helpers](https://www.codetriage.com/rafalwilinski/express-status-monitor/badges/users.svg)](https://www.codetriage.com/rafalwilinski/express-status-monitor)
|
8 |
|
9 | Simple, self-hosted module based on Socket.io and Chart.js to report realtime server metrics for Express-based node servers.
|
10 |
|
11 | ![Monitoring Page](http://i.imgur.com/AHizEWq.gif "Monitoring Page")
|
12 |
|
13 | ## Demo
|
14 |
|
15 | [Demo available here](https://express-status-monitor-example-fjovaypblp.now.sh)
|
16 |
|
17 | ## Support for other Node.js frameworks
|
18 |
|
19 | * [koa-monitor](https://github.com/capaj/koa-monitor) for Koa
|
20 | * [hapijs-status-monitor](https://github.com/ziyasal/hapijs-status-monitor) for hapi.js
|
21 |
|
22 | ## Installation & setup
|
23 |
|
24 | 1. Run `npm install express-status-monitor --save`
|
25 | 2. Before any other middleware or router add following line:
|
26 | `app.use(require('express-status-monitor')());`
|
27 | 3. Run server and go to `/status`
|
28 |
|
29 | Note: This plugin works on Node versions > 4.x
|
30 |
|
31 | ## Run examples
|
32 |
|
33 | 1. Go to `cd examples/`
|
34 | 2. Run `npm i`
|
35 | 3. Run server `npm start`
|
36 | 4. Go to `http://0.0.0.0:3000`
|
37 |
|
38 | ## Options
|
39 |
|
40 | Monitor can be configured by passing options object into `expressMonitor` constructor.
|
41 |
|
42 | Default config:
|
43 | ```javascript
|
44 | title: 'Express Status', // Default title
|
45 | path: '/status',
|
46 | websocket: existingSocketIoInstance,
|
47 | spans: [{
|
48 | interval: 1, // Every second
|
49 | retention: 60 // Keep 60 datapoints in memory
|
50 | }, {
|
51 | interval: 5, // Every 5 seconds
|
52 | retention: 60
|
53 | }, {
|
54 | interval: 15, // Every 15 seconds
|
55 | retention: 60
|
56 | }],
|
57 | chartVisibility: {
|
58 | cpu: true,
|
59 | mem: true,
|
60 | load: true,
|
61 | responseTime: true,
|
62 | rps: true,
|
63 | statusCodes: true
|
64 | },
|
65 | ignoreStartsWith: '/admin'
|
66 |
|
67 | ```
|
68 |
|
69 | ## Securing endpoint
|
70 |
|
71 | The HTML page handler is exposed as a `pageRoute` property on the main
|
72 | middleware function. So the middleware is mounted to intercept all requests
|
73 | while the HTML page handler will be authenticated.
|
74 |
|
75 | Example using https://www.npmjs.com/package/connect-ensure-login
|
76 | ```javascript
|
77 | const ensureLoggedIn = require('connect-ensure-login').ensureLoggedIn()
|
78 |
|
79 | const statusMonitor = require('express-status-monitor')();
|
80 | app.use(statusMonitor);
|
81 | app.get('/status', ensureLoggedIn, statusMonitor.pageRoute)
|
82 | ```
|
83 |
|
84 | Credits to [@mattiaerre](https://github.com/mattiaerre)
|
85 |
|
86 | Example using [http-auth](https://www.npmjs.com/package/http-auth)
|
87 | ```javascript
|
88 | const auth = require('http-auth');
|
89 | const basic = auth.basic({realm: 'Monitor Area'}, function(user, pass, callback) {
|
90 | callback(user === 'username' && pass === 'password');
|
91 | });
|
92 |
|
93 | // Set '' to config path to avoid middleware serving the html page (path must be a string not equal to the wanted route)
|
94 | const statusMonitor = require('express-status-monitor')({ path: '' });
|
95 | app.use(statusMonitor.middleware); // use the "middleware only" property to manage websockets
|
96 | app.get('/status', auth.connect(basic), statusMonitor.pageRoute); // use the pageRoute property to serve the dashboard html page
|
97 | ```
|
98 |
|
99 | ## Using module with socket.io in project
|
100 |
|
101 | 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.
|
102 |
|
103 | ## Tests and coverage
|
104 |
|
105 | In order to run test and coverage use the following npm commands:
|
106 | ```
|
107 | npm test
|
108 | npm run coverage
|
109 | ```
|
110 |
|
111 | ## License
|
112 |
|
113 | [MIT License](https://opensource.org/licenses/MIT) © Rafal Wilinski
|