mole 0.0.1

data/lib/mole/logger.rb

@@ -0,0 +1,131 @@
+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   => "mail.collectiveintellect.com".freeze  ,
+        :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]}" }                                                  
+      self.info( "[#{ip_addr}/#{browser_type}]-- #{context}(#{feature}) --- #{user_id} -> #{info.join( ', ' ) }" )
+    end
+  end
+end

data/lib/mole/models/mole_feature.rb

@@ -0,0 +1,45 @@
+# 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_feature( performance, app_name )
+    end
+                                 
+    # find exception feature
+    def find_exception_feature( app_name )         
+      find_feature( exception, app_name )
+    end
+    
+    def find_all_feature( app_name )
+      find_feature( all, 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 )
+      MoleFeature.find( :all, 
+                        :conditions => ["app_name = ?", app_name], 
+                        :select     => "id, name, context", 
+                        :order      => "name asc" )      
+    end
+      
+    # locates an existing feature or create a new one
+    def find_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                                
+      find_by_name_and_context_and_app_name( name, ctx_name, app_name ) ||     
+      create(:name => name,:context => ctx_name, :app_name => app_name )
+    end   
+  end
+end               

data/lib/mole/models/mole_log.rb

@@ -0,0 +1,56 @@
+# 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                                     
+    # logs unchecked exception           
+    def check_it( context, user_id, args )     
+      if args[:boom]
+        args[:trace] = dump_stack( args[:boom] )
+        args[:boom]  = args[:boom].to_s
+      end
+      log_it( context, MoleFeature::find_exception_feature( ::Mole.application ), user_id, args ) if ::Mole::moleable?
+    end             
+                                       
+    # logs perf occurence
+    def perf_it( context, user_id, args )
+      log_it( context, MoleFeature::find_performance_feature( ::Mole.application ), user_id, args ) if ::Mole::moleable?
+    end
+          
+    # persists mole information to the database. 
+    # This call will store information on the mole dedicated tables namely 
+    # mole_features and mole_logs.                                  
+    def mole_it(context, feature, user_id, args)   
+      log_it( context, MoleFeature::find_feature( feature, ::Mole.application, context.class.name ), user_id, args ) if ::Mole::moleable?
+    end               
+    
+    # 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
+                   
+    # dumps partial stack
+    def dump_stack( boom )      
+      buff = boom.backtrace[0...3].join( "-" )
+    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,274 @@
+# =============================================================================
+# 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, 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={}, &filter )    
+    opts[:interceptor] ||= filter
+    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, 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={}, &filter )    
+    opts[:interceptor] ||= filter
+    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, *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 = {}, &filter)   
+    raise "Missing :feature option" if opts[:feature].nil? or opts[:feature].to_s.empty?
+    opts[:interceptor] ||= filter
+    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, *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
+          
+  # def dump
+  #   puts "Filters for class <- #{self} ->"
+  #   puts "Before filters"
+  #   before_mole_filters.each_pair do |k,v|
+  #     puts "#{k} --> #{v}"
+  #   end
+  #   puts "After filters"
+  #   after_mole_filters.each_pair do |k,v|
+  #     puts "#{k} --> #{v}"
+  #   end
+  #   puts "Unchecked filters"
+  #   unchecked_mole_filters.each_pair do |k,v|
+  #     puts "#{k} --> #{v}"
+  #   end
+  #   puts "Perf filters"
+  #   perf_mole_filters.each_pair do |k,v|
+  #     puts "#{k} --> #{v}"
+  #   end    
+  # end
+      
+  # ===========================================================================
+  # protected
+    
+  # ---------------------------------------------------------------------------
+  # 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 NameError unless(between)
+    end
+    code = <<-code
+      def #{method}_with_mole (*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 )
+        begin                                          
+          elapsed = Benchmark::realtime do 
+            ret_val = between.bind(self).call(*a) 
+          end   
+          klass.apply_perf_filters( elapsed, klass.perf_mole_filters[key], self, key, *a, &b )                              
+        rescue => boom   
+          klass.apply_unchecked_filters( boom, klass.unchecked_mole_filters[key], self, key, *a, &b )
+          raise boom            
+        end                                                                 
+        klass.apply_after_filters( klass.after_mole_filters[key], self, key, *a, &b )
+        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, *a, &b) }
+    rescue => ca_boom
+      ::Mole.logger.error ">>> Mole Error: Before-Filter -- " + ca_boom
+      # ca_boom.backtrace.each { |l| ::Mole.logger.error l }           
+    end    
+  end
+                       
+  def apply_after_filters( filters, clazz, key, *a, &b )           #:nodoc:              
+    begin  
+      filters.each { |r,m| r.send(m, clazz, key, *a, &b) }
+    rescue => ca_boom    
+      ::Mole.logger.error ">>> Mole Error: After-Filter -- " + ca_boom
+      # ca_boom.backtrace.each { |l| ::Mole.logger.error l }           
+    end    
+  end
+                       
+  def apply_perf_filters( elapsed, filters, clazz, key, *a )       #:nodoc:
+    begin
+      if ( elapsed >= Mole.perf_threshold  )
+        filters.each { |r,m| r.send(m, clazz, key, elapsed, *a) }            
+      end
+    rescue => ca_boom
+      ::Mole.logger.error ">>> Mole Error: 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, *a, &b ) }
+    rescue => ca_boom                               
+      ::Mole.logger.error ">>> Mole Error: 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

