datadog 2.8.0 → 2.39.0

data/lib/datadog/tracing/span_event.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'time'
+require "time"
 
 module Datadog
   module Tracing
@@ -19,23 +19,143 @@ module Datadog
       #   @return [Integer]
       attr_reader :time_unix_nano
 
+      # TODO: Accept {Time} as the time_unix_nano parameter, possibly in addition to the current nano integer.
       def initialize(
         name,
         attributes: nil,
         time_unix_nano: nil
       )
         @name = name
-        @attributes = attributes || {}
+
+        @attributes = attributes.dup || {}
+        validate_attributes!(@attributes)
+        @attributes.transform_keys!(&:to_s)
+
         # OpenTelemetry SDK stores span event timestamps in nanoseconds (not seconds).
         # We will do the same here to avoid unnecessary conversions and inconsistencies.
-        @time_unix_nano = time_unix_nano || (Time.now.to_r * 1_000_000_000).to_i
+        @time_unix_nano = time_unix_nano || (Core::Utils::Time.now.to_r * 1_000_000_000).to_i
       end
 
+      # Converts the span event into a hash to be used by with the span tag serialization
+      # (`span.set_tag('events) = [event.to_hash]`). This serialization format has the drawback
+      # of being limiting span events to the size limit of a span tag.
+      # All Datadog agents support this format.
       def to_hash
-        h = { name: @name, time_unix_nano: @time_unix_nano }
-        h[:attributes] = attributes unless @attributes.empty?
+        h = {"name" => @name, "time_unix_nano" => @time_unix_nano}
+        h["attributes"] = @attributes unless @attributes.empty?
+        h
+      end
+
+      # Converts the span event into a hash to be used by the MessagePack serialization as a
+      # top-level span field (span.span_events = [event.to_native_format]).
+      # This serialization format removes the serialization limitations of the `span.set_tag('events)` approach,
+      # but is only supported by newer version of the Datadog agent.
+      def to_native_format
+        h = {"name" => @name, "time_unix_nano" => @time_unix_nano}
+
+        attr = {}
+        @attributes.each do |key, value|
+          attr[key] = if value.is_a?(Array)
+            {type: ARRAY_TYPE, array_value: {values: value.map { |v| serialize_native_attribute(v) }}}
+          else
+            serialize_native_attribute(value)
+          end
+        end
+
+        h["attributes"] = attr unless @attributes.empty?
+
         h
       end
+
+      private
+
+      MIN_INT64_SIGNED = -2 << 62
+      MAX_INT64_SIGNED = (2 << 62) - 1
+
+      # Checks the attributes hash to ensure it only contains serializable values.
+      # Invalid values are removed from the hash.
+      def validate_attributes!(attributes)
+        attributes.select! do |key, value|
+          case value
+          when Array
+            next true if value.empty?
+
+            first = value.first
+            case first
+            when String, Integer, Float
+              first_type = first.class
+              if value.all? { |v| v.is_a?(first_type) }
+                value.all? { |v| validate_scalar_attribute!(key, v) }
+              else
+                Datadog.logger.warn("Attribute #{key} array must be homogenous: #{value}.")
+                false
+              end
+            when TrueClass, FalseClass
+              if value.all? { |v| v.is_a?(TrueClass) || v.is_a?(FalseClass) }
+                value.all? { |v| validate_scalar_attribute!(key, v) }
+              else
+                Datadog.logger.warn("Attribute #{key} array must be homogenous: #{value}.")
+                false
+              end
+            else
+              Datadog.logger.warn("Attribute #{key} must be a string, number, or boolean: #{value}.")
+              false
+            end
+          when String, Numeric, TrueClass, FalseClass
+            validate_scalar_attribute!(key, value)
+          else
+            Datadog.logger.warn("Attribute #{key} must be a string, number, boolean, or array: #{value}.")
+            false
+          end
+        end
+      end
+
+      def validate_scalar_attribute!(key, value)
+        case value
+        when String, TrueClass, FalseClass
+          true
+        when Integer
+          # Cannot be larger than signed 64-bit integer
+          if value < MIN_INT64_SIGNED || value > MAX_INT64_SIGNED
+            Datadog.logger.warn("Attribute #{key} must be within the range of a signed 64-bit integer: #{value}.")
+            false
+          else
+            true
+          end
+        when Float
+          # Has to be finite
+          return true if value.finite?
+
+          Datadog.logger.warn("Attribute #{key} must be a finite number: #{value}.")
+          false
+        else
+          Datadog.logger.warn("Attribute #{key} must be a string, number, or boolean: #{value}.")
+          false
+        end
+      end
+
+      STRING_TYPE = 0
+      BOOLEAN_TYPE = 1
+      INTEGER_TYPE = 2
+      DOUBLE_TYPE = 3
+      ARRAY_TYPE = 4
+
+      # Serializes individual scalar attributes into the native format.
+      def serialize_native_attribute(value)
+        case value
+        when String
+          {type: STRING_TYPE, string_value: value}
+        when TrueClass, FalseClass
+          {type: BOOLEAN_TYPE, bool_value: value}
+        when Integer
+          {type: INTEGER_TYPE, int_value: value}
+        when Float
+          {type: DOUBLE_TYPE, double_value: value}
+        else
+          # This is technically unreachable due to the validation in #initialize.
+          raise ArgumentError, "Attribute must be a string, number, or boolean: #{value}."
+        end
+      end
     end
   end
 end

data/lib/datadog/tracing/span_link.rb

@@ -47,15 +47,15 @@ module Datadog
         @span_id = digest.span_id
         @trace_id = digest.trace_id
         @trace_flags = if digest.trace_sampling_priority.nil?
-                         nil
-                       elsif digest.trace_sampling_priority > 0
-                         1
-                       else
-                         0
-                       end
-        @trace_state = digest.trace_state && digest.trace_state.dup
+          nil
+        elsif digest.trace_sampling_priority > 0
+          1
+        else
+          0
+        end
+        @trace_state = digest.trace_state&.dup
         @dropped_attributes = 0
-        @attributes = (attributes && attributes.dup) || {}
+        @attributes = attributes&.dup || {}
       end
 
       def to_hash
@@ -81,10 +81,10 @@ module Datadog
         # If traceflags set, the high bit (bit 31) should be set to 1 (uint32).
         # This helps us distinguish between when the sample decision is zero or not set
         h[:flags] = if @trace_flags.nil?
-                      0
-                    else
-                      @trace_flags | (1 << 31)
-                    end
+          0
+        else
+          @trace_flags | (1 << 31)
+        end
         h
       end
     end

data/lib/datadog/tracing/span_operation.rb

@@ -1,17 +1,19 @@
 # frozen_string_literal: true
 
-require 'time'
+require "time"
 
-require_relative '../core/environment/identity'
-require_relative '../core/utils'
-require_relative '../core/utils/time'
-require_relative '../core/utils/safe_dup'
+require_relative "../core/environment/identity"
+require_relative "../core/utils"
+require_relative "../core/utils/time"
+require_relative "../core/utils/safe_dup"
 
-require_relative 'event'
-require_relative 'metadata'
-require_relative 'metadata/ext'
-require_relative 'span'
-require_relative 'utils'
+require_relative "event"
+require_relative "metadata"
+require_relative "metadata/ext"
+require_relative "span"
+require_relative "span_event"
+require_relative "span_link"
+require_relative "utils"
 
 module Datadog
   module Tracing
@@ -26,6 +28,7 @@ module Datadog
       # Span attributes
       # NOTE: In the future, we should drop the me
       attr_reader \
+        :logger,
         :end_time,
         :id,
         :name,
@@ -35,10 +38,12 @@ module Datadog
         :start_time,
         :trace_id,
         :type
+
       attr_accessor :links, :status, :span_events
 
       def initialize(
         name,
+        logger: Datadog.logger,
         events: nil,
         on_error: nil,
         parent_id: 0,
@@ -52,6 +57,8 @@ module Datadog
         span_events: nil,
         id: nil
       )
+        @logger = logger
+
         # Ensure dynamically created strings are UTF-8 encoded.
         #
         # All strings created in Ruby land are UTF-8. The only sources of non-UTF-8 string are:
