datadog 2.21.0 → 2.38.0

data/lib/datadog/core/utils/spawn_monkey_patch.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../../ruby_version'
+
+module Datadog
+  module Core
+    module Utils
+      # Applies the Process.spawn wrapper used to merge additional environment variables
+      # into child processes.
+      module SpawnMonkeyPatch
+        # @param env_provider [#call] returns a Hash of env vars to merge into the child process
+        def self.apply!(env_provider:)
+          @env_provider = env_provider
+
+          # Idempotent: tests, reloads, or repeated Components init must not stack prepends.
+          return if ::Process.singleton_class.ancestors.include?(ProcessSpawnPatch)
+
+          ::Process.singleton_class.prepend(ProcessSpawnPatch)
+        end
+
+        # Prepends `Process.spawn` to merge `env_provider` output into the child's environment hash.
+        module ProcessSpawnPatch
+          # The One and Only Correct Delegation Pattern
+          if RubyVersion.is?('>= 3')
+            def spawn(*args, **kwargs) # steep:ignore DifferentMethodParameterKind
+              super(*SpawnMonkeyPatch.inject_envs(args), **kwargs)
+            end
+          else
+            def spawn(*args)
+              super(*SpawnMonkeyPatch.inject_envs(args))
+            end
+            ruby2_keywords :spawn if respond_to?(:ruby2_keywords, true)
+          end
+        end
+
+        # Merge the env vars from `env_provider` with the optional env `Hash` from {Process.spawn}.
+        #
+        # `env` is the first argument when it is a {Hash}; see MRI `spawn([env, ] *args, options)`:
+        # https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn
+        #
+        # When there is **no** leading env Hash, MRI inherits the parent's `ENV`; we prepend only the
+        # `env_provider` hash so spawned children see parent env plus injections.
+        #
+        # When callers pass `unsetenv_others: true`, MRI only forwards the explicitly passed env Hash;
+        # replacing a missing hash with DATADOG_ENV.to_h would wrongly carry over parent variables.
+        # Prepending only the provider hash preserves `unsetenv_others` semantics.
+        #
+        # See https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Environment+Variables+-28-3Aunsetenv_others-29
+        #
+        # NOTE: `::Hash` (not bare `Hash`) is required because this module is nested under
+        # `Datadog::Core::Utils`, and `Datadog::Core::Utils::Hash` exists.
+        # Bare `Hash` resolves to that module via Module.nesting, making `Hash === some_hash`
+        # silently return `false`. See https://github.com/DataDog/dd-trace-rb/issues/5621.
+        def self.inject_envs(args)
+          provided_env = @env_provider.call
+
+          if ::Hash === args.first
+            args[0] = args.first.merge(provided_env)
+          else
+            args.unshift(provided_env)
+          end
+
+          args
+        end
+      end
+    end
+  end
+end

data/lib/datadog/core/utils/time.rb

@@ -8,11 +8,15 @@ module Datadog
         module_function
 
         # Current monotonic time
+        # On macOS, CLOCK_MONOTONIC only has microsecond precision,
+        # so we use CLOCK_MONOTONIC_RAW which has nanosecond precision instead.
         #
         # @param unit [Symbol] unit for the resulting value, same as ::Process#clock_gettime, defaults to :float_second
-        # @return [Numeric] timestamp in the requested unit, since some unspecified starting point
+        # @return [Float|Integer] timestamp in the requested unit, since some unspecified starting point
+        MONOTONIC_CLOCK_ID = RUBY_PLATFORM.include?("darwin") ? Process::CLOCK_MONOTONIC_RAW : Process::CLOCK_MONOTONIC
+
         def get_time(unit = :float_second)
-          Process.clock_gettime(Process::CLOCK_MONOTONIC, unit)
+          Process.clock_gettime(MONOTONIC_CLOCK_ID, unit)
         end
 
         # Current wall time.

data/lib/datadog/core/utils.rb

@@ -38,6 +38,8 @@ module Datadog
 
       # Ensure `str` is a valid UTF-8, ready to be
       # sent through the tracer transport.
+      # DEV-3.0: This method should unconditionally handle invalid byte sequences
+      # DEV-3.0: and return a safe string to display.
       #
       # @param [String,#to_s] str object to be converted to a UTF-8 string
       # @param [Boolean] binary whether to expect binary data in the `str` parameter
@@ -61,7 +63,7 @@ module Datadog
           str.encode(::Encoding::UTF_8)
         end
       rescue => e
-        Datadog.logger.debug("Error encoding string in UTF-8: #{e}")
+        Datadog.logger.debug("Error encoding string in UTF-8: #{e.class}: #{e.message}")
 
         placeholder
       end

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

