Monitoring notification routing + event processing system. For issues with the Flapjack packages, please see
Ruby JavaScript Gherkin HTML Go CSS Shell
Clone or download
Failed to load latest commit information.
bin remove environment CLI arg Oct 19, 2015
doc @ e4020a4 support acks, test notifications as zermelo stubs Jun 17, 2015
etc Merge remote-tracking branch 'mkobel/threema-gateway' into threema-ga… Apr 19, 2016
features port 1.x test for recovery delay Dec 14, 2015
lib Merge remote-tracking branch 'mkobel/threema-gateway' into threema-ga… Apr 19, 2016
libexec fix #930, previous changes broke pandik compatibility Feb 15, 2016
log add /log Oct 9, 2013
spec Merge remote-tracking branch 'mkobel/threema-gateway' into threema-ga… Apr 19, 2016
src/flapjack fix #930, previous changes broke pandik compatibility Feb 15, 2016
tasks task to dump data structures doc Dec 1, 2015
.gitignore merge cloudwatch code into main broker, add event format arg, add to … Oct 15, 2015
.gitmodules Merge branch 'master' into threading_and_sandstorm May 25, 2014
.rspec gem updates Jan 9, 2015
.ruby-version check against Ruby 2.3, latest bundler fixes platform bug Jan 8, 2016
.travis.yml edit travis notifications Aug 8, 2016 bump version for 2.0 final release Feb 8, 2016 minor doc updates for 2.0 Feb 16, 2016
Dockerfile fix deb repo url in dockerfile Oct 23, 2014
Gemfile change version format, use zermelo and -diner releases Oct 7, 2015
Gemfile.lock update flapjack-diner dependency, fix Gemfile.lock Feb 8, 2016
LICENCE minor doc updates for 2.0 Feb 16, 2016 minor doc updates for 2.0 Feb 16, 2016
Rakefile pact specs passing, json handling stuff adapted Oct 1, 2014 httpbroker: add support for details, tags Feb 9, 2016
flapjack.gemspec update flapjack-diner dependency, fix Gemfile.lock Feb 8, 2016

Flapjack Flapjack

Build Status

Flapjack is a flexible monitoring notification routing system that handles:

  • Alert routing (determining who should receive alerts based on interest, time of day, scheduled maintenance, etc)
  • Alert summarisation (with per-user, per media summary thresholds)
  • Your standard operational tasks (setting scheduled maintenance, acknowledgements, etc)

Flapjack will be immediately useful to you if:

  • You want to identify failures faster by rolling up your alerts across multiple monitoring systems.
  • You monitor infrastructures that have multiple teams responsible for keeping them up.
  • Your monitoring infrastructure is multitenant, and each customer has a bespoke alerting strategy.
  • You want to dip your toe in the water and try alternative check execution engines like Sensu, Icinga, or cron in parallel to Nagios.

Try it out with the Quickstart Guide

The Quickstart guide will help you get Flapjack up and running in a VM locally using Vagrant and VirtualBox.

The technical low-down

Flapjack provides a scalable method for dealing with events representing changes in system state (OK -> WARNING -> CRITICAL transitions) and alerting appropriate people as necessary.

At its core, Flapjack processes events received from external check execution engines, such as Nagios. Nagios provides a 'perfdata' event output channel, which writes to a named pipe. flapjack-nagios-receiver then reads from this named pipe, converts each line to JSON and adds them to the events queue.

Flapjack sits downstream of check execution engines (like Nagios, Sensu, Icinga, or cron), processing events to determine:

  • if a problem has been detected
  • who should know about the problem
  • how they should be told

Additional check engines can be supported by adding additional receiver processes similar to the nagios receiver.


NB: v2 packages will be ready soon -- for the moment these instructions will not work

Ubuntu Precise 64 (12.04):

Tell apt to trust the Flapjack package signing key:

gpg --keyserver --recv-keys 803709B6
gpg -a --export 803709B6 | sudo apt-key add -

Add the Flapjack Debian repository to your Apt sources:

echo "deb precise main" | sudo tee /etc/apt/sources.list.d/flapjack.list

Install the latest Flapjack package:

sudo apt-get update
sudo apt-get install flapjack

Alternatively, download the deb and install using sudo dpkg -i <filename>

The Flapjack package is an Omnibus package and as such contains most dependencies under /opt/flapjack, including Redis.

Installing the package will start Redis (non standard port) and Flapjack. You should now be able to access the Flapjack Web UI at:


And consume the REST API at:


N.B. The Redis installed by Flapjack runs on a non-standard port (6380), so it doesn't conflict with other Redis instances you may already have installed.

Other OSes:

Currently we only make a package for Ubuntu Precise (amd64). If you feel comfortable getting a ruby environment going on your preferred OS, then you can also just install Flapjack from

gem install flapjack

Using a tool like rbenv or rvm is recommended to keep your Ruby applications from intefering with one another.

Alternatively, you can add support for your OS of choice to omnibus-flapjack and build a native package. Pull requests welcome, and we'll help you make this happen!

You'll also need Redis >= 2.6.12.


Have a look at the default config file and modify things as required. The package installer copies this to /etc/flapjack/flapjack_config.toml if it doesn't already exist.

# edit the config
sudo vi /etc/flapjack/flapjack_config.toml

# reload the config
sudo /etc/init.d/flapjack reload


Ubuntu Precise 64:

After installing the Flapjack package, Redis and Flapjack should be automatically started.

First up, start Redis if it's not already started:

# status:
sudo /etc/init.d/redis-flapjack status

# start:
sudo /etc/init.d/redis-flapjack start

Operating Flapjack:

# status:
sudo /etc/init.d/flapjack status

# reload:
sudo /etc/init.d/flapjack reload

# restart:
sudo /etc/init.d/flapjack restart

# stop:
sudo /etc/init.d/flapjack stop

# start:
sudo /etc/init.d/flapjack start


Please see the documentation.

Developing Flapjack

Information on developing more Flapjack components or contributing to core Flapjack development can be found in the Developing section of the docs.

Note that the master branch corresponds to Flapjack 2; maintenance builds for Flapjack 1 are built from the maint/1.x branch.

Documentation Submodule

We have the documentation for this project on a github wiki and also referenced as a submodule at /doc in this project. Run the following commands to populate the local doc/ directory:

git submodule init
git submodule update

If you make changes to the documentation locally, here's how to publish them:

  • Checkout master within the doc subdir, otherwise you'll be commiting to no branch, a.k.a. no man's land.
  • git add, commit and push from inside the doc subdir
  • Add, commit and push the doc dir from the root (this updates the pointer in the main git repo to the correct ref in the doc repo, we think...)


All of the documentation.