datadog 2.8.0 → 2.39.0

data/lib/datadog/di.rb

@@ -1,111 +1,163 @@
 # frozen_string_literal: true
 
-require_relative 'di/error'
-require_relative 'di/code_tracker'
-require_relative 'di/component'
-require_relative 'di/configuration'
-require_relative 'di/extensions'
-require_relative 'di/instrumenter'
-require_relative 'di/probe'
-require_relative 'di/probe_builder'
-require_relative 'di/probe_manager'
-require_relative 'di/probe_notification_builder'
-require_relative 'di/probe_notifier_worker'
-require_relative 'di/redactor'
-require_relative 'di/remote'
-require_relative 'di/serializer'
-require_relative 'di/transport'
-require_relative 'di/utils'
-
-if defined?(ActiveRecord::Base)
-  # The third-party library integrations need to be loaded after the
-  # third-party libraries are loaded. Tracing and appsec use Railtie
-  # to delay integrations until all of the application's dependencies
-  # are loaded, when running under Rails. We should do the same here in
-  # principle, however DI currently only has an ActiveRecord integration
-  # and AR should be loaded before any application code is loaded, being
-  # part of Rails, therefore for now we should be OK to just require the
-  # AR integration from here.
-  #
-  # TODO this require might need to be delayed via Rails post-initialization
-  # logic?
-  require_relative 'di/contrib/active_record'
-end
+require_relative "di/configuration"
+require_relative "di/extensions"
+require_relative "di/remote"
 
 module Datadog
   # Namespace for Datadog dynamic instrumentation.
   #
   # @api private
   module DI
+    INSTRUMENTED_COUNTERS_LOCK = Mutex.new
+
+    # Captured at load time from Exception itself (not a subclass).
+    # Used to bypass subclass overrides of backtrace_locations.
+    #
+    # This does NOT protect against monkeypatching Exception#backtrace_locations
+    # before dd-trace-rb loads — in that case we'd capture the monkeypatch.
+    # The practical threat model is customer subclasses overriding the method:
+    #
+    #   class MyError < StandardError
+    #     def backtrace_locations; []; end
+    #   end
+    #
+    # The UnboundMethod bypasses subclass overrides: bind(exception).call
+    # always dispatches to the original Exception implementation.
+    #
+    # Note: if the subclass overrides #backtrace (not #backtrace_locations),
+    # MRI's setup_exception skips storing the VM backtrace entirely — both
+    # @bt and @bt_locations stay nil. In that case this UnboundMethod also
+    # returns nil. See EXCEPTION_BACKTRACE comment for details.
+    EXCEPTION_BACKTRACE_LOCATIONS = Exception.instance_method(:backtrace_locations)
+
+    # Same UnboundMethod trick for Exception#backtrace (Array<String>).
+    # Used as a fallback when backtrace_locations returns nil — which happens
+    # when someone calls Exception#set_backtrace with an Array<String>.
+    #
+    # set_backtrace accepts Array<String> or nil. When called with strings,
+    # it replaces the VM-level backtrace: backtrace returns the new strings,
+    # but backtrace_locations returns nil because the VM cannot reconstruct
+    # Location objects from formatted strings. This occurs in exception
+    # wrapping patterns where a library catches an exception, creates a new
+    # one, and copies the original's string backtrace onto it via
+    # set_backtrace before re-raising.
+    #
+    # Ruby 3.4+ also allows set_backtrace(Array<Location>), which preserves
+    # backtrace_locations — but older Rubies and most existing code use
+    # the string form.
+    #
+    # Like EXCEPTION_BACKTRACE_LOCATIONS, this UnboundMethod bypasses
+    # subclass overrides of #backtrace: bind(exception).call dispatches
+    # to Exception#backtrace regardless of what the subclass defines.
+    #
+    # However, when a subclass overrides #backtrace, MRI's setup_exception
+    # (eval.c) calls the override via rb_get_backtrace during raise. If it
+    # gets a non-nil result, it skips storing the VM backtrace in @bt and
+    # @bt_locations entirely. So the UnboundMethod bypasses the override
+    # at dispatch but reads nil from @bt because the data was never stored.
+    #
+    # This constant is used as a fallback when backtrace_locations returns
+    # nil. In the common set_backtrace-with-strings case, no subclass
+    # override is involved and the fallback works. The only unrecoverable
+    # case: a subclass overrides #backtrace, the exception is raised
+    # normally, and set_backtrace is never called. Both @bt and
+    # @bt_locations are nil — DI reports an empty stacktrace (type and
+    # message are still reported).
+    EXCEPTION_BACKTRACE = Exception.instance_method(:backtrace)
+
     class << self
       def enabled?
         Datadog.configuration.dynamic_instrumentation.enabled
       end
