newrelic_rpm 3.1.0 → 3.1.1.beta1

data/lib/new_relic/agent/beacon_configuration.rb

@@ -1,16 +1,39 @@
 module NewRelic
   module Agent
+    # This class contains the configuration data for setting up RUM
+    # headers and footers - acts as a cache of this data so we don't
+    # need to look it up or reconfigure it every request
     class BeaconConfiguration
+
+      # the statically generated header - generated when the beacon
+      # configuration is created - does not vary per page
       attr_reader :browser_timing_header
+
+      # the static portion of the RUM footer - this part does not vary
+      # by which request is in progress
       attr_reader :browser_timing_static_footer
+      
+      # the application id we include in the javascript -
+      # crossreferences with the application id on the collectors
       attr_reader :application_id
+
+      # the key used for browser monitoring. This is different from
+      # the account key
       attr_reader :browser_monitoring_key
+
+      # which beacon we should report to - set by startup of the agent
       attr_reader :beacon
-      attr_reader :rum_enabled
-      attr_reader :license_bytes
 
+      # whether RUM is enabled or not - determined based on server and
+      # local config
+      attr_reader :rum_enabled
+      
+      # A static javascript header that is identical for every account
+      # and application
       JS_HEADER = "<script type=\"text/javascript\">var NREUMQ=[];NREUMQ.push([\"mark\",\"firstbyte\",new Date().getTime()]);</script>"
-
+      
+      # Creates a new browser configuration data. Argument is a hash
+      # of configuration values from the server
       def initialize(connect_data)
         @browser_monitoring_key = connect_data['browser_key']
         @application_id = connect_data['application_id']
@@ -23,7 +46,9 @@ module NewRelic
         @browser_timing_static_footer = build_load_file_js(connect_data)
         NewRelic::Control.instance.log.debug("Browser timing static footer: #{@browser_timing_static_footer.inspect}")
       end
-
+      
+      # returns a memoized version of the bytes in the license key for
+      # obscuring transaction names in the javascript
       def license_bytes
         if @license_bytes.nil?
           @license_bytes = []
@@ -31,18 +56,35 @@ module NewRelic
         end
         @license_bytes
       end
-
+      
+      # returns a snippet of text that does not change
+      # per-transaction. Is empty when rum is disabled, or we are not
+      # including the episodes file dynamically (i.e. the user
+      # includes it themselves)
       def build_load_file_js(connect_data)
         return "" unless connect_data.fetch('rum.load_episodes_file', true)
 
         episodes_url = connect_data.fetch('episodes_url', '')
