Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 149 lines (100 sloc) 5.438 kb
c86f21f Change README
Loren West authored
1 Monitor your Node.js application
2 ================================
80bcc57 Initial commit under monitor-min
Loren West authored
3
5c9f25f Changed repo to node-monitor
Loren West authored
4 [![Build Status](https://secure.travis-ci.org/lorenwest/node-monitor.png?branch=master)](https://travis-ci.org/lorenwest/node-monitor)
80bcc57 Initial commit under monitor-min
Loren West authored
5
c86f21f Change README
Loren West authored
6 Introduction
7 ------------
80bcc57 Initial commit under monitor-min
Loren West authored
8
5e9f72a @lorenwest Update README.md
authored
9 Node-monitor is a library for remote monitoring and control of your Node.js app servers.
10
11 Like JMX in the Java world, node-monitor comes with a handful of general monitors, and allows you to create custom monitors for your application.
12
13 These monitors can be scripted using JavaScript, or placed onto a dashboard.
80bcc57 Initial commit under monitor-min
Loren West authored
14
c86f21f Change README
Loren West authored
15 Project Guidelines
16 ------------------
17
18 * *Simple* - Get started quickly
19 * *Powerful* - For multi-node enterprise deployment
20 * *Lightweight* - Inactive until used, small footprint during use
5e9f72a @lorenwest Update README.md
authored
21 * *Flexible* - Easy to write custom monitors for your app
c86f21f Change README
Loren West authored
22 * *Stable* - Well tested foundation for module developers
23
24
25 Getting Started
26 ---------------
27
5e9f72a @lorenwest Update README.md
authored
28 Run the following from your app server directory
80bcc57 Initial commit under monitor-min
Loren West authored
29
1380b4d Monitor-Min to Monitor
Loren West authored
30 $ npm install monitor
c7f30ff Documentation regen
Loren West authored
31
c86f21f Change README
Loren West authored
32 Then place the following line in your application bootstrap, and restart your server
33
5e9f72a @lorenwest Update README.md
authored
34 require('monitor').start();
c86f21f Change README
Loren West authored
35
36 Monitoring your app with a REPL console
37 ---------------------------------------
38
39 Ad-hoc monitoring can be done from a REPL console.
40
41 Start up the REPL, and get the Monitor class. Feel free to copy/paste these lines into your console:
42
43 $ node
44 > var Monitor = require('monitor');
0de341f Named and auto-starting monitors
Loren West authored
45 undefined
c86f21f Change README
Loren West authored
46
47 Now connect a monitor to a probe on your app server. There are a handful of built-in probes, and you can build custom probes for your application or npm module.
48
49 For this example, we'll monitor the *Process* probe:
50
a1a5253 Updated README
Loren West authored
51 > var processMonitor = new Monitor({probeClass:'Process'});
c86f21f Change README
Loren West authored
52 > processMonitor.connect();
53
54 The monitor is a [Backbone.js](http://backbonejs.org/) data model so it updates in real time, and you can get all fields with toJSON():
55
56 > processMonitor.get('freemem');
57 86368256
58 > processMonitor.get('freemem');
59 80044032
60 > processMonitor.toJSON();
61 ...
62
63 As the monitor changes, it emits change events:
64
65 > processMonitor.on('change', function() {
66 ... console.log(processMonitor.get('freemem'));
67 ... });
68
69 Monitoring your app with a custom script
70 ----------------------------------------
71
72 Using Node.js as a scripting language, you can write custom monitors that do anything Node.js can do. Here's an example that prints to the console when free memory falls below a threshold.
80bcc57 Initial commit under monitor-min
Loren West authored
73
c86f21f Change README
Loren West authored
74 Save this file to low-memory-warn.js, and run **node low-memory-warn**
75
76 // Low memory warning monitor
77 var Monitor = require('monitor');
78 var LOW_MEMORY_THRESHOLD = 100000000;
79
80 // Set the probe to push changes every 10 seconds
81 var options = {
82 hostName: 'localhost',
83 probeClass: 'Process',
84 initParams: {
85 pollInterval: 10000
86 }
87 }
88 var processMonitor = new Monitor(options);
89
90 // Attach the change listener
91 processMonitor.on('change', function() {
92 var freemem = processMonitor.get('freemem');
93 if (freemem < LOW_MEMORY_THRESHOLD) {
94 console.log('Low memory warning: ' + freemem);
95 }
96 });
97
98 // Now connect the monitor
99 processMonitor.connect(function(error) {
100 if (error) {
101 console.error('Error connecting with the process probe: ', error);
102 process.exit(1);
103 }
104 });
105
106 Monitoring your app in a browser
107 --------------------------------
108
109 The above script runs just as well within an html ```<script>``` tag as on the server. For example, change the ```var Monitor = require('monitor');``` line to something like this:
110
111 <script src="/path/to/monitor/dist/monitor-all.min.js"></script>
112
113 The browser distribution included in node-monitor exports a single variable ```Monitor``` to the global namespace, and it can be used just like the ```Monitor``` variable in ```var Monitor = require('monitor')```.
114
115 Your browser will probably have to be pointing to localhost or behind your firewall in order to connect with the app server on the configured monitor port. See *Security Concerns* below.
116
274a4de @lorenwest Update README.md
authored
117 Monitoring your app in a dashboard
c86f21f Change README
Loren West authored
118 ---------------------------
274a4de @lorenwest Update README.md
authored
119 ![Monitor-Dashboard](http://lorenwest.github.io/monitor-dashboard/img/cpu-gauge.png)
c86f21f Change README
Loren West authored
120
b2e4b2f @lorenwest Update README.md
authored
121 The [monitor-dashboard](https://github.com/lorenwest/monitor-dashboard) application lets you visualize your monitors in a dashboard.
c86f21f Change README
Loren West authored
122
123 $ npm install monitor-dashboard
f81ed57 Better README
Loren West authored
124 $ npm start monitor-dashboard
c86f21f Change README
Loren West authored
125
126 Security Concerns
127 -----------------
128
129 Exposing the internals of your app server is a high security risk. By default, the server listens on port 42000 and will connect with localhost clients only.
130
131 In order to monitor across machines, the default configuration must be changed to listen beyond localhost. Before doing this, it is recommended to understand the risks and have external measures in place to prevent unauthorized access.
132
133 See notes in the ```config/external.js``` file for more information.
80bcc57 Initial commit under monitor-min
Loren West authored
134
b176f05 Updated README
Derrick West authored
135 Links
136 -------
137
8da6cf2 More links in README
Loren West authored
138 * [API Docs](http://lorenwest.github.io/node-monitor/doc/index.html) - Node monitor JavaScript documentation.
139 * [Monitor Dashboard](https://github.com/lorenwest/monitor-dashboard) - Dashboards for the node monitor project.
140 * [Dashboard Components](https://github.com/lorenwest/core-monitor) - Core components for the Dashboard project.
b176f05 Updated README
Derrick West authored
141
80bcc57 Initial commit under monitor-min
Loren West authored
142 License
143 -------
144
c86f21f Change README
Loren West authored
145 May be freely distributed under the MIT license<br>
79c7c6d Better README
Loren West authored
146 See the [LICENSE](https://github.com/lorenwest/node-monitor/blob/master/LICENSE) file.<br>
a8543e8 Updated copyright year
Loren West authored
147 Copyright (c) 2010-2014 Loren West<br>
80bcc57 Initial commit under monitor-min
Loren West authored
148
Something went wrong with that request. Please try again.