tapping_device 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31bb339b2993e3656c953c0c403b4145d3047722919f86ab4d0683c577379027
-  data.tar.gz: 76b0b6fab4f3998173960d3a0bce5bdc6faa8155bc49fe4ec3a0ecd0196e8feb
+  metadata.gz: 4000e62db2d9672d87d133a5c6adeeaf5eed9d134b4bd8b9a948887ee2d06f48
+  data.tar.gz: 477c9bf04c5a218aa8a23034929bcae7d0d52e663954380bfeb7b57f1290152c
 SHA512:
-  metadata.gz: 7641adbd68125ce2cb1a2fdb96969d09dcedc8d35b0c24fc1e0136badaca586bf7287631c3b6fecc7d3909958e0c49bd2d05d2de3b41845f680fb19165ccab1e
-  data.tar.gz: f9d685094c3f45b3e330c2725fc61bc01a9ae11cb5e486a1fec5de9a2131860cd64160e1d83753210529dc3383523d8072437e8ff285fc589b6bb6aafe5fcf5c
+  metadata.gz: 629ce1239a852d1bc1e9b7585ad7746273a5722139a08b24a8712448af9fc3201915eb3d882d7eed5300afaba590ee880e3db103a9fa9825d5304613e278ad23
+  data.tar.gz: f03e06164e74ceab8bbef4f0dec75795fab1866ba427dbcc570a4dac6bdf5a7ac3c166e0d4a2af7a6b042d1fd74cc9ad7465c960254fe6536258bd7fa1b81031

data/Gemfile.lock

@@ -1,30 +1,31 @@
 PATH
   remote: .
   specs:
