newrelic_rpm 3.1.0 → 3.1.1.beta1

data/lib/new_relic/delayed_job_injection.rb

@@ -15,7 +15,13 @@ DependencyDetection.defer do
   depends_on do
     defined?(::Delayed) && defined?(::Delayed::Worker)
   end
-
+  
+  executes do
+    if NewRelic::Agent.respond_to?(:logger)
+      NewRelic::Agent.logger.debug 'Installing DelayedJob instrumentation hooks'
+    end
+  end
+  
   executes do
     Delayed::Worker.class_eval do
       def initialize_with_new_relic(*args)

data/lib/new_relic/local_environment.rb

@@ -14,12 +14,16 @@ module NewRelic
   #
   # NewRelic::LocalEnvironment should be accessed through NewRelic::Control#env (via the NewRelic::Control singleton).
   class LocalEnvironment
-
-    attr_accessor :dispatcher # mongrel, thin, webrick, or possibly nil
-    attr_accessor :dispatcher_instance_id # used to distinguish instances of a dispatcher from each other, may be nil
-    attr_accessor :framework # rails, rails3, merb, external, ruby, test
-    attr_reader :mongrel    # The mongrel instance, if there is one, captured as a convenience
-    attr_reader :processors # The number of cpus, if detected, or nil
+    
+    # mongrel, thin, webrick, or possibly nil
+    attr_accessor :dispatcher
+    # used to distinguish instances of a dispatcher from each other, may be nil
+    attr_writer :dispatcher_instance_id
+    # rails, rails3, merb, external, ruby, test, etc
+    attr_accessor :framework
+    # The number of cpus, if detected, or nil - many platforms do not
+    # support this :(
+    attr_reader :processors 
     alias environment dispatcher
 
     def initialize
@@ -49,21 +53,27 @@ module NewRelic
       # puts "#{e}\n  #{e.backtrace.join("\n  ")}"
       raise if @framework == :test
     end
-
+    
+    # yields to the block and appends the returned value to the list
+    # of gems - this catches errors that might be raised in the block
     def append_gem_list
       @gems += yield
     rescue Exception => e
       # puts "#{e}\n  #{e.backtrace.join("\n  ")}"
       raise if @framework == :test
     end
-
+    
+    # yields to the block and appends the returned value to the list
+    # of plugins - this catches errors that might be raised in the block
     def append_plugin_list
       @plugins += yield
     rescue Exception
       # puts "#{e}\n  #{e.backtrace.join("\n  ")}"
       raise if @framework == :test
     end
-
+    
+    # An instance id pulled from either @dispatcher_instance_id or by
+    # splitting out the first part of the running file
     def dispatcher_instance_id
       if @dispatcher_instance_id.nil?
         if @dispatcher.nil?
@@ -72,7 +82,9 @@ module NewRelic
       end
       @dispatcher_instance_id
     end
-
+    
+    # Interrogates some common ruby constants for useful information
+    # about what kind of ruby environment the agent is running in
     def gather_ruby_info
       append_environment_value('Ruby version'){ RUBY_VERSION }
       append_environment_value('Ruby description'){ RUBY_DESCRIPTION } if defined? ::RUBY_DESCRIPTION
@@ -83,13 +95,14 @@ module NewRelic
         gather_jruby_info
       end
     end
-
+    
+    # like gather_ruby_info but for the special case of JRuby
     def gather_jruby_info
       append_environment_value('JRuby version') { JRUBY_VERSION }
       append_environment_value('Java VM version') { ENV_JAVA['java.vm.version']}
     end
 
-    # See what the number of cpus is, works only on linux.
+    # See what the number of cpus is, works only on some linux variants
     def gather_cpu_info
       return unless File.readable? '/proc/cpuinfo'
       @processors = append_environment_value('Processors') do
@@ -98,25 +111,30 @@ module NewRelic
         processors
       end
     end
-
+    
+    # Grabs the architecture string from either `uname -p` or the env
+    # variable PROCESSOR_ARCHITECTURE
     def gather_architecture_info
       append_environment_value('Arch') { `uname -p` } ||
         append_environment_value('Arch') { ENV['PROCESSOR_ARCHITECTURE'] }
     end
