newrelic_rpm 2.13.5.beta4 → 2.13.6.beta1

data/CHANGELOG

@@ -1,3 +1,7 @@
+v2.13.6
+  * Dependency detection framework to prevent multi-loading or early-loading
+    of instrumentation files
+
 v2.13.5
   * Moved the API helper to the github newrelic_api gem.
   * Revamped queue time to include server, queue, and middleware time
@@ -7,6 +11,10 @@ v2.13.5
   * patches to 1.9 compatibility from dkastner on github
   * Support for 1.9.2's garbage collection instrumentation from Justin Weiss
   * On Heroku, existing queue time headers will be detected
+  * Fix rack constant scoping in dev mode for 1.9 (Rack != ::Rack)
+  * Fixes for instrumentation loading failing on Exception classes that
+    are not subclasses of StandardError
+  * Fix active record instrumentation load order for Rails 3
 
 v2.13.4
   * Update DNS lookup code to remove hardcoded IP addresses

data/cert/cacert.pem

@@ -32,3 +32,24 @@ UjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMMj4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8
 W9ViH0Pd
 -----END CERTIFICATE-----
 
+-----BEGIN CERTIFICATE-----
+MIIDfDCCAmSgAwIBAgIQGKy1av1pthU6Y2yv2vrEoTANBgkqhkiG9w0BAQUFADBY
+MQswCQYDVQQGEwJVUzEWMBQGA1UEChMNR2VvVHJ1c3QgSW5jLjExMC8GA1UEAxMo
+R2VvVHJ1c3QgUHJpbWFyeSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjEx
+MjcwMDAwMDBaFw0zNjA3MTYyMzU5NTlaMFgxCzAJBgNVBAYTAlVTMRYwFAYDVQQK
+Ew1HZW9UcnVzdCBJbmMuMTEwLwYDVQQDEyhHZW9UcnVzdCBQcmltYXJ5IENlcnRp
+ZmljYXRpb24gQXV0aG9yaXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
+AQEAvrgVe//UfH1nrYNke8hCUy3f9oQIIGHWAVlqnEQRr+92/ZV+zmEwu3qDXwK9
+AWbK7hWNb6EwnL2hhZ6UOvNWiAAxz9juapYC2e0DjPt1befquFUWBRaa9OBesYjA
+ZIVcFU2Ix7e64HXprQU9nceJSOC7KMgD4TCTZF5SwFlwIjVXiIrxlQqD17wxcwE0
+7e9GceBrAqg1cmuXm2bgyxx5X9gaBGgeRwLmnWDiNpcB3841kt++Z8dtd1k7j53W
+kBWUvEI0EME5+bEnPn7WinXFsq+W06Lem+SYvn3h6YGttm/81w7a4DSwDRp35+MI
+mO9Y+pyEtzavwt+s0vQQBnBxNQIDAQABo0IwQDAPBgNVHRMBAf8EBTADAQH/MA4G
+A1UdDwEB/wQEAwIBBjAdBgNVHQ4EFgQULNVQQZcVi/CPNmFbSvtr2ZnJM5IwDQYJ
+KoZIhvcNAQEFBQADggEBAFpwfyzdtzRP9YZRqSa+S7iq8XEN3GHHoOo0Hnp3DwQ1
+6CePbJC/kRYkRj5KTs4rFtULUh38H2eiAkUxT87z+gOneZ1TatnaYzr4gNfTmeGl
+4b7UVXGYNTq+k+qurUKykG/g/CFNNWMziUnWm07Kx+dOCQD32sfvmWKZd7aVIl6K
+oKv0uHiYyjgZmclynnjNS6yvGaBzEi38wkG6gZHaFloxt/m0cYASSJlyc1pZU8Fj
+UjPtp8nSOQJw+uCxQmYpqptR7TBUIhRf2asdweSU8Pj1K/fqynhG1riR/aYNKxoU
+AT6A8EKglQdebc3MS6RFjasS6LPeWuWgfOgPIh1a6Vk=
+-----END CERTIFICATE-----

data/lib/conditional_vendored_dependency_detection.rb

@@ -0,0 +1,3 @@
+path = File.expand_path('../vendor/gems/dependency_detection-0.0.1.build/lib', File.dirname(__FILE__))
+$LOAD_PATH << path unless $LOAD_PATH.include?(path)
+require 'dependency_detection'

data/lib/new_relic/agent/agent.rb

@@ -256,7 +256,20 @@ module NewRelic
           end
 
           def set_sql_recording!
-            @record_sql = sampler_config.fetch('record_sql', :obfuscated).to_sym
+            record_sql_config = sampler_config.fetch('record_sql', :obfuscated)
+            case record_sql_config.to_s
+            when 'off'
+              @record_sql = :off
+            when 'none'
+              @record_sql = :off
+            when 'false'
+              @record_sql = :off
+            when 'raw'
+              @record_sql = :raw
+            else
+              @record_sql = :obfuscated
+            end
+            
             log_sql_transmission_warning?
           end
 

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

@@ -1,16 +1,19 @@
-# ActiveMerchant Instrumentation.
-
-if defined? ActiveMerchant
+DependencyDetection.defer do
+  depends_on do
+    defined?(ActiveMerchant)
+  end
 
