newrelic_rpm 3.12.0.288 → 9.10.2

data/lib/new_relic/agent/method_tracer.rb

@@ -1,8 +1,12 @@
-# encoding: utf-8
 # This file is distributed under New Relic's license terms.
-# See https://github.com/newrelic/rpm/blob/master/LICENSE for complete details.
+# 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/control'
 require 'new_relic/agent/method_tracer_helpers'
 
 module NewRelic
@@ -43,12 +47,12 @@ module NewRelic
     #
 
     module MethodTracer
-      def self.included clazz
-        clazz.extend ClassMethods
+      def self.included(klass)
+        klass.extend(ClassMethods)
       end
 
-      def self.extended clazz
-        clazz.extend ClassMethods
+      def self.extended(klass)
+        klass.extend(ClassMethods)
       end
 
       # Trace a given block with stats and keep track of the caller.
@@ -63,7 +67,8 @@ module NewRelic
       #
       # @api public
       #
-      def trace_execution_scoped(metric_names, options={}) #THREAD_LOCAL_ACCESS
+      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
@@ -73,132 +78,63 @@ module NewRelic
       # 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.
-      # This is code is inlined in #add_method_tracer.
+      #
       # * <tt>metric_names</tt> is a single name or an array of names of metrics
       #
       # @api public
       #
-      def trace_execution_unscoped(metric_names, options={}) #THREAD_LOCAL_ACCESS
+      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 = Time.now
+
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         begin
           yield
         ensure
-          duration = (Time.now - t0).to_f              # for some reason this is 3 usec faster than Time - Time
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
           NewRelic::Agent.instance.stats_engine.tl_record_unscoped_metrics(metric_names, duration)
         end
       end
 
-      # Deprecated: original method preserved for API backward compatibility.
-      # Use either #trace_execution_scoped or #trace_execution_unscoped
-      #
-      # @api public
-      # @deprecated
-      #
-      def trace_method_execution(metric_names, push_scope, produce_metric, deduct_call_time_from_parent, &block) #:nodoc:
-        if push_scope
-          trace_execution_scoped(metric_names, :metric => produce_metric,
-                                 :deduct_call_time_from_parent => deduct_call_time_from_parent, &block)
-        else
-          trace_execution_unscoped(metric_names, &block)
-        end
-      end
-
-      # Deprecated. Use #trace_execution_scoped, a version with an options hash.
-      #
-      # @deprecated
-      #
-      def trace_method_execution_with_scope(metric_names, produce_metric, deduct_call_time_from_parent, scoped_metric_only=false, &block) #:nodoc:
-        trace_execution_scoped(metric_names,
-                               :metric => produce_metric,
-                               :deduct_call_time_from_parent => deduct_call_time_from_parent,
-                               :scoped_metric_only => scoped_metric_only, &block)
-      end
-
-      alias trace_method_execution_no_scope trace_execution_unscoped #:nodoc:
-
-      #
-      # This method is deprecated and exists only for backwards-compatibility
-      # reasons. Usages should be replaced with calls to
-      # NewRelic::Agent.record_metric.
-      #
-      # @api public
-      # @deprecated
-      #
-      def get_stats_scoped(first_name, scoped_metric_only)
-        NewRelic::Agent.instance.stats_engine.get_stats(first_name, true, scoped_metric_only)
-      end
-
-      # This method is deprecated and exists only for backwards-compatibility
-      # reasons. Usages should be replaced with calls to
-      # NewRelic::Agent.record_metric.
-      #
-      # @api public
-      # @deprecated
-      #
-      def get_stats_unscoped(name)
-        NewRelic::Agent.instance.stats_engine.get_stats_no_scope(name)
-      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 = [:force, :metric, :push_scope, :code_header, :code_footer].freeze
+          ALLOWED_KEYS = [:metric, :push_scope, :code_header, :code_information, :code_footer].freeze
 
