ddtrace 0.53.0 → 1.9.0

data/lib/datadog/tracing/distributed/helpers.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative '../sampling/ext'
+require_relative '../utils'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Helpers module provides common helper functions for distributed tracing data
+      module Helpers
+        # Base provides common methods for distributed helper classes
+        def self.clamp_sampling_priority(sampling_priority)
+          # B3 doesn't have our -1 (USER_REJECT) and 2 (USER_KEEP) priorities so convert to acceptable 0/1
+          if sampling_priority < 0
+            sampling_priority = Sampling::Ext::Priority::AUTO_REJECT
+          elsif sampling_priority > 1
+            sampling_priority = Sampling::Ext::Priority::AUTO_KEEP
+          end
+
+          sampling_priority
+        end
+
+        def self.truncate_base16_number(value)
+          # Lowercase if we want to parse base16 e.g. 3E8 => 3e8
+          # DEV: Ruby will parse `3E8` just fine, but to test
+          #      `num.to_s(base) == value` we need to lowercase
+          value = value.downcase
+
+          # Truncate to trailing 16 characters if length is greater than 16
+          # https://github.com/apache/incubator-zipkin/blob/21fe362899fef5c593370466bc5707d3837070c2/zipkin/src/main/java/zipkin2/storage/StorageComponent.java#L49-L53
+          # DEV: This ensures we truncate B3 128-bit trace and span ids to 64-bit
+          value = value[value.length - 16, 16] if value.length > 16
+
+          # Remove any leading zeros
+          # DEV: When we call `num.to_s(16)` later Ruby will not add leading zeros
+          #      for us so we want to make sure the comparision will work as expected
+          # DEV: regex, remove all leading zeros up until we find the last 0 in the string
+          #      or we find the first non-zero, this allows `'0000' -> '0'` and `'00001' -> '1'`
+          value.sub(/^0*(?=(0$)|[^0])/, '')
+        end
+
+        # DEV: move `base` to a keyword argument
+        def self.value_to_id(value, base = 10)
+          id = value_to_number(value, base)
+
+          # Return early if we could not parse a number
+          return if id.nil?
+
+          # Zero or greater than max allowed value of 2**64
+          return if id.zero? || id > Tracing::Utils::EXTERNAL_MAX_ID
+
+          id < 0 ? id + (2**64) : id
+        end
+
+        # DEV: move `base` to a keyword argument
+        def self.value_to_number(value, base = 10)
+          # It's important to make a difference between no data and zero.
+          return if value.nil?
+
+          # Be sure we have a string
+          value = value.to_s
+
+          # If we are parsing base16 number then truncate to 64-bit
+          value = Helpers.truncate_base16_number(value) if base == 16
+
+          # Convert value to an integer
+          # DEV: Ruby `.to_i` will return `0` if a number could not be parsed
+          num = value.to_i(base)
+
+          # Ensure the parsed number is the same as the original string value
+          # e.g. We want to make sure to throw away `'nan'.to_i == 0`
+          return unless num.to_s(base) == value
+
+          num
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/none.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# typed: false
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Propagator that does not inject nor extract data. It performs no operation.
+      # Supported for feature parity with OpenTelemetry.
+      # @see https://github.com/open-telemetry/opentelemetry-specification/blob/255a6c52b8914a2ed7e26bb5585abecab276aafc/specification/sdk-environment-variables.md?plain=1#L88
+      class None
+        # No-op
+        def inject!(_digest, _data); end
+
+        # No-op
+        def extract(_data); end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/propagation.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+# typed: false
+
+require_relative '../configuration/ext'
+require_relative '../trace_digest'
+require_relative '../trace_operation'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Provides extraction and injection of distributed trace data.
+      class Propagation
+        # DEV: This class should receive the value for
+        # DEV: `Datadog.configuration.tracing.distributed_tracing.propagation_inject_style`
+        # DEV: at initialization time, instead of constantly reading global values.
+        # DEV: This means this class should be reconfigured on `Datadog.configure` calls, thus
+        # DEV: singleton instances should not used as they will become stale.
+        #
+        # @param propagation_styles [Hash<String,Object>]
+        def initialize(propagation_styles:)
+          @propagation_styles = propagation_styles
+        end
+
+        # inject! populates the env with span ID, trace ID and sampling priority
+        #
+        # This method will never raise errors, but instead log them to `Datadog.logger`.
+        #
+        # DEV-2.0: inject! should work without arguments, injecting the active_trace's digest
+        # DEV-2.0: and returning a new Hash with the injected data.
+        # DEV-2.0: inject! should also accept either a `trace` or a `digest`, as a `trace`
+        # DEV-2.0: argument is the common use case, but also allows us to set error tags in the `trace`
+        # DEV-2.0: if needed.
+        # DEV-2.0: Ideally, we'd have a separate stream to report tracer errors and never
+        # DEV-2.0: touch the active span.
+        #
+        # @param digest [TraceDigest]
+        # @param data [Hash]
+        # @return [Boolean] `true` if injected successfully, `false` if no propagation style is configured
+        # @return [nil] in case of error, see `Datadog.logger` output for details.
+        def inject!(digest, data)
+          if digest.nil?
+            ::Datadog.logger.debug('Cannot inject distributed trace data: digest is nil.')
+            return nil
+          end
+
+          digest = digest.to_digest if digest.respond_to?(:to_digest)
+
+          result = false
+
+          # Inject all configured propagation styles
+          ::Datadog.configuration.tracing.distributed_tracing.propagation_inject_style.each do |style|
+            propagator = @propagation_styles[style]
+            begin
+              if propagator
+                propagator.inject!(digest, data)
+                result = true
+              end
+            rescue => e
+              result = nil
+              ::Datadog.logger.error(
+                "Error injecting distributed trace data. Cause: #{e} Location: #{Array(e.backtrace).first}"
+              )
+            end
+          end
+
+          result
+        end
+
+        # extract returns {TraceDigest} containing the distributed trace information.
+        # sampling priority defined in data.
+        #
+        # This method will never raise errors, but instead log them to `Datadog.logger`.
+        #
+        # @param data [Hash]
+        def extract(data)
+          trace_digest = nil
+          dd_trace_digest = nil
+
+          ::Datadog.configuration.tracing.distributed_tracing.propagation_extract_style.each do |style|
+            propagator = @propagation_styles[style]
+            next if propagator.nil?
+
+            begin
+              extracted_trace_digest = propagator.extract(data)
+            rescue => e
+              ::Datadog.logger.error(
+                'Error extracting distributed trace data. ' \
+              "Cause: #{e} Location: #{Array(e.backtrace).first}"
+              )
+            end
+
+            # Skip if no valid data was found
+            next if extracted_trace_digest.nil?
+
+            # Keep track of the Datadog extracted digest, we want to return it if we have it.
+            if extracted_trace_digest && style == Tracing::Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG
+              dd_trace_digest = extracted_trace_digest
+            end
+
+            # No previously extracted trace data, use the one we just extracted
+            if trace_digest.nil?
+              trace_digest = extracted_trace_digest
+            else
+              unless trace_digest.trace_id == extracted_trace_digest.trace_id \
+                    && trace_digest.span_id == extracted_trace_digest.span_id
+                # We have two mismatched propagation contexts
+                ::Datadog.logger.debug do
+                  'Cannot extract distributed trace data: extracted styles differ, ' \
+                  "#{trace_digest.trace_id} != #{extracted_trace_digest.trace_id} && " \
+                  "#{trace_digest.span_id} != #{extracted_trace_digest.span_id}"
+                end
+
+                # It's safer to create a new context than to attach ourselves to the wrong context
+                return TraceDigest.new # Early return from the whole method
+              end
+            end
+          end
+
+          # Return the extracted trace digest if we found one or else a new empty digest.
+          # Always return the Datadog trace digest if one exists since it has more
+          # information than the B3 digest, e.g. origin, priority sampling values.
+          dd_trace_digest || trace_digest || nil
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/trace_context.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+# typed: false
+
+module Datadog
+  module Tracing
+    module Distributed
+      # W3C Trace Context propagator implementation, version 00.
+      # The trace is propagated through two fields: `traceparent` and `tracestate`.
+      # @see https://www.w3.org/TR/trace-context/
+      class TraceContext
+        TRACEPARENT_KEY = 'traceparent'
+        TRACESTATE_KEY = 'tracestate'
+        SPEC_VERSION = '00'
+
+        def initialize(
+          fetcher:,
+          traceparent_key: TRACEPARENT_KEY,
+          tracestate_key: TRACESTATE_KEY
+        )
+          @fetcher = fetcher
+          @traceparent_key = traceparent_key
+          @tracestate_key = tracestate_key
+        end
+
+        def inject!(digest, data)
+          return if digest.nil?
+
+          if (traceparent = build_traceparent(digest))
+            data[@traceparent_key] = traceparent
+
+            if (tracestate = build_tracestate(digest))
+              data[@tracestate_key] = tracestate
+            end
+          end
+
+          data
+        end
+
+        def extract(data)
+          fetcher = @fetcher.new(data)
+
+          trace_id, dd_trace_id, parent_id, sampled, trace_flags = extract_traceparent(fetcher[@traceparent_key])
+
+          return unless trace_id # Could not parse traceparent
+
+          tracestate, sampling_priority, origin, tags, unknown_fields = extract_tracestate(fetcher[@tracestate_key])
+
+          sampling_priority = parse_priority_sampling(sampled, sampling_priority)
+
+          TraceDigest.new(
+            span_id: parent_id,
+            trace_id: dd_trace_id,
+            trace_origin: origin,
+            trace_sampling_priority: sampling_priority,
+            trace_distributed_tags: tags,
+            trace_distributed_id: trace_id,
+            trace_flags: trace_flags,
+            trace_state: tracestate,
+            trace_state_unknown_fields: unknown_fields,
+          )
+        end
+
+        private
+
+        # Refinements to ensure newer rubies do not suffer performance impact
+        # by needing to use older APIs.
+        module Refine
+          # Backport `Regexp::match?` because it is measurably the most performant
+          # way to check if a string matches a regular expression.
+          unless Regexp.method_defined?(:match?)
+            refine ::Regexp do
+              def match?(*args)
+                !match(*args).nil?
+              end
+            end
+          end
+
+          unless String.method_defined?(:delete_prefix)
+            refine ::String do
+              def delete_prefix(prefix)
+                prefix = prefix.to_s
+                if rindex(prefix, 0)
+                  self[prefix.length..-1]
+                else
+                  dup
+                end
+              end
+            end
+          end
+        end
+        using Refine
+
+        # @see https://www.w3.org/TR/trace-context/#traceparent-header
+        def build_traceparent(digest)
+          build_traceparent_string(
+            digest.trace_distributed_id || digest.trace_id,
+            digest.span_id,
+            build_trace_flags(digest)
+          )
+        end
+
+        # For the current version (00), the traceparent has the following format:
+        #
+        # `"#{version}-#{trace_id}-#{parent_id}-#{trace_flags}"`
+        #
+        # Where:
+        #   * `version`: 2 hex-encoded digits, zero padded.
+        #   * `trace_id`: 32 hex-encoded digits, zero padded.
+        #   * `parent_id`: 16 hex-encoded digits, zero padded.
+        #   * `trace_flags`: 2 hex-encoded digits, zero padded.
+        #
+        # All hex values should be lowercase.
+        #
+        # @param trace_id [Integer] 128-bit
+        # @param parent_id [Integer] 64-bit
+        # @param trace_flags [Integer] 8-bit
+        def build_traceparent_string(trace_id, parent_id, trace_flags)
+          "00-#{format('%032x', trace_id)}-#{format('%016x', parent_id)}-#{format('%02x', trace_flags)}"
+        end
+
+        # Sets the trace flag to an existing `trace_flags`.
+        def build_trace_flags(digest)
+          trace_flags = digest.trace_flags || DEFAULT_TRACE_FLAGS
+
+          if digest.trace_sampling_priority
+            if Tracing::Sampling::PrioritySampler.sampled?(digest.trace_sampling_priority)
+              trace_flags |= TRACE_FLAGS_SAMPLED
+            else
+              trace_flags &= ~TRACE_FLAGS_SAMPLED
+            end
+          end
+
+          trace_flags
+        end
+
+        # @see https://www.w3.org/TR/trace-context/#tracestate-header
+        def build_tracestate(digest)
+          tracestate = String.new('dd=')
+          tracestate << "s:#{digest.trace_sampling_priority};" if digest.trace_sampling_priority
+          tracestate << "o:#{serialize_origin(digest.trace_origin)};" if digest.trace_origin
+
+          if digest.trace_distributed_tags
+            digest.trace_distributed_tags.each do |name, value|
+              tag = "t.#{serialize_tag_key(name)}:#{serialize_tag_value(value)};"
+
+              # If tracestate size limit is exceed, drop the remaining data.
+              # String#bytesize is used because only ASCII characters are allowed.
+              #
+              # We add 1 to the limit because of the trailing comma, which will be removed before returning.
+              break if tracestate.bytesize + tag.bytesize > (TRACESTATE_VALUE_SIZE_LIMIT + 1)
+
+              tracestate << tag
+            end
+          end
+
+          tracestate << digest.trace_state_unknown_fields if digest.trace_state_unknown_fields
+
+          # Is there any Datadog-specific information to propagate.
+          # Check for > 3 size because the empty prefix `dd=` has 3 characters.
+          if tracestate.size > 3
+            # Propagate upstream tracestate with `dd=...` appended to the list
+            tracestate.chop! # Removes trailing `;` from Datadog trace state string.
+
+            if digest.trace_state
+              # Delete existing `dd=` tracestate fields, if present.
+              vendors = split_tracestate(digest.trace_state)
+              vendors.reject! { |v| v.start_with?('dd=') }
+            end
+
+            if vendors && !vendors.empty?
+              # Ensure the list has at most 31 elements, as we need to prepend Datadog's
+              # entry and the limit is 32 elements total.
+              vendors = vendors[0..30]
+              "#{tracestate},#{vendors.join(',')}"
+            else
+              tracestate.to_s
+            end
+          else
+            digest.trace_state # Propagate upstream tracestate with no Datadog changes
+          end
+        end
+
+        # If any characters in <origin_value> are invalid, replace each invalid character with 0x5F (underscore).
+        # Invalid characters are: characters outside the ASCII range 0x20 to 0x7E, 0x2C (comma), and 0x3D (equals).
+        def serialize_origin(value)
+          # DEV: It's unlikely that characters will be out of range, as they mostly
+          # DEV: come from Datadog-controlled sources.
+          # DEV: Trying to `match?` is measurably faster than a `gsub` that does not match.
+          if INVALID_ORIGIN_CHARS.match?(value)
+            value.gsub(INVALID_ORIGIN_CHARS, '_')
+          else
+            value
+          end
+        end
+
+        # Serialize `_dd.p.{key}` by first removing the `_dd.p.` prefix.
+        # Then replacing invalid characters with `_`.
+        def serialize_tag_key(name)
+          key = name.delete_prefix(Tracing::Metadata::Ext::Distributed::TAGS_PREFIX)
+
+          # DEV: It's unlikely that characters will be out of range, as they mostly
+          # DEV: come from Datadog-controlled sources.
+          # DEV: Trying to `match?` is measurably faster than a `gsub` that does not match.
+          if INVALID_TAG_KEY_CHARS.match?(key)
+            key.gsub(INVALID_TAG_KEY_CHARS, '_')
+          else
+            key
+          end
+        end
+
+        # Replaces invalid characters with `_`, then replaces `=` with `:`.
+        def serialize_tag_value(value)
+          # DEV: It's unlikely that characters will be out of range, as they mostly
+          # DEV: come from Datadog-controlled sources.
+          # DEV: Trying to `match?` is measurably faster than a `gsub` that does not match.
+          ret = if INVALID_TAG_VALUE_CHARS.match?(value)
+                  value.gsub(INVALID_TAG_VALUE_CHARS, '_')
+                else
+                  value
+                end
+
+          # DEV: Checking for an unlikely '=' is faster than a no-op `tr!`.
+          ret.tr!('=', ':') if ret.include?('=')
+          ret
+        end
+
+        def extract_traceparent(traceparent)
+          trace_id, parent_id, trace_flags = parse_traceparent_string(traceparent)
+
+          # Return unless all traceparent fields are valid.
+          return unless trace_id && !trace_id.zero? && parent_id && !parent_id.zero? && trace_flags
+
+          dd_trace_id = parse_datadog_trace_id(trace_id)
+          sampled = parse_sampled_flag(trace_flags)
+
+          [trace_id, dd_trace_id, parent_id, sampled, trace_flags]
+        end
+
+        def parse_traceparent_string(traceparent)
+          return unless traceparent
+
+          version, trace_id, parent_id, trace_flags, extra = traceparent.strip.split('-')
+
+          return if version == INVALID_VERSION
+
+          # Extra fields are not allowed in version 00, but we have to be lenient for future versions.
+          return if version == SPEC_VERSION && extra
+
+          # Invalid field sizes
+          return if version.size != 2 || trace_id.size != 32 || parent_id.size != 16 || trace_flags.size != 2
+
+          [Integer(trace_id, 16), Integer(parent_id, 16), Integer(trace_flags, 16)]
+        rescue ArgumentError # Conversion to integer failed
+          nil
+        end
+
+        # Datadog only allows 64 bits for the trace id.
+        # We extract the lower 64 bits from the original 128-bit id.
+        def parse_datadog_trace_id(trace_id)
+          trace_id & 0xFFFFFFFFFFFFFFFF
+        end
+
+        def parse_sampled_flag(trace_flags)
+          trace_flags & TRACE_FLAGS_SAMPLED
+        end
+
+        # @return [Array<String,Integer,String,Hash>] returns 4 values: tracestate, sampling_priority, origin, tags.
+        def extract_tracestate(tracestate)
+          return unless tracestate
+
+          vendors = split_tracestate(tracestate)
+
+          # Find Datadog's `dd=` tracestate field.
+          idx = vendors.index { |v| v.start_with?('dd=') }
+          return tracestate unless idx
+
+          # Delete `dd=` prefix
+          dd_tracestate = vendors.delete_at(idx)
+          dd_tracestate.slice!(0..2)
+
+          origin, sampling_priority, tags, unknown_fields = extract_datadog_fields(dd_tracestate)
+
+          [vendors.join(','), sampling_priority, origin, tags, unknown_fields]
+        end
+
+        def extract_datadog_fields(dd_tracestate)
+          sampling_priority = nil
+          origin = nil
+          tags = nil
+          unknown_fields = nil
+
+          # DEV: Since Ruby 2.6 `split` can receive a block, so `each` can be removed then.
+          dd_tracestate.split(';').each do |pair|
+            key, value = pair.split(':', 2)
+            case key
+            when 's'
+              sampling_priority = Integer(value) rescue nil
+            when 'o'
+              origin = value
+            when /^t\./
+              key.slice!(0..1) # Delete `t.` prefix
+
+              value = deserialize_tag_value(value)
+
+              tags ||= {}
+              tags["#{Tracing::Metadata::Ext::Distributed::TAGS_PREFIX}#{key}"] = value
+            else
+              unknown_fields ||= String.new
+              unknown_fields << pair
+              unknown_fields << ';'
+            end
+          end
+
+          [origin, sampling_priority, tags, unknown_fields]
+        end
+
+        # Restore `:` back to `=`.
+        def deserialize_tag_value(value)
+          value.tr!(':', '=')
+          value
+        end
+
+        # If `sampled` and `sampling_priority` disagree, `sampled` overrides the decision.
+        # @return [Integer] one of the {Datadog::Tracing::Sampling::Ext::Priority} values
+        def parse_priority_sampling(sampled, sampling_priority)
+          # If both fields agree
+          if sampling_priority &&
+              (!Tracing::Sampling::PrioritySampler.sampled?(sampling_priority) && sampled == 0 || # Both drop
+                Tracing::Sampling::PrioritySampler.sampled?(sampling_priority) && sampled == 1) # Both keep
+
+            return sampling_priority # Return the richer `sampling_priority`
+          end
+
+          sampled # Sampled flag trumps `sampling_priority` on conflict
+        end
+
+        def split_tracestate(tracestate)
+          tracestate.split(/[ \t]*,[ \t]*/)[0..31]
+        end
+
+        # Version 0xFF is invalid as per spec
+        # @see https://www.w3.org/TR/trace-context/#version
+        INVALID_VERSION = 'ff'
+        private_constant :INVALID_VERSION
+
+        # Empty 8-bit `trace-flags`.
+        # @see https://www.w3.org/TR/trace-context/#trace-flags
+        DEFAULT_TRACE_FLAGS = 0b00000000
+        private_constant :DEFAULT_TRACE_FLAGS
+
+        # Bit-mask for `trace-flags` that represents a sampled span (sampled==true).
+        # @see https://www.w3.org/TR/trace-context/#trace-flags
+        TRACE_FLAGS_SAMPLED = 0b00000001
+        private_constant :TRACE_FLAGS_SAMPLED
+
+        # The limit is inclusive: sizes *greater* than 256 are disallowed.
+        # @see https://www.w3.org/TR/trace-context/#value
+        TRACESTATE_VALUE_SIZE_LIMIT = 256
+        private_constant :TRACESTATE_VALUE_SIZE_LIMIT
+
+        # Replace all characters with `_`, except ASCII characters 0x20-0x7E.
+        # Additionally, `,`, ';', and `=` must also be replaced by `_`.
+        INVALID_ORIGIN_CHARS = /[\u0000-\u0019,;=\u007F-\u{10FFFF}]/.freeze
+        private_constant :INVALID_ORIGIN_CHARS
+
+        # Replace all characters with `_`, except ASCII characters 0x21-0x7E.
+        # Additionally, `,` and `=` must also be replaced by `_`.
+        INVALID_TAG_KEY_CHARS = /[\u0000-\u0020,=\u007F-\u{10FFFF}]/.freeze
+        private_constant :INVALID_TAG_KEY_CHARS
+
+        # Replace all characters with `_`, except ASCII characters 0x20-0x7E.
+        # Additionally, `,`, ':' and `;` must also be replaced by `_`.
+        INVALID_TAG_VALUE_CHARS = /[\u0000-\u001F,:;\u007F-\u{10FFFF}]/.freeze
+        private_constant :INVALID_TAG_VALUE_CHARS
+      end
+    end
+  end
+end

