ddtrace 1.1.0 → 1.9.0

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

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

@@ -0,0 +1,75 @@
+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!(span_op)
+
+              next if decision == :not_matched # Iterate until we find a matching decision
+
+              if decision == :kept
+                trace_op.set_tag(
+                  Metadata::Ext::Distributed::TAG_DECISION_MAKER,
+                  Sampling::Ext::Decision::SPAN_SAMPLING_RATE
+                )
+              end
+
+              break # Found either a `kept` or `rejected` decision
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/span.rb

@@ -2,11 +2,11 @@
 
 # typed: true
 
-require 'datadog/core/utils'
-require 'datadog/core/utils/safe_dup'
+require_relative '../core/utils/safe_dup'
+require_relative 'utils'
 
-require 'datadog/tracing/metadata/ext'
-require 'datadog/tracing/metadata'
+require_relative 'metadata/ext'
+require_relative 'metadata'
 
 module Datadog
   module Tracing
@@ -19,19 +19,6 @@ module Datadog
     class Span
       include Metadata
 
-      # The max value for a {Datadog::Tracing::Span} identifier.
-      # Span and trace identifiers should be strictly positive and strictly inferior to this limit.
-      #
-      # 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
-
       attr_accessor \
         :end_time,
         :id,
@@ -63,6 +50,7 @@ module Datadog
       # * +type+: the type of the span (such as +http+, +db+ and so on)
       # * +parent_id+: the identifier of the parent span
       # * +trace_id+: the identifier of the root span for this trace
+      # * +service_entry+: whether it is a service entry span.
       # TODO: Remove span_type
       def initialize(
         name,
@@ -78,16 +66,17 @@ module Datadog
         start_time: nil,
         status: 0,
         type: span_type,
-        trace_id: nil
+        trace_id: nil,
+        service_entry: nil
       )
         @name = Core::Utils::SafeDup.frozen_or_dup(name)
         @service = Core::Utils::SafeDup.frozen_or_dup(service)
         @resource = Core::Utils::SafeDup.frozen_or_dup(resource)
         @type = Core::Utils::SafeDup.frozen_or_dup(type)
 
-        @id = id || Core::Utils.next_id
+        @id = id || Tracing::Utils.next_id
         @parent_id = parent_id || 0
-        @trace_id = trace_id || Core::Utils.next_id
+        @trace_id = trace_id || Tracing::Utils.next_id
 
         @meta = meta || {}
         @metrics = metrics || {}
@@ -103,6 +92,11 @@ module Datadog
         # 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 = duration
+
+        @service_entry = service_entry
+
+        # Mark with the service entry span metric, if applicable
+        set_metric(Metadata::Ext::TAG_TOP_LEVEL, 1.0) if service_entry
       end
 
       # Return whether the duration is started or not
@@ -207,6 +201,16 @@ module Datadog
       def duration_nano
         (duration * 1e9).to_i
       end
+
+      # https://docs.datadoghq.com/tracing/visualization/#service-entry-span
+      # A span is a service entry span when it is the entrypoint method for a request to a service.
+      # You can visualize this within Datadog APM when the color of the immediate parent on a flame graph is a different
+      # color. Services are also listed on the right when viewing a flame graph.
+      #
+      # @return [Boolean] `true` if the span is a serivce entry span
+      def service_entry?
+        @service_entry == true
+      end
     end
   end
 end

data/lib/datadog/tracing/span_operation.rb

@@ -2,15 +2,16 @@
 
 require 'time'
 
-require 'datadog/core'
-require 'datadog/core/environment/identity'
-require 'datadog/core/utils'
-require 'datadog/core/utils/time'
+require_relative '../core'
+require_relative '../core/environment/identity'
+require_relative '../core/utils'
+require_relative '../core/utils/time'
 
-require 'datadog/tracing/metadata/ext'
-require 'datadog/tracing/event'
-require 'datadog/tracing/span'
-require 'datadog/tracing/metadata'
+require_relative 'event'
+require_relative 'metadata'
+require_relative 'metadata/ext'
+require_relative 'span'
+require_relative 'utils'
 
 module Datadog
   module Tracing
@@ -18,7 +19,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
@@ -62,9 +62,9 @@ module Datadog
         self.type = type
         self.resource = resource
 
-        @id = Core::Utils.next_id
+        @id = Tracing::Utils.next_id
         @parent_id = parent_id || 0
-        @trace_id = trace_id || Core::Utils.next_id
+        @trace_id = trace_id || Tracing::Utils.next_id
 
         @status = 0
 
@@ -468,7 +468,8 @@ module Datadog
           start_time: @start_time,
           status: @status,
           type: @type,
-          trace_id: @trace_id
+          trace_id: @trace_id,
+          service_entry: parent.nil? || (service && parent.service != service)
         )
       end
 
@@ -515,6 +516,5 @@ module Datadog
       alias :span_type :type
       alias :span_type= :type=
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/datadog/tracing/sync_writer.rb

@@ -1,12 +1,12 @@
 # typed: true
 
-require 'datadog/core'
+require_relative '../core'
 
-require 'datadog/tracing/pipeline'
-require 'datadog/tracing/runtime/metrics'
-require 'datadog/tracing/writer'
+require_relative 'pipeline'
+require_relative 'runtime/metrics'
+require_relative 'writer'
 
-require 'ddtrace/transport/http'
+require_relative '../../ddtrace/transport/http'
 
 module Datadog
   module Tracing

data/lib/datadog/tracing/trace_digest.rb

@@ -6,12 +6,84 @@ module Datadog
     # Used to propagate context and continue traces across execution boundaries.
     # @public_api
     class TraceDigest
