newrelic_rpm 3.1.0 → 3.1.1.beta1

data/lib/new_relic/agent/instrumentation.rb

@@ -1,8 +1,8 @@
 require 'new_relic/agent'
-# stub module that contains instrumentation defined in the
-# instrumentation directory
 module NewRelic
   module Agent
+    # stub module that contains instrumentation defined in the
+    # instrumentation directory
     module Instrumentation
     end
   end

data/lib/new_relic/agent/instrumentation/active_merchant.rb

@@ -2,7 +2,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(ActiveMerchant)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing ActiveMerchant instrumentation'
+  end
+  
   executes do
     ActiveMerchant::Billing::Gateway.implementations.each do |gateway|
       gateway.class_eval do

data/lib/new_relic/agent/instrumentation/acts_as_solr.rb

@@ -33,7 +33,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(ActsAsSolr::CommonMethods)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing ActsAsSolr instrumentation'
+  end
+  
   executes do
     ActsAsSolr::ParserMethods.module_eval do
       include NewRelic::Instrumentation::ActsAsSolrInstrumentation::ParserMethodsInstrumentation

data/lib/new_relic/agent/instrumentation/authlogic.rb

@@ -5,6 +5,10 @@ DependencyDetection.defer do
       defined?(AuthLogic::Session::Base)
   end
 
+  executes do
+    NewRelic::Agent.logger.debug 'Installing AuthLogic instrumentation'
+  end  
+  
   executes do
     AuthLogic::Session::Base.class_eval do
       add_method_tracer :find, 'Custom/Authlogic/find'

data/lib/new_relic/agent/instrumentation/controller_instrumentation.rb

@@ -276,18 +276,26 @@ module NewRelic
         def newrelic_request_headers
           self.respond_to?(:request) && self.request.respond_to?(:headers) && self.request.headers
         end
-
+        
+        # overrideable method to determine whether to trace an action
+        # or not - you may override this in your controller and supply
+        # your own logic for ignoring transactions.
         def do_not_trace?
           _is_filtered?('do_not_trace')
         end
-
+        
+        # overrideable method to determine whether to trace an action
+        # for purposes of apdex measurement - you can use this to
+        # ignore things like api calls or other fast non-user-facing
+        # actions
         def ignore_apdex?
           _is_filtered?('ignore_apdex')
         end
 
         private
 
-        # Profile the instrumented call.  Dev mode only.  Experimental.
+        # Profile the instrumented call.  Dev mode only.  Experimental
+        # - should definitely not be used on production applications
         def perform_action_with_newrelic_profile(args)
           frame_data = _push_metric_frame(block_given? ? args : [])
           val = nil
@@ -358,7 +366,8 @@ module NewRelic
           [category, path, params]
         end
 
-        # Filter out
+        # Filter out a request if it matches one of our parameters for
+        # ignoring it - the key is either 'do_not_trace' or 'ignore_apdex'
         def _is_filtered?(key)
           ignore_actions = self.class.newrelic_read_attr(key) if self.class.respond_to? :newrelic_read_attr
           case ignore_actions
@@ -402,7 +411,9 @@ module NewRelic
           NewRelic::Control.instance.log.debug("#{e.backtrace[0..20]}")
           now
         end
-
+        
+        # returns the NewRelic::MethodTraceStats object associated
+        # with the dispatcher time measurement
         def _dispatch_stat
           NewRelic::Agent.agent.stats_engine.get_stats_no_scope 'HttpDispatcher'
         end

data/lib/new_relic/agent/instrumentation/data_mapper.rb

@@ -53,7 +53,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(DataMapper::Collection)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing DataMapper instrumentation'
+  end
+  
   executes do
     DataMapper::Model.class_eval do
       add_method_tracer :get,      'ActiveRecord/#{self.name}/get'

data/lib/new_relic/agent/instrumentation/delayed_job_instrumentation.rb

@@ -8,7 +8,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(::Delayed) && defined?(::Delayed::Job)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing DelayedJob instrumentation'
+  end
+  
   executes do
     Delayed::Job.class_eval do
       include NewRelic::Agent::Instrumentation::ControllerInstrumentation

data/lib/new_relic/agent/instrumentation/memcache.rb

