# This file is distributed under New Relic's license terms. # See https://github.com/newrelic/newrelic-ruby-agent/blob/main/LICENSE for complete details. # frozen_string_literal: true # This file may be independently required to set up method tracing prior to # the full agent loading. In those cases, we do need at least this require to # bootstrap things. require 'new_relic/control' unless defined?(NewRelic::Control) require 'new_relic/agent/method_tracer_helpers' module NewRelic module Agent # This module contains class methods added to support installing custom # metric tracers and executing for individual metrics. # # == Examples # # When the agent initializes, it extends Module with these methods. # However if you want to use the API in code that might get loaded # before the agent is initialized you will need to require # this file: # # require 'new_relic/agent/method_tracer' # class A # include NewRelic::Agent::MethodTracer # def process # ... # end # add_method_tracer :process # end # # To instrument a class method: # # require 'new_relic/agent/method_tracer' # class An # def self.process # ... # end # class << self # include NewRelic::Agent::MethodTracer # add_method_tracer :process # end # end # # @api public # module MethodTracer def self.included(klass) klass.extend(ClassMethods) end def self.extended(klass) klass.extend(ClassMethods) end # Trace a given block with stats and keep track of the caller. # See NewRelic::Agent::MethodTracer::ClassMethods#add_method_tracer for a description of the arguments. # +metric_names+ is either a single name or an array of metric names. # If more than one metric is passed, the +produce_metric+ option only applies to the first. The # others are always recorded. Only the first metric is pushed onto the scope stack. # # Generally you pass an array of metric names if you want to record the metric under additional # categories, but generally this *should never ever be done*. Most of the time you can aggregate # on the server. # # @api public # def trace_execution_scoped(metric_names, options = NewRelic::EMPTY_HASH) # THREAD_LOCAL_ACCESS NewRelic::Agent.record_api_supportability_metric(:trace_execution_scoped) unless options[:internal] NewRelic::Agent::MethodTracerHelpers.trace_execution_scoped(metric_names, options) do # Using an implicit block avoids object allocation for a &block param yield end end # Trace a given block with stats assigned to the given metric_name. It does not # provide scoped measurements, meaning whatever is being traced will not 'blame the # Controller'--that is to say appear in the breakdown chart. # # * metric_names is a single name or an array of names of metrics # # @api public # def trace_execution_unscoped(metric_names, options = NewRelic::EMPTY_HASH) # THREAD_LOCAL_ACCESS NewRelic::Agent.record_api_supportability_metric(:trace_execution_unscoped) unless options[:internal] return yield unless NewRelic::Agent.tl_is_execution_traced? t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC) begin yield ensure duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0 NewRelic::Agent.instance.stats_engine.tl_record_unscoped_metrics(metric_names, duration) end end # Defines methods used at the class level, for adding instrumentation # @api public module ClassMethods # contains methods refactored out of the #add_method_tracer method module AddMethodTracer ALLOWED_KEYS = [:metric, :push_scope, :code_header, :code_information, :code_footer].freeze DEFAULT_SETTINGS = {:push_scope => true, :metric => true, :code_header => "", :code_footer => ""}.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 _nr_validate_method_tracer_options(method_name, options) unless options.is_a?(Hash) raise TypeError.new("Error adding method tracer to #{method_name}: provided options must be a Hash") end unrecognized_keys = options.keys - ALLOWED_KEYS if unrecognized_keys.any? raise "Unrecognized options when adding method tracer to #{method_name}: " + unrecognized_keys.join(', ') end options = DEFAULT_SETTINGS.merge(options) unless options[:push_scope] || options[:metric] raise "Can't add a tracer where push_scope is false and metric is false" end options end # Default to the class where the method is defined. # # Example: # Foo._nr_default_metric_name_code('bar') #=> "Custom/#{Foo.name}/bar" def _nr_default_metric_name(method_name) class_name = _nr_derived_class_name -> (*) { "Custom/#{class_name}/#{method_name}" } 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::Agent.logger.error("Did not trace #{_nr_derived_class_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 method_traced?(method_name) exists = method_name && _nr_traced_method_module.method_defined?(method_name) ::NewRelic::Agent.logger.error("Attempt to trace a method twice: Method = #{method_name}") if exists exists end # Returns an anonymous module that stores prepended trace methods. def _nr_traced_method_module @_nr_traced_method_module ||= Module.new end # for testing only def _nr_clear_traced_methods! _nr_traced_method_module.module_eval do self.instance_methods.each { |m| remove_method(m) } end end def _nr_derived_class_name return self.name if self.name && !self.name.empty? return "AnonymousModule" if self.to_s.start_with?("#" name = self.to_s[/^#$/, 1] if name.start_with?("0x") "AnonymousClass" elsif name.start_with?("# { "Custom/#{self.class.name}/foo" } # # This would name the metric according to the class of the runtime # instance, as opposed to the class where +foo+ is defined. # # If not provided, the metric name will be Custom/ClassName/method_name. # # @param method_name [Symbol] the name of the method to trace # @param metric_name [String,Proc,Array] the metric name to record calls to # the traced method under. This may be either a String, or a Proc # to be evaluated at call-time in order to determine the metric # name dynamically. # This method also accepts an array of Strings/Procs, in which case the # first metric given will be scoped, while the remaining metrics will be # recorded as though passed with :push_scope => false. If an Array of # metric names is given with :push_scope => false, all metrics will be # unscoped. # @param [Hash] options additional options controlling how the method is # traced. # @option options [Boolean] :push_scope (true) If false, the traced method will # not appear in transaction traces or breakdown charts, and it will # only be visible in custom dashboards. # @option options [Boolean] :metric (true) If false, the traced method will # only appear in transaction traces, but no metrics will be recorded # for it. # @option options [Proc] :code_header ('') Ruby code to be inserted and run # before the tracer begins timing. # @option options [Proc] :code_footer ('') Ruby code to be inserted and run # after the tracer stops timing. # # @example # add_method_tracer :foo # # # With a custom metric name # add_method_tracer :foo, "Custom/MyClass/foo" # add_method_tracer :bar, -> { "Custom/#{self.class.name}/bar" } # # # Instrument foo only for custom dashboards (not in transaction # # traces or breakdown charts) # add_method_tracer :foo, 'Custom/foo', :push_scope => false # # # Instrument foo in transaction traces only # add_method_tracer :foo, 'Custom/foo', :metric => false # # @api public # def add_method_tracer(method_name, metric_name = nil, options = {}) ::NewRelic::Agent.add_or_defer_method_tracer(self, method_name, metric_name, options) end # 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. def remove_method_tracer(method_name) # :nodoc: return unless Agent.config[:agent_enabled] if _nr_traced_method_module.method_defined?(method_name) _nr_traced_method_module.send(:remove_method, method_name) ::NewRelic::Agent.logger.debug("removed method tracer #{method_name}\n") else raise "No tracer on method '#{method_name}'" end end private def _nr_add_method_tracer_now(method_name, metric_name, options) NewRelic::Agent.record_api_supportability_metric(:add_method_tracer) return unless newrelic_method_exists?(method_name) remove_method_tracer(method_name) if method_traced?(method_name) options = _nr_validate_method_tracer_options(method_name, options) visibility = NewRelic::Helper.instance_method_visibility(self, method_name) scoped_metric, unscoped_metrics = _nr_scoped_unscoped_metrics(metric_name, method_name, push_scope: options[:push_scope]) _nr_define_traced_method(method_name, scoped_metric: scoped_metric, unscoped_metrics: unscoped_metrics, code_header: options[:code_header], code_footer: options[:code_footer], record_metrics: options[:metric], visibility: visibility, code_information: options[:code_information]) prepend(_nr_traced_method_module) ::NewRelic::Agent.logger.debug("Traced method: class = #{_nr_derived_class_name}," + "method = #{method_name}, " + "metric = '#{metric_name}'") end # See #add_method_tracer; if multiple metric names are given, the first is # treated as scoped, the rest unscoped. If options[:push_scope] is false, # all given metrics are unscoped. def _nr_scoped_unscoped_metrics(metric_name, method_name, push_scope: true) if metric_name.is_a?(Array) && push_scope [metric_name.shift, metric_name] elsif push_scope [metric_name || _nr_default_metric_name(method_name), []] else [nil, Array(metric_name)] end end def _nr_define_traced_method(method_name, scoped_metric: nil, unscoped_metrics: [], code_header: nil, code_footer: nil, record_metrics: true, visibility: :public, code_information: {}) _nr_traced_method_module.module_eval do define_method(method_name) do |*args, &block| return super(*args, &block) unless NewRelic::Agent.tl_is_execution_traced? scoped_metric_eval, unscoped_metrics_eval = nil, [] scoped_metric_eval = case scoped_metric when Proc instance_exec(*args, &scoped_metric) when String scoped_metric end unscoped_metrics_eval = unscoped_metrics.map do |metric| metric.kind_of?(Proc) ? instance_exec(*args, &metric) : metric.to_s end instance_exec(&code_header) if code_header.kind_of?(Proc) # NOTE: Calling ::NewRelic::Agent::MethodTracer.trace_execution_scoped and # .trace_execution_unscoped below relies on the fact that MethodTracer is included # in Module on agent startup. If/when this changes, these methods should be # explicitly namespaced and extended in MethodTracer. # If tracing multiple metrics on this method, nest one unscoped trace inside the scoped trace. begin if scoped_metric_eval ::NewRelic::Agent::MethodTracer.trace_execution_scoped(scoped_metric_eval, metric: record_metrics, internal: true, code_information: code_information) do if unscoped_metrics_eval.empty? super(*args, &block) else ::NewRelic::Agent::MethodTracer.trace_execution_unscoped(unscoped_metrics_eval, internal: true) do super(*args, &block) end end end elsif !unscoped_metrics_eval.empty? ::NewRelic::Agent::MethodTracer.trace_execution_unscoped(unscoped_metrics_eval, internal: true) do super(*args, &block) end end ensure instance_exec(&code_footer) if code_footer.kind_of?(Proc) end end send(visibility, method_name) ruby2_keywords(method_name) if respond_to?(:ruby2_keywords, true) end end end # @!parse extend ClassMethods end end end