di

lib/datadog/di/instrumenter.rb

@@ -7,30 +7,25 @@ module DI
     # Arranges to invoke a callback when a particular Ruby method or
     # line of code is executed.
     #
-    # The method hooking is currently accomplished via method aliasing.
-    # Unlike the traditional alias_method_chain pattern, the original
-    # method is stored in a local variable and is thus not leaking out.
-    # This should also prevent possible issues with infinite loops
-    # when the original or the aliased method is called incorrerctly
-    # due to conflicting aliasing happening.
+    # 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).
     #
     # Note that only explicitly defined methods can be hooked, e.g. if a
     # class has a +method_missing+ method that provides further virtual
     # methods, the hooking must be done on the +method_missing+ method
     # and not on one of the virtual methods provided by it.
     #
-    # Line hooking is currently done with a naive line trace point which
-    # imposes no requirements on the code being instrumented, but carries
-    # a serious performance penalty for the entire running application.
+    # 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.
     #
-    # An alternative line hooking implementation is to use targeted line
-    # trace points. These require all code to be instrumented to have been
-    # loaded after a require trace point is installed to map the loaded
-    # code to its files, and the trace point then targets the particular
-    # code object where the instrumented code is defined.
-    # The targeted trace points rewrites VM instructions to trigger the
-    # trace points on the desired line and otherwise has no performance
-    # impact on the application.
+    # Targeted line trace points require tracking of loaded code; see
+    # the CodeTracker class for more details.
     #
     # @api private
     class Instrumenter