minstrel 0.2.20101115170047 → 0.2.20110404021920

data/README.textile

@@ -16,6 +16,10 @@ to debug or dig into how a piece of code works.
 
 It's a lot like strace/tcpdump/dtrace for ruby, or aims to be, anyway.
 
+I wanted a tool that was useful for my own code as well as for helping
+understand and debug other code (puppet, mcollective, rails, activerecord,
+sinatra, etc...).
+
 h2. Examples
 
 h3. From the commandline
@@ -135,4 +139,19 @@ Wrap of TCPSocket successful
 Minstrel will wrap 'require' and check for classes you want wrapped at each
 require until it finds all the classes you asked to be wrapped.
 
+h2. Caveats
+
+Metaprogramming will not be often caught, necessarily, by minstrel, because they don't
+show usuall up as methods. However, the things invoking metaprogramming are
+usually methods so in most cases you'll get lucky enough to see what's going
+on.
+
+Some cases of metaprogramming (dynamic method generation, DSLs, etc) can be
+caught if you call Minstrel::Instrument#wrap() late enough in the lifetime of
+the program that the dynamic methods have been created.
+
+h2. Bugs?
 
+If you find bugs, have feature suggestions, etc, feel free to open bugs here on
+github (https://github.com/jordansissel/ruby-minstrel/issues). I also read email:
+jls@semicomplete.com

data/lib/minstrel.rb

@@ -15,63 +15,118 @@
 #
 # RUBY_INSTRUMENT=comma_separated_classnames ruby -rminstrel ./your/program.rb
 #
+
+require "set"
+
 module Minstrel; class Instrument
   attr_accessor :counter
 
   class << self
     @@deferred_wraps = {}
+    @@wrapped = Set.new
   end
 
   # Put methods we must not be wrapping here.
-  #DONOTWRAP = #[Kernel, Object, Module, Class,
-  DONOTWRAP = [Minstrel::Instrument].collect do |obj|
-    obj.methods.collect { |m| m.to_sym }
-  end.flatten
-  DONOTWRAP << :to_sym
-  DONOTWRAP << :respond_to?
-  DONOTWRAP << :send
+  DONOTWRAP = {
+    "Minstrel::Instrument" => Minstrel::Instrument.instance_methods.collect { |m| m.to_sym },
+    "Object" => [ :to_sym, :respond_to?, :send, :java_send, :method, :java_method,
+                  :ancestors, :inspect, :to_s, :instance_eval, :instance_exec,
+                  :class_eval, :class_exec, :module_eval, :module_exec],
+  }
 
   # Wrap a class's instance methods with your block.
   # The block will be called with 4 arguments, and called
   # before and after the original method.
   # Arguments:
-  #   * point - the point (symbol, :entry or :exit) of call
-  #   * klass - the class (object) owning this method
+  #   * point - the point (symbol, :entry or :exit) of call,
+  #   * this - the object instance in scope (use 'this.class' for the class)
   #   * method - the method (symbol) being called
   #   * *args - the arguments (array) passed to this method.
   def wrap(klass, &block)
-    #puts "Instrumenting #{klass.name} with #{block.inspect}"
-    instrumenter = self
+    return true if @@wrapped.include?(klass)
+    instrumenter = self # save 'self' for scoping below
+    @@wrapped << klass
+
+    ancestors = klass.ancestors.collect {|k| k.to_s } 
+    if ancestors.include?("Exception")
+      return true
+    end
+    puts "Wrapping #{klass.class} #{klass}" if $DEBUG
 
+    # Wrap class instance methods (like File#read)
     klass.instance_methods.each do |method|
-      next if DONOTWRAP.include?(method.to_sym)
+      method = method.to_sym
+
+      # If we shouldn't wrap a certain class method, skip it.
+      skip = false
+      (ancestors & DONOTWRAP.keys).each do |key|
+        if DONOTWRAP[key].include?(method)
+          skip = true 
+          break
+        end
+      end
+      if skip
+        #puts "Skipping #{klass}##{method} (do not wrap)"
+        next
+      end
+
       klass.class_eval do
         orig_method = "#{method}_original(wrapped)".to_sym
-        method = method.to_sym
+        orig_method_proc = klass.instance_method(method)
         alias_method orig_method, method
         #block.call(:wrap, klass, method)
+        puts "Wrapping #{klass.name}##{method} (method)" if $DEBUG
         define_method(method) do |*args, &argblock|
-          block.call(:enter, klass, method, *args)
           exception = false
+          block.call(:enter, self, method, *args)
           begin
-            m = self.method(orig_method)
-            val = m.call(*args, &argblock)
+            # TODO(sissel): Not sure which is better:
+            # * UnboundMethod#bind(self).call(...)
+            # * self.method(orig_method).call(...)
+            val = orig_method_proc.bind(self).call(*args, &argblock)
+            #m = self.method(orig_method)
+            #val = m.call(*args, &argblock)
           rescue => e
             exception = e
           end
           if exception
-            block.call(:exit_exception, klass, method, *args)
+            # TODO(sissel): Include the exception
+            block.call(:exit_exception, self, method, *args)
             raise e if exception
           else
-            block.call(:exit, klass, method, *args)
+            # TODO(sissel): Include the return value
+            block.call(:exit, self, method, *args)
           end
           return val
-        end
+        end # define_method(method)
       end # klass.class_eval
     end # klass.instance_methods.each
 
+    # Wrap class methods (like File.open)
     klass.methods.each do |method|
-      next if DONOTWRAP.include?(method.to_sym)
+      method = method.to_sym
+      # If we shouldn't wrap a certain class method, skip it.
+      skip = false
+      ancestors = klass.ancestors.collect {|k| k.to_s} 
+      (ancestors & DONOTWRAP.keys).each do |key|
+        if DONOTWRAP[key].include?(method)
+          skip = true 
+          #break
+        end
+      end
+
+      # Doubly-ensure certain methods are not wrapped.
+      # Some classes like "Timeout" do not have ancestors.
+      if DONOTWRAP["Object"].include?(method)
+        #puts "!! Skipping #{klass}##{method} (do not wrap)"
+        skip = true
+      end
+
+      if skip
+        puts "Skipping #{klass}##{method} (do not wrap, not safe)" if $DEBUG
+        next
+      end
+
       klass.instance_eval do
         orig_method = "#{method}_original(classwrapped)".to_sym
         (class << self; self; end).instance_eval do
@@ -82,8 +137,9 @@ module Minstrel; class Instrument
             orig_method = self.method(method.to_sym)
           end
           method = method.to_sym
+          #puts "Wrapping #{klass.name}.#{method} (classmethod)"
           define_method(method) do |*args, &argblock|
-            block.call(:class_enter, klass, method, *args)
+            block.call(:class_enter, self, method, *args)
             exception = false
             begin
               if orig_method.is_a?(Symbol)
@@ -95,17 +151,19 @@ module Minstrel; class Instrument
               exception = e
             end
             if exception
-              block.call(:class_exit_exception, klass, method, *args)
+              block.call(:class_exit_exception, self, method, *args)
               raise e if exception
             else
-              block.call(:class_exit, klass, method, *args)
+              block.call(:class_exit, self, method, *args)
             end
             return val
           end
         end
-        #block.call(:class_wrap, klass, method, self.method(method))
-      end # klass.class_eval
+        #block.call(:class_wrap, self, method, self.method(method))
+      end # klass.instance_eval
     end # klass.instance_methods.each
+
+    return true
   end # def wrap
 
   def wrap_classname(klassname, &block)
@@ -119,24 +177,50 @@ module Minstrel; class Instrument
     return false
   end
 
+  def wrap_all(&block)
+    @@deferred_wraps[:all] = block
+    ObjectSpace.each_object do |obj|
+      next unless obj.is_a?(Class)
+      wrap(obj, &block)
+    end
+  end
+
   def self.wrap_require
     Kernel.class_eval do
       alias_method :old_require, :require
       def require(*args)
-        return Minstrel::Instrument::instrumented_require(*args)
+        return Minstrel::Instrument::instrumented_loader(:require, *args)
       end
     end
   end
 
-  def self.instrumented_require(*args)
-    ret = old_require(*args)
-    klasses = @@deferred_wraps.keys
-    klasses.each do |klassname|
-      block = @@deferred_wraps[klassname]
-      instrument = Minstrel::Instrument.new
-      if instrument.wrap_classname(klassname, &block)
-        puts "Wrap of #{klassname} successful"
-        @@deferred_wraps.delete(klassname)
+  def self.wrap_load
+    Kernel.class_eval do
+      alias_method :old_load, :load
+      def load(*args)
+        return Minstrel::Instrument::instrumented_loader(:load, *args)
+      end
+    end
+  end
+
+  def self.instrumented_loader(method, *args)
+    ret = self.send(:"old_#{method}", *args)
+    if @@deferred_wraps.include?(:all)
+      # try to wrap anything new that is not wrapped
+      wrap_all(@@deferred_wraps[:all])
+    else
+      # look for deferred class wraps
+      klasses = @@deferred_wraps.keys
+      klasses.each do |klassname|
+        if @@deferred_wraps.include?("ALL")
+          all = true
+        end
+        block = @@deferred_wraps[klassname]
+        instrument = Minstrel::Instrument.new
+        if instrument.wrap_classname(klassname, &block)
+          $stderr.puts "Wrap of #{klassname} successful"
+          @@deferred_wraps.delete(klassname) if !all
+        end
       end
     end
     return ret
@@ -144,14 +228,23 @@ module Minstrel; class Instrument
 end; end # class Minstrel::Instrument
 
 Minstrel::Instrument.wrap_require
+Minstrel::Instrument.wrap_load
 
 # Provide a way to instrument a class using the command line:
 # RUBY_INSTRUMENT=String ruby -rminstrel ./your/program
 if ENV["RUBY_INSTRUMENT"]
-  ENV["RUBY_INSTRUMENT"].split(",").each do |klassname|
+  klasses = ENV["RUBY_INSTRUMENT"].split(",")
+
+  callback = proc do |point, this, method, *args|
+    puts "#{point} #{this.to_s}##{method}(#{args.inspect}) (thread=#{Thread.current}, self=#{this.inspect})"
+  end
+  if klasses.include?(":all:")
     instrument = Minstrel::Instrument.new 
-    instrument.wrap_classname(klassname) do |point, klass, method, *args|
-      puts "#{point} #{klass.name || klassname}##{method}(#{args.inspect})"
+    instrument.wrap_all &callback
+  else
+    klasses.each do |klassname|
+      instrument = Minstrel::Instrument.new 
+      instrument.wrap_classname(klassname, &callback) 
     end
   end
 end

metadata

@@ -1,37 +1,32 @@
 --- !ruby/object:Gem::Specification 
 name: minstrel
 version: !ruby/object:Gem::Version 
-  hash: 40202230340073
-  prerelease: false
-  segments: 
-  - 0
-  - 2
-  - 20101115170047
-  version: 0.2.20101115170047
+  prerelease: 
+  version: 0.2.20110404021920
 platform: ruby
 authors: 
-- Jordan Sissel
+  - Jordan Sissel
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-11-15 00:00:00 -08:00
+date: 2011-04-04 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
 description: Instrument class methods
 email: jls@semicomplete.com
 executables: 
-- minstrel
+  - minstrel
 extensions: []
 
 extra_rdoc_files: []
 
 files: 
-- ./lib/minstrel.rb
-- ./README.textile
-- ./minstrel.gemspec
-- bin/minstrel
+  - ./lib/minstrel.rb
+  - ./README.textile
+  - ./minstrel.gemspec
+  - bin/minstrel
 has_rdoc: true
 homepage: https://github.com/jordansissel/ruby-minstrel
 licenses: []
@@ -40,30 +35,24 @@ post_install_message:
 rdoc_options: []
 
 require_paths: 
-- lib
-- lib
+  - lib
+  - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.5.1
 signing_key: 
 specification_version: 3
 summary: minstrel - a ruby instrumentation tool