datadog 2.45.0 → 2.47.0

data/lib/datadog/core/remote/component.rb

@@ -15,7 +15,7 @@ module Datadog
       #
       # @api private
       class Component
-        attr_reader :logger, :client, :healthy, :worker
+        attr_reader :logger, :healthy, :worker
 
         def initialize(settings, capabilities, agent_settings, logger:)
           @logger = logger
@@ -28,6 +28,7 @@ module Datadog
 
           @barrier = Barrier.new(settings.remote.boot_timeout_seconds)
 
+          @client_mutex = Mutex.new
           @client = Client.new(@transport, @capabilities, settings: settings, logger: logger)
           @healthy = false
           logger.debug { "new remote configuration client: #{@client.id} products: #{@capabilities.products.sort.join(", ")}" }
@@ -40,7 +41,7 @@ module Datadog
             end
 
             begin
-              @client.sync
+              client.sync
               @healthy ||= true
             rescue Client::SyncError => e
               # Transient errors due to network or agent. Logged the error but not via telemetry
@@ -60,9 +61,11 @@ module Datadog
               end
 
               # client state is unknown, state might be corrupted
-              @client = Client.new(@transport, @capabilities, settings: settings, logger: logger)
+              new_client = @client_mutex.synchronize do
+                @client = Client.new(@transport, @capabilities, settings: settings, logger: logger)
+              end
               @healthy = false
-              logger.debug { "new remote configuration client: #{@client.id} products: #{@capabilities.products.sort.join(", ")}" }
+              logger.debug { "new remote configuration client: #{new_client.id} products: #{@capabilities.products.sort.join(", ")}" }
 
               # TODO: bail out if too many errors?
             end
@@ -81,6 +84,10 @@ module Datadog
           @worker.started?
         end
 
+        def client
+          @client_mutex.synchronize { @client }
+        end
+
         # If the worker is not initialized, initialize it.
         #
         # Then, waits for one client sync to be executed if `kind` is `:once`.
@@ -98,9 +105,11 @@ module Datadog
         def after_fork
           @worker.after_fork
           @barrier = Barrier.new(@settings.remote.boot_timeout_seconds)
-          @client = Client.new(@transport, @capabilities, settings: @settings, logger: @logger)
+          new_client = @client_mutex.synchronize do
+            @client = Client.new(@transport, @capabilities, settings: @settings, logger: @logger)
+          end
           @healthy = false
-          logger.debug { "remote configuration client recreated after fork: #{@client.id} products: #{@capabilities.products.sort.join(", ")}" }
+          logger.debug { "remote configuration client recreated after fork: #{new_client.id} products: #{@capabilities.products.sort.join(", ")}" }
         end
 
         def add_products(*products)
@@ -111,6 +120,17 @@ module Datadog
           @capabilities.remove_products(*products)
         end
 
+        def register(capabilities:, products:, receivers:)
+          @client_mutex.synchronize do
+            @capabilities.register_runtime(
+              capabilities: capabilities,
+              products: products,
+              receivers: receivers,
+            )
+            @client.dispatcher.add_receivers(*receivers)
+          end
+        end
+
         # Barrier provides a mechanism to fence execution until a condition happens
         class Barrier
           def initialize(timeout = nil)
@@ -189,14 +209,10 @@ module Datadog
           #
           # Those checks are instead performed inside the worker loop.
           # This allows users to upgrade their agent while keeping their application running.
-          def build(settings, agent_settings, logger:, telemetry:, open_feature_component_provider: nil)
+          def build(settings, agent_settings, logger:, telemetry:)
             return unless settings.remote.enabled
 
-            capabilities = Client::Capabilities.new(
-              settings,
-              telemetry,
-              open_feature_component_provider: open_feature_component_provider,
-            )
+            capabilities = Client::Capabilities.new(settings, telemetry: telemetry)
             new(settings, capabilities, agent_settings, logger: logger)
           end
         end

data/lib/datadog/core/remote/dispatcher.rb

@@ -5,24 +5,57 @@ module Datadog
     module Remote
       # Repository update dispatcher
       class Dispatcher
-        attr_reader :receivers
-
         def initialize(receivers)
