mole 0.0.1

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2008-02-13
+
+* 1 major enhancement
+  * Birthday!

data/Manifest.txt

@@ -0,0 +1,45 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/mole
+bin/molify
+config/database.yml
+config/test_database.yml
+lib/mole.rb
+lib/mole/db/migrate.rb
+lib/mole/e_mole.rb
+lib/mole/logger.rb
+lib/mole/models/mole_feature.rb
+lib/mole/models/mole_log.rb
+lib/mole/module.rb
+lib/mole/moler.rb
+lib/mole/utils/frameworks.rb
+lib/mole/version.rb
+spec/data/blee.rb
+spec/db/migrate_spec.rb
+spec/emole_spec.rb
+spec/logger_spec.rb
+spec/models/mole_feature_spec.rb
+spec/models/mole_log_spec.rb
+spec/module_spec.rb
+spec/mole_spec.rb
+spec/moler_spec.rb
+spec/spec_helper.rb
+spec/utils/framework_spec.rb
+tasks/ann.rake
+tasks/annotations.rake
+tasks/doc.rake
+tasks/gem.rake
+tasks/manifest.rake
+tasks/mole.rake
+tasks/post_load.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/spec.rake
+tasks/svn.rake
+tasks/test.rake
+templates/mole/e_mole/exception_alerts.rhtml
+templates/mole/e_mole/feature_alerts.rhtml
+templates/mole/e_mole/perf_alerts.rhtml
+test/test_mole.rb

data/README.txt