@@ -8,6 +8,11 @@ module Datadog
       module Async
         # Adds threading behavior to workers
         # to run tasks asynchronously.
+        #
+        # This module is included in Polling module, and has no other
+        # direct users.
+        #
+        # @api private
         module Thread
           FORK_POLICY_STOP = :stop
           FORK_POLICY_RESTART = :restart
@@ -24,7 +29,11 @@ module Datadog
           # Methods that must be prepended
           module PrependedMethods
             def perform(*args)
-              start_async { self.result = super(*args) } unless started?
+              unless started?
+                start_async do
+                  self.result = super(*args)
+                end
+              end
             end
           end
 
@@ -159,7 +168,7 @@ module Datadog
             rescue Exception => e
               @error = e
               Datadog.logger.debug(
-                "Worker thread error. Cause: #{e.class.name} #{e.message} Location: #{Array(e.backtrace).first}"
+                "Worker thread error. Cause: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}"
               )
               raise
 

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

@@ -5,6 +5,11 @@ module Datadog
     module Workers
       # Adds looping behavior to workers, with a sleep
       # interval between each loop.
+      #
+      # This module is included in Polling module, and has no other
+      # direct users.
+      #
+      # @api private
       module IntervalLoop
         BACK_OFF_RATIO = 1.2
         BACK_OFF_MAX = 5
@@ -38,19 +43,50 @@ module Datadog
 
         def stop_loop
           mutex.synchronize do
-            return false unless run_loop?
-
+            # Do not call run_loop? from this method to see if the loop
+            # is running, because @run_loop is normally initialized by
+            # the background thread and if the stop is requested right
+            # after the worker starts, the background thread may be created
+            # (and scheduled) but hasn't run yet, thus skipping the
+            # write to @run_loop here would leave the thread running forever.
             @run_loop = false
+
+            # It is possible that we don't need to signal shutdown if
+            # @run_loop was not initialized (i.e. we changed it from not
+            # defined to false above). But let's be safe and signal the
+            # shutdown anyway, I don't see what harm it can cause.
             shutdown.signal
           end
 
+          # Previously, this method would return false (and do nothing)
+          # if the worker was not running the loop. However, this was racy -
+          # see https://github.com/DataDog/ruby-guild/issues/279.
+          # stop_loop now always sets the state to "stop requested" and,
+          # correspondingly, always returns true.
+          #
+          # There is some test code that returns false when mocking this
+          # method - most likely this method should be treated as a void one
+          # and the caller should assume that the stop was always requested.
           true
         end
 
+        # TODO: This method carries two semantics today:
+        # 1. Is there work available to process?
+        # 2. Should the main loop keep running?
+        # Things get messy when `Queue` is mixed in,
+        # wanting to override semantic 1 but not 2.
+        # This should probably be split into two methods:
+        # `work_pending?` (semantic 1) and `continue_loop?` (semantic 2).
+        # Today, `run_loop?` performs semantic 2, but should probably be
+        # renamed to `continue_loop?`, since that would make it clear that
+        # we're just checking if we can "keep going inside the loop",
+        # and not checking if we should run the loop right now.
+        # Clean up {Workers::Queue} after this.
         def work_pending?
           run_loop?
         end
 
+        # TODO: Probably should be renamed to `continue_loop?`, see `work_pending?` TODO.
         def run_loop?
           return false unless instance_variable_defined?(:@run_loop)
 
@@ -104,7 +140,19 @@ module Datadog
 
         def perform_loop
           mutex.synchronize do
-            @run_loop = true
+            unless defined?(@run_loop)
+              # This write must only happen if @run_loop is not defined
+              # (i.e., not initialized). In the case when the worker is
+              # asked to stop right after it is created, the thread may not
+              # have run yet by the time +stop_loop+ is invoked and
+              # we need to preserve the stop-requested state from
+              # +stop_loop+ to +perform_loop+.
+              #
+              # If the workers are refactored to use classes and inheritance
+              # and their state, such as @run_loop, is initialized in
+              # constructors, the write can be made unconditional.
+              @run_loop = true
+            end
 
             shutdown.wait(mutex, loop_wait_time) if loop_wait_before_first_iteration?
           end

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

@@ -7,6 +7,8 @@ module Datadog
   module Core
     module Workers
       # Adds polling (async looping) behavior to workers
+      #
+      # @api private
       module Polling
         DEFAULT_SHUTDOWN_TIMEOUT = 1
 

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

@@ -5,6 +5,17 @@ module Datadog
     module Workers
       # Adds queue behavior to workers, with a buffer
       # to which items can be queued then dequeued.
