datadog 2.4.0 → 2.44.0

data/lib/datadog/di/instrumenter.rb

@@ -0,0 +1,978 @@
+# frozen_string_literal: true
+
+require_relative "../core/rate_limiter"
+require_relative "../core/utils/time"
+require_relative "../ruby_version"
+require_relative "fatal_exceptions"
+require_relative "capture_expression_evaluator"
+
+# rubocop:disable Lint/AssignmentInCondition
+# rubocop:disable Style/AndOr
+
+module Datadog
+  module DI
+    # Arranges to invoke a callback when a particular Ruby method or
+    # line of code is executed.
+    #
+    # Method instrumentation is accomplished via module prepending.
+    # Unlike the alias_method_chain pattern, module prepending permits
+    # removing instrumentation with no virtually performance side-effects
+    # (the target class retains an empty included module, but no additional
+    # code is executed as part of target method).
+    #
+    # Method hooking works with explicitly defined methods and "virtual"
+    # methods defined via method_missing.
+    #
+    # Line instrumentation is normally accomplished with a targeted line
+    # trace point. This requires MRI and at least Ruby 2.6.
+    # For testing purposes, it is also possible to use untargeted trace
+    # points, but they have a huge performance penalty and should generally
+    # not be used in production.
+    #
+    # Targeted line trace points require tracking of loaded code; see
+    # the CodeTracker class for more details.
+    #
+    # Instrumentation state (i.e., the module or trace point used for
+    # instrumentation) is stored in the Probe instance. Thus, Instrumenter
+    # mutates attributes of Probes it is asked to install or remove.
+    # A previous version of the code attempted to maintain the instrumentation
+    # state within Instrumenter but this was very messy and hard to
+    # guarantee correctness of. With the state stored in Probes, it is
+    # straightforward to determine if a Probe has been successfully instrumented,
+    # and thus requires cleanup, and to properly clean it up.
+    #
+    # Note that the upstream code is responsible for generally storing Probes.
+    # This is normally accomplished by ProbeManager. ProbeManager stores all
+    # known probes, instrumented or not, and is responsible for calling
+    # +unhook+ of Instrumenter to clean up instrumentation when a user
+    # deletes a probe in UI or when DI is shut down.
+    #
+    # Given the need to store state, and also that there are several Probe
+    # attributes that affect how instrumentation is set up and that must be
+    # consulted very early in the callback invocation (e.g., to perform
+    # rate limiting correctly), Instrumenter takes Probe instances as
+    # arguments rather than e.g. file + line number or class + method name.
+    # As a result, Instrumenter is rather coupled to DI the product and is
+    # not trivially usable as a general-purpose Ruby instrumentation tool
+    # (however, Probe instances can be replaced by OpenStruct instances
+    # providing the same interface with not much effort).
+    #
+    # Instrumenter (this class) is responsible for building snapshots.
+    # This is because to capture values on method entry, those values need to
+    # be duplicated or serialized into immutable values to prevent their
+    # modification by the instrumented method. Therefore this class must
+    # do at least some serialization/snapshot building and to keep the code
+    # well-encapsulated, all serialization/snapshot building should thus be
+    # initiated from this class rather than downstream code.
+    #
+    # As a consequence of Instrumenter building snapshots, it should not
+    # expose TracePoint objects to any downstream code.
+    #
+    # @api private
+    class Instrumenter
+      # Maximum number of capturing-probe snapshots admitted per second across the
+      # whole process.
+      GLOBAL_SNAPSHOT_RATE_LIMIT = 20
+
+      # Maximum number of non-capturing probe emissions admitted per second across
+      # the whole process.
+      GLOBAL_LOG_RATE_LIMIT = 5000
+
+      def initialize(settings, serializer, logger, code_tracker: nil, telemetry: nil)
+        @settings = settings
+        @serializer = serializer
+        @logger = logger
+        @telemetry = telemetry
+        @code_tracker = code_tracker
+        @global_snapshot_rate_limiter = Datadog::Core::TokenBucket.new(GLOBAL_SNAPSHOT_RATE_LIMIT)
+        @global_log_rate_limiter = Datadog::Core::TokenBucket.new(GLOBAL_LOG_RATE_LIMIT)
+
+        @lock = Mutex.new
+      end
+
+      attr_reader :settings
+      attr_reader :serializer
+      attr_reader :logger
+      attr_reader :telemetry
+      attr_reader :code_tracker
+
+      # The code tracker is a global singleton created lazily by
+      # DI.activate_tracking. When DI is enabled after boot via remote
+      # configuration this instrumenter was already built with a nil tracker;
+      # Component#start! assigns the now-current tracker here.
+      attr_writer :code_tracker
+
+      # Process-wide snapshot rate limiter.
+      # @return [Datadog::Core::TokenBucket]
+      attr_reader :global_snapshot_rate_limiter
+      # Process-wide log rate limiter.
+      # @return [Datadog::Core::TokenBucket]
+      attr_reader :global_log_rate_limiter
+
+      def capture_expression_evaluator
+        @capture_expression_evaluator ||= CaptureExpressionEvaluator.new(
+          settings: settings, serializer: serializer, logger: logger, telemetry: telemetry,
+        )
+      end
+
+      # Returns the process-wide rate limiter for the probe.
+      #
+      # @param probe [Probe] the probe whose invocation is being rate limited
+      # @return [Datadog::Core::TokenBucket] the shared limiter for the probe's category
+      def probe_global_rate_limiter(probe)
+        if probe.capturing?
+          global_snapshot_rate_limiter
+        else
+          global_log_rate_limiter
+        end
+      end
+
+      # This is a substitute for Thread::Backtrace::Location
+      # which does not have a public constructor.
+      # Used for the fabricated stack frame for the method itself
+      # for method probes (which use Module#prepend and thus aren't called
+      # from the method but from outside of the method).
+      Location = Struct.new(:path, :lineno, :label)
+
+      # Method probes can only target instance methods. The implementation uses
+      # Module#prepend with a module that defines an instance method matching the
+      # probe's target — class/singleton methods (def self.foo, module_function)
+      # are not reachable via prepend on the class itself. Line probes are
+      # unaffected since they install via TracePoint, not method dispatch.
+      def hook_method(probe, responder)
+        # Reject method probes targeting any class or module in the Datadog
+        # namespace. The tracer uses these classes internally while building
+        # and dispatching probe snapshots; allowing a method probe on them
+        # would let DI's own code paths re-enter the probe wrapper. Line
+        # probes are unaffected (TracePoint is self-disabling during its
+        # callback) and are not rejected here.
+        type_name = probe.type_name
+        if type_name && datadog_namespace_type_name?(type_name)
+          raise Error::ProbeTargetForbidden,
+            "Method probes on the Datadog namespace are not permitted: #{type_name}##{probe.method_name}"
+        end
+
+        lock.synchronize do
+          if probe.instrumentation_module
+            # Already instrumented, warn?
+            return
+          end
+        end
+
+        cls = symbolize_class_name(probe.type_name)
+        method_name = probe.method_name!
+        target_method = begin
+          cls.instance_method(method_name)
+        rescue NameError
+          # The target method is not defined.
+          # This could be because it will be explicitly defined later
+          # (since classes can be reopened in Ruby)
+          # or the method is virtual (provided by a method_missing handler).
+          # In these cases we do not have a source location for the
+          # target method here.
+          nil
+        end
+
+        # Reject method probes whose target method resolves to Kernel#lambda,
+        # including inherited targets. Every class inherits Kernel#lambda, so a
+        # probe naming any type that does not override lambda (Object#lambda,
+        # String#lambda, a plain user class, ...) prepends the wrapper ahead of
+        # Kernel#lambda and reaches the wrapper's super(&block) path. On
+        # Ruby 3.3+ that path raises ArgumentError for every lambda { ... }
+        # call site passing a captured block, breaking lambda creation
+        # process-wide. Resolving the method owner catches the inherited case
+        # that a textual "Kernel" name match misses; a type that defines its
+        # own lambda has a different owner and is left alone. Probing lambda
+        # creation has no legitimate customer use case. See #5560.
+        if method_name == "lambda" && target_method&.owner == ::Kernel
+          raise Error::ProbeTargetForbidden,
+            "Method probes on Kernel#lambda are not permitted: #{probe.type_name}##{method_name}"
+        end
+
+        loc = target_method&.source_location
+        # @type var instrumenter: Instrumenter
+        instrumenter = self
+
+        mod = Module.new do
+          # Argument delegation follows docs/Delegation.md: on Ruby 3+
+          # positional and keyword arguments are captured and forwarded
+          # separately; on Ruby < 3 everything is captured into a single
+          # splat that ruby2_keywords flags, which is the only way to forward
+          # a trailing hash while preserving its positional-vs-keyword
+          # identity. The pre-3 branch is what lets an empty trailing hash
+          # (e.g. foo('x', {})) reach the original method intact.
+          #
+          # Re-entrancy guard: if we are already inside a DI method-probe
+          # callback, skip DI processing and call the original method
+          # directly. This prevents SystemStackError when a method probe is
+          # set on a stdlib method that DI itself calls during method-probe
+          # snapshot building (e.g., String#length, Hash#each). Line probes
+          # do not enter the guard — they rely on Ruby's TracePoint, which
+          # self-disables during its own callback. Nested invocations during
+          # DI processing also bypass the rate limiter: they are not
+          # user-observable probe firings, just internal calls that happen to
+          # land on a probed method. Guard storage is fiber-local;
+          # DI.in_probe?/enter_probe/leave_probe are implemented in C and
+          # access it directly, bypassing Thread#[]/Thread#[]= method dispatch
+          # so user probes on those cannot recurse.
+          #
+          # The original method is invoked via super. That super call lives
+          # in a block passed to #run_method_probe and captures its binding
+          # from inside this define_method block — the only place super
+          # resolves to the prepended-on class's method. #run_method_probe
+          # invokes it with yield, which does not dispatch Proc#call, so a
+          # user probe on Proc#call cannot intercept the trampoline, and no
+          # Proc is allocated for the block.
+          if RubyVersion.is?(">= 3")
+            define_method(method_name) do |*args, **kwargs, &target_block|
+              # steep:ignore FallbackAny below: Steep cannot narrow the
+              # **kwargs parameter inside this define_method block, so it
+              # falls back to untyped at the super and run_method_probe sites.
+              if DI.in_probe?
+                return super(*args, **kwargs, &target_block) # steep:ignore FallbackAny
+              end
+
+              instrumenter.run_method_probe(
+                args, kwargs, target_block, # steep:ignore FallbackAny
+                self,
+                probe, responder,
+                loc, method_name,
+              ) do
+                super(*args, **kwargs, &target_block) # steep:ignore FallbackAny
+              end
+            end
+          else
+            define_method(method_name) do |*args, &target_block|
+              if DI.in_probe?
+                return super(*args, &target_block)
+              end
+
+              # The super block replays the original *args (closed over here)
+              # so the ruby2_keywords-flagged trailing hash keeps its
+              # identity. run_method_probe receives the serialization-split
+              # arguments separately; forwarding does not use them.
+              pos_args, kwargs = instrumenter.kwargs_from_splat(args)
+              instrumenter.run_method_probe(
+                pos_args, kwargs, target_block,
+                self,
+                probe, responder,
+                loc, method_name,
+              ) do
+                super(*args, &target_block)
+              end
+            end
+            ruby2_keywords(method_name) if respond_to?(:ruby2_keywords, true)
+          end
+        end
+
+        lock.synchronize do
+          if probe.instrumentation_module
+            # Already instrumented from another thread
+            return
+          end
+
+          probe.instrumentation_module = mod
+          cls.send(:prepend, mod)
+
+          DI.instrumented_count_inc(:method)
+        end
+      end
+
+      def unhook_method(probe)
+        # Ruby does not permit removing modules from classes.
+        # We can, however, remove method definitions from modules.
+        # After this the modules remain in memory and stay included
+        # in the classes but are empty (have no methods).
+        lock.synchronize do
+          if mod = probe.instrumentation_module
+            mod.send(:remove_method, probe.method_name)
+            probe.instrumentation_module = nil
+
+            DI.instrumented_count_dec(:method)
+          end
+        end
+      end
+
+      # Instruments a particluar line in a source file.
+      # Note that this method only works for physical files,
+      # not for eval'd code, unless the eval'd code is associated with
+      # a file name and client invokes this method with the correct
+      # file name for the eval'd code.
+      def hook_line(probe, responder)
+        lock.synchronize do
+          if probe.instrumentation_trace_point
+            # Already instrumented, warn?
+            return
+          end
+        end
+
+        line_no = probe.line_no!
+
+        # Memoize the value to ensure this method always uses the same
+        # value for the setting.
+        # Normally none of the settings should change, but in the test suite
+        # we use mock objects and the methods may be mocked with
+        # individual invocations, yielding different return values on
+        # different calls to the same method.
+        permit_untargeted_trace_points = settings.dynamic_instrumentation.internal.untargeted_trace_points
+
+        iseq = nil
+        if code_tracker
+          # Steep: Complex type narrowing (before calling hook_line,
+          # we check that probe.line? is true which itself checks that probe.file is not nil)
+          # Annotation do not work here as `file` is a method on probe, not a local variable.
+          ret = if code_tracker.respond_to?(:iseq_for_line)
+            code_tracker.iseq_for_line(probe.file, line_no) # steep:ignore ArgumentTypeMismatch
+          else
+            code_tracker.iseqs_for_path_suffix(probe.file) # steep:ignore ArgumentTypeMismatch
+          end
+          unless ret
+            if permit_untargeted_trace_points
+              # Continue withoout targeting the trace point.
+              # This is going to cause a serious performance penalty for
+              # the entire file containing the line to be instrumented.
+            else
+              # Do not use untargeted trace points unless they have been
+              # explicitly requested by the user, since they cause a
+              # serious performance penalty.
+              #
+              # If the requested file is not in code tracker's registry,
+              # or the code tracker does not exist at all,
+              # do not attempt to instrument now.
+              # The caller should add the line to the list of pending lines
+              # to instrument and install the hook when the file in
+              # question is loaded (and hopefully, by then code tracking
+              # is active, otherwise the line will never be instrumented.)
+              raise_if_probe_in_loaded_features(probe, line_no, code_tracker)
+              raise Error::DITargetNotDefined, "File not in code tracker registry: #{probe.file}:#{line_no}"
+            end
+          end
+        elsif !permit_untargeted_trace_points
+          # Same as previous comment, if untargeted trace points are not
+          # explicitly defined, and we do not have code tracking, do not
+          # instrument the method.
+          raise_if_probe_in_loaded_features(probe, line_no, nil)
+          raise Error::DITargetNotDefined, "File not in code tracker registry: #{probe.file}:#{line_no}"
+        end
+
+        if ret
+          actual_path, iseq = ret
+        end
+
+        # If trace point is not targeted, we only need one trace point per file.
+        # Creating a trace point for each probe does work but the performance
+        # penalty will be taken for each trace point defined in the file.
+        # Since untargeted trace points are only (currently) used internally
+        # for benchmarking, and shouldn't be used in customer applications,
+        # we always create a trace point here to reduce complexity.
+        #
+        # For targeted trace points, if multiple probes target the same
+        # file and line, we also only need one trace point, but since the
+        # overhead of targeted trace points is minimal, don't worry about
+        # this optimization just yet and create a trace point for each probe.
+
+        types = if iseq
+          # When targeting trace points we can target the 'end' line of a method.
+          # However, by adding the :return trace point we lose diagnostics
+          # for lines that contain no executable code (e.g. comments only)
+          # and thus cannot actually be instrumented.
+          [:line, :return, :b_return]
+        else
+          [:line]
+        end
+        tp = TracePoint.new(*types) do |tp|
+          line_trace_point_callback(probe, iseq, responder, tp)
+        end
+
+        # Internal sanity check - untargeted trace points create a huge
+        # performance impact, and we absolutely do not want to set them
+        # accidentally.
+        if !iseq && !permit_untargeted_trace_points
+          raise Error::InternalError, "Trying to use an untargeted trace point when user did not permit it"
+        end
+
+        lock.synchronize do
+          if probe.instrumentation_trace_point
+            # Already instrumented in another thread, warn?
+            return
+          end
+
+          probe.instrumentation_trace_point = tp
+          # actual_path could be nil if we don't use targeted trace points.
+          probe.instrumented_path = actual_path
+
+          # TracePoint#enable returns false when it succeeds.
+          rv = if iseq
+            tp.enable(target: iseq, target_line: line_no)
+          else
+            tp.enable
+          end
+
+          DI.instrumented_count_inc(:line)
+
+          rv
+        end
+        true
+      end
+
+      def unhook_line(probe)
+        lock.synchronize do
+          if tp = probe.instrumentation_trace_point
+            tp.disable
+            probe.instrumentation_trace_point = nil
+
+            DI.instrumented_count_dec(:line)
+          end
+        end
+      end
+
+      def hook(probe, responder)
+        if probe.method?
+          hook_method(probe, responder)
+        elsif probe.line?
+          hook_line(probe, responder)
+        else
+          # TODO add test coverage for this path
+          logger.debug { "di: unknown probe type to hook: #{probe}" }
+        end
+      end
+
+      def unhook(probe)
+        if probe.method?
+          unhook_method(probe)
+        elsif probe.line?
+          unhook_line(probe)
+        else
+          # TODO add test coverage for this path
+          logger.debug { "di: unknown probe type to unhook: #{probe}" }
+        end
+      end
+
+      class << self
+        def get_local_variables(trace_point)
+          # binding appears to be constructed on access, therefore
+          # 1) we should attempt to cache it and
+          # 2) we should not call +binding+ until we actually need variable values.
+          binding = trace_point.binding
+
+          # steep hack - should never happen
+          return {} unless binding
+
+          binding.local_variables.each_with_object({}) do |name, map|
+            value = binding.local_variable_get(name)
+            map[name] = value
+          end
+        end
+      end
+
+      private
+
+      attr_reader :lock
+
+      # Body of the method probe wrapper. Extracted from the define_method
+      # block in #hook_method so the begin/ensure structure can use normal
+      # indentation. The original method is invoked with yield, calling the
+      # block passed by #hook_method; that block captures super's binding
+      # from inside the define_method block, the only place super resolves
+      # to the prepended-on class's method.
+      #
+      # Performance: this method takes eight positional parameters, not
+      # keyword parameters, deliberately. Every probed method invocation
+      # passes through here on the firing/disabled/rate-limited paths.
+      # Keyword-argument calls in Ruby allocate a fresh Hash on every call
+      # to materialize the keyword bindings; with eight keyword arguments
+      # (~300-1000 ns of allocation per invocation), that hash dominated
+      # the wrapper's per-call overhead. Positional parameters skip the
+      # allocation entirely. The cost is a long unlabeled signature and
+      # an unlabeled call site in #hook_method — both small price for
+      # eliminating per-call allocation on the hot path. The argument
+      # order matches #hook_method's call site exactly; do not reorder
+      # without updating both sides.
+      #
+      # @param args [Array] positional arguments passed to the probed method
+      # @param kwargs [Hash{Symbol => Object}] keyword arguments passed to the probed method
+      # @param target_block [Proc, nil] block argument passed to the probed method
+      # @param target_self [any] the receiver of the probed method invocation
+      # @param probe [Datadog::DI::Probe] the probe whose callback this invocation runs
+      # @param responder [#probe_executed_callback, #probe_condition_evaluation_failed_callback] callback target invoked with the built Context
+      # @param loc [Array(String, Integer), nil] source location of the probed method, or nil for virtual/lazily-defined methods
+      # @param method_name [String] name of the probed method, used as the synthetic top stack frame label
+      # @yield invokes the original method via super and returns its value
+      # @return [Object] the original method's return value, or re-raises its exception
+      def run_method_probe(args, kwargs, target_block, target_self,
+        probe, responder, loc, method_name)
+        # Disabled probe: skip DI processing entirely. enter_probe is not
+        # called on this path so the guard is never set — there is no DI
+        # work to guard, and any nested probed methods invoked by the
+        # original method should fire normally without short-circuit.
+        return yield unless probe.enabled?
+
+        DI.enter_probe
+        begin
+          di_start_time = Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID)
+
+          continue = true
+          if condition = probe.condition
+            begin
+              # This context will be recreated later, unlike for line probes.
+              #
+              # We do not need the stack for condition evaluation, therefore
+              # stack is not passed to Context here.
+              context = Context.new(
+                locals: serializer.combine_args(args, kwargs, target_self),
+                target_self: target_self,
+                probe: probe, settings: settings, serializer: serializer,
+              )
+              continue = condition.satisfied?(context)
+            rescue Exception => exc # standard:disable Lint/RescueException
+              Datadog::DI.reraise_if_fatal(exc)
+              # Evaluation error exception can be raised for "expected"
+              # errors, we probably need another setting to control whether
+              # these exceptions are propagated.
+              raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions &&
+                !exc.is_a?(DI::Error::ExpressionEvaluationError)
+
+              if context
+                # We want to report evaluation errors for conditions
+                # as probe snapshots. However, if we failed to create
+                # the context, we won't be able to report anything as
+                # the probe notifier builder requires a context.
+                begin
+                  responder.probe_condition_evaluation_failed_callback(context, condition, exc)
+                rescue Exception => nested_exc # standard:disable Lint/RescueException
+                  Datadog::DI.reraise_if_fatal(nested_exc)
+                  raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+
+                  logger.debug { "di: error in probe condition evaluation failed callback: #{nested_exc.class}: #{nested_exc.message}" }
+                  telemetry&.report(nested_exc, description: "Error in probe condition evaluation failed callback")
+                end
+              else
+                raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+
+                logger.debug { "di: error evaluating condition without context (tracer bug?): #{exc.class}: #{exc.message}" }
+                telemetry&.report(exc, description: "Error evaluating condition without context")
+                # If execution gets here, there is probably a bug in the tracer.
+              end
+
+              continue = false
+            end
+          end
+
+          rate_limiter = probe.rate_limiter
+          admitted = continue && (rate_limiter.nil? || rate_limiter.allow?)
+          if admitted && !probe_global_rate_limiter(probe).allow?
+            admitted = false
+            logger.trace { "di: #{probe.type} probe #{probe.id}: skipping due to global rate limit" }
+          end
+          if admitted
+            # Arguments may be mutated by the method, therefore
+            # they need to be serialized prior to method invocation.
+            serialized_entry_args = if probe.capture_snapshot?
+              serializer.serialize_args(args, kwargs, target_self,
+                **probe.snapshot_serializer_limits(settings))
+            end
+
+            entry_capture_expressions = nil
+            entry_capture_evaluation_errors = nil
+            if probe.capture_entry_expressions?
+              begin
+                entry_context = Context.new(
+                  probe: probe, settings: settings, serializer: serializer,
+                  target_self: target_self,
+                  locals: serializer.combine_args(args, kwargs, target_self),
+                )
+                entry_capture_expressions, entry_capture_evaluation_errors =
+                  capture_expression_evaluator.evaluate(probe, entry_context)
+              rescue Exception => exc # standard:disable Lint/RescueException
+                Datadog::DI.reraise_if_fatal(exc)
+                raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+
+                logger.debug { "di: error evaluating entry-time capture expressions: #{exc.class}: #{exc.message}" }
+                telemetry&.report(exc, description: "Error evaluating entry-time capture expressions")
+              end
+            end
+            # We intentionally do not use Core::Utils::Time.get_time
+            # here because the time provider may be overridden by the
+            # customer, and DI is not allowed to invoke customer code.
+            start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+            di_duration = Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID) - di_start_time
+
+            # Release re-entrancy guard for the original method so that
+            # probes on other methods (or recursive calls) fire normally
+            # during user code execution.
+            DI.leave_probe
+
+            rv = nil
+            begin
+              # yield invokes the super block without dispatching Proc#call,
+              # so a user probe on Proc#call cannot intercept the trampoline.
+              # The guard was just released above so nested probes on the
+              # customer method body fire normally — but Proc#call must
+              # remain bypassed regardless, because the disabled-probe early
+              # return at the top of this method also invokes the block.
+              rv = yield
+            rescue Exception => exc # standard:disable Lint/RescueException
+              Datadog::DI.reraise_if_fatal(exc)
+              # We will raise the (non-fatal) exception captured here later,
+              # after the instrumentation callback runs.
+            end
+
+            # Re-acquire re-entrancy guard for DI post-processing
+            # (building context, notification callback).
+            DI.enter_probe
+
+            end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            duration = end_time - start_time
+
+            # Restart DI timer.
+            # The DI execution duration covers time spent in DI code before
+            # the customer method is invoked and time spent in DI code
+            # after the customer method finishes.
+            di_start_time = Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID)
+
+            # The method itself is not part of the stack trace because
+            # we are getting the stack trace from outside of the method.
+            # Add the method in manually as the top frame.
+            method_frame = if loc
+              [Location.new(loc.first, loc.last, method_name)]
+            else
+              # For virtual and lazily-defined methods, we do not have
+              # the original source location here, and they won't be
+              # included in the stack trace currently.
+              # TODO when begin/end trace points are added for local
+              # variable capture in method probes, we should be able
+              # to obtain actual method execution location and use
+              # that location here.
+              []
+            end
+            # depth 2 skips run_method_probe and the wrapper define_method
+            # block, leaving the user's call site as the first returned frame.
+            # caller_locations is RBS-nilable but never nil at this depth.
+            caller_locs = method_frame + (caller_locations(2) || [])
+            # TODO capture arguments at exit
+
+            capture_expression_locals = if probe.capture_expressions_only?
+              serializer.combine_args(args, kwargs, target_self)
+            end
+            context = Context.new(locals: capture_expression_locals, target_self: target_self,
+              probe: probe, settings: settings, serializer: serializer,
+              serialized_entry_args: serialized_entry_args,
+              entry_capture_expressions: entry_capture_expressions,
+              entry_capture_evaluation_errors: entry_capture_evaluation_errors,
+              caller_locations: caller_locs,
+              return_value: rv, duration: duration, exception: exc,)
+
+            begin
+              responder.probe_executed_callback(context)
+
+              check_and_disable_if_exceeded(probe, responder, di_start_time, di_duration)
+            rescue Exception => di_exc # standard:disable Lint/RescueException
+              Datadog::DI.reraise_if_fatal(di_exc)
+              raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+
+              logger.debug { "di: unhandled exception in method probe: #{di_exc.class}: #{di_exc.message}" }
+              telemetry&.report(di_exc, description: "Unhandled exception in method probe")
+            end
+
+            if exc
+              raise exc
+            else
+              rv
+            end
+          else
+            # Condition not satisfied or rate-limited: skip DI processing
+            # and call super. (The disabled-probe case is handled by the
+            # early return at the top of this method, so it never reaches
+            # this branch.)
+            #
+            # The guard must be released here (not relied on the ensure)
+            # because the super block invokes the customer's method, which
+            # may call other probed methods. Those nested probes should fire
+            # normally — they would not if the guard were still set,
+            # because the wrapper's early-return short-circuits when
+            # DI.in_probe? is true.
+            #
+            # No post-processing in this branch, so we don't re-acquire
+            # the guard after super. The ensure's leave_probe below is
+            # a no-op here (guard already cleared) and serves the
+            # firing branch above, where post-processing re-enters.
+            DI.leave_probe
+            # yield bypasses Proc#call dispatch — see the firing branch
+            # above for the same rationale.
+            yield
+          end
+        ensure
+          DI.leave_probe
+        end
+      end
+      # `run_method_probe` is documentation-private (`# @api private`) but must
+      # be lexically public so that the prepended wrapper can call it without
+      # `.send`. The wrapper hot path is reached when a probed customer method
+      # is invoked, and a customer probe on `Object#send` / `Kernel#send`
+      # would intercept any `.send` call before the wrapper had a chance to
+      # set the re-entrancy guard, causing infinite recursion. Calling the
+      # method directly avoids `Object#send` dispatch entirely.
+      public :run_method_probe
+
+      # Splits a Ruby < 3 splat-captured argument list into positional
+      # arguments and the trailing keyword-argument hash, for argument
+      # serialization only. Returns `[positional_args, kwargs]`. Forwarding
+      # does not use this — the wrapper's do_super replays the original
+      # splat so the trailing hash keeps its keyword identity.
+      #
+      # A trailing hash is treated as keyword arguments regardless of how it
+      # was passed at the call site, matching the previous `**kwargs`
+      # capture (which, on Ruby 2.x, absorbed a trailing hash into kwargs).
+      # The ruby2_keywords flag is intentionally not consulted here: callers
+      # that pass a hash positionally (e.g. `m(opts)`) still expect it shown
+      # as a keyword argument, consistent with Ruby 2.x serialization.
+      #
+      # The trailing-element test goes through DI.hash? (a C type check)
+      # rather than `last.is_a?(Hash)`: kwargs_from_splat runs before the
+      # re-entrancy guard is set, so a customer method probe on Kernel#is_a?
+      # would otherwise re-enter the wrapper and recurse. DI.hash? is a
+      # singleton method and cannot be targeted by a method probe.
+      #
+      # Defined only on Ruby < 3; the Ruby 3+ wrapper captures keyword
+      # arguments directly and never calls this.
+      if RubyVersion.is?("< 3")
+        def kwargs_from_splat(args)
+          last = args.last
+          if DI.hash?(last)
+            [args[0...-1] || [], last]
+          else
+            [args, {}]
+          end
+        end
+        # Lexically public for the same reason as #run_method_probe: the
+        # prepended wrapper must call it without `.send`, which a customer
+        # probe on Object#send could intercept.
+        public :kwargs_from_splat
+      end
+
+      def line_trace_point_callback(probe, iseq, responder, tp)
+        di_start_time = Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID)
+
+        # Check if probe is enabled before doing any processing
+        return unless probe.enabled?
+
+        # If trace point is not targeted, we must verify that the invocation
+        # is the file & line that we want, because untargeted trace points
+        # are invoked for *each* line of Ruby executed.
+        # TODO find out exactly when the path in trace point is relative.
+        # Looks like this is the case when line trace point is not targeted?
+        unless iseq
+          return unless tp.lineno == probe.line_no && ( # standard:disable Style/UnlessLogicalOperators
+            probe.file == tp.path || probe.file_matches?(tp.path)
+          )
+        end
+
+        # We set the trace point on :return to be able to instrument
+        # 'end' lines. This also causes the trace point to be invoked on
+        # non-'end' lines when a line raises an exception, since the
+        # exception causes the method to stop executing and stack unwends.
+        # We do not want two invocations of the trace point.
+        # Therefore, if a trace point is invoked with a :line event,
+        # mark it as such and ignore subsequent :return events.
+        if probe.executed_on_line?
+          return unless tp.event == :line
+        else
+          _ = 42 # stop standard from changing this code
+
+          if tp.event == :line
+            probe.executed_on_line!
+          end
+        end
+
+        if condition = probe.condition
+          begin
+            context = build_trace_point_context(probe, tp)
+            return unless condition.satisfied?(context)
+          rescue Exception => exc # standard:disable Lint/RescueException
+            Datadog::DI.reraise_if_fatal(exc)
+            # Evaluation error exception can be raised for "expected"
+            # errors, we probably need another setting to control whether
+            # these exceptions are propagated.
+            raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions &&
+              !exc.is_a?(DI::Error::ExpressionEvaluationError)
+
+            if context
+              # We want to report evaluation errors for conditions
+              # as probe snapshots. However, if we failed to create
+              # the context, we won't be able to report anything as
+              # the probe notifier builder requires a context.
+              begin
+                responder.probe_condition_evaluation_failed_callback(context, condition, exc)
+              rescue Exception => nested_exc # standard:disable Lint/RescueException
+                Datadog::DI.reraise_if_fatal(nested_exc)
+                raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+
+                logger.debug { "di: error in probe condition evaluation failed callback: #{nested_exc.class}: #{nested_exc.message}" }
+                telemetry&.report(nested_exc, description: "Error in probe condition evaluation failed callback")
+              end
+
+              return
+            else
+              _ = 42 # stop standard from wrecking this code
+
+              raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+
+              logger.debug { "di: error evaluating condition without context (tracer bug?): #{exc.class}: #{exc.message}" }
+              telemetry&.report(exc, description: "Error evaluating condition without context")
+              # If execution gets here, there is probably a bug in the tracer.
+            end
+          end
+        end
+
+        # In practice we should always have a rate limiter, but be safe
+        # and check that it is in fact set.
+        return if probe.rate_limiter && !probe.rate_limiter.allow?
+
+        unless probe_global_rate_limiter(probe).allow?
+          logger.trace { "di: #{probe.type} probe #{probe.id}: skipping due to global rate limit" }
+          return
+        end
+
+        # The context creation is relatively expensive and we don't
+        # want to run it if the callback won't be executed due to the
+        # rate limit.
+        # Thus the copy-paste of the creation call here.
+        context ||= build_trace_point_context(probe, tp)
+
+        responder.probe_executed_callback(context)
+
+        check_and_disable_if_exceeded(probe, responder, di_start_time)
+      rescue Exception => exc # standard:disable Lint/RescueException
+        Datadog::DI.reraise_if_fatal(exc)
+        raise if settings.dynamic_instrumentation.internal.propagate_all_exceptions
+        logger.debug { "di: unhandled exception in line trace point: #{exc.class}: #{exc.message}" }
+        telemetry&.report(exc, description: "Unhandled exception in line trace point")
+        # TODO test this path
+      end
+
+      def build_trace_point_context(probe, tp)
+        stack = caller_locations
+        # We have two helper methods being invoked from the trace point
+        # handler block, remove them from the stack.
+        #
+        # According to steep stack may be nil.
+        stack&.shift(2)
+        Context.new(
+          locals: Instrumenter.get_local_variables(tp),
+          target_self: tp.self,
+          probe: probe,
+          settings: settings,
+          serializer: serializer,
+          path: tp.path,
+          caller_locations: stack,
+        )
+      end
+
+      # Circuit breaker: disables the probe if total CPU time consumed by
+      # DI processing exceeds the configured threshold.
+      def check_and_disable_if_exceeded(probe, responder, di_start_time, accumulated_duration = 0.0)
+        return unless max_processing_time = settings.dynamic_instrumentation.internal.max_processing_time
+
+        di_duration = accumulated_duration + Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID) - di_start_time
+        if di_duration > max_processing_time
+          logger.debug { "di: disabling probe: consumed #{di_duration}: #{probe}" }
+          # We disable the probe here rather than remove it to
+          # avoid a dependency on ProbeManager from Instrumenter.
+          probe.disable!
+          responder.probe_disabled_callback(probe, di_duration)
+        end
+      end
+
+      def raise_if_probe_in_loaded_features(probe, line_no, code_tracker)
+        return unless probe.file
+
+        # Find the loaded path matching the probe file. Case-sensitive
+        # matching is attempted first, with case-insensitive matching as a
+        # fallback (see the design comment in utils.rb, steps 5-8). Leading
+        # directory components are stripped so probes whose sourceFile carries
+        # a source-repo prefix that does not exist on disk still resolve to
+        # the loaded file — matching the behavior of
+        # CodeTracker#iseqs_for_path_suffix.
+        loaded_path = if $LOADED_FEATURES.include?(probe.file)
+          probe.file
+        else
+          # Expensive suffix check.
+          suffix = Utils.normalize_windows_separators(probe.file)
+          found = nil #: ::String?
+          [false, true].each do |case_insensitive|
+            working_suffix = suffix.dup
+            loop do
+              found = $LOADED_FEATURES.find do |path|
+                Utils.path_matches_suffix?(path, working_suffix, case_insensitive: case_insensitive)
+              end
+              break if found
+              break unless working_suffix.include?("/")
+              working_suffix.sub!(%r{.*/+}, "")
+            end
+            break if found
+          end
+          found
+        end
+
+        return unless loaded_path
+
+        # Distinguish between "no iseqs at all" and "has per-method iseqs
+        # but none cover this line".
+        has_per_method = code_tracker&.send(:instance_variable_defined?, :@per_method_registry) &&
+          code_tracker.send(:per_method_registry).key?(loaded_path)
+
+        if code_tracker.nil?
+          raise Error::DITargetNotInRegistry,
+            "File #{loaded_path} is loaded but code tracking is not active; " \
+            "line probes cannot be targeted."
+        elsif has_per_method
+          raise Error::DITargetNotInRegistry,
+            "File #{loaded_path} is loaded and has per-method iseqs, " \
+            "but none cover line #{line_no}. " \
+            "The line may be in file-level setup code outside any method."
+        else
+          raise Error::DITargetNotInRegistry,
+            "File #{loaded_path} is loaded but has no surviving iseqs " \
+            "(whole-file iseq was garbage collected and no per-method iseqs remain). " \
+            "Line probes cannot target this file."
+        end
+      end
+
+      # TODO test that this resolves qualified names e.g. A::B
+      def symbolize_class_name(cls_name)
+        Object.const_get(cls_name) # steep:ignore ArgumentTypeMismatch
+      rescue NameError => exc
+        raise Error::DITargetNotDefined, "Class not defined: #{cls_name}: #{exc.class}: #{exc.message}"
+      end
+
+      # Matches a class name in the Datadog namespace, tolerating the alias
+      # forms that Object.const_get resolves to the same top-level constants.
+      # Two such forms exist: an optional leading "::" (Ruby's root-namespace
+      # prefix), and any number of leading "Object::" segments. Top-level
+      # constants are constants of Object, so "Object::Datadog::DI::Instrumenter"
+      # resolves to Datadog::DI::Instrumenter; without stripping "Object::" a
+      # probe could name a tracer-internal class through an Object:: alias and
+      # bypass the rejection, then get prepended onto tracer internals. These
+      # are the only alias paths to the top-level Datadog: "Foo::Datadog" does
+      # not resolve through const_get for an arbitrary Foo. Anchored at \A so
+      # the match decides in O(prefix length) without scanning.
+      DATADOG_NAMESPACE_TYPE_NAME = /\A(?:::)?(?:Object::)*Datadog(?:::|\z)/
+      private_constant :DATADOG_NAMESPACE_TYPE_NAME
+
+      # Returns true when +cls_name+ names the +Datadog+ module itself or
+      # any class/module under it (e.g. +Datadog::Tracing::SpanOperation+).
+      # The check is purely textual on the probe's declared type name; it
+      # does not require the class to be loaded. A leading +::+ and any
+      # number of leading +Object::+ segments are treated the same as the
+      # bare form, since Object.const_get resolves those aliases to the same
+      # top-level constants.
+      def datadog_namespace_type_name?(cls_name)
+        DATADOG_NAMESPACE_TYPE_NAME.match?(cls_name)
+      end
+    end
+  end
+end
+
+# rubocop:enable Lint/AssignmentInCondition
+# rubocop:enable Style/AndOr