is_it_working 1.0.10

data/README.rdoc

@@ -0,0 +1,75 @@
+= Is It Working
+
+This gem provides a mechanism for setting up a Rack handler that tests the status of various components of an application and reports the output. It is designed to be modular and give a comprehensive view of the application status with a consistent URL (/is_it_working by default).
+
+This handler can be used by monitoring to determine if an application is working or not, but it does not replace system level monitoring of low level resources. Rather it adds another level which tells if the application can actually use those resources.
+
+== Use It As Documentation
+
+A feature of this gem is that it gives you a consistent place to document the external dependencies of you application as code. The handler checking the status of you application should have a check for every line drawn from it to another box on a system architecture diagram.
+
+== Example
+
+Suppose you have a Rails application that uses the following services:
+
+* ActiveRecord uses PostgreSQL database
+* Caching is done using Rails.cache with a cluster of memcached instances
+* Web service API hosted at https://api.example.com
+* NFS shared directory symlinked to from system/data in the Rails root directory
+* SMTP server at mail.example.com
+* A black box service encapsulated in AwesomeService
+
+A monitoring handler for this set up could be set up in <tt>config/initializers/is_it_working.rb</tt> like this:
+
+  Rails.configuration.middleware.use(IsItWorking::Handler) do |h|
+    # Check the ActiveRecord database connection without spawning a new thread
+    h.check :active_record, :async => false
+    
+    # Check the memcache servers used by Rails.cache if using the MemCacheStore implementation
+    h.check :memcache, :cache => Rails.cache if Rails.cache.is_a?(ActiveSupport::Cache::MemCacheStore)
+    
+    # Check that the web service is working by hitting a known URL with Basic authentication
+    h.check :url, :get => "http://api.example.com/version", :username => "appname", :password => "abc123"
+    
+    # Check that the NFS mount directory is available with read/write permissions
+    h.check :directory, :path => Rails.root + "system/data", :permission => [:read, :write]
+    
+    # Check the mail server configured for ActionMailer
+    h.check :action_mailer if ActionMailer::Base.delivery_method == :smtp
+    
+    # Ping another mail server
+    h.check :ping, :host => "mail.example.com", :port => "smtp"
+    
+    # Check that AwesomeService is working using the service's own logic
+    h.check :awesome_service do |status|
+      if AwesomeService.active?
+        status.ok("service active")
+      else
+        status.fail("service down")
+      end
+    end
+  end
+
+== Output
+
+The response from the handler will be a plain text description of the checks that were run and the results of those checks. If all the checks passed, the response code will be 200. If any checks fail, the response code will be 500. The response will look something like this:
+
+  Host: example.com
+  PID:  696
+  Timestamp: 2011-01-13T16:55:13-06:00
+  Elapsed Time: 84ms
+
+  OK:   active_record - ActiveRecord::Base.connection is active (2.516ms)
+  OK:   memcache - cache1.example.com:11211 is available (0.022ms)
+  OK:   memcache - cache2.example.com:11211 is available (0.022ms)
+  OK:   url - GET http://www.example.com/ responded with response '200 OK' (81.775ms)
+  OK:   directory - /app/myapp/system/data exists with read/write permission (0.044ms)
+  OK:   ping - mail.example.com is accepting connections on port "smtp" (61.854ms)
+
+== Security
+
+Keep in mind that the output from the status check will be available on a publicly accessible URL. This can pose a security risk if some servers are not on a private network behind a firewall. If necessary, you can obscure the host names in the predefined checks by providing an <tt>:alias</tt> option that will be output instead of the actual host name or IP address. Also, you can manually specify the hostname that the handler reports for the application with the Handler#hostname= method.
+
+== Thread Safety
+
+By default status checks each happen in their own thread. If you write your own status check, you must make sure it is thread safe. If you need to synchronize the check logic, you can use the +synchronize+ method on the handler object to do so. Alternatively, you can pass <tt>:async => false</tt> to any +check+ specification. This will cause the check to be executed in the main request thread.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'rake'
+
+desc 'Default: run unit tests'
+task :default => :test
+
+begin
+  require 'rspec'
+  require 'rspec/core/rake_task'
+  desc 'Run the unit tests'
+  RSpec::Core::RakeTask.new(:test)
+rescue LoadError
+  task :test do
+    raise "You must have rspec 2.0 installed to run the tests"
+  end
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "is_it_working"
+    gem.summary = %Q{Rack handler for monitoring several parts of a web application.}
+    gem.description = %Q{Rack handler for monitoring several parts of a web application so one request can determine which system or dependencies are down.}
+    gem.authors = ["Brian Durand"]
+    gem.email = ["mdobrota@tribune.com", "ddpr@tribune.com"]
+    gem.files = FileList["lib/**/*", "spec/**/*", "bin/**/*", "example/**/*" "README.rdoc", "Rakefile", "License.txt"].to_a
+    gem.has_rdoc = true
+    gem.rdoc_options << '--line-numbers' << '--inline-source' << '--main' << 'README.rdoc'
+    gem.extra_rdoc_files = ["README.rdoc"]
+    # Add dependencies with gem.add_dependency('gem_name')
+    gem.add_development_dependency('rspec', '>= 2.0')
+    gem.add_development_dependency('webmock', '>= 1.6.0')
+    gem.add_development_dependency('memcache-client')
+    gem.add_development_dependency('dalli')
+  end
+  Jeweler::RubygemsDotOrgTasks.new
+rescue LoadError
+end