-    tapping_device (0.1.0)
-      activerecord (~> 6.0)
+    tapping_device (0.1.1)
+      activerecord (~> 5.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (6.0.0)
-      activesupport (= 6.0.0)
-    activerecord (6.0.0)
-      activemodel (= 6.0.0)
-      activesupport (= 6.0.0)
-    activesupport (6.0.0)
+    activemodel (5.2.3)
+      activesupport (= 5.2.3)
+    activerecord (5.2.3)
+      activemodel (= 5.2.3)
+      activesupport (= 5.2.3)
+      arel (>= 9.0)
+    activesupport (5.2.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-      zeitwerk (~> 2.1, >= 2.1.8)
+    arel (9.0.0)
     coderay (1.1.2)
     concurrent-ruby (1.1.5)
     diff-lcs (1.3)
     i18n (1.7.0)
       concurrent-ruby (~> 1.0)
     method_source (0.9.2)
-    minitest (5.12.2)
+    minitest (5.13.0)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
@@ -42,11 +43,10 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.2)
-    sqlite3 (1.4.1)
+    sqlite3 (1.3.13)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    zeitwerk (2.2.0)
 
 PLATFORMS
   ruby
@@ -56,7 +56,7 @@ DEPENDENCIES
   pry
   rake (~> 10.0)
   rspec (~> 3.0)
-  sqlite3 (~> 1.4.1)
+  sqlite3 (~> 1.3.6)
   tapping_device!
 
 BUNDLED WITH

data/README.md

@@ -6,13 +6,13 @@
 
 ```ruby
 class PostsController < ApplicationController
-  include TappingDevice::Trackable
-
   def show
     @post = Post.find(params[:id])
-    tap_on!(@post) do |payload|
+
+    device = TappingDevice.new do |payload|
       puts "Method: #{payload[:method_name]} line: #{payload[:filepath]}:#{payload[:line_number]}"
     end
+    device.tap_on!(@post)
   end
 end
 ```
@@ -28,9 +28,10 @@ Method: to_param line: /RUBY_PATH/gems/2.6.0/gems/actionpack-5.2.0/lib/action_di
 Or you can use `tap_assoc!`. This is very useful for tracking potential n+1 query calls, here’s a sample from my work
 
 ```ruby
-tap_assoc!(order) do |payload|
+device = TappingDevice.new do |payload|
   puts "Assoc: #{payload[:method_name]} line: #{payload[:filepath]}:#{payload[:line_number]}"
 end
+device.tap_assoc!(order)
 ```
 
 ```
@@ -65,15 +66,44 @@ $ gem install tapping_device
 ```
 
 ## Usage
-In order to use `tapping_device`, you need to include `TappingDevice::Trackable` module in where you want to track your code.
 
-### Methods
-- `tap_init!(class)` -  tracks a class’ instance initialization
-- `tap_on!(object)` - tracks any calls received by the object
-- `tap_assoc!(activerecord_object)` - tracks association calls on a record, like `post.comments`
-- `untap!(object)` - this stops tapping on the given object
+### Create a device object
+In order to tap on something, you need to first initialize a tapping device with a block that process the call info.
+
+```ruby
+device = TappingDevice.new do |payload|
+  if payload[:method_name].to_s.match?(/foo/)
+    puts "Method: #{payload[:method_name]} line: #{payload[:filepath]}:#{payload[:line_number]}"
+  end
+end
+```
+
+### Performance issue and setup stop condition
+
+Because `tapping_device` is built upon `TracePoint`, which literally scans **every method call** on **every object**. Even if we filter out the calls we’re not interested in, just filtering out through those method calls takes time if your application isn’t a small one. So it’s very important to stop the tapping device at a certain point. You can do this in 2 ways:
+
+#### Use `device.stop_when(&block)` to set a stop condition
+To define a stop condition, you can use `stop_when` method.
 
-### Info of the call
+```ruby
+device.stop_when do |payload|
+  device.calls.count >= 10 # stop after gathering 10 calls' data
+end
+```
+
+**If you don’t set a stop condition, you need to use tapping methods that has exclamation mark**, like `device.tap_on!(post)`.
+
+#### `device.stop!`
+If you don’t define a stop condition, you can also use `device.stop!` to stop it manually.
+
+### Start tapping
+
+#### Methods
+- `TappingDevice#tap_init(class)` -  tracks a class’ instance initialization
+- `TappingDevice#tap_on(object)` - tracks any calls received by the object
+- `TappingDevice#tap_assoc(activerecord_object)` - tracks association calls on a record, like `post.comments`
+
+#### Info of the call
 All tapping methods (start with `tap_`) takes a block and yield a hash as block argument. 
 
 ```ruby
@@ -110,34 +140,14 @@ The hash contains
 - `exclude_by_paths: [/path/]` - an array of call path patterns that we want to skip. This could be very helpful when working on large project like Rails applications.
 - `filter_by_paths: [/path/]` - only contain calls from the specified paths
 
-```ruby
-tap_on!(@post, exclude_by_paths: [/active_record/]) do |payload|
-  puts "Method: #{payload[:method_name]} line: #{payload[:filepath]}:#{payload[:line_number]}"
-end
-```
-
-```
-Method: _read_attribute line: /RUBY_PATH/gems/2.6.0/gems/activerecord-5.2.0/lib/active_record/attribute_methods/read.rb:40
-Method: name line: /PROJECT_PATH/sample/app/views/posts/show.html.erb:5
-Method: _read_attribute line: /RUBY_PATH/gems/2.6.0/gems/activerecord-5.2.0/lib/active_record/attribute_methods/read.rb:40
-Method: user_id line: /PROJECT_PATH/sample/app/views/posts/show.html.erb:10
-.......
-
-# versus
-
-Method: name line: /PROJECT_PATH/sample/app/views/posts/show.html.erb:5
-Method: user_id line: /PROJECT_PATH/sample/app/views/posts/show.html.erb:10
-Method: to_param line: /RUBY_PATH/gems/2.6.0/gems/actionpack-5.2.0/lib/action_dispatch/routing/route_set.rb:236
-```
-
-
-### `#tap_init!`
+### `#tap_init`
 
 ```ruby
 calls = []
-tap_init!(Student) do |payload|
+device = TappingDevice.new do |payload|
   calls << [payload[:method_name], payload[:arguments]]
 end
+device.tap_init!(Student) 
 
 Student.new("Stan", 18)
 Student.new("Jane", 23)
@@ -149,16 +159,16 @@ puts(calls.to_s) #=> [[:initialize, [[:name, "Stan"], [:age, 18]]], [:initialize
 
 ```ruby
 class PostsController < ApplicationController
-  include TappingDevice::Trackable
-
   before_action :set_post, only: [:show, :edit, :update, :destroy]
 
   # GET /posts/1
   # GET /posts/1.json
   def show
-    tap_on!(@post) do |payload|
+    device = TappingDevice.new do |payload|
       puts "Method: #{payload[:method_name]} line: #{payload[:filepath]}:#{payload[:line_number]}"
     end
+
+    device.tap_on!(@post)
   end
 end
 ```
@@ -174,9 +184,10 @@ Method: to_param line: /RUBY_PATH/gems/2.6.0/gems/actionpack-5.2.0/lib/action_di
 ### `tap_assoc!`
 
 ```ruby
-tap_assoc!(order) do |payload|
+device = TappingDevice.new do |payload|
   puts "Assoc: #{payload[:method_name]} line: #{payload[:filepath]}:#{payload[:line_number]}"
 end
+device.tap_assoc!(order) 
 ```
 
 ```
@@ -187,6 +198,20 @@ Assoc: amending_orders line: /MY_PROJECT/app/models/order.rb:385
 Assoc: amends_order line: /MY_PROJECT/app/models/order.rb:432
 ```
 
+### Device states & Managing Devices
+
+Every `TappingDevice` instance can have 3 states:
+
+- `Initial` - means the instance is initialized but hasn’t been used to tap on anything.
+- `Enabled` - means the instance has started to tap on something (has called `tap_*` methods).
+- `Disabled` - means the instance has been disabled. It will no longer receive any call info.
+
+When debugging, we may create many device instances and tap objects in several places. Then it’ll be quite annoying to manage their states. So `TappingDevice` has several class methods that allows you to manage all `TappingDevice` instances:
+
+- `TappingDevice.devices` - Lists all registered devices with `initial` or `enabled` state. Note that any instance that’s been stopped  will be removed from the list.
+- `TappingDevice.stop_all!` - Stops all registered devices and remove them from the `devices` list.
+- `TappingDevice.suspend_new!` - Suspends any device instance from changing their state from `initatial` to `enabled`. Which means any  `tap_*` calls after it will no longer work. 
+- `TappingDevice.reset!` - Cancels `suspend_new` (if called) and stops/removes all created devices. Useful to reset environment between test cases.
 
 ## Development
 

data/lib/tapping_device.rb

@@ -1,7 +1,170 @@
+require "active_record"
 require "tapping_device/version"
 require "tapping_device/trackable"
+require "tapping_device/exceptions"
 
-module TappingDevice
-  class Error < StandardError; end
-  # Your code goes here...
+class TappingDevice
+  CALLER_START_POINT = 2
+  FORCE_STOP_WHEN_MESSAGE = "You must set stop_when condition before start tapping"
+
+  attr_reader :options, :calls, :trace_point
+
+  @@devices = []
+  @@suspend_new = false
+
+  # list all registered devices
+  def self.devices
+    @@devices
+  end
+
+  # disable given device and remove it from registered list
+  def self.delete_device(device)
+    device.trace_point&.disable
+    @@devices -= [device]
+  end
+
+  # stops all registered devices and remove them from registered list
+  def self.stop_all!
+    @@devices.each(&:stop!)
+  end
+
+  # suspend enabling new trace points
+  # user can still create new Device instances, but they won't be functional
+  def self.suspend_new!
+    @@suspend_new = true
+  end
+
+  # reset everything to clean state and disable all devices
+  def self.reset!
+    @@suspend_new = false
+    stop_all!
+  end
+
+  def initialize(options = {}, &block)
+    @block = block
+    @options = options
+    @calls = []
+    self.class.devices << self
+  end
+
+  def tap_init!(klass)
+    raise "argument should be a class, got #{klass}" unless klass.is_a?(Class)
+    track(klass, condition: :tap_init?, block: @block, **@options)
+  end
+
+  def tap_on!(object)
+    track(object, condition: :tap_on?, block: @block, **@options)
+  end
+
+  def tap_assoc!(record)
+    raise "argument should be an instance of ActiveRecord::Base" unless record.is_a?(ActiveRecord::Base)
+    track(record, condition: :tap_associations?, block: @block, **@options)
+  end
+
+  def tap_init(klass)
+    validate_tapping(__method__)
+    tap_init!(klass)
+  end
+
+  def tap_on(object)
+    validate_tapping(__method__)
+    tap_on!(object)
+  end
+
+  def tap_assoc(record)
+    validate_tapping(__method__)
+    tap_assoc!(record)
+  end
+
+  def set_block(&block)
+    @block = block
+  end
+
+  def stop!
+    self.class.delete_device(self)
+  end
+
+  def stop_when(&block)
+    @stop_when = block
+  end
+
+  private
+
+  def validate_tapping(method_name)
+    unless @stop_when
+      raise TappingDevice::Exception.new <<~ERROR
+        You must set stop_when condition before calling #{method_name}. Or you can use #{method_name}! to force tapping.
+        Tapping without stop condition can largely slow down or even halt your application, because it'll need to
+        screen literally every call happened.
+      ERROR
+    end
+  end
+
+  def track(object, condition:, block:, with_trace_to: nil, exclude_by_paths: [], filter_by_paths: nil)
+    @trace_point = TracePoint.new(:return) do |tp|
+      filepath, line_number = caller(CALLER_START_POINT).first.split(":")[0..1]
+
+      # this needs to be placed upfront so we can exclude noise before doing more work
+      next if exclude_by_paths.any? { |pattern| pattern.match?(filepath) }
+
+      if filter_by_paths
+        next unless filter_by_paths.any? { |pattern| pattern.match?(filepath) }
+      end
+
+      arguments = tp.binding.local_variables.map { |n| [n, tp.binding.local_variable_get(n)] }
+
+      yield_parameters = {
+        receiver: tp.self,
+        method_name: tp.callee_id,
+        arguments: arguments,
+        return_value: (tp.return_value rescue nil),
+        filepath: filepath,
+        line_number: line_number,
+        defined_class: tp.defined_class,
+        trace: [],
+        tp: tp
+      }
+
+      yield_parameters[:trace] = caller[CALLER_START_POINT..(CALLER_START_POINT + with_trace_to)] if with_trace_to
+
+      if send(condition, object, yield_parameters)
+        if @block
+          @calls << block.call(yield_parameters)
+        else
+          @calls << yield_parameters
+        end
+      end
+
+      stop! if @stop_when&.call(yield_parameters)
+    end
+
+    @trace_point.enable unless @@suspend_new
+
+    self
+  end
+
+  private
+
+  def tap_init?(klass, parameters)
+    receiver = parameters[:receiver]
+    method_name = parameters[:method_name]
+
+    if klass.ancestors.include?(ActiveRecord::Base)
+      method_name == :new && receiver.ancestors.include?(klass)
+    else
+      method_name == :initialize && receiver.is_a?(klass)
+    end
+  end
+
+  def tap_on?(object, parameters)
+    parameters[:receiver].object_id == object.object_id
+  end
+
+  def tap_associations?(object, parameters)
+    return false unless tap_on?(object, parameters)
+
+    model_class = object.class
+    associations = model_class.reflections
+    associations.keys.include?(parameters[:method_name].to_s)
+  end
 end

data/lib/tapping_device/exceptions.rb

@@ -0,0 +1,4 @@
+class TappingDevice
+  class Exception < StandardError
+  end
+end

data/lib/tapping_device/trackable.rb

@@ -1,98 +1,15 @@
-require "active_record"
-
-module TappingDevice
+class TappingDevice
   module Trackable
-    TAPPING_DEVICE = :@tapping_device
-    CALLER_START_POINT = 2
-
-    def tap_initialization_of!(klass, options = {}, &block)
-      raise "argument should be a class, got #{klass}" unless klass.is_a?(Class)
-      track(klass, condition: :tap_init?, block: block, **options)
-    end
-
-    def tap_association_calls!(record, options = {}, &block)
-      raise "argument should be an instance of ActiveRecord::Base" unless record.is_a?(ActiveRecord::Base)
-      track(record, condition: :tap_associations?, block: block, **options)
-    end
-
-    def tap_calls_on!(object, options = {}, &block)
-      track(object, condition: :tap_on?, block: block, **options)
-    end
-
-    def stop_tapping!(object)
-      get_tapping_device(object)&.each { |tp| tp.disable }
-    end
-
-    alias :tap_init! :tap_initialization_of!
-    alias :tap_assoc! :tap_association_calls!
-    alias :tap_on! :tap_calls_on!
-    alias :untap! :stop_tapping!
-
-    private
-
-    def track(object, condition:, block:, with_trace_to: nil, exclude_by_paths: [], filter_by_paths: nil)
-      trace_point = TracePoint.trace(:return) do |tp|
-        filepath, line_number = caller(CALLER_START_POINT).first.split(":")[0..1]
-
-        # this needs to be placed upfront so we can exclude noise before doing more work
-        next if exclude_by_paths.any? { |pattern| pattern.match?(filepath) }
-
-        if filter_by_paths
-          next unless filter_by_paths.any? { |pattern| pattern.match?(filepath) }
-        end
-
-        arguments = tp.binding.local_variables.map { |n| [n, tp.binding.local_variable_get(n)] }
-
-        yield_parameters = {
-          receiver: tp.self,
-          method_name: tp.callee_id,
-          arguments: arguments,
-          return_value: (tp.return_value rescue nil),
-          filepath: filepath,
-          line_number: line_number,
-          defined_class: tp.defined_class,
-          trace: [],
-          tp: tp
-        }
-
-        yield_parameters[:trace] = caller[CALLER_START_POINT..(CALLER_START_POINT + with_trace_to)] if with_trace_to
-
-        block.call(yield_parameters) if send(condition, object, yield_parameters)
-      end
-
-      add_tapping_device(object, trace_point)
-    end
-
-    def tap_init?(klass, parameters)
-      receiver = parameters[:receiver]
-      method_name = parameters[:method_name]
-
-      if klass.ancestors.include?(ActiveRecord::Base)
-        method_name == :new && receiver.ancestors.include?(klass)
-      else
-        method_name == :initialize && receiver.is_a?(klass)
-      end
-    end
-
-    def tap_on?(object, parameters)
-      parameters[:receiver].object_id == object.object_id
-    end
-
-    def tap_associations?(object, parameters)
-      return false unless tap_on?(object, parameters)
-
-      model_class = object.class
-      associations = model_class.reflections
-      associations.keys.include?(parameters[:method_name].to_s)
+    def tap_init!(klass, options = {}, &block)
+      TappingDevice.new(options, &block).tap_init!(klass)
     end
 
-    def get_tapping_device(object)
-      object.instance_variable_get(TAPPING_DEVICE)
+    def tap_assoc!(record, options = {}, &block)
+      TappingDevice.new(options, &block).tap_assoc!(record)
     end
 
-    def add_tapping_device(object, trace_point)
-      object.instance_variable_set(TAPPING_DEVICE, []) unless get_tapping_device(object)
-      object.instance_variable_get(TAPPING_DEVICE) << trace_point
+    def tap_on!(object, options = {}, &block)
+      TappingDevice.new(options, &block).tap_on!(object)
     end
   end
 end

data/lib/tapping_device/version.rb

@@ -1,3 +1,3 @@
-module TappingDevice
-  VERSION = "0.1.1"
+class TappingDevice
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tapping_device
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - st0012
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-20 00:00:00.000000000 Z
+date: 2019-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -115,6 +115,7 @@ files:
 - bin/console
 - bin/setup
 - lib/tapping_device.rb
+- lib/tapping_device/exceptions.rb
 - lib/tapping_device/trackable.rb
 - lib/tapping_device/version.rb
 - tapping_device.gemspec