+      #
+      # This module is included in some but not all workers.
+      # Notably, Data Streams Processor uses a queue but implements it
+      # inline rather than using this module.
+      #
+      # The workers that do include Queue also include Polling, which
+      # in turn includes Async::Thread and IntervalLoop. This means
+      # we have e.g. +in_iteration?+ always available in any worker
+      # that includes Queue.
+      #
+      # @api private
       module Queue
         def self.included(base)
           base.prepend(PrependedMethods)
@@ -13,11 +24,16 @@ module Datadog
         # Methods that must be prepended
         module PrependedMethods
           def perform(*args)
-            super(*dequeue) if work_pending?
+            if work_pending?
+              work = dequeue
+              super(*work)
+            end
           end
         end
 
         def buffer
+          # Why is this an unsynchronized Array and not a Core::Buffer
+          # instance?
           @buffer ||= []
         end
 
@@ -34,10 +50,89 @@ module Datadog
           !buffer.empty?
         end
 
+        # Wait for the worker to finish handling all work that has already
+        # been submitted to it.
+        #
+        # If the worker is not enabled, returns nil.
+        # If the worker is enabled, returns whether, at the point of return,
+        # there was no pending or in progress work.
+        #
+        # Flushing can time out because there is a constant stream of work
+        # submitted at the same or higher rate than it is processed.
+        # Flushing can also fail if the worker thread is not running -
+        # this method will not flush from the calling thread.
+        def flush(timeout: nil)
+          # Default timeout is 5 seconds.
+          # Specific workers can override it to be more or less
+          timeout ||= 5
+
+          # Nothing needs to be done if the worker is not enabled.
+          return nil unless enabled?
+
+          unless running?
+            unless buffer.empty?
+              # If we are asked to flush but the worker is not running,
+              # do not flush from the caller thread. If the buffer is not
+              # empty, it will not be flushed. Log a warning to this effect.
+              #
+              # We are not guaranteed to have a logger as an instance method,
+              # reference the global for now - all other worker methods
+              # also reference the logger globally.
+              # TODO inject it into worker instances.
+              Datadog.logger.debug { "Asked to flush #{self} when the worker is not running" }
+              return false
+            end
+          end
+
+          started = Utils::Time.get_time
+          loop do
+            # The AppStarted event is triggered by the worker itself,
+            # from the worker thread. As such the main thread has no way
+            # to delay itself until that event is queued and we need some
+            # way to wait until that event is sent out to assert on it in
+            # the test suite. Check the run once flag which *should*
+            # indicate the event has been queued (at which point our queue
+            # depth check should wait until it's sent).
+            # This is still a hack because the flag can be overridden
+            # either way with or without the event being sent out.
+            # Note that if the AppStarted sending fails, this check
+            # will return false and flushing will be blocked until the
+            # 15 second timeout.
+            # Note that the first wait interval between telemetry event
+            # sending is 10 seconds, the timeout needs to be strictly
+            # greater than that.
+            return true if idle?
+
+            return false if Utils::Time.get_time - started > timeout
+
+            sleep 0.5
+          end
+        end
+
         protected
 
         attr_writer \
           :buffer
+
+        # Returns whether this worker has no pending work and is not actively
+        # working.
+        #
+        # The reason why "actively working" is considered is that we use
+        # flushing to ensure all work is completed before asserting on the
+        # outcome in the tests - if work is happening in a background thread,
+        # it's too early to assert on its results.
+        def idle?
+          # We have a +work_pending?+ method in this class that semantically
+          # would be appropriate here instead of calling +buffer.empty?+.
+          # Unfortunately IntervalLoop replaces our implementation of
+          # +work_pending?+ with one that doesn't make sense at least for the
+          # Queue. And we can't change the order of module includes because
+          # they all override +perform+ and the correct behavior depends on
+          # placing IntervalLoop after Queue.
+          #
+          # Until this mess is untangled, call +buffer.empty?+ here.
+          buffer.empty? && !in_iteration?
+        end
       end
     end
   end

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

@@ -21,7 +21,15 @@ module Datadog
           :metrics
 
         def initialize(telemetry:, **options)
-          @metrics = options.fetch(:metrics) { Core::Runtime::Metrics.new(logger: options[:logger], telemetry: telemetry) }
+          @metrics = options.fetch(:metrics) do
+            Core::Runtime::Metrics.new(
+              logger: options[:logger],
+              telemetry: telemetry,
+              experimental_propagate_process_tags_enabled: options.fetch(:propagate_process_tags_enabled) do
+                options.fetch(:experimental_propagate_process_tags_enabled)
+              end
+            )
+          end
 
           # Workers::Async::Thread settings
           self.fork_policy = options.fetch(:fork_policy, Workers::Async::Thread::FORK_POLICY_STOP)

