method_call_tracer 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ec122bd2856f55ddd0958f690f667cfac0dd6d0
-  data.tar.gz: c517dc70ab2c883d8acc5e8b32e78a833c0565ba
+  metadata.gz: deeb870dcd4aa81de135eb555d0001c94be527f8
+  data.tar.gz: e8a9ac1fcf43516060cbef76292a3d894a4546b3
 SHA512:
-  metadata.gz: f1f235d6fe985239be47614b1bcfd9a925c157152de974d7dabf071d0cf36a024dbc63f37db9b9bbfc71351faec6cfd0b93d5fef9874916199e456e1b26366a2
-  data.tar.gz: 672b73d90ab60177d87b3f0a67ab828800154e077c20cdc51facc2178637ba3ff015731e7bf85a13c53d844827406218c61575799a114f335c7869272af34a01
+  metadata.gz: 11ca20032353767f513a4b17895ff8d5fd5533680092fe0b5feddb9296fda1846c3a277125c698810e5ea62d62f5c69c2f130f6b8e9243b0f44eda6b474ea74d
+  data.tar.gz: db328e9510208b7ca663bfbcc9d46eef8d946d1751f3fe7c3b8adafb4adc572573221b207a1273792771405c4ed4cda13bdb9f8164c8238e7027314a8ed99d5f

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.0
+
+- Accept a second, optional parameter in the initializer so we can short-circuit matching methods based on the class name for performance. This is so useful that the initializer's two arguments are now both keywords, indicating equal importance.
+- MethodTracer::Tracer no longer creates TracePoints upon initialization. Use the new `#enable` method to begin tracing.
+- Change output format to be even more machine-readable
+
+## 0.2.0
+
+- Rewrite to use Ruby's TracePoint instead of manually unbinding and rebinding methods. This has fewer side effects, but is much slower.
+
+## 0.1.0
+
+- Initial release

data/README.md

@@ -1,25 +1,34 @@
 # MethodTracer
 
-MethodTracer is a tool for detecting lines in an application that call certain methods, somewhat akin to the syscall monitoring functionality of strace(1). The methods to be traced are specified by file pattern, which makes it simple to trace an entire gem<sup>1</sup>. The most common use case is helping developers and testers focus their efforts when upgrading or changing gems in large applications.
+MethodTracer is a tool for detecting lines in an application that call certain methods, somewhat akin to the syscall monitoring functionality of strace(1).
 
-<sup>1</sup> Designating traced methods by file lets you trace methods defined in the "namespace" of a different gem. For example, if a hypothetical gem `activerecord-extension` defines some methods on the class `ActiveRecord`, we still have the ability to trace only the methods from `activerecord-extension` without capturing the methods from `activerecord`.
+The most common use case is helping developers and testers focus their efforts when upgrading or changing gems in large applications.
+
+MethodTracer's output is intended to be easily machine-readable.
 
 **Note about gem name**: due to a naming collision on rubygems.org, this gem appears there as `method_call_tracer`.
 
 ## Usage
 
-To attach tracers to methods, instantiate `MethodTracer::Tracer` objects. For Rails applications, these can be placed in the provided initializer.
+To attach tracers to methods, instantiate `MethodTracer::Tracer` objects and call `#enable`. For Rails applications, this can be done in the provided initializer.
+
+The methods to be traced are specified by file pattern. You can optionally also specify a (partial) class name to speed up the matching process, which is recommended for performance. The comparison is a simple `String#include?`; no pattern matching is supported.
 
 ```ruby
-# Trace all methods defined by the system installation of gibbon:
-MethodTracer::Tracer.new('/var/lib/gems/2.3.0/gems/gibbon-2.2.4/')
+# Trace all methods defined by the system installation of gibbon that also have "Gibbon" in the class name:
+MethodTracer::Tracer.new(path: '/var/lib/gems/2.3.0/gems/gibbon-2.2.4/', name: 'Gibbon').enable
+
+# Trace all methods defined by the system installation of gibbon, regardless of class name:
+MethodTracer::Tracer.new(path: '/var/lib/gems/2.3.0/gems/gibbon-2.2.4/').enable
 
-# Trace all methods defined by rbenv's 2.3.3 installation of activerecord:
-MethodTracer::Tracer.new('/home/eddie/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/activerecord-5.0.7/')
+# Trace all methods defined by rbenv's 2.3.3 installation of activerecord, regardless of class name:
+MethodTracer::Tracer.new(path: '/home/eddie/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/activerecord-5.0.7/').enable
 ```
 
 With tracers attached, exercise as much of the application as possible. Perhaps run the comprehensive test suite that you of course have.
 
