ddtrace 0.54.2 → 1.2.0

data/lib/datadog/tracing/correlation.rb

@@ -0,0 +1,100 @@
+# typed: true
+
+require 'datadog/core'
+
+module Datadog
+  module Tracing
+    # Contains behavior for managing correlations with tracing
+    # e.g. Retrieve a correlation to the current trace for logging, etc.
+    module Correlation
+      # Represents current trace state with key identifiers
+      # @public_api
+      class Identifier
+        LOG_ATTR_ENV = 'dd.env'.freeze
+        LOG_ATTR_SERVICE = 'dd.service'.freeze
+        LOG_ATTR_SPAN_ID = 'dd.span_id'.freeze
+        LOG_ATTR_TRACE_ID = 'dd.trace_id'.freeze
+        LOG_ATTR_VERSION = 'dd.version'.freeze
+
+        attr_reader \
+          :env,
+          :service,
+          :span_id,
+          :span_name,
+          :span_resource,
+          :span_service,
+          :span_type,
+          :trace_id,
+          :trace_name,
+          :trace_resource,
+          :trace_service,
+          :version
+
+        # @!visibility private
+        def initialize(
+          env: nil,
+          service: nil,
+          span_id: nil,
+          span_name: nil,
+          span_resource: nil,
+          span_service: nil,
+          span_type: nil,
+          trace_id: nil,
+          trace_name: nil,
+          trace_resource: nil,
+          trace_service: nil,
+          version: nil
+        )
+          # Dup and freeze strings so they aren't modified by reference.
+          @env = Core::Utils::SafeDup.frozen_or_dup(env || Datadog.configuration.env).freeze
+          @service = Core::Utils::SafeDup.frozen_or_dup(service || Datadog.configuration.service).freeze
+          @span_id = span_id || 0
+          @span_name = Core::Utils::SafeDup.frozen_or_dup(span_name).freeze
+          @span_resource = Core::Utils::SafeDup.frozen_or_dup(span_resource).freeze
+          @span_service = Core::Utils::SafeDup.frozen_or_dup(span_service).freeze
+          @span_type = Core::Utils::SafeDup.frozen_or_dup(span_type).freeze
+          @trace_id = trace_id || 0
+          @trace_name = Core::Utils::SafeDup.frozen_or_dup(trace_name).freeze
+          @trace_resource = Core::Utils::SafeDup.frozen_or_dup(trace_resource).freeze
+          @trace_service = Core::Utils::SafeDup.frozen_or_dup(trace_service).freeze
+          @version = Core::Utils::SafeDup.frozen_or_dup(version || Datadog.configuration.version).freeze
+        end
+
+        def to_log_format
+          @log_format ||= begin
+            attributes = []
+            attributes << "#{LOG_ATTR_ENV}=#{env}" unless env.nil?
+            attributes << "#{LOG_ATTR_SERVICE}=#{service}"
+            attributes << "#{LOG_ATTR_VERSION}=#{version}" unless version.nil?
+            attributes << "#{LOG_ATTR_TRACE_ID}=#{trace_id}"
+            attributes << "#{LOG_ATTR_SPAN_ID}=#{span_id}"
+            attributes.join(' ')
+          end
+        end
+      end
+
+      module_function
+
+      # Produces a CorrelationIdentifier from the TraceDigest provided
+      #
+      # DEV: can we memoize this object, give it can be common to
+      # use a correlation multiple times, specially in the context of logging?
+      # @!visibility private
+      def identifier_from_digest(digest)
+        return Identifier.new unless digest
+
+        Identifier.new(
+          span_id: digest.span_id,
+          span_name: digest.span_name,
+          span_resource: digest.span_resource,
+          span_service: digest.span_service,
+          span_type: digest.span_type,
+          trace_id: digest.trace_id,
+          trace_name: digest.trace_name,
+          trace_resource: digest.trace_resource,
+          trace_service: digest.trace_service
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# typed: true
+
+require 'datadog/tracing/distributed/headers/parser'
+require 'datadog/tracing/distributed/helpers'
+require 'datadog/tracing/distributed/headers/ext'
+require 'datadog/tracing/trace_digest'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Headers
+        # B3 provides helpers to inject or extract headers for B3 style headers
+        module B3
+          include Ext
+
+          def self.inject!(digest, env)
+            return if digest.nil?
+
+            # DEV: We need these to be hex encoded
+            env[B3_HEADER_TRACE_ID] = digest.trace_id.to_s(16)
+            env[B3_HEADER_SPAN_ID] = digest.span_id.to_s(16)
+
+            if digest.trace_sampling_priority
+              sampling_priority = Helpers.clamp_sampling_priority(
+                digest.trace_sampling_priority
+              )
+              env[B3_HEADER_SAMPLED] = sampling_priority.to_s
+            end
+
+            env
+          end
+
+          def self.extract(env)
+            # Extract values from headers
+            # DEV: B3 doesn't have "origin"
+            headers = Parser.new(env)
+            trace_id = headers.id(B3_HEADER_TRACE_ID, 16)
+            span_id = headers.id(B3_HEADER_SPAN_ID, 16)
+            # We don't need to try and convert sampled since B3 supports 0/1 (AUTO_REJECT/AUTO_KEEP)
+            sampling_priority = headers.number(B3_HEADER_SAMPLED)
+
+            # Return early if this propagation is not valid
+            return unless trace_id && span_id
+
+            TraceDigest.new(
+              trace_id: trace_id,
+              span_id: span_id,
+              trace_sampling_priority: sampling_priority
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# typed: true
+
+require 'datadog/tracing/distributed/headers/parser'
+require 'datadog/tracing/distributed/helpers'
+require 'datadog/tracing/distributed/headers/ext'
+require 'datadog/tracing/trace_digest'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Headers
+        # B3Single provides helpers to inject or extract headers for B3 single header style headers
+        module B3Single
+          include Ext
+
+          def self.inject!(digest, env)
+            return if digest.nil?
+
+            # Header format:
+            #   b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
+            # https://github.com/apache/incubator-zipkin-b3-propagation/tree/7c6e9f14d6627832bd80baa87ac7dabee7be23cf#single-header
+            # DEV: `{SamplingState}` and `{ParentSpanId`}` are optional
+
+            # DEV: We need these to be hex encoded
+            header = "#{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
+              )
+              header += "-#{sampling_priority}"
+            end
+
+            env[B3_HEADER_SINGLE] = header
+
+            env
+          end
+
+          def self.extract(env)
+            # Header format:
+            #   b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
+            # https://github.com/apache/incubator-zipkin-b3-propagation/tree/7c6e9f14d6627832bd80baa87ac7dabee7be23cf#single-header
+            # DEV: `{SamplingState}` and `{ParentSpanId`}` are optional
+
+            headers = Parser.new(env)
+            value = headers.header(B3_HEADER_SINGLE)
+            return if value.nil?
+
+            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 early 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
+end

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

@@ -0,0 +1,52 @@
+# typed: true
+
+require 'datadog/tracing/distributed/headers/parser'
+require 'datadog/tracing/distributed/headers/ext'
+require 'datadog/tracing/trace_digest'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Headers
+        # Datadog provides helpers to inject or extract headers for Datadog style headers
+        module Datadog
+          include Ext
+
+          def self.inject!(digest, env)
+            return if digest.nil?
+
+            env[HTTP_HEADER_TRACE_ID] = digest.trace_id.to_s
+            env[HTTP_HEADER_PARENT_ID] = digest.span_id.to_s
+            env[HTTP_HEADER_SAMPLING_PRIORITY] = digest.trace_sampling_priority.to_s if digest.trace_sampling_priority
+            env[HTTP_HEADER_ORIGIN] = digest.trace_origin.to_s unless digest.trace_origin.nil?
+
+            env
+          end
+
+          def self.extract(env)
+            # Extract values from headers
+            headers = Parser.new(env)
+            trace_id = headers.id(HTTP_HEADER_TRACE_ID)
+            parent_id = headers.id(HTTP_HEADER_PARENT_ID)
+            origin = headers.header(HTTP_HEADER_ORIGIN)
+            sampling_priority = headers.number(HTTP_HEADER_SAMPLING_PRIORITY)
+
+            # 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: `Parser#id` will not return 0
+            return unless (trace_id && parent_id) || (origin && trace_id)
+
+            # Return new trace headers
+            TraceDigest.new(
+              span_id: parent_id,
+              trace_id: trace_id,
+              trace_origin: origin,
+              trace_sampling_priority: sampling_priority
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# 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)
+        # @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
+
+          # 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
+
+          # 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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# typed: false
+
+require 'datadog/tracing/distributed/helpers'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Headers
+        # Parser provides easy access and validation methods for Rack headers
+        class Parser
+          def initialize(env)
+            @env = env
+          end
+
+          # TODO: Don't assume Rack format.
+          #       Make distributed tracing headers apathetic.
+          def header(name)
+            rack_header = "http-#{name}".upcase!.tr('-', '_')
+
+            hdr = @env[rack_header]
+
+            # Only return the value if it is not an empty string
+            hdr if hdr != ''
+          end
+
+          def id(hdr, base = 10)
+            Helpers.value_to_id(header(hdr), base)
+          end
+
+          def number(hdr, base = 10)
+            Helpers.value_to_number(header(hdr), base)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# typed: true
+
+require 'datadog/core/configuration'
+require 'datadog/tracing/sampling/ext'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Helpers module provides common helper functions for distributed tracing headers
+      module Helpers
+        # Base provides common methods for distributed header 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
+
+        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 > Span::EXTERNAL_MAX_ID
+
+          id < 0 ? id + (2**64) : id
+        end
+
+        def self.value_to_number(value, base = 10)
+          # It's important to make a difference between no header,
+          # and a header defined to 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 header 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/metadata/b3.rb

@@ -0,0 +1,55 @@
+# typed: true
+
+require 'datadog/tracing/distributed/helpers'
+require 'datadog/tracing/distributed/metadata/parser'
+require 'datadog/tracing/distributed/headers/ext'
+require 'datadog/tracing/trace_digest'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Metadata
+        # B3 provides helpers to inject or extract metadata for B3 style headers
+        module B3
+          include Distributed::Headers::Ext
+
+          def self.inject!(digest, metadata)
+            return if digest.nil?
+
+            # DEV: We need these to be hex encoded
+            metadata[B3_HEADER_TRACE_ID] = digest.trace_id.to_s(16)
+            metadata[B3_HEADER_SPAN_ID] = digest.span_id.to_s(16)
+
+            if digest.trace_sampling_priority
+              sampling_priority = Helpers.clamp_sampling_priority(
+                digest.trace_sampling_priority
+              )
+              metadata[B3_HEADER_SAMPLED] = sampling_priority.to_s
+            end
+
+            metadata
+          end
+
+          def self.extract(metadata)
+            # Extract values from gRPC metadata
+            # DEV: B3 doesn't have "origin"
+            metadata = Parser.new(metadata)
+            trace_id = metadata.id(B3_HEADER_TRACE_ID, 16)
+            span_id = metadata.id(B3_HEADER_SPAN_ID, 16)
+            # We don't need to try and convert sampled since B3 supports 0/1 (AUTO_REJECT/AUTO_KEEP)
+            sampling_priority = metadata.number(B3_HEADER_SAMPLED)
+
+            # Return early if this propagation is not valid
+            return unless trace_id && span_id
+
+            TraceDigest.new(
+              trace_id: trace_id,
+              span_id: span_id,
+              trace_sampling_priority: sampling_priority
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# typed: true
+
+require 'datadog/tracing/distributed/metadata/parser'
+require 'datadog/tracing/distributed/helpers'
+require 'datadog/tracing/distributed/headers/ext'
+require 'datadog/tracing/trace_digest'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Metadata
+        # B3Single provides helpers to inject or extract metadata for B3 single header style headers
+        module B3Single
+          include Distributed::Headers::Ext
+
+          def self.inject!(digest, metadata)
+            return if digest.nil?
+
+            # Header format:
+            #   b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
+            # https://github.com/apache/incubator-zipkin-b3-propagation/tree/7c6e9f14d6627832bd80baa87ac7dabee7be23cf#single-header
+            # DEV: `{SamplingState}` and `{ParentSpanId`}` are optional
+
+            # DEV: We need these to be hex encoded
+            b3_header = "#{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
+              )
+              b3_header += "-#{sampling_priority}"
+            end
+
+            metadata[B3_HEADER_SINGLE] = b3_header
+
+            metadata
+          end
+
+          def self.extract(metadata)
+            # Metadata format:
+            #   b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
+            # https://github.com/apache/incubator-zipkin-b3-propagation/tree/7c6e9f14d6627832bd80baa87ac7dabee7be23cf#single-header
+            # DEV: `{SamplingState}` and `{ParentSpanId`}` are optional
+
+            b3_single = Parser.new(metadata).metadata_for_key(B3_HEADER_SINGLE)
+            return if b3_single.nil?
+
+            parts = b3_single.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 early 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
+end

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

@@ -0,0 +1,73 @@
+require 'datadog/tracing/distributed/headers/ext'
+require 'datadog/tracing/distributed/metadata/parser'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Metadata
+        # Datadog provides helpers to inject or extract metadata for Datadog style headers
+        class Datadog
+          include Distributed::Headers::Ext
+
+          def self.inject!(digest, metadata)
+            return if digest.nil?
+
+            metadata[GRPC_METADATA_TRACE_ID] = digest.trace_id.to_s
+            metadata[GRPC_METADATA_PARENT_ID] = digest.span_id.to_s
+            if digest.trace_sampling_priority
+              metadata[GRPC_METADATA_SAMPLING_PRIORITY] =
+                digest.trace_sampling_priority.to_s
+            end
+            metadata[GRPC_METADATA_ORIGIN] = digest.trace_origin.to_s if digest.trace_origin
+
+            metadata
+          end
+
+          def self.extract(metadata)
+            carrier = Carrier.new(metadata)
+
+            return nil unless carrier.valid?
+
+            TraceDigest.new(
+              span_id: carrier.parent_id,
+              trace_id: carrier.trace_id,
+              trace_origin: carrier.origin,
+              trace_sampling_priority: carrier.sampling_priority
+            )
+          end
+
+          # opentracing.io compliant carrier object
+          class Carrier
+            include Distributed::Headers::Ext
+
+            def initialize(metadata = {})
+              @metadata = Parser.new(metadata || {})
+            end
+
+            def valid?
+              (trace_id && parent_id) || (origin && trace_id)
+            end
+
+            def trace_id
+              @metadata.id(GRPC_METADATA_TRACE_ID)
+            end
+
+            def parent_id
+              @metadata.id(GRPC_METADATA_PARENT_ID)
+            end
+
+            def sampling_priority
+              value = @metadata.metadata_for_key(GRPC_METADATA_SAMPLING_PRIORITY)
+              value && value.to_i
+            end
+
+            def origin
+              value = @metadata.metadata_for_key(GRPC_METADATA_ORIGIN)
+              value if value != ''
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+require 'datadog/tracing/distributed/helpers'
+
+module Datadog
+  module Tracing
+    module Distributed
+      module Metadata
+        # Parser provides easy access and validation methods for metadata headers
+        class Parser
+          def initialize(metadata)
+            @metadata = metadata
+          end
+
+          def id(key, base = 10)
+            Helpers.value_to_id(metadata_for_key(key), base)
+          end
+
+          def number(key, base = 10)
+            Helpers.value_to_number(metadata_for_key(key), base)
+          end
+
+          def metadata_for_key(key)
+            # metadata values can be arrays (multiple headers with the same key)
+            value = @metadata[key]
+            if value.is_a?(Array)
+              value.first
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end