datadog 2.38.0 → 2.47.0

data/lib/datadog/di/code_tracker.rb

@@ -2,8 +2,8 @@
 
 # rubocop:disable Lint/AssignmentInCondition
 
-require_relative 'error'
-require_relative 'fatal_exceptions'
+require_relative "error"
+require_relative "fatal_exceptions"
 
 module Datadog
   module DI
@@ -275,8 +275,8 @@ module Datadog
               if inexact.any?
                 return inexact.first
               end
-              break unless working_suffix.include?('/')
-              working_suffix.sub!(%r{.*/+}, '')
+              break unless working_suffix.include?("/")
+              working_suffix.sub!(%r{.*/+}, "")
             end
           end
           nil
@@ -393,8 +393,8 @@ module Datadog
             matches = paths.select { |p| Utils.path_matches_suffix?(p, working_suffix, case_insensitive: case_insensitive) }
             raise Error::MultiplePathsMatch, "Multiple paths matched requested suffix" if matches.length > 1
             return matches.first if matches.any?
-            break unless working_suffix.include?('/')
-            working_suffix.sub!(%r{.*/+}, '')
+            break unless working_suffix.include?("/")
+            working_suffix.sub!(%r{.*/+}, "")
           end
         end
         nil

data/lib/datadog/di/component.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'fatal_exceptions'
+require_relative "fatal_exceptions"
 
 module Datadog
   module DI
@@ -16,6 +16,16 @@ module Datadog
     # resources and installed tracepoints upon shutdown.
     class Component
       class << self
+        # Builds and registers the DI component, or returns nil without
+        # building one when the settings have no dynamic_instrumentation
+        # section, DI is explicitly disabled, the runtime is unsupported,
+        # or Remote Configuration is disabled.
+        #
+        # @param settings [Datadog::Core::Configuration::Settings]
+        # @param agent_settings [Datadog::Core::Configuration::AgentSettings]
+        # @param logger [Core::Logger]
+        # @param telemetry [Core::Telemetry::Component, nil]
+        # @return [Component, nil] the built component, or nil when no component was built
         def build(settings, agent_settings, logger, telemetry: nil)
           return unless settings.respond_to?(:dynamic_instrumentation)
 
@@ -65,40 +75,66 @@ module Datadog
         end
       end
 
+      # Initializes the DI component.
+      #
+      # @param settings [Datadog::Core::Configuration::Settings] tracer settings
+      # @param agent_settings [Datadog::Core::Configuration::AgentSettings] agent connection settings for the transports
+      # @param logger [Datadog::Core::Logger] diagnostics logger, wrapped in the DI logger facade
+      # @param code_tracker [CodeTracker, nil] code tracker for line probe installation
+      # @param telemetry [Datadog::Core::Telemetry::Component, nil] component DI errors and guardrails metrics are emitted through
+      # @return [void]
       def initialize(settings, agent_settings, logger, code_tracker: nil, telemetry: nil)
         @settings = settings
         @agent_settings = agent_settings
         logger = DI::Logger.new(settings, logger)
         @logger = logger
         @telemetry = telemetry
+        @guardrails_telemetry = GuardrailsTelemetry.new(settings: settings, logger: logger, telemetry: telemetry)
         @code_tracker = code_tracker
         @redactor = Redactor.new(settings)
-        @serializer = Serializer.new(settings, redactor, telemetry: telemetry)
-        @instrumenter = Instrumenter.new(settings, serializer, logger, code_tracker: code_tracker, telemetry: telemetry)
+        @serializer = Serializer.new(settings, redactor, logger: logger,
+          guardrails_telemetry: guardrails_telemetry, telemetry: telemetry)
+        @capture_expression_evaluator = CaptureExpressionEvaluator.new(
+          settings: settings, serializer: serializer, logger: logger,
+          guardrails_telemetry: guardrails_telemetry, telemetry: telemetry,
+        )
+        @instrumenter = Instrumenter.new(settings, serializer, logger, code_tracker: code_tracker, telemetry: telemetry,
+          guardrails_telemetry: guardrails_telemetry,
+          capture_expression_evaluator: capture_expression_evaluator,)
         @probe_repository = ProbeRepository.new
