object_tracer 1.0.0

data/Gemfile

@@ -0,0 +1,20 @@
+source "https://rubygems.org"
+
+gemspec
+
+rails_version = ENV["RAILS_VERSION"]
+rails_version = "6.1.0" if rails_version.nil?
+
+if rails_version.to_f < 6
+  gem "sqlite3", "~> 1.3.0"
+else
+  gem "sqlite3"
+end
+
+gem "activerecord", "~> #{rails_version}"
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "simplecov", "~> 0.17.1"
+gem "database_cleaner", "~> 2.0.0"
+gem "pry"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 st0012
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Makefile

@@ -0,0 +1,3 @@
+test:
+	bundle exec rspec
+	WITH_ACTIVE_RECORD=true bundle exec rspec spec/active_record_spec.rb

data/README.md

@@ -0,0 +1,310 @@
+# ObjectTracer (previously called TappingDevice)
+
+![GitHub Action](https://github.com/st0012/object_tracer/workflows/Ruby/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/object_tracer.svg)](https://badge.fury.io/rb/object_tracer)
+[![Maintainability](https://api.codeclimate.com/v1/badges/3e3732a6983785bccdbd/maintainability)](https://codeclimate.com/github/st0012/object_tracer/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/3e3732a6983785bccdbd/test_coverage)](https://codeclimate.com/github/st0012/object_tracer/test_coverage)
+[![Open Source Helpers](https://www.codetriage.com/st0012/object_tracer/badges/users.svg)](https://www.codetriage.com/st0012/object_tracer)
+
+
+## Introduction
+As the name states, `ObjectTracer` allows you to secretly listen to different events of an object:
+
+- `Method Calls` - what does the object do
+- `Traces` - how is the object used by the application
+- `State Mutations` - what happens inside the object
+
+After collecting the events, `ObjectTracer` will output them in a nice, readable format to either stdout or a file. 
+
+**Ultimately, its goal is to let you know all the information you need for debugging with just 1 line of code.**
+
+## Usages
+
+### Track Method Calls
+
+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/object_tracer/blob/master/images/print_calls.png" alt="image of print_calls output" width="50%">
+
+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/object_tracer/blob/master/images/print_calls%20-%20single%20entry.png)
+
+#### 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/object_tracer.log`, but you can change it with `log_file: "new_path"` option
+
+#### Use Cases
+- Understand a service object/form object's behavior
+- Debug a messy controller
+
+### Track Traces
+
+By tracking an object's traces, you'll be able to observe the object's journey in your application
+
+![image of print_traces output](https://github.com/st0012/object_tracer/blob/master/images/print_traces.png)
+
+#### Helpers
+
+- `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/object_tracer.log`, but you can change it with `log_file: "new_path"` option
+
+#### Use Cases
+- Debug argument related issues
+- Understand how a library uses your objects
+
+### Track State Mutations
+
+By tracking an object's traces, you'll be able to observe the state changes happen inside the object between each method call
+
+<img src="https://github.com/st0012/object_tracer/blob/master/images/print_mutations.png" alt="image of print_mutations output" width="50%">
+
+#### Helpers
+
+- `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/object_tracer.log`, but you can change it with `log_file: "new_path"` option
+
+#### Use Cases
+- Debug state related issues
+- Debug memoization issues
+
+### Track All Instances Of A Class
+
+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:
+
+- `print_instance_calls(ObjectKlass)`
+- `print_instance_traces(ObjectKlass)`
+- `print_instance_mutations(ObjectKlass)`
+- `write_instance_calls(ObjectKlass)`
+- `write_instance_traces(ObjectKlass)`
+- `write_instance_mutations(ObjectKlass)`
+
+
+### Use `with_HELPER_NAME` for chained method calls
+
+In Ruby programs, we often chain multiple methods together like this:
+
+```ruby
+SomeService.new(params).perform
+```
+
+And to debug it, we'll need to break the method chain into
+
+```ruby
+service = SomeService.new(params)
+print_calls(service, options)
+service.perform
+```
+
+This kind of code changes are usually annoying, and that's one of the problems I want to solve with `ObjectTracer`.
+
+So here's another option, just insert a `with_HELPER_NAME` call in between:
+
+```ruby
+SomeService.new(params).with_print_calls(options).perform
+```
+
+And it'll behave exactly like
+
+```ruby
+service = SomeService.new(params)
+print_calls(service, options)
+service.perform
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'object_tracer', group: :development
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it directly:
+
+```
+$ gem install object_tracer
+```
+
+**Depending on the size of your application, `ObjectTracer` could harm the performance significantly.  So make sure you don't put it inside the production group**
+
+
+## Advance Usages & Options 
+
+### Add Conditions With `.with`
+
+Sometimes we don't need to know all the calls or traces of an object; we just want some of them. In those cases, we can chain the helpers with `.with` to filter the calls/traces.
+
+```ruby
+# only prints calls with name matches /foo/
+print_calls(object).with do |payload|
+  payload.method_name.to_s.match?(/foo/)
+end
+```
+
+### Options
+
+There are many options you can pass when using a helper method. You can list all available options and their default value with
+
+```ruby
+ObjectTracer::Configurable::DEFAULTS #=> {
+  :filter_by_paths=>[], 
+  :exclude_by_paths=>[], 
+  :with_trace_to=>50, 
+  :event_type=>:return, 
+  :hijack_attr_methods=>false, 
+  :track_as_records=>false, 
+  :inspect=>false, 
+  :colorize=>true, 
+  :log_file=>"/tmp/object_tracer.log"
+}
+```
+
+Here are some commonly used options:
+
+#### `colorize: false` 
+
+- default: `true`
+
+By default `print_calls` and `print_traces` colorize their output. If you don't want the colors, you can use `colorize: false` to disable it.
+
+
+```ruby
+print_calls(object, colorize: false)
+```
+
+
+#### `inspect: true` 
+
+- default: `false`
+
+As you might have noticed, all the objects are converted into strings with `#to_s` instead of `#inspect`.  This is because when used on some Rails objects, `#inspect` can generate a significantly larger string than `#to_s`. For example:
+
+``` ruby
+post.to_s #=> #<Post:0x00007f89a55201d0>
+post.inspect #=> #<Post id: 649, user_id: 3, topic_id: 600, post_number: 1, raw: "Hello world", cooked: "<p>Hello world</p>", created_at: "2020-05-24 08:07:29", updated_at: "2020-05-24 08:07:29", reply_to_post_number: nil, reply_count: 0, quote_count: 0, deleted_at: nil, off_topic_count: 0, like_count: 0, incoming_link_count: 0, bookmark_count: 0, score: nil, reads: 0, post_type: 1, sort_order: 1, last_editor_id: 3, hidden: false, hidden_reason_id: nil, notify_moderators_count: 0, spam_count: 0, illegal_count: 0, inappropriate_count: 0, last_version_at: "2020-05-24 08:07:29", user_deleted: false, reply_to_user_id: nil, percent_rank: 1.0, notify_user_count: 0, like_score: 0, deleted_by_id: nil, edit_reason: nil, word_count: 2, version: 1, cook_method: 1, wiki: false, baked_at: "2020-05-24 08:07:29", baked_version: 2, hidden_at: nil, self_edits: 0, reply_quoted: false, via_email: false, raw_email: nil, public_version: 1, action_code: nil, image_url: nil, locked_by_id: nil, image_upload_id: nil>
+```
+
+#### `hijack_attr_methods: true` 
+
+- default: `false`
+	- except for `tap_mutation!` and `print_mutations`
+	
+Because `TracePoint` doesn't track methods generated by `attr_*` helpers (see [this issue](https://bugs.ruby-lang.org/issues/16383) for more info), we need to redefine those methods with the normal method definition. 
+
+For example, it generates
+
+```ruby
+def name=(val)
+  @name = val
+end
+```
+
+for
+
+```ruby
+attr_writer :name
+```
+
+This hack will only be applied to the target instance with `instance_eval`. So other instances of the class remain untouched.
+
+The default is `false` because
+
+1. Checking what methods are generated by `attr_*` helpers isn't free. It's an `O(n)` operation, where `n` is the number of methods the target object has. 
+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:
+
+```ruby
+ObjectTracer.config[:colorize] = false
+ObjectTracer.config[:hijack_attr_methods] = true
+```
+
+And if you're using Rails, you can put the configs under `config/initializers/object_tracer.rb` like this:
+
+```ruby
+if defined?(ObjectTracer)
+  ObjectTracer.config[:colorize] = false
+  ObjectTracer.config[:hijack_attr_methods] = true
+end
+```
+
+
+### Lower-Level Helpers
+`print_calls` and `print_traces` aren't the only helpers you can get from `ObjectTracer`. They are actually built on top of other helpers, which you can use as well. To know more about them, please check [this page](https://github.com/st0012/object_tracer/wiki/Advance-Usages)
+
+
+### Related Blog Posts
+- [Optimize Your Debugging Process With Object-Oriented Tracing and object_tracer](http://bit.ly/object-oriented-tracing) 
+- [Debug Rails issues effectively with object_tracer](https://dev.to/st0012/debug-rails-issues-effectively-with-tappingdevice-c7c)
+- [Want to know more about your Rails app? Tap on your objects!](https://dev.to/st0012/want-to-know-more-about-your-rails-app-tap-on-your-objects-bd3)
+
+
+## Development
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/st0012/object_tracer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ObjectTracer project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/st0012/object_tracer/blob/master/CODE_OF_CONDUCT.md).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "object_tracer"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/object_tracer.rb

@@ -0,0 +1,258 @@
+require "method_source" # for using Method#source
+
+require "object_tracer/version"
+require "object_tracer/manageable"
+require "object_tracer/payload"
+require "object_tracer/output"
+require "object_tracer/trackable"
+require "object_tracer/configuration"
+require "object_tracer/exceptions"
+require "object_tracer/method_hijacker"
+require "object_tracer/trackers/initialization_tracker"
+require "object_tracer/trackers/passed_tracker"
+require "object_tracer/trackers/association_call_tracker"
+require "object_tracer/trackers/method_call_tracker"
+require "object_tracer/trackers/mutation_tracker"
+
+class ObjectTracer
+
+  CALLER_START_POINT = 3
+  C_CALLER_START_POINT = 2
+
+  attr_reader :options, :calls, :trace_point, :target
+
+  @devices = []
+  @suspend_new = false
+
+  extend Manageable
+
+  include Output::Helpers
+
+  def initialize(options = {}, &block)
+    @block = block
+    @output_block = nil
+    @options = process_options(options.dup)
+    @calls = []
+    @disabled = false
+    @with_condition = nil
+    ObjectTracer.devices << self
+  end
+
+  def with(&block)
+    @with_condition = block
+  end
+
+  def set_block(&block)
+    @block = block
+  end
+
+  def stop!
+    @disabled = true
+    ObjectTracer.delete_device(self)
+  end
+
+  def stop_when(&block)
+    @stop_when = block
+  end
+
+  def create_child_device
+    new_device = self.class.new(@options.merge(root_device: root_device), &@block)
+    new_device.stop_when(&@stop_when)
+    new_device.instance_variable_set(:@target, @target)
+    self.descendants << new_device
+    new_device
+  end
+
+  def root_device
+    options[:root_device]
+  end
+
+  def descendants
+    options[:descendants]
+  end
+
+  def track(object)
+    @target = object
+    validate_target!
+
+    MethodHijacker.new(@target).hijack_methods! if options[:hijack_attr_methods]
+
+    @trace_point = build_minimum_trace_point(event_type: options[:event_type]) do |payload|
+      record_call!(payload)
+
+      stop_if_condition_fulfilled!(payload)
+    end
+
+    @trace_point.enable unless ObjectTracer.suspend_new
+
+    self
+  end
+
+  private
+
+  def build_minimum_trace_point(event_type:)
+    TracePoint.new(*event_type) do |tp|
+      next unless filter_condition_satisfied?(tp)
+
+      filepath, line_number = get_call_location(tp)
+      payload = build_payload(tp: tp, filepath: filepath, line_number: line_number)
+
+      unless @options[:force_recording]
+        next if is_object_tracer_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
+  end
+
+  def validate_target!; end
+
+  def filter_condition_satisfied?(tp)
+    false
+  end
+
+  # this needs to be placed upfront so we can exclude noise before doing more work
+  def should_be_skipped_by_paths?(filepath)
+    exclude_by_paths = options[:exclude_by_paths]
+    filter_by_paths = options[:filter_by_paths]
+    exclude_by_paths.any? { |pattern| pattern.match?(filepath) } ||
+      (filter_by_paths && !filter_by_paths.empty? && !filter_by_paths.any? { |pattern| pattern.match?(filepath) })
+  end
+
+  def is_object_tracer_call?(tp)
+    if tp.defined_class == ObjectTracer::Trackable || tp.defined_class == ObjectTracer
+      return true
+    end
+
+    if Module.respond_to?(:module_parents)
+      tp.defined_class.module_parents.include?(ObjectTracer)
+    elsif Module.respond_to?(:parents)
+      tp.defined_class.parents.include?(ObjectTracer)
+    end
+  end
+
+  def with_condition_satisfied?(payload)
+    @with_condition.nil? || @with_condition.call(payload)
+  end
+
+  def build_payload(tp:, filepath:, line_number:)
+    Payload.new(
+      target: @target,
+      receiver: tp.self,
+      method_name: tp.callee_id,
+      method_object: get_method_object_from(tp.self, tp.callee_id),
+      arguments: collect_arguments(tp),
+      return_value: (tp.return_value rescue nil),
+      filepath: filepath,
+      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),
+      tag: options[:tag],
+      tp: tp
+    )
+  end
+
+  def get_method_object_from(target, method_name)
+    Object.instance_method(:method).bind(target).call(method_name)
+  rescue NameError
+    # if any part of the program uses Refinement to extend its methods
+    # we might still get NoMethodError when trying to get that method outside the scope
+    nil
+  end
+
+  def get_call_location(tp, padding: 0)
+    caller(get_trace_index(tp) + padding).first.split(":")[0..1]
+  end
+
+  def get_trace_index(tp)
+    if tp.event == :c_call
+      C_CALLER_START_POINT
+    else
+      CALLER_START_POINT
+    end
+  end
+
+  def get_traces(tp)
+    if with_trace_to = options[:with_trace_to]
+      trace_index = get_trace_index(tp)
+      caller[trace_index..(trace_index + with_trace_to)]
+    else
+      []
+    end
+  end
+
+  def collect_arguments(tp)
+    parameters =
+      if RUBY_VERSION.to_f >= 2.6
+        tp.parameters
+      else
+        get_method_object_from(tp.self, tp.callee_id)&.parameters || []
+      end.map { |parameter| parameter[1] }
+
+    tp.binding.local_variables.each_with_object({}) do |name, args|
+      args[name] = tp.binding.local_variable_get(name) if parameters.include?(name)
+    end
+  end
+
+  def process_options(options)
+    options[:filter_by_paths] ||= config[:filter_by_paths]
+    options[:exclude_by_paths] ||= config[:exclude_by_paths]
+    options[:with_trace_to] ||= config[:with_trace_to]
+    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
+    options
+  end
+
+  def is_from_target?(tp)
+    comparsion = tp.self
+    is_the_same_record?(comparsion) || target.__id__ == comparsion.__id__
+  end
+
+  def is_the_same_record?(comparsion)
+    return false unless options[:track_as_records]
+    if target.is_a?(ActiveRecord::Base) && comparsion.is_a?(target.class)
+      primary_key = target.class.primary_key
+      target.send(primary_key) && target.send(primary_key) == comparsion.send(primary_key)
+    end
+  end
+
+  def record_call!(payload)
+    return if @disabled
+
+    write_output!(payload) if @output_writer
+
+    if @block
+      root_device.calls << @block.call(payload)
+    else
+      root_device.calls << payload
+    end
+  end
+
+  def write_output!(payload)
+    @output_writer.write!(payload)
+  end
+
+  def stop_if_condition_fulfilled!(payload)
+    if @stop_when&.call(payload)
+      stop!
+      root_device.stop!
+    end
+  end
+
+  def config
+    ObjectTracer.config
+  end
+end