tapping_device 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9311ddb749d3c7bf09306161da25191c0de47734dea77f645f5d5af62a55d802
-  data.tar.gz: 4df7c9fef5c3a3a2b3852b5b4f4db31ec071149dd19b3fceb1df6f6b1ac191e8
+  metadata.gz: 231efa59a44f630df303db52d0d3bb460698c02a116374838e4bad4d71d7f69e
+  data.tar.gz: ca80df8a0ea00350c1e074628425848b5cba4d7f53a7aa4176947d55a3164929
 SHA512:
-  metadata.gz: deaece3e6096551df6fe3c7eb492f6049e72b32f7e19b7a8d4067f8d5a6dc9b6fe56a41d3bd9855220ae11c8adcc377cd188f51c043835845be5c2d9250bc6d1
-  data.tar.gz: 057766f277605fb3e80bd2797ee1256f0f6d81fbca56c95226199a72c7e14565dc353292d06711847e257d2f552e9eb3ddcd076ec35f1abd3aaf30cc9f686f5c
+  metadata.gz: 77131aab9e85a2661694ee57470b9067ee44d479d574cbe395eefabd7f88350eaf31071c4ed0d117b1608856e9e6beff9d7ccae592a665c8969231425dafdc43
+  data.tar.gz: c06dedd14da7798cf93d80ae0d4866928c9e2522184f453588691fdf1a3220b21cfdf953f04575f1015cc1cb58c5bcb2cb5673fd9384cf5515855d048d0bbdb3

data/CHANGELOG.md

@@ -1,16 +1,18 @@
 # Changelog
 
-## [Unreleased](https://github.com/st0012/tapping_device/tree/HEAD)
+## [v0.5.3](https://github.com/st0012/tapping_device/tree/v0.5.3) (2020-06-21)
 
-[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.2...HEAD)
+[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.2...v0.5.3)
 
 **Closed issues:**
 