-          @receivers = receivers
+          @receivers = receivers.dup
+          @mutex = Mutex.new
+        end
+
+        def receivers
+          @mutex.synchronize { @receivers.dup }
+        end
+
+        def add_receivers(*receivers)
+          @mutex.synchronize do
+            receivers.each { |receiver| @receivers << receiver unless @receivers.include?(receiver) }
+          end
+          nil
         end
 
         def dispatch(changes, repository)
           receivers.each do |receiver|
-            matching_changes = changes.select { |c| receiver.match?(c.path) }
+            matching = matching_changes(changes, receiver)
+
+            receiver.call(repository, matching) if matching.any?
+          end
+          nil
+        end
+
+        # Calls each receiver that declares initial-reconcile participation and has no
+        # matching change in `changes`, passing an empty change list.
+        def reconcile(changes, repository)
+          receivers.each do |receiver|
+            next unless receiver.initial_reconcile?
 
-            receiver.call(repository, matching_changes) if matching_changes.any?
+            receiver.call(repository, []) unless any_matching?(changes, receiver)
           end
+          nil
+        end
+
+        private
+
+        def matching_changes(changes, receiver)
+          changes.select { |change| receiver.match?(change.path) }
+        end
+
+        def any_matching?(changes, receiver)
+          changes.any? { |change| receiver.match?(change.path) }
         end
 
         # Store Matcher and block to be executed on a match
         class Receiver
-          def initialize(matcher, &block)
+          def initialize(matcher, initial_reconcile: false, &block)
             @block = block
+            @initial_reconcile = initial_reconcile
             @matcher = matcher
           end
 
@@ -30,6 +63,14 @@ module Datadog
             @matcher.match?(path)
           end
 
+          # Whether #reconcile may call this receiver with an empty change
+          # list on the client's first sync. A participating receiver must
+          # act on the repository's current contents when the change list is
+          # empty.
+          def initial_reconcile?
+            @initial_reconcile
+          end
+
           def call(repository, changes)
             @block.call(repository, changes)
           end

data/lib/datadog/core/workers/runtime_metrics.rb

@@ -32,7 +32,7 @@ module Datadog
           end
 
           # Workers::Async::Thread settings
-          self.fork_policy = options.fetch(:fork_policy, Workers::Async::Thread::FORK_POLICY_STOP)
+          self.fork_policy = options.fetch(:fork_policy, Workers::Async::Thread::FORK_POLICY_RESTART)
 
           # Workers::IntervalLoop settings
           self.loop_base_interval = options.fetch(:interval, DEFAULT_FLUSH_INTERVAL)

data/lib/datadog/di/boot.rb

@@ -7,6 +7,7 @@ require_relative "code_tracker"
 require_relative "component"
 require_relative "context"
 require_relative "capture_limits"
+require_relative "guardrails_telemetry"
 require_relative "capture_expression"
 require_relative "capture_expression_evaluator"
 require_relative "instrumenter"

data/lib/datadog/di/capture_expression_evaluator/result.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Datadog
+  module DI
+    class CaptureExpressionEvaluator
+      # The result of evaluating a probe's capture expressions: the
+      # serialized values and the evaluation errors.
+      class Result
+        # Initializes the result.
+        #
+        # @param serialized_values [Hash{String => untyped}] serialized values keyed by capture expression name
+        # @param errors [Array<EvaluationFailure>] evaluation errors of the expressions that failed to evaluate or serialize
+        # @return [void]
+        def initialize(serialized_values:, errors:)
+          @serialized_values = serialized_values
+          @errors = errors
+        end
+
+        # The serialized values keyed by capture expression name.
+        # @return [Hash{String => untyped}]
+        attr_reader :serialized_values
+
+        # The evaluation errors; one entry per expression that failed to
+        # evaluate or serialize.
+        # @return [Array<EvaluationFailure>]
+        attr_reader :errors
+      end
+    end
+  end
+end

data/lib/datadog/di/capture_expression_evaluator.rb

@@ -2,17 +2,28 @@
 
 require_relative "capture_expression"
 require_relative "capture_limits"
+require_relative "capture_expression_evaluator/result"
+require_relative "evaluation_failure"
 require_relative "fatal_exceptions"
+require_relative "guardrails_telemetry"
+require_relative "../core/utils/time"
 
 module Datadog
   module DI
     class CaptureExpressionEvaluator
