rackamole 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2009-11-11
+
+* 1 major enhancement
+  * Birthday!

data/README.txt

@@ -0,0 +1,93 @@
+== RackAMole
+  Your web application observer...
+  
+== DESCRIPTION:
+
+The MOle is a rack application that monitors user interactions with your web site. We are not 
+talking about counting page hits here. The MOle tracks all the information available to capture
+the essence of a user interaction with your application. Using the MOle, you are able to see
+which feature is a hit or a bust. As an added bonus, the MOle also track performance and exceptions 
+that might have escaped your test suites or alpha env. To boot your managers will love you for it! 
+
+Whether you are releasing a new application or improving on an old one, it is always a good thing 
+to know if anyone is using your application and if they are, how they are using it. 
+What features are your users most fond of and which features find their way into the abyss? 
+You will be able to rapidly assess whether or not your application is a hit and if
+your coolest features are thought as such by your users. You will be able to elegantly record user
+interactions and leverage these findings for the next iteration of your application. 
+
+== PROJECT INFORMATION
+
+* Developer:  Fernand Galiana [liquidrail.com]
+* Forum:      http://groups.google.com/group/rackamole
+* Git:        git://github.com/derailed/rackamole.git
+
+== FEATURES:
+
+* Monitors Rails or Sinatra applications
+* Captures the essence of the request as well as user information
+* Tracks performance issues based on your latency threshold
+* Tracks exceptions that might occurred during a request
+
+== REQUIREMENTS:
+
+* Logging
+* Hitimes
+* MongoDb
+
+== INSTALL:
+
+* sudo gem install rackamole
+
+  NOTE: The gem is hosted on gemcutter.com - please update your gem sources if not 
+  already specified
+  
+== USAGE:
+
+=== Rails applications
+  
+  Edit your environment.rb file and add the following lines:
+  
+  require 'rackamole'
+  config.middleware.use Rack::Mole, { :app_name => "My Cool App", :user_key => :user_name }
+
+  This instructs the mole to start logging information to the console and look for the user name 
+  in the session using the :user_name key. There are other options available, please take a look
+  at the docs for more information.
+  
+=== Sinatra Applications
+
+  Add the following lines in the config section and smoke it...
+  
+  require 'rackamole'
+  configure do
+    use Rack::Mole, { :app_name => "My Sinatra App", :user_key => :user_name }
+  end
+  
+  This assumes that you have session enabled to identify a user if not the mole will log the user
+  as 'Unknown'
+  
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 FIXME (different license?)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,28 @@
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'rackamole'
+
+task :default => 'spec:run'
+
+PROJ.name            = 'rackamole'
+PROJ.authors         = 'Fernand Galiana'
+PROJ.email           = 'fernand.galiana@gmail.com'
+PROJ.url             = 'http://rackamole.liquidrail.com'
+PROJ.version         = Rackamole::VERSION
+PROJ.spec.opts      << '--color'
+PROJ.ruby_opts       = %w[-W0]
+
+# Dependencies
+depend_on "logging"      , ">= 1.2.2"
+depend_on "hitimes"      , ">= 1.0.3"
+depend_on "mongodb-mongo", ">= 0.14.1"

data/aaa.txt

@@ -0,0 +1,36 @@
+== Problem
+
+ All tests green, CC happy, Customers are creaming their pants reading their Cucumber scenarios. App is in production on bitch'n servers.
+ Top of the world right?
+
+== Questions
+
+ Is the app being used ? How many customers hit it in the past week ? What are the most/least used features ? Why?
+ Are my cool ajax callbacks silently crapping out? Are there any perf issues ? ... ?
+
+== Got Mole ? (http://github.com/derailed/rackamole)
+
+The MOle is a rack component that traps your application requests and captures the associated context information.
+By intercepting the request, this rack app can gather calling context, alert you of latency issues on certain operation and
+also trap any exceptions that may have emerged in the request cycle. The MOle is currently able to either store this information
+in your log files or in a mongo instance for later processing.
+
+== Options 
+  
+  <tt>:app_name</tt> - The name of the application [Default: Moled App]
+  <tt>:environment</tt> - The environment for the application ie :environment => RAILS_ENV
+  <tt>:moleable</tt> - Enable/Disable the MOle [Default:true]
+  <tt>:store </tt> - The storage instance ie log file or database [Default:stdout]
+  <tt>:user_key</tt> - If session is enable, the session key for the user name or user_id. ie :user_key => :user_name 
+
+== Rails
+
+  require 'rackamole'
+  config.middleware.use Rack::Mole, { :app_name => "My Cool App", :user_key => :user_name }
+
+== Sinatra
+
+  require 'rackamole'
+  configure do
+     use Rack::Mole, { :app_name => "My Sinatra App", :user_key => :user_name }
+  end

data/bin/rackamole

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib rackamole]))
+
+# Put your code here
+
+# EOF

data/lib/rackamole.rb

@@ -0,0 +1,46 @@
+module Rackamole
+
+  # :stopdoc:
+  VERSION = '0.0.1'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end
+
+Rackamole.require_all_libs_relative_to(__FILE__)

data/lib/rackamole/interceptor.rb