-        @probe_notification_builder = ProbeNotificationBuilder.new(settings, serializer, logger, telemetry: telemetry)
+        @probe_notification_builder = ProbeNotificationBuilder.new(settings, serializer, logger,
+          capture_expression_evaluator: capture_expression_evaluator,)
         @probe_notifier_worker = ProbeNotifierWorker.new(
           settings, logger,
           agent_settings: agent_settings,
           probe_repository: probe_repository,
           probe_notification_builder: probe_notification_builder,
           telemetry: telemetry,
+          guardrails_telemetry: guardrails_telemetry,
         )
         @probe_manager = ProbeManager.new(
           settings, instrumenter, probe_notification_builder, probe_notifier_worker, logger, probe_repository,
           telemetry: telemetry,
+          guardrails_telemetry: guardrails_telemetry,
         )
         # @started transitions are serialized by @lifecycle_mutex so that
         # concurrent RC callbacks (which run on the remote-config thread)
         # cannot race a foreground start! with a background stop!.
         @lifecycle_mutex = Mutex.new
         @started = false
+        @rc_enablement_signal_paths = []
       end
 
       attr_reader :settings
       attr_reader :agent_settings
       attr_reader :logger
       attr_reader :telemetry
+      # The guardrails metric emitter.
+      # @return [GuardrailsTelemetry]
+      attr_reader :guardrails_telemetry
+      # The capture expression evaluator.
+      # @return [CaptureExpressionEvaluator]
+      attr_reader :capture_expression_evaluator
       attr_reader :code_tracker
       attr_reader :instrumenter
       attr_reader :probe_repository
@@ -123,6 +159,14 @@ module Datadog
         @lifecycle_mutex.synchronize do
           return if @started
 
+          # DI.activate_tracking creates the global code tracker lazily. When DI
+          # is enabled after boot via remote configuration (in-product
+          # enablement), this component and its instrumenter were built with a
+          # nil tracker; adopt the now-current global tracker so line probes
+          # can be targeted.
+          @code_tracker = DI.code_tracker
+          instrumenter.code_tracker = @code_tracker
+
           probe_notifier_worker.start
           probe_manager.reopen
           @started = true
@@ -158,6 +202,75 @@ module Datadog
         @started
       end
 
+      # Whether the component is started while the customer left
+      # DD_DYNAMIC_INSTRUMENTATION_ENABLED at its default, the state produced
+      # by remote-configuration enablement.
+      #
+      # An explicit `enabled = false` takes precedence over a prior RC
+      # enablement: once the customer sets the option, this returns false
+      # even while the component is still started.
+      #
+      # @return [Boolean]
+      def implicitly_enabled?
+        started? && settings.dynamic_instrumentation.using_default?(:enabled)
+      end
+
+      # Whether an APM_TRACING merge that omitted dynamic_instrumentation_enabled
+      # withdraws this component's RC enable signal, so the component must stop.
+      #
+      # Returns true when the component is implicitly enabled and no unparseable
+      # content can be the signal carrier. A content at a recorded signal path can be
+      # the carrier. When no paths are recorded, every unparseable content can be the
+      # carrier.
+      #
+      # @param unparseable_contents [Array<Core::Remote::Configuration::Content>] the APM_TRACING contents that failed to parse at this merge
+      # @return [Boolean]
+      def rc_enablement_signal_withdrawn?(unparseable_contents)
+        return false unless implicitly_enabled?
+
+        recorded_signal_paths = rc_enablement_signal_paths
+        signal_source_unparseable =
+          if recorded_signal_paths.empty?
+            unparseable_contents.any?
+          else
+            unparseable_contents.any? { |content| recorded_signal_paths.include?(content.path) }
+          end
+        if signal_source_unparseable
+          if recorded_signal_paths.empty?
+            logger.trace do
+              "APM_TRACING RC: dynamic_instrumentation_enabled absent while an APM_TRACING config " \
+              "failed to parse; the enable signal carrier is unknown (no signal paths recorded), " \
+              "keeping the DI state"
+            end
+          else
+            logger.trace do
+              "APM_TRACING RC: dynamic_instrumentation_enabled absent while the config that carried " \
+              "the enable signal failed to parse; keeping the DI state"
+            end
+          end
+          false
+        else
+          logger.trace { "APM_TRACING RC: dynamic_instrumentation_enabled withdrawn; treating as false" }
+          true
+        end
+      end
+
+      # The repository paths of the APM_TRACING contents that supplied the
+      # dynamic_instrumentation_enabled value at the last merge where the field was
+      # present. The component holds the paths so that they outlive the RC client.
+      #
+      # @return [Array<Core::Remote::Configuration::Path>]
+      attr_reader :rc_enablement_signal_paths
+
+      # Replaces the recorded enable-signal carrier paths.
+      #
+      # @param paths [Array<Core::Remote::Configuration::Path>] the carrier paths, empty when the merged field was absent
+      # @return [void]
+      def record_rc_enablement_signal_paths(paths)
+        @rc_enablement_signal_paths = paths.dup
+        nil
+      end
+
       # Shuts down dynamic instrumentation permanently.
       #
       # Removes all code hooks and stops background threads.