data/lib/datadog/core.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Keep this at the top, this is needed at require-time by some files
+require_relative 'ruby_version'
+
 require_relative 'core/deprecations'
 require_relative 'core/configuration/config_helper'
 require_relative 'core/extensions'
@@ -18,20 +21,24 @@ module Datadog
         require "libdatadog_api.#{RUBY_VERSION[/\d+.\d+/]}_#{RUBY_PLATFORM}"
         nil
       rescue LoadError => e
-        e.message
+        "#{e.class}: #{e.message}"
       end
   end
 
-  DATADOG_ENV = Core::Configuration::ConfigHelper.new
   extend Core::Extensions
 
   # Add shutdown hook:
   # Ensures the Datadog components have a chance to gracefully
   # shut down and cleanup before terminating the process.
   at_exit do
-    if Interrupt === $! # rubocop:disable Style/SpecialGlobalVars is process terminating due to a ctrl+c or similar?
+    exception = $! # rubocop:disable Style/SpecialGlobalVars
+
+    if Interrupt === exception # is process terminating due to a ctrl+c or similar?
       Datadog.send(:handle_interrupt_shutdown!)
     else
+      # Report unhandled exception to crash tracker before shutdown
+      Datadog::Core::Crashtracking::Component.report_unhandled_exception(exception)
+
       Datadog.shutdown!
     end
   end

data/lib/datadog/data_streams/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative '../core/environment/variable_helpers'
+require_relative 'ext'
+
+module Datadog
+  module DataStreams
+    # Configuration for Data Streams Monitoring
+    module Configuration
+      # Configuration settings for Data Streams Monitoring.
+      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
+            # Data Streams Monitoring configuration
+            # @public_api
+            settings :data_streams do
+              # Whether Data Streams Monitoring is enabled. When enabled, the library will
+              # collect and report data lineage information for messaging systems.
+              #
+              # @default `DD_DATA_STREAMS_ENABLED` environment variable, otherwise `false`.
+              # @return [Boolean]
+              option :enabled do |o|
+                o.type :bool
+                o.env Ext::ENV_ENABLED
+                o.default false
+              end
+
+              # The interval (in seconds) at which Data Streams Monitoring stats are flushed.
+              #
+              # @default 10.0
+              # @env '_DD_TRACE_STATS_WRITER_INTERVAL'
+              # @return [Float]
+              # @!visibility private
+              option :interval do |o|
+                o.type :float
+                o.env '_DD_TRACE_STATS_WRITER_INTERVAL'
+                o.default 10.0
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/data_streams/ext.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Datadog
+  module DataStreams
+    # Constants for Data Streams Monitoring configuration
+    # @public_api
+    module Ext
+      ENV_ENABLED = 'DD_DATA_STREAMS_ENABLED'
+    end
+  end
+end

data/lib/datadog/data_streams/extensions.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'configuration'
+require_relative '../core/configuration'
+
+module Datadog
+  module DataStreams
+    # Extends Datadog with Data Streams Monitoring features
+    module Extensions
+      # Inject Data Streams settings into global configuration.
+      def self.activate!
+        Core::Configuration::Settings.extend(Configuration::Settings)
+      end
+    end
+  end
+end