-      TELEMETRY_NAMESPACE = "dynamic_instrumentation"
-
-      def initialize(settings:, serializer:, logger:, telemetry: nil)
+      # Initializes the evaluator.
+      #
+      # @param settings [Datadog::Core::Configuration::Settings] tracer settings
+      # @param serializer [Serializer] serializer for captured expression values
+      # @param logger [DI::Logger] logger for evaluation failure diagnostics
+      # @param guardrails_telemetry [GuardrailsTelemetry] emitter for the canonical capture-timeout skip metric
+      # @param telemetry [Datadog::Core::Telemetry::Component, nil] component evaluation failures are reported through
+      # @return [void]
+      def initialize(settings:, serializer:, logger:, guardrails_telemetry:, telemetry: nil)
         @settings = settings
         @serializer = serializer
         @logger = logger
+        @guardrails_telemetry = guardrails_telemetry
         @telemetry = telemetry
       end
 
@@ -22,11 +33,25 @@ module Datadog
 
       attr_reader :logger
 
+      # The guardrails metric emitter.
+      # @return [GuardrailsTelemetry]
+      attr_reader :guardrails_telemetry
+
       attr_reader :telemetry
 
+      # Evaluates each of the probe's capture expressions against the given
+      # context, serializing the captured values under one capture deadline
+      # resolved through the serializer and shared across all expressions.
+      # An expression that fails to evaluate or serialize contributes an entry
+      # to the returned errors.
+      #
+      # @param probe [Probe] the probe whose capture expressions are evaluated
+      # @param context [Context] evaluation context the expressions are evaluated against
+      # @return [Result] the evaluation result: the serialized values keyed by
+      #   capture expression name and the errors of the expressions that failed
+      #   to evaluate or serialize
       def evaluate(probe, context)
-        budget_ns = settings.dynamic_instrumentation.max_time_to_serialize_ms * 1_000_000
-        deadline_ns = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :nanosecond) + budget_ns
+        deadline = serializer.serialization_deadline
 
         output = {}
         evaluation_errors = []
@@ -34,9 +59,13 @@ module Datadog
         probe.capture_expressions.each do |capture_expression|
           name = capture_expression.name
 
-          if ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :nanosecond) >= deadline_ns
+          if Process.clock_gettime(Process::CLOCK_THREAD_CPUTIME_ID, :float_second) >= deadline
             output[name] = {notCapturedReason: "timeout"}
-            telemetry&.inc(TELEMETRY_NAMESPACE, "capture_expressions_skipped_by_timeout", 1)
+            telemetry&.inc(DI::TELEMETRY_NAMESPACE, "capture_expressions_skipped_by_timeout", 1)
+            guardrails_telemetry.skipped(
+              reason: GuardrailsTelemetry::Reason::EVALUATION_TIMEOUT,
+              probe: probe,
+            )
             next
           end
 
@@ -53,10 +82,11 @@ module Datadog
               attribute_count: limits[:attribute_count],
               length: limits[:length],
               collection_size: limits[:collection_size],
+              deadline: deadline,
             )
           rescue Exception => exc # standard:disable Lint/RescueException
             Datadog::DI.reraise_if_fatal(exc)
-            evaluation_errors << {expr: name, message: "#{exc.class}: #{exc.message}"}
+            evaluation_errors << EvaluationFailure.new(expr: name, message: "#{exc.class}: #{exc.message}")
             logger.debug do
               "di: probe #{probe.id}: capture expression #{name}: evaluation failed: #{exc.class}: #{exc.message}"
             end
@@ -64,7 +94,7 @@ module Datadog
           end
         end
 
-        [output, evaluation_errors]
+        Result.new(serialized_values: output, errors: evaluation_errors)
       end
     end
   end

data/lib/datadog/di/component.rb

@@ -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
@@ -166,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.

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
@@ -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/evaluation_failure.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Datadog
+  module DI
+    # An expression evaluation failure reported in a snapshot's evaluation
+    # errors: the expression that failed and the error description.
+    # @api private
+    class EvaluationFailure
+      # Initializes the failure.
+      #
+      # @param expr [String] name of the capture expression, or source of the condition or template expression, that failed to evaluate or serialize
+      # @param message [String] error description of the failed evaluation
+      # @return [void]
+      def initialize(expr:, message:)
+        @expr = expr
+        @message = message
+      end
+
+      # The name of the capture expression, or the source of the condition or
+      # template expression, that failed to evaluate or serialize.
+      # @return [String]
+      attr_reader :expr
+
+      # @return [String] the error description of the failed evaluation
+      attr_reader :message
+    end
+  end
+end