@@ -88,11 +95,17 @@ module Datadog
         set_tags(tags) if tags
 
         # Some other SpanOperation-specific behavior
-        @events = events || Events.new
+        @events = events || Events.new(logger: logger)
         @span = nil
 
-        # Subscribe :on_error event
-        @events.on_error.wrap_default(&on_error) if on_error.is_a?(Proc)
+        if on_error.nil?
+          # Nothing, default error handler is already set up.
+        elsif on_error.is_a?(Proc)
+          # Subscribe :on_error event
+          @events.on_error.wrap_default(&on_error)
+        else
+          logger.warn("on_error argument to SpanOperation ignored because is not a Proc: #{on_error}")
+        end
 
         # Start the span with start time, if given.
         start(start_time) if start_time
@@ -128,8 +141,12 @@ module Datadog
         @resource = resource.nil? ? nil : Core::Utils.utf8_encode(resource) # Allow this to be explicitly set to nil
       end
 
+      def get_collector_or_initialize
+        @collector ||= yield
+      end
+
       def measure
-        raise ArgumentError, 'Must provide block to measure!' unless block_given?
+        raise ArgumentError, "Must provide block to measure!" unless block_given?
         # TODO: Should we just invoke the block and skip tracing instead?
         raise AlreadyStartedError if started?
 
@@ -140,13 +157,15 @@ module Datadog
           # running, to minimize impact on normal application function.
           begin
             start
-          rescue StandardError => e
-            Datadog.logger.debug { "Failed to start span: #{e}" }
+          rescue => e
+            logger.debug { "Failed to start span: #{e.class}: #{e.message}" }
           ensure
             # We should yield to the provided block when possible, as this
             # block is application code that we don't want to hinder.
             # * We don't yield during a fatal error, as the application is likely trying to
             #   end its execution (either due to a system error or graceful shutdown).
+            # @type var e: Exception?
+            # Steep: https://github.com/soutaro/steep/issues/919
             return_value = yield(self) unless e && !e.is_a?(StandardError)
           end
         # rubocop:disable Lint/RescueException
@@ -159,7 +178,7 @@ module Datadog
           # Stop the span first, so timing is a more accurate.
           # If the span failed to start, timing may be inaccurate,
           # but this is not really a serious concern.
-          stop
+          stop(exception: e)
 
           # Trigger the on_error event
           events.on_error.publish(self, e)
@@ -197,7 +216,7 @@ module Datadog
       end
 
       # Mark the span stopped at the current time
-      def stop(stop_time = nil)
+      def stop(stop_time = nil, exception: nil)
         # A span should not be stopped twice. Note that this is not thread-safe,
         # stop is called from multiple threads, a given span might be stopped
         # several times. Again, one should not do this, so this test is more a
@@ -215,7 +234,7 @@ module Datadog
         @duration_end = stop_time.nil? ? duration_marker : nil
 
         # Trigger after_stop event
-        events.after_stop.publish(self)
+        events.after_stop.publish(self, exception)
 
         self
       end
@@ -230,6 +249,10 @@ module Datadog
         !@end_time.nil?
       end
 
+      def root?
+        parent_id == 0
+      end
+
       # for backwards compatibility
       def start_time=(time)
         time.tap { start(time) }
@@ -247,6 +270,9 @@ module Datadog
         # Stop timing
         stop(end_time)
 
+        # Allow subscribers to enrich the span before it is finalized.
+        events.before_finish.publish(self)
+
         # Build span
         # Memoize for performance reasons
         @span = build_span
@@ -262,8 +288,15 @@ module Datadog
       end
 
       def duration
+        # Steep: https://github.com/soutaro/steep/issues/477
+        # @type ivar @duration_end: Time
+        # @type ivar @duration_start: Time
         return @duration_end - @duration_start if @duration_start && @duration_end
-        return @end_time - @start_time if @start_time && @end_time
+
+        # Steep: https://github.com/soutaro/steep/issues/477
+        # @type ivar @end_time: Time
+        # @type ivar @start_time: Time
+        @end_time - @start_time if @start_time && @end_time
       end
 
       def set_error(e)
@@ -271,6 +304,30 @@ module Datadog
         set_error_tags(e)
       end
 
