ddtrace 1.0.0 → 1.9.0

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

@@ -1,7 +1,7 @@
 # typed: true
 
-require 'datadog/tracing/sampling/sampler'
-require 'datadog/tracing/sampling/rate_sampler'
+require_relative 'sampler'
+require_relative 'rate_sampler'
 
 module Datadog
   module Tracing
@@ -12,7 +12,7 @@ module Datadog
         attr_reader \
           :default_key
 
-        def initialize(default_key, default_rate = 1.0, &block)
+        def initialize(default_key, default_rate = 1.0, decision: nil, &block)
           super()
 
           raise ArgumentError, 'No resolver given!' unless block
@@ -22,7 +22,7 @@ module Datadog
           @mutex = Mutex.new
           @samplers = {}
 
-          set_rate(default_key, default_rate)
+          set_rate(default_key, default_rate, decision)
         end
 
         def resolve(trace)
@@ -57,15 +57,15 @@ module Datadog
           end
         end
 
-        def update(key, rate)
+        def update(key, rate, decision: nil)
           @mutex.synchronize do
-            set_rate(key, rate)
+            set_rate(key, rate, decision)
           end
         end
 
-        def update_all(rate_by_key)
+        def update_all(rate_by_key, decision: nil)
           @mutex.synchronize do
-            rate_by_key.each { |key, rate| set_rate(key, rate) }
+            rate_by_key.each { |key, rate| set_rate(key, rate, decision) }
           end
         end
 
@@ -87,9 +87,8 @@ module Datadog
 
         private
 
-        def set_rate(key, rate)
-          @samplers[key] ||= RateSampler.new(rate)
-          @samplers[key].sample_rate = rate
+        def set_rate(key, rate, decision)
+          @samplers[key] = RateSampler.new(rate, decision: decision)
         end
       end
     end

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

@@ -1,27 +1,33 @@
 # typed: true
 
-require 'datadog/core'
-require 'datadog/tracing/sampling/rate_by_key_sampler'
+require_relative '../../core'
+require_relative 'rate_by_key_sampler'
 
 module Datadog
   module Tracing
     module Sampling
-      # {Datadog:::Tracing::Sampling::RateByServiceSampler} samples different services at different rates
+      # {Datadog::Tracing::Sampling::RateByServiceSampler} samples different services at different rates
       # @public_api
       class RateByServiceSampler < RateByKeySampler
         DEFAULT_KEY = 'service:,env:'.freeze
 
-        def initialize(default_rate = 1.0, options = {})
-          super(DEFAULT_KEY, default_rate, &method(:key_for))
-          @env = options[:env]
+        def initialize(default_rate = 1.0, env: nil, decision: Datadog::Tracing::Sampling::Ext::Decision::DEFAULT)
+          super(
+            DEFAULT_KEY,
+            default_rate,
+            decision: decision,
+            &method(:key_for)
+          )
+
+          @env = env
         end
 
-        def update(rate_by_service)
+        def update(rate_by_service, decision: nil)
           # Remove any old services
           delete_if { |key, _| key != DEFAULT_KEY && !rate_by_service.key?(key) }
 
           # Update each service rate
-          update_all(rate_by_service)
+          update_all(rate_by_service, decision: decision)
 
           # Emit metric for service cache size
           Datadog.health_metrics.sampling_service_cache_length(length)
@@ -29,6 +35,24 @@ module Datadog
 
         private
 
+        # DEV: Creating a string on every trace to perform a single Hash lookup is expensive.
+        #
+        # Using 2 nested hashes: 1 for env and 1 for service is the fastest option.
+        # This approach requires large API changes to `RateByKeySampler`.
+        #
+        # Reducing the interpolated string size, by using a 1 character separator,
+        # is also measurably faster than the current method. This approach does not
+        # require changes to `RateByKeySampler`.
+        #
+        # Keep in mind that these changes also require changes to `#update`.
+        #
+        # Comparison:
+        #  2 nested hashes: `service_hash.fetch(service, {}).fetch(env, default_rate)`
+        #                   7730045 i/s
+        # 1 char separator: `hash.fetch("#{service}\0#{env}", default_rate)`
+        #                   4302801 i/s - 1.80x slower
+        #          current: `hash.fetch("service:#{service},env:#{env}", default_rate)`
+        #                   2720459 i/s - 2.84x slower
         def key_for(trace)
           # Resolve env dynamically, if Proc is given.
           env = @env.is_a?(Proc) ? @env.call : @env

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

@@ -1,6 +1,6 @@
 # typed: true
 
-require 'datadog/core/utils/time'
+require_relative '../../core/utils/time'
 
 module Datadog
   module Tracing