@@ -45,7 +45,11 @@ DependencyDetection.defer do
   depends_on do
     !NewRelic::Control.instance['disable_memcache_instrumentation']
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Memcached instrumentation'
+  end
+  
   executes do
     %w[get get_multi set add incr decr delete replace append prepend cas].each do | method_name |
       NewRelic::Agent::Instrumentation::Memcache.instrument_method(::MemCache, method_name) if defined? ::MemCache

data/lib/new_relic/agent/instrumentation/merb/controller.rb

@@ -5,7 +5,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(Merb) && defined?(Merb::Controller)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Merb Controller instrumentation'
+  end
+  
   executes do
     require 'merb-core/controller/merb_controller'
 

data/lib/new_relic/agent/instrumentation/merb/errors.rb

@@ -6,7 +6,11 @@ DependencyDetection.defer do
   depends_on do
     Merb::Dispatcher::DefaultException.respond_to?(:before)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Merb Errors instrumentation'
+  end
+  
   executes do
 
     # Hook in the notification to merb

data/lib/new_relic/agent/instrumentation/metric_frame/pop.rb

@@ -17,10 +17,6 @@ module NewRelic
             NewRelic::Agent.logger.error "Underflow in metric frames: #{caller.join("\n   ")}"
           end
 
-          def process_histogram_for_transaction(ending)
-            agent.histogram.process((ending - start).to_f)
-          end
-
           def notice_scope_empty
             transaction_sampler.notice_scope_empty
           end
@@ -59,7 +55,6 @@ module NewRelic
 
           def notify_transaction_sampler(web_transaction)
             record_transaction_cpu
-            process_histogram_for_transaction(Time.now) if web_transaction
             notice_scope_empty
           end
 

data/lib/new_relic/agent/instrumentation/net.rb

@@ -2,7 +2,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(Net) && defined?(Net::HTTP)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Net instrumentation'
+  end
+  
   executes do
     Net::HTTP.class_eval do
       def request_with_newrelic_trace(*args, &block)

data/lib/new_relic/agent/instrumentation/rails/action_controller.rb

@@ -1,3 +1,5 @@
+# FIXME: this should be a separate dependency block for each kind of
+# view instrumentation
 DependencyDetection.defer do
   depends_on do
     defined?(ActionController) && defined?(ActionController::Base)
@@ -11,8 +13,7 @@ DependencyDetection.defer do
     !NewRelic::Control.instance['disable_view_instrumentation']
   end
 
-  executes do
-
+  executes do    
     case Rails::VERSION::STRING
 
     when /^(1\.|2\.0)/  # Rails 1.* - 2.0
@@ -48,9 +49,12 @@ DependencyDetection.defer do
   depends_on do
     defined?(Rails) && Rails::VERSION::MAJOR.to_i == 2
   end
-
+  
   executes do
+    NewRelic::Agent.logger.debug 'Installing Rails Controller instrumentation'
+  end
 
+  executes do
     ActionController::Base.class_eval do
       include NewRelic::Agent::Instrumentation::ControllerInstrumentation
 

data/lib/new_relic/agent/instrumentation/rails/action_web_service.rb

@@ -2,7 +2,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(ActionWebService)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Rails ActionWebService instrumentation'
+  end  
+  
   executes do
     # NewRelic Agent instrumentation for WebServices
 

data/lib/new_relic/agent/instrumentation/rails/active_record_instrumentation.rb

@@ -87,7 +87,11 @@ DependencyDetection.defer do
   depends_on do
     !NewRelic::Control.instance['disable_activerecord_instrumentation']
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Rails ActiveRecord instrumentation'
+  end
+  
   executes do
     ActiveRecord::ConnectionAdapters::AbstractAdapter.module_eval do
       include ::NewRelic::Agent::Instrumentation::ActiveRecordInstrumentation

data/lib/new_relic/agent/instrumentation/rails/errors.rb

@@ -7,6 +7,10 @@ DependencyDetection.defer do
     defined?(Rails) && Rails::VERSION::MAJOR.to_i == 2
   end
 
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Rails Error instrumentation'
+  end  
+  
   executes do
 
     ActionController::Base.class_eval do

data/lib/new_relic/agent/instrumentation/rails3/action_controller.rb

@@ -50,6 +50,10 @@ DependencyDetection.defer do
     defined?(ActionController) && defined?(ActionController::Base)
   end
 
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Rails3 Controller instrumentation'
+  end  
+  
   executes do
     class ActionController::Base
       include NewRelic::Agent::Instrumentation::ControllerInstrumentation