@@ -190,14 +303,14 @@ module Datadog
         Datadog::DI.reraise_if_fatal(exc)
         begin
           probe = Struct.new(:id).new(
-            probe_spec['id'],
+            probe_spec["id"],
           )
           payload = probe_notification_builder.build_errored(probe, exc)
           probe_notifier_worker.add_status(payload)
         rescue Exception => nested_exc # standard:disable Lint/RescueException
           Datadog::DI.reraise_if_fatal(nested_exc)
           logger.debug { "di: failed to build error notification: #{nested_exc.class}: #{nested_exc.message}" }
-          telemetry&.report(nested_exc, description: 'Error building probe error notification')
+          telemetry&.report(nested_exc, description: "Error building probe error notification")
           raise
         end
 

data/lib/datadog/di/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../core/configuration/stable_config"
+
 module Datadog
   module DI
     # Configuration for DI
@@ -136,8 +138,35 @@ module Datadog
 
               option :max_time_to_serialize_ms do |o|
                 o.type :int
-                o.default 200
-                o.env 'DD_DYNAMIC_INSTRUMENTATION_MAX_TIME_TO_SERIALIZE'
+                o.env "DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS"
+                o.default do
+                  legacy = Settings.legacy_capture_timeout_value
+                  if legacy
+                    Datadog::Core.log_deprecation(key: :di_legacy_max_time_to_serialize) do
+                      "The DD_DYNAMIC_INSTRUMENTATION_MAX_TIME_TO_SERIALIZE environment variable is deprecated " \
+                      "and will be removed in a future release. " \
+                      "Please use DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS instead."
+                    end
+
+                    begin
+                      Integer(legacy, 10)
+                    rescue ArgumentError
+                      raise ArgumentError,
+                        "Expected environment variable DD_DYNAMIC_INSTRUMENTATION_MAX_TIME_TO_SERIALIZE " \
+                        "to be an int, but '#{legacy}' was provided."
+                    end
+                  else
+                    150
+                  end
+                end
+                o.setter do |value, _old|
+                  if value < 0
+                    raise ArgumentError,
+                      "The setting `dynamic_instrumentation.max_time_to_serialize_ms` must not be negative, " \
+                      "but `#{value.inspect}` was provided."
+                  end
+                  value
+                end
               end
 
               # Settings in the 'internal' group are for internal Datadog
@@ -229,7 +258,7 @@ module Datadog
                   # dedicated environment variable in the future but
                   # will likely need a way to turn on remote config
                   # debugging (since DI uses RC for configuration).
-                  o.env 'DD_TRACE_DEBUG'
+                  o.env "DD_TRACE_DEBUG"
                 end
 
                 # If the CPU time consumed by the thread performing instrumentation
@@ -244,6 +273,28 @@ module Datadog
             end
           end
         end
+
+        # Resolves the deprecated capture-timeout name for the setting's
+        # default. The legacy value applies only when the canonical variable
+        # is configured nowhere (environment with its registry alias, local or
+        # fleet stable configuration), and the legacy itself resolves in the
+        # option machinery's precedence order: fleet stable configuration,
+        # environment, local stable configuration.
+        def self.legacy_capture_timeout_value
+          canonical_name = "DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS"
+          legacy_name = "DD_DYNAMIC_INSTRUMENTATION_MAX_TIME_TO_SERIALIZE"
+
+          stable = Datadog::Core::Configuration::StableConfig.configuration
+          local = stable&.dig(:local, :config)
+          fleet = stable&.dig(:fleet, :config)
+
+          canonical = (fleet && DATADOG_ENV.get_environment_variable(canonical_name, source_env: fleet)) ||
+            DATADOG_ENV[canonical_name] ||
+            (local && DATADOG_ENV.get_environment_variable(canonical_name, source_env: local))
+          return nil if canonical
+
+          (fleet && fleet[legacy_name]) || DATADOG_ENV[legacy_name] || (local && local[legacy_name])
+        end
       end
     end
   end

