ddtrace 1.4.2 → 1.5.0

data/lib/datadog/tracing/sampling/rate_sampler.rb

@@ -20,6 +20,16 @@ module Datadog
         # * +sample_rate+: the sample rate as a {Float} between 0.0 and 1.0. 0.0
         #   means that no trace will be sampled; 1.0 means that all traces will be
         #   sampled.
+        #
+        # DEV-2.0: Allow for `sample_rate` zero (drop all) to be allowed. This eases
+        # DEV-2.0: usage for all internal users of the {RateSampler} class: both
+        # DEV-2.0: RuleSampler and Single Span Sampling leverage the RateSampler, but want
+        # DEV-2.0: `sample_rate` zero to mean "drop all". They work around this by hard-
+        # DEV-2.0: setting the `sample_rate` to zero like so:
+        # DEV-2.0: ```
+        # DEV-2.0: sampler = RateSampler.new
+        # DEV-2.0: sampler.sample_rate = sample_rate
+        # DEV-2.0: ```
         def initialize(sample_rate = 1.0)
           super()
 

data/lib/datadog/tracing/sampling/span/ext.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Sampling
+      module Span
+        # Single Span Sampling constants.
+        module Ext
+          # Accept all spans (100% retention).
+          DEFAULT_SAMPLE_RATE = 1.0
+          # Unlimited.
+          # @see Datadog::Tracing::Sampling::TokenBucket
+          DEFAULT_MAX_PER_SECOND = -1
+
+          # Sampling decision method used to come to the sampling decision for this span
+          TAG_MECHANISM = '_dd.span_sampling.mechanism'
+          # Sampling rate applied to this span, if a rule applies
+          TAG_RULE_RATE = '_dd.span_sampling.rule_rate'
+          # Rate limit configured for this span, if a rule applies
+          TAG_MAX_PER_SECOND = '_dd.span_sampling.max_per_second'
+
+          # This span was sampled on account of a Span Sampling Rule
+          # @see Datadog::Tracing::Sampling::Span::Rule
+          MECHANISM_SPAN_SAMPLING_RATE = 8
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/sampling/span/matcher.rb

@@ -6,6 +6,8 @@ module Datadog
       module Span
         # Checks if a span conforms to a matching criteria.
         class Matcher
+          attr_reader :name, :service
+
           # Pattern that matches any string
           MATCH_ALL_PATTERN = '*'
 
@@ -54,6 +56,13 @@ module Datadog
             end
           end
 
+          def ==(other)
+            return super unless other.is_a?(Matcher)
+
+            name == other.name &&
+              service == other.service
+          end
+
           private
 
           # @param pattern [String]