-          DEPRECATED_KEYS = [:force, :scoped_metric_only, :deduct_call_time_from_parent].freeze
+          DEFAULT_SETTINGS = {:push_scope => true, :metric => true, :code_header => '', :code_footer => ''}.freeze
 
-          # raises an error when the
-          # NewRelic::Agent::MethodTracer::ClassMethods#add_method_tracer
-          # method is called with improper keys. This aids in
-          # debugging new instrumentation by failing fast
-          def check_for_illegal_keys!(method_name, options)
-            unrecognized_keys = options.keys - ALLOWED_KEYS
-            deprecated_keys   = options.keys & DEPRECATED_KEYS
+          # 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(', ')
+                unrecognized_keys.join(', ')
             end
 
-            if deprecated_keys.any?
-              NewRelic::Agent.logger.warn("Deprecated options when adding method tracer to #{method_name}: "+
-                deprecated_keys.join(', '))
-            end
-          end
-
-          # validity checking - add_method_tracer must receive either
-          # push scope or metric, or else it would record no
-          # data. Raises an error if this is the case
-          def check_for_push_scope_and_metric(options)
+            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
-          end
-
-          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 validate_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
-            check_for_illegal_keys!(method_name, options)
-            options = DEFAULT_SETTINGS.merge(options)
-            check_for_push_scope_and_metric(options)
             options
           end
 
           # Default to the class where the method is defined.
           #
           # Example:
-          #  Foo.default_metric_name_code('bar') #=> "Custom/#{Foo.name}/bar"
-          def default_metric_name_code(method_name)
-            "Custom/#{self.name}/#{method_name.to_s}"
+          #  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
@@ -206,7 +142,7 @@ module NewRelic
           # 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 #{self.name}##{method_name} because that method does not exist") unless exists
+            ::NewRelic::Agent.logger.error("Did not trace #{_nr_derived_class_name}##{method_name} because that method does not exist") unless exists
             exists
           end
 
@@ -214,61 +150,36 @@ module NewRelic
           # 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 traced_method_exists?(method_name, metric_name_code)
-            exists = method_defined?(_traced_method_name(method_name, metric_name_code))
-            ::NewRelic::Agent.logger.error("Attempt to trace a method twice with the same metric: Method = #{method_name}, Metric Name = #{metric_name_code}") if exists
+          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 a code snippet to be eval'd that skips tracing
-          # when the agent is not tracing execution. turns
-          # instrumentation into effectively one method call overhead
-          # when the agent is disabled
-          def assemble_code_header(method_name, metric_name_code, options)
-            header = "return #{_untraced_method_name(method_name, metric_name_code)}(*args, &block) unless NewRelic::Agent.tl_is_execution_traced?\n"
-            header += options[:code_header].to_s
-            header
+          # Returns an anonymous module that stores prepended trace methods.
+          def _nr_traced_method_module
+            @_nr_traced_method_module ||= Module.new
           end
 
