datadog 2.45.0 → 2.46.0

data/lib/datadog/di/serializer.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
+require "date"
 require_relative "redactor"
+require_relative "guardrails_telemetry"
+require_relative "../core/utils/time"
 
 module Datadog
   module DI
-    # Serializes captured snapshot to primitive types, which are subsequently
+    # Serializes captured snapshots to primitive types, which are subsequently
     # serialized to JSON and sent to the backend.
     #
-    # This class performs actual removal of sensitive values from the
-    # snapshots. It uses Redactor to determine which values are sensitive
-    # and need to be removed.
+    # Sensitive values are removed from the snapshots.
     #
     # Serializer normally ought not to invoke user (application) code,
     # to guarantee predictable performance. However, objects like ActiveRecord
@@ -19,7 +20,7 @@ module Datadog
     # thus they won't be captured at all). To accommodate complex objects,
     # there is an extension mechanism implemented permitting registration
     # of serializer callbacks for arbitrary types. Applications and libraries
-    # definining such serializer callbacks should be very careful to
+    # defining such serializer callbacks should be very careful to
     # have predictable performance and avoid exceptions and infinite loops
     # and other such issues.
     #
@@ -36,25 +37,21 @@ module Datadog
     # efficient but there would be additional overhead from passing this
     # parameter all the time and the API would get more complex.
     #
-    # Note: "self" cannot be used as a parameter name in Ruby, therefore
-    # there should never be a conflict between instance variable
-    # serialization and method parameters.
-    #
     # @api private
     class Serializer
-      # Exception classes that should never be caught during serialization.
-      # These represent fatal conditions (signals, interrupts, system exit)
-      # that must propagate to the caller. NoMemoryError is deliberately
-      # excluded (unlike DI::FATAL_EXCEPTION_CLASSES): serialization of large
-      # or deeply recursive objects can exhaust memory, and the serializer must
-      # return a safe stub rather than tear the process down.
+      # Exception classes that must propagate to the caller during
+      # serialization: fatal conditions (signals, interrupts, system exit).
+      # NoMemoryError is deliberately excluded (unlike
+      # DI::FATAL_EXCEPTION_CLASSES): serialization of large or deeply
+      # recursive objects can exhaust memory, and the serializer must return
+      # a safe stub rather than terminate the process.
       SERIALIZABLE_FATAL_EXCEPTION_CLASSES = [SystemExit, SignalException].freeze
 
       # Placeholder emitted by #serialize_value_for_message in place of a value
-      # whose identifier or type matches the redaction configuration. This
-      # mirrors, for the human-readable log-probe message path, the
-      # notCapturedReason: "redactedIdent"/"redactedType" gating that
-      # #serialize_value applies on the snapshot path.
+      # whose identifier or type matches the redaction configuration. The
+      # message-path counterpart of the +notCapturedReason+
+      # "redactedIdent"/"redactedType" markers that #serialize_value produces
+      # on the snapshot path.
       REDACTED_VALUE_FOR_MESSAGE = "[redacted]"
 
       # Third-party library integration / custom serializers.
@@ -103,16 +100,42 @@ module Datadog
         @@flat_registry << {condition: condition, proc: block}
       end
 
-      def initialize(settings, redactor, telemetry: nil)
+      # Initializes the serializer.
+      #
+      # @param settings [Datadog::Core::Configuration::Settings] tracer settings
+      # @param redactor [Redactor] redactor gating captured values
+      # @param logger [DI::Logger] logger for contained serialization failures
+      # @param guardrails_telemetry [GuardrailsTelemetry] emitter for the canonical capture-incomplete metric
+      # @param telemetry [Datadog::Core::Telemetry::Component, nil] component serializer errors are reported through
+      # @return [void]
+      def initialize(settings, redactor, logger:, guardrails_telemetry:, telemetry: nil)
         @settings = settings
         @redactor = redactor
+        @logger = logger
+        @guardrails_telemetry = guardrails_telemetry
         @telemetry = telemetry
       end
 
       attr_reader :settings
       attr_reader :redactor