-
+    
+    # gathers OS info from either `uname -v`, `uname -s`, or the OS
+    # env variable
     def gather_os_info
       append_environment_value('OS version') { `uname -v` }
       append_environment_value('OS') { `uname -s` } ||
         append_environment_value('OS') { ENV['OS'] }
     end
-
+    
+    # Gathers the architecture and cpu info
     def gather_system_info
       gather_architecture_info
       gather_cpu_info
     end
-
+    
+    # Looks for a capistrano file indicating the current revision
     def gather_revision_info
-      # Look for a capistrano file indicating the current revision:
       rev_file = File.join(NewRelic::Control.instance.root, "REVISION")
       if File.readable?(rev_file) && File.size(rev_file) < 64
         append_environment_value('Revision') do
@@ -124,9 +142,11 @@ module NewRelic
         end
       end
     end
-
+    
+    # The name of the AR database adapter for the current environment and
+    # the current schema version
     def gather_ar_adapter_info
-      # The name of the database adapter for the current environment.
+      
       append_environment_value 'Database adapter' do
         if defined?(ActiveRecord) && defined?(ActiveRecord::Base) &&
             ActiveRecord::Base.respond_to?(:configurations)
@@ -140,14 +160,17 @@ module NewRelic
         ActiveRecord::Migrator.current_version
       end
     end
-
+    
+    # Datamapper version
     def gather_dm_adapter_info
       append_environment_value 'DataMapper version' do
         require 'dm-core/version'
         DataMapper::VERSION
       end
     end
-
+    
+    # sensing for which adapter is defined, then appends the relevant
+    # config information
     def gather_db_info
       # room here for more database adapters, when.
       if defined? ::ActiveRecord
@@ -181,17 +204,22 @@ module NewRelic
       i << [ 'Gems', @gems.to_a] if not @gems.empty?
       i
     end
-
+    
+    # it's a working jruby if it has the runtime method, and object
+    # space is enabled
     def working_jruby?
       !(defined?(::JRuby) && JRuby.respond_to?(:runtime) && !JRuby.runtime.is_object_space_enabled)
     end
-
+    
+    # Runs through all the objects in ObjectSpace to find the first one that
+    # match the provided class
     def find_class_in_object_space(klass)
       ObjectSpace.each_object(klass) do |x|
         return x
       end
     end
-
+    
+    # Sets the @mongrel instance variable if we can find a Mongrel::HttpServer
     def mongrel
       return @mongrel if @mongrel
       if defined?(::Mongrel) && defined?(::Mongrel::HttpServer) && working_jruby?
@@ -199,7 +227,8 @@ module NewRelic
       end
       @mongrel
     end
-
+    
+    # sets the @unicorn instance variable if we can find a Unicorn::HttpServer
     def unicorn
       return @unicorn if @unicorn
       if (defined?(::Unicorn) && defined?(::Unicorn::HttpServer)) && working_jruby?
@@ -379,6 +408,7 @@ module NewRelic
     end
 
     public
+    # outputs a human-readable description
     def to_s
       s = "LocalEnvironment["
       s << @framework.to_s

data/lib/new_relic/metric_data.rb

@@ -1,7 +1,10 @@
 module NewRelic
   class MetricData
+    # nil, or a NewRelic::MetricSpec object if we have no cached ID
     attr_accessor :metric_spec
+    # nil or a cached integer ID for the metric from the collector.
     attr_accessor :metric_id
+    # the actual statistics object
     attr_accessor :stats
 
     def initialize(metric_spec, stats, metric_id)
@@ -17,7 +20,9 @@ module NewRelic
     def original_spec
       @original_spec || @metric_spec
     end
-
+    
+    # assigns a new metric spec, and retains the old metric spec as
+    # @original_spec if it exists currently
     def metric_spec= new_spec
       @original_spec = @metric_spec if @metric_spec
       @metric_spec = new_spec