data/lib/datadog/di/context.rb

@@ -61,9 +61,14 @@ module Datadog
       # Exception raised by the method, if any, for a method probe
       attr_reader :exception
 
-      def serialized_locals
+      # Returns the locals captured at the probe hit in serialized form,
+      # or nil when no locals were captured.
+      #
+      # @param serialization_deadline [Float] absolute capture deadline in monotonic clock seconds
+      # @return [Hash{Symbol => Hash}, nil] serialized locals keyed by variable name
+      def serialized_locals(serialization_deadline:)
         # TODO cache?
-        locals && serializer.serialize_vars(locals, **probe.snapshot_serializer_limits(settings))
+        locals && serializer.serialize_vars(locals, deadline: serialization_deadline, **probe.snapshot_serializer_limits(settings))
       end
 
       def fetch(var_name)

data/lib/datadog/di/contrib/active_record.rb

@@ -10,7 +10,7 @@ Datadog::DI::Serializer.register(
   # logic for "instances of classes derived from X", but a condition Proc
   # is more universal.
   condition: lambda { |value| ActiveRecord::Base === value }
-) do |serializer, value, name:, depth:|
+) do |serializer, value, name:, depth:, deadline:|
   # +serializer+ is an instance of DI::Serializer.
   # Use it to perform the serialization to primitive values.
   #
@@ -30,12 +30,18 @@ Datadog::DI::Serializer.register(
   # nesting levels in the output.
   # This serializer could also potentially do its own depth limiting.
   #
+  # +deadline+ is the absolute monotonic-clock deadline (in seconds) of the
+  # capture point that is being serialized. Pass it through to
+  # +serialize_value+ so the custom-serialized subtree draws down the same
+  # capture budget as the rest of the snapshot.
+  #
   # Steep: steep thinks all of the arguments are nil here
   # Looks like it cannot handle kwargs in lambdas
   # @type var depth: Integer
+  # @type var deadline: Float
   value_to_serialize = {
     attributes: value.attributes,
     new_record: value.new_record?,
   }
-  serializer.serialize_value(value_to_serialize, depth: depth, type: value.class)
+  serializer.serialize_value(value_to_serialize, depth: depth, type: value.class, deadline: deadline)
 end

data/lib/datadog/di/contrib/railtie.rb

@@ -6,7 +6,7 @@ module Datadog
       # Railtie class initializes dynamic instrumentation contrib code
       # in Rails environments.
       class Railtie < Rails::Railtie
-        initializer 'datadog.dynamic_instrumentation.initialize' do |app|
+        initializer "datadog.dynamic_instrumentation.initialize" do |app|
           Contrib.load_now
         end
       end

data/lib/datadog/di/contrib.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-require_relative '../core/contrib/rails/utils'
+require_relative "../core/contrib/rails/utils"
 
 module Datadog
   module DI
     module Contrib
       module_function def load_now_or_later
         if Datadog::Core::Contrib::Rails::Utils.railtie_supported?
-          Datadog.logger.debug('di: loading contrib/railtie')
-          require_relative 'contrib/railtie'
+          Datadog.logger.debug("di: loading contrib/railtie")
+          require_relative "contrib/railtie"
         else
           load_now
         end
@@ -19,8 +19,8 @@ module Datadog
       # dependencies are loaded (or potentially loaded).
       module_function def load_now
         if defined?(ActiveRecord::Base)
-          Datadog.logger.debug('di: loading contrib/active_record')
-          require_relative 'contrib/active_record'
+          Datadog.logger.debug("di: loading contrib/active_record")
+          require_relative "contrib/active_record"
         end
       end
     end

data/lib/datadog/di/el/compiler.rb

@@ -16,20 +16,54 @@ module Datadog
       #
       # @api private
       class Compiler
+        # Compiles +ast+ into eval'able Ruby source.
+        #
+        # Returns the compiled source and companion compiled Regexp
+        # objects.
+        #
+        # @param ast [untyped] expression AST from the probe definition.
+        # @return [Array(String, Array<Regexp>)] the compiled Ruby source and
+        #   the precompiled Regexps, indexed in the order the compiled code
+        #   references them.
         def compile(ast)
-          compile_partial(ast)
+          regexps = []
+          code = compile_partial(ast, regexps)
+          [code, regexps]
+        end
+
+        # Returns the identifier that +ast+ directly references at its top
+        # level, so the message path can redact direct references the same
+        # way snapshots redact by name.
+        #
+        # @param ast [untyped] top-level expression AST from a probe definition.
+        # @return [String, nil] the variable name for a `ref`/`iref`, the field
+        #   name for a `getmember`, or the string key for an `index`; nil when
+        #   the top-level expression is not a direct reference.
+        def redaction_identifier(ast)
+          return nil unless Hash === ast && ast.length == 1
+
+          entry = ast.first
+          return nil if entry.nil?
+
+          op, target = entry
+          case op
+          when "ref"
+            target if String === target
+          when "getmember", "index"
+            target[1] if Array === target && target.length == 2 && String === target[1]
+          end
         end
 
         private
 
         # Steep: https://github.com/soutaro/steep/issues/363
         OPERATORS = { # steep:ignore IncompatibleAssignment
-          'eq' => '==',
-          'ne' => '!=',
-          'ge' => '>=',
-          'gt' => '>',
-          'le' => '<=',
-          'lt' => '<',
+          "eq" => "==",
+          "ne" => "!=",
+          "ge" => ">=",
+          "gt" => ">",
+          "le" => "<=",
+          "lt" => "<",
         }.freeze
 
         # Steep: https://github.com/soutaro/steep/issues/363
@@ -37,49 +71,58 @@ module Datadog
           len isEmpty isUndefined
         ].freeze # steep:ignore IncompatibleAssignment
 