@@ -0,0 +1,140 @@
+The MOle
+    by Fernand Galiana
+    liquidrail.com
+
+== DESCRIPTION:
+                   
+The MOle allows you to track user's interactions with your ruby application and closely monitors
+how your customers are using your application.
+
+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? 
+Using the MOle you'll 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. 
+
+== FEATURES:
+                                                                                     
+The MOle allows you to easily
+  
+* Trap method calls within your ruby application. You can use the MOle with either a straight ruby 
+  application, Rails or Merb. The MOle allows you to inject aspects across various method calls.    
+  You are in full control on how and where to trap the calls and the arguments you want to record. 
+  'Moled' methods are not limited to controller's actions, you can also mole any third party or library methods. 
+
+* Single configuration file. You won't have to sprinkle MOle code all over your application.
+  The MOle instructions reside in a single file easy to manage and maintain. 
+
+* Trap and surface uncaught exceptions in one easy call. The MOle will watch your execution stack
+  and alert you when an unexpected exception is encountered
+
+* Trap and surface performance bottle neck in your ruby application in one easy call. You can 
+  specify a performance threshold within the MOle configuration file. Any methods taking longer
+  than the specified threshold will trip an alert.
+                                                  
+* You can record users interaction by either using the MOle is a transient or persistent mode.
+  In the persistent mode, users interactions will be recorded in your database. In the transient
+  case, MOle events will be recorded in your application logs.
+
+== INSTALL:
+
+* sudo gem install mole
+
+== SYNOPSIS:
+                                                                                             
+* Mole initialization. This must be specified during your application initialization code.
+  In a rails app, this can be set in you application controller class or environment.rb. In 
+  a Merb app, this can be set in your merb_init.rb file.
+        
+   require 'mole'                    
+   Mole.initialize( :moleable         => true,
+                    :emole_from       => "MoleBeatch@acme.com",
+                    :emole_recipients => ['fernand@acme.com'],
+                    :mode             => :persistent,
+                    :log_file         => $stdout,
+                    :log_level        => :debug,
+                    :perf_threshold   => 2,
+                    :application      => "Smf",
+                    :mole_config      => File.join( File.dirname(__FILE__), %w[mole.rb] ) )                            
+                           
+* Now you'll need to create a mole.rb specification file to specify the various aspects you'll want
+  to inject. This file is specified in the initialize call via the :mole_config tag.
+  
+  To trap a feature before or after it occurs you can use the mole_before/mole_after 
+  interceptors. The following will mole the "Posts" class after the "show" method is called. 
+  The context argument hands you an execution context. In a rails/merb environment
+  this will be your controller object. You can handle this interaction any way
+  you want. The MOle provides a convenience class to record this interaction via
+  the database or the MOle logger in the guise of Mole::Moler. But you can also log it to 
+  any media you'll find suitable. In a rails/merb context, you'll be able to extract session/params information
+  as in this case.
+    
+      Posts.mole_after( :feature => :show ) { |context, feature, ret, args, block|
+        # Records the interaction to the database
+        Mole::Moler.mole_it( context, feature, 
+          context.session[:user_id],                           # Retrieves which user performed this action
+          :post_id=> context.params[:post_id],                 # Records request parameter post id
+          :url    => context.instance_variable_get( "@url" ) ) # Retrieves controller state 
+        end
+      }
+
+  To record performance issues, you will need to provide a collection of
+  methods that must be watched on a given class. In the case of rails or merb you can easily fetch the list
+  of actions from the controller api and pass it to the MOle. The MOle provides convenience
+  classes to log the perf issues to your database and send out alerts when a perf condition is met. 
+  Upon invocation, you will be handed a calling context, that comprises the feature (method) being
+  called, the actual time it took to complete the call and any args/block that was passed into
+  the feature that causes the performance threshold to be triggered. Setting the :email option
+  to true will also send out an email alert.           
+     
+      Posts.mole_perf( :features => merb_actions ) do |context, feature, elapsed_time, args, block|
+        user    = context.instance_variable_get( "@user" )
+        key     = context.params[:key], "N/A"                                                                     
+        request = context.request.nil? ? "N/A" : context.request.remote_ip,
+        Mole::Moler.perf_it( context, user.id,
+          :controller   => context.class.name,
+          :feature      => feature,
+          :key          => key,
+          :request      => request,
+          :user         => user.user_name,
+          :elapsed_time => "%3.3f" % elapsed_time,
+          :email        => true )
+      end
+
+  The unchecked exception trap works very similarly to the mole_perf trap. It will pass in
+  the context of the method that triggered the exception.
+    
+        Posts.mole_unchecked( :features => merb_actions ) do |context, action, boom, args, block|
+          sub     = context.instance_variable_get("@sub")
+          user_id = "N/A"  
+          user_id = sub.user.id if sub and sub.user    
+          Mole::Moler.check_it( context, user_id,
+            :controller => context.class.name,
+            :action     => action,
+            :boom       => boom,
+            :email      => true )                               
+        end     
+                             
+== LICENSE:
+
+MIT Copyright (c) 2008
+
+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,47 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+require 'mole'      
+require 'mole/version'
+                   
+task :default => 'spec:run'
+
+PROJ.name           = 'mole'
+PROJ.authors        = 'Fernand Galiana'
+PROJ.email          = 'fernand@liquidrail.com'
+PROJ.url            = 'http://mole.rubyforge.org'
+PROJ.rubyforge_name = 'mole'            
+PROJ.description    = "A flexible way to track user's interactions within your ruby web applications"
+PROJ.spec_opts      << '--color'
+PROJ.rcov_dir       = ENV['CC_BUILD_ARTIFACTS']  ? "#{ENV['CC_BUILD_ARTIFACTS']}/test_coverage" : 'coverage'  
+PROJ.rdoc_dir       = ENV['CC_BUILD_ARTIFACTS']  ? "#{ENV['CC_BUILD_ARTIFACTS']}/api_docs" : 'docs'  
+PROJ.ruby_opts      = %w[-W0]
+PROJ.version        = ::Mole::Version.version
+PROJ.svn            = 'mole'
+PROJ.rcov_threshold = 90.0
+PROJ.executables    = ['molify']
+
+PROJ.exclude        << %w[.DS_Store$ .swo$ .swp$]
+PROJ.tests          = FileList['test/**/test_*.rb']   
+PROJ.dependencies   = [ ["logging"] ]
+PROJ.annotation_tags << 'BOZO'
+
+desc "Clean up artifact directories"
+task :clean do    
+  rcov_artifacts = File.join( File.dirname( __FILE__ ), "coverage" )
+  FileUtils.rm_rf rcov_artifacts if File.exists? rcov_artifacts
+  rdoc_artifacts = File.join( File.dirname( __FILE__ ), "docs" )
+  FileUtils.rm_rf rdoc_artifacts if File.exists? rdoc_artifacts  
+  gem_artifacts = File.join( File.dirname( __FILE__ ), "pkg" )
+  FileUtils.rm_rf gem_artifacts if File.exists? gem_artifacts    
+end  
+
+task 'gem:package' => 'manifest:assert'
+
+                
+depend_on "logging"     , "= 0.7.0"       
+depend_on "activerecord", "= 2.0.2"

data/bin/mole

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

data/bin/molify

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby            
+require 'optparse'
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), '..', 'lib', 'mole') )
+    
+require 'mole/db/migrate'
+
+module Mole
+  class Molify  
+    # Performs db migration when the MOle is to be used in a persistent mode.
+    def initialize( argv=ARGV )   
+      option_parser = default_option_parser 
+      option_parser.parse!(argv)
+      puts options.inspect
+      ::Mole::Db::Migrate.new( options ).apply
+    end                  
+            
+    # access the options
+    def options  #:nodoc:
+      if not @options then      
+        @options = OpenStruct.new 
+        # Unless specified attempt to lookup config/database.yml
+        @options.configuration = File.join( Dir.pwd, %w[config database.yml] )
+        # Unless specified assumes test env
+        @options.environment   = "test"    
+        # Unless specficied migrates up
+        @options.direction     = :up
+      end
+      return @options
+    end
+
+    def default_option_parser #:nodoc:
+      OptionParser.new do |op|
+        op.separator ""
+        op.separator "Molify options"
+
+        op.on( "-c", "--config FILE", "The location of the database configuration file." ) do |db|
+          options.configuration = db
+        end
+
+        op.on("-e", "--env ENV", "The environment to run in." ) do |env|
+          options.environment = env
+        end
+        
+        op.on("-u", "--up", "Install MOle related tables") do |dir|
+          options.direction= :up
+        end
+
+        op.on("-d", "--down", "Uninstall MOle related tables") do |dir|
+          options.direction= :down
+        end
+
+        op.separator ""
+      end
+    end   
+  end
+end  
+
+Mole::Molify.new(ARGV)
+
+
+
+    