data/lib/new_relic/agent/instrumentation/rails3/active_record_instrumentation.rb

@@ -13,9 +13,11 @@ module NewRelic
           end
         end
 
-        def log_with_newrelic_instrumentation(sql, name, &block)
+        def log_with_newrelic_instrumentation(*args, &block)
 
-          return log_without_newrelic_instrumentation(sql, name, &block) unless NewRelic::Agent.is_execution_traced?
+          return log_without_newrelic_instrumentation(*args, &block) unless NewRelic::Agent.is_execution_traced?
+
+          sql, name, binds = args
 
           # Capture db config if we are going to try to get the explain plans
           if (defined?(ActiveRecord::ConnectionAdapters::MysqlAdapter) && self.is_a?(ActiveRecord::ConnectionAdapters::MysqlAdapter)) ||
@@ -26,7 +28,7 @@ module NewRelic
             model = parts.first
             operation = parts.last.downcase
             metric_name = case operation
-                          when 'load' then 'find'
+                          when 'load', 'count', 'exists' then 'find'
                           when 'indexes', 'columns' then nil # fall back to DirectSQL
                           when 'destroy', 'find', 'save', 'create' then operation
                           when 'update' then 'save'
@@ -53,14 +55,15 @@ module NewRelic
           end
 
           if !metric
-            log_without_newrelic_instrumentation(sql, name, &block)
+            log_without_newrelic_instrumentation(*args, &block)
           else
             metrics = [metric, "ActiveRecord/all"]
             metrics << "ActiveRecord/#{metric_name}" if metric_name
             self.class.trace_execution_scoped(metrics) do
+              sql, name, binds = args
               t0 = Time.now
               begin
-                log_without_newrelic_instrumentation(sql, name, &block)
+                log_without_newrelic_instrumentation(*args, &block)
               ensure
                 NewRelic::Agent.instance.transaction_sampler.notice_sql(sql, supported_config, (Time.now - t0).to_f)
               end
@@ -89,7 +92,11 @@ DependencyDetection.defer do
   depends_on do
     !NewRelic::Control.instance['disable_activerecord_instrumentation']
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Rails3 ActiveRecord instrumentation'
+  end
+  
   executes do
     Rails.configuration.after_initialize do
       ActiveRecord::ConnectionAdapters::AbstractAdapter.module_eval do

data/lib/new_relic/agent/instrumentation/rails3/errors.rb

@@ -23,6 +23,10 @@ DependencyDetection.defer do
     defined?(ActionController) && defined?(ActionController::Base)
   end
 
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Rails3 Error instrumentation'
+  end
+
   executes do
     class ActionController::Base
       include NewRelic::Agent::Instrumentation::Rails3::Errors

data/lib/new_relic/agent/instrumentation/sinatra.rb

@@ -5,6 +5,10 @@ DependencyDetection.defer do
     defined?(::Sinatra) && defined?(::Sinatra::Base)
   end
 
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Sinatra instrumentation'
+  end
+
   executes do
     ::Sinatra::Base.class_eval do
       include NewRelic::Agent::Instrumentation::Sinatra

data/lib/new_relic/agent/instrumentation/sunspot.rb

@@ -3,6 +3,10 @@ DependencyDetection.defer do
     defined?(::Sunspot)
   end
 
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Rails Sunspot instrumentation'
+  end
+  
   executes do
     ::Sunspot.module_eval do
       class << self

data/lib/new_relic/agent/instrumentation/unicorn_instrumentation.rb

@@ -2,7 +2,11 @@ DependencyDetection.defer do
   depends_on do
     defined?(::Unicorn) && defined?(::Unicorn::HttpServer)
   end
-
+  
+  executes do
+    NewRelic::Agent.logger.debug 'Installing Unicorn instrumentation'
+  end
+  
   executes do
     Unicorn::HttpServer.class_eval do
       NewRelic::Agent.logger.debug "Installing Unicorn worker hook."

data/lib/new_relic/agent/method_tracer.rb

@@ -44,7 +44,9 @@ module NewRelic
         clazz.extend ClassMethods
         clazz.extend InstanceMethods
       end
