ddtrace 0.13.0 → 0.47.0

data/lib/ddtrace/sampling/rule.rb

@@ -0,0 +1,61 @@
+require 'forwardable'
+
+require 'ddtrace/sampling/matcher'
+require 'ddtrace/sampler'
+
+module Datadog
+  module Sampling
+    # Sampling rule that dictates if a span matches
+    # a specific criteria and what sampling strategy to
+    # apply in case of a positive match.
+    class Rule
+      extend Forwardable
+
+      attr_reader :matcher, :sampler
+
+      # @param [Matcher] matcher A matcher to verify span conformity against
+      # @param [Sampler] sampler A sampler to be consulted on a positive match
+      def initialize(matcher, sampler)
+        @matcher = matcher
+        @sampler = sampler
+      end
+
+      # Evaluates if the provided `span` conforms to the `matcher`.
+      #
+      # @param [Span] span
+      # @return [Boolean] whether this rules applies to the span
+      # @return [NilClass] if the matcher fails errs during evaluation
+      def match?(span)
+        @matcher.match?(span)
+      rescue => e
+        Datadog.logger.error("Matcher failed. Cause: #{e.message} Source: #{e.backtrace.first}")
+        nil
+      end
+
+      def_delegators :@sampler, :sample?, :sample_rate
+    end
+
+    # A \Rule that matches a span based on
+    # operation 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 span name, defaults to always match
+      # @param service [String,Regexp,Proc] Matcher for case equality (===) with the service name, defaults to always match
+      # @param sample_rate [Float] Sampling rate between +[0,1]+
+      def initialize(name: SimpleMatcher::MATCH_ALL, service: SimpleMatcher::MATCH_ALL, sample_rate: 1.0)
+        # We want to allow 0.0 to drop all traces, but \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 \RateSampler
+        # because it breaks its current contract to existing users.
+        sampler = Datadog::RateSampler.new
+        sampler.sample_rate = sample_rate
+
+        super(SimpleMatcher.new(name: name, service: service), sampler)
+      end
+    end
+  end
+end

data/lib/ddtrace/sampling/rule_sampler.rb