data/lib/datadog/tracing/sampling/span/rule.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+
+module Datadog
+  module Tracing
+    module Sampling
+      module Span
+        # Span sampling rule that applies a sampling rate if the span
+        # matches the provided {Matcher}.
+        # Additionally, a rate limiter is also applied.
+        #
+        # If a span does not conform to the matcher, no changes are made.
+        class Rule
+          attr_reader :matcher, :sample_rate, :rate_limit
+
+          # Creates a new span sampling rule.
+          #
+          # @param [Sampling::Span::Matcher] matcher whether this rule applies to a specific span
+          # @param [Float] sample_rate span sampling ratio, between 0.0 (0%) and 1.0 (100%).
+          # @param [Numeric] rate_limit maximum number of spans sampled per second. Negative numbers mean unlimited spans.
+          def initialize(
+            matcher,
+            sample_rate: Span::Ext::DEFAULT_SAMPLE_RATE,
+            rate_limit: Span::Ext::DEFAULT_MAX_PER_SECOND
+          )
+
+            @matcher = matcher
+            @sample_rate = sample_rate
+            @rate_limit = rate_limit
+
+            @sampler = Sampling::RateSampler.new
+            # Set the sample_rate outside of the initializer to allow for
+            # zero to be a "drop all".
+            # The RateSampler initializer enforces non-zero, falling back to 100% sampling
+            # if zero is provided.
+            @sampler.sample_rate = sample_rate
+            @rate_limiter = Sampling::TokenBucket.new(rate_limit)
+          end
+
+          # This method should only be invoked for spans that are part
+          # of a trace that has been dropped by trace-level sampling.
+          # Invoking it for other spans will cause incorrect sampling
+          # metrics to be reported by the Datadog App.
+          #
+          # Returns `true` if the provided span is sampled.
+          # If the span is dropped due to sampling rate or rate limiting,
+          # it returns `false`.
+          #
+          # Returns `nil` if the span did not meet the matching criteria by the
+          # provided matcher.
+          #
+          # This method modifies the `span` if it matches the provided matcher.
+          #
+          # @param [Datadog::Tracing::SpanOperation] span_op span to be sampled
+          # @return [:kept,:rejected] should this span be sampled?
+          # @return [:not_matched] span did not satisfy the matcher, no changes are made to the span
+          def sample!(span_op)
+            return :not_matched unless @matcher.match?(span_op)
+
+            if @sampler.sample?(span_op) && @rate_limiter.allow?(1)
+              span_op.set_metric(Span::Ext::TAG_MECHANISM, Span::Ext::MECHANISM_SPAN_SAMPLING_RATE)
+              span_op.set_metric(Span::Ext::TAG_RULE_RATE, @sample_rate)
+              span_op.set_metric(Span::Ext::TAG_MAX_PER_SECOND, @rate_limit)
+              :kept
+            else
+              :rejected
+            end
+          end
+
+          def ==(other)
+            return super unless other.is_a?(Rule)
+
+            matcher == other.matcher &&
+              sample_rate == other.sample_rate &&
+              rate_limit == other.rate_limit
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/sampling/span/rule_parser.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'ext'
+require_relative 'matcher'
+require_relative 'rule'
+
+module Datadog
+  module Tracing
+    module Sampling
+      module Span
+        # Converts user configuration into {Datadog::Tracing::Sampling::Span::Rule} objects,
+        # handling any parsing errors.
+        module RuleParser
+          class << self
+            # Parses the provided JSON string containing the Single Span
+            # Sampling configuration list.
+            # In case of parsing errors, `nil` is returned.
+            #
+            # @param rules [String] the JSON configuration rules to be parsed
+            # @return [Array<Datadog::Tracing::Sampling::Span::Rule>] a list of parsed rules
+            # @return [nil] if parsing failed
+            def parse_json(rules)
+              return nil unless rules
+
+              begin
+                list = JSON.parse(rules)
+              rescue => e
+                Datadog.logger.warn(
+                  "Error parsing Span Sampling Rules `#{rules.inspect}`: "\
+                  "#{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+                )
+                return nil
+              end
+
+              parse_list(list)
+            end
+
+            # Parses a list of Hashes containing the parsed JSON information
+            # for Single Span Sampling configuration.
+            # In case of parsing errors, `nil` is returned.
+            #
+            # @param rules [Array<String] the JSON configuration rules to be parsed
+            # @return [Array<Datadog::Tracing::Sampling::Span::Rule>] a list of parsed rules
+            # @return [nil] if parsing failed
+            def parse_list(rules)
+              unless rules.is_a?(Array)
+                Datadog.logger.warn("Span Sampling Rules are not an array: #{rules.inspect}")
+                return nil
+              end
+
+              parsed = rules.map do |hash|
+                unless hash.is_a?(Hash)
+                  Datadog.logger.warn("Span Sampling Rule is not a key-value object: #{hash.inspect}")
+                  return nil
+                end
+
+                begin
+                  parse_rule(hash)
+                rescue => e
+                  Datadog.logger.warn(
+                    "Cannot parse Span Sampling Rule #{hash.inspect}: " \
+                    "#{e.class.name} #{e} at #{Array(e.backtrace).first}"
+                  )
+                  return nil
+                end
+              end
+
+              parsed.compact!
+              parsed
+            end
+
+            private
+
+            def parse_rule(hash)
+              matcher_options = {}
+              if (name_pattern = hash['name'])
+                matcher_options[:name_pattern] = name_pattern
+              end
+
+              if (service_pattern = hash['service'])
+                matcher_options[:service_pattern] = service_pattern
+              end
+
+              matcher = Matcher.new(**matcher_options)
+
+              rule_options = {}
+              if (sample_rate = hash['sample_rate'])
+                rule_options[:sample_rate] = sample_rate
+              end
+
+              if (max_per_second = hash['max_per_second'])
+                rule_options[:rate_limit] = max_per_second
+              end
+
+              Rule.new(matcher, **rule_options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/sampling/span/sampler.rb

@@ -0,0 +1,64 @@
+module Datadog
+  module Tracing
+    module Sampling
+      module Span
+        # Applies Single Span Sampling rules to spans.
+        # When matching the configured rules, a span is ensured to
+        # be processed Datadog App. In other words, a single sampled span
+        # will never be dropped by the tracer or Datadog agent.
+        #
+        # All spans in a trace are subject to the single sampling rules, if
+        # any rules are configured.
+        #
+        # Single Span Sampling is distinct from trace-level sampling:
+        # Single Span Sampling can ensure a span is kept, even if its
+        # enclosing trace is rejected by trace-level sampling.
+        #
+        # This class only applies operations to spans that are part
+        # of traces that was rejected by trace sampling.
+        # A trace is rejected if either of the following conditions is true:
+        # * The priority sampling for a trace is set to either {USER_REJECT} or {AUTO_REJECT}.
+        # * The trace was rejected by internal sampling, thus never flushed.
+        #
+        # Single-sampled spans are tagged and the tracer ensures they will
+        # reach the Datadog App, regardless of their enclosing trace sampling decision.
+        #
+        # Single Span Sampling does not inspect spans that are part of a trace
+        # that has been accepted by trace-level sampling rules: all spans from such
+        # trace are guaranteed to reach the Datadog App.
+        class Sampler
+          attr_reader :rules
+
+          # Receives sampling rules to apply to individual spans.
+          #
+          # @param [Array<Datadog::Tracing::Sampling::Span::Rule>] rules list of rules to apply to spans
+          def initialize(rules = [])
+            @rules = rules
+          end
+
+          # Applies Single Span Sampling rules to the span if the trace has been rejected.
+          #
+          # The trace can be outright rejected, and never reach the transport,
+          # or be set as rejected by priority sampling. In both cases, the trace
+          # is considered rejected for Single Span Sampling purposes.
+          #
+          # If multiple rules match, only the first one is applied.
+          #
+          # @param [Datadog::Tracing::TraceOperation] trace_op trace for the provided span
+          # @param [Datadog::Tracing::SpanOperation] span_op Span to apply sampling rules
+          # @return [void]
+          def sample!(trace_op, span_op)
+            return if trace_op.sampled? && trace_op.priority_sampled?
+
+            # Return as soon as one rule matches
+            @rules.any? do |rule|
+              rule.sample!(span_op) != :not_matched
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/span_operation.rb

@@ -18,7 +18,6 @@ module Datadog
     # It gives a Span a context which can be used to
     # build a Span. When completed, it yields the Span.
     #
-    # rubocop:disable Metrics/ClassLength
     # @public_api
     class SpanOperation
       include Metadata
@@ -516,6 +515,5 @@ module Datadog
       alias :span_type :type
       alias :span_type= :type=
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/datadog/tracing/trace_operation.rb

@@ -22,7 +22,6 @@ module Datadog
     # For async support, a {Datadog::Tracing::TraceOperation} should be employed
     # per execution context (e.g. Thread, etc.)
     #
-    # rubocop:disable Metrics/ClassLength
     # @public_api
     class TraceOperation
       include Metadata::Tagging
@@ -113,8 +112,22 @@ module Datadog
         @finished == true
       end
 
+      # Will this trace be flushed by the tracer transport?
+      # This includes cases where the span is kept solely due to priority sampling.
+      #
+      # This is not the ultimate Datadog App sampling decision. Downstream systems
+      # can decide to reject this trace, especially for cases where priority
+      # sampling is set to AUTO_KEEP.
+      #
+      # @return [Boolean]
       def sampled?
-        @sampled == true || (!@sampling_priority.nil? && @sampling_priority > 0)
+        @sampled == true || priority_sampled?
+      end
+
+      # Has the priority sampling chosen to keep this span?
+      # @return [Boolean]
+      def priority_sampled?
+        !@sampling_priority.nil? && @sampling_priority > 0
       end
 
       def keep!
@@ -233,6 +246,11 @@ module Datadog
         end
       end
 
+      # Returns a {TraceSegment} with all finished spans that can be flushed
+      # at invocation time. All other **finished** spans are discarded.
+      #
+      # @yield [spans] spans that will be returned as part of the trace segment returned
+      # @return [TraceSegment]
       def flush!
         finished = finished?
 
@@ -240,6 +258,8 @@ module Datadog
         spans = @spans.dup
         @spans = []
 
+        spans = yield(spans) if block_given?
+
         # Use them to build a trace
         build_trace(spans, !finished)
       end
@@ -433,6 +453,5 @@ module Datadog
         )
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/datadog/tracing/trace_segment.rb

@@ -11,7 +11,6 @@ module Datadog
   module Tracing
     # Serializable construct representing a trace
     # @public_api
-    # rubocop:disable Metrics/ClassLength
     class TraceSegment
       TAG_NAME = 'name'.freeze
       TAG_RESOURCE = 'resource'.freeze
@@ -36,6 +35,7 @@ module Datadog
 
       # rubocop:disable Metrics/CyclomaticComplexity
       # rubocop:disable Metrics/PerceivedComplexity
+      # @param spans [Array<Datadog::Span>]
       def initialize(
         spans,
         agent_sample_rate: nil,
@@ -202,6 +202,5 @@ module Datadog
         meta[TAG_SERVICE]
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/datadog/tracing/tracer.rb

@@ -11,6 +11,7 @@ require_relative 'context_provider'
 require_relative 'sampling/all_sampler'
 require_relative 'sampling/rule_sampler'
 require_relative 'sampling/priority_sampler'
+require_relative 'sampling/span/sampler'
 require_relative 'span_operation'
 require_relative 'trace_digest'
 require_relative 'trace_operation'
@@ -22,12 +23,12 @@ module Datadog
     # example, a trace can be used to track the entire time spent processing a complicated web request.
     # Even though the request may require multiple resources and machines to handle the request, all
     # of these function calls and sub-requests would be encapsulated within a single trace.
-    # rubocop:disable Metrics/ClassLength
     class Tracer
       attr_reader \
         :trace_flush,
         :provider,
         :sampler,
+        :span_sampler,
         :tags
 
       attr_accessor \
@@ -56,6 +57,7 @@ module Datadog
           base_sampler: Sampling::AllSampler.new,
           post_sampler: Sampling::RuleSampler.new
         ),
+        span_sampler: Sampling::Span::Sampler.new,
         tags: {},
         writer: Writer.new
       )