-
+      
+      # Defines modules used at instrumentation runtime, to do the
+      # actual tracing of time spent
       module InstanceMethods
         # Deprecated: original method preserved for API backward compatibility.
         # Use either #trace_execution_scoped or #trace_execution_unscoped
@@ -90,35 +92,51 @@ module NewRelic
         end
 
         alias trace_method_execution_no_scope trace_execution_unscoped #:nodoc:
-
+        
+        # Refactored out of the previous trace_execution_scoped
+        # method, most methods in this module relate to code used in
+        # the #trace_execution_scoped method in this module
         module TraceExecutionScoped
+          # Shorthand to return the NewRelic::Agent.instance
           def agent_instance
             NewRelic::Agent.instance
           end
-
+          
+          # Shorthand to return the status of tracing
           def traced?
             NewRelic::Agent.is_execution_traced?
           end
-
+          
+          # Tracing is disabled if we are not in a traced context and
+          # no force option is supplied
           def trace_disabled?(options)
             !(traced? || options[:force])
           end
-
+          
+          # Shorthand to return the current statistics engine
           def stat_engine
             agent_instance.stats_engine
           end
-
+          
+          # returns a scoped metric stat for the specified name
           def get_stats_scoped(first_name, scoped_metric_only)
             stat_engine.get_stats(first_name, true, scoped_metric_only)
           end
+          # Shorthand method to get stats from the stat engine
           def get_stats_unscoped(name)
             stat_engine.get_stats_no_scope(name)
           end
-
+          
+          # the main statistic we should record in
+          # #trace_execution_scoped - a scoped metric provided by the
+          # first item in the metric array
           def main_stat(metric, options)
             get_stats_scoped(metric, options[:scoped_metric_only])
           end
-
+          
+          # returns an array containing the first metric, and an array
+          # of other unscoped statistics we should also record along
+          # side it
           def get_metric_stats(metrics, options)
             metrics = Array(metrics)
             first_name = metrics.shift
@@ -128,26 +146,51 @@ module NewRelic
             stats.unshift(main_stat(first_name, options)) if options[:metric]
             [first_name, stats]
           end
-
+          
+          # Helper for setting a hash key if the hash key is nil,
+          # instead of the default ||= behavior which sets if it is
+          # false as well
           def set_if_nil(hash, key)
             hash[key] = true if hash[key].nil?
           end
-
+          
+          # delegates to #agent_instance to push a trace execution
+          # flag, only if execution of this metric is forced.
+          #
+          # This causes everything scoped inside this metric to be
+          # recorded, even if the parent transaction is generally not.
           def push_flag!(forced)
             agent_instance.push_trace_execution_flag(true) if forced
           end
-
+          
+          # delegates to #agent_instance to pop the trace execution
+          # flag, only if execution of this metric is
+          # forced. otherwise this is taken care of for us
+          # automatically.
+          #
+          # This ends the forced recording of metrics within the
+          # #trace_execution_scoped block
           def pop_flag!(forced)
             agent_instance.pop_trace_execution_flag if forced
           end
-
+          
+          # helper for logging errors to the newrelic_agent.log
+          # properly. Logs the error at error level, and includes a
+          # backtrace if we're running at debug level
           def log_errors(code_area, metric)
             yield
           rescue => e
             NewRelic::Control.instance.log.error("Caught exception in #{code_area}. Metric name = #{metric}, exception = #{e}")
             NewRelic::Control.instance.log.error(e.backtrace.join("\n"))
           end
-
+          
+          # provides the header for our traced execution scoped
+          # method - gets the initial time, sets the tracing flag if
+          # needed, and pushes the scope onto the metric stack
+          # logs any errors that occur and returns the start time and
+          # the scope so that we can check for it later, to maintain
+          # sanity. If the scope stack becomes unbalanced, this
+          # transaction loses meaning.
           def trace_execution_scoped_header(metric, options, t0=Time.now.to_f)
             scope = log_errors("trace_execution_scoped header", metric) do
               push_flag!(options[:force])
@@ -157,7 +200,15 @@ module NewRelic
             # the start time.
             [t0, scope]
           end
-
+          
+          # Handles the end of the #trace_execution_scoped method -
+          # calculating the time taken, popping the tracing flag if
+          # needed, deducting time taken by children, and tracing the
+          # subsidiary unscoped metrics if any
+          #
+          # this method fails safely if the header does not manage to
+          # push the scope onto the stack - it simply does not trace
+          # any metrics.
           def trace_execution_scoped_footer(t0, first_name, metric_stats, expected_scope, forced, t1=Time.now.to_f)
             log_errors("trace_method_execution footer", first_name) do
               duration = t1 - t0
