gem install mole

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

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