@@ -64,6 +66,7 @@ module Datadog
         @enabled = enabled
         @provider = context_provider
         @sampler = sampler
+        @span_sampler = span_sampler
         @tags = tags
         @writer = writer
       end
@@ -341,7 +344,8 @@ module Datadog
           sample_trace(event_trace_op) if event_span_op && event_span_op.parent_id == 0
         end
 
-        events.span_finished.subscribe do |_event_span, event_trace_op|
+        events.span_finished.subscribe do |event_span, event_trace_op|
+          sample_span(event_trace_op, event_span)
           flush_trace(event_trace_op)
         end
       end
@@ -461,20 +465,43 @@ module Datadog
         begin
           @sampler.sample!(trace_op)
         rescue StandardError => e
-          Datadog.logger.debug { "Failed to sample trace: #{e}" }
+          SAMPLE_TRACE_LOG_ONLY_ONCE.run do
+            Datadog.logger.warn { "Failed to sample trace: #{e.class.name} #{e} at #{Array(e.backtrace).first}" }
+          end
         end
       end
 
+      SAMPLE_TRACE_LOG_ONLY_ONCE = Core::Utils::OnlyOnce.new
+      private_constant :SAMPLE_TRACE_LOG_ONLY_ONCE
+
+      def sample_span(trace_op, span)
+        begin
+          @span_sampler.sample!(trace_op, span)
+        rescue StandardError => e
+          SAMPLE_SPAN_LOG_ONLY_ONCE.run do
+            Datadog.logger.warn { "Failed to sample span: #{e.class.name} #{e} at #{Array(e.backtrace).first}" }
+          end
+        end
+      end
+
+      SAMPLE_SPAN_LOG_ONLY_ONCE = Core::Utils::OnlyOnce.new
+      private_constant :SAMPLE_SPAN_LOG_ONLY_ONCE
+
       # Flush finished spans from the trace buffer, send them to writer.
       def flush_trace(trace_op)
         begin
           trace = @trace_flush.consume!(trace_op)
           write(trace) if trace && !trace.empty?
         rescue StandardError => e
