Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Move the plugin installatin logic to the configuration

* Enable console and patternMatcher plugins by default
* Keep old way to extend the frontend (via plugins/index.js) for BC
* Rewrite the plugin documentation
commit 92c40a18e4a4a14b0cd461e1a37118d0203ef1fe 1 parent 34083c3
@fzaninotto authored
View
3  CHANGELOG.md
@@ -4,6 +4,8 @@ Uptime Changelog
To be released
--------------
+* Update the README about the plugin system
+* Update plugins system to make it easier to enable new plugins, just by adding a line in the configuration
* Add pollerCollections to allow the addition of custom pollers
* Update HTTP and HTTPS pollers (they now specialize a BaseHttpPoller, to reduce code duplication)
* Fix monitor crash when poller is badly set
@@ -15,7 +17,6 @@ To be released
* Add new events to Monitor and dashboard app
* Add more plugins extension points: they can now add details to checks, abilities to pollers, and store additional details about pings
* Move Pattern Matcher logic to a plugin
-* Update the README accordingly
* Fix warnings in production by using cookie store for sessions
* Add mention of external plugins in README
* Add pattern detection in response body
View
64 README.md
@@ -12,10 +12,12 @@ Features
--------
* Monitor thousands of websites (powered by [Node.js asynchronous programming](http://dotheweb.posterous.com/nodejs-for-php-programmers-1-event-driven-pro))
-* Check the presence of a pattern in the response body
* Tweak frequency of monitoring on a per-check basis, up to the second
-* Receive on screen notifications whenever a check goes down (powered by [socket.io](http://socket.io/))
-* Receive email notifications whenever a check goes down
+* Check the presence of a pattern in the response body
+* Receive notifications whenever a check goes down
+ * On screen (powered by [socket.io](http://socket.io/))
+ * By email
+ * On the console
* Record availability statistics for further reporting (powered by [MongoDB](http://www.mongodb.org/))
* Detailed uptime reports with animated charts (powered by [Flotr2](http://www.humblesoftware.com/flotr2/))
* Monitor availability, responsiveness, average response time, and total uptime/downtime
@@ -23,6 +25,7 @@ Features
* Group checks by tags and get reports by tag
* Familiar web interface (powered by [Twitter Bootstrap 2.0](http://twitter.github.com/bootstrap/index.html))
* Complete API for integration with third-party monitoring services
+* Powerful plugin system to ease extension and customization
* Easy installation and zero administration
Installing Uptime
@@ -91,6 +94,11 @@ autoStartMonitor: true
server:
port: 8082
+
+plugins:
+ - ./plugins/console
+ - ./plugins/patternMatcher
+ # - ./plugins/email
```
To modify this configuration, create a `development.yaml` or a `production.yaml` file in the same directory, and override just the settings you need. For instance, to run Uptime on port 80 in production, create a `production.yaml` file as follows:
@@ -100,7 +108,7 @@ server:
port: 80
```
-Node that Uptime works great behind a proxy - it uses the http_proxy environment variable transparently.
+Node that Uptime works great behind a proxy - it uses the `http_proxy` environment variable transparently.
Architecture
------------
@@ -128,37 +136,55 @@ You can even run several monitor servers in several datacenters to get average r
Using Plugins
-------------
-Uptime provides plugins that you can enable to add more functionality. Plugins can add more notification types, more poller types, new routes to the webapp, etc. To enable plugins, create a `plugins/index.js` module. Uptime automatically requires this module when starting the webapp and the monitor, and tries to call the two following functions:
+Plugins can add more notification types, more poller types, new routes to the webapp, etc. Uptime currently bundles three plugins:
-* `initWebApp()` when starting the webapp
-* `initMonitor()` when starting the monitor
+ * [`console`](https://github.com/fzaninotto/uptime/blob/master/plugins/console/index.js): log pings and events in the console in real time
+ * [`email`](https://github.com/fzaninotto/uptime/blob/master/plugins/email/index.js): notify events (up, down pause) by email
+ * [`patternMatcher`](https://github.com/fzaninotto/uptime/blob/master/plugins/patternMatcher/index.js): allow HTTP & HTTPS pollers to test the response body against a pattern
-For instance, to enable the `console` plugin:
+To enable plugins, just add a line to the `plugins:` section of the configuration file.
+Two of the bundled plugins are already enabled by default:
-```js
-// in plugins/index.js
-exports.initWebApp = function() {
- require('./console').init();
-};
+```yaml
+# in config/default.yaml
+plugins:
+ - ./plugins/console
+ - ./plugins/patternMatcher
+ # - ./plugins/email
```
-Uptime currently bundles three plugins. Check their documentation for installation/configuration instructions:
+You can override these settings in your environment configuration, for instance:
- * [`console`](https://github.com/fzaninotto/uptime/blob/master/plugins/console/index.js): log pings and events in the console in real time
- * [`email`](https://github.com/fzaninotto/uptime/blob/master/plugins/email/index.js): notify events (up, down pause) by email
- * [`patternMatcher`](https://github.com/fzaninotto/uptime/blob/master/plugins/patternMatcher/index.js): allow HTTP & HTTPS pollers to test the response body against a pattern
+```yaml
+# in config/production.yaml
+# disable the console plugin and enable the email plugin
+plugins:
+ # - ./plugins/console
+ - ./plugins/patternMatcher
+ - ./plugins/email
+```
Third-party plugins:
* [`webhooks`](https://github.com/mintbridge/uptime-webhooks): notify events to an URL by sending an HTTP POST request
* [`campfire`](https://gist.github.com/dmathieu/5592418): notify events to Campfire
-You can also create your own plugins. For instance, if you had to recreate a simple version of the `console` plugin, you could write it as follows:
+Writing Plugins
+---------------
+
+A plugin is a simple Node.js module which hooks into predefined extension points. Uptime automatically requires plugin modules when starting the webapp and the monitor, and tries to call the two following functions:
+
+* `initWebApp(options)` when starting the webapp
+* `initMonitor(options)` when starting the monitor
+
+Check the [app.js](https://github.com/fzaninotto/uptime/blob/master/app.js#L97) and [monitor.js](https://github.com/fzaninotto/uptime/blob/master/monitor.js#L8) to see a detail of the options passed to each hook. Also, check the code of existing plugins to understand how they can add new pollers, new notification types, etc.
+
+For instance, if you had to recreate a simple version of the `console` plugin, you could write it as follows:
```js
// in plugins/console/index.js
var CheckEvent = require('../../models/checkEvent');
-exports.init = function() {
+exports.initWebapp = function() {
CheckEvent.on('afterInsert', function(checkEvent) {
checkEvent.findCheck(function(err, check) {
console.log(new Date() + check.name + checkEvent.isGoDown ? ' goes down' : ' goes back up');
View
14 app.js
@@ -95,6 +95,20 @@ io.sockets.on('connection', function(socket) {
});
// load plugins
+config.plugins.forEach(function(pluginName) {
+ var plugin = require(pluginName);
+ if (typeof plugin.initWebApp !== 'function') return;
+ console.log('loading plugin %s on app', pluginName);
+ plugin.initWebApp({
+ app: app,
+ api: apiApp, // mounted into app, but required for events
+ dashboard: dashboardApp, // mounted into app, but required for events
+ io: io,
+ config: config,
+ mongoose: mongoose
+ });
+});
+// old way to load plugins, kept for BC
fs.exists('./plugins/index.js', function(exists) {
if (exists) {
var pluginIndex = require('./plugins');
View
5 config/default.yaml
@@ -22,6 +22,11 @@ autoStartMonitor: true
server:
port: 8082
+plugins:
+ - ./plugins/console
+ - ./plugins/patternMatcher
+ # - ./plugins/email
+
email:
method: SMTP # possible methods are SMTP, SES, or Sendmail
transport: # see https://github.com/andris9/nodemailer for transport options
View
18 monitor.js
@@ -6,16 +6,14 @@ var Monitor = require('./lib/monitor');
monitor = Monitor.createMonitor(config.monitor);
// load plugins
-fs.exists('./plugins/index.js', function(exists) {
- if (exists) {
- var pluginIndex = require('./plugins');
- if (typeof pluginIndex.initMonitor === 'function') {
- pluginIndex.initMonitor({
- monitor: monitor,
- config: config
- });
- }
- }
+config.plugins.forEach(function(pluginName) {
+ var plugin = require(pluginName);
+ if (typeof plugin.initMonitor !== 'function') return;
+ console.log('loading plugin %s on monitor', pluginName);
+ plugin.initMonitor({
+ monitor: monitor,
+ config: config
+ });
});
monitor.start();
View
15 plugins/console/index.js
@@ -3,16 +3,19 @@
*
* Logs all pings and events (up, down, paused, restarted) on the console
*
- * To enable the plugin, call init() in the webapp hook in plugins/index.js
- * exports.initWebApp = function() {
- * require('./console').init();
- * }
- *
+ * Installation
+ * ------------
+ * This plugin is enabled by default. To disable it, remove its entry
+ * from the `plugins` key of the configuration:
+ *
+ * // in config/production.yaml
+ * plugins:
+ * # - ./plugins/console
*/
var Ping = require('../../models/ping');
var CheckEvent = require('../../models/checkEvent');
-exports.init = function(enableNewEvents, enableNewPings) {
+exports.initWebApp = function(enableNewEvents, enableNewPings) {
if (typeof enableNewEvents == 'undefined') enableNewEvents = true;
if (typeof enableNewPings == 'undefined') enableNewPings = true;
if (enableNewEvents) registerNewEventsLogger();
View
53 plugins/email/index.js
@@ -3,12 +3,35 @@
*
* Notifies all events (up, down, paused, restarted) by email
*
- * To enable the plugin, call init() in the webapp hook in plugins/index.js
- * exports.initWebApp = function() {
- * require('./email').init();
- * }
+ * Installation
+ * ------------
+ * This plugin is disabled by default. To enable it, add its entry
+ * to the `plugins` key of the configuration:
*
- * Example configuration
+ * // in config/production.yaml
+ * plugins:
+ * - ./plugins/email
+ *
+ * Usage
+ * -----
+ * This plugin sends an email each time a check is started, goes down, or goes back up.
+ * When the check goes down, the email contains the error details:
+ *
+ * Object: [Down] Check "FooBar" just went down
+ * On Thursday, September 4th 1986 8:30 PM,
+ * a test on URL "http://foobar.com" failed with the following error:
+ *
+ * Error 500
+ *
+ * Uptime won't send anymore emails about this check until it goes back up.
+ * ---------------------------------------------------------------------
+ * This is an automated email sent from Uptime. Please don't reply to it.
+ *
+ * Configuration
+ * -------------
+ * Here is an example configuration:
+ *
+ * // in config/production.yaml
* email:
* method: SMTP # possible methods are SMTP, SES, or Sendmail
* transport: # see https://github.com/andris9/nodemailer for transport options
@@ -32,8 +55,8 @@ var moment = require('moment');
var config = require('config').email;
var CheckEvent = require('../../models/checkEvent');
var ejs = require('ejs');
-
-exports.init = function() {
+
+exports.initWebApp = function() {
var mailer = nodemailer.createTransport(config.method, config.transport);
var templateDir = __dirname + '/views/';
CheckEvent.on('afterInsert', function(checkEvent) {
@@ -41,11 +64,11 @@ exports.init = function() {
checkEvent.findCheck(function(err, check) {
if (err) return console.error(err);
var filename = templateDir + checkEvent.message + '.ejs';
- var renderOptions = {
- check: check,
- checkEvent: checkEvent,
- url: config.dashboardUrl,
- moment: moment,
+ var renderOptions = {
+ check: check,
+ checkEvent: checkEvent,
+ url: config.dashboardUrl,
+ moment: moment,
filename: filename
};
var lines = ejs.render(fs.readFileSync(filename, 'utf8'), renderOptions).split('\n');
@@ -53,11 +76,11 @@ exports.init = function() {
from: config.message.from,
to: config.message.to,
subject: lines.shift(),
- text: lines.join('\n'),
+ text: lines.join('\n')
};
mailer.sendMail(mailOptions, function(err2, response) {
- if (err2) return console.error(err2);
- console.log('Notified event by email: Check ' + check.name + ' ' + checkEvent.message);
+ if (err2) return console.error('Email plugin error: %s', err2);
+ console.log('Notified event by email: Check ' + check.name + ' ' + checkEvent.message);
});
});
});
View
24 plugins/patternMatcher/index.js
@@ -3,22 +3,18 @@
*
* Adds the ability to HTTP & HTTPS pollers to test the response body against a pattern
*
- * The plugin must be enabled both in the monitor and in the webapp:
+ * Installation
+ * ------------
+ * This plugin is enabled by default. To disable it, remove its entry
+ * from the `plugins` key of the configuration:
*
- * // in plugins/index.js
- * var patternMatcherPlugin = require('./patternMatcher');
+ * // in config/production.yaml
+ * plugins:
+ * # - ./plugins/patternMatcher
*
- * exports.initWebApp = function(options) {
- * // enable patternMatcher for the webapp
- * patternMatcherPlugin.initWebApp(options);
- * };
- *
- * exports.initMonitor = function(options) {
- * // enable patternMatcher for the monitor
- * patternMatcherPlugin.initMonitor(options);
- * };
- *
- * Then, restart Uptime, and add a pattern to http checks in the dashboard UI.
+ * Usage
+ * -----
+ * Add a pattern to http checks in the dashboard UI.
* Patterns are regexp, for instance '/hello/i'.
*
* When Uptime polls a check with a pattern, it tests the pattern against the
Please sign in to comment.
Something went wrong with that request. Please try again.