scout_rails 0.0.1

data/lib/scout_rails/metric_stats.rb

@@ -0,0 +1,45 @@
+# Stats that are associated with each instrumented method. 
+class ScoutRails::MetricStats
+  attr_accessor :call_count
+  attr_accessor :min_call_time
+  attr_accessor :max_call_time
+  attr_accessor :total_call_time
+  attr_accessor :total_exclusive_time
+  attr_accessor :sum_of_squares
+  
+  def initialize
+    self.call_count = 0
+    self.total_call_time = 0.0
+    self.total_exclusive_time = 0.0
+    self.min_call_time = 0.0
+    self.max_call_time = 0.0
+    self.sum_of_squares = 0.0
+  end
+  
+  def update!(call_time,exclusive_time)
+    self.min_call_time = call_time if self.call_count == 0 or call_time < min_call_time
+    self.max_call_time = call_time if self.call_count == 0 or call_time > max_call_time   
+    self.call_count +=1
+    self.total_call_time += call_time
+    self.total_exclusive_time += exclusive_time
+    self.sum_of_squares += (call_time * call_time)
+    self
+  end
+  
+  # combines data from another MetricStats object
+  def combine!(other)
+    self.call_count += other.call_count
+    self.total_call_time += other.total_call_time
+    self.total_exclusive_time += other.total_exclusive_time
+    self.min_call_time = other.min_call_time if other.min_call_time < self.min_call_time
+    self.max_call_time = other.max_call_time if other.max_call_time > self.max_call_time
+    self.sum_of_squares += other.sum_of_squares
+    self
+  end
+  
+  # To avoid conflicts with different JSON libaries handle JSON ourselves. 
+  # Time-based metrics are converted to milliseconds from seconds.
+  def to_json(*a)
+     %Q[{"total_exclusive_time":#{total_exclusive_time*1000},"min_call_time":#{min_call_time*1000},"call_count":#{call_count},"sum_of_squares":#{sum_of_squares*1000},"total_call_time":#{total_call_time*1000},"max_call_time":#{max_call_time*1000}}]
+  end
+end # class MetricStats

data/lib/scout_rails/stack_item.rb

@@ -0,0 +1,18 @@
+class ScoutRails::StackItem
+  attr_accessor :children_time
+  attr_reader :metric_name, :start_time 
+  
+  def initialize(metric_name)
+    @metric_name = metric_name
+    @start_time = Time.now
+    @children_time = 0
+  end
+  
+  def ==(o)
+    self.eql?(o)
+  end
+
+  def eql?(o)
+    self.class == o.class && metric_name.eql?(o.metric_name)
+  end
+end # class StackItem

data/lib/scout_rails/store.rb

@@ -0,0 +1,78 @@
+# The store encapsolutes the logic that (1) saves instrumented data by Metric name to memory and (2) maintains a stack (just an Array)
+# of instrumented methods that are being called. It's accessed via +ScoutRails::Agent.instance.store+. 
+class ScoutRails::Store
+  attr_accessor :metric_hash
+  attr_accessor :stack
+  
+  def initialize
+    @metric_hash = Hash.new
+    @stack = Array.new
+  end
+  
+  # Called at the start of Tracer#instrument:
+  # (1) Either finds an existing MetricStats object in the metric_hash or 
+  # initialize a new one. An existing MetricStats object is present if this +metric_name+ has already been instrumented.
+  # (2) Adds a StackItem to the stack. This StackItem is returned and later used to validate the item popped off the stack
+  # when an instrumented code block completes.
+  def record(metric_name)
+    #ScoutRails::Agent.instance.logger.debug "recording #{metric_name}"
+    item = ScoutRails::StackItem.new(metric_name)
+    stack << item
+    item
+  end
+  
+  def stop_recording(sanity_check_item)
+    item = stack.pop
+    raise "items not equal: #{item.inspect} / #{sanity_check_item.inspect}" if item != sanity_check_item
+    duration = Time.now - item.start_time
+    if last=stack.last
+      #ScoutRails::Agent.instance.logger.debug "found an element on stack [#{last.inspect}]. adding duration #{duration} to children time [#{last.children_time}]"
+      last.children_time += duration
+    end
+    #ScoutRails::Agent.instance.logger.debug "popped #{item.inspect} off stack. duration: #{duration}s"
+    if stack.empty? # this is the last item on the stack. it shouldn't have a scope.
+      Thread::current[:scout_scope_name] = nil
+    end
+    meta = ScoutRails::MetricMeta.new(item.metric_name)
+    #ScoutRails::Agent.instance.logger.debug "meta: #{meta.inspect}"
+    stat = metric_hash[meta] || ScoutRails::MetricStats.new
+    #ScoutRails::Agent.instance.logger.debug "found existing stat w/ky: #{meta}" if !stat.call_count.zero?
+    stat.update!(duration,duration-item.children_time)
+    metric_hash[meta] = stat   
+    #ScoutRails::Agent.instance.logger.debug "metric hash has #{metric_hash.size} items"
+  end
+  
+  # Finds or creates the metric w/the given name in the metric_hash, and updates the time. Primarily used to 
+  # record sampled metrics. For instrumented methods, #record and #stop_recording are used.
+  #
+  # Options:
+  # :scope => If provided, overrides the default scope. 
+  # :exclusive_time => Sets the exclusive time for the method. If not provided, uses +call_time+.
+  def track!(metric_name,call_time,options = {})
+     meta = ScoutRails::MetricMeta.new(metric_name)
+     meta.scope = options[:scope] if options.has_key?(:scope)
+     stat = metric_hash[meta] || ScoutRails::MetricStats.new
+     stat.update!(call_time,options[:exclusive_time] || call_time)
+     metric_hash[meta] = stat
+  end
+  
+  # Combines old and current data
+  def merge_data(old_data)
+    old_data.each do |old_meta,old_stats|
+      if stats = metric_hash[old_meta]
+        metric_hash[old_meta] = stats.combine!(old_stats)
+      else
+        metric_hash[old_meta] = old_stats
+      end
+    end
+    metric_hash
+  end
+  
+  # Merges old and current data, clears the current in-memory metric hash, and returns
+  # the merged data
+  def merge_data_and_clear(old_data)
+    merged = merge_data(old_data)
+    self.metric_hash =  {}
+    merged
+  end
+end # class Store

data/lib/scout_rails/tracer.rb

@@ -0,0 +1,90 @@
+# Contains the methods that instrument blocks of code. 
+# 
+# When a code block is wrapped inside #instrument(metric_name):
+# * The #instrument method pushes a StackItem onto Store#stack
+# * When a code block is finished, #instrument pops the last item off the stack and verifies it's the StackItem
+#   we created earlier. 
+# * Once verified, the metrics for the recording session are merged into the in-memory Store#metric_hash. The current scope
+#   is also set for the metric (if Thread::current[:scout_scope_name] isn't nil).
+module ScoutRails::Tracer
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+  
+  module ClassMethods
+    # An easier reference to the agent's associated store. 
+    def store
+      ScoutRails::Agent.instance.store
+    end
+    
+    def instrument(metric_name, &block)
+      #ScoutRails::Agent.instance.logger.debug "Instrumenting: #{metric_name} w/scope: #{Thread::current[:scout_scope_name]}"
+      stack_item = store.record(metric_name)
+      #ScoutRails::Agent.instance.logger.debug "Stack contains: #{store.stack.size} methods"
+      begin
+        yield
+      ensure
+        store.stop_recording(stack_item)
+      end
+    end
+    
+    def instrument_method(method,metric_name = nil)
+      #ScoutRails::Agent.instance.logger.debug "Instrumenting method name: #{name} w/metric name: #{metric_name}"
+      metric_name = metric_name || default_metric_name(method)
+      return if !instrumentable?(method) or instrumented?(method,metric_name)
+      class_eval instrumented_method_string(method, metric_name), __FILE__, __LINE__
+      
+      alias_method _uninstrumented_method_name(method, metric_name), method
+      alias_method method, _instrumented_method_name(method, metric_name)
+      #ScoutRails::Agent.instance.logger.debug "Instrumented #{self.name}##{method} w/metric name: #{metric_name}"
+    end
+    
+    private
+    
+    def instrumented_method_string(method, metric_name)
+      klass = (self === Module) ? "self" : "self.class"
+      "def #{_instrumented_method_name(method, metric_name)}(*args, &block)
+        result = #{klass}.instrument(\"#{metric_name}\") do
+          #{_uninstrumented_method_name(method, metric_name)}(*args, &block)
+        end
+        result
+      end"
+    end
+    
+    # The method must exist to be instrumented.
+    def instrumentable?(method)
+      exists = method_defined?(method) || private_method_defined?(method)
+      ScoutRails::Agent.instance.logger.warn "The method [#{self.name}##{method}] does not exist and will not be instrumented" unless exists
+      exists
+    end
+    
+    # +True+ if the method is already instrumented. 
+    def instrumented?(method,metric_name)
+      instrumented = method_defined?(_instrumented_method_name(method, metric_name))
+      ScoutRails::Agent.instance.logger.warn "The method [#{self.name}##{method}] has already been instrumented" if instrumented
+      instrumented
+    end
+    
+    def default_metric_name(method)
+      "Custom/#{self.name}/#{method.to_s}"
+    end
+    
+    # given a method and a metric, this method returns the
+    # untraced alias of the method name
+    def _uninstrumented_method_name(method, metric_name)
+      "#{_sanitize_name(method)}_without_scout_instrument_#{_sanitize_name(metric_name)}"
+    end
+    
+    # given a method and a metric, this method returns the traced
+    # alias of the method name
+    def _instrumented_method_name(method, metric_name)
+      name = "#{_sanitize_name(method)}_with_scout_instrument_#{_sanitize_name(metric_name)}"
+    end
+    
+    # Method names like +any?+ or +replace!+ contain a trailing character that would break when
+    # eval'd as ? and ! aren't allowed inside method names.
+    def _sanitize_name(name)
+      name.to_s.tr_s('^a-zA-Z0-9', '_')
+    end
+  end # ClassMethods
+end # module Tracer

data/lib/scout_rails/version.rb

@@ -0,0 +1,3 @@
+module ScoutRails
+  VERSION = "0.0.1"
+end

data/scout_rails.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "scout_rails/version"
+
+Gem::Specification.new do |s|
+  s.name        = "scout_rails"
+  s.version     = ScoutRails::VERSION
+  s.authors     = ["Derek Haynes",'Andre Lewis']
+  s.email       = ["support@scoutapp.com"]
+  s.homepage    = "http://scoutapp.com"
+  s.summary     = "Rails application performance monitoring"
+  s.description = "Monitors a Ruby on Rails application and reports detailed metrics on performance to Scout, a hosted monitoring service."
+
+  s.rubyforge_project = "scout_rails"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: scout_rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Derek Haynes
+- Andre Lewis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-27 00:00:00.000000000 Z
+dependencies: []
+description: Monitors a Ruby on Rails application and reports detailed metrics on
+  performance to Scout, a hosted monitoring service.
+email:
+- support@scoutapp.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .DS_Store
+- .gitignore
+- Gemfile
+- README.markdown
+- Rakefile
+- lib/scout_rails.rb
+- lib/scout_rails/agent.rb
+- lib/scout_rails/config.rb
+- lib/scout_rails/environment.rb
+- lib/scout_rails/instruments/active_record_instruments.rb
+- lib/scout_rails/instruments/process/process_cpu.rb
+- lib/scout_rails/instruments/process/process_memory.rb
+- lib/scout_rails/instruments/rails/action_controller_instruments.rb
+- lib/scout_rails/instruments/rails3/action_controller_instruments.rb
+- lib/scout_rails/instruments/sinatra_instruments.rb
+- lib/scout_rails/layaway.rb
+- lib/scout_rails/layaway_file.rb
+- lib/scout_rails/metric_meta.rb
+- lib/scout_rails/metric_stats.rb
+- lib/scout_rails/stack_item.rb
+- lib/scout_rails/store.rb
+- lib/scout_rails/tracer.rb
+- lib/scout_rails/version.rb
+- scout_rails.gemspec
+homepage: http://scoutapp.com
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: scout_rails
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Rails application performance monitoring
+test_files: []