-    end
-
-    # Expose DI to global shared objects
-    Extensions.activate!
-
-    LOCK = Mutex.new
-
-    class << self
-      attr_reader :code_tracker
 
-      # Activates code tracking. Normally this method should be called
-      # when the application starts. If instrumenting third-party code,
-      # code tracking needs to be enabled before the third-party libraries
-      # are loaded. If you definitely will not be instrumenting
-      # third-party libraries, activating tracking after third-party libraries
-      # have been loaded may improve lookup performance.
+      # Returns a human-readable reason why dynamic instrumentation cannot run
+      # under the given settings, or nil if all build-time preconditions are met.
       #
-      # TODO test that activating tracker multiple times preserves
-      # existing mappings in the registry
-      def activate_tracking!
-        (@code_tracker ||= CodeTracker.new).start
-      end
-
-      # Activates code tracking if possible.
+      # Single source of truth for the preconditions checked in
+      # {Component.build} and reported back by {Remote.handle_rc_enablement}
+      # when an implicit enablement signal arrives but the component was not
+      # built at startup. Checks are ordered from most-actionable to
+      # platform-constraint so the most useful reason wins.
       #
-      # This method does nothing if invoked in an environment that does not
-      # implement required trace points for code tracking (MRI Ruby < 2.6,
-      # JRuby) and rescues any exceptions that may be raised by downstream
-      # DI code.
-      def activate_tracking
-        # :script_compiled trace point was added in Ruby 2.6.
-        return unless RUBY_VERSION >= '2.6'
-
-        begin
-          # Activate code tracking by default because line trace points will not work
-          # without it.
-          Datadog::DI.activate_tracking!
-        rescue => exc
-          if defined?(Datadog.logger)
-            Datadog.logger.warn("Failed to activate code tracking for DI: #{exc.class}: #{exc}")
-          else
-            # We do not have Datadog logger potentially because DI code tracker is
-            # being loaded early in application boot process and the rest of datadog
-            # wasn't loaded yet. Output to standard error.
-            warn("Failed to activate code tracking for DI: #{exc.class}: #{exc}")
+      # The settings argument is optional so the helper can be called from
+      # contexts that don't have settings in scope (e.g. the RC handler).
+      #
+      # @param settings [Datadog::Core::Configuration::Settings]
+      # @return [String, nil] reason string or nil when supported
+      def unsupported_reason(settings = Datadog.configuration)
+        # Symmetric to the respond_to?(:remote) guard below: in unusual
+        # configurations (test doubles, partial Settings) the DI namespace
+        # may be absent. Returning a reason here lets callers — most
+        # importantly Remote.handle_rc_enablement — emit the customer-facing
+        # warn instead of raising NoMethodError on the unguarded access at
+        # line 92 (`settings.dynamic_instrumentation.internal.development`).
+        unless settings.respond_to?(:dynamic_instrumentation)
+          return "dynamic instrumentation settings are not available"
+        end
+        unless settings.respond_to?(:remote) && settings.remote.enabled
+          return "Remote Configuration is not enabled. See https://docs.datadoghq.com/agent/remote_config"
+        end
+        unless settings.dynamic_instrumentation.internal.development
+          if Datadog::Core::Environment::Execution.development?
+            return "development environment detected"
           end
         end
+        if (reason = unsupported_platform_reason)
+          return reason
+        end
+        unless respond_to?(:exception_message)
+          return "C extension is not available"
+        end
+        nil
+      end
+
+      # Whether the current Ruby runtime can run dynamic instrumentation:
+      # MRI (CRuby) on Ruby 2.6 or later.
+      #
+      # @return [Boolean]
+      def supported_runtime?
+        unsupported_platform_reason.nil?
       end
 