@@ -39,6 +39,9 @@ module Datadog
         def initialize(rate, max_tokens = rate)
           super()
 
+          raise ArgumentError, "rate must be a number: #{rate}" unless rate.is_a?(Numeric)
+          raise ArgumentError, "max_tokens must be a number: #{max_tokens}" unless max_tokens.is_a?(Numeric)
+
           @rate = rate
           @max_tokens = max_tokens
 

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

@@ -1,26 +1,36 @@
 # typed: true
 
-require 'datadog/core'
+require_relative '../../core'
 
-require 'datadog/tracing/sampling/sampler'
-require 'datadog/tracing/span'
+require_relative 'sampler'
+require_relative '../utils'
 
 module Datadog
   module Tracing
     module Sampling
-      # {Datadog:::Tracing::Sampling::RateSampler} is based on a sample rate.
+      # {Datadog::Tracing::Sampling::RateSampler} is based on a sample rate.
       # @public_api
       class RateSampler < Sampler
         KNUTH_FACTOR = 1111111111111111111
 
-        # Initialize a {Datadog:::Tracing::Sampling::RateSampler}.
+        # Initialize a {Datadog::Tracing::Sampling::RateSampler}.
         # This sampler keeps a random subset of the traces. Its main purpose is to
         # reduce the instrumentation footprint.
         #
         # * +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.
-        def initialize(sample_rate = 1.0)
+        #
+        # 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, decision: nil)
           super()
 
           unless sample_rate > 0.0 && sample_rate <= 1.0
@@ -29,6 +39,8 @@ module Datadog
           end
 
           self.sample_rate = sample_rate
+
+          @decision = decision
         end
 
         def sample_rate(*_)
@@ -37,17 +49,22 @@ module Datadog
 
         def sample_rate=(sample_rate)
           @sample_rate = sample_rate
-          @sampling_id_threshold = sample_rate * Span::EXTERNAL_MAX_ID
+          @sampling_id_threshold = sample_rate * Tracing::Utils::EXTERNAL_MAX_ID
         end
 
         def sample?(trace)
-          ((trace.id * KNUTH_FACTOR) % Span::EXTERNAL_MAX_ID) <= @sampling_id_threshold
+          ((trace.id * KNUTH_FACTOR) % Tracing::Utils::EXTERNAL_MAX_ID) <= @sampling_id_threshold
         end
 
         def sample!(trace)
           sampled = trace.sampled = sample?(trace)
-          trace.sample_rate = @sample_rate if sampled
-          sampled
+
+          return false unless sampled
+
+          trace.sample_rate = @sample_rate
+          trace.set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, @decision) if @decision
+
+          true
         end
       end
     end

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

@@ -1,11 +1,9 @@
 # typed: true
 
-require 'forwardable'
+require_relative '../../core'
 
-require 'datadog/core'
-
-require 'datadog/tracing/sampling/matcher'
-require 'datadog/tracing/sampling/rate_sampler'
+require_relative 'matcher'
+require_relative 'rate_sampler'
 
 module Datadog
   module Tracing
@@ -15,8 +13,6 @@ module Datadog
       # apply in case of a positive match.
       # @public_api
       class Rule
-        extend Forwardable
-
         attr_reader :matcher, :sampler
 
         # @param [Matcher] matcher A matcher to verify trace conformity against
@@ -34,11 +30,21 @@ module Datadog
         def match?(trace)
           @matcher.match?(trace)
         rescue => e
-          Datadog.logger.error("Matcher failed. Cause: #{e.message} Source: #{Array(e.backtrace).first}")
+          Datadog.logger.error(
+            "Matcher failed. Cause: #{e.class.name} #{e.message} Source: #{Array(e.backtrace).first}"
+          )
           nil
         end
 
-        def_delegators :@sampler, :sample?, :sample_rate
+        # (see Datadog::Tracing::Sampling::Sampler#sample?)
+        def sample?(trace)
+          @sampler.sample?(trace)
+        end
+
+        # (see Datadog::Tracing::Sampling::Sampler#sample_rate)
+        def sample_rate(trace)
+          @sampler.sample_rate(trace)
+        end
       end
 
       # A {Datadog::Tracing::Sampling::Rule} that matches a trace based on

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

@@ -1,12 +1,10 @@
 # typed: true
 
-require 'forwardable'
+require_relative '../../core'
 
-require 'datadog/core'
-
-require 'datadog/tracing/sampling/ext'
-require 'datadog/tracing/sampling/rate_limiter'
-require 'datadog/tracing/sampling/rule'
+require_relative 'ext'
+require_relative 'rate_limiter'
+require_relative 'rule'
 
 module Datadog
   module Tracing
