app_status 1.0.0 → 1.1.0

data/README.md

@@ -63,6 +63,8 @@ This is where you set up the checks which you want to be run when
 someone hits the URL above. Set up some calls which evaluate the health
 of your application and call `add_check` for each one.
 
+#### add_check
+
 `add_check` expects a service name, plus a block to be evaluated to determine
 the health of that service. The block should return either a status value, or
 a 2-element array with status and some details.
@@ -94,6 +96,37 @@ Valid status values (in ascending order of seriousness) are:
 
 These are set up to be compatible with Nagios.
 
+#### add_description
+
+`add_description` allows you to specify extended description and troubleshooting
+information for any check which has been added via `add_check`.
+
+Currently these are not returned via the JSON endpoint, but are available
+via the HTML status page.
+
+Description information is parsed by kramdown for display. Refer to the
+[kramdown style guide](http://kramdown.rubyforge.org/quickref.html) for
+usage information.
+
+```ruby
+AppStatus::CheckCollection.configure do |c|
+
+  c.add_check('some_service') do
+    [:critical, 'what is going on']
+  end
+  c.add_description 'some_service', <<-EOF
+some_service failures indicate that some_service is going wrong.
+
+this is handy since nagios really requires brief output, but sometimes you need
+more space to explain what a check is.
+
+think of it as the answer to the problem of "That guy is on vaction, but his
+app is raising alarms. WTF do I do?"
+  EOF
+
+end
+```
+
 Keep in mind that anyone who hits your status URL can cause your checks to run,
 so if they expose sensitive data or are a potential DOS vector you should
 probably protect them with some kind of authentication.

data/app/models/app_status/check_collection.rb

@@ -4,6 +4,9 @@ module AppStatus
 
   class CheckCollection
 
+    include Enumerable
+
+    @@check_descriptions = HashWithIndifferentAccess.new
     @@checks = HashWithIndifferentAccess.new
 
     # Add checks here.
@@ -28,89 +31,117 @@ module AppStatus
     end
 
     def self.clear_checks!
+      @@check_descriptions = HashWithIndifferentAccess.new
       @@checks = HashWithIndifferentAccess.new
     end
 
-    def initialize
-      @valid_status = {
+    def self.valid_status_map
+      {
               ok: 0,
          warning: 1,
         critical: 2,
          unknown: 3
-      }.freeze
-
-      @check_results = HashWithIndifferentAccess.new
-      @eval_finished = nil
-      @eval_time = 0
+      }
     end
 
     # add the results of a check to the collection.
     # this should describe the health of some portion of your application
+    # The check block you supply should return a status value, or a
+    # [:status, 'details'] array.
     #
     # example:
-    #   value = some_service_check
-    #   c.add(:name => 'some_service', :status => :ok, :details => value)
+    #   AppStatus::CheckCollection.add_check('some_service') do
+    #     [:ok, 'these are optional details']
+    #   end
     def self.add_check(name, &block)
       raise ArgumentError, ":name option is required." if ! name
-      # raise ArgumentError, ":status option is required." if ! options[:status]
 
       name = name.to_sym
       raise ArgumentError, "Check name '#{name}' has already been added." if @@checks.keys.include?(name.to_s)
       raise ArgumentError, "No check defined for '#{name}'." if ! block_given?
 
-      @@checks[name] = block
+      item = CheckItem.new(name)
+      item.proc = block
+      @@checks[name] = item
     end
 
-    def valid_status?(status)
-      @valid_status.keys.include?(status)
+    # add a long-form description of a check
+    # service must have already been added via add_check.
+    #
+    # example:
+    #   AppStatus::CheckCollection.configure do |c|
+    #     c.add_check('some_service') do
+    #       [:ok, 'these are optional details']
+    #     end
+    #     c.add_decription 'some_service', <<-EOF
+    # some_service is pretty easy to understand.
+    # it always works, no matter what.
+    # but if it were **harder to comprehend** you
+    # could add markdown here to explain what it is
+    # and what to do if it starts failing.
+    #     EOF
+    #
+    def self.add_description(name, markdown)
+      raise ArgumentError, "Check '#{name}' is not defined." if ! @@checks[name]
+      @@checks[name].description = markdown
+    end
+
+
+
+    attr_reader :finished, :ms, :status, :status_code
+
+
+    def initialize
+      reset
+    end
+
+    def reset
+      @finished = nil
+      @ms = 0
+      @status = :ok
+      @status_code = self.class.valid_status_map[@status]
+      @@checks.each {|key,check| check.reset }
+    end
+
+    def each
+      @@checks.each {|name,check| yield check }
     end
 
     # run the checks added via configure
     # results of the checks are available via as_json
     def evaluate!
       eval_start = Time.now
-      @check_results = {}
-      @@checks.each do |name,proc|
-        check_start = Time.now
-        status, details = proc.call
-        check_time = (Time.now - check_start) * 1000
-
-        status = status.to_sym if status
-        details = details.to_s if details
-
-        if ! valid_status?(status)
-          details = "Check returned invalid status '#{status}'. #{details}".strip
-          status = :unknown
-        end
-        @check_results[name] = {
-          status: status,
-          status_code: @valid_status[status],
-          details: details,
-          ms: check_time.to_i
-        }
+
+      reset
+
+      @@checks.each do |name,check|
+        @status_code = [check.evaluate!, @status_code].max
       end
 
-      @eval_finished = Time.now.utc
-      @eval_time = (Time.now - eval_start) * 1000
-    end
+      @finished = Time.now.utc
+      @ms = (Time.now - eval_start) * 1000
 
-    def as_json
-      if @check_results.size == 0
-        max_status = :unknown
-        max_int = @valid_status[max_status]
+      if @@checks.size == 0
+        @status = :unknown
+        @status_code = self.class.valid_status_map[@status]
       else
-        max_int = @check_results.inject([]){ |memo,val| memo << val[1][:status_code]; memo}.max
-        max_status = @valid_status.invert[max_int]
+        @status = self.class.valid_status_map.invert[@status_code]
       end
+    end
 
+    def as_hash
       HashWithIndifferentAccess.new({
-        status: max_status,
-        status_code: max_int,
-        ms: @eval_time.to_i,
-        finished: @eval_finished.iso8601,
-        checks: @check_results
+        status: @status,
+        status_code: @status_code,
+        ms: @ms.to_i,
+        finished: @finished.iso8601,
+        checks: @@checks.inject({}) {|memo,(name,check)| memo[name] = check.as_hash; memo}
       })
     end
+
+    def as_json
+      as_hash
+    end
   end
 
 end

data/app/models/app_status/check_item.rb

@@ -0,0 +1,58 @@
+require 'kramdown'
+
+module AppStatus
+  class CheckItem
+    attr_reader :name, :status, :status_code, :details, :ms
+    attr_accessor :proc, :description
+
+    def initialize(name)
+      @name = name
+      @proc = nil
+      @description = ''
+
+      reset
+    end
+
+    def reset
+      @result = {}
+    end
+
+    def valid_status?(status)
+      CheckCollection.valid_status_map.keys.include?(status)
+    end
+
+    def evaluate!
+      check_start = Time.now
+      status, details = @proc ? @proc.call : [:unknown, "Check is not configured."]
+      check_time = (Time.now - check_start) * 1000
+
+      status = status.to_sym if status
+      details = details.to_s if details
+
+      if ! valid_status?(status)
+        details = "Check returned invalid status '#{status}'. #{details}".strip
+        status = :unknown
+      end
+
+      @status = status
+      @status_code = CheckCollection.valid_status_map[@status]
+      @details = details
+      @ms = check_time.to_i
+
+      return @status_code
+    end
+
+    def as_hash
+      {
+        status: @status,
+        status_code: @status_code,
+        details: @details,
+        ms: @ms
+      }
+    end
+
+    def html_description
+      Kramdown::Document.new(@description).to_html
+    end
+  end
+end

data/app/views/app_status/status/index.html.erb

@@ -0,0 +1,32 @@
+<div class="app_status">
+
+  <h1 class="<%= @checks.status %>">Current Status : <%= @checks.status %></h1>
+
+  <table>
+  <% @checks.each do |check| %>
+    <tr class="check <%= check.status %> <%= check.name %>" data-check-name="<%= check.name %>">
+      <td class="status"><%= check.status %></td>
+      <td class="name"><%= check.name %></td>
+      <td class="details"><%= check.details %></td>
+      <td class="ms"><%= check.ms %>ms</td>
+    </tr>
+    <% if check.description.present? -%>
+      <tr class="<%= check.name %> description" style="display: none;">
+        <td colspan="4">
+          <%= check.html_description.html_safe %>
+        </td>
+      </tr>
+    <% end %>
+  <% end %>
+  </table>
+
+</div>
+
+<script>
+  $(function() {
+    $('.app_status .check').click(function() {
+      var checkName = $(this).data('check-name');
+      $('.'+checkName+'.description').fadeToggle();
+    })
+  })
+</script>

data/bin/kramdown

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'kramdown' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('kramdown', 'kramdown')

data/lib/app_status/version.rb

@@ -1,3 +1,3 @@
 module AppStatus
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/app_status.rb

@@ -1,5 +1,4 @@
 require "app_status/engine"
-require "haml"
 
 module AppStatus
 end

data/spec/dummy/config/initializers/app_status.rb

@@ -0,0 +1,28 @@
+AppStatus::CheckCollection.configure do |c|
+  c.add_check('ok') do
+    [:ok, "looks good"]
+  end
+  c.add_description 'ok', <<-EOF
+### OK Check
+
+This check is always ok.
+  EOF
+
+  c.add_check('crit') do
+    [:critical, "fail"]
+  end
+  c.add_description 'crit', <<-EOF
+### Critical Check
+
+This check is always critical.
+  EOF
+
+  c.add_check('no_description') do
+    [:ok, 'check has no longer description']
+  end
+
+  c.add_check('no_details') do
+    :ok
+  end
+  c.add_description('no_details', 'check only returns a status.')
+end

data/spec/dummy/config/routes.rb

@@ -1,4 +1,3 @@
 Rails.application.routes.draw do
-
   mount AppStatus::Engine => "/status"
 end