-  ActiveMerchant::Billing::Gateway.implementations.each do |gateway|
-    gateway.class_eval do
-      implemented_methods = public_instance_methods(false)
-      gateway_name = self.name.split('::').last
-      [:authorize, :purchase, :credit, :void, :capture, :recurring].each do |operation|
-        if implemented_methods.include?(operation.to_s)
-          add_method_tracer operation, "ActiveMerchant/gateway/#{gateway_name}/#{operation}", :scoped_metric_only => true
-          add_method_tracer operation, "ActiveMerchant/gateway/#{gateway_name}", :push_scope => false
-          add_method_tracer operation, "ActiveMerchant/operation/#{operation}", :push_scope => false
+  executes do
+    ActiveMerchant::Billing::Gateway.implementations.each do |gateway|
+      gateway.class_eval do
+        implemented_methods = public_instance_methods(false)
+        gateway_name = self.name.split('::').last
+        [:authorize, :purchase, :credit, :void, :capture, :recurring].each do |operation|
+          if implemented_methods.include?(operation.to_s)
+            add_method_tracer operation, "ActiveMerchant/gateway/#{gateway_name}/#{operation}", :scoped_metric_only => true
+            add_method_tracer operation, "ActiveMerchant/gateway/#{gateway_name}", :push_scope => false
+            add_method_tracer operation, "ActiveMerchant/operation/#{operation}", :push_scope => false
+          end
         end
       end
     end

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

@@ -1,40 +1,58 @@
-if defined?(::ActsAsSolr)
-
-  module NewRelic
-    module Instrumentation
-      module ActsAsSolrInstrumentation
-        module ParserMethodsInstrumentation
-          def parse_query_with_newrelic(*args)
-            self.class.trace_execution_scoped(["SolrClient/ActsAsSolr/query"]) do
-              t0 = Time.now
-              begin
-                parse_query_without_newrelic(*args)
-              ensure
-                NewRelic::Agent.instance.transaction_sampler.notice_nosql(args.first.inspect, (Time.now - t0).to_f) rescue nil
-              end
+module NewRelic
+  module Instrumentation
+    module ActsAsSolrInstrumentation
+      module ParserMethodsInstrumentation
+        def parse_query_with_newrelic(*args)
+          self.class.trace_execution_scoped(["SolrClient/ActsAsSolr/query"]) do
+            t0 = Time.now
+            begin
+              parse_query_without_newrelic(*args)
+            ensure
+              NewRelic::Agent.instance.transaction_sampler.notice_nosql(args.first.inspect, (Time.now - t0).to_f) rescue nil
             end
-
           end
         end
       end
     end
   end
+end
 
-  module ActsAsSolr
-    module ParserMethods #:nodoc
+DependencyDetection.defer do
+  depends_on do
+    defined?(ActsAsSolr)
+  end
+
+  depends_on do
+    defined?(ActsAsSolr::ParserMethods)
+  end
+  
+  depends_on do
+    defined?(ActsAsSolr::ClassMethods)
+  end
+
+  depends_on do
+    defined?(ActsAsSolr::CommonMethods)
+  end
+  
+  executes do
+    ActsAsSolr::ParserMethods.module_eval do
       include NewRelic::Instrumentation::ActsAsSolrInstrumentation::ParserMethodsInstrumentation
       alias :parse_query_without_newrelic :parse_query
       alias :parse_query :parse_query_with_newrelic
     end
-
-    module ClassMethods #:nodoc
+  end
+  
+  executes do
+    ActsAsSolr::ClassMethods.module_eval do
       %w[find_by_solr find_id_by_solr multi_solr_search count_by_solr].each do |method|
         add_method_tracer method, 'SolrClient/ActsAsSolr/query'
       end
       add_method_tracer :rebuild_solr_index, 'SolrClient/ActsAsSolr/index'
     end
+  end
 
-    module CommonMethods #:nodoc
+  executes do
+    ActsAsSolr::CommonMethods.module_eval do
       add_method_tracer :solr_add, 'SolrClient/ActsAsSolr/add'
       add_method_tracer :solr_delete, 'SolrClient/ActsAsSolr/delete'
       add_method_tracer :solr_commit, 'SolrClient/ActsAsSolr/commit'
@@ -42,4 +60,3 @@ if defined?(::ActsAsSolr)
     end
   end
 end
-

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

@@ -1,7 +1,12 @@
-if defined? Authlogic::Session::Base
-  Authlogic::Session::Base.class_eval do
-  #  add_method_tracer :record, 'Custom/Authlogic/record'
-    class << self
+DependencyDetection.defer do
+  depends_on do
+    defined?(AuthLogic) &&
+      defined?(AuthLogic::Session) &&
+      defined?(AuthLogic::Session::Base)
+  end
+
+  executes do
+    AuthLogic::Session::Base.class_eval do
       add_method_tracer :find, 'Custom/Authlogic/find'
     end
   end

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

@@ -3,405 +3,405 @@ require 'new_relic/agent/instrumentation/queue_time'
 module NewRelic
   module Agent
     module Instrumentation
-  # == NewRelic instrumentation for controller actions and tasks
-  #
-  # This instrumentation is applied to the action controller to collect
-  # metrics for every web request.
-  #
-  # It can also be used to capture performance information for
-  # background tasks and other non-web transactions, including
-  # detailed transaction traces and traced errors.
-  #
-  # For details on how to instrument background tasks see
-  # ClassMethods#add_transaction_tracer and
-  # #perform_action_with_newrelic_trace
-  #
-  module ControllerInstrumentation
-
-    def self.included(clazz) # :nodoc:
-      clazz.extend(ClassMethods)
-    end
-
-    # This module is for importing stubs when the agent is disabled
-    module ClassMethodsShim # :nodoc:
-      def newrelic_ignore(*args); end
-      def newrelic_ignore_apdex(*args); end
-    end
+      # == NewRelic instrumentation for controller actions and tasks
+      #
+      # This instrumentation is applied to the action controller to collect
+      # metrics for every web request.
+      #
+      # It can also be used to capture performance information for
+      # background tasks and other non-web transactions, including
+      # detailed transaction traces and traced errors.
+      #
+      # For details on how to instrument background tasks see
+      # ClassMethods#add_transaction_tracer and
+      # #perform_action_with_newrelic_trace
+      #
+      module ControllerInstrumentation
 
-    module Shim # :nodoc:
-      def self.included(clazz)
-        clazz.extend(ClassMethodsShim)
-      end
-      def newrelic_notice_error(*args); end
-      def new_relic_trace_controller_action(*args); yield; end
-      def newrelic_metric_path; end
-      def perform_action_with_newrelic_trace(*args); yield; end
-    end
+        def self.included(clazz) # :nodoc:
+          clazz.extend(ClassMethods)
+        end
 
-    module ClassMethods
-      # Have NewRelic ignore actions in this controller.  Specify the actions as hash options
-      # using :except and :only.  If no actions are specified, all actions are ignored.
-      def newrelic_ignore(specifiers={})
-        newrelic_ignore_aspect('do_not_trace', specifiers)
-      end
-      # Have NewRelic omit apdex measurements on the given actions.  Typically used for
-      # actions that are not user facing or that skew your overall apdex measurement.
-      # Accepts :except and :only options, as with #newrelic_ignore.
-      def newrelic_ignore_apdex(specifiers={})
-        newrelic_ignore_aspect('ignore_apdex', specifiers)
-      end
+        # This module is for importing stubs when the agent is disabled
+        module ClassMethodsShim # :nodoc:
+          def newrelic_ignore(*args); end
+          def newrelic_ignore_apdex(*args); end
+        end
 
-      def newrelic_ignore_aspect(property, specifiers={}) # :nodoc:
-        if specifiers.empty?
-          self.newrelic_write_attr property, true
-        elsif ! (Hash === specifiers)
-          logger.error "newrelic_#{property} takes an optional hash with :only and :except lists of actions (illegal argument type '#{specifiers.class}')"
-        else
-          self.newrelic_write_attr property, specifiers
+        module Shim # :nodoc:
+          def self.included(clazz)
+            clazz.extend(ClassMethodsShim)
+          end
+          def newrelic_notice_error(*args); end
+          def new_relic_trace_controller_action(*args); yield; end
+          def newrelic_metric_path; end
+          def perform_action_with_newrelic_trace(*args); yield; end
         end
-      end
 
-      # Should be monkey patched into the controller class implemented
-      # with the inheritable attribute mechanism.
-      def newrelic_write_attr(attr_name, value) # :nodoc:
-        instance_variable_set "@#{attr_name}", value
-      end
-      def newrelic_read_attr(attr_name) # :nodoc:
-        instance_variable_get "@#{attr_name}"
-      end
+        module ClassMethods
+          # Have NewRelic ignore actions in this controller.  Specify the actions as hash options
+          # using :except and :only.  If no actions are specified, all actions are ignored.
+          def newrelic_ignore(specifiers={})
+            newrelic_ignore_aspect('do_not_trace', specifiers)
+          end
+          # Have NewRelic omit apdex measurements on the given actions.  Typically used for
+          # actions that are not user facing or that skew your overall apdex measurement.
+          # Accepts :except and :only options, as with #newrelic_ignore.
+          def newrelic_ignore_apdex(specifiers={})
+            newrelic_ignore_aspect('ignore_apdex', specifiers)
+          end
 