@@ -0,0 +1,126 @@
+require 'forwardable'
+
+require 'ddtrace/ext/priority'
+
+require 'ddtrace/ext/sampling'
+require 'ddtrace/sampler'
+require 'ddtrace/sampling/rate_limiter'
+
+module Datadog
+  module Sampling
+    # Span {Sampler} that applies a set of {Rule}s to decide
+    # on sampling outcome. Then, a rate limiter is applied.
+    #
+    # If a span does not conform to any rules, a default
+    # sampling strategy is applied.
+    class RuleSampler
+      extend Forwardable
+
+      AGENT_RATE_METRIC_KEY = '_dd.agent_psr'.freeze
+
+      attr_reader :rules, :rate_limiter, :default_sampler
+
+      # @param rules [Array<Rule>] ordered list of rules to be applied to a span
+      # @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 span,
+      #   between +[0,1]+, defaults to +1+
+      # @param default_sampler [Sample] fallback strategy when no rules apply to a span
+      def initialize(rules = [],
+                     rate_limit: Datadog.configuration.sampling.rate_limit,
+                     rate_limiter: nil,
+                     default_sample_rate: Datadog.configuration.sampling.default_rate,
+                     default_sampler: nil)
+
+        @rules = rules
+
+        @rate_limiter = if rate_limiter
+                          rate_limiter
+                        elsif rate_limit
+                          Datadog::Sampling::TokenBucket.new(rate_limit)
+                        else
+                          Datadog::Sampling::UnlimitedLimiter.new
+                        end
+
+        @default_sampler = if default_sampler
+                             default_sampler
+                           elsif default_sample_rate
+                             # We want to allow 0.0 to drop all traces, but \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 \RateSampler
+                             # because it breaks its current contract to existing users.
+                             Datadog::RateSampler.new.tap { |s| s.sample_rate = default_sample_rate }
+                           else
+                             RateByServiceSampler.new(1.0, env: -> { Datadog.tracer.tags[:env] })
+                           end
+      end
+
+      # /RuleSampler's components (it's rate limiter, for example) are
+      # not be guaranteed to be size-effect free.
+      # It is not possible to guarantee that a call to {#sample?} will
+      # return the same result as a successive call to {#sample!} with the same span.
+      #
+      # Use {#sample!} instead
+      def sample?(_span)
+        raise 'RuleSampler cannot be evaluated without side-effects'
+      end
+
+      def sample!(span)
+        sampled = sample_span(span) do |s|
+          @default_sampler.sample!(s).tap do
+            # We want to make sure the span 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.
+            if @default_sampler.is_a?(RateByServiceSampler)
+              s.set_metric(AGENT_RATE_METRIC_KEY, @default_sampler.sample_rate(span))
+            end
+          end
+        end
+
+        sampled.tap do
+          span.sampled = sampled
+        end
+      end
+
+      def update(*args)
+        return false unless @default_sampler.respond_to?(:update)
+
+        @default_sampler.update(*args)
+      end
+
+      private
+
+      def sample_span(span)
+        rule = @rules.find { |r| r.match?(span) }
+
+        return yield(span) if rule.nil?
+
+        sampled = rule.sample?(span)
+        sample_rate = rule.sample_rate(span)
+
+        set_rule_metrics(span, sample_rate)
+
+        return false unless sampled
+
+        rate_limiter.allow?(1).tap do
+          set_limiter_metrics(span, rate_limiter.effective_rate)
+        end
+      rescue StandardError => e
+        Datadog.logger.error("Rule sampling failed. Cause: #{e.message} Source: #{e.backtrace.first}")
+        yield(span)
+      end
+
+      def set_rule_metrics(span, sample_rate)
+        span.set_metric(Ext::Sampling::RULE_SAMPLE_RATE, sample_rate)
+      end
+
+      def set_limiter_metrics(span, limiter_rate)
+        span.set_metric(Ext::Sampling::RATE_LIMITER_RATE, limiter_rate)
+      end
+    end
+  end
+end

data/lib/ddtrace/span.rb

@@ -1,8 +1,14 @@
-require 'time'
-require 'thread'
+# frozen_string_literal: true
 
+require 'time'
 require 'ddtrace/utils'
 require 'ddtrace/ext/errors'
+require 'ddtrace/ext/priority'
+require 'ddtrace/environment'
+require 'ddtrace/analytics'
+require 'ddtrace/forced_tracing'
+require 'ddtrace/diagnostics/health'
+require 'ddtrace/utils/time'
 
 module Datadog
   # Represents a logical unit of work in the system. Each trace consists of one or more spans.
@@ -10,21 +16,36 @@ module Datadog
   # spent on a distributed call on a separate machine, or the time spent in a small component
   # within a larger operation. Spans can be nested within each other, and in those instances
   # will have a parent-child relationship.
+  #
+  # rubocop:disable Metrics/ClassLength
   class Span
+    prepend Analytics::Span
+    prepend ForcedTracing::Span
+
     # The max value for a \Span identifier.
     # Span and trace identifiers should be strictly positive and strictly inferior to this limit.
     #
-    # Limited to 63-bit positive integers, as some other languages might be limited to this,
-    # and IDs need to be easy to port across various languages and platforms.
-    MAX_ID = 2**63
+    # Limited to +2<<62-1+ positive integers, as Ruby is able to represent such numbers "inline",
+    # inside a +VALUE+ scalar, thus not requiring memory allocation.
+    #
+    # The range of IDs also has to consider portability across different languages and platforms.
+    RUBY_MAX_ID = (1 << 62) - 1
+
+    # While we only generate 63-bit integers due to limitations in other languages, we support
+    # parsing 64-bit integers for distributed tracing since an upstream system may generate one
+    EXTERNAL_MAX_ID = 1 << 64
+
+    # This limit is for numeric tags because uint64 could end up rounded.
+    NUMERIC_TAG_SIZE_RANGE = (-1 << 53..1 << 53).freeze
 
     attr_accessor :name, :service, :resource, :span_type,