data/config/database.yml

@@ -0,0 +1,21 @@
+# ------------------------ Databases ------------------------ 
+#
+# Local login
+local:     &local
+ adapter:  mysql
+ host:     localhost
+ username: root
+ password: 
+
+local_dev: &local_dev
+  <<:       *local
+  database: mole_dev
+  
+local_test: &local_test
+  <<: *local
+  database: mole_test
+
+# ------------------------ Environments ------------------------ 
+#  
+development: *local_dev 
+test:        *local_test

data/config/test_database.yml

@@ -0,0 +1,69 @@
+                                                  #
+# ------------------------ Databases ------------------------ 
+#
+
+# Production read-only
+read_only: &read_only
+  adapter:  mysql
+  host:     10.10.12.100
+  database: ci_sentiment_db
+  username: ciro  
+  password: ciro
+
+# Production writable
+writable: &writable
+ adapter: mysql
+ host:     10.10.12.101
+ database: ci_sentiment_db
+ username: ciprod
+ password: ciprod
+
+# Remote development database
+dev2: &dev2
+ adapter:  mysql
+ host:     dev2
+ encoding: utf8
+ database: ci_sentiment_db
+ username: root  
+ password: alchem1st
+
+# CC test database
+cc: &cc
+ adapter:  mysql
+ host:     10.10.14.105
+ encoding: utf8
+ database: sentiment_test
+ username: root  
+ password: alchem1st
+
+# Local login
+local: &local
+ adapter:  mysql
+ host:     localhost
+ username: root
+ password: 
+
+local_dev: &local_dev
+  <<: *local
+  database: sentiment_dev
+  
+local_test: &local_test
+  <<: *local
+  database: sentiment_test
+ 
+yahoo: &yahoo
+  adapter: mysql
+  database: ci_yahoo_db
+  host: 10.10.12.104
+  username: ciprod
+  password: ciprod
+#
+# ------------------------ Environments ------------------------ 
+#  
+development:      *local_dev 
+test:             *local_test
+beta:             *dev2
+production:       *writable
+cc:               *cc
+yahoo_production: *yahoo
+production_ro:    *read_only

data/lib/mole/db/migrate.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+
+# -----------------------------------------------------------------------------
+# Sets up the MOle persistent layer
+# Two tables are involved: mole_features and mole_logs 
+# -----------------------------------------------------------------------------
+require 'rake'
+require 'rake/tasklib'
+
+module Mole
+  module Db           
+    class Migrate                     
+      def initialize( opts )
+        @direction = opts.direction
+        @config    = opts.configuration
+        @env       = opts.environment
+      end
+                                                      
+      # Creates a MOle migration by creating or dropping the MOle related tables    
+      def apply #:nodoc:
+        setup
+        @direction == :up ? migrate_up : migrate_down
+      end
+                                              
+      # Setup database connection prior to applying migrations
+      def setup #:nodoc:
+        require 'rubygems'
+        gem "activerecord"
+        require 'active_record'  
+        db_config = YAML.load_file( File.expand_path( @config ) )[@env]
+        ::ActiveRecord::Base.establish_connection(db_config)
+      end                                                   
+                        
+      # ---------------------------------------------------------------------
+      # Create mole persistence tables ( 2 tables mole_features/mole_logs )
+      def migrate_up
+        # Create the mole_features table if it doesn't exist
+        unless ActiveRecord::Schema.tables.include?('mole_features')
+          ActiveRecord::Schema.create_table('mole_features') do |t|
+            t.column :name,             :string     
+            t.column :context,          :string
+            t.column :app_name,         :string
+            t.column :created_at,       :datetime
+            t.column :updated_at,       :datetime
+          end
+          ActiveRecord::Schema.add_index( 'mole_features', 
+                                          ['name', 'context', 'app_name'], 
+                                          :name   => 'feature_idx')
+        end
+        # Create the mole_logs table if it doesn't exist
+        unless ActiveRecord::Schema.tables.include?('mole_logs')
+          ActiveRecord::Schema.create_table('mole_logs') do |t|
+            t.column :mole_feature_id,  :integer
+            t.column :user_id,          :integer
+            t.column :params,           :string, :limit => 1024    
+            t.column :ip_address,       :string
+            t.column :browser_type,     :string  
+            t.column :host_name,        :string
+            t.column :created_at,       :datetime
+            t.column :updated_at,       :datetime
+          end     
+          ActiveRecord::Schema.add_index( 'mole_logs', 
+                                          ['mole_feature_id','user_id'], 
+                                          :name   => "log_feature_idx" )
+          ActiveRecord::Schema.add_index( 'mole_logs', 
+                                          ['mole_feature_id','created_at'], 
+                                          :name   => "log_date_idx",
+                                          :unique => true )
+        end
+      end
+                                                     
+      # -------------------------------------------------------------------------
+      # Destroys mole persistence tables
+      def migrate_down
+        # Delete the mole_feature table
+        if ActiveRecord::Schema.tables.include?( 'mole_features' )                                                             
+          ActiveRecord::Schema.remove_index( 'mole_features', :name => 'feature_idx' )              
+          ActiveRecord::Schema.drop_table( 'mole_features' )
+        end
+    
+        # Delete the mole_logs table
+        if ActiveRecord::Schema.tables.include?( 'mole_logs' )
+          ActiveRecord::Schema.remove_index( 'mole_logs', :name => 'log_feature_idx' )        
+          ActiveRecord::Schema.remove_index( 'mole_logs', :name =>'log_date_idx' )              
+          ActiveRecord::Schema.drop_table( 'mole_logs' )
+        end
+      end                                      
+    end
+  end
+end

