cw-datadog 2.23.0.2

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

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+require_relative '../../core/rate_limiter'
+require_relative 'rule'
+require_relative '../../core/telemetry/logger'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # Span {Sampler} that applies a set of {Rule}s to decide
+      # on sampling outcome. Then, a rate limiter is applied.
+      #
+      # If a trace does not conform to any rules, a default
+      # sampling strategy is applied.
+      class RuleSampler
+        attr_reader :rules, :rate_limiter, :default_sampler
+
+        # @param rules [Array<Rule>] ordered list of rules to be applied to a trace
+        # @param rate_limit [Float] number of traces per second, defaults to +100+
+        # @param rate_limiter [RateLimiter] limiter applied after rule matching
+        # @param default_sample_rate [Float] fallback sample rate when no rules apply to a trace,
+        #   between +[0,1]+, defaults to +1+
+        # @param default_sampler [Sample] fallback strategy when no rules apply to a trace
+        def initialize(
+          rules = [],
+          rate_limit: Datadog.configuration.tracing.sampling.rate_limit,
+          rate_limiter: nil,
+          default_sample_rate: Datadog.configuration.tracing.sampling.default_rate,
+          default_sampler: nil
+        )
+          @rules = if default_sample_rate && !default_sampler
+            # Add to the end of the rule list a rule always matches any trace
+            rules << SimpleRule.new(sample_rate: default_sample_rate)
+          else
+            rules
+          end
+          @rate_limiter = if rate_limiter
+            rate_limiter
+          elsif rate_limit
+            Core::TokenBucket.new(rate_limit)
+          else
+            Core::UnlimitedLimiter.new
+          end
+          @default_sampler = if default_sampler
+            default_sampler
+          elsif default_sample_rate
+            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'] })
+          end
+        end
+
+        def self.parse(rules, rate_limit, default_sample_rate)
+          parsed_rules = JSON.parse(rules).map do |rule|
+            sample_rate = rule['sample_rate']
+
+            begin
+              sample_rate = Float(sample_rate)
+            rescue
+              raise "Rule '#{rule.inspect}' does not contain a float property `sample_rate`"
+            end
+
+            kwargs = {
+              name: rule['name'],
+              service: rule['service'],
+              resource: rule['resource'],
+              tags: rule['tags'],
+              sample_rate: sample_rate,
+              provenance: if (provenance = rule['provenance'])
+                            # `Rule::PROVENANCE_*` values are symbols, so convert strings to match
+                            provenance.to_sym
+                          else
+                            Rule::PROVENANCE_LOCAL
+                          end,
+            }
+
+            kwargs.compact!
+
+            SimpleRule.new(**kwargs)
+          end
+
+          new(parsed_rules, rate_limit: rate_limit, default_sample_rate: default_sample_rate)
+        rescue => e
+          Datadog.logger.warn do
+            "Could not parse trace sampling rules '#{rules}': #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+          end
+
+          nil
+        end
+
+        def sample!(trace)
+          sampled = sample_trace(trace) do |t|
+            @default_sampler.sample!(t).tap do
+              # We want to make sure the trace is tagged with the agent-derived
+              # service rate. Retrieve this from the rate by service sampler.
+              # Only do this if it was set by a RateByServiceSampler.
+              trace.agent_sample_rate = @default_sampler.sample_rate(trace) if @default_sampler.is_a?(RateByServiceSampler)
+            end
+          end
+
+          trace.sampled = sampled
+        end
+
+        # @!visibility private
+        def update(*args, **kwargs)
+          return false unless @default_sampler.respond_to?(:update)
+
+          @default_sampler.update(*args, **kwargs)
+        end
+
+        private
+
+        def sample_trace(trace)
+          rule = @rules.find { |r| r.match?(trace) }
+
+          return yield(trace) if rule.nil?
+
+          sampled = rule.sample!(trace)
+          sample_rate = rule.sample_rate(trace)
+
+          set_priority(trace, sampled)
+          set_rule_metrics(trace, sample_rate)
+
+          return false unless sampled
+
+          rate_limiter.allow?.tap do |allowed|
+            set_priority(trace, allowed)
+            set_limiter_metrics(trace, rate_limiter.effective_rate)
+
+            provenance = case rule.provenance
+            when Rule::PROVENANCE_REMOTE_USER
+              Ext::Decision::REMOTE_USER_RULE
+            when Rule::PROVENANCE_REMOTE_DYNAMIC
+              Ext::Decision::REMOTE_DYNAMIC_RULE
+            else
+              Ext::Decision::TRACE_SAMPLING_RULE
+            end
+
+            trace.set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, provenance)
+          end
+        rescue => e
+          Datadog.logger.error(
+            "Rule sampling failed. Cause: #{e.class.name} #{e.message} Source: #{Array(e.backtrace).first}"
+          )
+          Datadog::Core::Telemetry::Logger.report(e, description: 'Rule sampling failed')
+
+          yield(trace)
+        end
+
+        # Span priority should only be set when the {RuleSampler}
+        # was responsible for the sampling decision.
+        def set_priority(trace, sampled)
+          trace.sampling_priority = if sampled
+            Sampling::Ext::Priority::USER_KEEP
+          else
+            Sampling::Ext::Priority::USER_REJECT
+          end
+        end
+
+        def set_rule_metrics(trace, sample_rate)
+          trace.rule_sample_rate = sample_rate
+        end
+
+        def set_limiter_metrics(trace, limiter_rate)
+          trace.rate_limiter_rate = limiter_rate
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Sampling
+      # Interface for client-side trace sampling.
+      # @abstract
+      class Sampler
+        # Returns `true` if the provided trace should be kept.
+        # Otherwise, `false`.
+        #
+        # This method *may* modify the `trace`, in case changes are necessary based on the
+        # sampling decision.
+        #
+        # @param [Datadog::Tracing::TraceOperation] trace
+        # @return [Boolean] should this trace be kept?
+        def sample!(trace)
+          raise NotImplementedError, 'Samplers must implement the #sample! method'
+        end
+
+        # The sampling rate, if this sampler has such concept.
+        # Otherwise, `nil`.
+        #
+        # @param [Datadog::Tracing::TraceOperation] trace
+        # @return [Float,nil] sampling ratio between 0.0 and 1.0 (inclusive), or `nil` if not applicable
+        def sample_rate(trace)
+          raise NotImplementedError, 'Samplers must implement the #sample_rate method'
+        end
+      end
+    end
+  end
+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::Core::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,61 @@
+# frozen_string_literal: true
+
+require_relative '../matcher'
+
+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 = Sampling::Matcher.glob_to_regex(name_pattern)
+            @service = Sampling::Matcher.glob_to_regex(service_pattern)
+          end
+
+          # 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
+
+          def ==(other)
+            return super unless other.is_a?(Matcher)
+
+            name == other.name &&
+              service == other.service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# 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(sample_rate)
+            @rate_limiter = Core::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::TraceOperation] trace_op trace for the span to be sampled
+          # @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!(trace_op, span_op)
+            return :not_matched unless @matcher.match?(span_op)
+
+            if @rate_limiter.allow? && @sampler.sample!(trace_op)
+              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

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+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?
+
+            # Applies the first matching rule
+            @rules.each do |rule|
+              decision = rule.sample!(trace_op, span_op)
+
+              next if decision == :not_matched # Iterate until we find a matching decision
+
+              break # Found either a `kept` or `rejected` decision
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end