data/lib/datadog/data_streams/pathway_context.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require_relative '../core/utils/base64_codec'
+
+module Datadog
+  module DataStreams
+    # Represents a pathway context for data streams monitoring
+    class PathwayContext
+      # The current pathway hash value (result of FNV-1a hash function)
+      attr_accessor :hash
+      # When the pathway started
+      attr_accessor :pathway_start
+      # When the current edge started
+      attr_accessor :current_edge_start
+      # The hash value of the parent checkpoint
+      attr_accessor :parent_hash
+      # The direction tag of the previous checkpoint (e.g., 'direction:in', 'direction:out'), or nil if none
+      attr_accessor :previous_direction
+      # Hash value of the closest checkpoint in opposite direction (used for loop detection)
+      attr_accessor :closest_opposite_direction_hash
+      # Edge start time of the closest opposite direction checkpoint
+      attr_accessor :closest_opposite_direction_edge_start
+
+      def initialize(hash_value:, pathway_start:, current_edge_start:)
+        @hash = hash_value
+        @pathway_start = pathway_start
+        @current_edge_start = current_edge_start
+        @parent_hash = nil
+
+        @previous_direction = nil
+        @closest_opposite_direction_hash = 0
+        @closest_opposite_direction_edge_start = current_edge_start
+      end
+
+      def encode_b64
+        Core::Utils::Base64Codec.strict_encode64(encode)
+      end
+
+      # Decode pathway context from base64 encoded string
+      def self.decode_b64(encoded_ctx)
+        return nil unless encoded_ctx && !encoded_ctx.empty?
+
+        begin
+          binary_data = Core::Utils::Base64Codec.strict_decode64(encoded_ctx)
+          decode(binary_data)
+        rescue ArgumentError => e
+          # Invalid base64 encoding - may indicate version mismatch or corruption
+          Datadog.logger.debug { "Failed to decode DSM pathway context: #{e.class}: #{e.message}" }
+          nil
+        end
+      end
+
+      private
+
+      def encode
+        # Format:
+        # - 8 bytes: hash value (little-endian)
+        # - VarInt: pathway start time (milliseconds)
+        # - VarInt: current edge start time (milliseconds)
+        [@hash].pack('Q') <<
+          encode_var_int_64(time_to_ms(@pathway_start)) <<
+          encode_var_int_64(time_to_ms(@current_edge_start))
+      end
+
+      # Decode pathway context from binary data
+      def self.decode(binary_data)
+        return nil unless binary_data && binary_data.bytesize >= 8
+
+        reader = StringIO.new(binary_data)
+
+        # Extract 8-byte hash (little-endian)
+        hash_bytes = reader.read(8)
+        return nil unless hash_bytes
+
+        hash_value = hash_bytes.unpack1('Q') # : Integer
+
+        # Extract pathway start time (VarInt milliseconds)
+        pathway_start_ms = decode_varint(reader)
+        return nil unless pathway_start_ms
+
+        # Extract current edge start time (VarInt milliseconds)
+        current_edge_start_ms = decode_varint(reader)
+        return nil unless current_edge_start_ms
+
+        # Convert milliseconds to Time objects
+        pathway_start = ms_to_time(pathway_start_ms)
+        current_edge_start = ms_to_time(current_edge_start_ms)
+
+        new(
+          hash_value: hash_value,
+          pathway_start: pathway_start,
+          current_edge_start: current_edge_start
+        )
+      rescue EOFError
+        # Not enough data in binary stream
+        nil
+      end
+      private_class_method :decode
+
+      # Encode an unsigned 64-bit integer using LEB128 variable-length encoding.
+      #
+      # This implements unsigned LEB128 (Little Endian Base 128) encoding as specified
+      # in DWARF5 standard section 7.6:
+      # https://dwarfstd.org/doc/DWARF5.pdf#page=301
+      #
+      # Each byte uses 7 bits for data and 1 bit to indicate continuation.
+      # The high bit is set if more bytes follow, clear for the final byte.
+      #
+      # @param value [Integer] Unsigned integer value to encode
+      # @return [String] Binary string of encoded bytes
+      def encode_var_int_64(value)
+        bytes = []
+        while value >= 0x80
+          bytes << ((value & 0x7F) | 0x80)
+          value >>= 7
+        end
+        bytes << value
+        bytes.pack('C*')
+      end
+
+      # Decode an unsigned LEB128 variable-length integer from IO stream.
+      #
+      # This implements unsigned LEB128 (Little Endian Base 128) decoding as specified
+      # in DWARF5 standard section 7.6:
+      # https://dwarfstd.org/doc/DWARF5.pdf#page=301
+      #
+      # VarInt format: Each byte uses 7 bits for data, 1 bit for continuation
+      # - High bit set = more bytes follow
+      # - High bit clear = final byte
+      # - Data bits accumulated in little-endian order
+      #
+      # @param io [StringIO] IO stream to read from
+      # @return [Integer, nil] Decoded unsigned integer, or nil if malformed
+      def self.decode_varint(io)
+        value = 0
+        shift = 0
+
+        loop do
+          byte = io.readbyte
+
+          # Add this byte's 7 data bits to our value
+          value |= (byte & 0x7F) << shift
+
+          # If high bit is clear, we're done
+          return value unless (byte & 0x80).nonzero?
+
+          shift += 7
+
+          # Safety: prevent infinite decoding
+          return nil if shift >= 64
+        end
+      rescue EOFError
+        # Stream ended unexpectedly - malformed data
+        nil
+      end
+      private_class_method :decode_varint
+
+      def self.ms_to_time(milliseconds)
+        ::Time.at(milliseconds / 1000.0)
+      end
+      private_class_method :ms_to_time
+
+      def time_to_ms(time)
+        (time.to_f * 1000).to_i
+      end
+    end
+  end
+end