+- Global Configuration [\#46](https://github.com/st0012/tapping_device/issues/46)
 - Support write\_\* helpers [\#44](https://github.com/st0012/tapping_device/issues/44)
 - Use Method\#source to replace Payload\#method\_head’s implementation  [\#19](https://github.com/st0012/tapping_device/issues/19)
 
 **Merged pull requests:**
 
+- Support Global Configuration [\#48](https://github.com/st0012/tapping_device/pull/48) ([st0012](https://github.com/st0012))
 - Support write\_\* helpers [\#47](https://github.com/st0012/tapping_device/pull/47) ([st0012](https://github.com/st0012))
 - Hijack attr methods with `hijack\_attr\_methods` option [\#45](https://github.com/st0012/tapping_device/pull/45) ([st0012](https://github.com/st0012))
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    tapping_device (0.5.3)
+    tapping_device (0.5.4)
       activerecord (>= 5.2)
       activesupport
       pry
@@ -56,7 +56,7 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.7)
       thread_safe (~> 0.1)
-    zeitwerk (2.3.0)
+    zeitwerk (2.3.1)
 
 PLATFORMS
   ruby

data/README.md

@@ -8,187 +8,119 @@
 
 
 ## Introduction
-`TappingDevice` makes the objects tell you what they do, so you don't need to track them yourself.
+As the name states, `TappingDevice` allows you to secretly listen to different events of an object:
 
-#### Contact Tracing For Objects
+- `Method Calls` - what does the object do
+- `Traces` - how is the object used by the application
+- `State Mutations` - what happens inside the object
 
-The concept is very simple. It's basically like [contact tracing](https://en.wikipedia.org/wiki/Contact_tracing) for your Ruby objects. You can use 
+After collecting the events, `TappingDevice` will output them in a nice, readable format to either stdout or a file. 
 
-- `print_calls(object)` to see what the object does
-- `print_traces(object)` to see how the object interacts with other objects (like used as an argument)
-- `print_mutations(object)` to see what actions changed the object's state (instance variables)
+**Ultimately, its goal is to let you know all the information you need for debugging with just 1 line of code.**
 
-Still sounds vague? Let's see some examples:
+## Usages
 
-### `print_calls` - Track Method Calls
+### Track Method Calls
 
-In [Discourse](https://github.com/discourse/discourse), it uses the `Guardian` class for authorization (like policy objects). It's barely visible in controller actions, but it does many checks under the hood. Now, let's say we want to know what the `Guardian` would do when a user creates a post; here's the controller action:
-
-```ruby
-  def create
-    @manager_params = create_params
-    @manager_params[:first_post_checks] = !is_api?
-
-    manager = NewPostManager.new(current_user, @manager_params)
-
-    if is_api?
-      memoized_payload = DistributedMemoizer.memoize(signature_for(@manager_params), 120) do
-        result = manager.perform
-        MultiJson.dump(serialize_data(result, NewPostResultSerializer, root: false))
-      end
-
-      parsed_payload = JSON.parse(memoized_payload)
-      backwards_compatible_json(parsed_payload, parsed_payload['success'])
-    else
-      result = manager.perform
-      json = serialize_data(result, NewPostResultSerializer, root: false)
-      backwards_compatible_json(json, result.success?)
-    end
-  end
-```
-
-As you can see, it doesn't even exist in the controller action, which makes tracking it by reading code very hard to do.
-
-But with `TappingDevice`. You can use `print_calls` to show what method calls the object performs
-
-```ruby
-  def create
-    # you can retrieve the current guardian object by calling guardian in the controller
-    print_calls(guardian)
-    @manager_params = create_params
-   
-    # .....
-```
-
-Now, if you execute the code, like via tests:
-
-```shell
-$ rspec spec/requests/posts_controller_spec.rb:603
-```
-
-You can get all the method calls it performs with basically everything you need to know
+By tracking an object's method calls, you'll be able to observe the object's behavior very easily
 
 <img src="https://github.com/st0012/tapping_device/blob/master/images/print_calls.png" alt="image of print_calls output" width="50%">
 
-Let's take a closer look at each entry. Everyone of them contains the method call's
-- method name 
-- method source class/module
+Each entry consists of 5 pieces of information:
+- method name
+- source of the method
 - call site
 - arguments
 - return value
 
 ![explanation of individual entry](https://github.com/st0012/tapping_device/blob/master/images/print_calls%20-%20single%20entry.png)
 
-These are the information you'd have to look up one by one manually (probably with many debug code writing). Now you can get all of them in just one line of code.
+#### Helpers
 
+- `print_calls(object)` - prints the result to stdout
+- `write_calls(object, log_file: "file_name")` - writes the result to a file
+	- the default file is `/tmp/tapping_device.log`, but you can change it with `log_file: "new_path"` option
 
-### `print_traces` - See The Object's Traces
+#### Use Cases
+- Understand a service object/form object's behavior
+- Debug a messy controller
 
-If you're not interested in what an object does, but what it interacts with other parts of the program, e.g., used as arguments. You can use the `print_traces` helper. Let's see how `Discourse` uses the `manager` object when creating a post
+### Track Traces
 
-```ruby
-  def create
-    @manager_params = create_params
-    @manager_params[:first_post_checks] = !is_api?
-   
-    manager = NewPostManager.new(current_user, @manager_params)
-
-    print_traces(manager)
-    # .....
-```
+By tracking an object's traces, you'll be able to observe the object's journey in your application
 
-And after running the test case
+![image of print_traces output](https://github.com/st0012/tapping_device/blob/master/images/print_traces.png)
 
-```shell
-$ rspec spec/requests/posts_controller_spec.rb:603
-```
+#### Helpers
 
-You will see that it performs 2 calls: `perform` and `perform_create_post`. And it's also used as `manager` argument in various of calls of the `NewPostManager` class.
+- `print_traces(object)` - prints the result to stdout
+- `write_traces(object, log_file: "file_name")` - writes the result to a file
+	- the default file is `/tmp/tapping_device.log`, but you can change it with `log_file: "new_path"` option
 
-![image of print_traces output](https://github.com/st0012/tapping_device/blob/master/images/print_traces.png)
+#### Use Cases
+- Debug argument related issues
+- Understand how a library uses your objects
 
-### `print_mutations` - Display All State Changes At Once
+### Track State Mutations
 
-Another thing that often bothers developers in debugging is to track an object's internal state changes. And `tapping_device` allows you to see all state changes with just one line of code. Let me keep using [Discourse](https://github.com/discourse/discourse) to demonstrate it. 
+By tracking an object's traces, you'll be able to observe the state changes happen inside the object between each method call
 
-When updating a post, it uses an object called `PostRevisor` to revise it:
+<img src="https://github.com/st0012/tapping_device/blob/master/images/print_mutations.png" alt="image of print_mutations output" width="50%">
 
-```ruby
-# app/controllers/posts_controller.rb
-class PostsController
-  def update
-    # ......
-    revisor = PostRevisor.new(post, topic)
-    revisor.revise!(current_user, changes, opts)
-    # ......
-  end
-end
-```
+#### Helpers
 
-In the `PostReviser#revise!`, it uses many instance variables to track different information:
+- `print_mutations(object)` - prints the result to stdout
+- `write_mutations(object, log_file: "file_name")` - writes the result to a file
+	- the default file is `/tmp/tapping_device.log`, but you can change it with `log_file: "new_path"` option
 
-```ruby
-  # lib/post_revisor.rb
-  def revise!(editor, fields, opts = {})
-    @editor = editor
-    @fields = fields.with_indifferent_access
-    @opts = opts
+#### Use Cases
+- Debug state related issues
+- Debug memoization issues
 
-    @topic_changes = TopicChanges.new(@topic, editor)
-    
-    # ......
+### Track All Instances Of A Class
 
-    @revised_at = @opts[:revised_at] || Time.now
-    @last_version_at = @post.last_version_at || Time.now
+It's not always easy to directly access the objects we want to track, especially when they're managed by a library (e.g. `ActiveRecord::Relation`). In such cases, you can use these helpers to track the class's instances:
 
-    @version_changed = false
-    @post_successfully_saved = true
+- `print_instance_calls(ObjectKlass)`
+- `print_instance_traces(ObjectKlass)`
+- `print_instance_mutations(ObjectKlass)`
+- `write_instance_calls(ObjectKlass)`
+- `write_instance_traces(ObjectKlass)`
+- `write_instance_mutations(ObjectKlass)`
 
-    @validate_post = true
-    # ......
-  end
-```
 
-Tracking the changes of that many instance variables can be a painful task, especially when we want to know the values before and after certain method call. This is why I created `print_mutations` to save us from this. 
+### Use `with_HELPER_NAME` for chained method calls
 
-Like other helpers, you only need 1 line of code
+In Ruby programs, we often chain multiple methods together like this:
 
 ```ruby
-# app/controllers/posts_controller.rb
-class PostsController
-  def update
-    # ......
-    revisor = PostRevisor.new(post, topic)
-    print_mutations(revisor)
-    revisor.revise!(current_user, changes, opts)
-    # ......
-  end
-end
+SomeService.new(params).perform
 ```
 
-And then you'll see all the state changes:
+And to debug it, we'll need to break the method chain into
 
-<img src="https://github.com/st0012/tapping_device/blob/master/images/print_mutations.png" alt="image of print_mutations output" width="50%">
-
-Now you can see what method changes which states. And more importantly, you get to see all the sate changes at once!
-
-**You can try these examples on [my fork of discourse](https://github.com/st0012/discourse/tree/demo-for-tapping-device)**
+```ruby
+service = SomeService.new(params)
+print_calls(service, options)
+service.perform
+```
 
-### `write_*` helpers
+This kind of code changes are usually annoying, and that's one of the problems I want to solve with `TappingDevice`.
 
-`tapping_device` also provides helpers that write the events into files:
+So here's another option, just insert a `with_HELPER_NAME` call in between:
 
-- `write_calls(object)`
-- `write_traces(object)`
-- `write_mutations(object)`
+```ruby
+SomeService.new(params).with_print_calls(options).perform
+```
 
-The default destination is `/tmp/tapping_device.log`. You can change it with the `log_file`  option:
+And it'll behave exactly like
 
 ```ruby
-write_calls(object, log_file: "/tmp/another_file")
+service = SomeService.new(params)
+print_calls(service, options)
+service.perform
 ```
 
-
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -296,6 +228,40 @@ The default is `false` because
 2. It's still unclear if this hack safe enough for most applications.
 
 
+#### `ignore_private`
+
+Sometimes we use many private methods to perform trivial operations, like
+
+```ruby
+class Operation
+  def extras
+    dig_attribute("extras")
+  end
+
+  private
+
+  def data
+    @data
+  end
+
+  def dig_attribute(attr)
+    data.dig("attributes", attr) 
+  end
+end
+```
+
+And we may not be interested in those method calls. If that's the case, you can use the `ignore_private` option
+
+```ruby
+operation = Operation.new(params)
+print_calls(operation, ignore_private: true) #=> only prints the `extras` call
+```
+
+#### `only_private`
+
+This option does the opposite of the `ignore_private` option does.
+
+
 ### Global Configuration
 
 If you don't want to pass options every time you use a helper, you can use global configuration to change the default values:
@@ -341,3 +307,4 @@ The gem is available as open-source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the TappingDevice project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/tapping_device/blob/master/CODE_OF_CONDUCT.md).
+

data/lib/tapping_device.rb

@@ -34,7 +34,7 @@ class TappingDevice
   def initialize(options = {}, &block)
     @block = block
     @output_block = nil
-    @options = process_options(options)
+    @options = process_options(options.dup)
     @calls = []
     @disabled = false
     @with_condition = nil
@@ -94,15 +94,19 @@ class TappingDevice
   private
 
   def build_minimum_trace_point(event_type:)
-    TracePoint.new(event_type) do |tp|
+    TracePoint.new(*event_type) do |tp|
       next unless filter_condition_satisfied?(tp)
-      next if is_tapping_device_call?(tp)
 
       filepath, line_number = get_call_location(tp)
       payload = build_payload(tp: tp, filepath: filepath, line_number: line_number)
 
-      next if should_be_skipped_by_paths?(filepath)
-      next unless with_condition_satisfied?(payload)
+      unless @options[:force_recording]
+        next if is_tapping_device_call?(tp)
+        next if should_be_skipped_by_paths?(filepath)
+        next unless with_condition_satisfied?(payload)
+        next if payload.is_private_call? && @options[:ignore_private]
+        next if !payload.is_private_call? && @options[:only_private]
+      end
 
       yield(payload)
     end
@@ -148,6 +152,7 @@ class TappingDevice
       line_number: line_number,
       defined_class: tp.defined_class,
       trace: get_traces(tp),
+      is_private_call?: tp.defined_class.private_method_defined?(tp.callee_id),
       tp: tp
     })
   end
@@ -204,6 +209,10 @@ class TappingDevice
     options[:event_type] ||= config[:event_type]
     options[:hijack_attr_methods] ||= config[:hijack_attr_methods]
     options[:track_as_records] ||= config[:track_as_records]
+    options[:ignore_private] ||= config[:ignore_private]
+    options[:only_private] ||= config[:only_private]
+    # for debugging the gem more easily
+    options[:force_recording] ||= false
 
     options[:descendants] ||= []
     options[:root_device] ||= self

data/lib/tapping_device/configurable.rb

@@ -12,6 +12,8 @@ class TappingDevice
       event_type: :return,
       hijack_attr_methods: false,
       track_as_records: false,
+      ignore_private: false,
+      only_private: false
     }.merge(TappingDevice::Output::DEFAULT_OPTIONS)
 
     included do

data/lib/tapping_device/output/payload.rb

@@ -7,7 +7,11 @@ class TappingDevice
       alias :raw_return_value :return_value
 
       def method_name(options = {})
-        ":#{super(options)}"
+        if is_private_call?
+          ":#{super(options)} (private)"
+        else
+          ":#{super(options)}"
+        end
       end
 
       def arguments(options = {})

data/lib/tapping_device/payload.rb

@@ -2,7 +2,7 @@ class TappingDevice
   class Payload < Hash
     ATTRS = [
       :target, :receiver, :method_name, :method_object, :arguments, :return_value, :filepath, :line_number,
-      :defined_class, :trace, :tp, :ivar_changes
+      :defined_class, :trace, :tp, :ivar_changes, :is_private_call?
     ]
 
     ATTRS.each do |attr|

data/lib/tapping_device/trackable.rb

@@ -20,28 +20,29 @@ class TappingDevice
       TappingDevice::Trackers::MutationTracker.new(options, &block).track(object)
     end
 
-    def print_traces(target, options = {})
-      output_traces(target, options, output_action: :and_print)
-    end
+    [:calls, :traces, :mutations].each do |subject|
+      [:print, :write].each do |output_action|
+        helper_method_name = "#{output_action}_#{subject}"
 
-    def write_traces(target, options = {})
-      output_traces(target, options, output_action: :and_write)
-    end
+        define_method helper_method_name do |target, options = {}|
+          send("output_#{subject}", target, options, output_action: "and_#{output_action}")
+        end
 
-    def print_calls(target, options = {})
-      output_calls(target, options, output_action: :and_print)
-    end
+        define_method "with_#{helper_method_name}" do |options = {}|
+          send(helper_method_name, self, options)
+          self
+        end
 
-    def write_calls(target, options = {})
-      output_calls(target, options, output_action: :and_write)
-    end
+        define_method "#{output_action}_instance_#{subject}" do |target_klass, options = {}|
+          collection_proxy = AsyncCollectionProxy.new
 
-    def print_mutations(target, options = {})
-      output_mutations(target, options, output_action: :and_print)
-    end
+          tap_init!(target_klass, options) do |payload|
+            collection_proxy << send(helper_method_name, payload.return_value, options)
+          end
 
-    def write_mutations(target, options = {})
-      output_mutations(target, options, output_action: :and_write)
+          collection_proxy
+        end
+      end
     end
 
     private
@@ -84,12 +85,15 @@ class TappingDevice
       [options, output_options]
     end
 
+    # CollectionProxy delegates chained actions to multiple devices
     class CollectionProxy
+      CHAINABLE_ACTIONS = [:stop!, :stop_when, :with]
+
       def initialize(devices)
         @devices = devices
       end
 
-      [:stop!, :stop_when, :with].each do |method|
+      CHAINABLE_ACTIONS.each do |method|
         define_method method do |&block|
           @devices.each do |device|
             device.send(method, &block)
@@ -97,6 +101,32 @@ class TappingDevice
         end
       end
     end
+
+    # AsyncCollectionProxy delegates chained actions to multiple device "asyncronously"
+    # when we use tapping methods like `tap_init!` to create sub-devices
+    # we need to find a way to pass the chained actions to every sub-device that's created
+    # and this can only happen asyncronously as we won't know when'll that happen
+    class AsyncCollectionProxy < CollectionProxy
+      def initialize(devices = [])
+        super
+        @blocks = {}
+      end
+
+      CHAINABLE_ACTIONS.each do |method|
+        define_method method do |&block|
+          super(&block)
+          @blocks[method] = block
+        end
+      end
+
+      def <<(device)
+        @devices << device
+
+        @blocks.each do |method, block|
+          device.send(method, &block)
+        end
+      end
+    end
   end
 end
 

data/lib/tapping_device/trackers/initialization_tracker.rb

@@ -1,6 +1,14 @@
 class TappingDevice
   module Trackers
     class InitializationTracker < TappingDevice
+      def initialize(options = {}, &block)
+        super
+        event_type = @options[:event_type]
+        # if a class doesn't override the 'initialize' method
+        # Class.new will only trigger c_return or c_call
+        @options[:event_type] = [event_type, "c_#{event_type}"]
+      end
+
       def build_payload(tp:, filepath:, line_number:)
         payload = super
         payload[:return_value] = payload[:receiver]

data/lib/tapping_device/version.rb

@@ -1,3 +1,3 @@
 class TappingDevice
-  VERSION = "0.5.3"
+  VERSION = "0.5.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tapping_device
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - st0012
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-21 00:00:00.000000000 Z
+date: 2020-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord