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 ClassMethods#add_transaction_tracer.

Here‘s a more verbose version of the example shown in ClassMethods#add_transaction_tracer 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 New Relic 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:

• :category => :controller indicates that this is a controller action and will appear with all the other actions. This is the default.
• :category => :task indicates that this is a background task and will show up in New Relic with other background tasks instead of in the controllers list
• :category => :middleware if you are instrumenting a rack middleware call. The :name is optional, useful if you have more than one potential transaction in the call.
• :category => :uri 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.
• :name => action_name is used to specify the action name used as part of the metric name
• :params => {…} to provide information about the context of the call, used in transaction trace display, for example: :params => { :account => @account.name, :file => file.name } These are treated similarly to request parameters in web transactions.

Seldomly used options:

• :class_name => aClass.name is used to override the name of the class when used inside the metric name. Default is the current class.
• :path => metric_path is deprecated in the public API. It allows you to set the entire metric after the category part. Overrides all the other options.
• :request => Rack::Request#new(env) is used to pass in a request object that may respond to path and referer.

@api public

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.

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

Should be implemented in the dispatcher class