-                  :start_time, :end_time,
                   :span_id, :trace_id, :parent_id,
                   :status, :sampled,
                   :tracer, :context
 
-    attr_reader :parent
+    attr_reader :parent, :start_time, :end_time
+
+    attr_writer :duration
 
     # Create a new span linked to the given tracer. Call the \Tracer method <tt>start_span()</tt>
     # and then <tt>finish()</tt> once the tracer operation is over.
@@ -56,38 +77,91 @@ module Datadog
       @parent = nil
       @sampled = true
 
-      @start_time = nil # set by Tracer.start_span
-      @end_time = nil # set by Span.finish
+      @allocation_count_start = now_allocations
+      @allocation_count_finish = @allocation_count_start
+
+      # start_time and end_time track wall clock. In Ruby, wall clock
+      # has less accuracy than monotonic clock, so if possible we look to only use wall clock
+      # to measure duration when a time is supplied by the user, or if monotonic clock
+      # is unsupported.
+      @start_time = nil
+      @end_time = nil
+
+      # duration_start and duration_end track monotonic clock, and may remain nil in cases where it
+      # is known that we have to use wall clock to measure duration.
+      @duration_start = nil
+      @duration_end = nil
     end
 
     # Set the given key / value tag pair on the span. Keys and values
     # must be strings. A valid example is:
     #
     #   span.set_tag('http.method', request.method)
-    def set_tag(key, value)
-      @meta[key] = value.to_s
+    def set_tag(key, value = nil)
+      # Keys must be unique between tags and metrics
+      @metrics.delete(key)
+
+      # Ensure `http.status_code` is always a string so it is added to
+      #   @meta instead of @metrics
+      # DEV: This is necessary because the agent looks to `meta['http.status_code']` for
+      #   tagging necessary metrics
+      value = value.to_s if key == Ext::HTTP::STATUS_CODE
+
+      # NOTE: Adding numeric tags as metrics is stop-gap support
+      #       for numeric typed tags. Eventually they will become
+      #       tags again.
+      # Any numeric that is not an integer greater than max size is logged as a metric.
+      # Everything else gets logged as a tag.
+      if value.is_a?(Numeric) && !(value.is_a?(Integer) && !NUMERIC_TAG_SIZE_RANGE.cover?(value))
+        set_metric(key, value)
+      else
+        @meta[key] = value.to_s
+      end
     rescue StandardError => e
-      Datadog::Tracer.log.debug("Unable to set the tag #{key}, ignoring it. Caused by: #{e}")
+      Datadog.logger.debug("Unable to set the tag #{key}, ignoring it. Caused by: #{e}")
+    end
+
+    # Sets tags from given hash, for each key in hash it sets the tag with that key
+    # and associated value from the hash. It is shortcut for `set_tag`. Keys and values
+    # of the hash must be strings. Note that nested hashes are not supported.
+    # A valid example is:
+    #
+    #   span.set_tags({ "http.method" => "GET", "user.id" => "234" })
+    def set_tags(tags)
+      tags.each { |k, v| set_tag(k, v) }
+    end
+
+    # This method removes a tag for the given key.
+    def clear_tag(key)
+      @meta.delete(key)
     end
 
     # Return the tag with the given key, nil if it doesn't exist.
     def get_tag(key)
-      @meta[key]
+      @meta[key] || @metrics[key]
     end
 
     # This method sets a tag with a floating point value for the given key. It acts
     # like `set_tag()` and it simply add a tag without further processing.
     def set_metric(key, value)
+      # Keys must be unique between tags and metrics
+      @meta.delete(key)
+
       # enforce that the value is a floating point number
       value = Float(value)
       @metrics[key] = value
     rescue StandardError => e
-      Datadog::Tracer.log.debug("Unable to set the metric #{key}, ignoring it. Caused by: #{e}")
+      Datadog.logger.debug("Unable to set the metric #{key}, ignoring it. Caused by: #{e}")
+    end
+
+    # This method removes a metric for the given key. It acts like {#remove_tag}.
+    def clear_metric(key)
+      @metrics.delete(key)
     end
 
     # Return the metric with the given key, nil if it doesn't exist.
     def get_metric(key)
