wtf-tools 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 39cd4bdb18179b654c8c89627596eba83ef1bb93
+  data.tar.gz: b55d4b4ddb008660477c7c54a3124299b50f8380
+SHA512:
+  metadata.gz: 3fe5a3c452e36a089d9f54f94f2e082e3453bf9f2164ea91d28a58c3b725d24b7c18c8935e914890ab830374305cca3cb6d73add38cdbad12bc86191b6485b13
+  data.tar.gz: b3301c939c79f6dcf23ad3060908e0555255bd517e3f71a129bc26f57a26ec4c3cdde88643f2828bf607ff49c18038420667dcc8782937cfb61af39bbe5bdce2

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Remigijus Jodelis
+
+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/README.md

@@ -0,0 +1,142 @@
+wtf-tools
+=========
+
+Some tools for debugging and profiling Ruby on Rails projects. Included:
+
+* data dumper 
+* code timing tool
+* method tracker - a kind of middle ground between simple timing and full profiling
+* SQL tracker - detect where exactly given SQL query originated from
+
+User is responsible for requiring gems necessary for rendering output. 
+For example, when :yaml option is used with `WTF?`, we expect that `YAML` is already loaded.
+Library requirements for specific options are documented below.
+
+Usage examples
+--------------
+
+### Data dumping
+
+```ruby
+WTF? my_var                                   # basic
+WTF? my_var, other_var, { some: data }, :pp   # more data, option: pretty-print
+WTF? :label, records, :bare, :time            # multiple options given
+```
+
+Supported options
+
+```
+Prefix
+  (default)  WTF (my_file_name/method_name:227): 
+  :time      with timestamp: [2014-10-28 12:33:11 +0200]
+  :nl        new line before the record
+  :no        no prefix at all
+
+Formatting
+  (default)  simple Ruby inspect
+  :pp        pretty-print, require 'pp'
+  :yaml      YAML format,  require 'yaml'
+  :json      JSON format,  require 'json'
+  :csv       CSV format,   require 'csv'
+  :text      simple Ruby to_s
+  :line      modifier, each object in separate line
+  :bare      modifier, ActiveRecord with just id attributs: #<MyClass id: 1234>
+
+Output control
+  (default)  to the chosen logger (see configuration)
+  :log       to Rails default logger
+  :file      to a separate file in configured location
+  :page      to a thread variable Thread.current[:wtf]
+  :redis     to a Redis list on key 'wtf', expiring in 30min
+  :raise     raise the string containing data as exception
+```
+
+---
+
+### Code timing
+
+```ruby
+class MyClass
+  def run_something
+    WTF.time {
+      # your code
+    }
+  end
+end
+```
+
+---
+
+### Method tracking
+
+```ruby
+class MyClass
+  def run_something
+    WTF.track(self, OtherClass)
+    # lots of code
+    WTF.track_finish
+  end
+end
+```
+
+This will create a CSV file in configured location, containing profiling info.
+Profiling happens only in the methods of the calling class, and other given class.
+
+How it works: every method in `MyClass` and `OtherClass` is overridden, adding resource timing code.
+All calls to those methods from the code between `track` and `track_finish` are measured (time and memory),
+and sum amounts are output at the end, sorted by total time used.
+
+Example output:
+
+```csv
+class,method,count,time,heap_mb
+,top,0,0.948,0.0
+Overview,some_helper,16408,0.351,0.0
+Overview,my_records,28,0.172,0.0
+Overview,load_data,1,0.166,0.0 
+...
+```
+
+Requirements: Ruby 2.0, because the technique used involves module `prepend`-ing, which is not available in Ruby 1.9.
+Warning: tracking method calls adds time overhead (somewhere from 10% to 3x, depending on number of times the methods were called).
+
+---
+
+### SQL tracking
+
+```ruby
+class MyClass
+  def run_something
+    WTF.sql %q{SELECT * FROM `my_records` WHERE `attribute`='value' AND `etc`}
+    WTF.sql %q{UPDATE `my_records` SET `some_values`=NULL}
+    # lots of code
+  end
+end
+```
+
+This will add a `WTF?`-style dump in the default location, containing stacktrace where given SQL statement was generated. SQL must match exactly as strings.
+
+---
+
+
+Configuration
+-------------
+
+Configure WTF before using the above-mentioned facilities. Rails initializer dir is a good place for it.
+
+```ruby
+WTF.options = {
+  default: Rails.logger,
+  files:   "#{Rails.root}/log/wtf",
+  redis:   Redis.new,
+}
+
+require 'yaml' # to use :yaml option, etc
+```
+
+---
+
+License
+-------
+
+This is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/example/dump.rb

