ddtrace 0.54.2 → 1.0.0

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

@@ -0,0 +1,55 @@
+# typed: true
+
+require 'datadog/tracing/distributed/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/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 = headers.value_to_id(parts[0], 16) unless parts.empty?
+            span_id = headers.value_to_id(parts[1], 16) if parts.length > 1
+            sampling_priority = headers.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/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/helpers.rb

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

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

@@ -0,0 +1,70 @@
+# typed: false
+
+require 'datadog/tracing/span'
+require 'datadog/tracing/distributed/helpers'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # 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)
+          value_to_id(header(hdr), base)
+        end
+
+        def 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 number(hdr, base = 10)
+          value_to_number(header(hdr), base)
+        end
+
+        def 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/event.rb

@@ -0,0 +1,77 @@
+# typed: false
+
+require 'datadog/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.message} at #{Array(e.backtrace).first}"
+            end
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/datadog/tracing/flush.rb

@@ -0,0 +1,74 @@
+# typed: true
+
+module Datadog
+  module Tracing
+    module Flush
+      # Consumes only completed traces (where all spans have finished)
+      class Finished
+        # Consumes and returns completed traces (where all spans have finished)
+        # from the provided \trace_op, if any.
+        #
+        # Any traces consumed are removed from +trace_op+ as a side effect.
+        #
+        # @return [TraceSegment] trace to be flushed, or +nil+ if the trace is not finished
+        def consume!(trace_op)
+          return unless full_flush?(trace_op)
+
+          get_trace(trace_op)
+        end
+
+        def full_flush?(trace_op)
+          trace_op && trace_op.sampled? && trace_op.finished?
+        end
+
+        protected
+
+        def get_trace(trace_op)
+          trace_op.flush!
+        end
+      end
+
+      # Performs partial trace flushing to avoid large traces residing in memory for too long
+      class Partial
+        # Start flushing partial trace after this many active spans in one trace
+        DEFAULT_MIN_SPANS_FOR_PARTIAL_FLUSH = 500
+
+        attr_reader :min_spans_for_partial
+
+        def initialize(options = {})
+          @min_spans_for_partial = options.fetch(:min_spans_before_partial_flush, DEFAULT_MIN_SPANS_FOR_PARTIAL_FLUSH)
+        end
+
+        # Consumes and returns completed or partially completed
+        # traces from the provided +trace_op+, if any.
+        #
+        # Partially completed traces, where not all spans have finished,
+        # will only be returned if there are at least
+        # +@min_spans_for_partial+ finished spans.
+        #
+        # Any spans consumed are removed from +trace_op+ as a side effect.
+        #
+        # @return [TraceSegment] partial or complete trace to be flushed, or +nil+ if no spans are finished
+        def consume!(trace_op)
+          return unless partial_flush?(trace_op)
+
+          get_trace(trace_op)
+        end
+
+        def partial_flush?(trace_op)
+          return false unless trace_op.sampled?
+          return true if trace_op.finished?
+          return false if trace_op.finished_span_count < @min_spans_for_partial
+
+          true
+        end
+
+        protected
+
+        def get_trace(trace_op)
+          trace_op.flush!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# typed: true
+
+require 'datadog/tracing/analytics'
+require 'datadog/tracing/metadata/ext'
+
+module Datadog
+  module Tracing
+    module Metadata
+      # Defines analytics tagging behavior
+      module Analytics
+        def set_tag(key, value)
+          case key
+          when Ext::Analytics::TAG_ENABLED
+            # If true, set rate to 1.0, otherwise set 0.0.
+            value = value == true ? Ext::Analytics::DEFAULT_SAMPLE_RATE : 0.0
+            Tracing::Analytics.set_sample_rate(self, value)
+          when Ext::Analytics::TAG_SAMPLE_RATE
+            Tracing::Analytics.set_sample_rate(self, value)
+          else
+            super if defined?(super)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# typed: false
+
+require 'datadog/core/error'
+
+require 'datadog/tracing/metadata/ext'
+
+module Datadog
+  module Tracing
+    module Metadata
+      # Adds error tagging behavior
+      # @public_api
+      module Errors
+        # Mark the span with the given error.
+        def set_error(e)
+          e = Core::Error.build_from(e)
+
+          set_tag(Ext::Errors::TAG_TYPE, e.type) unless e.type.empty?
+          set_tag(Ext::Errors::TAG_MSG, e.message) unless e.message.empty?
+          set_tag(Ext::Errors::TAG_STACK, e.backtrace) unless e.backtrace.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module Datadog
+  module Tracing
+    module Metadata
+      # Trace and span tags that represent meta information
+      # regarding the trace. These fields are normally only used
+      # internally, and can have special meaning to downstream
+      # trace processing.
+      # @public_api
+      module Ext
+        # Name of package that was instrumented
+        TAG_COMPONENT = 'component'
+        # Type of operation being performed (e.g. )
+        TAG_OPERATION = 'operation'
+        # Hostname of external service interacted with
+        TAG_PEER_HOSTNAME = 'peer.hostname'
+        # Name of external service that performed the work
+        TAG_PEER_SERVICE = 'peer.service'
+
+        # Defines constants for trace analytics
+        # @public_api
+        module Analytics
+          DEFAULT_SAMPLE_RATE = 1.0
+          TAG_ENABLED = 'analytics.enabled'
+          TAG_MEASURED = '_dd.measured'
+          TAG_SAMPLE_RATE = '_dd1.sr.eausr'
+        end
+
+        module AppTypes
+          TYPE_WEB = 'web'
+          TYPE_DB = 'db'
+          TYPE_CACHE = 'cache'
+          TYPE_WORKER = 'worker'
+          TYPE_CUSTOM = 'custom'
+        end
+
+        # @public_api
+        # Tags related to distributed tracing
+        module Distributed
+          TAG_ORIGIN = '_dd.origin'
+          TAG_SAMPLING_PRIORITY = '_sampling_priority_v1'
+        end
+
+        # @public_api
+        module Errors
+          STATUS = 1
+          TAG_MSG = 'error.msg'
+          TAG_STACK = 'error.stack'
+          TAG_TYPE = 'error.type'
+        end
+
+        # @public_api
+        module HTTP
+          ERROR_RANGE = (500...600).freeze
+          TAG_BASE_URL = 'http.base_url'
+          TAG_METHOD = 'http.method'
+          TAG_STATUS_CODE = 'http.status_code'
+          TAG_URL = 'http.url'
+          TYPE_INBOUND = AppTypes::TYPE_WEB.freeze
+          TYPE_OUTBOUND = 'http'
+          TYPE_PROXY = 'proxy'
+          TYPE_TEMPLATE = 'template'
+
+          # General header functionality
+          module Headers
+            module_function
+
+            INVALID_TAG_CHARACTERS = %r{[^a-z0-9_\-:./]}.freeze
+
+            # Normalizes an HTTP header string into a valid tag string.
+            def to_tag(name)
+              # Tag normalization based on: https://docs.datadoghq.com/getting_started/tagging/#defining-tags.
+              #
+              # Only the following characters are accepted.
+              #  * Alphanumerics
+              #  * Underscores
+              #  * Minuses
+              #  * Colons
+              #  * Periods
+              #  * Slashes
+              #
+              # All other characters are replaced with an underscore.
+              tag = name.to_s.strip
+              tag.downcase!
+              tag.gsub!(INVALID_TAG_CHARACTERS, '_')
+
+              # Additional HTTP header normalization.
+              #
+              # Periods are replaced with an underscore.
+              tag.tr!('.', '_')
+              tag
+            end
+          end
+
+          # Request headers
+          module RequestHeaders
+            PREFIX = 'http.request.headers'
+
+            module_function
+
+            def to_tag(name)
+              "#{PREFIX}.#{Headers.to_tag(name)}"
+            end
+          end
+
+          # Response headers
+          module ResponseHeaders
+            PREFIX = 'http.response.headers'
+
+            module_function
+
+            def to_tag(name)
+              "#{PREFIX}.#{Headers.to_tag(name)}"
+            end
+          end
+        end
+
+        # @public_api
+        module NET
+          TAG_HOSTNAME = '_dd.hostname'
+          TAG_TARGET_HOST = 'out.host'
+          TAG_TARGET_PORT = 'out.port'
+        end
+
+        # @public_api
+        module Sampling
+          TAG_AGENT_RATE = '_dd.agent_psr'
+
+          # If rule sampling is applied to a span, set this metric the sample rate configured for that rule.
+          # This should be done regardless of sampling outcome.
+          TAG_RULE_SAMPLE_RATE = '_dd.rule_psr'
+
+          # If rate limiting is checked on a span, set this metric the effective rate limiting rate applied.
+          # This should be done regardless of rate limiting outcome.
+          TAG_RATE_LIMITER_RATE = '_dd.limit_psr'
+
+          TAG_SAMPLE_RATE = '_sample_rate'
+        end
+
+        # @public_api
+        module SQL
+          TYPE = 'sql'
+          TAG_QUERY = 'sql.query'
+        end
+      end
+    end
+  end
+end