+      # Record an exception during the execution of this span. Multiple exceptions
+      # can be recorded on a span.
+      #
+      # @param [Exception] exception The exception to record
+      # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+      #   attributes One or more key:value pairs, where the keys must be
+      #   strings and the values may be (array of) string, boolean or numeric
+      #   type.
+      #
+      # @return [void]
+      def record_exception(exception, attributes: {})
+        exc = Core::Error.build_from(exception)
+
+        event_attributes = {
+          "exception.type" => exc.type,
+          "exception.message" => exc.message,
+          "exception.stacktrace" => exc.backtrace,
+        }
+
+        # Steep: Caused by wrong declaration, should be the same parameters as `merge`
+        # https://github.com/ruby/rbs/blob/3d0fb3a7fdde60af7120e875fe3bd7237b5b6a88/core/hash.rbs#L1468
+        @span_events << SpanEvent.new("exception", attributes: event_attributes.merge!(attributes)) # steep:ignore ArgumentTypeMismatch
+      end
+
       # Return a string representation of the span.
       def to_s
         "SpanOperation(name:#{@name},sid:#{@id},tid:#{@trace_id},pid:#{@parent_id})"
@@ -283,6 +340,7 @@ module Datadog
           id: @id,
           meta: meta,
           metrics: metrics,
+          metastruct: metastruct,
           name: @name,
           parent_id: @parent_id,
           resource: @resource,
@@ -316,18 +374,21 @@ module Datadog
           q.text "Start: #{start_time}\n"
           q.text "End: #{end_time}\n"
           q.text "Duration: #{duration.to_f if stopped?}\n"
-          q.group(2, 'Tags: [', "]\n") do
+          q.group(2, "Tags: [", "]\n") do
             q.breakable
             q.seplist meta.each do |key, value|
               q.text "#{key} => #{value}"
             end
           end
-          q.group(2, 'Metrics: [', ']') do
+          q.group(2, "Metrics: [", "]\n") do
             q.breakable
             q.seplist metrics.each do |key, value|
               q.text "#{key} => #{value}"
             end
           end
+          q.group(2, "Metastruct: [", "]") do
+            metastruct.pretty_print(q)
+          end
         end
       end
 
@@ -335,23 +396,28 @@ module Datadog
       class Events
         include Tracing::Events
 
-        DEFAULT_ON_ERROR = proc { |span_op, error| span_op.set_error(error) unless span_op.nil? }
+        # Steep: https://github.com/soutaro/steep/issues/335
+        DEFAULT_ON_ERROR = proc { |span_op, error| span_op&.set_error(error) } # steep:ignore IncompatibleAssignment
 
         attr_reader \
+          :logger,
           :after_finish,
           :after_stop,
+          :before_finish,
           :before_start
 
-        def initialize(on_error: nil)
+        def initialize(logger: Datadog.logger)
+          @logger = logger
           @after_finish = AfterFinish.new
           @after_stop = AfterStop.new
+          @before_finish = BeforeFinish.new
           @before_start = BeforeStart.new
         end
 
         # This event is lazily initialized as error paths
         # are normally less common that non-error paths.
         def on_error
-          @on_error ||= OnError.new(DEFAULT_ON_ERROR)
+          @on_error ||= OnError.new(DEFAULT_ON_ERROR, logger: logger)
         end
 
         # Triggered when the span is finished, regardless of error.
@@ -368,6 +434,14 @@ module Datadog
           end
         end
 
+        # Triggered just before the span is finalized into a Span object.
+        # Subscribers can still mutate tags on the SpanOperation at this point.
+        class BeforeFinish < Tracing::Event
+          def initialize
+            super(:before_finish)
+          end
+        end
+
         # Triggered just before the span is started.
         class BeforeStart < Tracing::Event
           def initialize
@@ -377,10 +451,13 @@ module Datadog
 
         # Triggered when the span raises an error during measurement.
         class OnError
-          def initialize(default)
+          def initialize(default, logger: Datadog.logger)
             @handler = default
+            @logger = logger
           end
 
+          attr_reader :logger
+
           # Call custom error handler but fallback to default behavior on failure.
 
           # DEV: Revisit this before full 1.0 release.
