derailed-mole 1.0.10

data/History.txt

@@ -0,0 +1,17 @@
+== 1.0.0 / 2008-02-04
+
+* 1 Initial drop
+  * Converted from rails plugin into gem
+  * Retrofited to work with pure ruby, merb and rails env
+
+== 1.0.1 / 2008-02-04
+
+* 1 Documentation enhancements
+  
+== 1.0.2 / 2008-02-04
+
+* 1 Added Snitch support
+
+== 1.0.3 / 2008-02-05
+
+* 1 Bug Fixes

data/Manifest.txt

@@ -0,0 +1,137 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/molify
+config/database.yml
+config/test_database.yml
+lib/mole.rb
+lib/mole/db/migrate.rb
+lib/mole/e_mole.rb
+lib/mole/e_mole_helper.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
+samples/merbapp/README
+samples/merbapp/Rakefile
+samples/merbapp/app/controllers/application.rb
+samples/merbapp/app/controllers/exceptions.rb
+samples/merbapp/app/controllers/moled.rb
+samples/merbapp/app/helpers/global_helper.rb
+samples/merbapp/app/mailers/views/layout/application.html.erb
+samples/merbapp/app/mailers/views/layout/application.text.erb
+samples/merbapp/app/parts/views/layout/application.html.erb
+samples/merbapp/app/views/exceptions/internal_server_error.html.erb
+samples/merbapp/app/views/exceptions/not_acceptable.html.erb
+samples/merbapp/app/views/exceptions/not_found.html.erb
+samples/merbapp/app/views/layout/application.html.erb
+samples/merbapp/app/views/moled/index.html.erb
+samples/merbapp/app/views/moled/result.html.erb
+samples/merbapp/config/boot.rb
+samples/merbapp/config/dependencies.rb
+samples/merbapp/config/environments/development.rb
+samples/merbapp/config/environments/production.rb
+samples/merbapp/config/environments/test.rb
+samples/merbapp/config/merb.yml
+samples/merbapp/config/merb_init.rb
+samples/merbapp/config/mole_config.rb
+samples/merbapp/config/router.rb
+samples/merbapp/config/upload.conf
+samples/merbapp/log/merb.4000.pid
+samples/merbapp/public/images/merb.jpg
+samples/merbapp/public/merb.fcgi
+samples/merbapp/public/stylesheets/master.css
+samples/merbapp/script/destroy
+samples/merbapp/script/generate
+samples/merbapp/script/stop_merb
+samples/merbapp/spec/spec_helper.rb
+samples/merbapp/test/test_helper.rb
+samples/railsapp/README
+samples/railsapp/Rakefile
+samples/railsapp/app/controllers/application.rb
+samples/railsapp/app/controllers/moled_controller.rb
+samples/railsapp/app/helpers/application_helper.rb
+samples/railsapp/app/views/moled/index.html.erb
+samples/railsapp/app/views/moled/result.html.erb
+samples/railsapp/config/boot.rb
+samples/railsapp/config/database.yml
+samples/railsapp/config/environment.rb
+samples/railsapp/config/environments/development.rb
+samples/railsapp/config/environments/production.rb
+samples/railsapp/config/environments/test.rb
+samples/railsapp/config/initializers/inflections.rb
+samples/railsapp/config/initializers/mime_types.rb
+samples/railsapp/config/initializers/mole.rb
+samples/railsapp/config/moles/mole_config.rb
+samples/railsapp/config/routes.rb
+samples/railsapp/doc/README_FOR_APP
+samples/railsapp/log/development.log
+samples/railsapp/log/production.log
+samples/railsapp/log/server.log
+samples/railsapp/log/test.log
+samples/railsapp/public/.htaccess
+samples/railsapp/public/404.html
+samples/railsapp/public/422.html
+samples/railsapp/public/500.html
+samples/railsapp/public/dispatch.cgi
+samples/railsapp/public/dispatch.fcgi
+samples/railsapp/public/dispatch.rb
+samples/railsapp/public/favicon.ico
+samples/railsapp/public/images/rails.png
+samples/railsapp/public/javascripts/application.js
+samples/railsapp/public/javascripts/controls.js
+samples/railsapp/public/javascripts/dragdrop.js
+samples/railsapp/public/javascripts/effects.js
+samples/railsapp/public/javascripts/prototype.js
+samples/railsapp/public/robots.txt
+samples/railsapp/script/about
+samples/railsapp/script/console
+samples/railsapp/script/destroy
+samples/railsapp/script/generate
+samples/railsapp/script/performance/benchmarker
+samples/railsapp/script/performance/profiler
+samples/railsapp/script/performance/request
+samples/railsapp/script/plugin
+samples/railsapp/script/process/inspector
+samples/railsapp/script/process/reaper
+samples/railsapp/script/process/spawner
+samples/railsapp/script/runner
+samples/railsapp/script/server
+samples/railsapp/test/test_helper.rb
+samples/rubyapp/README
+samples/rubyapp/bin/ruby_app
+samples/rubyapp/config/mole_conf.rb
+samples/rubyapp/lib/fred.rb
+spec/config/auto_mole_config.rb
+spec/config/mole_config.rb
+spec/config/moles/fred_config.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