-      @metrics[key]
+      @metrics[key] || @meta[key]
     end
 
     # Mark the span with the given error.
@@ -100,6 +174,28 @@ module Datadog
       set_tag(Ext::Errors::STACK, e.backtrace) unless e.backtrace.empty?
     end
 
+    # Mark the span started at the current time.
+    def start(start_time = nil)
+      # A span should not be started twice. However, this is existing
+      # behavior and so we maintain it for backward compatibility for those
+      # who are using async manual instrumentation that may rely on this
+
+      @start_time = start_time || Utils::Time.now.utc
+      @duration_start = start_time.nil? ? duration_marker : nil
+
+      self
+    end
+
+    # for backwards compatibility
+    def start_time=(time)
+      time.tap { start(time) }
+    end
+
+    # for backwards compatibility
+    def end_time=(time)
+      time.tap { finish(time) }
+    end
+
     # Mark the span finished at the current time and submit it.
     def finish(finish_time = nil)
       # A span should not be finished twice. Note that this is not thread-safe,
@@ -108,12 +204,17 @@ module Datadog
       # fallback to avoid very bad things and protect you in most common cases.
       return if finished?
 
-      # Provide a default start_time if unset, but this should have been set by start_span.
-      # Using now here causes 0-duration spans, still, this is expected, as we never
-      # explicitely say when it started.
-      @start_time ||= Time.now.utc
+      @allocation_count_finish = now_allocations
+
+      now = Utils::Time.now.utc
 
-      @end_time = finish_time.nil? ? Time.now.utc : finish_time # finish this
+      # Provide a default start_time if unset.
+      # Using `now` here causes duration to be 0; this is expected
+      # behavior when start_time is unknown.
+      start(finish_time || now) unless started?
+
+      @end_time = finish_time || now
+      @duration_end = finish_time.nil? ? duration_marker : nil
 
       # Finish does not really do anything if the span is not bound to a tracer and a context.
       return self if @tracer.nil? || @context.nil?
@@ -121,22 +222,18 @@ module Datadog
       # spans without a service would be dropped, so here we provide a default.
       # This should really never happen with integrations in contrib, as a default
       # service is always set. It's only for custom instrumentation.
-      @service ||= @tracer.default_service unless @tracer.nil?
+      @service ||= (@tracer && @tracer.default_service)
 
       begin
         @context.close_span(self)
         @tracer.record(self)
       rescue StandardError => e
-        Datadog::Tracer.log.debug("error recording finished trace: #{e}")
+        Datadog.logger.debug("error recording finished trace: #{e}")
+        Datadog.health_metrics.error_span_finish(1, tags: ["error:#{e.class.name}"])
       end
       self
     end
 
-    # Return whether the span is finished or not.
-    def finished?
-      !@end_time.nil?
-    end
-
     # Return a string representation of the span.
     def to_s
       "Span(name:#{@name},sid:#{@span_id},tid:#{@trace_id},pid:#{@parent_id})"
@@ -163,6 +260,10 @@ module Datadog
       end
     end
 
+    def allocations
+      @allocation_count_finish - @allocation_count_start
+    end
+
     # Return the hash representation of the current span.
     def to_hash
       h = {
@@ -175,22 +276,80 @@ module Datadog
         type: @span_type,
         meta: @meta,
         metrics: @metrics,
+        allocations: allocations,
         error: @status
       }
 
-      if !@start_time.nil? && !@end_time.nil?
-        h[:start] = (@start_time.to_f * 1e9).to_i
-        h[:duration] = ((@end_time - @start_time) * 1e9).to_i
+      if finished?
+        h[:start] = start_time_nano
+        h[:duration] = duration_nano
       end
 
       h
     end
 