@@ -18,8 +16,6 @@ module Datadog
       # sampling strategy is applied.
       # @public_api
       class RuleSampler
-        extend Forwardable
-
         attr_reader :rules, :rate_limiter, :default_sampler
 
         # @param rules [Array<Rule>] ordered list of rules to be applied to a trace
@@ -52,7 +48,7 @@ module Datadog
                                nil
                              else
                                # TODO: Simplify .tags access, as `Tracer#tags` can't be arbitrarily changed anymore
-                               RateByServiceSampler.new(1.0, env: -> { Tracing.send(:tracer).tags[:env] })
+                               RateByServiceSampler.new(1.0, env: -> { Tracing.send(:tracer).tags['env'] })
                              end
         end
 
@@ -80,10 +76,10 @@ module Datadog
         end
 
         # @!visibility private
-        def update(*args)
+        def update(*args, **kwargs)
           return false unless @default_sampler.respond_to?(:update)
 
-          @default_sampler.update(*args)
+          @default_sampler.update(*args, **kwargs)
         end
 
         private
@@ -104,9 +100,12 @@ module Datadog
           rate_limiter.allow?(1).tap do |allowed|
             set_priority(trace, allowed)
             set_limiter_metrics(trace, rate_limiter.effective_rate)
+            trace.set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, Ext::Decision::TRACE_SAMPLING_RULE)
           end
         rescue StandardError => e
-          Datadog.logger.error("Rule sampling failed. Cause: #{e.message} Source: #{Array(e.backtrace).first}")
+          Datadog.logger.error(
+            "Rule sampling failed. Cause: #{e.class.name} #{e.message} Source: #{Array(e.backtrace).first}"
+          )
           yield(trace)
         end
 

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

@@ -0,0 +1,25 @@
+# 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'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Sampling
+      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 = '*'
+
+          # Matches span name and service to their respective patterns provided.
+          #
+          # The patterns are {String}s with two special characters available:
+          # 1. `?`: matches exactly one of any character.
+          # 2. `*`: matches a substring of any size, including zero.
+          # These patterns can occur any point of the string, any number of times.
+          #
+          # Both {SpanOperation#name} and {SpanOperation#service} must match the provided patterns.
+          #
+          # The whole String has to match the provided patterns: providing a pattern that
+          # matches a portion of the provided String is not considered a match.
+          #
+          # @example web-*
+          #   `'web-*'` will match any string starting with `web-`.
+          # @example cache-?
+          #   `'cache-?'` will match any string starting with `database-` followed by exactly one character.
+          #
+          # @param name_pattern [String] a pattern to be matched against {SpanOperation#name}
+          # @param service_pattern [String] a pattern to be matched against {SpanOperation#service}
+          def initialize(name_pattern: MATCH_ALL_PATTERN, service_pattern: MATCH_ALL_PATTERN)
+            @name = pattern_to_regex(name_pattern)
+            @service = pattern_to_regex(service_pattern)
+          end
+
+          # {Regexp#match?} was added in Ruby 2.4, and it's measurably
+          # the least costly way to get a boolean result for a Regexp match.
+          # @see https://www.ruby-lang.org/en/news/2016/12/25/ruby-2-4-0-released/
+          if Regexp.method_defined?(:match?)
+            # Returns `true` if the span conforms to the configured patterns,
+            # `false` otherwise
+            #
+            # @param [SpanOperation] span
+            # @return [Boolean]
+            def match?(span)
+              # Matching is performed at the end of the lifecycle of a Span,
+              # thus both `name` and `service` are guaranteed to be not `nil`.
+              @name.match?(span.name) && @service.match?(span.service)
+            end
+          else
+            # DEV: Remove when support for Ruby 2.3 and older is removed.
+            def match?(span)
+              @name === span.name && @service === span.service
+            end
+          end
+
+          def ==(other)
+            return super unless other.is_a?(Matcher)
+
+            name == other.name &&
+              service == other.service
+          end
+
+          private
+
+          # @param pattern [String]
+          # @return [Regexp]
+          def pattern_to_regex(pattern)
+            # Ensure no undesired characters are treated as regex.
+            # Our valid special characters, `?` and `*`,
+            # will be escaped so...
+            pattern = Regexp.quote(pattern)
+
+            # ...we account for that here:
+            pattern.gsub!('\?', '.') # Any single character
+            pattern.gsub!('\*', '.*') # Any substring
+
+            # Patterns have to match the whole input string
+            pattern = "\\A#{pattern}\\z"
+
+            Regexp.new(pattern)
+          end
+        end
+      end
+    end
+  end
+end

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, Sampling::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