+        # `matches` is also a two-argument method but is special-cased in
+        # #compile_partial so that regular expressions can be precompiled
+        # once, so it is not listed here.
+        #
         # Steep: https://github.com/soutaro/steep/issues/363
         TWO_ARG_METHODS = %w[
-          startsWith endsWith contains matches
+          startsWith endsWith contains
           getmember index instanceof
         ].freeze # steep:ignore IncompatibleAssignment
 
         # Steep: https://github.com/soutaro/steep/issues/363
         MULTI_ARG_METHODS = { # steep:ignore IncompatibleAssignment
-          'and' => '&&',
-          'or' => '||',
+          "and" => "&&",
+          "or" => "||",
         }.freeze
 
-        def compile_partial(ast)
+        # @param ast [untyped] AST node to compile.
+        # @param regexps [Array<Regexp>] output array that collects the
+        #   companion precompiled Regexp objects.
+        # @return [String] compiled Ruby source for +ast+.
+        def compile_partial(ast, regexps)
           case ast
           when Hash
-            if ast.length != 1
+            entry = ast.first
+            if ast.length != 1 || entry.nil?
               raise DI::Error::InvalidExpression, "Expected hash of length 1: #{ast}"
             end
-            op, target = ast.first
+            op, target = entry
             case op
-            when 'ref'
+            when "ref"
               unless String === target
                 raise DI::Error::InvalidExpression, "Bad ref value type: #{target.class}: #{target}"
               end
               case target
-              when '@it'
-                'current_item'
-              when '@key'
-                'current_key'
-              when '@value'
-                'current_value'
-              when '@return'
+              when "@it"
+                "current_item"
+              when "@key"
+                "current_key"
+              when "@value"
+                "current_value"
+              when "@return"
                 # For @return, @duration and @exception we shadow
                 # instance variables.
                 "context.return_value"
-              when '@duration'
+              when "@duration"
                 # There is no way to explicitly format the duration.
                 # TODO come up with better formatting?
                 # We could format to a string here but what if customer
                 # has @duration as part of an expression and wants
                 # to retain it as a number?
                 "(context.duration && context.duration * 1000)"
-              when '@exception'
+              when "@exception"
                 "context.exception"
               else
                 # Ruby technically allows all kinds of symbols in variable
@@ -89,44 +132,60 @@ module Datadog
                 unless target =~ %r{\A(@?)([a-zA-Z0-9_]+)\z}
                   raise DI::Error::BadVariableName, "Bad variable name: #{target}"
                 end
-                method_name = (($1 == '@') ? 'iref' : 'ref')
+                method_name = (($1 == "@") ? "iref" : "ref")
                 "#{method_name}('#{target}')"
               end
             when *SINGLE_ARG_METHODS
               method_name = op.gsub(/[A-Z]/) { |m| "_#{m.downcase}" }