+Using file paths makes it simple to trace an entire gem because it includes methods defined in the "namespace" of a different gem. For example, if a hypothetical gem `activerecord-extension` defines some methods on the class `ActiveRecord`, we still have the ability to trace only the methods from `activerecord-extension` without capturing the methods from `activerecord`.
+
 ## Configuration
 
 MethodTracer supports the following configuration options:
@@ -28,10 +37,6 @@ MethodTracer supports the following configuration options:
 
 `MethodTracer::Config.output_file`: A filename or `IO` or `StringIO` object where the report output should be sent. Defaults to `$stdout`.
 
-## Limitations
-
-MethodTracer theoretically does not interfere with the original behavior of methods being traced. However, certain gems are known to misbehave when the tracing logic is monkeypatched in, and MethodTracer will refuse to trace those gems. Furthermore, any methods defined after the `MethodTracer::Tracer` is instantiated will remain untraced.
-
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/generators/method_tracer/templates/initializer.rb

@@ -8,6 +8,6 @@ MethodTracer::Config.app_path = Rails.application.paths.path.to_s
 # like `$stdout`.
 # MethodTracer::Config.output_file = 'output_file_2.log'
 
-# Create a MethodTracer::Spy object for every gem to be spied on
-# MethodTracer::Tracer.new('/var/lib/gems/2.3.0/gems/gibbon-2.2.4/lib/gibbon/')
-# MethodTracer::Tracer.new('/var/lib/gems/2.3.0/gems/other_gem-1.0.0/lib/other_gem-1.0.0/')
+# Create a MethodTracer::Tracer object for every gem to be spied on
+# MethodTracer::Tracer.new(path: '/var/lib/gems/2.3.0/gems/gibbon-2.2.4/', name: 'Gibbon').enable
+# MethodTracer::Tracer.new(path: '/var/lib/gems/2.3.0/gems/other_gem-1.0.0/').enable

data/lib/method_tracer/tracer.rb

@@ -2,24 +2,26 @@ require 'where_is'
 
 module MethodTracer
   class Tracer
-    def initialize(target)
-      @target_path = target
+    def initialize(path:, name: nil)
+      @target_path = path
+      @target_name = name
+    end
 
+    def enable
       @tracer = TracePoint.trace(:call) do |tp|
         record_call_if_interesting(tp)
       end
     end
 
     def record_call_if_interesting(tp)
-      return unless class_is_interesting?(tp.defined_class)
+      return unless method_is_interesting?(tp.defined_class, tp.method_id)
 
       locations = caller_locations.select { |loc| loc.path.start_with?(Config.app_path) }
       return if locations.empty?
 
-      outfile.write "#{@target_path} :#{tp.method_id}\n"
-      locations.each do |loc|
-        outfile.write "#{loc.path}:#{loc.lineno}\n"
-      end
+      outfile.write "#{tp.defined_class} :#{tp.method_id} "
+      outfile.write locations.map { |loc| "#{loc.path}:#{loc.lineno}" }.join('; ')
+      outfile.write "\n"
     end
 
     def outfile
@@ -35,12 +37,28 @@ module MethodTracer
                    end
     end
 
-    def class_is_interesting?(candidate_class)
+    def method_is_interesting?(candidate_class, method_id)
+      candidate_name = if candidate_class.instance_of?(Class)
+                         candidate_class.name
+                       else
+                         candidate_class.class.name
+                       end
+
+      # short circuit if possible for speed
+      return false if !@target_name.nil? &&
+                      !candidate_name.nil? &&
+                      !candidate_name.include?(@target_name)
+
+      method_is_defined_in_target_path(candidate_class, method_id)
+    end
+
+    def method_is_defined_in_target_path(candidate_class, method_id)
       begin
-        location = Where.is(candidate_class)
+        location = Where.is(candidate_class, method_id)
       rescue NameError
         return false
       end
+
       location[:file].start_with?(@target_path)
     end
   end

data/lib/method_tracer/version.rb

@@ -1,3 +1,3 @@
 module MethodTracer
-  VERSION = '0.2.0'.freeze
+  VERSION = '1.0.0'.freeze
 end

data/run_tests.sh

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 if [ "$#" -ge 1 ]; then
-	name_arg=--name "$*"
+	name_arg="--name $*"
 else
 	name_arg=""
 fi

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: method_call_tracer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Eddie Lebow
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-25 00:00:00.000000000 Z
+date: 2018-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: where_is
@@ -50,6 +50,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rubocop.yml"
+- CHANGELOG.md
 - Gemfile
 - README.md
 - Rakefile