@@ -198,99 +249,51 @@ module NewRelic
         include TraceExecutionScoped
 
       end
-
+      
+      # Defines methods used at the class level, for adding instrumentation
       module ClassMethods
-        # Add a method tracer to the specified method.
-        #
-        # === Common Options
-        #
-        # * <tt>:push_scope => false</tt> specifies this method tracer should not
-        #   keep track of the caller; it will not show up in controller breakdown
-        #   pie charts.
-        # * <tt>:metric => false</tt> specifies that no metric will be recorded.
-        #   Instead the call will show up in transaction traces as well as traces
-        #   shown in Developer Mode.
-        #
-        # === Uncommon Options
-        #
-        # * <tt>:scoped_metric_only => true</tt> indicates that the unscoped metric
-        #   should not be recorded.  Normally two metrics are potentially created
-        #   on every invocation: the aggregate method where statistics for all calls
-        #   of that metric are stored, and the "scoped metric" which records the
-        #   statistics for invocations in a particular scope--generally a controller
-        #   action.  This option indicates that only the second type should be recorded.
-        #   The effect is similar to <tt>:metric => false</tt> but in addition you
-        #   will also see the invocation in breakdown pie charts.
-        # * <tt>:deduct_call_time_from_parent => false</tt> indicates that the method invocation
-        #   time should never be deducted from the time reported as 'exclusive' in the
-        #   caller.  You would want to use this if you are tracing a recursive method
-        #   or a method that might be called inside another traced method.
-        # * <tt>:code_header</tt> and <tt>:code_footer</tt> specify ruby code that
-        #   is inserted into the tracer before and after the call.
-        # * <tt>:force = true</tt> will ensure the metric is captured even if called inside
-        #   an untraced execution call.  (See NewRelic::Agent#disable_all_tracing)
-        #
-        # === Overriding the metric name
-        #
-        # +metric_name_code+ is a string that is eval'd to get the
-        # name of the metric associated with the call, so if you want to
-        # use interpolaion evaluated at call time, then single quote
-        # the value like this:
-        #
-        #     add_method_tracer :foo, 'Custom/#{self.class.name}/foo'
-        #
-        # This would name the metric according to the class of the runtime
-        # intance, as opposed to the class where +foo+ is defined.
-        #
-        # If not provided, the metric name will be <tt>Custom/ClassName/method_name</tt>.
-        #
-        # === Examples
-        #
-        # Instrument +foo+ only for custom views--will not show up in transaction traces or caller breakdown graphs:
-        #
-        #     add_method_tracer :foo, :push_scope => false
-        #
-        # Instrument +foo+ just for transaction traces only:
-        #
-        #     add_method_tracer :foo, :metric => false
-        #
-        # Instrument +foo+ so it shows up in transaction traces and caller breakdown graphs
-        # for actions:
-        #
-        #     add_method_tracer :foo
-        #
-        # which is equivalent to:
-        #
-        #     add_method_tracer :foo, 'Custom/#{self.class.name}/foo', :push_scope => true, :metric => true
-        #
-        # Instrument the class method +foo+ with the metric name 'Custom/People/fetch':
-        #
-        #     class << self
-        #       add_method_tracer :foo, 'Custom/People/fetch'
-        #     end
-        #
-
+        # contains methods refactored out of the #add_method_tracer method
         module AddMethodTracer
           ALLOWED_KEYS = [:force, :metric, :push_scope, :deduct_call_time_from_parent, :code_header, :code_footer, :scoped_metric_only].freeze
-
+          
+          # used to verify that the keys passed to
+          # NewRelic::Agent::MethodTracer::ClassMethods#add_method_tracer
+          # are valid. Returns a list of keys that were unexpected
           def unrecognized_keys(expected, given)
             given.keys - expected
           end
-
+          
+          # used to verify that the keys passed to
+          # NewRelic::Agent::MethodTracer::ClassMethods#add_method_tracer
+          # are valid. checks the expected list against the list
+          # actually provided
           def any_unrecognized_keys?(expected, given)
             unrecognized_keys(expected, given).any?
           end