-      # Add transaction tracing to the given method.  This will treat
-      # the given method as a main entrypoint for instrumentation, just
-      # like controller actions are treated by default.  Useful especially
-      # for background tasks.
-      #
-      # Example for background job:
-      #   class Job
-      #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
-      #     def run(task)
-      #        ...
-      #     end
-      #     # Instrument run so tasks show up under task.name.  Note single
-      #     # quoting to defer eval to runtime.
-      #     add_transaction_tracer :run, :name => '#{args[0].name}'
-      #   end
-      #
-      # Here's an example of a controller that uses a dispatcher
-      # action to invoke operations which you want treated as top
-      # level actions, so they aren't all lumped into the invoker
-      # action.
-      #
-      #   MyController < ActionController::Base
-      #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
-      #     # dispatch the given op to the method given by the service parameter.
-      #     def invoke_operation
-      #       op = params['operation']
-      #       send op
-      #     end
-      #     # Ignore the invoker to avoid double counting
-      #     newrelic_ignore :only => 'invoke_operation'
-      #     # Instrument the operations:
-      #     add_transaction_tracer :print
-      #     add_transaction_tracer :show
-      #     add_transaction_tracer :forward
-      #   end
-      #
-      # Here's an example of how to pass contextual information into the transaction
-      # so it will appear in transaction traces:
-      #
-      #   class Job
-      #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
-      #     def process(account)
-      #        ...
-      #     end
-      #     # Include the account name in the transaction details.  Note the single
-      #     # quotes to defer eval until call time.
-      #     add_transaction_tracer :process, :params => '{ :account_name => args[0].name }'
-      #   end
-      #
-      # See NewRelic::Agent::Instrumentation::ControllerInstrumentation#perform_action_with_newrelic_trace
-      # for the full list of available options.
-      #
-      def add_transaction_tracer(method, options={})
-        # The metric path:
-        options[:name] ||= method.to_s
-        # create the argument list:
-        options_arg = []
-        options.each do |key, value|
-          valuestr = case
-          when value.is_a?(Symbol)
-            value.inspect
-          when key == :params
-            value.to_s
-          else
-              %Q["#{value.to_s}"]
+          def newrelic_ignore_aspect(property, specifiers={}) # :nodoc:
+            if specifiers.empty?
+              self.newrelic_write_attr property, true
+            elsif ! (Hash === specifiers)
+              logger.error "newrelic_#{property} takes an optional hash with :only and :except lists of actions (illegal argument type '#{specifiers.class}')"
+            else
+              self.newrelic_write_attr property, specifiers
+            end
           end