-          # returns an eval-able string that contains the traced
-          # method code used if the agent is not creating a scope for
-          # use in scoped metrics.
-          def method_without_push_scope(method_name, metric_name_code, options)
-            "def #{_traced_method_name(method_name, metric_name_code)}(*args, &block)
-              #{assemble_code_header(method_name, metric_name_code, options)}
-              t0 = Time.now
-              begin
-                #{_untraced_method_name(method_name, metric_name_code)}(*args, &block)\n
-              ensure
-                duration = (Time.now - t0).to_f
-                NewRelic::Agent.record_metric(\"#{metric_name_code}\", duration)
-                #{options[:code_footer]}
-              end
-            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
 
-          # returns an eval-able string that contains the tracing code
-          # for a fully traced metric including scoping
-          def method_with_push_scope(method_name, metric_name_code, options)
-            "def #{_traced_method_name(method_name, metric_name_code)}(*args, &block)
-              #{options[:code_header]}
-              result = ::NewRelic::Agent::MethodTracerHelpers.trace_execution_scoped(\"#{metric_name_code}\",
-                        :metric => #{options[:metric]}) do
-                #{_untraced_method_name(method_name, metric_name_code)}(*args, &block)
-              end
-              #{options[:code_footer]}
-              result
-            end"
-          end
+          def _nr_derived_class_name
+            return self.name if self.name && !self.name.empty?
+            return 'AnonymousModule' if self.to_s.start_with?('#<Module:')
 
-          # Decides which code snippet we should be eval'ing in this
-          # context, based on the options.
-          def code_to_eval(method_name, metric_name_code, options)
-            options = validate_options(method_name, options)
-            if options[:push_scope]
-              method_with_push_scope(method_name, metric_name_code, options)
+            # trying to get the "MyClass" portion of "#<Class:MyClass>"
+            name = self.to_s[/^#<Class:(.+)>$/, 1]
+            if name.start_with?('0x')
+              'AnonymousClass'
+            elsif name.start_with?('#<Class:')
+              'AnonymousClass/Class'
             else
-              method_without_push_scope(method_name, metric_name_code, options)
+              "#{name}/Class"
             end
           end
         end
@@ -283,22 +194,26 @@ module NewRelic
         #
         # === 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 interpolation
-        # evaluated at call time, then single quote the value like this:
+        # +metric_name+ is a String or Proc. If a Proc is given, it is bound to
+        # the object that called the traced method. For example:
         #
-        #     add_method_tracer :foo, 'Custom/#{self.class.name}/foo'
+        #     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.
+        # instance, as opposed to the class where +foo+ is defined.
         #
         # If not provided, the metric name will be <tt>Custom/ClassName/method_name</tt>.
         #
-        # @param [Symbol] method_name the name of the method to trace
-        # @param [String] metric_name_code the metric name to record calls to
-        #   the traced method under. This may be either a static string, or Ruby
-        #   code to be evaluated at call-time in order to determine the metric
+        # @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
@@ -307,16 +222,17 @@ module NewRelic
         # @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 [String] :code_header ('') Ruby code to be inserted and run
+        # @option options [Proc] :code_header ('') Ruby code to be inserted and run
         #   before the tracer begins timing.
-        # @option options [String] :code_footer ('') Ruby code to be inserted and run
+        # @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/#{self.class.name}/foo'
+        #   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)
@@ -327,57 +243,119 @@ module NewRelic
         #
         # @api public
         #
-        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)
-
-          visibility = NewRelic::Helper.instance_method_visibility self, method_name
-
-          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)
-          send visibility, method_name
-          send visibility, _traced_method_name(method_name, metric_name_code)
-          ::NewRelic::Agent.logger.debug("Traced method: class = #{self.name},"+
-                    "method = #{method_name}, "+
-                    "metric = '#{metric_name_code}'")
+        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, metric_name_code) # :nodoc:
+        def remove_method_tracer(method_name) # :nodoc:
           return unless Agent.config[: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::Agent.logger.debug("removed method tracer #{method_name} #{metric_name_code}\n")
+
+          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 for '#{metric_name_code}' on method '#{method_name}'"
+            raise "No tracer on method '#{method_name}'"
           end
         end
+
         private
 
-        # given a method and a metric, this method returns the
-        # untraced alias of the method name
-        def _untraced_method_name(method_name, metric_name)
-          "#{_sanitize_name(method_name)}_without_trace_#{_sanitize_name(metric_name)}"
+        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
 
-        # given a method and a metric, this method returns the traced
-        # alias of the method name
-        def _traced_method_name(method_name, metric_name)
-          "#{_sanitize_name(method_name)}_with_trace_#{_sanitize_name(metric_name)}"
+        # 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
 
-        # makes sure that method names do not contain characters that
-        # might break the interpreter, for example ! or ? characters
-        # that are not allowed in the middle of method names
-        def _sanitize_name(name)
-          name.to_s.tr_s('^a-zA-Z0-9', '_')
+        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