+    # MessagePack serializer interface. Making this object
+    # respond to `#to_msgpack` allows it to be automatically
+    # serialized by MessagePack.
+    #
+    # This is more efficient than doing +MessagePack.pack(span.to_hash)+
+    # as we don't have to create an intermediate Hash.
+    #
+    # @param packer [MessagePack::Packer] serialization buffer, can be +nil+ with JRuby
+    def to_msgpack(packer = nil)
+      # As of 1.3.3, JRuby implementation doesn't pass an existing packer
+      packer ||= MessagePack::Packer.new
+
+      if finished?
+        packer.write_map_header(13) # Set header with how many elements in the map
+
+        packer.write('start')
+        packer.write(start_time_nano)
+
+        packer.write('duration')
+        packer.write(duration_nano)
+      else
+        packer.write_map_header(11) # Set header with how many elements in the map
+      end
+
+      # DEV: We use strings as keys here, instead of symbols, as
+      # DEV: MessagePack will ultimately convert them to strings.
+      # DEV: By providing strings directly, we skip this indirection operation.
+      packer.write('span_id')
+      packer.write(@span_id)
+      packer.write('parent_id')
+      packer.write(@parent_id)
+      packer.write('trace_id')
+      packer.write(@trace_id)
+      packer.write('name')
+      packer.write(@name)
+      packer.write('service')
+      packer.write(@service)
+      packer.write('resource')
+      packer.write(@resource)
+      packer.write('type')
+      packer.write(@span_type)
+      packer.write('meta')
+      packer.write(@meta)
+      packer.write('metrics')
+      packer.write(@metrics)
+      packer.write('allocations')
+      packer.write(allocations)
+      packer.write('error')
+      packer.write(@status)
+      packer
+    end
+
+    # JSON serializer interface.
+    # Used by older version of the transport.
+    def to_json(*args)
+      to_hash.to_json(*args)
+    end
+
     # Return a human readable version of the span
     def pretty_print(q)
-      start_time = (@start_time.to_f * 1e9).to_i rescue '-'
-      end_time = (@end_time.to_f * 1e9).to_i rescue '-'
-      duration = ((@end_time - @start_time) * 1e9).to_i rescue 0
+      start_time = (self.start_time.to_f * 1e9).to_i
+      end_time = (self.end_time.to_f * 1e9).to_i
       q.group 0 do
         q.breakable
         q.text "Name: #{@name}\n"
@@ -203,7 +362,8 @@ module Datadog
         q.text "Error: #{@status}\n"
         q.text "Start: #{start_time}\n"
         q.text "End: #{end_time}\n"
-        q.text "Duration: #{duration}\n"
+        q.text "Duration: #{duration.to_f if finished?}\n"
+        q.text "Allocations: #{allocations}\n"
         q.group(2, 'Tags: [', "]\n") do
           q.breakable
           q.seplist @meta.each do |key, value|
@@ -218,5 +378,55 @@ module Datadog
         end
       end
     end
+
+    # Return whether the duration is started or not
+    def started?
+      !@start_time.nil?
+    end
+
+    # Return whether the duration is finished or not.
+    def finished?
+      !@end_time.nil?
+    end
+
+    def duration
+      if @duration_end.nil? || @duration_start.nil?
+        @end_time - @start_time
+      else
+        @duration_end - @duration_start
+      end
+    end
+
+    private
+
+    def duration_marker
+      Utils::Time.get_time
+    end
+
+    if defined?(JRUBY_VERSION) || Gem::Version.new(RUBY_VERSION) < Gem::Version.new(VERSION::MINIMUM_RUBY_VERSION)
+      def now_allocations
+        0
+      end
+    elsif Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.2.0')
+      def now_allocations
+        GC.stat.fetch(:total_allocated_object)
+      end
+    else
+      def now_allocations
+        GC.stat(:total_allocated_objects)
+      end
+    end
+
+    # Used for serialization
+    # @return [Integer] in nanoseconds since Epoch
+    def start_time_nano
+      @start_time.to_i * 1000000000 + @start_time.nsec
+    end
+
+    # Used for serialization
+    # @return [Integer] in nanoseconds since Epoch
+    def duration_nano
+      (duration * 1e9).to_i
+    end
   end
 end