@@ -0,0 +1,26 @@
+require 'rubygems'
+require 'wtf-tools'
+require 'pp'
+require 'json'
+require 'yaml'
+require 'active_support/logger'
+require 'fileutils'
+
+WTF.options = {
+  :default => ActiveSupport::Logger.new('./example.log'),
+  :files => './wtf',
+}
+
+data = { 'some' => { 'nested' => { 'data' => 17 } }, :question => %w(life universe and everything), :answer => 42 }
+
+WTF? Time.now
+
+WTF? :label, "string", 17, 2.0001, :time, :nl
+
+WTF? 'label', "string", 17, 2.0001, :time, :line, :nl
+
+WTF? data, :pp, :nl
+
+WTF? data, :json, :nl
+
+WTF? data, :yaml, :no, :file

data/example/timing.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'wtf-tools'
+require 'active_support/logger'
+
+# default: puts
+WTF.time {
+  sleep 1.01
+}
+
+# logging time with specified precision and options
+WTF.options = {
+  :default => ActiveSupport::Logger.new('./example.log'),
+}
+result = WTF.time(4, :nl) {
+  sleep 3.12346
+  17
+}
+p result # => 17

data/example/tracking.rb

@@ -0,0 +1,32 @@
+require 'rubygems'
+require 'wtf-tools'
+require 'fileutils'
+require 'csv'
+
+WTF.options = {
+  :files => './wtf',
+}
+
+class Sample
+  def run
+    WTF.track(self)
+    action1
+    action2
+    action3
+    WTF.track_finish
+  end
+
+  def action1
+    sleep 1
+  end
+
+  def action2
+    sleep 2
+  end
+
+  def action3
+    sleep 3
+  end
+end
+
+Sample.new.run

data/lib/wtf-tools.rb

@@ -0,0 +1,56 @@
+require 'wtf/dumper'
+require 'wtf/method_tracker'
+require 'wtf/query_tracker'
+
+module WTF
+  class << self
+    def options=(value)
+      @options = value
+    end
+
+    def options
+      @options ||= {}
+    end
+
+    def files_path
+      dirs = FileUtils.mkdir_p(options[:files])
+      dirs.first
+    end
+
+    # TODO: separately track ActiveRecord finders usage in the related methods
+    def track(*objects)
+      WTF::MethodTracker.start_tracking(*objects)
+      if block_given?
+        yield
+        track_finish
+      end
+    end
+
+    def track_finish
+      WTF::MethodTracker.finish
+    end
+
+    def sql(sql)
+      WTF::QueryTracker.start_tracking(sql)
+    end
+
+    def time(*args)
+      require 'absolute_time'
+
+      precision = args.shift if args.first.is_a?(Fixnum)
+      precision ||= 3
+      before = AbsoluteTime.now
+      result = yield
+      duration = AbsoluteTime.now - before
+      WTF::Dumper.new(duration.round(precision), *args)
+      result
+    end
+  end
+end
+
+Object.class_eval do
+  def WTF?(*args)
+    WTF::Dumper.new(*args)
+    nil
+  end
+end

data/lib/wtf/dumper.rb

