datadog 2.21.0 → 2.38.0

data/lib/datadog/tracing/span_event.rb

@@ -69,8 +69,8 @@ module Datadog
 
       private
 
-      MIN_INT64_SIGNED = -2**63
-      MAX_INT64_SIGNED = 2 << 63 - 1
+      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.

data/lib/datadog/tracing/span_operation.rb

@@ -158,12 +158,14 @@ module Datadog
           begin
             start
           rescue => e
-            logger.debug { "Failed to start span: #{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
@@ -214,9 +216,6 @@ module Datadog
       end
 
       # Mark the span stopped at the current time
-      #
-      # steep:ignore:start
-      # Steep issue fixed in https://github.com/soutaro/steep/pull/1467
       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
@@ -239,7 +238,6 @@ module Datadog
 
         self
       end
-      # steep:ignore:end
 
       # Return whether the duration is started or not
       def started?
@@ -272,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
@@ -287,8 +288,14 @@ 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
 
+        # 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
 
@@ -316,7 +323,9 @@ module Datadog
           'exception.stacktrace' => exc.backtrace,
         }
 
-        @span_events << SpanEvent.new('exception', attributes: event_attributes.merge!(attributes)) # steep:ignore
+        # 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.
@@ -387,18 +396,21 @@ module Datadog
       class Events
         include Tracing::Events
 
-        DEFAULT_ON_ERROR = proc { |span_op, error| span_op&.set_error(error) }
+        # 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(logger: Datadog.logger, 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
 
@@ -422,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
@@ -452,7 +472,7 @@ module Datadog
             rescue => e
               logger.debug do
                 "Custom on_error handler #{@handler} failed, using fallback behavior. \
-                  Cause: #{e.class}: #{e} Location: #{Array(e.backtrace).first}"
+                  Cause: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}"
               end
 
               original&.call(op, error)
@@ -464,7 +484,7 @@ module Datadog
               @handler.call(*args)
             rescue => e
               logger.debug do
-                "Error in on_error handler '#{@default}': #{e.class}: #{e} at #{Array(e.backtrace).first}"
+                "Error in on_error handler '#{@handler}': #{e.class}: #{e.message} at #{Array(e.backtrace).first}"
               end
             end
 
@@ -548,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

@@ -9,7 +9,6 @@ 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:

data/lib/datadog/tracing/trace_digest.rb

@@ -22,6 +22,9 @@ module Datadog
       # @!attribute [r] span_type
       #   The type of the currently active span.
       #   @return [String]
+      # @!attribute [r] span_links
+      #   Span links associated with this trace context.
+      #   @return [Array<Datadog::Tracing::SpanLink>, nil]
       # @!attribute [r] trace_distributed_tags
       #   Datadog-specific tags that support richer distributed tracing association.
       #   @return [Hash<String,String>]
@@ -91,6 +94,7 @@ module Datadog
         :span_resource,
         :span_service,
         :span_type,
+        :span_links,
         :trace_distributed_tags,
         :trace_hostname,
         :trace_id,
@@ -114,6 +118,7 @@ module Datadog
         span_resource: nil,
         span_service: nil,
         span_type: nil,
+        span_links: nil,
         trace_distributed_tags: nil,
         trace_hostname: nil,
         trace_id: nil,
@@ -136,6 +141,7 @@ module Datadog
         @span_resource = span_resource && span_resource.dup.freeze
         @span_service = span_service && span_service.dup.freeze
         @span_type = span_type && span_type.dup.freeze
+        @span_links = span_links && span_links.dup.freeze
         @trace_distributed_tags = trace_distributed_tags && trace_distributed_tags.dup.freeze
         @trace_hostname = trace_hostname && trace_hostname.dup.freeze
         @trace_id = trace_id
@@ -167,6 +173,7 @@ module Datadog
           span_resource: span_resource,
           span_service: span_service,
           span_type: span_type,
+          span_links: span_links,
           trace_distributed_tags: trace_distributed_tags,
           trace_hostname: trace_hostname,
           trace_id: trace_id,

data/lib/datadog/tracing/trace_operation.rb

@@ -27,6 +27,8 @@ module Datadog
       include Metadata::Tagging
 
       DEFAULT_MAX_LENGTH = 100_000
+      AUTO_SAMPLING_PRIORITIES = [Sampling::Ext::Priority::AUTO_KEEP, Sampling::Ext::Priority::AUTO_REJECT].freeze
+      RECONSIDERABLE_DECISIONS = [Sampling::Ext::Decision::DEFAULT, Sampling::Ext::Decision::AGENT_RATE].freeze
 
       attr_accessor \
         :agent_sample_rate,
@@ -51,10 +53,16 @@ module Datadog
 
       attr_writer \
         :name,
-        :resource,
         :sampled,
         :service
 