data/lib/mole/e_mole.rb

@@ -0,0 +1,74 @@
+require 'action_mailer'
+
+module Mole
+  class EMole < ActionMailer::Base        
+    self.template_root = File.join( File.dirname(__FILE__), %w[.. .. templates] )
+                            
+    def setup #:nodoc:
+      recipients  ::Mole.emole_recipients
+      from        ::Mole.emole_from             
+      @host = `hostname`      
+    end
+       
+    # Setup aspect
+    %w[perf exception feature].each do |asp|
+      module_eval "def #{asp}_alerts_with_setup( context, user_name, opts={} ) setup; #{asp}_alerts_without_setup( context, user_name, opts) end #:nodoc:"
+    end
+    
+    # send out feature alerts
+    def feature_alerts( context, user_id, options={} )
+      Mole.logger.debug "Sending feature email from #{::Mole.emole_from} -- to #{::Mole.emole_recipients}"                  
+      subject     "[FEATURE] #{options[:feature]} -- #{@host} -- #{Mole.application} -- #{user_id}"        
+      body        :application  => Mole.application,
+                  :host_name    => @host,
+                  :context      => context.class.name,
+                  :feature      => options[:feature],
+                  :args         => dump_args( options )
+    end                                  
+    alias_method_chain :feature_alerts, :setup
+    
+    # send out mole performance alert
+    def perf_alerts( context, user_id, options={} )                                           
+      Mole.logger.debug "Sending perf email from #{::Mole.emole_from} -- to #{::Mole.emole_recipients}"                  
+      subject     "[PERF] #{@host} -- #{Mole.application} -- #{user_id}"        
+      body        :application  => ::Mole.application,       
+                  :host_name    => @host,      
+                  :context      => context.class.name,
+                  :feature      => options[:feature],                          
+                  :elapsed_time => options[:elapsed_time] ,
+                  :args         => dump_args( options )
+    end           
+    alias_method_chain :perf_alerts, :setup
+
+    # send out mole exception alerts
+    def exception_alerts( context, user_id, options={} )
+      Mole.logger.debug "Sending perf email from #{::Mole.emole_from} -- to #{::Mole.emole_recipients}"                  
+      subject     "[EXCEPTION] #{@host} -- #{Mole.application} -- #{user_id}"        
+      body        :application  => Mole.application,
+                  :host_name    => @host,
+                  :context      => context.class.name,
+                  :feature      => options[:feature],
+                  :boom         => options[:boom],  
+                  :trace        => dump_stack( options[:boom] ),
+                  :args         => dump_args( options )                  
+    end                                  
+    alias_method_chain :exception_alerts, :setup
+                   
+    # dumps partial stack
+    def dump_stack( boom )      
+      buff = boom.backtrace[0...3].join( "\r" )
+    end
+                                        
+    # dumps arguments
+    def dump_args( args )
+      return "N/A" unless args
+      buff = []
+      args.keys.sort { |a,b| a.to_s <=> b.to_s}.each do |k|  
+        key   = k.to_s.rjust(20)
+        value = args[k].to_s.rjust(97,".")
+        buff << "#{key} :  #{value}" 
+      end
+      buff.join( "\r" )
+    end
+  end
+end