changelog

Aims to answer the question "what's changed in the last hour?" in a distributed system. Very useful to have when the proverbial bad things hit the proverbial ventilation hardware. It can drastically drop mean time to recovery.

How?

changelog provides a simple REST API to post events to, and a web interface where you can quickly see and filter events. The basic idea is that you'll send any event that has even a remote chance of causing problems to this system. Later, when something goes wrong, you can quickly check what's changed in the last minutes / hours.

The web interface:

Sending events is simple:

curl http://changelog.awesomecompany.com/api/events \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"criticality": 1, "unix_timestamp": 1395334488, "category": "misc", "description": "cli test"}'

All four JSON fields are required, and there are no other fields the server understands.

Some ideas for events to send:

• deployment, release
• feature (switch|flag|toggle) changes
• changes to chef / puppet / ansible / ...
• changes to DNS configuration
• cloud instances started, stopped

Getting started

Prerequisites

• sqlite3
• python 2
• virtualenv
• optionally: a Sentry server for collecting exceptions; not that there'll be any :)

Setup - Docker

A public image may be coming up. Until then:

sudo docker build -t changelog .
sudo docker run -d -p 80:8000 changelog

Watch out: with the current Dockerfile, upgrading the application in the container will erase the database. It may not be a huge issue if you don't want to keep a long history, but keep it in mind.

Setup - Manually

git clone https://github.com/prezi/changelog.git
cd changelog
./setup.sh
. virtualenv/bin/activate
python application.py

Configuration

You can set the environment variable CHANGELOG_SETTINGS_PATH to point to a python file. That file can set the values detailed below. The application prints the final configuration at startup to make debugging this easier (not that there's anything to debug, but configuration always needs debugging). The file pointed to by CHANGELOG_SETTINGS_PATH can, for example, look like this:

LISTEN_PORT = 8080
DB_PATH = '/opt/foo/bar/local/changelog.db'

Values you can set:

Variable	Description	Default
DB_PATH	Path to the sqlite3 database file.	/opt/changelog/changelog.db
LISTEN_HOST	IP address where the application will listen when started with python application.py.	127.0.0.1
LISTEN_PORT	Port where the application will listen when started with python application.py.	5000
USE_SENTRY	Send exceptions to Sentry?	False
SENTRY_DSN	Sentry DSN, used only if USE_SENTRY is True.	None

The default configuration values are in settings.py.

Considerations for running in production

• Running under a WSGI server is highly recommended. This project uses the Flask framework, see their documentation for running under Apache or Standalone WSGI containers
• No authentication is provided, you'll probably want to put some authenticating proxy in front of this application. Pull requests for adding authentication support are of course welcome.
• Similarly, no HTTPS termination is provided. Ideally the WSGI container will take care of that.
• If you plan to send a ton of events, sqlite will probably soon become a bottleneck.

Contributing

Feature requests are welcome, bug reports are especially welcome, and pull requests are super welcome. Please make sure to use a feature branch in your fork. Don't look too hard for tests, there are none - not for a lack of belief in tests, but because the application is almost trivial. Please make sure you also update the README to reflect your changes. While you're there you may as well add yourself to the Credits section too :)

Credits

• Roy Rapoport (@royrapoport) for inspiring this tool with his talk at the SF Metrics Meetup
• Ryan Bowlby (@rbowlby)

Awesome tools used

These tools made it possible to write changelog in a weekend. Huge thanks.

• Flask, the lightweight Python web framework and Flask-RESTful for making the REST api trivial to write
• Bootstrap, for making the whole UI look not terrible and bootstrap-datetimepicker for making the date chooser pretty awesome
• jQuery, because obviously
• jQuery BBQ and jQuery hashchange for making the permalink simple to implement
• Sentry for simple-to-use, awesome error reporting / collection / aggregation
• cdnjs for hosting all the client-side libraries above
• Those that we take for granted: sqlite3, python, virtualenv, and the list goes on...

---

^{Image gleefully copied from Android Police}