data/lib/is_it_working.rb

@@ -0,0 +1,18 @@
+require 'time'
+require 'thread'
+
+module IsItWorking
+  autoload :Check, File.expand_path("../is_it_working/check.rb", __FILE__)
+  autoload :Filter, File.expand_path("../is_it_working/filter.rb", __FILE__)
+  autoload :Handler, File.expand_path("../is_it_working/handler.rb", __FILE__)
+  autoload :Status, File.expand_path("../is_it_working/status.rb", __FILE__)
+  
+  # Predefined checks
+  autoload :ActionMailerCheck, File.expand_path("../is_it_working/checks/action_mailer_check.rb", __FILE__)
+  autoload :ActiveRecordCheck, File.expand_path("../is_it_working/checks/active_record_check.rb", __FILE__)
+  autoload :DalliCheck, File.expand_path("../is_it_working/checks/dalli_check.rb", __FILE__)
+  autoload :DirectoryCheck, File.expand_path("../is_it_working/checks/directory_check.rb", __FILE__)
+  autoload :MemcacheCheck, File.expand_path("../is_it_working/checks/memcache_check.rb", __FILE__)
+  autoload :PingCheck, File.expand_path("../is_it_working/checks/ping_check.rb", __FILE__)
+  autoload :UrlCheck, File.expand_path("../is_it_working/checks/url_check.rb", __FILE__)
+end

data/lib/is_it_working/checks/action_mailer_check.rb

@@ -0,0 +1,25 @@
+require 'action_mailer'
+
+module IsItWorking
+  # Check if the mail server configured for ActionMailer is responding.
+  #
+  # The ActionMailer class that yields the configuration can be specified with the <tt>:class</tt>
+  # option. By default this will be ActionMailer::Base. You can also set a <tt>:timeout</tt> option
+  # for how long to wait for a response and an <tt>:alias</tt> option which will be the name reported
+  # back by the check (defaults to the ActionMailer class).
+  #
+  # === Example
+  #
+  #   IsItWorking::Handler.new do |h|
+  #     h.check :action_mailer, :class => UserMailer
+  #   end
+  class ActionMailerCheck < PingCheck
+    def initialize(options={})
+      options = options.dup
+      klass = options.delete(:class) || ActionMailer::Base
+      options.merge!(:host => klass.smtp_settings[:address], :port => klass.smtp_settings[:port] || 'smtp')
+      options[:alias] ||= klass.name
+      super(options)
+    end
+  end
+end

