cw-datadog 2.23.0.2

data/lib/datadog/tracing/runtime/metrics.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Runtime
+      # Decorates runtime metrics feature
+      module Metrics
+        def self.associate_trace(trace)
+          return unless trace && !trace.empty?
+
+          # Register service as associated with metrics
+          Datadog.send(:components).runtime_metrics.register_service(trace.service) unless trace.service.nil?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'sampler'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # {Datadog::Tracing::Sampling::AllSampler} samples all the traces.
+      class AllSampler < Sampler
+        def sample?(_trace)
+          true
+        end
+
+        def sample!(trace)
+          trace.sampled = true
+        end
+
+        def sample_rate(*_)
+          1.0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Sampling
+      module Ext
+        # Priority is a hint given to the backend so that it knows which traces to reject or kept.
+        # In a distributed context, it should be set before any context propagation (fork, RPC calls) to be effective.
+        # @public_api
+        module Priority
+          # Use this to explicitly inform the backend that a trace MUST be rejected and not stored.
+          # This includes rules and rate limits configured by the user
+          # through the {Datadog::Tracing::Sampling::RuleSampler}.
+          USER_REJECT = -1
+          # Used by the {PrioritySampler} to inform the backend that a trace should be rejected and not stored.
+          AUTO_REJECT = 0
+          # Used by the {PrioritySampler} to inform the backend that a trace should be kept and stored.
+          AUTO_KEEP = 1
+          # Use this to explicitly inform the backend that a trace MUST be kept and stored.
+          # This includes rules and rate limits configured by the user
+          # through the {Datadog::Tracing::Sampling::RuleSampler}.
+          USER_KEEP = 2
+        end
+
+        # List of what mechanism was used to make the trace-level sampling decision.
+        module Mechanism
+          # Single Span Sampled.
+          SPAN_SAMPLING_RATE = 8
+        end
+
+        # List of how the decision was made for the trace-level sampling.
+        #
+        # These values used to populate the {Datadog::Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER} tag.
+        #
+        # The decision has two parts, separated by a `-`:
+        # `part1-sampling_mechanism`. `part1` is currently not populated, thus
+        # this tag is currently formatted as `"-sampling_mechanism"`.
+        module Decision
+          # Used before the tracer receives any rates from agent and there are no rules configured.
+          DEFAULT = '-0'
+          # The sampling rate received in the agent's http response.
+          AGENT_RATE = '-1'
+          # Locally configured rule.
+          TRACE_SAMPLING_RULE = '-3'
+          # User directly sets sampling priority via {Tracing.reject!} or {Tracing.keep!},
+          # or by a custom sampler implementation.
+          MANUAL = '-4'
+          # Formerly AppSec.
+          ASM = '-5'
+          # Dynamically configured rule, explicitly created by the user.
+          REMOTE_USER_RULE = '-11'
+          # Dynamically configured  rule, automatically generated by Datadog.
+          REMOTE_DYNAMIC_RULE = '-12'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Sampling
+      # Checks if a trace conforms to a matching criteria.
+      # @abstract
+      class Matcher
+        # Pattern that matches any string
+        MATCH_ALL_PATTERN = '*'
+
+        # Returns `true` if the trace should conforms to this rule, `false` otherwise
+        #
+        # @param [TraceOperation] trace
+        # @return [Boolean]
+        def match?(trace)
+          raise NotImplementedError
+        end
+
+        # Converts a glob pattern String to a case-insensitive String matcher object.
+        # The match object will only return `true` if it matches the complete String.
+        #
+        # The following special characters are supported:
+        # - `?` matches any single character
+        # - `*` matches any substring
+        #
+        # @param glob [String]
+        # @return [#match?(String)]
+        def self.glob_to_regex(glob)
+          # Optimization for match-all case
+          return MATCH_ALL if /\A\*+\z/.match?(glob)
+
+          # Ensure no undesired characters are treated as regex.
+          glob = Regexp.quote(glob)
+
+          # Our valid special characters, `?` and `*`, were just escaped
+          # by `Regexp.quote` above. We need to unescape them:
+          glob.gsub!('\?', '.') # Any single character
+          glob.gsub!('\*', '.*') # Any substring
+
+          # Patterns have to match the whole input string
+          glob = "\\A#{glob}\\z"
+
+          Regexp.new(glob, Regexp::IGNORECASE)
+        end
+
+        # Returns `true` for any input
+        MATCH_ALL = Class.new do
+          def match?(_other)
+            true
+          end
+
+          def inspect
+            "MATCH_ALL:Matcher('*')"
+          end
+        end.new
+      end
+
+      # A {Datadog::Sampling::Matcher} that supports matching a trace by
+      # trace name and/or service name.
+      class SimpleMatcher < Matcher
+        attr_reader :name, :service, :resource, :tags
+
+        # @param name [String,Regexp,Proc] Matcher for case equality (===) with the trace name,
+        #             defaults to always match
+        # @param service [String,Regexp,Proc] Matcher for case equality (===) with the service name,
+        #                defaults to always match
+        # @param resource [String,Regexp,Proc] Matcher for case equality (===) with the resource name,
+        #                defaults to always match
+        def initialize(
+          name: MATCH_ALL_PATTERN,
+          service: MATCH_ALL_PATTERN,
+          resource: MATCH_ALL_PATTERN,
+          tags: {}
+        )
+          super()
+
+          name = Matcher.glob_to_regex(name)
+          service = Matcher.glob_to_regex(service)
+          resource = Matcher.glob_to_regex(resource)
+          tags = tags.transform_values { |matcher| Matcher.glob_to_regex(matcher) }
+
+          @name = name || Datadog::Tracing::Sampling::Matcher::MATCH_ALL
+          @service = service || Datadog::Tracing::Sampling::Matcher::MATCH_ALL
+          @resource = resource || Datadog::Tracing::Sampling::Matcher::MATCH_ALL
+          @tags = tags
+        end
+
+        def match?(trace)
+          @name.match?(trace.name) &&
+            @service.match?(trace.service) &&
+            @resource.match?(trace.resource) &&
+            tags_match?(trace)
+        end
+
+        private
+
+        # Match against the trace tags and metrics.
+        def tags_match?(trace)
+          @tags.all? do |name, matcher|
+            tag = trace.get_tag(name)
+
+            # Floats: Matching floating point values with a non-zero decimal part is not supported.
+            # For floating point values with a non-zero decimal part, any all * pattern always returns true.
+            # Other patterns always return false.
+            return false if tag.is_a?(Float) && tag.truncate != tag && matcher != MATCH_ALL
+
+            # Format metrics as strings, to allow for partial number matching (/4.*/ matching '400', '404', etc.).
+            # Because metrics are floats, we use the '%g' format specifier to avoid trailing zeros, which
+            # can affect exact string matching (e.g. '400' matching '400.0').
+            tag = format('%g', tag) if tag.is_a?(Numeric)
+
+            matcher.match?(tag)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+require_relative 'all_sampler'
+require_relative 'rate_sampler'
+require_relative 'rate_by_service_sampler'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # {Datadog::Tracing::Sampling::PrioritySampler}
+      class PrioritySampler
+        # NOTE: We do not advise using a pre-sampler. It can save resources,
+        # but pre-sampling at rates < 100% may result in partial traces, unless
+        # the pre-sampler knows exactly how to drop a span without dropping its ancestors.
+        #
+        # Additionally, as service metrics are calculated in the Datadog Agent,
+        # the service's throughput will be underestimated.
+        attr_reader :pre_sampler, :priority_sampler
+
+        def initialize(opts = {})
+          @pre_sampler = opts[:base_sampler] || AllSampler.new
+          @priority_sampler = opts[:post_sampler] || RateByServiceSampler.new(decision: Sampling::Ext::Decision::AGENT_RATE)
+        end
+
+        # DEV-2.0:We should get rid of this complicated interaction between @pre_sampler and @priority_sampler.
+        # DEV-2.0:If the user wants to configure a custom sampler, we should only allow them to provide a complete
+        # DEV-2.0:sampling suite, not having this convoluted support for mixing arbitrary provided samplers in
+        # DEV-2.0:the PrioritySampler. Ideally, the PrioritySampler is only used by Datadog.
+        # DEV-2.0:There are too many edge cases and combinations to work around currently in this class.
+        def sample!(trace)
+          # The priority that was set before the sampler ran.
+          # This comes from distributed tracing priority propagation.
+          distributed_sampling_priority = priority_assigned?(trace)
+
+          # If pre-sampling is configured, do it first. (By default, this will sample at 100%.)
+          # NOTE: Pre-sampling at rates < 100% may result in partial traces; not recommended.
+          trace.sampled = pre_sample?(trace) ? preserving_priority_sampling(trace) { @pre_sampler.sample!(trace) } : true
+
+          if trace.sampled?
+            # If priority sampling has already been applied upstream, use that value.
+            return true if priority_assigned?(trace)
+
+            # Check with post sampler how we set the priority.
+            sample = priority_sample!(trace)
+
+            # Check if post sampler has already assigned a priority.
+            return true if priority_assigned?(trace)
+
+            # If not, use agent priority values.
+            priority = sample ? Sampling::Ext::Priority::AUTO_KEEP : Sampling::Ext::Priority::AUTO_REJECT
+            assign_priority!(trace, priority)
+          else
+            # If discarded by pre-sampling, set "reject" priority, so other
+            # services for the same trace don't sample needlessly.
+            assign_priority!(trace, Sampling::Ext::Priority::AUTO_REJECT)
+          end
+
+          trace.sampled?
+        ensure
+          if trace.sampling_priority && trace.sampling_priority > 0
+            # Don't modify decision if priority was set upstream.
+            if !distributed_sampling_priority && !trace.has_tag?(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+              # If no sampling priority being assigned at this point, a custom
+              # sampler implementation is configured: this means the user has
+              # full control over the sampling decision.
+              trace.set_tag(
+                Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER,
+                Sampling::Ext::Decision::MANUAL
+              )
+            end
+          else
+            # The sampler decided to not keep this span, removing sampling decision.
+            trace.clear_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+          end
+        end
+
+        # (see Datadog::Tracing::Sampling::RateByServiceSampler#update)
+        def update(rate_by_service, decision: nil)
+          @priority_sampler.update(rate_by_service, decision: decision)
+        end
+
+        # Check if the Priority Sampling decision is to keep or drop the trace.
+        # Other factors can influence the sampling decision; this method is only
+        # responsible for interpreting the Sampling Priority decision.
+        #
+        # @param priority_sampling [Integer] priority sampling number
+        # @return [Boolean] true if trace is "kept" by priority sampling
+        # @return [Boolean] false if trace is "dropped" by priority sampling
+        def self.sampled?(priority_sampling)
+          priority_sampling >= Ext::Priority::AUTO_KEEP
+        end
+
+        private
+
+        def pre_sample?(trace)
+          case @pre_sampler
+          when RateSampler
+            @pre_sampler.sample_rate < 1.0
+          when RateByServiceSampler
+            @pre_sampler.sample_rate(trace) < 1.0
+          else
+            true
+          end
+        end
+
+        def priority_assigned?(trace)
+          !trace.sampling_priority.nil?
+        end
+
+        def priority_sample!(trace)
+          preserving_sampling(trace) do
+            @priority_sampler.sample!(trace)
+          end
+        end
+
+        # Ensures the trace's priority sampling decision is not changed by the @pre_sampler.
+        # The @pre_sampler should only change `trace.sampled`.
+        def preserving_priority_sampling(trace)
+          sampling_priority = trace.sampling_priority
+          sampling_decision = trace.get_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+
+          yield.tap do
+            trace.sampling_priority = sampling_priority
+
+            if sampling_decision
+              trace.set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, sampling_decision)
+            else
+              trace.clear_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+            end
+          end
+        end
+
+        # Ensures the trace is always propagated to the writer and that
+        # the sample rate metric represents the true client-side sampling.
+        def preserving_sampling(trace)
+          pre_sample_rate_metric = trace.sample_rate
+
+          yield.tap do
+            # NOTE: We'll want to leave `trace.sampled = true` here; all spans for priority sampling must
+            #       be sent to the agent. Otherwise metrics for traces will not be accurate, since the
+            #       agent will have an incomplete dataset.
+            #
+            #       We also ensure that the agent knows we that our `post_sampler` is not performing true sampling,
+            #       to avoid erroneous metric upscaling.
+            trace.sampled = true
+
+            # Restore true sampling metric, as only the @pre_sampler can reject traces.
+            # otherwise if @pre_sampler is not enabled, sending this metric would be misleading.
+            trace.sample_rate = pre_sample_rate_metric || nil
+          end
+        end
+
+        def assign_priority!(trace, priority)
+          trace.sampling_priority = priority
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'sampler'
+require_relative 'rate_sampler'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # Samples at different rates by key.
+      class RateByKeySampler < Sampler
+        attr_reader \
+          :default_key
+
+        def initialize(default_key, default_rate = 1.0, decision: nil, &block)
+          super()
+
+          raise ArgumentError, 'No resolver given!' unless block
+
+          @default_key = default_key
+          @resolver = block
+          @mutex = Mutex.new
+          @samplers = {}
+
+          set_rate(default_key, default_rate, decision)
+        end
+
+        def resolve(trace)
+          @resolver.call(trace)
+        end
+
+        def default_sampler
+          @samplers[default_key]
+        end
+
+        def sample!(trace)
+          key = resolve(trace)
+
+          @mutex.synchronize do
+            @samplers.fetch(key, default_sampler).sample!(trace)
+          end
+        end
+
+        def sample_rate(trace)
+          key = resolve(trace)
+
+          @mutex.synchronize do
+            @samplers.fetch(key, default_sampler).sample_rate
+          end
+        end
+
+        def update(key, rate, decision: nil)
+          @mutex.synchronize do
+            set_rate(key, rate, decision)
+          end
+        end
+
+        def update_all(rate_by_key, decision: nil)
+          @mutex.synchronize do
+            rate_by_key.each { |key, rate| set_rate(key, rate, decision) }
+          end
+        end
+
+        def delete(key)
+          @mutex.synchronize do
+            @samplers.delete(key)
+          end
+        end
+
+        def delete_if(&block)
+          @mutex.synchronize do
+            @samplers.delete_if(&block)
+          end
+        end
+
+        def length
+          @samplers.length
+        end
+
+        private
+
+        def set_rate(key, rate, decision)
+          @samplers[key] = RateSampler.new(rate, decision: decision)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'rate_by_key_sampler'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # {Datadog::Tracing::Sampling::RateByServiceSampler} samples different services at different rates
+      class RateByServiceSampler < RateByKeySampler
+        DEFAULT_KEY = 'service:,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, 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, decision: decision)
+
+          # Emit metric for service cache size
+          Datadog.health_metrics.sampling_service_cache_length(length)
+        end
+
+        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
+
+          "service:#{trace.service},env:#{env}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'sampler'
+require_relative '../utils'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # {Datadog::Tracing::Sampling::RateSampler} is based on a sample rate.
+      class RateSampler < Sampler
+        KNUTH_FACTOR = 1111111111111111111
+        UINT64_MODULO = (1 << 64)
+
+        # Initialize a {Datadog::Tracing::Sampling::RateSampler}.
+        # This sampler keeps a random subset of the traces. Its main purpose is to
+        # reduce the instrumentation footprint.
+        #
+        # @param sample_rate [Numeric] the sample rate between 0.0 and 1.0, inclusive.
+        #   0.0 means that no trace will be sampled; 1.0 means that all traces will be  sampled.
+        def initialize(sample_rate = 1.0, decision: nil)
+          super()
+
+          unless sample_rate >= 0.0 && sample_rate <= 1.0
+            Datadog.logger.warn('sample rate is not between 0 and 1, falling back to 1')
+            sample_rate = 1.0
+          end
+
+          self.sample_rate = sample_rate
+
+          @decision = decision
+        end
+
+        def sample_rate(*_)
+          @sample_rate
+        end
+
+        def sample_rate=(sample_rate)
+          @sample_rate = sample_rate
+          @sampling_id_threshold = sample_rate * Tracing::Utils::EXTERNAL_MAX_ID
+        end
+
+        def sample?(trace)
+          ((trace.id * KNUTH_FACTOR) % UINT64_MODULO) <= @sampling_id_threshold
+        end
+
+        def sample!(trace)
+          sampled = sample?(trace)
+
+          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
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'matcher'
+require_relative 'rate_sampler'
+require_relative '../../core/telemetry/logger'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # Sampling rule that dictates if a trace matches
+      # a specific criteria and what sampling strategy to
+      # apply in case of a positive match.
+      class Rule
+        PROVENANCE_LOCAL = :local
+        PROVENANCE_REMOTE_USER = :customer
+        PROVENANCE_REMOTE_DYNAMIC = :dynamic
+
+        attr_reader :matcher, :sampler, :provenance
+
+        # @param [Matcher] matcher A matcher to verify trace conformity against
+        # @param [Sampler] sampler A sampler to be consulted on a positive match
+        def initialize(matcher, sampler, provenance)
+          @matcher = matcher
+          @sampler = sampler
+          @provenance = provenance
+        end
+
+        # Evaluates if the provided `trace` conforms to the `matcher`.
+        #
+        # @param [TraceOperation] trace
+        # @return [Boolean] whether this rules applies to the trace
+        # @return [NilClass] if the matcher fails errs during evaluation
+        def match?(trace)
+          @matcher.match?(trace)
+        rescue => e
+          Datadog.logger.error(
+            "Matcher failed. Cause: #{e.class.name} #{e.message} Source: #{Array(e.backtrace).first}"
+          )
+          Datadog::Core::Telemetry::Logger.report(e, description: 'Matcher failed')
+          nil
+        end
+
+        # (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
+      # trace name and/or service name and
+      # applies a fixed sampling to matching spans.
+      class SimpleRule < Rule
+        # @param name [String,Regexp,Proc] Matcher for case equality (===) with the trace name, defaults to always match
+        # @param service [String,Regexp,Proc] Matcher for case equality (===) with the service name,
+        #                defaults to always match
+        # @param resource [String,Regexp,Proc] Matcher for case equality (===) with the resource name,
+        #                defaults to always match
+        # @param sample_rate [Float] Sampling rate between +[0,1]+
+        def initialize(
+          name: SimpleMatcher::MATCH_ALL_PATTERN, service: SimpleMatcher::MATCH_ALL_PATTERN,
+          resource: SimpleMatcher::MATCH_ALL_PATTERN, tags: {},
+          provenance: Rule::PROVENANCE_LOCAL,
+          sample_rate: 1.0
+        )
+          # We want to allow 0.0 to drop all traces, but {Datadog::Tracing::Sampling::RateSampler}
+          # considers 0.0 an invalid rate and falls back to 100% sampling.
+          #
+          # We address that here by not setting the rate in the constructor,
+          # but using the setter method.
+          #
+          # We don't want to make this change directly to {Datadog::Tracing::Sampling::RateSampler}
+          # because it breaks its current contract to existing users.
+          sampler = RateSampler.new
+          sampler.sample_rate = sample_rate
+
+          super(SimpleMatcher.new(name: name, service: service, resource: resource, tags: tags), sampler, provenance)
+        end
+      end
+    end
+  end
+end