ddtrace 1.6.0 → 1.7.0

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative 'helpers'
+require_relative '../trace_digest'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # B3 single header-style trace propagation.
+      #
+      # DEV: Format:
+      # DEV:   b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
+      # DEV: https://github.com/apache/incubator-zipkin-b3-propagation/tree/7c6e9f14d6627832bd80baa87ac7dabee7be23cf#single-header
+      # DEV: `{SamplingState}` and `{ParentSpanId}` are optional
+      #
+      # @see https://github.com/openzipkin/b3-propagation#single-header
+      class B3Single
+        B3_SINGLE_HEADER_KEY = 'b3'
+
+        def initialize(fetcher:, key: B3_SINGLE_HEADER_KEY)
+          @key = key
+          @fetcher = fetcher
+        end
+
+        def inject!(digest, env)
+          return if digest.nil?
+
+          # DEV: We need these to be hex encoded
+          value = "#{digest.trace_id.to_s(16)}-#{digest.span_id.to_s(16)}"
+
+          if digest.trace_sampling_priority
+            sampling_priority = Helpers.clamp_sampling_priority(
+              digest.trace_sampling_priority
+            )
+            value += "-#{sampling_priority}"
+          end
+
+          env[@key] = value
+          env
+        end
+
+        def extract(env)
+          fetcher = @fetcher.new(env)
+          value = fetcher[@key]
+
+          return unless value
+
+          parts = value.split('-')
+          trace_id = Helpers.value_to_id(parts[0], 16) unless parts.empty?
+          span_id = Helpers.value_to_id(parts[1], 16) if parts.length > 1
+          sampling_priority = Helpers.value_to_number(parts[2]) if parts.length > 2
+
+          # Return if this propagation is not valid
+          return unless trace_id && span_id
+
+          TraceDigest.new(
+            span_id: span_id,
+            trace_id: trace_id,
+            trace_sampling_priority: sampling_priority
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative '../metadata/ext'
+require_relative '../trace_digest'
+require_relative 'datadog_tags_codec'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Datadog-style trace propagation.
+      class Datadog
+        TRACE_ID_KEY = 'x-datadog-trace-id'
+        PARENT_ID_KEY = 'x-datadog-parent-id'
+        SAMPLING_PRIORITY_KEY = 'x-datadog-sampling-priority'
+        ORIGIN_KEY = 'x-datadog-origin'
+        # Distributed trace-level tags
+        TAGS_KEY = 'x-datadog-tags'
+
+        # Prefix used by all Datadog-specific distributed tags
+        TAGS_PREFIX = 'x-datadog-'
+
+        def initialize(
+          fetcher:,
+          trace_id_key: TRACE_ID_KEY,
+          parent_id_key: PARENT_ID_KEY,
+          sampling_priority_key: SAMPLING_PRIORITY_KEY,
+          origin_key: ORIGIN_KEY,
+          tags_key: TAGS_KEY
+        )
+          @trace_id_key = trace_id_key
+          @parent_id_key = parent_id_key
+          @sampling_priority_key = sampling_priority_key
+          @origin_key = origin_key
+          @tags_key = tags_key
+          @fetcher = fetcher
+        end
+
+        def inject!(digest, data)
+          return if digest.nil?
+
+          data[@trace_id_key] = digest.trace_id.to_s
+          data[@parent_id_key] = digest.span_id.to_s
+          data[@sampling_priority_key] = digest.trace_sampling_priority.to_s if digest.trace_sampling_priority
+          data[@origin_key] = digest.trace_origin.to_s if digest.trace_origin
+
+          inject_tags(digest, data)
+
+          data
+        end
+
+        def extract(data)
+          fetcher = @fetcher.new(data)
+          trace_id = fetcher.id(@trace_id_key)
+          parent_id = fetcher.id(@parent_id_key)
+          sampling_priority = fetcher.number(@sampling_priority_key)
+          origin = fetcher[@origin_key]
+
+          # Return early if this propagation is not valid
+          # DEV: To be valid we need to have a trace id and a parent id
+          #      or when it is a synthetics trace, just the trace id.
+          # DEV: `Fetcher#id` will not return 0
+          return unless (trace_id && parent_id) || (origin && trace_id)
+
+          trace_distributed_tags = extract_tags(fetcher)
+
+          TraceDigest.new(
+            span_id: parent_id,
+            trace_id: trace_id,
+            trace_origin: origin,
+            trace_sampling_priority: sampling_priority,
+            trace_distributed_tags: trace_distributed_tags,
+          )
+        end
+
+        private
+
+        # Export trace distributed tags through the `x-datadog-tags` key.
+        #
+        # DEV: This method accesses global state (the active trace) to record its error state as a trace tag.
+        # DEV: This means errors cannot be reported if there's not active span.
+        # DEV: Ideally, we'd have a dedicated error reporting stream for all of ddtrace.
+        def inject_tags(digest, data)
+          return if digest.trace_distributed_tags.nil? || digest.trace_distributed_tags.empty?
+          return set_tags_propagation_error(reason: 'disabled') if tags_disabled?
+
+          tags = DatadogTagsCodec.encode(digest.trace_distributed_tags)
+
+          return set_tags_propagation_error(reason: 'inject_max_size') if tags_too_large?(tags.size, scenario: 'inject')
+
+          data[@tags_key] = tags
+        rescue => e
+          set_tags_propagation_error(reason: 'encoding_error')
+          ::Datadog.logger.warn(
+            "Failed to inject x-datadog-tags: #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+          )
+        end
+
+        # Import `x-datadog-tags` tags as trace distributed tags.
+        # Only tags that have the `_dd.p.` prefix are processed.
+        #
+        # DEV: This method accesses global state (the active trace) to record its error state as a trace tag.
+        # DEV: This means errors cannot be reported if there's not active span.
+        # DEV: Ideally, we'd have a dedicated error reporting stream for all of ddtrace.
+        def extract_tags(fetcher)
+          tags = fetcher[@tags_key]
+
+          return if !tags || tags.empty?
+          return set_tags_propagation_error(reason: 'disabled') if tags_disabled?
+          return set_tags_propagation_error(reason: 'extract_max_size') if tags_too_large?(tags.size, scenario: 'extract')
+
+          tags_hash = DatadogTagsCodec.decode(tags)
+          # Only extract keys with the expected Datadog prefix
+          tags_hash.select! do |key, _|
+            key.start_with?(Tracing::Metadata::Ext::Distributed::TAGS_PREFIX) && key != EXCLUDED_TAG
+          end
+          tags_hash
+        rescue => e
+          set_tags_propagation_error(reason: 'decoding_error')
+          ::Datadog.logger.warn(
+            "Failed to extract x-datadog-tags: #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+          )
+        end
+
+        def set_tags_propagation_error(reason:)
+          active_trace = Tracing.active_trace
+          active_trace.set_tag('_dd.propagation_error', reason) if active_trace
+          nil
+        end
+
+        def tags_disabled?
+          ::Datadog.configuration.tracing.x_datadog_tags_max_length <= 0
+        end
+
+        def tags_too_large?(size, scenario:)
+          return false if size <= ::Datadog.configuration.tracing.x_datadog_tags_max_length
+
+          ::Datadog.logger.warn(
+            "Failed to #{scenario} x-datadog-tags: tags are too large for configured limit (size:#{size} >= " \
+              "limit:#{::Datadog.configuration.tracing.x_datadog_tags_max_length}). This limit can be configured " \
+              'through the DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH environment variable.'
+          )
+
+          true
+        end
+
+        # We want to exclude tags that we don't want to propagate downstream.
+        EXCLUDED_TAG = '_dd.p.upstream_services'
+        private_constant :EXCLUDED_TAG
+      end
+    end
+  end
+end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: false
 
 module Datadog
   module Tracing

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,31 +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'.freeze
+          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,14 @@
+# frozen_string_literal: true
 # typed: true
 
-require_relative '../../core/configuration'
 require_relative '../sampling/ext'
 
 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
@@ -39,6 +39,7 @@ module Datadog
           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)
 
@@ -51,9 +52,9 @@ module Datadog
           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 header,
-          # and a header defined to zero.
+          # It's important to make a difference between no data and zero.
           return if value.nil?
 
           # Be sure we have a string
@@ -62,7 +63,7 @@ module Datadog
           # If we are parsing base16 number then truncate to 64-bit
           value = Helpers.truncate_base16_number(value) if base == 16
 
-          # Convert header to an integer
+          # Convert value to an integer
           # DEV: Ruby `.to_i` will return `0` if a number could not be parsed
           num = value.to_i(base)
 

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/propagation/http.rb

@@ -1,117 +1,14 @@
 # typed: false
 
-require_relative '../../core'
-
-require_relative '../configuration/ext'
-require_relative '../sampling/ext'
-require_relative '../distributed/headers/b3'
-require_relative '../distributed/headers/b3_single'
-require_relative '../distributed/headers/datadog'
-
-require_relative '../trace_digest'
-require_relative '../trace_operation'
+require_relative '../contrib/http/distributed/propagation'
 
 module Datadog
   module Tracing
     module Propagation
       # Propagation::HTTP helps extracting and injecting HTTP headers.
+      # DEV-2.0: This file has been moved to Contrib. Should be deleted in the next release.
       # @public_api
-      module HTTP
-        PROPAGATION_STYLES = {
-          Configuration::Ext::Distributed::PROPAGATION_STYLE_B3 => Distributed::Headers::B3,
-          Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER => Distributed::Headers::B3Single,
-          Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG => Distributed::Headers::Datadog
-        }.freeze
-
-        # inject! populates the env with span ID, trace ID and sampling priority
-        #
-        # 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 headers.
-        # 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.
-        def self.inject!(digest, env)
-          # Prevent propagation from being attempted if trace headers provided are nil.
-          if digest.nil?
-            Datadog.logger.debug(
-              'Cannot inject trace headers into env to propagate over HTTP: trace headers are nil.'.freeze
-            )
-            return
-          end
-
-          digest = digest.to_digest if digest.is_a?(TraceOperation)
-
-          # Inject all configured propagation styles
-          Datadog.configuration.tracing.distributed_tracing.propagation_inject_style.each do |style|
-            propagator = PROPAGATION_STYLES[style]
-            begin
-              propagator.inject!(digest, env) unless propagator.nil?
-            rescue => e
-              Datadog.logger.error(
-                'Error injecting propagated trace headers into the environment. ' \
-                "Cause: #{e} Location: #{Array(e.backtrace).first}"
-              )
-            end
-          end
-        end
-
-        # extract returns trace headers containing the span ID, trace ID and
-        # sampling priority defined in env.
-        def self.extract(env)
-          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?
-
-            # Extract trace headers
-            # DEV: `propagator.extract` will return `nil`, where `Propagation::HTTP#extract` will not
-            begin
-              extracted_trace_digest = propagator.extract(env)
-            rescue => e
-              Datadog.logger.error(
-                'Error extracting propagated trace headers from the environment. ' \
-                "Cause: #{e} Location: #{Array(e.backtrace).first}"
-              )
-            end
-
-            # Skip this style if no valid headers were found
-            next if extracted_trace_digest.nil?
-
-            # Keep track of the Datadog extract trace headers, we want to return
-            #   this one if we have one
-            if extracted_trace_digest && style == Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG
-              dd_trace_digest = extracted_trace_digest
-            end
-
-            # No previously extracted trace headers, 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
-                # Return an empty/new trace headers if we have a mismatch in values extracted
-                msg = "#{trace_digest.trace_id} != #{extracted_trace_digest.trace_id} && " \
-                      "#{trace_digest.span_id} != #{extracted_trace_digest.span_id}"
-                Datadog.logger.debug(
-                  "Cannot extract trace headers from HTTP: extracted trace headers differ, #{msg}"
-                )
-                # DEV: This will return from `self.extract` not this `each` block
-                return TraceDigest.new
-              end
-            end
-          end
-
-          # Return the extracted trace headers if we found one or else a new empty trace headers
-          # Always return the Datadog trace headers if one exists since it has more
-          #   information than the B3 headers e.g. origin, expanded priority
-          #   sampling values, etc
-          dd_trace_digest || trace_digest || nil
-        end
-      end
+      HTTP = Tracing::Contrib::HTTP::Distributed::Propagation.new
     end
   end
 end

data/lib/datadog/tracing/trace_segment.rb

@@ -173,7 +173,7 @@ module Datadog
       end
 
       def process_id_tag
-        meta[Core::Runtime::Ext::TAG_PID]
+        meta[Core::Runtime::Ext::TAG_PROCESS_ID]
       end
 
       def rate_limiter_rate_tag

data/lib/ddtrace/transport/trace_formatter.rb

@@ -94,7 +94,7 @@ module Datadog
       end
 
       def tag_lang!
-        return if trace.lang.nil? || root_span.get_tag(Tracing::Metadata::Ext::TAG_PEER_SERVICE)
+        return if trace.lang.nil?
 
         root_span.set_tag(
           Core::Runtime::Ext::TAG_LANG,
@@ -114,10 +114,7 @@ module Datadog
       def tag_process_id!
         return unless trace.process_id
 
-        root_span.set_tag(
-          Core::Runtime::Ext::TAG_PID,
-          trace.process_id
-        )
+        root_span.set_tag(Core::Runtime::Ext::TAG_PROCESS_ID, trace.process_id)
       end
 
       def tag_rate_limiter_rate!

data/lib/ddtrace/version.rb

@@ -3,7 +3,7 @@
 module DDTrace
   module VERSION
     MAJOR = 1
-    MINOR = 6
+    MINOR = 7
     PATCH = 0
     PRE = nil