+      # The logger.
+      # @return [DI::Logger]
+      attr_reader :logger
+      # The guardrails metric emitter.
+      # @return [GuardrailsTelemetry]
+      attr_reader :guardrails_telemetry
       attr_reader :telemetry
 
+      # Emits the canonical capture-incomplete metric for a capture limit
+      # enforced while serializing a snapshot, with the snapshot event
+      # type.
+      #
+      # @param reason [String] a GuardrailsTelemetry::Reason constant naming the enforced limit
+      # @return [void]
+      def record_capture_incomplete(reason)
+        guardrails_telemetry.capture_incomplete(reason: reason, event_type: GuardrailsTelemetry::EVENT_TYPE_SNAPSHOT)
+      end
+
       def combine_args(args, kwargs, target_self)
         counter = 0
         combined = args.each_with_object({}) do |value, c|
@@ -133,31 +156,39 @@ module Datadog
       # arguments to keyword arguments ("arg1", "arg2", ...) and ensure
       # the positional arguments are listed first.
       #
-      # Instance variables are technically a hash just like kwargs,
-      # we take them as a separate parameter to avoid a hash merge
-      # in upstream code.
+      # @param args [Array] positional arguments passed to the probed method
+      # @param kwargs [Hash{Symbol => Object}] keyword arguments passed to the probed method
+      # @param target_self [any] receiver of the probed method invocation
+      # @param deadline [Float] absolute capture deadline in monotonic clock seconds
+      # @return [Hash{Symbol => Hash}] serialized arguments keyed by argument name
       def serialize_args(args, kwargs, target_self,
+        deadline:,
         depth: settings.dynamic_instrumentation.max_capture_depth,
         attribute_count: settings.dynamic_instrumentation.max_capture_attribute_count,
         length: nil,
         collection_size: nil)
         combined = combine_args(args, kwargs, target_self)
         serialize_vars(combined, depth: depth, attribute_count: attribute_count,
-          length: length, collection_size: collection_size)
+          length: length, collection_size: collection_size, deadline: deadline,)
       end
 
       # Serializes variables captured by a line probe.
       #
       # These are normally local variables that exist on a particular line
       # of executed code.
+      #
+      # @param vars [Hash{Symbol => Object}] variables to serialize, keyed by variable name
+      # @param deadline [Float] absolute capture deadline in monotonic clock seconds
+      # @return [Hash{Symbol => Hash}] serialized variables keyed by variable name
       def serialize_vars(vars,
+        deadline:,
         depth: settings.dynamic_instrumentation.max_capture_depth,
         attribute_count: settings.dynamic_instrumentation.max_capture_attribute_count,
         length: nil,
         collection_size: nil)
         vars.each_with_object({}) do |(k, v), agg|
           agg[k] = serialize_value(v, name: k, depth: depth, attribute_count: attribute_count,
-            length: length, collection_size: collection_size)
+            length: length, collection_size: collection_size, deadline: deadline,)
         end
       end
 
@@ -173,7 +204,13 @@ module Datadog
       # (integers, strings, arrays, hashes).
       #
       # Respects string length, collection size and traversal depth limits.