-      # Deactivates code tracking. In normal usage of DI this method should
-      # never be called, however it is used by DI's test suite to reset
-      # state for individual tests.
+      # Reason the current Ruby runtime cannot run dynamic instrumentation, or
+      # nil when the platform is supported. Single source of truth for the
+      # minimum-runtime definition, shared by {unsupported_reason} (which layers
+      # the settings and C-extension checks on top) and {supported_runtime?}.
       #
-      # Note that deactivating tracking clears out the registry, losing
-      # the ability to look up files that have been loaded into the process
-      # already.
-      def deactivate_tracking!
-        code_tracker&.stop
+      # @return [String, nil]
+      private def unsupported_platform_reason
+        if RUBY_ENGINE != "ruby"
+          "MRI is required, but running on #{RUBY_ENGINE}"
+        elsif Datadog::RubyVersion.is?("< 2.6")
+          "Ruby 2.6+ is required, but running on #{RUBY_VERSION}"
+        end
       end
 
-      # Returns whether code tracking is available.
-      # This method should be used instead of querying #code_tracker
-      # because the latter one may be nil.
-      def code_tracking_active?
-        code_tracker&.active? || false
+      # Returns iseqs that correspond to loaded files (filtering out eval'd code).
+      #
+      # There are several types of iseqs returned by +all_iseqs+:
+      #
+      # 1. Eval'd code — these have a nil +absolute_path+ and are filtered out here.
+      # 2. Whole-file iseqs — have +absolute_path+ set and +first_lineno+ of 0.
+      #    Only available for a subset of loaded files (the full-file iseq may be
+      #    garbage collected after loading completes). Easiest to work with since
+      #    we just match the file path to the probe specification.
+      # 3. Per-method iseqs — have +absolute_path+ set and +first_lineno+ > 0.
+      #    Often the only iseqs available for third-party code. Require identifying
+      #    the correct iseq containing the target line, which may involve examining
+      #    the iseq's +trace_points+ since +define_method+ can create nested,
+      #    non-contiguous line ranges.
+      #
+      # Note: the same line of code can appear in multiple iseqs (e.g. when
+      # +define_method+ is used inside a method). DI treats this as an error
+      # since a probe must resolve to exactly one code location.
+      #
+      # @return [Array<RubyVM::InstructionSequence>] iseqs with non-nil +absolute_path+
+      def file_iseqs
+        all_iseqs.select do |iseq|
+          iseq.absolute_path
+        end
       end
 
       # This method is called from DI Remote handler to issue DI operations
@@ -121,49 +173,64 @@ module Datadog
         Datadog.send(:components).dynamic_instrumentation
       end
 
-      # DI code tracker is instantiated globally before the regular set of
-      # components is created, but the code tracker needs to call out to the
-      # "current" DI component to perform instrumentation when application
-      # code is loaded. Because this call may happen prior to Datadog
-      # components having been initialized, we maintain the "current component"
-      # which contains a reference to the most recently instantiated
-      # DI::Component. This way, if a DI component hasn't been instantiated,
-      # we do not try to reference Datadog.components.
-      def current_component
-        LOCK.synchronize do
-          @current_components&.last
+      # Track how many outstanding instrumentations are in DI.
+      #
+      # It is hard to find the actual instrumentations - there is no
+      # method provided by Ruby to list all trace points, and we would
+      # need to manually track our instrumentation modules for method probes.
+      # Plus, tracking the modules could create active references to
+      # instrumentation, which is not desired.
+      #
+      # A simpler solution is to maintain a counter which is increased
+      # whenever a probe is installed and decreased when a probe is removed.
+      #
+      # This counter does not include pending probes - being not installed,
+      # those pose no concerns to customer applications.
+      def instrumented_count(kind = nil)
+        INSTRUMENTED_COUNTERS_LOCK.synchronize do
+          if defined?(@instrumented_count)
+            if kind
+              validate_kind!(kind)
+              @instrumented_count[kind] || 0
+            else
+              @instrumented_count.inject(0) do |sum, (_kind, count)|
+                sum + count
+              end
+            end
+          else
+            0
+          end
+        end
+      end
+
+      def instrumented_count_inc(kind)
+        validate_kind!(kind)
+        INSTRUMENTED_COUNTERS_LOCK.synchronize do
+          @instrumented_count = Hash.new(0) unless defined?(@instrumented_count)
+          @instrumented_count[kind] += 1
         end
       end
 