data/lib/mole/moler.rb

@@ -0,0 +1,51 @@
+# -----------------------------------------------------------------------------
+# Manages different ways to log the Mole interceptors. Currently there are two
+# allowed modes ie persistent and transient
+# Persistent mode will log the interception to the database for easy viewing
+# and reporting.
+# Transient mode will log the interaction to the mole logger.
+# -----------------------------------------------------------------------------
+module Mole
+  class Moler    
+    class << self            
+      # log an unchecked exception. Moler will look at the MOle
+      # configuration to see if this event should be persisted to the db or
+      # sent out to the logger.           
+      def check_it( context, user_id, args )                                            
+        return unless ::Mole.moleable?
+        if ::Mole.persistent?             
+          MoleLog.log_it( context, MoleFeature::find_exception_feature( ::Mole.application ), user_id, args )             
+        else                                                                            
+          ::Mole.logger.log_it( context, "Exception", user_id, args ) 
+        end          
+        # Send out email notification if requested
+        Mole::EMole.deliver_exception_alerts( context, user_id, args ) if args[:email] and args[:email] == true        
+      end             
+                                         
+      # log performance occurence. 
+      def perf_it( context, user_id, args )
+        return unless ::Mole.moleable?        
+        if ::Mole.persistent?
+          MoleLog.log_it( context, MoleFeature::find_performance_feature( ::Mole.application ), user_id, args )
+        else
+          ::Mole.logger.log_it( context, "Performance", user_id, args )
+        end
+        # Send out email notification if requested
+        Mole::EMole.deliver_perf_alerts( context, user_id, args ) if args[:email] and args[:email] == true                
+      end
+            
+      # log a mole feature occurence.           
+      def mole_it(context, feature, user_id, args)    
+        return unless ::Mole.moleable?        
+        if ::Mole.persistent?
+          MoleLog.log_it( context, MoleFeature::find_feature( feature, ::Mole.application, context.class.name ), user_id, args )
+        else
+          ::Mole.logger.log_it( context, feature, user_id, args )
+        end
+        # Send out email notification if requested   
+        args[:feature] = feature
+        Mole::EMole.deliver_feature_alerts( context, user_id, args ) if args[:email] and args[:email] == true                        
+      end  
+    end             
+  end
+end

data/lib/mole/utils/frameworks.rb

@@ -0,0 +1,22 @@
+# -----------------------------------------------------------------------------
+# Convenience for extracting actions out controller classes                    
+# Currently supported frameworks : Rails and Merb, more in the future...
+# -----------------------------------------------------------------------------
+module Mole
+   module Utils
+     class Frameworks       
+       class << self                                                    
+         # Retrieves the collection of callable actions from a Merb controller.
+         def merb_actions( controller_class )
+           actions = []
+           controller_class.send( :callable_actions ).keys.each { |action| actions << action } 
+         end               
+         
+         # Retrieves the collection of callable actions from a Rails controller
+         def rails_actions( controller_class )    
+           controller_class.send( :action_methods )
+         end
+       end       
+    end
+  end
+end

data/lib/mole/version.rb

@@ -0,0 +1,15 @@
+module Mole
+  module Version
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 1
+    
+    # Returns the version string for the library.
+    #
+    def self.version
+      [ MAJOR, MINOR, TINY].join( "." )
+    end
+  end
+end
+
+