-          Datadog.logger.debug { "Failed to flush trace: #{e}" }
+          FLUSH_TRACE_LOG_ONLY_ONCE.run do
+            Datadog.logger.warn { "Failed to flush trace: #{e.class.name} #{e} at #{Array(e.backtrace).first}" }
+          end
         end
       end
 
+      FLUSH_TRACE_LOG_ONLY_ONCE = Core::Utils::OnlyOnce.new
+      private_constant :FLUSH_TRACE_LOG_ONLY_ONCE
+
       # Send the trace to the writer to enqueue the spans list in the agent
       # sending queue.
       def write(trace)
@@ -500,6 +527,5 @@ module Datadog
         end
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/ddtrace/version.rb

@@ -3,8 +3,8 @@
 module DDTrace
   module VERSION
     MAJOR = 1
-    MINOR = 4
-    PATCH = 2
+    MINOR = 5
+    PATCH = 0
     PRE = nil
 
     STRING = [MAJOR, MINOR, PATCH, PRE].compact.join('.')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ddtrace
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.5.0
 platform: ruby
 authors:
 - Datadog, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-27 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -28,16 +28,22 @@ dependencies:
   name: debase-ruby_core_source
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.10.16
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: 0.10.17
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.10.16
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: 0.10.17
 - !ruby/object:Gem::Dependency
   name: libddwaf
   requirement: !ruby/object:Gem::Requirement