-        "(function(){var d=document;var e=d.createElement(\"script\");e.async=true;e.src=\"#{episodes_url}\";e.type=\"text/javascript\";var s=d.getElementsByTagName(\"script\")[0];s.parentNode.insertBefore(e,s);})();"
+        
+<<-eos
+if (!NREUMQ.f) NREUMQ.f=function() {
+NREUMQ.push(["load",new Date().getTime()]);
+var e=document.createElement(\"script\");
+e.type=\"text/javascript\";e.async=true;e.src=\"#{episodes_url}\";
+document.body.appendChild(e);
+if(NREUMQ.a)NREUMQ.a();
+};
+if(window.onload!==NREUMQ.f){NREUMQ.a=window.onload;window.onload=NREUMQ.f;};
+eos
       end
 
+      # returns a copy of the static javascript header, in case people
+      # are munging strings somewhere down the line
       def javascript_header
         JS_HEADER.dup
       end
-
+      
+      # Returns the header string, properly html-safed if needed
       def build_browser_timing_header
         return "" if !@rum_enabled
         return "" if @browser_monitoring_key.nil?

data/lib/new_relic/agent/browser_monitoring.rb

@@ -2,8 +2,19 @@ require 'base64'
 require 'new_relic/agent/beacon_configuration'
 module NewRelic
   module Agent
+    # This module contains support for Real User Monitoring - the
+    # javascript generation and configuration
     module BrowserMonitoring
-
+      
+      # This method returns a string suitable for inclusion in a page
+      # - known as 'manual instrumentation' for Real User
+      # Monitoring. Can return either a script tag with associated
+      # javascript, or in the case of disabled Real User Monitoring,
+      # an empty string
+      #
+      # This is the header string - it should be placed as high in the
+      # page as is reasonably possible - that is, before any style or
+      # javascript inclusions, but after any header-related meta tags
       def browser_timing_header
         return "" if NewRelic::Agent.instance.beacon_configuration.nil?
         return "" if !NewRelic::Agent.is_transaction_traced? || !NewRelic::Agent.is_execution_traced?
@@ -11,6 +22,14 @@ module NewRelic
         NewRelic::Agent.instance.beacon_configuration.browser_timing_header
       end
 
+      # This method returns a string suitable for inclusion in a page
+      # - known as 'manual instrumentation' for Real User
+      # Monitoring. Can return either a script tag with associated
+      # javascript, or in the case of disabled Real User Monitoring,
+      # an empty string
+      #
+      # This is the footer string - it should be placed as low in the
+      # page as is reasonably possible.
       def browser_timing_footer
         config = NewRelic::Agent.instance.beacon_configuration
         return "" if config.nil? || !config.rum_enabled || config.browser_monitoring_key.nil?

data/lib/new_relic/agent/busy_calculator.rb

@@ -14,7 +14,10 @@ module NewRelic
 
       # For testability, add accessors:
       attr_reader :harvest_start, :accumulator
-
+      
+      # sets up busy calculations based on the start and end of
+      # transactions - used for a rough estimate of what percentage of
+      # wall clock time is spent processing requests
       def dispatcher_start(time)
         Thread.current[:busy_entries] ||= 0
         callers = Thread.current[:busy_entries] += 1
@@ -23,7 +26,10 @@ module NewRelic
           @entrypoint_stack.push time
         end
       end
-
+      
+      # called when a transaction finishes, to add time to the
+      # instance variable accumulator. this is harvested when we send
+      # data to the server
       def dispatcher_finish(end_time = Time.now)
         callers = Thread.current[:busy_entries] -= 1
         # Ignore nested calls
@@ -36,7 +42,9 @@ module NewRelic
           end
         end
       end
-
+      
+      # this returns the size of the entry point stack, which
+      # determines how many transactions are running
       def busy_count
         @entrypoint_stack.size
       end

data/lib/new_relic/agent/chained_call.rb

@@ -1,5 +1,5 @@
-# This is used to allow obfuscators to be chained.
-
+# This class is used by NewRelic::Agent.set_sql_obfuscator to chain multiple
+# obfuscation blocks when not using the default :replace action
 class NewRelic::ChainedCall
   def initialize(block1, block2)
     @block1 = block1

data/lib/new_relic/agent/error_collector.rb

@@ -1,203 +1,249 @@
-
 module NewRelic
   module Agent
-  class ErrorCollector
-    include NewRelic::CollectionHelper
-
-    # Defined the methods that need to be stubbed out when the
-    # agent is disabled
-    module Shim #:nodoc:
-      def notice_error(*args); end
-    end
-
-    MAX_ERROR_QUEUE_LENGTH = 20 unless defined? MAX_ERROR_QUEUE_LENGTH
-
-    attr_accessor :enabled
-    attr_reader :config_enabled
-
-    def initialize
-      @errors = []
-      # lookup of exception class names to ignore.  Hash for fast access
-      @ignore = {}
-      @ignore_filter = nil
-
-      config = NewRelic::Control.instance.fetch('error_collector', {})
-
-      @enabled = @config_enabled = config.fetch('enabled', true)
-      @capture_source = config.fetch('capture_source', true)
-
-      ignore_errors = config.fetch('ignore_errors', "")
-      ignore_errors = ignore_errors.split(",") if ignore_errors.is_a? String
-      ignore_errors.each { |error| error.strip! }
-      ignore(ignore_errors)
-      @lock = Mutex.new
-    end
-
-    def control
-      NewRelic::Control.instance
-    end
-
-    def ignore_error_filter(&block)
-      if block
-        @ignore_filter = block
-      else
-        @ignore_filter
-      end
-    end
-
-    # errors is an array of Exception Class Names
-    #
-    def ignore(errors)
-      errors.each { |error| @ignore[error] = true; log.debug("Ignoring errors of type '#{error}'") }
-    end
-
-    module NoticeError
-      def disabled?
-        !@enabled
-      end
-
-      def filtered_by_error_filter?(error)
-        return unless @ignore_filter
-        !@ignore_filter.call(error)
-      end
-
-      def filtered_error?(error)
-        @ignore[error.class.name] || filtered_by_error_filter?(error)
-      end
-
-      def error_is_ignored?(error)
-        error && filtered_error?(error)
+    # This class collects errors from the parent application, storing
+    # them until they are harvested and transmitted to the server
+    class ErrorCollector
+      include NewRelic::CollectionHelper
+
+      # Defined the methods that need to be stubbed out when the
+      # agent is disabled
+      module Shim #:nodoc:
+        def notice_error(*args); end
+      end
+      
+      # Maximum possible length of the queue - defaults to 20, may be
+      # made configurable in the future. This is a tradeoff between
+      # memory and data retention
+      MAX_ERROR_QUEUE_LENGTH = 20 unless defined? MAX_ERROR_QUEUE_LENGTH
+
+      attr_accessor :enabled
+      attr_reader :config_enabled
+      
+      # Returns a new error collector
+      def initialize
+        @errors = []
+        # lookup of exception class names to ignore.  Hash for fast access
+        @ignore = {}
+        @ignore_filter = nil
+
+        config = NewRelic::Control.instance.fetch('error_collector', {})
+
+        @enabled = @config_enabled = config.fetch('enabled', true)
+        @capture_source = config.fetch('capture_source', true)
+
+        ignore_errors = config.fetch('ignore_errors', "")
+        ignore_errors = ignore_errors.split(",") if ignore_errors.is_a? String
+        ignore_errors.each { |error| error.strip! }
+        ignore(ignore_errors)
+        @lock = Mutex.new
+      end
+      
+      # Helper method to get the NewRelic::Control.instance
+      def control
+        NewRelic::Control.instance
+      end
+      
+      # Returns the error filter proc that is used to check if an
+      # error should be reported. When given a block, resets the
+      # filter to the provided block
+      def ignore_error_filter(&block)
+        if block
+          @ignore_filter = block
+        else
+          @ignore_filter
+        end
       end
 
-      def increment_error_count!
-        NewRelic::Agent.get_stats("Errors/all").increment_count
+      # errors is an array of Exception Class Names
+      #
+      def ignore(errors)
+        errors.each { |error| @ignore[error] = true; log.debug("Ignoring errors of type '#{error}'") }
       end
-
-      def should_exit_notice_error?(exception)
-        if @enabled
-          if !error_is_ignored?(exception)
-            increment_error_count!
-            return exception.nil?
+      
+      # This module was extracted from the notice_error method - it is
+      # internally tested and can be refactored without major issues.
+      module NoticeError
+        # Whether the error collector is disabled or not
+        def disabled?
+          !@enabled
+        end
+        
+        # Checks the provided error against the error filter, if there
+        # is an error filter
+        def filtered_by_error_filter?(error)
+          return unless @ignore_filter
+          !@ignore_filter.call(error)
+        end
+        
+        # Checks the array of error names and the error filter against
+        # the provided error
+        def filtered_error?(error)
+          @ignore[error.class.name] || filtered_by_error_filter?(error)
+        end
+        
+        # an error is ignored if it is nil or if it is filtered
+        def error_is_ignored?(error)
+          error && filtered_error?(error)
+        end
+        
+        # Increments a statistic that tracks total error rate
+        def increment_error_count!
+          NewRelic::Agent.get_stats("Errors/all").increment_count
+        end
+        
+        # whether we should return early from the notice_error process
+        # - based on whether the error is ignored or the error
+        # collector is disabled
+        def should_exit_notice_error?(exception)
+          if @enabled
+            if !error_is_ignored?(exception)
+              increment_error_count!
+              return exception.nil? # exit early if the exception is nil
+            end
           end
+          # disabled or an ignored error, per above
+          true
         end
-        # disabled or an ignored error, per above
-        true
-      end
-
-      def fetch_from_options(options, key, default=nil)
-        options.delete(key) || default
-      end
-
-      def uri_ref_and_root(options)
-        {
-          :request_uri => fetch_from_options(options, :uri, ''),
-          :request_referer => fetch_from_options(options, :referer, ''),
-          :rails_root => control.root
-        }
-      end
-
-      def custom_params_from_opts(options)
-        # If anything else is left over, treat it like a custom param:
-        fetch_from_options(options, :custom_params, {}).merge(options)
-      end
-
-      def request_params_from_opts(options)
-        value = options.delete(:request_params)
-        if control.capture_params
-          value
-        else
-          nil
+        
+        # acts just like Hash#fetch, but deletes the key from the hash
+        def fetch_from_options(options, key, default=nil)
+          options.delete(key) || default
+        end
+        
+        # returns some basic option defaults pulled from the provided
+        # options hash
+        def uri_ref_and_root(options)
+          {
+            :request_uri => fetch_from_options(options, :uri, ''),
+            :request_referer => fetch_from_options(options, :referer, ''),
+            :rails_root => control.root
+          }
+        end
+        
+        # If anything else is left over, we treat it like a custom param
+        def custom_params_from_opts(options)
+          # If anything else is left over, treat it like a custom param:
+          fetch_from_options(options, :custom_params, {}).merge(options)
+        end
+        
+        # takes the request parameters out of the options hash, and
+        # returns them if we are capturing parameters, otherwise
+        # returns nil
+        def request_params_from_opts(options)
+          value = options.delete(:request_params)
+          if control.capture_params
+            value
+          else
+            nil
+          end
+        end
+        
+        # normalizes the request and custom parameters before attaching
+        # them to the error. See NewRelic::CollectionHelper#normalize_params
+        def normalized_request_and_custom_params(options)
+          {
+            :request_params => normalize_params(request_params_from_opts(options)),
+            :custom_params  => normalize_params(custom_params_from_opts(options))
+          }
+        end
+        
+        # Merges together many of the options into something that can
+        # actually be attached to the error
+        def error_params_from_options(options)
+          uri_ref_and_root(options).merge(normalized_request_and_custom_params(options))
+        end
+        
+        # calls a method on an object, if it responds to it - used for
+        # detection and soft fail-safe. Returns nil if the method does
+        # not exist
+        def sense_method(object, method)
+          object.send(method) if object.respond_to?(method)
+        end
+        
+        # extracts source from the exception, if the exception supports
+        # that method
+        def extract_source(exception)
+          sense_method(exception, 'source_extract') if @capture_source
+        end
+        
+        # extracts a stack trace from the exception for debugging purposes
+        def extract_stack_trace(exception)
+          actual_exception = sense_method(exception, 'original_exception') || exception
+          sense_method(actual_exception, 'backtrace') || '<no stack trace>'
+        end
+        
+        # extracts a bunch of information from the exception to include
+        # in the noticed error - some may or may not be available, but
+        # we try to include all of it
+        def exception_info(exception)
+          {
+            :file_name => sense_method(exception, 'file_name'),
+            :line_number => sense_method(exception, 'line_number'),
+            :source => extract_source(exception),
+            :stack_trace => extract_stack_trace(exception)
+          }
+        end
+        
+        # checks the size of the error queue to make sure we are under
+        # the maximum limit, and logs a warning if we are over the limit.
+        def over_queue_limit?(message)
+          over_limit = (@errors.length >= MAX_ERROR_QUEUE_LENGTH)
+          log.warn("The error reporting queue has reached #{MAX_ERROR_QUEUE_LENGTH}. The error detail for this and subsequent errors will not be transmitted to New Relic until the queued errors have been sent: #{message}") if over_limit
+          over_limit
         end
-      end
-
-      def normalized_request_and_custom_params(options)
-        {
-          :request_params => normalize_params(request_params_from_opts(options)),
-          :custom_params  => normalize_params(custom_params_from_opts(options))
-        }
-      end
-
-      def error_params_from_options(options)
-        uri_ref_and_root(options).merge(normalized_request_and_custom_params(options))
-      end
-
-      def sense_method(object, method)
-        object.send(method) if object.respond_to?(method)
-      end
-
-      def extract_source(exception)
-        sense_method(exception, 'source_extract') if @capture_source
-      end
-
-      def extract_stack_trace(exception)
-        actual_exception = sense_method(exception, 'original_exception') || exception
-        sense_method(actual_exception, 'backtrace') || '<no stack trace>'
-      end
-
-      def exception_info(exception)
-        {
-          :file_name => sense_method(exception, 'file_name'),
-          :line_number => sense_method(exception, 'line_number'),
-          :source => extract_source(exception),
-          :stack_trace => extract_stack_trace(exception)
-        }
-      end
-
-      def over_queue_limit?(message)
-        over_limit = (@errors.length >= MAX_ERROR_QUEUE_LENGTH)
-        log.warn("The error reporting queue has reached #{MAX_ERROR_QUEUE_LENGTH}. The error detail for this and subsequent errors will not be transmitted to New Relic until the queued errors have been sent: #{message}") if over_limit
-        over_limit
-      end
-
 
-      def add_to_error_queue(noticed_error)
-        @lock.synchronize do
-          @errors << noticed_error unless over_queue_limit?(noticed_error.message)
+        
+        # Synchronizes adding an error to the error queue, and checks if
+        # the error queue is too long - if so, we drop the error on the
+        # floor after logging a warning.
+        def add_to_error_queue(noticed_error)
+          @lock.synchronize do
+            @errors << noticed_error unless over_queue_limit?(noticed_error.message)
+          end
         end
       end
-    end
-
-    include NoticeError
 
-    # Notice the error with the given available options:
-    #
-    # * <tt>:uri</tt> => The request path, minus any request params or query string.
-    # * <tt>:referer</tt> => The URI of the referer
-    # * <tt>:metric</tt> => The metric name associated with the transaction
-    # * <tt>:request_params</tt> => Request parameters, already filtered if necessary
-    # * <tt>:custom_params</tt> => Custom parameters
-    #
-    # If anything is left over, it's added to custom params
-    # If exception is nil, the error count is bumped and no traced error is recorded
-    def notice_error(exception, options={})
-      return if should_exit_notice_error?(exception)
-      action_path     = fetch_from_options(options, :metric, (NewRelic::Agent.instance.stats_engine.scope_name || ''))
-      exception_options = error_params_from_options(options).merge(exception_info(exception))
-      add_to_error_queue(NewRelic::NoticedError.new(action_path, exception_options, exception))
-      exception
-    rescue Exception => e
-      log.error("Error capturing an error, yodawg. #{e}")
-    end
+      include NoticeError
+
+      # Notice the error with the given available options:
+      #
+      # * <tt>:uri</tt> => The request path, minus any request params or query string.
+      # * <tt>:referer</tt> => The URI of the referer
+      # * <tt>:metric</tt> => The metric name associated with the transaction
+      # * <tt>:request_params</tt> => Request parameters, already filtered if necessary
+      # * <tt>:custom_params</tt> => Custom parameters
+      #
+      # If anything is left over, it's added to custom params
+      # If exception is nil, the error count is bumped and no traced error is recorded
+      def notice_error(exception, options={})
+        return if should_exit_notice_error?(exception)
+        action_path     = fetch_from_options(options, :metric, (NewRelic::Agent.instance.stats_engine.scope_name || ''))
+        exception_options = error_params_from_options(options).merge(exception_info(exception))
+        add_to_error_queue(NewRelic::NoticedError.new(action_path, exception_options, exception))
+        exception
+      rescue Exception => e
+        log.error("Error capturing an error, yodawg. #{e}")
+      end
+
+      # Get the errors currently queued up.  Unsent errors are left
+      # over from a previous unsuccessful attempt to send them to the server.
+      def harvest_errors(unsent_errors)
+        @lock.synchronize do
+          errors = @errors
+          @errors = []
 
-    # Get the errors currently queued up.  Unsent errors are left
-    # over from a previous unsuccessful attempt to send them to the server.
-    def harvest_errors(unsent_errors)
-      @lock.synchronize do
-        errors = @errors
-        @errors = []
+          if unsent_errors && !unsent_errors.empty?
+            errors = unsent_errors + errors
+          end
 
-        if unsent_errors && !unsent_errors.empty?
-          errors = unsent_errors + errors
+          errors
         end
-
-        errors
       end
-    end
 
-    private
-    def log
-      NewRelic::Agent.logger
+      private
+      def log
+        NewRelic::Agent.logger
+      end
     end
   end
 end
-end