derailed-mole 1.0.10

data/lib/mole/e_mole_helper.rb

@@ -0,0 +1,2 @@
+module Mole::EMoleHelper
+end

data/lib/mole/logger.rb

@@ -0,0 +1,134 @@
+require 'logging'
+require 'forwardable'
+
+module Mole
+  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 = ::Mole::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 
+    
+    # mole the bastard - create an entry into MOle log file
+    def log_it( context, feature, user_id, args )
+      args    ||= "no args"                           
+      user_id ||= "N/A"             
+      ip_addr, browser_type = MoleLog.log_details( context )
+      info = []
+      args.keys.sort { |a,b| a.to_s <=> b.to_s }.each { |k| info << "#{k}=>#{args[k]}" }
+      buff = ""
+      buff << "[#{ip_addr}/#{browser_type}]--" if ip_addr and browser_type
+      buff << "#{context.class.name}(#{feature}) --- #{user_id} -> #{info.join( ', ' ) }"
+      self.info(  buff )
+    end
+  end
+end

data/lib/mole/models/mole_feature.rb

@@ -0,0 +1,58 @@
+# Feature model - Tracks the various application features in the db.
+class MoleFeature < ActiveRecord::Base
+  has_many :mole_logs    
+        
+  class << self     
+    # famous constants...  
+    def all()         "ALL"        ; end
+    def exception()   "Exception"  ; end
+    def performance() "Performance"; end  
+    
+    # find performance feature
+    def find_performance_feature( app_name )
+      find_or_create_feature( performance, app_name )
+    end
+                                 
+    # find exception feature
+    def find_exception_feature( app_name )         
+      find_or_create_feature( exception, app_name )
+    end
+       
+    # Find the all feature ( wildcard feature for given app )
+    def find_all_feature( app_name )
+      find_or_create_feature( all, app_name )
+    end
+                     
+    # Find all the MOled applications                                       
+    def find_moled_application_names
+      res = find( :all, 
+                  :select => "distinct( app_name )", 
+                  :order  => "name asc" )            
+      res.map(&:app_name)             
+    end
+          
+    # Finds all the features available for a given application
+    def find_features( app_name )       
+      # Creates the all feature if necessary    
+      find_all_feature( app_name )
+      find( :all, 
+            :conditions => ["app_name = ?", app_name], 
+            :select     => "id, name, context", 
+            :order      => "name asc" )      
+    end
+      
+    # locates an existing feature or create a new one if it does not exist.
+    def find_or_create_feature( name, app_name, ctx_name=nil )
+      if name.nil? or name.empty? 
+        ::Mole.logger.error( "--- MOLE ERROR - Invalid feature. Empty or nil" ) 
+        return nil
+      end                          
+      if ctx_name      
+        res = find_by_name_and_context_and_app_name( name, ctx_name, app_name )
+      else
+        res = find_by_name_and_app_name( name, app_name )
+      end
+      res || create(:name => name,:context => ctx_name, :app_name => app_name )
+    end   
+  end
+end               

data/lib/mole/models/mole_log.rb

@@ -0,0 +1,31 @@
+# Log Model - Tracks and record user interactions with various features
+# This will make it easy to write an app on top on the MOle to track a 
+# particular application utilization.                     
+class MoleLog < ActiveRecord::Base                                             
+  belongs_to :mole_feature  
+    
+  class << self                                               
+    # mole the bastard - create db entry into mole logs
+    def log_it( context, feature, user_id, args )
+      args    ||= "no args"                           
+      user_id ||= "N/A"             
+      ip_addr, browser_type = log_details( context )      
+      MoleLog.create( :mole_feature => feature, 
+                      :user_id      => user_id, 
+                      :host_name    => `hostname`,
+                      :params       => args.to_yaml,
+                      :ip_address   => ip_addr, 
+                      :browser_type => browser_type )
+    end               
+    
+    # extract orginating ip address and browser type                                               
+    def log_details( context ) #:nodoc:
+      ip_addr, browser_type = nil
+      if context.respond_to? :request                                                                     
+        ip_addr, browser_type = context.request.env['REMOTE_ADDR'], context.request.env['HTTP_USER_AGENT'] 
+      end
+      return ip_addr, browser_type
+    end            
+  end          
+  
+end

