timeasure 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 284614263b2c5c4343831c8d79e391c869009490
+  data.tar.gz: 72aa7b99c6eaeef54890c1c12d66679be73895f1
+SHA512:
+  metadata.gz: 175a8df40f6cf4a2ef58b11375b6b83da05499d960ed67055812fae8ebb9337b5d76834a432efc781d6ca8afc43f2fe816011538047755746bffb1ca448e853d
+  data.tar.gz: 20b2c718f96d7d0f8057cb086dc0cdab8fce80b1933fe9b7c0f68dddfa9606244b99cf57311b89976bac98250c8bd15652f832aba2ceb4317cd2e7d7c29dc5e5

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.idea/*

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,11 @@
+AllCops:
+  TargetRubyVersion: 2.4.2
+
+Metrics/LineLength:
+  Max: 120
+
+Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  ExcludedMethods: ['describe', 'context', 'before']

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in timeasure.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2017 Eliav Lavi
+
+MIT License
+
+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,207 @@
+# Timeasure
+
+**What Is It?**
+
+Timeasure is a transparent method-level wrapper for profiling purposes developed by [Eliav Lavi](http://www.eliavlavi.com) & [Riskified](https://www.riskified.com/)).
+
+Timeasure is a Ruby gem that allows measuring the runtime of methods in production environments
+without having to alter the code of the methods themselves.
+
+Timeasure allows you to declare tracked methods to be measured transparently upon each call.
+Measured calls are then reported to Timeasure's Profiler, which aggregates the measurements on the method level.
+This part is configurable and if you wish you can report measurements to another profiler of your choice.
+
+**Why Use It?**
+
+Timeasure was created in order to serve as an easy-to-use, self-contained framework for method-level profiling
+that is safe to use in production. Testing runtime in non-production environments is helpful, but there is
+great value to the knowledge gained by measuring what really goes on at real time.
+
+**What To Do With the Data?**
+
+The imagined usage of measured methods timing is to aggregate it along a certain transaction and report it to a live
+BI service such as [NewRelic Insights](https://newrelic.com/insights) or [Keen.io](https://keen.io/);
+however, different usages might prove helpful as well, such as writing the data to a database or a file.
+
+**Disclaimers**
+
+Timeasure uses minimal intervention in the Ruby Object Model for tracked modules and classes.
+It integrates well within Rails and non-Rails apps.
+
+Timeasure is inspired by [Metaprogramming Ruby 2](https://pragprog.com/book/ppmetr2/metaprogramming-ruby-2)
+by [Paolo Perrotta](https://twitter.com/nusco)
+and by [this](https://hashrocket.com/blog/posts/module-prepend-a-super-story) blog post by Hashrocket.
+
+## Requirements
+
+Ruby 2.0 or a later version is mandatory. (Timeasure uses `Module#prepend` introduced in Ruby 2.0.)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'timeasure'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install timeasure
+
+## Usage
+#### 1. Include Timeasure in Modules and Classes
+Simply include the Timeasure module in any class or module and declare the desired methods to track:
+
+```ruby
+class Foo
+  include Timeasure
+  tracked_class_methods :bar
+  tracked_instance_methods :baz, :qux
+  
+  def self.bar
+    # some class-level stuff that can benefit from measuring runtime...
+  end
+    
+  def baz
+    # some instance-level stuff that can benefit from measuring runtime...
+  end
+  
+  def qux
+    # some other instance-level stuff that can benefit from measuring runtime...
+  end
+end
+```
+
+#### 2. Define the Boundaries of the Tracked Transaction
+**Preparing for Method Tracking**
+
+The user is responsible for managing the final reporting and the clean-up of the aggregated data after each transation.
+It is recommended to prepare the profiler at the beginning of a transaction in which tracked methods exist with
+
+```ruby
+Timeasure::Profiling::Manager.prepare
+```
+and to re-prepare it again at the end of it in order to ensure a "clean slate" -
+after you have handled the aggregated data in some way.
+
+**Getting Hold of the Data**
+
+In order to get hold of the reported methods data, use 
+```ruby
+Timeasure::Profiling::Manager.export
+````
+This will return an array of `ReportedMethod`s. Each `ReportedMethod` object holds the aggregated timing data per
+each tracked method call. This means that no matter how many times you call a tracked method, Timeasure's Profiler will
+still hold a single `ReportedMethod` object to represent it.
+
+`ReportedMethod` allows reading the following attributes:  
+* `klass_name`: Name of the class in which the tracked method resides.
+* `method_name`: Name of the tracked method.
+* `segment`: See [Segmented Method Tracking](#segmented-method-tracking) below.
+* `metadata`: See [Carrying Metadata](#carrying-metadata) below.
+* `method_path`: `klass_name` and `method_name` concatenated.
+* `full_path`: Same as `method_path` unless segmentation is declared,
+in which case the segment will be concatenated to the string as well. See [Segmented Method Tracking](#segmented-method-tracking) below.
+* `runtime_sum`: The aggregated time it took the reported method in question to run across all calls.
+* `call_count`: The times the reported method in question was called across all calls.
+ 
+
+## Advanced Usage
+
+#### Segmented Method Tracking
+Timeasure was designed to separate regular code from its time measurement declaration.
+This is achieved by Timeasure's class macros `tracked_class_methods` and `tracked_instance_methods`.
+Sometimes, however, the need for additional data might arise. Imagine this method:
+
+```ruby
+class Foo
+  def bar(baz)
+    # some stuff that can benefit from measuring runtime
+    # yet its runtime is also highly affected by the value of baz...
+  end
+end
+```
+
+We've seen how Timeasure makes it easy to measure the `bar` method.
+However, if we wish to segment each call by the value of `baz`,
+we may use Timeasure's direct interface and send this value as a **segment**:
+
+```ruby
+class Foo
+  def bar(baz)
+    Timeasure.measure(klass_name: 'Foo', method_name: 'bar', segment: { baz: baz }) do
+      # the code to be measured
+    end
+  end
+end
+```
+
+For such calls, Timeasure's Profiler will aggregate the data in `ReportedMethod` objects grouped by
+class, method and segment.
+
+This approach obviously violates Timeasure's idea of separating code and measurement-declaration,
+but it allows for much more detailed investigations, if needed.
+This will result in different `ReportedMethod` object in Timeasure's Profiler for
+each combination of class, method and segment. Accordingly, such `ReportedMethod` object will include
+these three elements, concatenated, as the value for `ReportedMethod#full_path`. 
+
+#### Carrying Metadata
+This feature was developed in order to complement the segmented method tracking.
+
+Sometimes carrying data with measurement that does not define a segment might be needed.
+For example, assuming we save all our `ReportedMethod`s to some table called `reported_methods`,
+we might want to supply a custom table name for specific measurements.
+This might be achieved by using `metadata`:
+ 
+```ruby
+class Foo
+  def bar
+    Timeasure.measure(klass_name: 'Foo', method_name: 'bar', metadata: { table_name: 'my_custom_table' }) do
+      # the code to be measured
+    end
+  end
+end
+```
+
+Unlike Segments, Timeasure only carries the Metadata onwards.
+It is up to the user to make use of this data, probably after calling `Timeasure::Profiling::Manager.export`.
+
+## Notes
+
+#### Compatibility with RSpec
+
+If you run your test suite with Timeasure installed and modules, classes and methods tracked and all works fine - hurray!
+However, due to the mechanics of Timeasure - namely, its usage of prepended modules - there exist a problem with
+**stubbing** Timeasure-tracked method (RSpec does not support stubbing methods that appear in a prepended module).
+To be accurate, that means that if you are tracking method `#foo`, you can not
+declare something like `allow(bar).to receive(:foo).and_return(bar)`. Your specs will refuse to run in this case.
+To solve that problem you can configure Timeasure's `enable_timeasure_proc` **not** to run under certain conditions.
+
+If you are on Rails, add the following as a Rails initializer:
+
+```ruby
+require 'timeasure'
+
+Timeasure.configure do |configuration|
+  configuration.enable_timeasure_proc = lambda { !Rails.env.test? }
+end
+```  
+
+Timeasure will not come into action if the expression in the block evaluates to `false`.
+By default this block evaluates to `true`.
+
+
+## Feature Requests
+
+Timeasure is open for changes and requests!
+If you have an idea, a question or some need, feel free to contact me here or at eliavlavi@gmail.com.
+
+## Contributing
+
+1. Fork it ( https://github.com/riskified/timeasure/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/timeasure.rb

@@ -0,0 +1,69 @@
+require_relative 'timeasure/version'
+require_relative 'timeasure/configuration'
+require_relative 'timeasure/class_methods'
+require_relative 'timeasure/measurement'
+require_relative 'timeasure/profiling/manager'
+
+module Timeasure
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def included(base_class)
+      base_class.extend ClassMethods
+
+      instance_interceptor = const_set(instance_interceptor_name_for(base_class), interceptor_module_for(base_class))
+      class_interceptor = const_set(class_interceptor_name_for(base_class), interceptor_module_for(base_class))
+
+      return unless timeasure_enabled?
+
+      base_class.prepend instance_interceptor
+      base_class.singleton_class.prepend class_interceptor
+    end
+
+    def measure(klass_name: nil, method_name: nil, segment: nil, metadata: nil)
+      t0 = Time.now.utc
+      block_return_value = yield if block_given?
+      t1 = Time.now.utc
+
+      begin
+        measurement = Timeasure::Measurement.new(klass_name: klass_name.to_s, method_name: method_name.to_s,
+                                                 segment: segment, metadata: metadata, t0: t0, t1: t1)
+        Timeasure.configuration.post_measuring_proc.call(measurement)
+      rescue => e
+        Timeasure.configuration.rescue_proc.call(e, klass_name)
+      end
+
+      block_return_value
+    end
+
+    private
+
+    def instance_interceptor_name_for(base_class)
+      "#{base_class.timeasure_name}InstanceInterceptor"
+    end
+
+    def class_interceptor_name_for(base_class)
+      "#{base_class.timeasure_name}ClassInterceptor"
+    end
+
+    def interceptor_module_for(base_class)
+      Module.new do
+        @klass_name = base_class
+
+        def self.klass_name
+          @klass_name
+        end
+      end
+    end
+
+    def timeasure_enabled?
+      configuration.enable_timeasure_proc.call
+    end
+  end
+end

data/lib/timeasure/class_methods.rb

@@ -0,0 +1,33 @@
+module Timeasure
+  module ClassMethods
+    def tracked_instance_methods(*method_names)
+      method_names.each do |method_name|
+        instance_interceptor = const_get("#{timeasure_name}InstanceInterceptor")
+        add_method_to_interceptor(instance_interceptor, method_name)
+      end
+    end
+
+    def tracked_class_methods(*method_names)
+      method_names.each do |method_name|
+        class_interceptor = const_get("#{timeasure_name}ClassInterceptor")
+        add_method_to_interceptor(class_interceptor, method_name)
+      end
+    end
+
+    def timeasure_name
+      name.gsub('::', '_')
+    end
+
+    private
+
+    def add_method_to_interceptor(interceptor, method_name)
+      interceptor.class_eval do
+        define_method method_name do |*args, &block|
+          Timeasure.measure(klass_name: interceptor.klass_name.to_s, method_name: method_name.to_s) do
+            super(*args, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/timeasure/configuration.rb

@@ -0,0 +1,42 @@
+module Timeasure
+  class Configuration
+    attr_accessor :post_measuring_proc, :rescue_proc, :enable_timeasure_proc,
+                  :reported_methods_handler_set_proc, :reported_methods_handler_get_proc
+
+    def initialize
+      @post_measuring_proc = lambda do |measurement|
+        # Enables the configuration of what to do with each method runtime measurement.
+        # By default it reports to Timeasure's Profiling Manager.
+
+        Timeasure::Profiling::Manager.report(measurement)
+      end
+
+      @rescue_proc = lambda do |e, klass|
+        # Enabled the configuration of post_measuring_proc rescue.
+      end
+
+      @enable_timeasure_proc = lambda do
+        # Enables toggling Timeasure's activation (e.g. for disabling Timeasure for RSpec).
+
+        true
+      end
+
+      @reported_methods_handler_set_proc = lambda do |reported_methods_handler|
+        # Enables configuring where to store the ReportedMethodsHandler instance.
+        # This proc will be called by Timeasure::Profiling::Manager.prepare.
+        # By default it stores the handler as a class instance variable (in Timeasure::Profiling::Manager)
+
+        @reported_methods_handler = reported_methods_handler
+      end
+
+      @reported_methods_handler_get_proc = lambda do
+        # Enables configuring where to fetch the ReportedMethodsHandler instance.
+        # This proc will be called by Timeasure::Profiling::Manager.report and Timeasure::Profiling::Manager.export.
+        # By default it fetches the handler from the class instance variable
+        # (see @reported_methods_handler_set_proc).
+
+        @reported_methods_handler
+      end
+    end
+  end
+end

data/lib/timeasure/measurement.rb

@@ -0,0 +1,26 @@
+module Timeasure
+  class Measurement
+    attr_reader :klass_name, :method_name, :segment, :metadata, :t0, :t1
+
+    def initialize(klass_name:, method_name:, t0:, t1:, segment: nil, metadata: nil)
+      @klass_name = klass_name
+      @method_name = method_name
+      @t0 = t0
+      @t1 = t1
+      @segment = segment
+      @metadata = metadata
+    end
+
+    def runtime_in_milliseconds
+      (@t1 - @t0) * 1000
+    end
+
+    def full_path
+      @segment.nil? ? method_path : "#{method_path}:#{@segment}"
+    end
+
+    def method_path
+      "#{@klass_name}##{@method_name}"
+    end
+  end
+end

data/lib/timeasure/profiling/manager.rb

@@ -0,0 +1,39 @@
+require 'logger'
+require_relative 'reported_methods_handler'
+require_relative 'reported_method'
+
+module Timeasure
+  module Profiling
+    class Manager
+      class << self
+        def prepare
+          Timeasure.configuration.reported_methods_handler_set_proc.call(ReportedMethodsHandler.new)
+        end
+
+        def report(measurement)
+          handler = reported_methods_handler
+          handler.nil? ? warn_unprepared_handler : handler.report(measurement)
+        end
+
+        def export
+          handler = reported_methods_handler
+          handler.nil? ? warn_unprepared_handler : handler.export
+        end
+
+        private
+
+        def reported_methods_handler
+          Timeasure.configuration.reported_methods_handler_get_proc.call
+        end
+
+        def warn_unprepared_handler
+          logger.warn("#{self} is not prepared. Call Timeasure::Profiling::Manager.prepare before trying to report measurements or export reported methods.")
+        end
+
+        def logger
+          @logger ||= Logger.new(STDOUT)
+        end
+      end
+    end
+  end
+end

data/lib/timeasure/profiling/reported_method.rb

@@ -0,0 +1,27 @@
+module Timeasure
+  module Profiling
+    class ReportedMethod
+      attr_reader :klass_name, :method_name, :segment, :metadata, :full_path, :method_path, :runtime_sum, :call_count
+
+      def initialize(measurement)
+        @klass_name = measurement.klass_name
+        @method_name = measurement.method_name
+        @segment = measurement.segment
+        @metadata = measurement.metadata
+        @full_path = measurement.full_path
+        @method_path = measurement.method_path
+
+        @runtime_sum = 0
+        @call_count = 0
+      end
+
+      def increment_runtime_sum(runtime)
+        @runtime_sum += runtime
+      end
+
+      def increment_call_count
+        @call_count += 1
+      end
+    end
+  end
+end

data/lib/timeasure/profiling/reported_methods_handler.rb

@@ -0,0 +1,30 @@
+module Timeasure
+  module Profiling
+    class ReportedMethodsHandler
+      def initialize
+        @reported_methods = {}
+      end
+
+      def report(measurement)
+        initialize_path_for(measurement) if path_uninitialized_for(measurement)
+
+        @reported_methods[measurement.full_path].increment_runtime_sum(measurement.runtime_in_milliseconds)
+        @reported_methods[measurement.full_path].increment_call_count
+      end
+
+      def export
+        @reported_methods.values
+      end
+
+      private
+
+      def path_uninitialized_for(measurement)
+        @reported_methods[measurement.full_path].nil?
+      end
+
+      def initialize_path_for(measurement)
+        @reported_methods[measurement.full_path] = ReportedMethod.new(measurement)
+      end
+    end
+  end
+end

data/lib/timeasure/version.rb

@@ -0,0 +1,3 @@
+module Timeasure
+  VERSION = '0.1.0'
+end

data/timeasure.gemspec

@@ -0,0 +1,27 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'timeasure/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'timeasure'
+  spec.version       = Timeasure::VERSION
+  spec.authors       = ['Eliav Lavi']
+  spec.email         = ['eliav@riskified.com', 'eliavlavi@gmail.com']
+  spec.summary       = 'Transparent method-level wrapper for profiling purposes'
+  spec.description   = <<-DESCRIPTION
+                          Timeasure is a Ruby gem that allows measuring the runtime of methods
+                          without having to alter the code of the methods themselves.
+                       DESCRIPTION
+  spec.homepage      = 'https://github.com/riskified/timeasure'
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.start_with? 'spec/' }
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ['lib', 'lib/timeasure', 'lib/timeasure/profiling']
+
+  spec.required_ruby_version = '>= 2.0'
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'rake', '~> 12.0'
+  spec.add_development_dependency 'rspec', '~> 3.6'
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: timeasure
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eliav Lavi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-02-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+description: |2
+                            Timeasure is a Ruby gem that allows measuring the runtime of methods
+                            without having to alter the code of the methods themselves.
+email:
+- eliav@riskified.com
+- eliavlavi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/timeasure.rb
+- lib/timeasure/class_methods.rb
+- lib/timeasure/configuration.rb
+- lib/timeasure/measurement.rb
+- lib/timeasure/profiling/manager.rb
+- lib/timeasure/profiling/reported_method.rb
+- lib/timeasure/profiling/reported_methods_handler.rb
+- lib/timeasure/version.rb
+- timeasure.gemspec
+homepage: https://github.com/riskified/timeasure
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+- lib/timeasure
+- lib/timeasure/profiling
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Transparent method-level wrapper for profiling purposes
+test_files: []