data/lib/is_it_working/checks/active_record_check.rb

@@ -0,0 +1,28 @@
+require 'active_record'
+
+module IsItWorking
+  # Check if the database connection used by an ActiveRecord class is up.
+  #
+  # The ActiveRecord class that yields the connection can be specified with the <tt>:class</tt>
+  # option. By default this will be ActiveRecord::Base.
+  #
+  # === Example
+  #
+  #   IsItWorking::Handler.new do |h|
+  #     h.check :active_record, :class => User
+  #   end
+  class ActiveRecordCheck
+    def initialize(options={})
+      @class = options[:class] || ActiveRecord::Base
+    end
+    
+    def call(status)
+      @class.connection.verify!
+      if @class.connection.active?
+        status.ok("#{@class}.connection is active")
+      else
+        status.fail("#{@class}.connection is not active")
+      end
+    end
+  end
+end

data/lib/is_it_working/checks/dalli_check.rb

@@ -0,0 +1,48 @@
+require 'dalli'
+
+module IsItWorking
+  class DalliCheck
+    # Check if all the memcached servers in a cluster are responding.
+    # The memcache cluster to check is specified with the <tt>:cache</tt> options. The
+    # value can be either a Dalli::Client object (from the dalli gem) or an
+    # ActiveSupport::Cache::DalliStore (i.e. Rails.cache).
+    #
+    # If making the IP addresses of the memcache servers known to the world could
+    # pose a security risk because they are not on a private network behind a firewall,
+    # you can provide the <tt>:alias</tt> option to change the host names that are reported.
+    #
+    # === Example
+    #
+    #   IsItWorking::Handler.new do |h|
+    #     h.check :dalli, :cache => Rails.cache, :alias => "memcache server"
+    #   end
+    def initialize(options={})
+      memcache = options[:cache]
+      raise ArgumentError.new(":cache not specified") unless memcache
+      unless memcache.is_a?(Dalli::Client)
+        if defined?(ActiveSupport::Cache::DalliStore) && memcache.is_a?(ActiveSupport::Cache::DalliStore)
+          # Big hack to get the MemCache object from Rails.cache
+          @memcache = memcache.instance_variable_get(:@data)
+        else
+          raise ArgumentError.new("#{memcache} is not a Dalli::Client")
+        end
+      else
+        @memcache = memcache
+      end
+      @alias = options[:alias]
+    end
+
+    def call(status)
+      servers = @memcache.send(:ring).servers
+      servers.each_with_index do |server, i|
+        public_host_name = @alias ? "#{@alias} #{i + 1}" : "#{server.hostname}:#{server.port}"
+
+        if server.alive?
+          status.ok("#{public_host_name} is available")
+        else
+          status.fail("#{public_host_name} is not available")
+        end
+      end
+    end
+  end
+end

data/lib/is_it_working/checks/directory_check.rb

@@ -0,0 +1,44 @@
+module IsItWorking
+  class DirectoryCheck
+    # Check if a file system directory exists and has the correct access. This
+    # can be very useful to check if the application relies on a shared file sytem
+    # being mounted. The <tt>:path</tt> options must be supplied to the initializer. You
+    # may also supply an <tt>:permission</tt> option with the values <tt>:read</tt>, <tt>:write</tt>, or
+    # <tt>[:read, :write]</tt> to check the permission on the directory as well.
+    #
+    # === Example
+    #
+    #   IsItWorking::Handler.new do |h|
+    #     h.check :directory, :path => "/var/shared/myapp", :permission => [:read, :write]
+    #   end
+    def initialize (options={})
+      raise ArgumentError.new(":path not specified") unless options[:path]
+      @path = File.expand_path(options[:path])
+      @permission = options[:permission]
+      @permission = [@permission] if @permission && !@permission.is_a?(Array)
+    end
+    
+    def call(status)
+      stat = File.stat(@path) if File.exist?(@path)
+      if stat
+        if stat.directory?
+          if @permission
+            if @permission.include?(:read) && !stat.readable?
+              status.fail("#{@path} is not readable by #{ENV['USER']}")
+            elsif @permission.include?(:write) && !stat.writable?
+              status.fail("#{@path} is not writable by #{ENV['USER']}")
+            else
+              status.ok("#{@path} exists with #{@permission.collect{|a| a.to_s}.join('/')} permission")
+            end
+          else
+            status.ok("#{@path} exists")
+          end
+        else
+          status.fail("#{@path} is not a directory")
+        end
+      else
+        status.fail("#{@path} does not exist")
+      end
+    end
+  end
+end

