Easymon

Easymon helps you monitor your application's availability. It provides a simple way to test the availability of resources your application needs, like the application database, a memcached connection, or a redis instance. These test results can be used by a load balancer to determine the general health and viability of the node your application is running on.

It's packaged up as a rails engine for 3.1 and greater, and a plugin for 2.3 - 3.0.

History

This gem extracts and modularizes the logic we had in our monitoring controllers and were copying back and forth between applications.

Installation

Add to Gemfile and bundle!:

gem 'easymon'

Usage

To get started, you'll need to add an initializer for this to do anything. In

config/initializers/easymon.rb

Easymon::Repository.add("application-database", Easymon::ActiveRecordCheck.new(ActiveRecord::Base))

This will register a check called

application-database

Next, we need to add the routes to your application. Depending on the rails version, this is done one of two ways:

Rails 2.3.x & 3.0

Add

Easymon.routes(map)

config/routes.rb

/up

/up

Easymon.routes(map, "/monitoring")

/monitoring

map

Easymon.routes(self)

Rails 3.1+

Rails 3.1+ gives us mountable engines, so use the standard syntax, adding

mount Easymon::Engine => "/up"

config/routes.rb

Now, you can run your entire checklist by visiting

/up

/up/application-database

application-database

Critical Checks

If you have several services that are critical to your app, and others that are not, you can segregate those for health check purposes if you wish. Assuming your database and redis are critical, but memcached is not, again in

config/initializers/easymon.rb

Easymon::Repository.add(
  "application-database",
  Easymon::ActiveRecordCheck.new(ActiveRecord::Base),
  :critical
)
Easymon::Repository.add(
  "redis",
  Easymon::RedisCheck.new(
    YAML.load_file(
      Rails.root.join("config/redis.yml")
    )[Rails.env].symbolize_keys
  ),
  :critical
)
Easymon::Repository.add(
  "memcached",
  Easymon::MemcachedCheck.new(Rails.cache)
)

In addition to the main route

/up

• /up/application-database

• /up/redis

• /up/memcached

• /up/critical

  - Runs both the application-database and redis checks.

Security

You might not want to have this data available to everyone who hits your site, as it can expose both timing data and, depending on your check names, various bits of your infrastructure. You can tell Easymon what addresses, headers, or whatever defines an authorized request by providing a block to

Easymon.authorize_with

Easymon.authorize_with = Proc.new { |request| request.remote_ip == '192.168.1.1'}
# Or
Easymon.authorize_with = Proc.new { |request|
  request.headers["X-Forwarded-For"].nil?
}

This will get run on each request, so keep it simple. (Actually, that's a good rule of thumb for any checks you write, too. Remember, these are all in your main app request pipeline!)

Checks

A check can be any ruby code that responds_to? a #check method that returns a two element array. The first element is the result of executing the check and should be true or false. The second element is the message describing what's going on. The array would look something like this:

[true, "Up"]

[false, "Timeout"]

Included Checks

• ActiveRecord
• Redis
• Memcached
• Semaphore
• Traffic Enabled
• Split ActiveRecord
• Http

ActiveRecord

Easymon::ActiveRecordCheck

Easymon::ActiveRecordCheck.new(ActiveRecord::Base)

Internally, it checks

klass.connection.active?

Redis

Easymon::RedisCheck

Easymon::RedisCheck.new(
  YAML.load_file(Rails.root.join("config/redis.yml"))[Rails.env].symbolize_keys
)

This is the most visually complex test to instantiate, but it's only because we're loading the config from disk and getting the config block that matches the Rails.env in one line. As long as you pass a hash that can be used by Redis.new, it doesn't care where the config comes from.

Memcached

Easymon::MemcachedCheck

Easymon::MemcachedCheck.new(Rails.cache)

Semaphore

Easymon::Semaphore

check = Easymon::SemaphoreCheck.new("config/redis.yml")

This is mainly a check that gets subclassed by the next check.

Traffic Enabled

Easymon::TrafficEnabledCheck

Easymon::TrafficEnabledCheck.new("enable-traffic")

This is a subclass of the Semaphore check mentioned above.

Split ActiveRecord

Easymon::SplitActiveRecordCheck

ActiveRecord::Base

For example, given the following other class:

module Easymon
  class Base < ActiveRecord::Base
    def establish_connection(spec = nil)
      if spec
        super
      elsif config = Easymon.database_configuration
        super config
      end
    end
    def database_configuration
      env = "#{Rails.env}_slave"
      config = YAML.load_file(Rails.root.join('config/database.yml'))[env]
    end
  end
end

We would check both it and

ActiveRecord::Base

check = Easymon::SplitActiveRecordCheck.new {
  [ActiveRecord::Base.connection, Easymon::Base.connection]
}
Easymon::Repository.add("split-database", check)

Http

Easymon::HttpCheck

Easymon::HttpCheck.new("http://localhost:9200")

Typically, we'll read an elasticsearch config off disk, and use the URL like so:

config = YAML.load_file(Rails.root.join("config/elasticsearch.yml"))[Rails.env].symbolize_keys
Easymon::HttpCheck.new(config[:url])

Testing

To run the tests, you need MySQL server installed and running, and accepting connections on localhost:3306 for the

root

Create the MySQL test databases by running:

bundle exec rake db:create

To run tests on PostgreSQL, you need the server installed and running, and accepting connections on localhost:5432 for the

dummy

psql

CREATE USER dummy WITH PASSWORD 'dummy';

Then run the tests with:

bundle exec rake test

How to contribute

Here's the most direct way to get your work merged into the project:

1. Fork the project
2. Clone down your fork
3. Create a feature branch
4. Add your feature + tests
5. Document new features in the README
6. Make sure everything still passes by running the tests
7. If necessary, rebase your commits into logical chunks, without errors
8. Push the branch up
9. Send a pull request for your branch

If you're going to make a major change ask first to make sure it's in line with the project goals.

To Do

See the issues page. :smile:

Authors

• Nathan Anderson

License

See LICENSE