-      # To avoid potential races with DI::Component being added and removed,
-      # we maintain a list of the components. Normally the list should contain
-      # either zero or one component depending on whether DI is enabled in
-      # Datadog configuration. However, if a new instance of DI::Component
-      # is created while the previous instance is still running, we are
-      # guaranteed to not end up with no component when one is running.
-      def add_current_component(component)
-        LOCK.synchronize do
-          @current_components ||= []
-          @current_components << component
+      def instrumented_count_dec(kind)
+        validate_kind!(kind)
+        INSTRUMENTED_COUNTERS_LOCK.synchronize do
+          @instrumented_count = Hash.new(0) unless defined?(@instrumented_count)
+          if @instrumented_count[kind] <= 0
+            Datadog.logger.debug { "di: attempting to decrease instrumented count below zero for #{kind}" }
+            return
+          end
+          @instrumented_count[kind] -= 1
         end
       end
 
-      def remove_current_component(component)
-        LOCK.synchronize do
-          @current_components&.delete(component)
+      private def validate_kind!(kind)
+        unless %i[line method].include?(kind)
+          raise ArgumentError, "Invalid kind: #{kind}"
         end
       end
     end
-  end
-end
 
-if %w(1 true).include?(ENV['DD_DYNAMIC_INSTRUMENTATION_ENABLED']) # steep:ignore
-  # For initial release of Dynamic Instrumentation, activate code tracking
-  # only if DI is explicitly requested in the environment.
-  # Code tracking is required for line probes to work; see the comments
-  # above for the implementation of the method.
-  #
-  # If DI is enabled programmatically, the application can (and must,
-  # for line probes to work) activate tracking in an initializer.
-  Datadog::DI.activate_tracking
+    # Expose DI to global shared objects
+    Extensions.activate!
+  end
 end

data/lib/datadog/error_tracking/collector.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "ext"
+require_relative "../ruby_version"
+
+module Datadog
+  module ErrorTracking
+    # The Collector is in charge, for a SpanOperation of storing the span events
+    # created when an error is handled. Each SpanOperation has a Collector as soon
+    # as a span event is created and the Collector has the same life time as the SpanOp.
+    #
+    # If an error is handled then rethrown, the SpanEvent corresponding to the error
+    # will be deleted. That is why we do not add directly the SpanEvent to the SpanOp.
+    #
+    # @api private
+    class Collector
+      SPAN_EVENTS_LIMIT = 100
+      LOCK = Mutex.new
+      # Proc called when the span_operation :after_stop event is published
+      def self.after_stop
+        @after_stop ||= proc do |span_op, error|
+          # if this proc is called, we are sure that span_op has a collector
+          collector = span_op.get_collector_or_initialize
+          # if an error exited the scope of the span, we delete the corresponding SpanEvent.
+          collector.on_error(span_op, error) if error
+
+          span_events = collector.span_events
+          span_op.span_events.concat(span_events)
+        end
+      end
+
+      def initialize
+        @span_event_per_error = {}
+      end
+
+      def add_span_event(span_op, span_event, error)
+        # When this is the first time we add a span event for a span,
+        # we suscribe to the :after_stop event
+        if @span_event_per_error.empty?
+          events = span_op.send(:events)
+          events.after_stop.subscribe(&self.class.after_stop)
+
+          # This tag is used by the Error Tracking product to report
+          # the error in Error Tracking
+          span_op.set_tag(Ext::SPAN_EVENTS_HAS_EXCEPTION, true)
+        end
+        # Set a limit to the number of span event we can store per SpanOp
+        # If an error has been handled several times in the same span we can still
+        # modify the event (even if the capacity is reached) in order to report
+        # the information of the last rescue
+        if @span_event_per_error.key?(error) || @span_event_per_error.length < SPAN_EVENTS_LIMIT
+          @span_event_per_error[error] = span_event
+        end
+      end
+
+      if RubyVersion.is?(">= #{Ext::RUBY_VERSION_WITH_RESCUE_EVENT}")
+        # Starting from ruby3.3, as we are listening to :rescue event,
+        # we just want to remove the span event if the error was
+        # previously handled
+        def on_error(_span_op, error)
+          @span_event_per_error.delete(error)
+        end
+      else
+        # Up to ruby3.2, we are listening to :raise event. We need to ensure
+        # that an error exiting the scope of a span is not handled in a parent span.
+        # This function will propagate the span event to the parent span. If the
+        # error is not handled in the parent span, it will be deleted by design.
+        def on_error(span_op, error)
+          return unless @span_event_per_error.key?(error)
+
+          unless span_op.root?
+            parent = span_op.send(:parent)
+            LOCK.synchronize do
+              parent_collector = parent.get_collector_or_initialize { Collector.new }
+              parent_collector.add_span_event(parent, @span_event_per_error[error], error)
+            end
+          end
+
+          @span_event_per_error.delete(error)
+        end
+      end
+
+      def span_events
+        @span_event_per_error.values
+      end
+    end
+  end
+end