data/README.txt

@@ -0,0 +1,216 @@
+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. This is a must cheaper way than to hire a monitoring
+service and produces much more detailed information on your application behavior and usage. To boot
+your managers will love you !
+
+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. 
+                
+The MOle was initialy released as a Rails plugin, but we found the behavior usefull in other types
+of projects such as Merb or straight up ruby applications, and decided to re-release it as a gem 
+instead.
+
+== PROJECT INFORMATION
+
+* Developer:  Fernand Galiana [liquidrail.com]
+* Forum:      http://groups.google.com/group/mole-plugin
+* Home:       mole.rubyforge.org
+* Svn:        svn://rubyforge.org/var/svn/mole/mole/trunk
+* Git:        git://github.com/derailed/mole.git
+* Snitch Svn: svn://rubyforge.org/var/svn/mole/snitch/trunk
+* Examples:   svn://rubyforge.org/var/svn/mole/samples
+
+== 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:
+
+* The MOle can operate in 2 different modes: transient or persistent. The transient mode will
+  simply record MOle interactions within your log file. If you opt to use the 
+  persistent mode (recommanded!) which will allow to leverage the Snitch Application
+  and also draw out MOle usage reports from you database, you will need to install the 2 MOle tables in your database.
+  This is achived via the 'molify' command. In order to 'MOle' an application using the persistent
+  mode, you will need to issue the following commands:
+                                                     
+   > cd my_non_moled_application
+   > molify --up --config config/database.yml --env test
+  
+  This command will update your test database and create the MOle tables required when 
+  the MOle is in a persistent mode. Namely, these tables are mole_features and mole_logs.
+   
+  You can use molify --help to see usage information. 
+                                                                                             
+* 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,
+                    :application      => "Smf",   
+                    :emole_from       => "MoleBeatch@liquidrail.com",
+                    :emole_recipients => ['fernand@liquidrail.com'],
+                    :mode             => :persistent,
+                    :log_file         => $stdout,
+                    :log_level        => :debug,
+                    :perf_threshold   => 2,
+                    :mole_config      => File.join( File.dirname(__FILE__), %w[mole.rb] ) ) 
+   # Load the MOle configuration file(s)
+   ::Mole.load_configuration                  
+                    
+  NOTE: The mole_config can either be a single ruby file or a directory containing multiple MOle
+  configuration files. Thanks to Ian Schreuder for the suggestion !
+  
+  NOTE: For rails applications you can either put the MOle initialization code in a custom initializer
+  ie config/initializers/mole.rb or in your environment file (config/environments/production.rb). 
+  You will need to make the load_configuration call in your application controller(application.rb) as follows:
+  
+    ::Mole.load_mole_configuration rescue nil 
+    
+  In dev env, the MOle will reload the configuration so you can tweak your app on the fly. In production
+  env the MOle configuration will be loaded once.
+                             
+* 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, block, *args|
+        # 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, ret, block, *args|
+        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, block, *args|
+          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     
+          
+== Snitch
+
+To view MOle interaction simply, we've created the "Snitch" a rails console application that
+allows you to see the results of your MOled application. The Snitch is a Rails 2.0 application.
+It is available at http://mole.rubyforge.org/svn/snitch/trunk/. 
+
+In order to start using the Snitch you will have to perform the following steps:
+
+* Download the Snitch
+   svn co http://mole.rubyforge.org/svn/snitch/trunk/
+   
+* The Snitch needs to access your user table to provide user related log information. So 
+  you will need to run the following rake task and provide your users table description.
+  
+  > rake setup
+  
+* Edit the Snitch database.yml to point to your application database.
+
+* Out of the box the Snitch will monitor and application named "Default". You will want
+  to match the application name that you've used in the Mole.initialize call. So you
+  should now be able to specify the following commands:
+  
+   > script/server
+   
+  Then in your browser
+  
+  http://localhost:3000?app_name=my_moled_application_name
+  
+* NOTE: You will keep enhancing the Snitch to provide capistrano deployment scripts,
+  auto application name detection and many other enhancements...
+                      
+== 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,46 @@
+# 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.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.9.0"       
+depend_on "activerecord", "= 2.0.2"

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)
+
+
+
+