data/lib/datadog/tracing/event.rb

@@ -0,0 +1,78 @@
+# typed: false
+
+require_relative '../core'
+
+module Datadog
+  module Tracing
+    # Event behavior and DSL
+    module Events
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+      end
+
+      # Class methods
+      module ClassMethods
+        def build(**event_handlers)
+          events = new
+          events.subscribe(**event_handlers)
+          events
+        end
+      end
+
+      # Instance methods
+      module InstanceMethods
+        def subscribe(**event_handlers)
+          return unless event_handlers
+
+          event_handlers.each do |event_name, handlers|
+            handlers.each do |handler_name, handler|
+              events.send(event_name).subscribe(handler_name, &handler)
+            end
+          end
+
+          event_handlers
+        end
+      end
+    end
+
+    # A simple pub-sub event model for components to exchange messages through.
+    class Event
+      attr_reader \
+        :name,
+        :subscriptions
+
+      def initialize(name)
+        @name = name
+        @subscriptions = []
+      end
+
+      def subscribe(&block)
+        raise ArgumentError, 'Must give a block to subscribe!' unless block
+
+        subscriptions << block
+      end
+
+      def unsubscribe_all!
+        subscriptions.clear
+
+        true
+      end
+
+      def publish(*args)
+        subscriptions.each do |block|
+          begin
+            block.call(*args)
+          rescue StandardError => e
+            Datadog.logger.debug do
+              "Error while handling '#{name}' event with '#{block}': #{e.class.name} #{e.message} " \
+              "at #{Array(e.backtrace).first}"
+            end
+          end
+        end
+
+        true
+      end
+    end
+  end
+end