-
+          
+          # raises an error when the
+          # NewRelic::Agent::MethodTracer::ClassMethods#add_method_tracer
+          # method is called with improper keys. This aids in
+          # debugging new instrumentation by failing fast
           def check_for_illegal_keys!(options)
             if any_unrecognized_keys?(ALLOWED_KEYS, options)
               raise "Unrecognized options in add_method_tracer_call: #{unrecognized_keys(ALLOWED_KEYS, options).join(', ')}"
             end
           end
-
+          
+          # Sets the options for deducting call time from
+          # parents. This defaults to true if we are recording a metric, but
+          # can be overridden by the user if desired.
+          #
+          # has the effect of not allowing overlapping times, and
+          # should generally be true
           def set_deduct_call_time_based_on_metric(options)
             {:deduct_call_time_from_parent => !!options[:metric]}.merge(options)
           end
-
+          
+          # validity checking - add_method_tracer must receive either
+          # push scope or metric, or else it would record no
+          # data. Raises an error if this is the case
           def check_for_push_scope_and_metric(options)
             unless options[:push_scope] || options[:metric]
               raise "Can't add a tracer where push_scope is false and metric is false"
@@ -298,7 +301,11 @@ module NewRelic
           end
 
           DEFAULT_SETTINGS = {:push_scope => true, :metric => true, :force => false, :code_header => "", :code_footer => "", :scoped_metric_only => false}.freeze
-
+          
+          # Checks the provided options to make sure that they make
+          # sense. Raises an error if the options are incorrect to
+          # assist with debugging, so that errors occur at class
+          # construction time rather than instrumentation run time
           def validate_options(options)
             raise TypeError.new("provided options must be a Hash") unless options.is_a?(Hash)
             check_for_illegal_keys!(options)
@@ -308,28 +315,45 @@ module NewRelic
           end
 
           # Default to the class where the method is defined.
+          #
+          # Example:
+          #  Foo.default_metric_name_code('bar') #=> "Custom/#{Foo.name}/bar"
           def default_metric_name_code(method_name)
             "Custom/#{self.name}/#{method_name.to_s}"
           end
-
+          
+          # Checks to see if the method we are attempting to trace
+          # actually exists or not. #add_method_tracer can't do
+          # anything if the method doesn't exist.
           def newrelic_method_exists?(method_name)
             exists = method_defined?(method_name) || private_method_defined?(method_name)
             NewRelic::Control.instance.log.warn("Did not trace #{self.name}##{method_name} because that method does not exist") unless exists
             exists
           end
-
+          
+          # Checks to see if we have already traced a method with a
+          # given metric by checking to see if the traced method
+          # exists. Warns the user if methods are being double-traced
+          # to help with debugging custom instrumentation.
           def traced_method_exists?(method_name, metric_name_code)
             exists = method_defined?(_traced_method_name(method_name, metric_name_code))
             NewRelic::Control.instance.log.warn("Attempt to trace a method twice with the same metric: Method = #{method_name}, Metric Name = #{metric_name_code}") if exists
             exists
           end
-
+          
+          # Returns a code snippet to be eval'd that skips tracing
+          # when the agent is not tracing execution. turns
+          # instrumentation into effectively one method call overhead
+          # when the agent is disabled
           def assemble_code_header(method_name, metric_name_code, options)
             unless options[:force]
               "return #{_untraced_method_name(method_name, metric_name_code)}(*args, &block) unless NewRelic::Agent.is_execution_traced?\n"
             end.to_s + options[:code_header].to_s
           end
-
+          
+          # returns an eval-able string that contains the traced
+          # method code used if the agent is not creating a scope for
+          # use in scoped metrics.
           def method_without_push_scope(method_name, metric_name_code, options)
             "def #{_traced_method_name(method_name, metric_name_code)}(*args, &block)
               #{assemble_code_header(method_name, metric_name_code, options)}
@@ -347,6 +371,8 @@ module NewRelic
             end"
           end
 
+          # returns an eval-able string that contains the tracing code
+          # for a fully traced metric including scoping
           def method_with_push_scope(method_name, metric_name_code, options)
             klass = (self === Module) ? "self" : "self.class"
 
@@ -363,7 +389,9 @@ module NewRelic
               result
             end"
           end