@@ -0,0 +1,20 @@
+module Rackamole
+  module Interceptor
+    
+    # In order for the mole to trap framework exception, you must include
+    # the interceptor in your application controller.
+    # ie include Wackamole::Interceptor
+    def self.included( base )
+      base.send( :alias_method_chain, :rescue_action_in_public, :mole )
+    end
+    
+    private
+          
+      # Instructs the mole to trap the framework exception
+      def rescue_action_in_public_with_mole( exception )
+        # Stuff the exception in the env for mole rack retrieval
+        request.env['mole.exception'] = exception
+        rescue_action_in_public_without_mole( exception )
+      end
+  end
+end

data/lib/rackamole/logger.rb

@@ -0,0 +1,121 @@
+require 'logging'
+require 'forwardable'
+
+module Rackamole
+  class Logger
+    class ConfigurationError < StandardError ; end  #:nodoc:
+
+    attr_reader :log # here for testing, don't really use it.
+
+    extend Forwardable
+    def_delegators :@log, :debug, :warn, :info, :error, :fatal 
+    def_delegators :@log, :level=, :level
+    def_delegators :@log, :debug?, :warn?, :info?, :error?, :fatal?  
+    def_delegators :@log, :add, :clear_appenders
+
+    # there are more options here than are typically utilized for the
+    # logger, they are made available if someone wants to utilize
+    # them directly.  
+    #
+    def self.default_options #:nodoc:
+      @default_options ||= {
+
+        # log event layout pattern
+        #    YYYY-MM-DDTHH:MM:SS 12345 LEVEL LoggerName : The Log message
+        #
+        :layout_pattern       => '%d %5p %5l %c : %m\n'.freeze  ,
+        :logger_name          => 'Mole'                         ,
+        :additive             => true                           ,
+
+        # log file configuration options
+        #   age        -> how often to rotate the logs if a file is used
+        #   keep_count -> how many of the log files to keep
+        :log_level            => :info          ,
+        :log_file             => $stdout        ,
+        :log_file_age         => 'daily'.freeze ,
+        :log_file_keep_count  => 7              ,
+
+        # email logging options
+        #   buffsize -> number of log events used as a threshold to send an
+        #               email.  If that is not reached before the program
+        #               exists then the at_exit handler for logging will flush
+        #               the log to smtp.
+        :email_alerts_to      => nil    ,
+        :email_alert_level    => :error ,
+        :email_alert_server   => nil    ,
+        :email_alert_buffsize => 200    ,
+      }
+    end
+
+    # create a new logger
+    #
+    def initialize( opts = {} )
+      @options = ::Rackamole::Logger.default_options.merge(opts)
+      @log     = ::Logging::Logger[@options[:logger_name]]
+      @layout  = ::Logging::Layouts::Pattern.new( { :pattern => @options[:layout_pattern] } )
+     
+      # add appenders explicitly, since this logger may already be defined and
+      # already have loggers
+      @appenders = []
+      @appenders << log_file_appender if @options[:log_file]
+      @appenders << email_appender if @options[:email_alerts_to]
+
+      @log.appenders = @appenders
+      @log.level = @options[:log_level]
+      @log.additive = @options[:additive]
+    end
+
+    # File appender, this is either an IO appender or a RollingFile appender
+    # depending on if an IO object or a String is passed in.
+    #
+    # a configuration error is raised in any other circumstance
+    def log_file_appender  #:nodoc:
+      appender_name = "#{@log.name}-log_file_appender"
+      if String === @options[:log_file] then 
+        ::Logging::Appenders::RollingFile.new( appender_name, 
+                                             { :layout    => @layout,
+                                               :filename  => @options[:log_file],
+                                               :age       => @options[:log_file_age],
+                                               :keep      => @options[:log_file_keep_count],
+                                               :safe      => true  # make sure log files are rolled using lockfile
+        })
+      elsif @options[:log_file].respond_to?(:print) then
+        ::Logging::Appenders::IO.new( appender_name, @options[:log_file],  :layout => @layout  )
+      else
+        raise ConfigurationError, "Invalid :log_file option [#{@options[:log_file].inspect}]"
+      end
+    end
+
+    # an email appender that uses :email_alerts_to option to send emails to.
+    # :email_alerts_to can either be a singe email address as a string or an
+    # Array of email addresses.  Any other option for :email_alerts_to is
+    # invalid and raises an error.
+    #
+    def email_appender #:nodoc:
+      email_alerts_to = [ @options[:email_alerts_to] ].flatten.reject { |x| x == nil }
+      raise ConfigurationError, "Invalid :email_alerts_to option [#{@options[:email_alerts_to].inspect}]" unless email_alerts_to.size > 0
+      ::Logging::Appenders::Email.new("#{@log.name}-email_appender",
+                                      {
+                                        :level    => @options[:email_alert_level],
+                                        :layout   => @layout,
+                                        :from     => "#{@log.name}",
+                                        :to       => "#{email_alerts_to.join(', ')}",
+                                        :subject  => "Logging Alert from #{@log.name} on #{ENV['HOSTNAME']}",
+                                        :server   => @options[:email_alert_server],
+                                        :buffsize => @options[:email_alert_buffsize], # lines 
+      })
+    end
+
+    # create a new logger thi logger has no options when it is created although 
+    # more can be added with the logger instance that is returned.  The
+    # appenders of the current instance of Logger will be set on the new
+    # logger and the options of the current logger will be applied
+    def for( arg ) #:nodoc:
+      new_logger           = ::Logging::Logger[arg]
+      new_logger.level     = @options[:level]
+      new_logger.additive  = @options[:additive]
+      new_logger.appenders = @appenders
+      return new_logger
+    end     
+  end
+end