data/lib/is_it_working/checks/memcache_check.rb

@@ -0,0 +1,46 @@
+require 'memcache'
+
+module IsItWorking
+  class MemcacheCheck
+    # Check if all the memcached servers in a cluster are responding.
+    # The memcache cluster to check is specified with the <tt>:cache</tt> options. The
+    # value can be either a MemCache object (from the memcache-client gem) or an
+    # ActiveSupport::Cache::MemCacheStore (i.e. Rails.cache).
+    #
+    # If making the IP addresses of the memcache servers known to the world could
+    # pose a security risk because they are not on a private network behind a firewall,
+    # you can provide the <tt>:alias</tt> option to change the host names that are reported.
+    #
+    # === Example
+    #
+    #   IsItWorking::Handler.new do |h|
+    #     h.check :memcache, :cache => Rails.cache, :alias => "memcache server"
+    #   end
+    def initialize(options={})
+      memcache = options[:cache]
+      raise ArgumentError.new(":cache not specified") unless memcache
+      unless memcache.is_a?(MemCache)
+        if defined?(ActiveSupport::Cache::MemCacheStore) && memcache.is_a?(ActiveSupport::Cache::MemCacheStore)
+          # Big hack to get the MemCache object from Rails.cache
+          @memcache = memcache.instance_variable_get(:@data)
+        else
+          raise ArgumentError.new("#{memcache} is not a MemCache")
+        end
+      else
+        @memcache = memcache
+      end
+      @alias = options[:alias]
+    end
+    
+    def call(status)
+      @memcache.servers.each_with_index do |server, i|
+        public_host_name = @alias ? "#{@alias} #{i + 1}" : "#{server.host}:#{server.port}"
+        if server.alive?
+          status.ok("#{public_host_name} is available")
+        else
+          status.fail("#{public_host_name} is not available")
+        end
+      end
+    end
+  end
+end

data/lib/is_it_working/checks/ping_check.rb

@@ -0,0 +1,53 @@
+require 'socket'
+require 'timeout'
+
+module IsItWorking
+  class PingCheck
+    # Check if a host is reachable and accepting connections on a specified port.
+    #
+    # The host and port to ping are specified with the <tt>:host</tt> and <tt>:port</tt> options. The port
+    # can be either a port number or port name for a well known port (i.e. "smtp" and 25 are
+    # equivalent). The default timeout to wait for a response is 2 seconds. This can be
+    # changed with the <tt>:timeout</tt> option.
+    #
+    # By default, the host name will be included in the output. If this could pose a security
+    # risk by making the existence of the host known to the world, you can supply the <tt>:alias</tt>
+    # option which will be used for output purposes. In general, you should supply this option
+    # unless the host is on a private network behind a firewall.
+    #
+    # === Example
+    #
+    #   IsItWorking::Handler.new do |h|
+    #     h.check :ping, :host => "example.com", :port => "ftp", :timeout => 4
+    #   end
+    def initialize(options={})
+      @host = options[:host]
+      raise ArgumentError.new(":host not specified") unless @host
+      @port = options[:port]
+      raise ArgumentError.new(":port not specified") unless @port
+      @timeout = options[:timeout] || 2
+      @alias = options[:alias] || @host
+    end
+    
+    def call(status)
+      begin
+        ping(@host, @port)
+        status.ok("#{@alias} is accepting connections on port #{@port.inspect}")
+      rescue Errno::ECONNREFUSED
+        status.fail("#{@alias} is not accepting connections on port #{@port.inspect}")
+      rescue SocketError => e
+        status.fail("connection to #{@alias} on port #{@port.inspect} failed with '#{e.message}'")
+      rescue Timeout::Error
+        status.fail("#{@alias} did not respond on port #{@port.inspect} within #{@timeout} seconds")
+      end
+    end
+    
+    def ping(host, port)
+      timeout(@timeout) do
+        s = TCPSocket.new(host, port)
+        s.close
+      end
+      true
+    end
+  end
+end