+      # @!attribute [r] span_id
+      #   Datadog id for the currently active span.
+      #   @return [Integer]
+      # @!attribute [r] span_name
+      #   The operation name of the currently active span.
+      #   @return [String]
+      # @!attribute [r] span_resource
+      #   The resource name of the currently active span.
+      #   @return [String]
+      # @!attribute [r] span_service
+      #   The service of the currently active span.
+      #   @return [String]
+      # @!attribute [r] span_type
+      #   The type of the currently active span.
+      #   @return [String]
+      # @!attribute [r] trace_distributed_tags
+      #   Datadog-specific tags that support richer distributed tracing association.
+      #   @return [Hash<String,String>]
+      # @!attribute [r] trace_hostname
+      #   The hostname of the currently active trace. Use to attribute traces to hosts.
+      #   @return [String]
+      # @!attribute [r] trace_id
+      #   Datadog id for the currently active trace.
+      #   @return [Integer]
+      # @!attribute [r] trace_name
+      #   Operation name for the currently active trace.
+      #   @return [Integer]
+      # @!attribute [r] trace_origin
+      #   Datadog-specific attribution of this trace's creation.
+      #   @return [String]
+      # @!attribute [r] trace_process_id
+      #   The OS-specific process id.
+      #   @return [Integer]
+      # @!attribute [r] trace_resource
+      #   The resource name of the currently active trace.
+      #   @return [String]
+      # @!attribute [r] trace_runtime_id
+      #   Unique id to this Ruby process. Used to differentiate traces coming from
+      #   child processes forked from same parent process.
+      #   @return [String]
+      # @!attribute [r] trace_sampling_priority
+      #   Datadog-specific sampling decision for the currently active trace.
+      #   @return [Integer]
+      # @!attribute [r] trace_service
+      #   The service of the currently active trace.
+      #   @return [String]
+      # @!attribute [r] trace_distributed_id
+      #   The trace id extracted from a distributed context, if different from `trace_id`.
+      #
+      #   The current use case is when the distributed context has a trace id integer larger than 64-bit:
+      #   This attribute will preserve the original id, while `trace_id` will only contain the lower 64 bits.
+      #   @return [Integer]
+      #   @see https://www.w3.org/TR/trace-context/#trace-id
+      # @!attribute [r] trace_flags
+      #   The W3C "trace-flags" extracted from a distributed context. This field is an 8-bit unsigned integer.
+      #   @return [Integer]
+      #   @see https://www.w3.org/TR/trace-context/#trace-flags
+      # @!attribute [r] trace_state
+      #   The W3C "tracestate" extracted from a distributed context.
+      #   This field is a string representing vendor-specific distribution data.
+      #   The `dd=` entry is removed from `trace_state` as its value is dynamically calculated
+      #   on every propagation injection.
+      #   @return [String]
+      #   @see https://www.w3.org/TR/trace-context/#tracestate-header
+      # @!attribute [r] trace_state_unknown_fields
+      #   From W3C "tracestate"'s `dd=` entry, when keys are not recognized they are stored here long with their values.
+      #   This allows later propagation to include those unknown fields, as they can represent future versions of the spec
+      #   sending data through this service. This value ends in a trailing `;` to facilitate serialization.
+      #   @return [String]
+      # TODO: The documentation for the last attribute above won't be rendered.
+      # TODO: This might be a YARD bug as adding an attribute, making it now second-last attribute, renders correctly.
       attr_reader \
         :span_id,
         :span_name,
         :span_resource,
         :span_service,
         :span_type,
+        :trace_distributed_tags,
         :trace_hostname,
         :trace_id,
         :trace_name,
@@ -20,7 +92,11 @@ module Datadog
         :trace_resource,
         :trace_runtime_id,
         :trace_sampling_priority,
-        :trace_service
+        :trace_service,
+        :trace_distributed_id,
+        :trace_flags,
+        :trace_state,
+        :trace_state_unknown_fields
 
       def initialize(
         span_id: nil,
@@ -28,6 +104,7 @@ module Datadog
         span_resource: nil,
         span_service: nil,
         span_type: nil,
+        trace_distributed_tags: nil,
         trace_hostname: nil,
         trace_id: nil,
         trace_name: nil,
@@ -36,13 +113,18 @@ module Datadog
         trace_resource: nil,
         trace_runtime_id: nil,
         trace_sampling_priority: nil,
-        trace_service: nil
+        trace_service: nil,
+        trace_distributed_id: nil,
+        trace_flags: nil,
+        trace_state: nil,
+        trace_state_unknown_fields: nil
       )
         @span_id = span_id
         @span_name = span_name && span_name.dup.freeze
         @span_resource = span_resource && span_resource.dup.freeze
         @span_service = span_service && span_service.dup.freeze
         @span_type = span_type && span_type.dup.freeze
+        @trace_distributed_tags = trace_distributed_tags && trace_distributed_tags.dup.freeze
         @trace_hostname = trace_hostname && trace_hostname.dup.freeze
         @trace_id = trace_id
         @trace_name = trace_name && trace_name.dup.freeze
@@ -52,6 +134,10 @@ module Datadog
         @trace_runtime_id = trace_runtime_id && trace_runtime_id.dup.freeze
         @trace_sampling_priority = trace_sampling_priority
         @trace_service = trace_service && trace_service.dup.freeze
+        @trace_distributed_id = trace_distributed_id
+        @trace_flags = trace_flags
+        @trace_state = trace_state && trace_state.dup.freeze
+        @trace_state_unknown_fields = trace_state_unknown_fields && trace_state_unknown_fields.dup.freeze
 
         freeze
       end