@@ -0,0 +1,87 @@
+module WTF
+  class Dumper
+    OPTIONS = [
+      :time, :nl, :no,                       # prefix
+      :pp, :yaml, :json, :text, :line, :csv, # format
+      :bare,                                 # modify
+      :page, :file, :raise, :redis, :log,    # output
+    ].freeze
+
+    attr_reader :options
+
+    def initialize(*args)
+      @options = {}
+      while OPTIONS.include?(args.last)
+        @options[args.pop] = true
+      end
+
+      data = prefix(args) << format(args)
+      output(data)
+    end
+
+    private
+
+    def prefix(args)
+      data = ''
+      return data if options[:no]
+      data << "\n" if options[:nl]
+      data << "[%s] " % Time.now if options[:time]
+      data << if args[0].is_a?(Symbol)
+        args.shift.to_s.upcase
+      else
+        pattern = %r{([^/]+?)(?:\.rb)?:(\d+):in `(.*)'$}  # '
+        "WTF (%s/%s:%s)" % caller[3].match(pattern).values_at(1,3,2)
+      end
+      data << ': '
+    end
+
+    def format(args)
+      case
+      when options[:pp]
+        cleanup(args.pretty_inspect, options[:bare])
+      when options[:yaml]
+        YAML.dump(args)
+      when options[:json]
+        JSON::pretty_generate(args)
+      when options[:text]
+        args.map(&:to_s).join("\n")
+      when options[:line]
+        args.map(&:inspect).join("\n  ")
+      when options[:csv]
+        args[0].map(&:to_csv).join
+      else
+        cleanup(args.inspect, options[:bare])
+      end
+    end
+
+    def output(data)
+      case
+      when options[:page]
+        (Thread.current[:wtf] ||= []) << data
+      when options[:file]
+        time = Time.now.strftime('%m%d_%H%M%S')
+        file = "#{WTF.files_path}/wtf_#{time}_#{rand(10000)}.txt"
+        File.write(file, data)
+      when options[:raise]
+        raise StandardError, data
+      when options[:redis]
+        WTF.options[:redis].rpush('wtf', data)
+        WTF.options[:redis].expire('wtf', 30*60)
+      when options[:log]
+        Rails.logger.info(data)
+      when WTF.options[:default]
+        WTF.options[:default].info(data)
+      else
+        puts data
+      end
+    end
+
+    def cleanup(str, bare = false)
+      # remove array parentheses
+      str.gsub!(/^\[|\]$/,'')
+      # ActiveRecord no attributes
+      str.gsub!(/#<[A-Z]\w+ id: \d+\K.*?>/, '>') if bare
+      str
+    end
+  end
+end

data/lib/wtf/method_tracker.rb

@@ -0,0 +1,89 @@
+module WTF
+  module MethodTracker
+    class << self
+      def start_tracking(*objects)
+        require 'absolute_time'
+
+        objects.each do |object|
+          klass = object.is_a?(Module) ? object : object.class
+          prepare(klass)
+        end
+        reset_state
+      end
+
+      def prepare(base)
+        methods = base.instance_methods(false) + base.private_instance_methods(false)
+        compiled = methods.map do |name|
+          override_method(base, name)
+        end
+        base.module_eval %{
+          module Tracking
+            #{compiled.join}
+          end
+          prepend Tracking
+        }
+      end
+
+      def override_method(base, name)
+        %{
+          def #{name}(*args)
+            WTF::MethodTracker.on_start(#{base}, :#{name})
+            return_value = super
+            WTF::MethodTracker.on_end
+            return_value
+          end
+        }
+      end
+
+      attr_accessor :stats, :stack, :last_time, :last_heap
+
+      def reset_state
+        self.stats = Hash.new { |h,k| h[k] = { :freq => 0, :time => 0.0, :heap => 0 } }
+        self.stack = [[nil, :top]]
+        self.last_time = AbsoluteTime.now
+        self.last_heap = GC.stat[:heap_length]
+      end
+
+      def on_start(*full_name)
+        add_stats(full_name)
+        stack.push(full_name)
+      end
+
+      def on_end
+        add_stats
+        stack.pop
+      end
+
+      def finish
+        add_stats
+        dump_stats
+        reset_state
+      end
+
+      def add_stats(at_start = nil)
+        stat = stats[stack.last]
+
+        this_time = AbsoluteTime.now
+        stat[:time] += this_time - last_time
+        self.last_time = this_time
+
+        this_heap = GC.stat[:heap_length]
+        stat[:heap] += this_heap - last_heap
+        self.last_heap = this_heap
+
+        stats[at_start][:freq] += 1 if at_start
+      end
+
+      def dump_stats
+        data = stats.map do |key, val|
+          [*key, val[:freq].to_i, val[:time].to_f.round(3), (val[:heap].to_f / 64).round(3)]
+        end
+        data = data.sort_by {|it| it[3] }.reverse
+        data.unshift(%w(class method count time heap_mb))
+
+        time = Time.now.strftime('%m%d_%H%M%S')
+        File.write("#{WTF.files_path}/track_#{time}_#{rand(10000)}.csv", data.map(&:to_csv).join)
+      end
+    end
+  end
+end

data/lib/wtf/query_tracker.rb

@@ -0,0 +1,33 @@
+module WTF
+  module QueryTracker
+    class << self
+      attr_reader :trackable
+
+      def start_tracking(sql)
+        if @trackable.nil?
+          prepare_hook
+          @trackable = {}
+        end
+        @trackable[sql] = true
+      end
+
+      def prepare_hook
+        ActiveRecord::ConnectionAdapters::AbstractAdapter.module_eval %{
+          module TrackingSQL
+            def log(sql, *args, &block)
+              WTF::QueryTracker.on_sql(sql)
+              super(sql, *args, &block)
+            end
+          end
+          prepend TrackingSQL
+        }
+      end
+
+      def on_sql(sql)
+        if trackable[sql]
+          WTF::Dumper.new(:sql, sql, *caller.take(30), :line)
+        end
+      end
+    end
+  end
+end

data/test/test_dumper.rb

@@ -0,0 +1,8 @@
+require 'minitest/autorun'
+require 'wtf-tools'
+
+class TestWtfDumper < Minitest::Unit::TestCase
+  def test_dump
+    # TODO
+  end
+end

data/test/test_method_tracker.rb

@@ -0,0 +1,8 @@
+require 'minitest/autorun'
+require 'wtf-tools'
+
+class TestWtfMethodTracker < Minitest::Unit::TestCase
+  def test_track
+    # TODO
+  end
+end

data/test/test_timing.rb

@@ -0,0 +1,8 @@
+require 'minitest/autorun'
+require 'wtf-tools'
+
+class TestWtfTiming < Minitest::Unit::TestCase
+  def test_timing
+    # TODO
+  end
+end

data/wtf-tools.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+  s.name            = 'wtf-tools'
+  s.version         = '1.0.0'
+  s.date            = '2014-10-14'
+  s.platform        = Gem::Platform::RUBY
+  s.required_ruby_version = Gem::Requirement.new(">= 2.0.0")
+  s.summary         = 'tools for debugging and profiling Ruby on Rails projects'
+  s.license         = 'MIT'
+
+  s.description = <<-EOF
+WTF-tools offers some flexible options for your puts-style Ruby debugging needs,
+and method-level profiling for Ruby on Rails projects.
+EOF
+
+  s.files           = Dir['{lib/**/*,example/*,test/*}'] + %w(LICENSE Rakefile README.md wtf-tools.gemspec)
+  s.require_path    = 'lib'
+  s.test_files      = Dir['test/*.rb']
+
+  s.author          = 'Remigijus Jodelis'
+  s.email           = 'remigijus.jodelis@gmail.com'
+  s.homepage        = 'http://github.com/remigijusj/wtf-tools'
+
+  s.add_runtime_dependency 'absolute_time', '~> 1.0'
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: wtf-tools
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Remigijus Jodelis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: absolute_time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  WTF-tools offers some flexible options for your puts-style Ruby debugging needs,
+  and method-level profiling for Ruby on Rails projects.
+email: remigijus.jodelis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- example/dump.rb
+- example/timing.rb
+- example/tracking.rb
+- lib/wtf-tools.rb
+- lib/wtf/dumper.rb
+- lib/wtf/method_tracker.rb
+- lib/wtf/query_tracker.rb
+- test/test_dumper.rb
+- test/test_method_tracker.rb
+- test/test_timing.rb
+- wtf-tools.gemspec
+homepage: http://github.com/remigijusj/wtf-tools
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: tools for debugging and profiling Ruby on Rails projects
+test_files:
+- test/test_dumper.rb
+- test/test_method_tracker.rb
+- test/test_timing.rb