Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

node-uptime

fzaninotto19MIT3.0.0

Remote monitoring for HTTP applications

uptime, monitoring, api, check

readme

uptime

A simple remote monitoring utility using Node.js and MongoDB.

You can watch a demo screencast on Vimeo.

Features

  • Monitor thousands of websites (powered by Node.js asynchronous programming)
  • Tweak frequency of monitoring on a per-check basis, up to the millisecond
  • Receive instant web alerts on every page when a check goes down (thanks socket.io)
  • Record availability statistics for further reporting (powered by MongoDB)
  • Detailed uptime reports with animated charts (powered by Highcharts)
  • Monitor availability, responsiveness, average response time , and total uptime/downtime
  • Get details about failed checks (HTTP error code, etc.)
  • Group checks by tags and get reports by tag
  • Familiar web interface (powered by Twitter Bootstrap 2.0)
  • complete API for integration with third-party monitoring services
  • Easy installation and zero administration

Installing Uptime

One line:

> npm install node-uptime

Alternatively, clone the repository from GitHub and install dependencies using npm:

> git clone git://github.com/fzaninotto/uptime.git
> npm install

Lastly, start the application with:

> node app.js

Note that Uptime requires at least Node.js 0.6.

Adding Checks

By default, the web UI runs on port 8082, so just browse to

http://localhost:8082/

And you're ready to begin. Create your first check by entering an URL, wait for the first ping, and you'll soon see data flowing through your charts!

Configuring

Uptime uses node-config to allow YAML configuration and environment support. Here is the default configuration, taken from config/default.yaml:

mongodb:
  server:   localhost
  database: uptime
  user:     root 
  password:

monitor:
  name:                   origin
  apiUrl:                 'http://localhost:8082/api'
  pollingInterval:        10000      # ten seconds
  timeout:                5000       # five seconds

analyzer:
  updateInterval:         60000      # one minute
  qosAggregationInterval: 600000     # ten minutes
  pingHistory:            8035200000 # three months

autoStartMonitor: true

server:
  port:     8082

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:

server:
  port:     80

Node that Uptime works great behind a proxy - it uses the http_proxy environment variable transparently.

Running The Monitor In a Separate Process

Heavily browsing the web dashboard may slow down the server - including the polling monitor. In other terms, using the application can influence the uptime measurements. To avoid this effect, it is recommended to run the polling monitor in a separate process.

To that extent, set the autoStartMonitor setting to false in the production.yaml, and launch the monitor by hand:

> node monitor.js &
> node app.js

You can also run the monitor in a different server. This second server must be able to reach the API of the dashboard server: set the monitor.apiUrl setting accordingly in the production.yaml file of the monitor server.

You can even run several monitor servers in several datacenters to get average response time. In that case, make sure you set a different monitor.name setting for all monitor servers to be able to tell which server make a particular ping.

Using Plugins

Uptime provides plugins that you can enable to add more functionality.

To enable plugins, create a plugins/index.js module. This module must offer a public init() method, where you will require and initialize plugin modules. For instance, to enable only the console plugin:

// in plugins/index.js
exports.init = function() {
  require('./console').init();
}

Currently supported plugins:

  • console: log pings and events in the console in real time

You can add your own plugins under the plugins directory. A plugin is simply a module with a public init() method. For instance, if you had to recreate a simple version of the console plugin, you could write it as follows:

// in plugins/console/index.js
var CheckEvent = require('../../models/checkEvent');
exports.init = function() {
  CheckEvent.on('postInsert', function(checkEvent) {
    checkEvent.findCheck(function(err, check) {
      console.log(new Date() + check.name + checkEvent.isGoDown ? ' goes down' : ' goes back up');
    });
  });
}

All Uptime entities emit lifecycle events that you can listen to on the Model class. These events are preInsert, postInsert, preUpdate, postUpdate, preSave (called for both inserts and updates), postSave (called for both inserts and updates), preRemove, and postRemove.

License

The Uptime code is free to use and distribute, under the MIT license.

Uptime uses third-party libraries:

If you like the software, please help improving it by contributing PRs on the GitHub project!

TODO

  • Allow email alerts in case of non-availability (not sure if this should be part of the lib)
  • Account for scheduled maintenance (and provide two QoS calculations: with and without scheduled maintenance)
  • Allow for JavaScript execution in the monitored resources by using a headless browser (probably zombie.js)
  • Unit tests