+      # Creates a new TraceOperation.
+      #
+      # @param span_links [Array<Datadog::Tracing::SpanLink>, nil] links to attach to the local root span.
+      # @param auto_finish [Boolean] when true, automatically finishes the trace when the local root span finishes.
+      #   When false, the trace remains unfinished until {#finish!} is called.
+      #   This is useful when this {TraceOperation} represents the continuation of a remote {TraceDigest},
+      #   in which case local root spans in this {TraceOperation} are children of the {TraceDigest}'s last active span.
       def initialize(
         logger: Datadog.logger,
         agent_sample_rate: nil,
@@ -65,6 +73,7 @@ module Datadog
         name: nil,
         origin: nil,
         parent_span_id: nil,
+        span_links: nil,
         rate_limiter_rate: nil,
         resource: nil,
         rule_sample_rate: nil,
@@ -80,7 +89,8 @@ module Datadog
         trace_state_unknown_fields: nil,
         remote_parent: false,
         tracer: nil, # DEV-3.0: deprecated, remove in 3.0
-        baggage: nil
+        baggage: nil,
+        auto_finish: true
       )
         @logger = logger
 
@@ -90,7 +100,7 @@ module Datadog
         @parent_span_id = parent_span_id
         @sampled = sampled.nil? || sampled
         @remote_parent = remote_parent
-
+        @span_links = span_links
         # Tags
         @agent_sample_rate = agent_sample_rate
         @hostname = hostname
@@ -119,6 +129,9 @@ module Datadog
         @events = events || Events.new
         @finished = false
         @spans = []
+        @auto_finish = !!auto_finish
+        @flushed = false
+        @propagated = false
       end
 
       def full?
@@ -162,6 +175,17 @@ module Datadog
         set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, Tracing::Sampling::Ext::Decision::MANUAL)
       end
 
+      def resource=(value)
+        previous_resource = @resource
+        @resource = value
+
+        return if !!previous_resource || value.nil?
+
+        events.trace_resource_change.publish(self)
+      rescue => e
+        logger.debug { "Error updating trace resource: #{e.class}: #{e.message} Backtrace: #{e.backtrace.first(3)}" }
+      end
+
       def name
         @name || root_span&.name
       end
@@ -200,6 +224,12 @@ module Datadog
         !@resource.nil?
       end
 
+      def reconsider_resource_sample?
+        return false if @resource.nil?
+
+        reconsider_rule_sample?
+      end
+
       def service
         @service || root_span&.service
       end
@@ -266,15 +296,20 @@ module Datadog
         parent_id = parent ? parent.id : @parent_span_id || 0
 
         # Build events
-        events ||= SpanOperation::Events.new(logger: logger)
+        span_events = events || SpanOperation::Events.new(logger: logger)
 
         # Before start: activate the span, publish events.
-        events.before_start.subscribe do |span_op|
+        span_events.before_start.subscribe do |span_op|
           start_span(span_op)
         end
 
+        # Before finish: allow enrichment before the span is finalized, publish events.
+        span_events.before_finish.subscribe do |span_op|
+          before_finish_span(span_op)
+        end
+
         # After finish: deactivate the span, record, publish events.
-        events.after_finish.subscribe do |span, span_op|
+        span_events.after_finish.subscribe do |span, span_op|
           finish_span(span, span_op, parent)
         end
 
@@ -282,9 +317,10 @@ module Datadog
         SpanOperation.new(
           op_name,
           logger: logger,
-          events: events,
+          events: span_events,
           on_error: on_error,
           parent_id: parent_id,
+          links: (@root_span.nil? ? @span_links : nil),
           resource: resource || op_name,
           service: service,
           start_time: start_time,
@@ -294,7 +330,7 @@ module Datadog
           id: id
         )
       rescue => e
-        logger.debug { "Failed to build new span: #{e}" }
+        logger.debug { "Failed to build new span: #{e.class}: #{e.message}" }
 
         # Return dummy span
         SpanOperation.new(op_name, logger: logger)
@@ -311,6 +347,7 @@ module Datadog
         # Copy out completed spans
         spans = @spans.dup
         @spans = []
+        @flushed = true
 
         spans = yield(spans) if block_given?
 
@@ -318,6 +355,29 @@ module Datadog
         build_trace(spans, !finished)
       end
 
+      # When automatic context management is disabled (@auto_finish is false),
+      # this method finishes the trace, marking it as completed.
+      #
+      # The trace will **not** automatically finish when its local root span
+      # when @auto_finish is false, thus calling this method is mandatory
+      # in such scenario.
+      #
+      # Unfinished spans are discarded.
+      #
+      # This method is idempotent and safe to call after the trace is finished.
+      # It is also a no-op when @auto_finish is true, to prevent misuse.
+      #
+      # @!visibility private
+      def finish!
+        return if @auto_finish || finished?
+
+        @finished = true
+        @active_span = nil
+        @active_span_count = 0
+
+        events.trace_finished.publish(self)
+      end
+
       # Returns a set of trace headers used for continuing traces.
       # Used for propagation across execution contexts.
       # Data should reflect the active state of the trace.