data/lib/is_it_working/checks/url_check.rb

@@ -0,0 +1,81 @@
+require 'net/http'
+require 'net/https'
+
+module IsItWorking
+  # Check if getting a URL returns a successful response. Only responses in the range 2xx or 304
+  # are considered successful. Redirects will not be followed.
+  #
+  # Available options are:
+  #
+  # * <tt>:get</tt> - The URL to get.
+  # * <tt>:headers</tt> - Hash of headers to send with the request
+  # * <tt>:proxy</tt> - Hash of proxy server information. The hash must contain a <tt>:host</tt> key and may contain <tt>:port</tt>, <tt>:username</tt>, and <tt>:password</tt>
+  # * <tt>:username</tt> - Username to use for Basic Authentication
+  # * <tt>:password</tt> - Password to use for Basic Authentication
+  # * <tt>:open_timeout</tt> - Time in seconds to wait for opening the connection (defaults to 5 seconds)
+  # * <tt>:read_timeout</tt> - Time in seconds to wait for data from the connection (defaults to 10 seconds)
+  # * <tt>:alias</tt> - Alias used for reporting in case making the URL known to the world could provide a security risk.
+  #
+  # === Example
+  #
+  #   IsItWorking::Handler.new do |h|
+  #     h.check :url, :get => "http://services.example.com/api", :headers => {"Accept" => "text/xml"}
+  #   end
+  class UrlCheck
+    def initialize(options={})
+      raise ArgumentError.new(":get must provide the URL to check") unless options[:get]
+      @uri = URI.parse(options[:get])
+      @headers = options[:headers] || {}
+      @proxy = options[:proxy]
+      @username = options[:username]
+      @password = options[:password]
+      @open_timeout = options[:open_timeout] || 5
+      @read_timeout = options[:read_timeout] || 10
+      @alias = options[:alias] || options[:get]
+    end
+    
+    def call(status)
+      t = Time.now
+      response = perform_http_request
+      if response.is_a?(Net::HTTPSuccess)
+        status.ok("GET #{@alias} responded with response '#{response.code} #{response.message}'")
+      else
+        status.fail("GET #{@alias} failed with response '#{response.code} #{response.message}'")
+      end
+    rescue Timeout::Error
+      status.fail("GET #{@alias} timed out after #{Time.now - t} seconds")
+    end
+    
+    private
+      # Create an HTTP object with the options set.
+      def instantiate_http #:nodoc:
+        http_class = nil
+
+        if @proxy && @proxy[:host]
+          http_class = Net::HTTP::Proxy(@proxy[:host], @proxy[:port], @proxy[:username], @proxy[:password])
+        else
+          http_class = Net::HTTP
+        end
+
+        http = http_class.new(@uri.host, @uri.port)
+        if @uri.scheme == 'https'
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        end
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+
+        return http
+      end
+    
+      # Perform an HTTP request and return the response
+      def perform_http_request #:nodoc:
+        request = Net::HTTP::Get.new(@uri.request_uri, @headers)
+        request.basic_auth(@username, @password) if @username || @password
+        http = instantiate_http
+        http.start do
+          http.request(request)
+        end
+      end
+  end
+end