changelog

Uptime Changelog

To be released

  • Remove ICMP poller as it requires Uptime to be launched with root permissions to work
  • Add basicAuth plugin to restrict access to the API and dashboard apps using Basic Authentication
  • Upgrade moment.js to version 2.1
  • Add httpOptions plugin to allow setting custom headers or HTTP options to a check
  • 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
  • Update plugins to let them extend both the monitor and the webapp (warning: changes plugins signature)
  • Add architecture schema in the README
  • Update Dummy Target more to make it verbose on the console
  • Update Check model to store pollerParams
  • Update Ping model to store pollerDetails
  • 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
  • Fix warnings in production by using cookie store for sessions
  • Add mention of external plugins in README
  • Add patternMatcher plugin to allow pattern detection in response body
  • Fix bug allowing the creation of empty checks
  • Add Http Status 303 to allowed redirect Types
  • Fix "Cannot set property 'protocol' of undefined" error when running Uptime behind a proxy
  • Node 0.10 support

2013-04-22, v3.1

  • Update README.md
  • Use Url as Check name when left empty
  • Stop the server if MongoDB is not started
  • Support port overriding via process.env.PORT
  • Fix bug with pause and email
  • Fix bug where checks are pinged too often when they timeout
  • Add link to uptime home page in the dashboard footer
  • Mention the fact that the monitor URL must be accessible without proxy
  • Add email plugin
  • Added uptime version in the footer

2012-12-07, v3.0

  • Uptime bars
  • Exact availability calculation
  • New stats page and date navigation
  • Replaced Highcharts by Flotr2 for charts. No more licence problem!
  • Upgraded to Twitter Bootstrap V2
  • Many tweaks in the GUI
  • Heavy refactoring

2012-12-07, v2.0

  • Moved Mongo initialization to a dedicated bootstrap file
  • Added support for setting the full MongoDB connection string in the config file
  • Fixed engine requirement in package.json
  • Updated Node poller user agent version
  • Fixed console plugin
  • Fixed fixtures to let them generate CheckEvents
  • Fixed pings list not refreshing live in dashboard

2012-09-19, v2.0rc0

  • Upgraded Node.js to 0.8
  • Bumped main dependencies (Express and Mongoose) to v3. This lead to some refactoring in the model classes.
  • Switched to local jQuery to avoid networking issue

2012-09-19, v1.4

  • This is the last release compatible with Node 0.6.
  • New events appear as such when watching event list
  • Added favicon. The favicon turns red when at least one check is down.

2012-08-05, v1.3

  • Added a User-Agent header to both http and https pollers, to identify pings from the monitor in server logs; you can override the header via configuration
  • Fixed "Save and add" redirection
  • Made check title optional (falls back to the url)
  • Fixed handling of relative Location headers
  • Fixed chart timezone and vertical scale bugs
  • Made new events more apparent in the navbar, and in the events page
  • Removed custom date display logic and added moment.js as a dependency.
  • Fixed check when http redirects to https
  • Removed lifecycleEventsPlugin and added mongoose-lifecycle module as a dependency. This change renames events on Mongoose models from 'pre-' to 'before-' and from 'post-' to 'after-' (e.g. 'postRemove' becomes 'afterRemove').
  • Modified API routes to be more RESTful
  • Upgraded dependencies (mongoose, express, ejs, config, async, socket.io)
  • Added a Reports tab for tags, offering easily accessible monthly reports
  • Made tabs compatible with direct links and back button in tag and check view

2012-04-21, v1.2

  • Ping list is now updated in real time
  • Added 'Save and add' button in new check form to facilitate batch check creation
  • Changed the CheckEvent format for better extensibility (use the fixtures/fixEvents.js fix to migrate existing events)
  • Fix polling interval to mimic the behavior of a cron
  • Add a way to pause checks in the dashboard GUI, in the API, and in the model
  • Split Monitor class and configuration, to fix polling when autoStartMonitor is false
  • Fixed failure to add check in the dashboard when the protocol wasn't set
  • Added UDP poller (bolgovr)

2012-04-10, v1.1

  • Add support for HTTPS checks
  • Refactor poller class to allow adapter pattern. Opens the door for UDP, FTP, complete page... check types.
  • Removed proxy configuration (now uses environment variables)

2012-03-28, v1.0

  • Initial version