@@ -217,6 +223,7 @@ files:
 - lib/datadog/core/error.rb
 - lib/datadog/core/extensions.rb
 - lib/datadog/core/git/ext.rb
+- lib/datadog/core/header_collection.rb
 - lib/datadog/core/logger.rb
 - lib/datadog/core/logging/ext.rb
 - lib/datadog/core/metrics/client.rb
@@ -339,6 +346,7 @@ files:
 - lib/datadog/tracing.rb
 - lib/datadog/tracing/analytics.rb
 - lib/datadog/tracing/buffer.rb
+- lib/datadog/tracing/client_ip.rb
 - lib/datadog/tracing/configuration/ext.rb
 - lib/datadog/tracing/context.rb
 - lib/datadog/tracing/context_provider.rb
@@ -470,6 +478,7 @@ files:
 - lib/datadog/tracing/contrib/excon/integration.rb
 - lib/datadog/tracing/contrib/excon/middleware.rb
 - lib/datadog/tracing/contrib/excon/patcher.rb
+- lib/datadog/tracing/contrib/ext.rb
 - lib/datadog/tracing/contrib/extensions.rb
 - lib/datadog/tracing/contrib/faraday/configuration/settings.rb
 - lib/datadog/tracing/contrib/faraday/connection.rb
@@ -582,6 +591,7 @@ files:
 - lib/datadog/tracing/contrib/racecar/patcher.rb
 - lib/datadog/tracing/contrib/rack/configuration/settings.rb
 - lib/datadog/tracing/contrib/rack/ext.rb
+- lib/datadog/tracing/contrib/rack/header_collection.rb
 - lib/datadog/tracing/contrib/rack/integration.rb
 - lib/datadog/tracing/contrib/rack/middlewares.rb
 - lib/datadog/tracing/contrib/rack/patcher.rb
@@ -710,7 +720,11 @@ files:
 - lib/datadog/tracing/sampling/rule.rb
 - lib/datadog/tracing/sampling/rule_sampler.rb
 - lib/datadog/tracing/sampling/sampler.rb
+- lib/datadog/tracing/sampling/span/ext.rb
 - lib/datadog/tracing/sampling/span/matcher.rb
+- lib/datadog/tracing/sampling/span/rule.rb
+- lib/datadog/tracing/sampling/span/rule_parser.rb
+- lib/datadog/tracing/sampling/span/sampler.rb
 - lib/datadog/tracing/span.rb
 - lib/datadog/tracing/span_operation.rb
 - lib/datadog/tracing/sync_writer.rb
@@ -778,7 +792,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 2.0.0
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.2.26
 signing_key:
 specification_version: 4
 summary: Datadog tracing code for your Ruby applications