-          options_arg << %Q[:#{key} => #{valuestr}]
-        end
-        class_eval <<-EOC
-        def #{method.to_s}_with_newrelic_transaction_trace(*args, &block)
-          perform_action_with_newrelic_trace(#{options_arg.join(',')}) do
-            #{method.to_s}_without_newrelic_transaction_trace(*args, &block)
+
+          # Should be monkey patched into the controller class implemented
+          # with the inheritable attribute mechanism.
+          def newrelic_write_attr(attr_name, value) # :nodoc:
+            instance_variable_set "@#{attr_name}", value
+          end
+          def newrelic_read_attr(attr_name) # :nodoc:
+            instance_variable_get "@#{attr_name}"
+          end
+
+          # Add transaction tracing to the given method.  This will treat
+          # the given method as a main entrypoint for instrumentation, just
+          # like controller actions are treated by default.  Useful especially
+          # for background tasks.
+          #
+          # Example for background job:
+          #   class Job
+          #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
+          #     def run(task)
+          #        ...
+          #     end
+          #     # Instrument run so tasks show up under task.name.  Note single
+          #     # quoting to defer eval to runtime.
+          #     add_transaction_tracer :run, :name => '#{args[0].name}'
+          #   end
+          #
+          # Here's an example of a controller that uses a dispatcher
+          # action to invoke operations which you want treated as top
+          # level actions, so they aren't all lumped into the invoker
+          # action.
+          #
+          #   MyController < ActionController::Base
+          #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
+          #     # dispatch the given op to the method given by the service parameter.
+          #     def invoke_operation
+          #       op = params['operation']
+          #       send op
+          #     end
+          #     # Ignore the invoker to avoid double counting
+          #     newrelic_ignore :only => 'invoke_operation'
+          #     # Instrument the operations:
+          #     add_transaction_tracer :print
+          #     add_transaction_tracer :show
+          #     add_transaction_tracer :forward
+          #   end
+          #
+          # Here's an example of how to pass contextual information into the transaction
+          # so it will appear in transaction traces:
+          #
+          #   class Job
+          #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
+          #     def process(account)
+          #        ...
+          #     end
+          #     # Include the account name in the transaction details.  Note the single
+          #     # quotes to defer eval until call time.
+          #     add_transaction_tracer :process, :params => '{ :account_name => args[0].name }'
+          #   end
+          #
+          # See NewRelic::Agent::Instrumentation::ControllerInstrumentation#perform_action_with_newrelic_trace
+          # for the full list of available options.
+          #
+          def add_transaction_tracer(method, options={})
+            # The metric path:
+            options[:name] ||= method.to_s
+            # create the argument list:
+            options_arg = []
+            options.each do |key, value|
+              valuestr = case
+                         when value.is_a?(Symbol)
+                           value.inspect
+                         when key == :params
+                           value.to_s
+                         else
+                           %Q["#{value.to_s}"]
+                         end
+              options_arg << %Q[:#{key} => #{valuestr}]
+            end
+            class_eval <<-EOC
+              def #{method.to_s}_with_newrelic_transaction_trace(*args, &block)
+                perform_action_with_newrelic_trace(#{options_arg.join(',')}) do
+                  #{method.to_s}_without_newrelic_transaction_trace(*args, &block)
+                 end
+              end
+            EOC
+            alias_method "#{method.to_s}_without_newrelic_transaction_trace", method.to_s
+            alias_method method.to_s, "#{method.to_s}_with_newrelic_transaction_trace"
+            NewRelic::Control.instance.log.debug("Traced transaction: class = #{self.name}, method = #{method.to_s}, options = #{options.inspect}")
           end
         end
-        EOC
-        alias_method "#{method.to_s}_without_newrelic_transaction_trace", method.to_s
-        alias_method method.to_s, "#{method.to_s}_with_newrelic_transaction_trace"
-        NewRelic::Control.instance.log.debug("Traced transaction: class = #{self.name}, method = #{method.to_s}, options = #{options.inspect}")
-      end
-    end
 
-    # Must be implemented in the controller class:
-    # Determine the path that is used in the metric name for
-    # the called controller action.  Of the form controller_path/action_name
-    #
-    def newrelic_metric_path(action_name_override = nil) # :nodoc:
-      raise "Not implemented!"
-    end
+        # Must be implemented in the controller class:
+        # Determine the path that is used in the metric name for
+        # the called controller action.  Of the form controller_path/action_name
+        #
+        def newrelic_metric_path(action_name_override = nil) # :nodoc:
+          raise "Not implemented!"
+        end
 
-    # Yield to the given block with NewRelic tracing.  Used by
-    # default instrumentation on controller actions in Rails and Merb.
-    # But it can also be used in custom instrumentation of controller
-    # methods and background tasks.
-    #
-    # This is the method invoked by instrumentation added by the
-    # <tt>ClassMethods#add_transaction_tracer</tt>.
-    #
-    # Here's a more verbose version of the example shown in
-    # <tt>ClassMethods#add_transaction_tracer</tt> using this method instead of
-    # #add_transaction_tracer.
-    #
-    # Below is a controller with an +invoke_operation+ action which
-    # dispatches to more specific operation methods based on a
-    # parameter (very dangerous, btw!).  With this instrumentation,
-    # the +invoke_operation+ action is ignored but the operation
-    # methods show up in RPM as if they were first class controller
-    # actions
-    #
-    #   MyController < ActionController::Base
-    #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
-    #     # dispatch the given op to the method given by the service parameter.
-    #     def invoke_operation
-    #       op = params['operation']
-    #       perform_action_with_newrelic_trace(:name => op) do
-    #         send op, params['message']
-    #       end
-    #     end
-    #     # Ignore the invoker to avoid double counting
-    #     newrelic_ignore :only => 'invoke_operation'
-    #   end
-    #
-    #
-    # When invoking this method explicitly as in the example above, pass in a
-    # block to measure with some combination of options:
-    #
-    # * <tt>:category => :controller</tt> indicates that this is a
-    #   controller action and will appear with all the other actions.  This
-    #   is the default.
-    # * <tt>:category => :task</tt> indicates that this is a
-    #   background task and will show up in RPM with other background
-    #   tasks instead of in the controllers list
-    # * <tt>:category => :rack</tt> if you are instrumenting a rack
-    #   middleware call.  The <tt>:name</tt> is optional, useful if you
-    #   have more than one potential transaction in the #call.
-    # * <tt>:category => :uri</tt> indicates that this is a
-    #   web transaction whose name is a normalized URI, where  'normalized'
-    #   means the URI does not have any elements with data in them such
-    #   as in many REST URIs.
-    # * <tt>:name => action_name</tt> is used to specify the action
-    #   name used as part of the metric name
-    # * <tt>:params => {...}</tt> to provide information about the context
-    #   of the call, used in transaction trace display, for example:
-    #   <tt>:params => { :account => @account.name, :file => file.name }</tt>
-    #   These are treated similarly to request parameters in web transactions.
-    #
-    # Seldomly used options:
-    #
-    # * <tt>:force => true</tt> indicates you should capture all
-    #   metrics even if the #newrelic_ignore directive was specified
-    # * <tt>:class_name => aClass.name</tt> is used to override the name
-    #   of the class when used inside the metric name.  Default is the
-    #   current class.
-    # * <tt>:path => metric_path</tt> is *deprecated* in the public API.  It
-    #   allows you to set the entire metric after the category part.  Overrides
-    #   all the other options.
-    # * <tt>:request => Rack::Request#new(env)</tt> is used to pass in a
-    #   request object that may respond to uri and referer.
-    #
-    # If a single argument is passed in, it is treated as a metric
-    # path.  This form is deprecated.
-    def perform_action_with_newrelic_trace(*args, &block)
+        # Yield to the given block with NewRelic tracing.  Used by
+        # default instrumentation on controller actions in Rails and Merb.
+        # But it can also be used in custom instrumentation of controller
+        # methods and background tasks.
+        #
+        # This is the method invoked by instrumentation added by the
+        # <tt>ClassMethods#add_transaction_tracer</tt>.
+        #
+        # Here's a more verbose version of the example shown in
+        # <tt>ClassMethods#add_transaction_tracer</tt> using this method instead of
+        # #add_transaction_tracer.
+        #
+        # Below is a controller with an +invoke_operation+ action which
+        # dispatches to more specific operation methods based on a
+        # parameter (very dangerous, btw!).  With this instrumentation,
+        # the +invoke_operation+ action is ignored but the operation
+        # methods show up in RPM as if they were first class controller
+        # actions
+        #
+        #   MyController < ActionController::Base
+        #     include NewRelic::Agent::Instrumentation::ControllerInstrumentation
+        #     # dispatch the given op to the method given by the service parameter.
+        #     def invoke_operation
+        #       op = params['operation']
+        #       perform_action_with_newrelic_trace(:name => op) do
+        #         send op, params['message']
+        #       end
+        #     end
+        #     # Ignore the invoker to avoid double counting
+        #     newrelic_ignore :only => 'invoke_operation'
+        #   end
+        #
+        #
+        # When invoking this method explicitly as in the example above, pass in a
+        # block to measure with some combination of options:
+        #
+        # * <tt>:category => :controller</tt> indicates that this is a
+        #   controller action and will appear with all the other actions.  This
+        #   is the default.
+        # * <tt>:category => :task</tt> indicates that this is a
+        #   background task and will show up in RPM with other background
+        #   tasks instead of in the controllers list
+        # * <tt>:category => :rack</tt> if you are instrumenting a rack
+        #   middleware call.  The <tt>:name</tt> is optional, useful if you
+        #   have more than one potential transaction in the #call.
+        # * <tt>:category => :uri</tt> indicates that this is a
+        #   web transaction whose name is a normalized URI, where  'normalized'
+        #   means the URI does not have any elements with data in them such
+        #   as in many REST URIs.
+        # * <tt>:name => action_name</tt> is used to specify the action
+        #   name used as part of the metric name
+        # * <tt>:params => {...}</tt> to provide information about the context
+        #   of the call, used in transaction trace display, for example:
+        #   <tt>:params => { :account => @account.name, :file => file.name }</tt>
+        #   These are treated similarly to request parameters in web transactions.
+        #
+        # Seldomly used options:
+        #
+        # * <tt>:force => true</tt> indicates you should capture all
+        #   metrics even if the #newrelic_ignore directive was specified
+        # * <tt>:class_name => aClass.name</tt> is used to override the name
+        #   of the class when used inside the metric name.  Default is the
+        #   current class.
+        # * <tt>:path => metric_path</tt> is *deprecated* in the public API.  It
+        #   allows you to set the entire metric after the category part.  Overrides
+        #   all the other options.
+        # * <tt>:request => Rack::Request#new(env)</tt> is used to pass in a
+        #   request object that may respond to uri and referer.
+        #
+        # If a single argument is passed in, it is treated as a metric
+        # path.  This form is deprecated.
+        def perform_action_with_newrelic_trace(*args, &block)
 
-      # Skip instrumentation based on the value of 'do_not_trace' and if
-      # we aren't calling directly with a block.
-      if !block_given? && _is_filtered?('do_not_trace')
-        # Also ignore all instrumentation in the call sequence
-        NewRelic::Agent.disable_all_tracing do
-          return perform_action_without_newrelic_trace(*args)
-        end
-      end
+          # Skip instrumentation based on the value of 'do_not_trace' and if
+          # we aren't calling directly with a block.
+          if !block_given? && _is_filtered?('do_not_trace')
+            # Also ignore all instrumentation in the call sequence
+            NewRelic::Agent.disable_all_tracing do
+              return perform_action_without_newrelic_trace(*args)
+            end
+          end
 
-      return perform_action_with_newrelic_profile(args, &block) if NewRelic::Control.instance.profiling?
+          return perform_action_with_newrelic_profile(args, &block) if NewRelic::Control.instance.profiling?
 
-      frame_data = _push_metric_frame(block_given? ? args : [])
-      begin
-        NewRelic::Agent.trace_execution_scoped frame_data.recorded_metrics, :force => frame_data.force_flag do
-          frame_data.start_transaction
+          frame_data = _push_metric_frame(block_given? ? args : [])
           begin
-            NewRelic::Agent::BusyCalculator.dispatcher_start frame_data.start
-            if block_given?
-              yield
-            else
-              perform_action_without_newrelic_trace(*args)
+            NewRelic::Agent.trace_execution_scoped frame_data.recorded_metrics, :force => frame_data.force_flag do
+              frame_data.start_transaction
+              begin
+                NewRelic::Agent::BusyCalculator.dispatcher_start frame_data.start
+                if block_given?
+                  yield
+                else
+                  perform_action_without_newrelic_trace(*args)
+                end
+              rescue Exception => e
+                frame_data.notice_error(e)
+                raise
+              end
+            end
+          ensure
+            NewRelic::Agent::BusyCalculator.dispatcher_finish
+            # Look for a metric frame in the thread local and process it.
+            # Clear the thread local when finished to ensure it only gets called once.
+            frame_data.record_apdex unless _is_filtered?('ignore_apdex')
+            
+            if Thread::current[:browser_request]
+              NewRelic::Agent.instance.stats_engine.get_stats_no_scope("HttpDispatcherWithBrowser").record_data_point(Time.now - frame_data.start)
             end
-          rescue Exception => e
-            frame_data.notice_error(e)
-            raise
+            
+            frame_data.pop
           end
         end
-      ensure
-        NewRelic::Agent::BusyCalculator.dispatcher_finish
-        # Look for a metric frame in the thread local and process it.
-        # Clear the thread local when finished to ensure it only gets called once.
-        frame_data.record_apdex unless _is_filtered?('ignore_apdex')
-        
-        if Thread::current[:browser_request]
-          NewRelic::Agent.instance.stats_engine.get_stats_no_scope("HttpDispatcherWithBrowser").record_data_point(Time.now - frame_data.start)
+
+        protected
+        # Should be implemented in the dispatcher class
+        def newrelic_response_code; end
+
+        def newrelic_request_headers
+          self.respond_to?(:request) && self.request.respond_to?(:headers) && self.request.headers
         end
-        
-        frame_data.pop
-      end
-    end
 
-    protected
-    # Should be implemented in the dispatcher class
-    def newrelic_response_code; end
+        private
 
-    def newrelic_request_headers
-      self.respond_to?(:request) && self.request.respond_to?(:headers) && self.request.headers
-    end
+        # Profile the instrumented call.  Dev mode only.  Experimental.
+        def perform_action_with_newrelic_profile(args)
+          frame_data = _push_metric_frame(block_given? ? args : [])
+          val = nil
+          NewRelic::Agent.trace_execution_scoped frame_data.metric_name do
+            MetricFrame.current(true).start_transaction
+            NewRelic::Agent.disable_all_tracing do
+              # turn on profiling
+              profile = RubyProf.profile do
+                if block_given?
+                  val = yield
+                else
+                  val = perform_action_without_newrelic_trace(*args)
+                end
+              end
+              NewRelic::Agent.instance.transaction_sampler.notice_profile profile
+            end
+          end
+          return val
+        ensure
+          frame_data.pop
+        end
 
-    private
+        # Write a metric frame onto a thread local if there isn't already one there.
+        # If there is one, just update it.
+        def _push_metric_frame(args) # :nodoc:
+          frame_data = NewRelic::Agent::Instrumentation::MetricFrame.current(true)
 
-    # Profile the instrumented call.  Dev mode only.  Experimental.
-    def perform_action_with_newrelic_profile(args)
-      frame_data = _push_metric_frame(block_given? ? args : [])
-      val = nil
-      NewRelic::Agent.trace_execution_scoped frame_data.metric_name do
-        MetricFrame.current(true).start_transaction
-        NewRelic::Agent.disable_all_tracing do
-          # turn on profiling
-          profile = RubyProf.profile do
-            if block_given?
-              val = yield
-            else
-              val = perform_action_without_newrelic_trace(*args)
+          frame_data.apdex_start ||= _detect_upstream_wait(frame_data.start)
+          _record_queue_length
+          # If a block was passed in, then the arguments represent options for the instrumentation,
+          # not app method arguments.
+          if args.any?
+            if args.last.is_a?(Hash)
+              options = args.last
+              frame_data.force_flag = options[:force]
+              frame_data.request = options[:request] if options[:request]
             end
+            category, path, available_params = _convert_args_to_path(args)
+          else
+            category = 'Controller'
+            path = newrelic_metric_path
+            available_params = self.respond_to?(:params) ? self.params : {}
           end
-          NewRelic::Agent.instance.transaction_sampler.notice_profile profile
+          frame_data.request ||= self.request if self.respond_to? :request
+          frame_data.push(category + '/'+ path)
+          frame_data.filtered_params = (respond_to? :filter_parameters) ? filter_parameters(available_params) : available_params
+          frame_data
         end
-      end
-      return val
-    ensure
-      frame_data.pop
-    end
 
-    # Write a metric frame onto a thread local if there isn't already one there.
-    # If there is one, just update it.
-    def _push_metric_frame(args) # :nodoc:
-      frame_data = NewRelic::Agent::Instrumentation::MetricFrame.current(true)
+        def _convert_args_to_path(args)
+          options =  args.last.is_a?(Hash) ? args.pop : {}
+          params = options[:params] || {}
+          category = case options[:category]
+                     when :controller, nil then 'Controller'
+                     when :task then 'OtherTransaction/Background' # 'Task'
+                     when :rack then 'Controller/Rack' #'WebTransaction/Rack'
+                     when :uri then 'Controller' #'WebTransaction/Uri'
+                     when :sinatra then 'Controller/Sinatra' #'WebTransaction/Uri'
+                       # for internal use only
+                     else options[:category].to_s
+                     end
+          unless path = options[:path]
+            action = options[:name] || args.first
+            metric_class = options[:class_name] || (self.is_a?(Class) ? self.name : self.class.name)
+            path = metric_class
+            path += ('/' + action) if action
+          end
+          [category, path, params]
+        end
 
-      frame_data.apdex_start ||= _detect_upstream_wait(frame_data.start)
-      _record_queue_length
-      # If a block was passed in, then the arguments represent options for the instrumentation,
-      # not app method arguments.
-      if args.any?
-        if args.last.is_a?(Hash)
-          options = args.last
-          frame_data.force_flag = options[:force]
-          frame_data.request = options[:request] if options[:request]
+        # Filter out
+        def _is_filtered?(key)
+          ignore_actions = self.class.newrelic_read_attr(key) if self.class.respond_to? :newrelic_read_attr
+          case ignore_actions
+          when nil; false
+          when Hash
+            only_actions = Array(ignore_actions[:only])
+            except_actions = Array(ignore_actions[:except])
+            only_actions.include?(action_name.to_sym) || (except_actions.any? && !except_actions.include?(action_name.to_sym))
+          else
+            true
+          end
+        end
+        # Take a guess at a measure representing the number of requests waiting in mongrel
+        # or heroku.
+        def _record_queue_length
+          if newrelic_request_headers
+            if queue_depth = newrelic_request_headers['HTTP_X_HEROKU_QUEUE_DEPTH']
+              queue_depth = queue_depth.to_i rescue nil
+            elsif mongrel = NewRelic::Control.instance.local_env.mongrel
+              # Always subtrace 1 for the active mongrel
+              queue_depth = [mongrel.workers.list.length.to_i - 1, 0].max rescue nil
+            end
+            NewRelic::Agent.agent.stats_engine.get_stats_no_scope('Mongrel/Queue Length').trace_call(queue_depth) if queue_depth
+          end
         end
-        category, path, available_params = _convert_args_to_path(args)
-      else
-        category = 'Controller'
-        path = newrelic_metric_path
-        available_params = self.respond_to?(:params) ? self.params : {}
-      end
-      frame_data.request ||= self.request if self.respond_to? :request
-      frame_data.push(category + '/'+ path)
-      frame_data.filtered_params = (respond_to? :filter_parameters) ? filter_parameters(available_params) : available_params
-      frame_data
-    end
 
-    def _convert_args_to_path(args)
-      options =  args.last.is_a?(Hash) ? args.pop : {}
-      params = options[:params] || {}
-      category = case options[:category]
-        when :controller, nil then 'Controller'
-        when :task then 'OtherTransaction/Background' # 'Task'
-        when :rack then 'Controller/Rack' #'WebTransaction/Rack'
-        when :uri then 'Controller' #'WebTransaction/Uri'
-        when :sinatra then 'Controller/Sinatra' #'WebTransaction/Uri'
-        # for internal use only
-        else options[:category].to_s
-      end
-      unless path = options[:path]
-        action = options[:name] || args.first
-        metric_class = options[:class_name] || (self.is_a?(Class) ? self.name : self.class.name)
-        path = metric_class
-        path += ('/' + action) if action
-      end
-      [category, path, params]
-    end
+        include NewRelic::Agent::Instrumentation::QueueTime
 
-    # Filter out
-    def _is_filtered?(key)
-      ignore_actions = self.class.newrelic_read_attr(key) if self.class.respond_to? :newrelic_read_attr
-      case ignore_actions
-      when nil; false
-      when Hash
-        only_actions = Array(ignore_actions[:only])
-        except_actions = Array(ignore_actions[:except])
-        only_actions.include?(action_name.to_sym) || (except_actions.any? && !except_actions.include?(action_name.to_sym))
-      else
-        true
-      end
-    end
-    # Take a guess at a measure representing the number of requests waiting in mongrel
-    # or heroku.
-    def _record_queue_length
-      if newrelic_request_headers
-        if queue_depth = newrelic_request_headers['HTTP_X_HEROKU_QUEUE_DEPTH']
-          queue_depth = queue_depth.to_i rescue nil
-        elsif mongrel = NewRelic::Control.instance.local_env.mongrel
-          # Always subtrace 1 for the active mongrel
-          queue_depth = [mongrel.workers.list.length.to_i - 1, 0].max rescue nil
+        # Return a Time instance representing the upstream start time.
+        # now is a Time instance to fall back on if no other candidate
+        # for the start time is found.
+        def _detect_upstream_wait(now)
+          if newrelic_request_headers
+            parse_frontend_headers(newrelic_request_headers)
+          end
+          now
+        rescue Exception => e
+          NewRelic::Control.instance.log.error("Error detecting upstream wait time: #{e}")
+          NewRelic::Control.instance.log.debug("#{e.backtrace[0..20]}")
+          now
         end
-        NewRelic::Agent.agent.stats_engine.get_stats_no_scope('Mongrel/Queue Length').trace_call(queue_depth) if queue_depth
-      end
-    end
 
-    include NewRelic::Agent::Instrumentation::QueueTime
+        def _dispatch_stat
+          NewRelic::Agent.agent.stats_engine.get_stats_no_scope 'HttpDispatcher'
+        end
 
-    # Return a Time instance representing the upstream start time.
-    # now is a Time instance to fall back on if no other candidate
-    # for the start time is found.
-    def _detect_upstream_wait(now)
-      if newrelic_request_headers
-        parse_frontend_headers(newrelic_request_headers)
       end
-      now
-    rescue Exception => e
-      NewRelic::Control.instance.log.error("Error detecting upstream wait time: #{e}")
-      NewRelic::Control.instance.log.debug("#{e.backtrace[0..20]}")
-      now
     end
-
-    def _dispatch_stat
-      NewRelic::Agent.agent.stats_engine.get_stats_no_scope 'HttpDispatcher'
-    end
-
   end
 end
-end
-end