-
+          
+          # Decides which code snippet we should be eval'ing in this
+          # context, based on the options.
           def code_to_eval(method_name, metric_name_code, options)
             options = validate_options(options)
             if options[:push_scope]
@@ -375,6 +403,77 @@ module NewRelic
         end
         include AddMethodTracer
 
+
+        
+        # Add a method tracer to the specified method.
+        #
+        # === Common Options
+        #
+        # * <tt>:push_scope => false</tt> specifies this method tracer should not
+        #   keep track of the caller; it will not show up in controller breakdown
+        #   pie charts.
+        # * <tt>:metric => false</tt> specifies that no metric will be recorded.
+        #   Instead the call will show up in transaction traces as well as traces
+        #   shown in Developer Mode.
+        #
+        # === Uncommon Options
+        #
+        # * <tt>:scoped_metric_only => true</tt> indicates that the unscoped metric
+        #   should not be recorded.  Normally two metrics are potentially created
+        #   on every invocation: the aggregate method where statistics for all calls
+        #   of that metric are stored, and the "scoped metric" which records the
+        #   statistics for invocations in a particular scope--generally a controller
+        #   action.  This option indicates that only the second type should be recorded.
+        #   The effect is similar to <tt>:metric => false</tt> but in addition you
+        #   will also see the invocation in breakdown pie charts.
+        # * <tt>:deduct_call_time_from_parent => false</tt> indicates that the method invocation
+        #   time should never be deducted from the time reported as 'exclusive' in the
+        #   caller.  You would want to use this if you are tracing a recursive method
+        #   or a method that might be called inside another traced method.
+        # * <tt>:code_header</tt> and <tt>:code_footer</tt> specify ruby code that
+        #   is inserted into the tracer before and after the call.
+        # * <tt>:force = true</tt> will ensure the metric is captured even if called inside
+        #   an untraced execution call.  (See NewRelic::Agent#disable_all_tracing)
+        #
+        # === Overriding the metric name
+        #
+        # +metric_name_code+ is a string that is eval'd to get the
+        # name of the metric associated with the call, so if you want to
+        # use interpolaion evaluated at call time, then single quote
+        # the value like this:
+        #
+        #     add_method_tracer :foo, 'Custom/#{self.class.name}/foo'
+        #
+        # This would name the metric according to the class of the runtime
+        # intance, as opposed to the class where +foo+ is defined.
+        #
+        # If not provided, the metric name will be <tt>Custom/ClassName/method_name</tt>.
+        #
+        # === Examples
+        #
+        # Instrument +foo+ only for custom views--will not show up in transaction traces or caller breakdown graphs:
+        #
+        #     add_method_tracer :foo, :push_scope => false
+        #
+        # Instrument +foo+ just for transaction traces only:
+        #
+        #     add_method_tracer :foo, :metric => false
+        #
+        # Instrument +foo+ so it shows up in transaction traces and caller breakdown graphs
+        # for actions:
+        #
+        #     add_method_tracer :foo
+        #
+        # which is equivalent to:
+        #
+        #     add_method_tracer :foo, 'Custom/#{self.class.name}/foo', :push_scope => true, :metric => true
+        #
+        # Instrument the class method +foo+ with the metric name 'Custom/People/fetch':
+        #
+        #     class << self
+        #       add_method_tracer :foo, 'Custom/People/fetch'
+        #     end
+        #
         def add_method_tracer(method_name, metric_name_code=nil, options = {})
           return unless newrelic_method_exists?(method_name)
           metric_name_code ||= default_metric_name_code(method_name)
@@ -404,15 +503,22 @@ module NewRelic
           end
         end
         private
-
+        
+        # given a method and a metric, this method returns the
+        # untraced alias of the method name
         def _untraced_method_name(method_name, metric_name)
           "#{_sanitize_name(method_name)}_without_trace_#{_sanitize_name(metric_name)}"
         end
-
+        
+        # given a method and a metric, this method returns the traced
+        # alias of the method name
         def _traced_method_name(method_name, metric_name)
           "#{_sanitize_name(method_name)}_with_trace_#{_sanitize_name(metric_name)}"
         end
-
+        
+        # makes sure that method names do not contain characters that
+        # might break the interpreter, for example ! or ? characters
+        # that are not allowed in the middle of method names 
         def _sanitize_name(name)
           name.to_s.tr_s('^a-zA-Z0-9', '_')
         end