@@ -31,7 +36,7 @@ module NewRelic
     def to_json(*a)
        %Q[{"metric_spec":#{metric_id ? 'null' : metric_spec.to_json},"stats":{"total_exclusive_time":#{stats.total_exclusive_time},"min_call_time":#{stats.min_call_time},"call_count":#{stats.call_count},"sum_of_squares":#{stats.sum_of_squares},"total_call_time":#{stats.total_call_time},"max_call_time":#{stats.max_call_time}},"metric_id":#{metric_id ? metric_id : 'null'}}]
     end
-
+    
     def to_s
       if metric_spec
         "#{metric_spec.name}(#{metric_spec.scope}): #{stats}"

data/lib/new_relic/metric_spec.rb

@@ -3,7 +3,8 @@
 class NewRelic::MetricSpec
   attr_accessor   :name
   attr_accessor   :scope
-
+  
+  # the maximum length of a metric name or metric scope
   MAX_LENGTH = 255
   # Need a "zero-arg" constructor so it can be instantiated from java (using
   # jruby) for sending responses to ruby agents from the java collector.
@@ -12,12 +13,13 @@ class NewRelic::MetricSpec
     self.name = (metric_name || '') && metric_name[0...MAX_LENGTH]
     self.scope = metric_scope && metric_scope[0...MAX_LENGTH]
   end
-
+  
+  # truncates the name and scope to the MAX_LENGTH
   def truncate!
     self.name = name[0...MAX_LENGTH] if name && name.size > MAX_LENGTH
     self.scope = scope[0...MAX_LENGTH] if scope && scope.size > MAX_LENGTH
   end
-
+  
   def ==(o)
     self.eql?(o)
   end

data/lib/new_relic/stats.rb

@@ -1,12 +1,13 @@
 
 module NewRelic
   module Stats
-
+    
+    # a stat is absent if its call count equals zero
     def absent?
-      # guess on absent values
       call_count == 0
     end
-
+    
+    # outputs a useful human-readable time given a value in milliseconds
     def time_str(value_ms)
       case
       when value_ms >= 10000
@@ -26,7 +27,7 @@ module NewRelic
         numerator.to_f / denominator
       end
     end
-
+    
     def average_call_time
       checked_calculation(total_call_time, call_count)
     end
@@ -336,7 +337,10 @@ module NewRelic
     end
 
     alias trace_call record_data_point
-
+    
+    # Records multiple data points as one method call - this handles
+    # all the aggregation that would be done with multiple
+    # record_data_point calls
     def record_multiple_data_points(total_value, count=1)
       return record_data_point(total_value) if count == 1
       @call_count += count
@@ -348,11 +352,13 @@ module NewRelic
       @sum_of_squares += (avg_val * avg_val) * count
       self
     end
-
+    
+    # increments the call_count by one
     def increment_count(value = 1)
       @call_count += value
     end
-
+    
+    # outputs a human-readable version of the MethodTraceStats object
     def inspect
       "#<NewRelic::MethodTraceStats #{summary} >"
     end
@@ -369,6 +375,9 @@ module NewRelic
       unscoped_stats.trace_call call_time, exclusive_time
       super call_time, exclusive_time
     end
+    # Records multiple data points as one method call - this handles
+    # all the aggregation that would be done with multiple
+    # trace_call calls    
     def record_multiple_data_points(total_value, count=1)
       unscoped_stats.record_multiple_data_points(total_value, count)
       super total_value, count

data/lib/new_relic/transaction_analysis.rb

@@ -15,11 +15,12 @@ module NewRelic
     # limit the data set to the top n
     def breakdown_data(limit = nil)
       metric_hash = {}
-      each_segment do |segment|
+      each_segment_with_nest_tracking do |segment|
         unless segment == root_segment
           metric_name = segment.metric_name
           metric_hash[metric_name] ||= SegmentSummary.new(metric_name, self)
           metric_hash[metric_name] << segment
+          metric_hash[metric_name]
         end
       end
 

data/lib/new_relic/transaction_analysis/segment_summary.rb

@@ -3,11 +3,12 @@ module NewRelic
     # summarizes performance data for all calls to segments
     # with the same metric_name
     class SegmentSummary
-      attr_accessor :metric_name, :total_time, :exclusive_time, :call_count
+      attr_accessor :metric_name, :total_time, :exclusive_time, :call_count, :current_nest_count
       def initialize(metric_name, sample)
         @metric_name = metric_name
         @total_time, @exclusive_time, @call_count = 0,0,0
         @sample = sample
+        @current_nest_count = 0
       end
 
       def <<(segment)
@@ -15,7 +16,8 @@ module NewRelic
           raise ArgumentError, "Metric Name Mismatch: #{segment.metric_name} != #{metric_name}"
         end
 
-        @total_time += segment.duration
+        # a nested segment should use the sum of the top level totals
+        @total_time += segment.duration if current_nest_count == 0
         @exclusive_time += segment.exclusive_duration
         @call_count += 1
       end

data/lib/new_relic/transaction_sample.rb

@@ -3,8 +3,11 @@ require 'new_relic/transaction_sample/summary_segment'
 require 'new_relic/transaction_sample/fake_segment'
 require 'new_relic/transaction_sample/composite_segment'
 module NewRelic
+  # the number of segments that need to exist before we roll them up
+  # into one segment with multiple executions
   COLLAPSE_SEGMENTS_THRESHOLD = 2
 
+  # columns for a mysql explain plan
   MYSQL_EXPLAIN_COLUMNS = [
         "Id",
         "Select Type",
@@ -34,7 +37,11 @@ module NewRelic
       def obfuscate_sql(sql)
         NewRelic::Agent.instance.obfuscator.call(sql)
       end
-
+      
+      # Returns a cached connection for a given ActiveRecord
+      # configuration - these are stored or reopened as needed, and if
+      # we cannot get one, we ignore it and move on without explaining
+      # the sql
       def get_connection(config)
         @@connections ||= {}
 
@@ -51,7 +58,8 @@ module NewRelic
           nil
         end
       end
-
+      
+      # Closes all the connections in the internal connection cache
       def close_connections
         @@connections ||= {}
         @@connections.values.each do |connection|
@@ -77,7 +85,10 @@ module NewRelic
     def count_segments
       @root_segment.count_segments - 1    # don't count the root segment
     end
-
+    
+    # Truncates the transaction sample to a maximum length determined
+    # by the passed-in parameter. Operates recursively on the entire
+    # tree of transaction segments in a depth-first manner
     def truncate(max)
       count = count_segments
       return if count < max
@@ -85,7 +96,9 @@ module NewRelic
 
       ensure_segment_count_set(count)
     end
-
+    
+    # makes sure that the parameter cache for segment count is set to
+    # the correct value
     def ensure_segment_count_set(count)
       params[:segment_count] ||= count
     end
@@ -122,15 +135,25 @@ module NewRelic
     def duration
       root_segment.duration
     end
-
+    
+    # Iterates recursively over each segment in the entire transaction
+    # sample tree
     def each_segment(&block)
       @root_segment.each_segment(&block)
     end
 
+    # Iterates recursively over each segment in the entire transaction
+    # sample tree while keeping track of nested segments
+    def each_segment_with_nest_tracking(&block)
+      @root_segment.each_segment_with_nest_tracking(&block)
+    end
+
     def to_s_compact
       @root_segment.to_s_compact
     end
-
+    
+    # Searches the tree recursively for the segment with the given
+    # id. note that this is an internal id, not an ActiveRecord id
     def find_segment(id)
       @root_segment.find_segment(id)
     end
@@ -202,7 +225,8 @@ module NewRelic
     end
 
   private
-
+    
+    # This is badly in need of refactoring
     def build_segment_with_omissions(new_sample, time_delta, source_segment, target_segment, regex)
       source_segment.called_segments.each do |source_called_segment|
         # if this segment's metric name matches the given regular expression, bail
@@ -233,6 +257,8 @@ module NewRelic
     end
 
     # see prepare_to_send for what we do with options
+    #
+    # This is badly in need of refactoring
     def build_segment_for_transfer(new_sample, source_segment, target_segment, options)
       source_segment.called_segments.each do |source_called_segment|
         target_called_segment = new_sample.create_segment(