data/lib/rackamole/mole.rb

@@ -0,0 +1,134 @@
+require 'hitimes'
+require 'mongo/util/ordered_hash'
+require 'json'
+
+module Rack
+  class Mole
+    
+    # Initialize The Mole with the possible options
+    # <tt>:app_name</tt>    - The name of the application [Default: Moled App]
+    # <tt>:environment</tt> - The environment for the application ie :environment => RAILS_ENV
+    # <tt>:perf_threshold</tt> - Any request taking longer than this value will get moled [Default: 10]    
+    # <tt>:moleable</tt>    - Enable/Disable the MOle [Default:true]
+    # <tt>:store</tt>       - The storage instance ie log file or mongodb [Default:stdout]
+    # <tt>:user_key</tt>    - If session is enable, the session key for the user name or user_id. ie :user_key => :user_name 
+    def initialize( app, opts={} )
+      @app = app
+      init_options( opts )
+    end
+            
+    def call( env )      
+      # Bail if application is not moleable
+      return @app.call( env ) unless moleable?
+      
+      response = nil
+      elapsed = Hitimes::Interval.measure do
+        response = @app.call( env )
+      end
+      @store.mole( mole_info( env, elapsed ) )
+      response
+    end 
+
+  # ===========================================================================  
+  private
+       
+    # Load up configuration options
+    def init_options( opts )
+      options         = default_options.merge( opts )      
+      @environment    = options[:environment]
+      @perf_threshold = options[:perf_threshold]
+      @moleable       = options[:moleable]
+      @app_name       = options[:app_name]
+      @user_key       = options[:user_key]
+      @store          = options[:store]      
+    end
+    
+    # Mole default options
+    def default_options
+      { 
+        :app_name       =>  "Moled App",
+        :moleable       =>  true,
+        :perf_threshold =>  10,
+        :store          =>  Rackamole::Store::Log.new
+      }
+    end
+               
+    # Extract interesting information from the request
+    def mole_info( env, elapsed )      
+      request     = Rack::Request.new( env )
+      session     = env['rack.session']      
+      route       = get_route( request )
+      info        = OrderedHash.new
+      ip, browser = identify( env )
+      user_id     = nil
+      user_name   = nil
+           
+      if session and @user_key
+        if @user_key.instance_of? Symbol
+          user_name = session[@user_key]
+        elsif @user_key.instance_of? Hash
+          user_id  = session[ @user_key[:session_key] ]
+          if @user_key[:extractor]
+            user_name = @user_key[:extractor].call( user_id )
+          end
+        end
+      end
+            
+      info[:app_name]     = @app_name
+      info[:environment]  = @environment if @environment
+      info[:user_id]      = user_id      if user_id
+      info[:user_name]    = user_name || "Unknown"
+      info[:ip]           = ip
+      info[:browser]      = browser
+      info[:request_time] = elapsed if elapsed
+      info[:perf_issue]   = (elapsed and elapsed > @perf_threshold)
+      info[:url]          = request.url
+      info[:method]       = env['REQUEST_METHOD']
+      info[:path]         = request.path
+      info[:route_info]   = route if route
+      
+      # Dump request params
+      unless request.params.empty?
+        info[:params] = OrderedHash.new
+        request.params.keys.sort.each { |k| info[:params][k.to_sym] = request.params[k].to_json }
+      end
+            
+      # Dump session var
+      if session and !session.empty?
+        info[:session] = OrderedHash.new 
+        session.keys.sort{ |a,b| a.to_s <=> b.to_s }.each { |k| info[:session][k.to_sym] = session[k].to_json }
+      end
+      
+      # Check if an exception was raised. If so consume it and clear state
+      exception = env['mole.exception']
+      if exception
+        info[:ruby_version]   = %x[ruby -v]
+        info[:stack]          = trim_stack( exception )
+        env['mole.exception'] = nil
+      end
+      
+      info
+    end
+        
+    # Trim stack trace
+    def trim_stack( boom )
+      boom.backtrace[0...4]
+    end
+
+    # Identify request ie ip and browser configuration   
+    def identify( request_env )
+      return request_env['HTTP_X_FORWARDED_FOR'] || request_env['REMOTE_ADDR'], request_env['HTTP_USER_AGENT']
+    end
+            
+    # Checks if this application is moleable
+    def moleable?
+      @moleable
+    end
+    
+    # Fetch route info if any...
+    def get_route( request )
+      return nil unless defined?( RAILS_ENV )      
+      ::ActionController::Routing::Routes.recognize_path( request.path, {:method => request.request_method } )
+    end
+  end
+end