ddtrace 1.1.0 → 1.9.0

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+# typed: false
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Encodes and decodes distributed 'x-datadog-tags' tags for transport
+      # to and from external processes.
+      module DatadogTagsCodec
+        # Backport `Regexp::match?` because it is measurably the most performant
+        # way to check if a string matches a regular expression.
+        module RefineRegexp
+          unless Regexp.method_defined?(:match?)
+            refine ::Regexp do
+              def match?(*args)
+                !match(*args).nil?
+              end
+            end
+          end
+        end
+        using RefineRegexp
+
+        # ASCII characters 32-126, except `,`, `=`, and ` `. At least one character.
+        VALID_KEY_CHARS = /\A(?:(?![,= ])[\u0020-\u007E])+\Z/.freeze
+        # ASCII characters 32-126, except `,`. At least one character.
+        VALID_VALUE_CHARS = /\A(?:(?!,)[\u0020-\u007E])+\Z/.freeze
+
+        # Serializes a {Hash<String,String>} into a `x-datadog-tags`-compatible
+        # String.
+        #
+        # @param tags [Hash<String,String>] trace tag hash
+        # @return [String] serialized tags hash
+        # @raise [EncodingError] if tags cannot be serialized to the `x-datadog-tags` format
+        def self.encode(tags)
+          begin
+            tags.map do |raw_key, raw_value|
+              key = raw_key.to_s
+              value = raw_value.to_s
+
+              raise EncodingError, "Invalid key `#{key}` for value `#{value}`" unless VALID_KEY_CHARS.match?(key)
+              raise EncodingError, "Invalid value `#{value}` for key `#{key}`" unless VALID_VALUE_CHARS.match?(value)
+
+              "#{key}=#{value.strip}"
+            end.join(',')
+          rescue => e
+            raise EncodingError, "Error encoding tags `#{tags}`: `#{e}`"
+          end
+        end
+
+        # Deserializes a `x-datadog-tags`-formatted String into a {Hash<String,String>}.
+        #
+        # @param string [String] tags as serialized by {#encode}
+        # @return [Hash<String,String>] decoded input as a hash of strings
+        # @raise [DecodingError] if string does not conform to the `x-datadog-tags` format
+        def self.decode(string)
+          result = Hash[string.split(',').map do |raw_tag|
+            raw_tag.split('=', 2).tap do |raw_key, raw_value|
+              key = raw_key.to_s
+              value = raw_value.to_s
+
+              raise DecodingError, "Invalid key: #{key}" unless VALID_KEY_CHARS.match?(key)
+              raise DecodingError, "Invalid value: #{value}" unless VALID_VALUE_CHARS.match?(value)
+
+              value.strip!
+            end
+          end]
+
+          raise DecodingError, "Invalid empty tags: #{string}" if result.empty? && !string.empty?
+
+          result
+        end
+
+        # An error occurred during distributed tags encoding.
+        # See {#message} for more information.
+        class EncodingError < StandardError
+        end
+
+        # An error occurred during distributed tags decoding.
+        # See {#message} for more information.
+        class DecodingError < StandardError
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative 'helpers'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Common fetcher that retrieves fields from a Hash data input
+      class Fetcher
+        # @param data [Hash]
+        def initialize(data)
+          @data = data
+        end
+
+        def [](key)
+          @data[key]
+        end
+
+        def id(key, base: 10)
+          Helpers.value_to_id(self[key], base)
+        end
+
+        def number(key, base: 10)
+          Helpers.value_to_number(self[key], base)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/headers/ext.rb

@@ -1,29 +1,33 @@
+# frozen_string_literal: true
 # typed: true
 
 module Datadog
   module Tracing
     module Distributed
       module Headers
-        # HTTP headers one should set for distributed tracing.
-        # These are cross-language (eg: Python, Go and other implementations should honor these)
+        # DEV-2.0: This module only exists for backwards compatibility with the public API. It should be removed.
+        # @deprecated use [Datadog::Tracing::Distributed::Ext]
         # @public_api
         module Ext
-          HTTP_HEADER_TRACE_ID = 'x-datadog-trace-id'.freeze
-          HTTP_HEADER_PARENT_ID = 'x-datadog-parent-id'.freeze
-          HTTP_HEADER_SAMPLING_PRIORITY = 'x-datadog-sampling-priority'.freeze
-          HTTP_HEADER_ORIGIN = 'x-datadog-origin'.freeze
+          HTTP_HEADER_TRACE_ID = 'x-datadog-trace-id'
+          HTTP_HEADER_PARENT_ID = 'x-datadog-parent-id'
+          HTTP_HEADER_SAMPLING_PRIORITY = 'x-datadog-sampling-priority'
+          HTTP_HEADER_ORIGIN = 'x-datadog-origin'
+          # Distributed trace-level tags
+          HTTP_HEADER_TAGS = 'x-datadog-tags'
 
-          # B3 headers used for distributed tracing
-          B3_HEADER_TRACE_ID = 'x-b3-traceid'.freeze
-          B3_HEADER_SPAN_ID = 'x-b3-spanid'.freeze
-          B3_HEADER_SAMPLED = 'x-b3-sampled'.freeze
-          B3_HEADER_SINGLE = 'b3'.freeze
+          # B3 keys used for distributed tracing.
+          # @see https://github.com/openzipkin/b3-propagation
+          B3_HEADER_TRACE_ID = 'x-b3-traceid'
+          B3_HEADER_SPAN_ID = 'x-b3-spanid'
+          B3_HEADER_SAMPLED = 'x-b3-sampled'
+          B3_HEADER_SINGLE = 'b3'
 
           # gRPC metadata keys for distributed tracing. https://github.com/grpc/grpc-go/blob/v1.10.x/Documentation/grpc-metadata.md
-          GRPC_METADATA_TRACE_ID = 'x-datadog-trace-id'.freeze
-          GRPC_METADATA_PARENT_ID = 'x-datadog-parent-id'.freeze
-          GRPC_METADATA_SAMPLING_PRIORITY = 'x-datadog-sampling-priority'.freeze
-          GRPC_METADATA_ORIGIN = 'x-datadog-origin'.freeze
+          GRPC_METADATA_TRACE_ID = 'x-datadog-trace-id'
+          GRPC_METADATA_PARENT_ID = 'x-datadog-parent-id'
+          GRPC_METADATA_SAMPLING_PRIORITY = 'x-datadog-sampling-priority'
+          GRPC_METADATA_ORIGIN = 'x-datadog-origin'
         end
       end
     end

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

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # typed: true
 
-require 'datadog/core/configuration'
-require 'datadog/tracing/sampling/ext'
+require_relative '../sampling/ext'
+require_relative '../utils'
 
 module Datadog
   module Tracing
     module Distributed
-      # Helpers module provides common helper functions for distributed tracing headers
+      # Helpers module provides common helper functions for distributed tracing data
       module Helpers
-        # Base provides common methods for distributed header helper classes
+        # 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
@@ -38,6 +39,41 @@ module Datadog
           #      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

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