data/lib/datadog/error_tracking/component.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "collector"
+require_relative "filters"
+
+module Datadog
+  module ErrorTracking
+    # Component for Error Tracking.
+    #
+    # Only one instance of the Component should ever be active.
+    #
+    # The component instance records every handled exceptions from the configured scopes
+    # (user, third_party packages, specified files or everything).
+    class Component
+      LOCK = Mutex.new
+
+      class << self
+        def build(settings, tracer, logger)
+          return if !settings.respond_to?(:error_tracking) || (settings.error_tracking.handled_errors.nil? &&
+            settings.error_tracking.handled_errors_include.empty?)
+
+          return unless environment_supported?(logger)
+
+          new(
+            tracer: tracer,
+            handled_errors: settings.error_tracking.handled_errors,
+            handled_errors_include: settings.error_tracking.handled_errors_include,
+          ).tap(&:start)
+        end
+
+        def environment_supported?(logger)
+          if RUBY_ENGINE != "ruby"
+            logger.warn("error tracking: cannot enable error tracking: MRI is required, but running on #{RUBY_ENGINE}")
+            false
+          elsif RubyVersion.is?("< 2.7")
+            logger.warn(
+              "error tracking: cannot enable error tracking: Ruby 2.7+ is required, but running
+              on #{RUBY_VERSION}"
+            )
+            false
+          else
+            true
+          end
+        end
+      end
+
+      def initialize(tracer:, handled_errors:, handled_errors_include:)
+        @tracer = tracer
+
+        # Hash containing the paths to the instrumented files
+        @instrumented_files = Set.new unless handled_errors_include.empty?
+        # Array containing file paths, file names and gems names to instrument.
+        # This is coming from the DD_ERROR_TRACKING_HANDLED_ERRORS_INCLUDE env variable
+        @handled_errors_include = handled_errors_include
+
+        # Filter function is used to filter out the exception
+        # we do not want to report. For instance exception from gems.
+        @filter_function = Filters.generate_filter(handled_errors, @instrumented_files)
+
+        # :rescue event was added in Ruby 3.3
+        #
+        # Before Ruby3.3 the TracePoint listen for :raise events.
+        # If an error is not handled, we will delete the according
+        # span event in the collector.
+        event = RubyVersion.is?(">= 3.3") ? :rescue : :raise
+
+        # This TracePoint is in charge of capturing the handled exceptions
+        # and of adding the corresponding span events to the collector
+        @handled_exc_tracker = create_exc_tracker_trace_point(event)
+
+        if @instrumented_files
+          # The only thing we know about the handled errors is the path of the file
+          # in which the error was rescued. Therefore, we need to retrieve the path
+          # of the files the user want to instrument. This TracePoint is used for that
+          # purpose
+          @include_path_getter = create_script_compiled_trace_point
+        end
+      end
+
+      def create_exc_tracker_trace_point(event)
+        TracePoint.new(event) do |tp|
+          active_span = @tracer.active_span
+          if active_span
+            raised_exception = tp.raised_exception
+            # Note that in 3.2, this will give the path of where the error was raised
+            # which may cause the handled_error_include env variable to malfunction.
+            rescue_file_path = tp.path
+            if @filter_function.call(rescue_file_path)
+              span_event = generate_span_event(raised_exception)
+              LOCK.synchronize do
+                collector = active_span.get_collector_or_initialize { Collector.new }
+                collector.add_span_event(active_span, span_event, raised_exception)
+              end
+            end
+          end
+        end
+      end
+
+      def create_script_compiled_trace_point
+        TracePoint.new(:script_compiled) do |tp|
+          next if tp.eval_script
+
+          path = tp.instruction_sequence.path
+          next if path.nil?
+
+          @handled_errors_include.each do |file_to_instr|
+            # The user can provide either
+            # - absolute_path starting with '/'. In that case the path of the file
+            #   should begin with file_to_instr
+            # - a relative_path starting with './'. In that case, we extend the path
+            #   and it is the same as above
+            # - otherwise we just check if the name provided is in the path and is
+            #   either the name of a folder or of a ruby file.
+            regex =
+              if file_to_instr.start_with?("/")
+                %r{\A#{Regexp.escape(file_to_instr)}(?:/|\.rb\z|\z)}
+              elsif file_to_instr.start_with?("./")
+                abs_path = File.expand_path(file_to_instr)
+                %r{\A#{Regexp.escape(abs_path)}(?:/|\.rb\z|\z)}
+              else
+                %r{/#{Regexp.escape(file_to_instr)}(?:/|\.rb\z|\z)}
+              end
+
+            add_instrumented_file(path) if path.match?(regex)
+          end
+        end
+      end
+
+      # Starts the TracePoints.
+      #
+      # Enables the script_compiled TracePoint if handled_errors_include is not empty.
+      def start
+        @handled_exc_tracker.enable
+        @include_path_getter&.enable
+      end
+
+      # Shuts down error tracker.
+      #
+      # Disables the TracePoints.
+      def shutdown!
+        @handled_exc_tracker.disable
+        @include_path_getter&.disable
+      end
+
+      private
+
+      # Generates a span event from the exception info.
+      #
+      # The event follows the otel semantics.
+      # https://opentelemetry.io/docs/specs/otel/trace/exceptions/
+      def generate_span_event(exception)
+        formatted_exception = Datadog::Core::Error.build_from(exception)
+        attributes = {
+          "exception.type" => formatted_exception.type,
+          "exception.message" => formatted_exception.message,
+          "exception.stacktrace" => formatted_exception.backtrace
+        }
+        Datadog::Tracing::SpanEvent.new("exception", attributes: attributes)
+      end
+
+      def add_instrumented_file(file_path)
+        @instrumented_files&.add(file_path)
+      end
+    end
+  end
+end

data/lib/datadog/error_tracking/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "ext"
+
+module Datadog
+  module ErrorTracking
+    # Configuration for ErrorTracking
+    module Configuration
+      # Settings
+      module Settings
+        def self.extended(base)
+          base = base.singleton_class unless base.is_a?(Class)
+          add_settings!(base)
+        end
+
+        def self.add_settings!(base)
+          base.class_eval do
+            # Error Tracking specific configurations.
+            # @public_api
+            settings :error_tracking do
+              # Enable automatic reporting of handled errors and defines the scope
+              # for which to report errors: user code, gems, or both. Possible
+              # values are: all | user | third_party.
+              #
+              # @default 'DD_ERROR_TRACKING_HANDLED_ERRORS' environment variable, otherwise `nil`
+              # @return [String, nil]
+              option :handled_errors do |o|
+                o.type :string, nilable: true
+                o.default Ext::DEFAULT_HANDLED_ERRORS
+                o.env Ext::ENV_HANDLED_ERRORS
+                o.setter do |value|
+                  next value if Ext::VALID_HANDLED_ERRORS.include?(value)
+
+                  unless value.nil?
+                    Datadog.logger.warn(
+                      "Invalid handled errors scope: #{value}. " \
+                      "Supported values are: #{Ext::VALID_HANDLED_ERRORS.join(" | ")}. " \
+                      "Deactivating the feature."
+                    )
+                  end
+
+                  Ext::DEFAULT_HANDLED_ERRORS
+                end
+              end
+
+              # Enable automatic reporting of handled errors and specify what files should be
+              # instrumented. The value is a list of comma separated paths, filenames or gem names.
+              # The paths can be absolute, starting with '/' or relative to directory in which the program
+              # is launched, starting with './'.
+              #
+              # @default 'DD_ERROR_TRACKING_HANDLED_ERRORS_MODULES' environment variable, otherwise `nil`
+              # @return [String, nil]
+              option :handled_errors_include do |o|
+                o.type :array
+                o.default []
+                o.env Ext::ENV_HANDLED_ERRORS_INCLUDE
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end