@@ -391,25 +468,23 @@ module Datadog
             original = @handler
 
             @handler = proc do |op, error|
-              begin
-                yield(op, error)
-              rescue StandardError => e
-                Datadog.logger.debug do
-                  "Custom on_error handler #{@handler} failed, using fallback behavior. \
-                  Cause: #{e.class.name} #{e.message} Location: #{Array(e.backtrace).first}"
-                end
-
-                original.call(op, error) if original
+              yield(op, error)
+            rescue => e
+              logger.debug do
+                "Custom on_error handler #{@handler} failed, using fallback behavior. \
+                  Cause: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}"
               end
+
+              original&.call(op, error)
             end
           end
 
           def publish(*args)
             begin
               @handler.call(*args)
-            rescue StandardError => e
-              Datadog.logger.debug do
-                "Error in on_error handler '#{@default}': #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+            rescue => e
+              logger.debug do
+                "Error in on_error handler '#{@handler}': #{e.class}: #{e.message} at #{Array(e.backtrace).first}"
               end
             end
 
@@ -421,7 +496,7 @@ module Datadog
       # Error when the span attempts to start again after being started
       class AlreadyStartedError < StandardError
         def message
-          'Cannot measure an already started span!'
+          "Cannot measure an already started span!"
         end
       end
 
@@ -450,6 +525,7 @@ module Datadog
           id: @id,
           meta: Core::Utils::SafeDup.frozen_or_dup(meta),
           metrics: Core::Utils::SafeDup.frozen_or_dup(metrics),
+          metastruct: Core::Utils::SafeDup.frozen_or_dup(metastruct),
           parent_id: @parent_id,
           resource: @resource,
           service: @service,
@@ -492,6 +568,10 @@ module Datadog
       # Used for serialization
       # @return [Integer] in nanoseconds since Epoch
       def start_time_nano
+        return 0 if @start_time.nil?
+
+        # Steep: https://github.com/soutaro/steep/issues/477
+        # @type ivar @start_time: Time
         @start_time.to_i * 1000000000 + @start_time.nsec
       end
 

data/lib/datadog/tracing/sync_writer.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
-require_relative 'pipeline'
-require_relative 'runtime/metrics'
-require_relative 'writer'
+require_relative "pipeline"
+require_relative "runtime/metrics"
+require_relative "writer"
 
-require_relative 'transport/http'
+require_relative "transport/http"
 
 module Datadog
   module Tracing
     # SyncWriter flushes both services and traces synchronously
-    # DEV: To be replaced by Datadog::Tracing::Workers::TraceWriter.
     #
     # Note: If you're wondering if this class is used at all, since there are no other references to it on the codebase,
     # the separate `datadog-lambda` uses it as of February 2021:
@@ -17,18 +16,22 @@ module Datadog
     # @public_api
     class SyncWriter
       attr_reader \
+        :logger,
         :events,
-        :transport
+        :transport,
+        :agent_settings
 
       # @param [Datadog::Tracing::Transport::Traces::Transport] transport a custom transport instance.
       #   If provided, overrides `transport_options` and `agent_settings`.
       # @param [Hash<Symbol,Object>] transport_options options for the default transport instance.
-      # @param [Datadog::Tracing::Configuration::AgentSettingsResolver::AgentSettings] agent_settings agent options for
+      # @param [Datadog::Tracing::Configuration::AgentSettings] agent_settings agent options for
       #   the default transport instance.
-      def initialize(transport: nil, transport_options: {}, agent_settings: nil)
+      def initialize(transport: nil, transport_options: {}, agent_settings: nil, logger: Datadog.logger)
+        @logger = logger
+        @agent_settings = agent_settings
+
         @transport = transport || begin
-          transport_options[:agent_settings] = agent_settings if agent_settings
-          Transport::HTTP.default(**transport_options)
+          Transport::HTTP.default(agent_settings: agent_settings, logger: logger, **transport_options)
         end
 
         @events = Writer::Events.new
@@ -40,7 +43,7 @@ module Datadog
       def write(trace)
         flush_trace(trace)
       rescue => e
-        Datadog.logger.debug(e)
+        logger.debug(e)
       end
 
       # Does nothing.