Easy Monitoring
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.
This gem extracts and modularizes the logic we had in our monitoring controllers and were copying back and forth between applications.
Add to Gemfile and bundle!:
gem 'easymon'
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-databasefor use.
Next, we need to add the routes to your application. Depending on the rails version, this is done one of two ways:
Add
Easymon.routes(map)to your
config/routes.rb. This will put the Easymon routes under
/up. If you want Easymon mounted somewhere other than
/up, use
Easymon.routes(map, "/monitoring"). That would put the Easymon paths under
/monitoring. For Rails 3.0, the default routes file does not provide
map, so use
Easymon.routes(self)instead.
Rails 3.1+ gives us mountable engines, so use the standard syntax, adding
mount Easymon::Engine => "/up"to your
config/routes.rb.
Now, you can run your entire checklist by visiting
/up, or wherever you have mounted the application. If you want to just test the single check, go to
/up/application-database, and only the check named
application-databasewill be run.
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, this will register four checks, individually available at:
/up/application-database
/up/redis
/up/memcached
/up/critical- Runs both the application-database and redis checks.
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_withthat will be called with the current request object:
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!)
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"]in the case of a successful check or
[false, "Timeout"]in the case of a failed check.
Easymon::ActiveRecordCheckis a basic check that uses ActiveRecord to check the availability of your main database. It's usually invoked as such:
Easymon::ActiveRecordCheck.new(ActiveRecord::Base)
Internally, it checks
klass.connection.active?where klass is whatever class you passed to the check. Usually this will be ActiveRecord::Base, but feel free to go crazy.
Easymon::RedisCheckwill check the availability of a Redis server, given an appropriate config hash. Typically, we'll read the config off disk, but as long as you get a valid config hash, this will work:
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.
Easymon::MemcachedCheckis a basic check that will write and then read a key from the cache. It expects a cache instance to check, so it could be as easy as:
Easymon::MemcachedCheck.new(Rails.cache)
Easymon::Semaphorechecks for the presence of a file on disk relative to the Rails.root of the current application.
check = Easymon::SemaphoreCheck.new("config/redis.yml")
This is mainly a check that gets subclassed by the next check.
Easymon::TrafficEnabledCheckis fairly specific, but when we want a server to accept traffic, we can place a file in the Rails.root, and the load balancers can use the result of this check to help decide whether or not to send traffic to the node.
Easymon::TrafficEnabledCheck.new("enable-traffic")
This is a subclass of the Semaphore check mentioned above.
Easymon::SplitActiveRecordCheckis the most complicated check, as it's not something you can use out of the gate. Here we pass a block so we get a fresh instance of
ActiveRecord::Baseor whatever other class we might be using to make a secondary database connection.
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::Baselike so:
check = Easymon::SplitActiveRecordCheck.new { [ActiveRecord::Base.connection, Easymon::Base.connection] } Easymon::Repository.add("split-database", check)
Easymon::HttpCheckwill check the return status of a HEAD request to a URL. Great for checking service endpoint availability! The following will make a request to port 9200 on localhost, which is where you might have Elasticsearch running:
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])
To run the tests, you need MySQL server installed and running, and accepting connections on localhost:3306 for the
rootuser with a blank password, as configured in database.yml.
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
dummyuser. You can create the dummy user with the following command in
psql:
CREATE USER dummy WITH PASSWORD 'dummy';
Then run the tests with:
bundle exec rake test
Here's the most direct way to get your work merged into the project:
If you're going to make a major change ask first to make sure it's in line with the project goals.
See the issues page. :smile:
See LICENSE