-              "#{method_name}(#{compile_partial(target)}, '#{var_name_maybe(target)}')"
+              "#{method_name}(#{compile_partial(target, regexps)}, '#{var_name_maybe(target)}')"
+            when "matches"
+              unless Array === target && target.length == 2
+                raise DI::Error::InvalidExpression, "Improper matches syntax"
+              end
+              first, second = target
+              if String === second
+                # Match against a literal regular expression (string).
+                index = precompile_regexp(second, regexps)
+                "matches_compiled(#{compile_partial(first, regexps)}, #{index})"
+              else
+                # Match against a (complex) expression.
+                "matches(#{compile_partial(first, regexps)}, (#{compile_partial(second, regexps)}))"
+              end
             when *TWO_ARG_METHODS
               method_name = op.gsub(/[A-Z]/) { |m| "_#{m.downcase}" }
               unless Array === target && target.length == 2
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
               first, second = target
-              "#{method_name}(#{compile_partial(first)}, (#{compile_partial(second)}))"
+              "#{method_name}(#{compile_partial(first, regexps)}, (#{compile_partial(second, regexps)}))"
             when *MULTI_ARG_METHODS.keys
               unless Array === target && target.length >= 1
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
               compiled_targets = target.map do |item|
-                "(#{compile_partial(item)})"
+                "(#{compile_partial(item, regexps)})"
               end
               compiled_op = MULTI_ARG_METHODS[op]
               "(#{compiled_targets.join(" #{compiled_op} ")})"
-            when 'substring'
+            when "substring"
               unless Array === target && target.length == 3
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
-              "#{op}(#{target.map { |arg| "(#{compile_partial(arg)})" }.join(", ")})"
-            when 'not'
-              "!(#{compile_partial(target)})"
+              "#{op}(#{target.map { |arg| "(#{compile_partial(arg, regexps)})" }.join(", ")})"
+            when "not"
+              "!(#{compile_partial(target, regexps)})"
             when *OPERATORS.keys
               unless Array === target && target.length == 2
                 raise DI::Error::InvalidExpression, "Improper #{op} syntax"
               end
               first, second = target
               operator = OPERATORS.fetch(op)
-              "(#{compile_partial(first)}) #{operator} (#{compile_partial(second)})"
-            when 'any', 'all', 'filter'
-              "#{op}(#{compile_partial(target.first)}) { |current_item, current_key, current_value| #{compile_partial(target.last)} }"
+              "(#{compile_partial(first, regexps)}) #{operator} (#{compile_partial(second, regexps)})"
+            when "any", "all", "filter"
+              unless Array === target && target.length == 2
+                raise DI::Error::InvalidExpression, "Improper #{op} syntax"
+              end
+              "#{op}(#{compile_partial(target.first, regexps)}) { |current_item, current_key, current_value| #{compile_partial(target.last, regexps)} }"
             else
               raise DI::Error::InvalidExpression, "Unknown operation: #{op}"
             end
@@ -151,16 +210,33 @@ module Datadog
         # WARNING: the result of this method is included in eval'd code,
         # it must be sanitized to avoid injection.
         def var_name_maybe(target)
-          if Hash === target && target.length == 1 && target.keys.first == 'ref' &&
+          if Hash === target && target.length == 1 && target.keys.first == "ref" &&
               String === (value = target.values.first)
             escape(value)
           else
-            '(expression)'
+            "(expression)"
           end
         end
 
         def escape(needle)
-          needle.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub('#') { "\\#" }
+          needle.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("#") { "\\#" }
+        end
+
+        # Compile a literal regular expression +regexp_str+ at
+        # instrumentation time. Append it to +regexps+, returning its index for
+        # Evaluator#matches_compiled to look up.
+        #
+        # @param regexp_str [String] regular expression source.
+        # @param regexps [Array<Regexp>] output array to append the compiled
+        #   regexp to.
+        # @return [Integer] index into +regexps+.
+        # @raise [DI::Error::InvalidExpression] if +needle+ is not a valid regexp.
+        def precompile_regexp(regexp_str, regexps)
+          index = regexps.length
+          regexps << Evaluator.compile_regexp(regexp_str)
+          index
+        rescue RegexpError => exc
+          raise DI::Error::InvalidExpression, "Invalid regular expression in matches: #{exc.class}: #{exc.message}"
         end
       end
     end