@@ -328,6 +388,7 @@ module Datadog
         span_id = @active_span&.id
         span_id ||= @parent_span_id unless finished?
         # sample the trace_operation with the tracer
+        @propagated = true
         events.trace_propagated.publish(self)
 
         TraceDigest.new(
@@ -396,16 +457,28 @@ module Datadog
         include Tracing::Events
 
         attr_reader \
+          :span_before_finish,
           :span_before_start,
           :span_finished,
           :trace_finished,
-          :trace_propagated
+          :trace_propagated,
+          :trace_resource_change
 
         def initialize
+          @span_before_finish = SpanBeforeFinish.new
           @span_before_start = SpanBeforeStart.new
           @span_finished = SpanFinished.new
           @trace_finished = TraceFinished.new
           @trace_propagated = TracePropagated.new
+          @trace_resource_change = TraceResourceChange.new
+        end
+
+        # Triggered just before a span is finalized, mirroring SpanOperation::Events::BeforeFinish.
+        # Subscribers can still mutate tags on the SpanOperation at this point.
+        class SpanBeforeFinish < Tracing::Event
+          def initialize
+            super(:span_before_finish)
+          end
         end
 
         # Triggered before a span starts.
@@ -445,6 +518,14 @@ module Datadog
             subscribe(&block)
           end
         end
+
+        # Triggered when the resource name is set
+        # This is used to reconsider trace sampling on resource name change
+        class TraceResourceChange < Tracing::Event
+          def initialize
+            super(:trace_resource_change)
+          end
+        end
       end
 
       private
@@ -460,7 +541,7 @@ module Datadog
 
         @active_span = span_op
 
-        set_root_span!(span_op) unless root_span
+        set_local_root_span!(span_op)
       end
 
       def deactivate_span!(span_op)
@@ -480,9 +561,22 @@ module Datadog
         # Publish :span_before_start event
         events.span_before_start.publish(span_op, self)
       rescue => e
-        logger.debug { "Error starting span on trace: #{e} Backtrace: #{e.backtrace.first(3)}" }
+        logger.debug { "Error starting span on trace: #{e.class}: #{e.message} Backtrace: #{e.backtrace.first(3)}" }
       end
 
+      def before_finish_span(span_op)
+        # Publish :span_before_finish event
+        events.span_before_finish.publish(span_op, self)
+      rescue => e
+        logger.debug { "Error in before_finish_span on trace: #{e.class}: #{e.message} Backtrace: #{e.backtrace.first(3)}" }
+      end
+
+      # For traces with automatic context management (auto_finish),
+      # when the local root span finishes, the trace also finishes.
+      # The trace cannot receive new spans after finished.
+      #
+      # Without auto_finish, the trace can still receive spans
+      # until explicitly finished.
       def finish_span(span, span_op, parent)
         # Save finished span & root span
         @spans << span unless span.nil?
@@ -490,8 +584,9 @@ module Datadog
         # Deactivate the span, re-activate parent.
         deactivate_span!(span_op)
 
-        # Set finished, to signal root span has completed.
-        @finished = true if span_op == root_span
+        # Finish if the local root span is finished and automatic
+        # context management is enabled.
+        @finished = true if span_op == root_span && @auto_finish
 
         # Update active span count
         @active_span_count -= 1
@@ -502,11 +597,11 @@ module Datadog
         # Publish :trace_finished event
         events.trace_finished.publish(self) if finished?
       rescue => e
-        logger.debug { "Error finishing span on trace: #{e} Backtrace: #{e.backtrace.first(3)}" }
+        logger.debug { "Error finishing span on trace: #{e.class}: #{e.message} Backtrace: #{e.backtrace.first(3)}" }
       end
 
-      # Track the root span
-      def set_root_span!(span)
+      # Track the root {SpanOperation} object from the current execution context.
+      def set_local_root_span!(span)
         return if span.nil? || root_span
 
         @root_span = span
@@ -544,12 +639,24 @@ module Datadog
         meta.select { |name, _| name.start_with?(Metadata::Ext::Distributed::TAGS_PREFIX) }
       end
 
+      def reconsider_rule_sample?
+        decision = get_tag(Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+
+        return false if remote_parent || @propagated || @flushed
+        return false unless AUTO_SAMPLING_PRIORITIES.include?(@sampling_priority)
+        return false if decision && !RECONSIDERABLE_DECISIONS.include?(decision)
+
+        true
+      end
+
       def reset
         @root_span = nil
         @active_span = nil
         @active_span_count = 0
         @finished = false
         @spans = []
+        @flushed = false
+        @propagated = false
       end
     end
   end