Module: NewRelic::Agent::MethodTracer::ClassMethods

Includes:
AddMethodTracer
Defined in:
lib/new_relic/agent/method_tracer.rb

Overview

Defines methods used at the class level, for adding instrumentation

Defined Under Namespace

Modules: AddMethodTracer

Constant Summary

Constants included from AddMethodTracer

AddMethodTracer::ALLOWED_KEYS, AddMethodTracer::DEFAULT_SETTINGS

Instance Method Summary collapse

Methods included from AddMethodTracer

#any_unrecognized_keys?, #assemble_code_header, #check_for_illegal_keys!, #check_for_push_scope_and_metric, #code_to_eval, #default_metric_name_code, #method_with_push_scope, #method_without_push_scope, #newrelic_method_exists?, #set_deduct_call_time_based_on_metric, #traced_method_exists?, #unrecognized_keys, #validate_options

Instance Method Details

#add_method_tracer(method_name, metric_name_code = nil, options = {}) ⇒ Object

Add a method tracer to the specified method.

Common Options

  • :push_scope => false specifies this method tracer should not keep track of the caller; it will not show up in controller breakdown pie charts.

  • :metric => false 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

  • :scoped_metric_only => true 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 :metric => false but in addition you will also see the invocation in breakdown pie charts.

  • :deduct_call_time_from_parent => false 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.

  • :code_header and :code_footer specify ruby code that is inserted into the tracer before and after the call.

  • :force = true 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 Custom/ClassName/method_name.

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


477
478
479
480
481
482
483
484
485
486
487
488
489
490
# File 'lib/new_relic/agent/method_tracer.rb', line 477

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)
  return if traced_method_exists?(method_name, metric_name_code)

  traced_method = code_to_eval(method_name, metric_name_code, options)

  class_eval traced_method, __FILE__, __LINE__
  alias_method _untraced_method_name(method_name, metric_name_code), method_name
  alias_method method_name, _traced_method_name(method_name, metric_name_code)
  NewRelic::Control.instance.log.debug("Traced method: class = #{self.name},"+
            "method = #{method_name}, "+
            "metric = '#{metric_name_code}'")
end

#remove_method_tracer(method_name, metric_name_code) ⇒ Object

For tests only because tracers must be removed in reverse-order from when they were added, or else other tracers that were added to the same method may get removed as well.



495
496
497
498
499
500
501
502
503
504
# File 'lib/new_relic/agent/method_tracer.rb', line 495

def remove_method_tracer(method_name, metric_name_code) # :nodoc:
  return unless NewRelic::Control.instance.agent_enabled?
  if method_defined? "#{_traced_method_name(method_name, metric_name_code)}"
    alias_method method_name, "#{_untraced_method_name(method_name, metric_name_code)}"
    undef_method "#{_traced_method_name(method_name, metric_name_code)}"
    NewRelic::Control.instance.log.debug("removed method tracer #{method_name} #{metric_name_code}\n")
  else
    raise "No tracer for '#{metric_name_code}' on method '#{method_name}'"
  end
end