data/lib/mole/module.rb

@@ -0,0 +1,292 @@
+# =============================================================================
+# Extends module to inject interceptors                                        
+# =============================================================================
+require 'benchmark'
+require 'active_support'
+
+class Module              
+  # intercepts a collection of features and wrap performance check based on the
+  # specified :perf_threshold. The trigger defaults to 5 secs if not explicitly set.
+  #
+  # Example:   
+  #
+  #   MyClass.mole_perf do |context, action, elapsed_time, ret, block, *args|                            
+  #     Mole::DbMole.perf_it( context.session[:user_id], 
+  #                           :controller   => context.class.name,
+  #                           :action       => action,                           
+  #                           :elapsed_time => "%3.3f" % elapsed_time )
+  #   end  
+  #
+  # This will trap all public methods on the MyClass that takes more than 
+  # :perf_threshold to complete. You can override this default by using the option
+  # :features => [m1,m2,...]. This is handy for controller moling rails
+  # and merb context.
+  # 
+  # If you elect not to use the block form of the call, you can pass in the
+  # following arguments to the option hash:
+  # <tt>:interceptor</tt>::   The class name of your interceptor class
+  # <tt>:method</tt>::        The name of the method to callback the interceptor on
+  #                           once a perf condition has been trapped.
+  def mole_perf( opts={}, &interceptor )    
+    opts[:interceptor] ||= interceptor
+    opts[:method]      ||= :call             
+    opts[:features]    ||= instance_methods( false )
+    opts[:features].each do |feature|  
+      wrap feature
+      perf_mole_filters[feature.to_s] << [opts[:interceptor], opts[:method]]
+    end    
+  end
+         
+  # monitors a collections of features and wrap rescue logic to trap unchecked 
+  # exceptions. You can handle to trap differently by either logging the event
+  # in the db or sending out email/IM notification.
+  #
+  # Example:   
+  #
+  #   MyClass.mole_unchecked do |context, action, boom, block, *args|
+  #     Mole::Moler.check_it( context.session[:user_id], 
+  #                          :controller => context.class.name,  
+  #                          :action     => action,
+  #                          :boom       => boom )    
+  #   end  
+  #
+  # This will wrap all public instance methods on MyClass. If any of these methods
+  # raises an unchecked exception, the MOle will surface the condition. 
+  # This call also takes in a :features option to specify a list of methods if the
+  # default instance methods is not suitable, you can pass in a collection of methods
+  # that you wish to mole. This is handy in the case of Rails/Merb where conveniences
+  # are provided to gather controller actions
+  # 
+  # If you elect not to use the block form of the call, you can pass in the
+  # following arguments to the option hash:
+  # <tt>:interceptor</tt>::   The class name of your interceptor class
+  # <tt>:method</tt>::        The name of the method to callback the interceptor on
+  #                           once an exception condition has been trapped.   
+  def mole_unchecked( opts={}, &interceptor )    
+    opts[:interceptor] ||= interceptor
+    opts[:method]      ||= :call             
+    opts[:features]    ||= instance_methods( false )
+    opts[:features].each do |feature|  
+      wrap feature
+      unchecked_mole_filters[feature.to_s] << [opts[:interceptor], opts[:method]]
+    end
+  end
+
+  # intercepts a feature before the feature is called. During the callback
+  # you will have access to the object ( context ) on which the call is intercepted,
+  # as well as the arguments/block, the feature was issued with.
+  #
+  # Example:   
+  #
+  #   MyClass.mole_before( :feature => :blee ) do |context, feature, block, *args|
+  #     Mole::Moler.mole_it( context, feature, context.session[:user_id], 
+  #                         :args => args )
+  #   end  
+  #
+  # This will wrap the method blee with a before interceptor. Before the blee call
+  # is issued on MyClass, control will be handed to the before interceptor. 
+  # 
+  # Options:
+  # <tt>:feature</tt>::       The name of the feature to be intercepted  
+  # If you elect not to use the block form of the call, you can pass in the
+  # following arguments to the option hash:  
+  # <tt>:interceptor</tt>::   The class name of your interceptor class. If no interceptor block is specified
+  # <tt>:method</tt>::        The name of the method to callback the interceptor on
+  #                           once an exception condition has been trapped.     
+  def mole_before(opts={}, &interceptor)  
+    raise "Missing :feature option" if opts[:feature].nil? or opts[:feature].to_s.empty?
+    opts[:interceptor] ||= interceptor
+    opts[:method] ||= :call
+    feature = opts[:feature].to_s
+    if before_mole_filters[feature].empty?
+      wrap feature 
+      before_mole_filters[feature] << [opts[:interceptor], opts[:method]]
+    end
+  end
+
+  # intercepts a feature after the feature is called. During the callback
+  # you will have access to the object ( context ) on which the call is intercepted,
+  # as well as the arguments/block and return values the feature was issued with.
+  #
+  # Example:   
+  #
+  #   MyClass.mole_after( :feature => :blee ) do |context, feature, ret_val, block, *args|
+  #     Mole::Moler.mole_it( context, feature, context.session[:user_id], 
+  #                         :args => args )
+  #   end  
+  #
+  # This will wrap the method blee with an after interceptor. After the blee call
+  # is issued on MyClass, control will be handed to the after interceptor. 
+  # 
+  # Options:
+  # <tt>:feature</tt>::       The name of the feature to be intercepted  
+  # <tt>:interceptor</tt>::   The class name of your interceptor class. If no interceptor block is specified
+  # <tt>:method</tt>::        The name of the method to callback the interceptor on
+  #                           once an exception condition has been trapped.     
+  def mole_after(opts = {}, &interceptor)
+    raise "Missing :feature option" if opts[:feature].nil? or opts[:feature].to_s.empty?    
+    opts[:interceptor] ||= interceptor
+    opts[:method] ||= :call
+    feature = opts[:feature].to_s
+    if after_mole_filters[feature].empty?
+      wrap feature 
+      after_mole_filters[feature] << [opts[:interceptor], opts[:method]]
+    end
+  end
+   
+  # ---------------------------------------------------------------------------
+  # Dumps moled feature info       
+  def mole_dump( msg=nil )
+    puts "\n------------------------------------------------------------------"
+    puts "From #{msg}" if msg
+    puts "MOle Info for class <- #{self} ->"
+    puts "\nBefore filters"
+    before_mole_filters.keys.sort.each { |k| puts "\t#{k} --> #{before_mole_filters[k]}" }
+    puts "\nAfter filters"
+    after_mole_filters.keys.sort.each { |k| puts "\t#{k} --> #{after_mole_filters[k]}" }
+    puts "\nUnchecked filters"
+    unchecked_mole_filters.keys.sort.each { |k| puts "\t#{k} --> #{unchecked_mole_filters[k]}" }
+    puts "\nPerf filters"
+    perf_mole_filters.keys.sort.each { |k| puts "\t#{k} --> #{perf_mole_filters[k]}" }    
+    puts "---------------------------------------------------------------------\n"    
+  end
+      
+  # ===========================================================================
+  private
+
+    # Strip out all invalid punctuation
+    def clean_method_name( method )
+      return method.to_s.sub(/([?!=])$/, ''), $1
+    end
+
+    # Clear MOle state for this class # Used for testing only
+    def mole_clear!
+      @before_mole_filters = nil  
+      @after_mole_filters = nil  
+      @perf_mole_filters = nil  
+      @unchecked_mole_filters = nil                    
+    end  
+    
+  # ===========================================================================
+  public
+    
+    # -------------------------------------------------------------------------
+    # Holds before filters
+    def before_mole_filters #:nodoc:    
+      @before_mole_filters ||= Hash.new{ |h,k| h[k] = [] }
+    end
+
+    # -------------------------------------------------------------------------
+    # Holds after filters
+    def after_mole_filters #:nodoc:
+      @after_mole_filters ||= Hash.new{ |h,k| h[k] = [] }
+    end
+  
+    # -------------------------------------------------------------------------
+    # Holds perf around filters   
+    def perf_mole_filters #:nodoc:
+      @perf_mole_filters ||= Hash.new{ |h,k| h[k] = []} 
+    end
+
+    # -------------------------------------------------------------------------
+    # Holds unchecked exception filters   
+    def unchecked_mole_filters #:nodoc:
+      @unchecked_mole_filters ||= Hash.new{ |h,k| h[k] = []} 
+    end
+        
+    # -------------------------------------------------------------------------        
+    # Attempt to find singleton class method with given name 
+    # TODO Figure out how to get method for static signature...
+    # def find_public_class_method(method)                        
+    #   singleton_methods.each { |name| puts "Looking for #{method}--#{method.class} -- #{name}#{name.class}";return name if name == method }
+    #   nil
+    # end
+  
+    # -------------------------------------------------------------------------
+    # Wrap method call                                
+    # TODO Add support for wrapping class methods ??
+    def wrap( method ) #:nodoc:
+      return if wrapped?( method )  
+      begin
+        between = instance_method( method )
+      rescue
+        # between = find_public_class_method( method )
+        raise "Unable to find moled feature `#{method}" unless(between)
+      end
+      method_name, punctuation = clean_method_name( method )
+      code = <<-code
+        def #{method_name}_with_mole#{punctuation} (*a, &b)
+          key                 = '#{method}'
+          klass               = self.class
+          between             = klass.wrapped[key]
+          ret_val             = nil
+          klass.apply_before_filters( klass.before_mole_filters[key], self, key, *a, &b ) if klass.before_mole_filters[key]
+          begin                                          
+            elapsed = Benchmark::realtime do 
+              ret_val = between.bind(self).call( *a, &b ) 
+            end   
+            klass.apply_perf_filters( elapsed, klass.perf_mole_filters[key], self, key, ret_val, *a, &b ) if klass.perf_mole_filters[key]
+          rescue => boom   
+            klass.apply_unchecked_filters( boom, klass.unchecked_mole_filters[key], self, key, *a, &b ) if klass.unchecked_mole_filters[key]
+            raise boom            
+          end                                                                 
+          klass.apply_after_filters( klass.after_mole_filters[key], self, key, ret_val, *a, &b ) if klass.after_mole_filters[key]
+          ret_val
+        end
+      code
+   
+      module_eval                code               
+      alias_method_chain method, "mole" 
+      wrapped[method.to_s]       = between
+    end    
+   
+    def apply_before_filters( filters, clazz, key, *a, &b )          #:nodoc:              
+      begin
+        filters.each { |r,m| r.send( m, clazz, key, b, *a ) }
+      rescue => ca_boom
+        ::Mole.logger.error ">>> MOle Failure: Before-Filter -- " + ca_boom
+        ca_boom.backtrace.each { |l| ::Mole.logger.error l }           
+      end    
+    end
+                       
+    def apply_after_filters( filters, clazz, key, ret_val, *a, &b )   #:nodoc:              
+      begin  
+        filters.each { |r,m| r.send( m, clazz, key, ret_val, b, *a ) }
+      rescue => ca_boom    
+        ::Mole.logger.error ">>> MOle Failure: After-Filter -- " + ca_boom
+        ca_boom.backtrace.each { |l| ::Mole.logger.error l }           
+      end    
+    end
+                       
+    def apply_perf_filters( elapsed, filters, clazz, key, ret_val, *a, &b )       #:nodoc:
+      begin
+        if ( elapsed >= Mole.perf_threshold  )
+          filters.each { |r,m| r.send( m, clazz, key, elapsed, ret_val, b, *a ) }            
+        end
+      rescue => ca_boom
+        ::Mole.logger.error ">>> MOle Failure: Perf-Filter -- " + ca_boom
+        ca_boom.backtrace.each { |l| ::Mole.logger.error l }             
+      end    
+    end
+                       
+    def apply_unchecked_filters( boom, filters, clazz, key, *a, &b ) #:nodoc:
+      begin
+        filters.each { |r,m| r.send( m, clazz, key, boom, b, *a ) }
+      rescue => ca_boom                               
+        ::Mole.logger.error ">>> MOle Failure: Unchecked-Filter -- " + ca_boom
+        ca_boom.backtrace.each { |l| ::Mole.logger.error l }             
+      end                                                                       
+    end
+                          
+    # ---------------------------------------------------------------------------
+    # Log wrapped class
+    def wrapped #:nodoc:
+      @wrapped ||= {}
+    end
+
+    # ---------------------------------------------------------------------------
+    # Check if method has been wrapped
+    def wrapped?(which) #:nodoc:
+      wrapped.has_key?(which.to_s)
+    end       
+end