-      def serialize_value(value, name: nil,
+      #
+      # @param value [any] value to serialize
+      # @param name [Symbol, String, nil] name the value is bound to, used for redaction
+      # @param deadline [Float] absolute capture deadline in monotonic clock seconds
+      # @return [Hash{Symbol => Object}] serialized value; the {type:, notCapturedReason: "timeout"} stub when the deadline is exceeded
+      def serialize_value(value, deadline:,
+        name: nil,
         depth: settings.dynamic_instrumentation.max_capture_depth,
         attribute_count: nil,
         length: nil,
@@ -182,6 +219,12 @@ module Datadog
         attribute_count ||= settings.dynamic_instrumentation.max_capture_attribute_count
         cls = type || value.class
         begin
+          if deadline_exceeded?(deadline)
+            telemetry&.inc(DI::TELEMETRY_NAMESPACE, "serialized_values_skipped_by_timeout", 1)
+            record_capture_incomplete(GuardrailsTelemetry::Reason::CAPTURE_TIMEOUT)
+            return {type: class_name(cls), notCapturedReason: "timeout"}
+          end
+
           if redactor.redact_type?(value)
             return {type: class_name(cls), notCapturedReason: "redactedType"}
           end
@@ -213,7 +256,7 @@ module Datadog
 
               if condition_result
                 serializer_proc = entry.fetch(:proc)
-                return serializer_proc.call(self, value, name: nil, depth: depth)
+                return serializer_proc.call(self, value, name: nil, depth: depth, deadline: deadline)
               end
             end
           end
@@ -227,8 +270,6 @@ module Datadog
           when Integer, Float, TrueClass, FalseClass
             serialized.update(value: value.to_s)
           when Time
-            # This path also handles DateTime values although they do not need
-            # to be explicitly added to the case statement.
             serialized.update(value: value.iso8601)
           when Date
             serialized.update(value: value.to_s)
@@ -246,27 +287,24 @@ module Datadog
             end
 
             # Handle binary strings and invalid UTF-8 by escaping to JSON-safe format.
-            # See escape_binary_string for details on the escaping format.
-            #
-            # Truncate binary data BEFORE escaping to avoid cutting mid-escape-sequence.
             # For regular strings, the limit is applied to string length in characters.
             length ||= settings.dynamic_instrumentation.max_capture_string_length
             max = length
 
             if value.encoding == Encoding::BINARY || !value.valid_encoding?
-              # Truncate binary data BEFORE escaping to avoid cutting mid-escape-sequence
+              # Truncate binary data before escaping to avoid cutting mid-escape-sequence
               # For invalid encodings, use bytesize instead of length to avoid encoding errors
               original_size = value.bytesize
               if original_size > max
                 serialized.update(truncated: true, size: original_size)
+                record_capture_incomplete(GuardrailsTelemetry::Reason::STRING_LENGTH)
                 value = value.byteslice(0...max)
               end
               value = escape_binary_string(value) # steep:ignore ArgumentTypeMismatch
-              false # Already converted to a new string
             else
-              # Truncate non-binary strings
               if value.length > max
                 serialized.update(truncated: true, size: value.length)
+                record_capture_incomplete(GuardrailsTelemetry::Reason::STRING_LENGTH)
                 value = value[0...max]
                 need_dup = false
               end
@@ -278,23 +316,32 @@ module Datadog
           when Array
             if depth <= 0
               serialized.update(notCapturedReason: "depth")
+              record_capture_incomplete(GuardrailsTelemetry::Reason::DEPTH)
             else
               collection_size ||= settings.dynamic_instrumentation.max_capture_collection_size
               max = collection_size
               if max != 0 && value.length > max
                 serialized.update(notCapturedReason: "collectionSize", size: value.length)
+                record_capture_incomplete(GuardrailsTelemetry::Reason::COLLECTION_SIZE)
                 # same steep failure with array slices.
                 # https://github.com/soutaro/steep/issues/1219
                 value = value[0...max] || []
               end
-              entries = value.map do |elt|
-                serialize_value(elt, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count)
+              entries = []
+              value.each do |elt|
+                entry = serialize_value(elt, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count, deadline: deadline)
+                entries << entry
+                if entry[:notCapturedReason] == "timeout"
+                  serialized.update(notCapturedReason: "timeout")
+                  break
+                end
               end
               serialized.update(elements: entries)
             end
           when Hash
             if depth <= 0
               serialized.update(notCapturedReason: "depth")
+              record_capture_incomplete(GuardrailsTelemetry::Reason::DEPTH)
             else
               collection_size ||= settings.dynamic_instrumentation.max_capture_collection_size
               max = collection_size
@@ -303,17 +350,28 @@ module Datadog
               value.each do |k, v|
                 if max != 0 && cur >= max
                   serialized.update(notCapturedReason: "collectionSize", size: value.length)
+                  record_capture_incomplete(GuardrailsTelemetry::Reason::COLLECTION_SIZE)
                   break
                 end
                 cur += 1
-                entries << [serialize_value(k, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count),
-                  serialize_value(v, name: k, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count)]
+                key_entry = serialize_value(k, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count, deadline: deadline)
+                if key_entry[:notCapturedReason] == "timeout"
+                  serialized.update(notCapturedReason: "timeout")
+                  break
+                end
+                value_entry = serialize_value(v, name: k, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count, deadline: deadline)
+                entries << [key_entry, value_entry]
+                if value_entry[:notCapturedReason] == "timeout"
+                  serialized.update(notCapturedReason: "timeout")
+                  break
+                end
               end
               serialized.update(entries: entries)
             end
           else
             if depth <= 0
               serialized.update(notCapturedReason: "depth")
+              record_capture_incomplete(GuardrailsTelemetry::Reason::DEPTH)
             else
               fields = {}
               cur = 0
@@ -334,40 +392,42 @@ module Datadog
               #
               # For consistency, we should have some kind of stable order of
               # instance variables on all supported Ruby runtimes, so that the UI
-              # stays consistent. Given that initial implementation of Ruby DI
-              # does not support JRuby, we don't handle JRuby's lack of ordering
-              # of #instance_variables here, but if JRuby is supported in the
-              # future this may need to be addressed.
+              # stays consistent. Ruby DI does not support JRuby, so JRuby's lack
+              # of ordering of #instance_variables is not handled here.
               ivars = value.instance_variables
 
               ivars.each do |ivar|
                 if cur >= attribute_count
                   serialized.update(notCapturedReason: "fieldCount", fields: fields)
+                  record_capture_incomplete(GuardrailsTelemetry::Reason::FIELD_COUNT)
                   break
                 end
                 cur += 1
-                fields[ivar] = serialize_value(value.instance_variable_get(ivar), name: ivar, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count)
+                entry = serialize_value(value.instance_variable_get(ivar), name: ivar, depth: depth - 1, length: length, collection_size: collection_size, attribute_count: attribute_count, deadline: deadline)
+                fields[ivar] = entry
+                if entry[:notCapturedReason] == "timeout"
+                  serialized.update(notCapturedReason: "timeout")
+                  break
+                end
               end
               serialized.update(fields: fields)
             end
           end
           serialized
         rescue Exception => exc # standard:disable Lint/RescueException
-          # Re-raise fatal exceptions that should not be caught
-          # (signals, interrupts, system exit)
           raise if SERIALIZABLE_FATAL_EXCEPTION_CLASSES.any? { |klass| exc.is_a?(klass) }
 
-          # Catch all other exceptions including SystemStackError and NoMemoryError.
-          # These inherit from Exception (not StandardError) but can occur during
-          # serialization (e.g., infinite recursion in custom serializers, memory
-          # exhaustion from large objects) and should return a safe structure
-          # rather than propagating to the transport layer.
+          # Catch all remaining exceptions: SystemStackError and NoMemoryError can
+          # occur during serialization (e.g. a custom serializer recursing
+          # infinitely) and produce the safe stub.
+          record_capture_incomplete(GuardrailsTelemetry::Reason::RUNTIME_ERROR)
+          logger.debug { "di: error serializing value of #{class_name(cls)}: #{exc.class}: #{exc.message}" }
           telemetry&.report(exc, description: "Error serializing")
           {type: class_name(cls), notSerializedReason: exc.to_s}
         end
       end
 
-      # This method is used for serializing arbitrary values into log messages.
+      # Serializes a value for interpolation into a log-probe message.
       # Because the output is meant to be human-readable, we cannot use
       # the "normal" serialization format which is meant to be machine-readable.
       # Serialize objects with depth of 1 and include the class name.
@@ -386,6 +446,8 @@ module Datadog
       # +name+, when given, is the identifier the template expression
       # references at its top level; a redacted identifier yields the
       # redaction placeholder, mirroring #serialize_value on the snapshot path.
+      # Message rendering is capped by depth (1) and
+      # MAX_MESSAGE_COLLECTION_SIZE / MAX_MESSAGE_ATTRIBUTE_COUNT.
       def serialize_value_for_message(value, depth: 1, name: nil)
         # This method is more verbose than "normal" Ruby code to avoid
         # array allocations.
@@ -475,13 +537,27 @@ module Datadog
         raise if SERIALIZABLE_FATAL_EXCEPTION_CLASSES.any? { |klass| exc.is_a?(klass) }
 
         telemetry&.report(exc, description: "Error serializing for message")
-        # TODO class_name(foo) can also fail, which we don't handle here.
-        # Telemetry reporting could potentially also fail?
+        # TODO handle class_name raising here as well.
         "#<#{class_name(value.class)}: serialization error>"
       end
 
+      # Computes the absolute monotonic deadline (in seconds) for a capture
+      # point from max_time_to_serialize_ms. Resolve once per capture point and
+      # share across all values serialized on the built-in paths so the
+      # budget is not exceeded.
+      #
+      # @return [Float] absolute monotonic clock reading, in seconds, at
+      #   which the capture budget is exhausted
+      def serialization_deadline
+        Core::Utils::Time.get_time + settings.dynamic_instrumentation.max_time_to_serialize_ms / 1000.0
+      end
+
       private
 
+      def deadline_exceeded?(deadline)
+        Core::Utils::Time.get_time >= deadline
+      end
+
       MAX_MESSAGE_COLLECTION_SIZE = 3
       MAX_MESSAGE_ATTRIBUTE_COUNT = 5
 

data/lib/datadog/di/snapshot_event.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Datadog
+  module DI
+    # A snapshot payload queued for sending to the agent, paired with
+    # the guardrails event type of the probe that produced it, so drop
+    # metrics can be tagged with the probe's classification.
+    # @api private
+    class SnapshotEvent
+      # Initializes the event.
+      #
+      # @param payload [Hash] the snapshot payload to send to the agent
+      # @param event_type [String] one of GuardrailsTelemetry::EVENT_TYPE_SNAPSHOT and EVENT_TYPE_LOG
+      # @return [void]
+      def initialize(payload:, event_type:)
+        @payload = payload
+        @event_type = event_type
+      end
+
+      # The snapshot payload to send to the agent.
+      # @return [Hash]
+      attr_reader :payload
+
+      # The guardrails event type of the probe that produced the payload.
+      # @return [String] one of GuardrailsTelemetry::EVENT_TYPE_SNAPSHOT and EVENT_TYPE_LOG
+      attr_reader :event_type
+
+      # Compares two events by payload and event type.
+      #
+      # @param other [Object] the object to compare with
+      # @return [Boolean] whether the other object is an event with the
+      #   same payload and event type
+      def ==(other)
+        other.is_a?(SnapshotEvent) && other.payload == payload && other.event_type == event_type
+      end
+    end
+  end
+end

data/lib/datadog/di/transport/http.rb

@@ -47,11 +47,20 @@ module Datadog
           end.to_transport(DI::Transport::Diagnostics::Transport)
         end
 
-        # Builds a new Transport::HTTP::Client with default settings
-        # Pass a block to override any settings.
+        # Builds the snapshot input transport. Pass a block to override
+        # any transport settings.
+        #
+        # @param agent_settings [Datadog::Core::Configuration::AgentSettings] agent connection settings
+        # @param logger [DI::Logger] logger for transport diagnostics
+        # @param headers [Hash{String => String}, nil] headers to send with every request
+        # @param telemetry [Datadog::Core::Telemetry::Component, nil] component transport errors are reported through
+        # @param guardrails_telemetry [GuardrailsTelemetry] emitter for the canonical guardrails drop metric
+        # @return [DI::Transport::Input::Transport]
+        # @yield [builder] block overriding the default transport builder settings
         def self.input(
           agent_settings:,
           logger:,
+          guardrails_telemetry:,
           headers: nil,
           telemetry: nil
         )
@@ -72,7 +81,8 @@ module Datadog
             builder.to_api_instances,
             builder.default_api,
             logger: logger,
-            telemetry: telemetry
+            telemetry: telemetry,
+            guardrails_telemetry: guardrails_telemetry,
           )
         end
       end

data/lib/datadog/di/transport/input.rb

@@ -8,6 +8,7 @@ require_relative "../../core/transport/request"
 require_relative "../../core/transport/transport"
 require_relative "../error"
 require_relative "../fatal_exceptions"
+require_relative "../guardrails_telemetry"
 require_relative "http/input"
 
 module Datadog
@@ -26,10 +27,22 @@ module Datadog
 
         class Transport < Core::Transport::Transport
           attr_reader :telemetry
+          # The guardrails metric emitter.
+          # @return [GuardrailsTelemetry]
+          attr_reader :guardrails_telemetry
 
-          def initialize(apis, default_api, logger:, telemetry: nil)
+          # Initializes the transport.
+          #
+          # @param apis [Datadog::Core::Transport::HTTP::API::Map] API instances by name
+          # @param default_api [String] name of the API requests are sent through when unspecified
+          # @param logger [Datadog::Core::Logger] logger for transport diagnostics
+          # @param guardrails_telemetry [GuardrailsTelemetry] emitter for the canonical payload-drop metric
+          # @param telemetry [Datadog::Core::Telemetry::Component, nil] component transport errors are reported through
+          # @return [void]
+          def initialize(apis, default_api, logger:, guardrails_telemetry:, telemetry: nil)
             super(apis, default_api, logger: logger)
             @telemetry = telemetry
+            @guardrails_telemetry = guardrails_telemetry
           end
 
           # The limit on an individual snapshot payload, aka "log line",
@@ -62,19 +75,24 @@ module Datadog
           # Large snapshots (> 1MB) are dropped. Batches are split into chunks
           # of ~2MB each to avoid large network requests.
           #
-          # @param payload [Array<Hash>] Array of snapshot payloads
+          # @param payload [Array<SnapshotEvent>] the snapshot events to send, each paired with its probe's guardrails event type
           # @param tags [Hash] Tags to send with the snapshots
           # @param on_serialization_error [Proc] Called with (probe_id, exception)
           #   when a snapshot fails to serialize.
+          # @return [Array<SnapshotEvent>] the events that were sent
           def send_input(payload, tags, on_serialization_error:)
             serialized_tags = Core::TagBuilder.serialize_tags(tags)
 
             # Serialize each snapshot individually to isolate failures
             encoded_snapshots = []
-            payload.each do |snapshot|
-              encoded = encoder.encode(snapshot)
-              if encoded.length > MAX_SERIALIZED_SNAPSHOT_SIZE
-                logger.debug { "di: dropping too big snapshot" }
+            dropped_events = []
+            payload.each do |event|
+              encoded = encoder.encode(event.payload)
+              if encoded.bytesize > MAX_SERIALIZED_SNAPSHOT_SIZE
+                logger.debug do
+                  "di: dropping too big snapshot (#{GuardrailsTelemetry::Reason::PAYLOAD_TOO_LARGE})"
+                end
+                dropped_events << [event, encoded.bytesize]
                 next
               end
               encoded_snapshots << encoded
@@ -82,7 +100,7 @@ module Datadog
               Datadog::DI.reraise_if_fatal(exc)
               # Serialization failed for this snapshot - report via callback
               # This catches JSON::GeneratorError, Encoding errors, TypeError, etc.
-              probe_id = snapshot.dig(:debugger, :snapshot, :probe, :id)
+              probe_id = event.payload.dig(:debugger, :snapshot, :probe, :id)
               logger.debug { "di: JSON encoding failed for snapshot (probe #{probe_id}): #{exc.class}: #{exc.message}" }
               telemetry&.report(exc, description: "JSON encoding failed for snapshot")
 
@@ -97,6 +115,13 @@ module Datadog
               end
             end
 
+            dropped_events.each do |event, bytes|
+              guardrails_telemetry.dropped(
+                reason: GuardrailsTelemetry::Reason::PAYLOAD_TOO_LARGE,
+                event_type: event.event_type, bytes: bytes,
+              )
+            end
+
             return payload if encoded_snapshots.empty?
 
             Datadog::Core::Chunker.chunk_by_size(