Fast health and performance monitoring with process handling


Process monitoring with scalable health/performance checking.

Upbeat provides several useful features:

##Complex healthcheck strategies

For accurate healthchecks, sometimes the likes of monit, nagios and/or haproxy is not enough. An example would be testing a mysql server to see if 1) the process is running 2) a query works 3) how fast the query was This is just and example of what upbeat is meant to do. It is not meant to replace the tools mentioned previously, but to actually play nicely with them.

##Fast and scalable remote health checking

Upbeat leverages nodes quickness and allows service healthchecks to be temporarily cached allowing more throughout put in your healthchecks. This will enable every machine to know the status of every other machine in a cluster without doing an expotential number of "real" healthchecks. In the context of cloud computing, where high throughput load balancing is non-trivial this becomes very useful.

##Web Dashboard##

See your statuses on one page or use them for scripting through an api.

##Forever Integration##

Define processes to be run and how to monitor them.



Assuming you have node and npm installed, run:

npm-g install upbeat
upbeat ./my/upbeat-config.yml

Now an http server will be running that you can query for health statuses

##Example Config File:

port: 2468

    - strategy: mysql
      socket: /tmp/mysql.sock
    - strategy: process
      pidfile: /tmp/rails.pid
    - strategy: http
      url: http://localhost:3000/
    - strategy: http
      port: 3000
      interval: 3000
      timeout:  1000

    - name: places
      strategy: http
      url: http://api.v3.factual.com/t/places
        KEY: <my key>
        q:   starbucks 

    - name: homepage
      url: http://www.google.com
      strategy: http

    - strategy: redis
      port: 6537

    - strategy: mysql
      socket: /tmp/mysql.sock

##Web Dashboard:

  • http://localhost:2468/ - dashboard
  • http://localhost:2468/health - health check returns 200
  • http://localhost:2468/services/factual-api
  • http://localhost:2468/services/factual-api/health
  • http://localhost:2468/services/google.com
  • http://localhost:2468/services/google.com/health
  • http://localhost:2468/services/redis
  • http://localhost:2468/services/redis/health


Upbeat uses YAML for configuration. There are several concepts to take note of when running configuring upbeat: server, services, actions and strategies

###Global Server Configuration:

In the top level of the yaml configuration you have 4 main categories:

  • webapp: parameters for the ui
  • logging: parameters for logging
  • processes: parameters for using forever
  • services: a key/value hash where the key is the name of the service and the value is an array of action definitions

###Web Application (UI)

To disable the UI altogether:

webapp: false

To run the web app on a particular port:

  port: 2468

By default, the webapp is enabled and runs on port 2468


You can integrate forever by using the "processes" keyword in your config.

    command: "/usr/local/bin/node"
    options: [ "server.js" ]
      - strategy: http
        url: http://localhost:1337
        status: 200
        interval: 3000
      - strategy: http
        url: http://localhost:1337/hello
        status: 200
        interval: 3000


The services section in the global configuration has to be a hash where the key is the name of the service and the value is an array of "actions" for the service to check.


Actions are a hash that have one required field: strategy. Stragety is used to tell upbeat how to test a particular service. Every action has these fields available to it:

optional fields

  • rise: number of times action has to pass before action can be upgraded from "down" to "up"
  • fall: number of times action has to fail before action can be downgraded from "up" to "down"
  • interval (in millisecondes): time between passed or failed checks (default depends on the strategy)
  • timeout (in milliseconds): time allowed for the request to pass otherwise, its canceled and marked as failed (defaults depends on the strategy)
  • max-response-time: similar to timeout. If an action returns before timeout but is greater than max-response-time, it will still count as a failure
  • name: vanity name for the action used in reports



Checks to see if a process is running via pidfile:

  • pidfile: file with the pid written in it


    - pidfile: /tmp/my.pid
      strategy: process


The http strategy will send a request to the server. Fields:

  • url: The url of the request to use
  • post or put: hash of key/value pairs to use as the data of the request
  • get: hash of key/value parise to use as the query string
  • timeout: defaults to 10000
  • interval: defaults to 10000
  • matches: (array or string) regular expression to test against the returned http payload.
  • lambda: (array or string) a function that should return a boolean (if its matches is not enough)
  • headers: Hash of headers to be used


    - url: http://www.google.com
      strategy: http
      matches: html
      lambda: "function (data) { return data.match(/html/); }"

    - name: test-google
      url: http://www.google.com
      strategy: http
        Host: www.google.info

    - name: test-search
      url: http://www.google.com
      strategy: http
        q: upbeat

    - name: test-google
      strategy: http
      url: http://www.google.com
      rise: 3
      fall: 1


Yes, upbeat can monitor other upbeat servers. Fields:

  • port: port of upbeat server to monitor
  • host: host of upbeat server to monitor
  • timeout: defaults to 5000
  • interval: defaults to 5000


port: 2467
    - strategy: upbeat


Strategy to check if a connection to a port can be established. Fields:

  • port: port of service
  • host: host of service
  • timeout: defaults to 2000
  • interval: defaults to 3000


The mysql strategy will connect to a mysql server and perform a query. Fields:

  • sql: sql to send - defaults to "SHOW DATABASES LIMIT 1"
  • database: selects database to use - defaults to "MYSQL"

connecting - either use the socket field or:

  • host: defaults to ''
  • port: defaults to 3306
  • user
  • password
  • timeout: defaults to 5000
  • interval: defaults to 10000


    - strategy: mysql
      socket: /tmp/mysql.sock


The redis strategy will connect to a redis server and issue an "ECHO hello" command. Fields:

  • host: host of redis server
  • port: port of redis server
  • timeout: defaults to 2000
  • interval: defaults to 10000


    - host:
      port: 6537
      strategy: redis


Upbeat supports basic OAuth get requests. Fields:

  • url
  • key: oauth key
  • secret: oauth secret


    - strategy: oauth
      url: http://api.v3.factual.com/t/places
      key: "My Key"
      secret: "My Secret"

Its pretty simple to register a custom strategy. There are 3 things the object needs to have:

  1. an instantiator where the only paramater is a config hash (action)
  2. check(callback): the callback is function that expects a boolean
  3. clear(): a function that should halt any asynchronus activity


var AlwaysPass = function (config) { this.config };
AlwaysPass.prototype.check = function (callback) {

AlwaysPass.prototype.clear = function () { 
  // no op

require('./upbeat').registerCallback('always-pass', AlwaysPass);

Config file

    - strategy: "/home/me/my-strategy.js"
      key0: val0
      key1: val1


All logging is optional, but here are some parameters you can use:

  console: false # defaults to true
    - /var/log/upbeat.log
    - file: /var/log/upbeat.errors.log
      level: error

If you want to build your own listeners to upbeat, please follow lib/upbeat/logger.ms for an example. You can also look at bin/upbeat for an example of how to instantiate an upbeat server via config file.

var c = new upbeat.Configurer(<config object>);
c.server.on('change', function (service) { console.log('something changed') });


Using configurer to instantiate your server.

var config = ... json config ...;
var configurer = new upbeat.Configurer(config);

The configurer has 3 main members:

  1. server
  2. logger
  3. webapp

The upbeat server is the object that does all the health checking and process management.


Every time a service comes up.


Every time a service goes down.


Every time a services changes status.


Every time a service gets snapshotted

A container for a winston object and is a proxy for a lot of the server events.

A container for an express application.