ddtrace 0.54.2 → 1.18.0

data/lib/datadog/tracing/flush.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Flush
+      # Consumes and returns a {TraceSegment} to be flushed, from
+      # the provided {TraceSegment}.
+      #
+      # Only finished spans are consumed. Any spans consumed are
+      # removed from +trace_op+ as a side effect. Unfinished spans are
+      # unaffected.
+      #
+      # @abstract
+      class Base
+        # Consumes and returns a {TraceSegment} to be flushed, from
+        # the provided {TraceSegment}.
+        #
+        # Only finished spans are consumed. Any spans consumed are
+        # removed from +trace_op+ as a side effect. Unfinished spans are
+        # unaffected.
+        #
+        # @param [TraceOperation] trace_op
+        # @return [TraceSegment] trace to be flushed, or +nil+ if the trace is not finished
+        def consume!(trace_op)
+          return unless flush?(trace_op)
+
+          get_trace(trace_op)
+        end
+
+        # Should we consume spans from the +trace_op+?
+        # @abstract
+        def flush?(trace_op)
+          raise NotImplementedError
+        end
+
+        protected
+
+        # Consumes all finished spans from trace.
+        # @return [TraceSegment]
+        def get_trace(trace_op)
+          trace_op.flush! do |spans|
+            spans.select! { |span| single_sampled?(span) } unless trace_op.sampled?
+
+            spans
+          end
+        end
+
+        # Single Span Sampling has chosen to keep this span
+        # regardless of the trace-level sampling decision
+        def single_sampled?(span)
+          span.get_metric(Sampling::Span::Ext::TAG_MECHANISM) == Sampling::Ext::Mechanism::SPAN_SAMPLING_RATE
+        end
+      end
+
+      # Consumes and returns completed traces (where all spans have finished),
+      # if any, from the provided +trace_op+.
+      #
+      # Spans consumed are removed from +trace_op+ as a side effect.
+      class Finished < Base
+        # Are all spans finished?
+        def flush?(trace_op)
+          trace_op && trace_op.finished?
+        end
+      end
+
+      # Consumes and returns completed or partially completed
+      # traces from the provided +trace_op+, if any.
+      #
+      # Partial trace flushing avoids large traces residing in memory for too long.
+      #
+      # Partially completed traces, where not all spans have finished,
+      # will only be returned if there are at least
+      # +@min_spans_for_partial+ finished spans.
+      #
+      # Spans consumed are removed from +trace_op+ as a side effect.
+      class Partial < Base
+        # 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 = {})
+          super()
+          @min_spans_for_partial = options.fetch(:min_spans_before_partial_flush, DEFAULT_MIN_SPANS_FOR_PARTIAL_FLUSH)
+        end
+
+        def flush?(trace_op)
+          return true if trace_op.finished?
+          return false if trace_op.finished_span_count < @min_spans_for_partial
+
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../analytics'
+require_relative '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 @@
+# frozen_string_literal: true
+
+require_relative '../../core/error'
+
+require_relative '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,191 @@
+# frozen_string_literal: 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'
+
+        TAG_KIND = 'span.kind'
+
+        # Set this tag to `1.0` if the span is a Service Entry span.
+        TAG_TOP_LEVEL = '_dd.top_level'
+
+        # Set to `1.0` if profiling is enabled together with tracing, and `0.0` otherwise
+        # See Datadog-internal "RFC: Identifying which spans have profiling enabled " for details
+        TAG_PROFILING_ENABLED = '_dd.profiling.enabled'
+
+        # 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
+          # What mechanism was used to make this trace's sampling decision.
+          # @see Datadog::Tracing::Sampling::Ext::Mechanism
+          TAG_DECISION_MAKER = '_dd.p.dm'
+
+          TAG_ORIGIN = '_dd.origin'
+          TAG_SAMPLING_PRIORITY = '_sampling_priority_v1'
+
+          # Trace tags with this prefix will propagate from a trace through distributed tracing.
+          # Distributed headers tags with this prefix will be injected into the active trace.
+          TAGS_PREFIX = '_dd.p.'
+
+          # The distributed tag to carry hex encoded high order 64 bits of 127 bits trace id during
+          # the context restricted with 64 bits. Such as, Datadog propagation and messagepack encoding
+          TID = 'tid'
+          TAG_TID = TAGS_PREFIX + TID
+        end
+
+        # @public_api
+        module Errors
+          STATUS = 1
+          TAG_MSG = 'error.message'
+          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_USER_AGENT = 'http.useragent'
+          TAG_URL = 'http.url'
+          TYPE_INBOUND = AppTypes::TYPE_WEB.freeze
+          TYPE_OUTBOUND = 'http'
+          TYPE_PROXY = 'proxy'
+          TYPE_TEMPLATE = 'template'
+          TAG_CLIENT_IP = 'http.client_ip'
+          HEADER_USER_AGENT = 'User-Agent'
+
+          # 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.
+            #
+            # By default, tags cannot create nested span tag levels:
+            # `allow_nested` allows you to override this behavior.
+            def to_tag(name, allow_nested: false)
+              # 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!('.', '_') unless allow_nested
+              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'
+          TAG_DESTINATION_NAME = 'network.destination.name'
+          TAG_DESTINATION_PORT = 'network.destination.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
+
+        # @public_api
+        module SpanKind
+          TAG_PROXY = 'proxy'
+          TAG_SERVER = 'server'
+          TAG_CLIENT = 'client'
+          TAG_PRODUCER = 'producer'
+          TAG_CONSUMER = 'consumer'
+          TAG_INTERNAL = 'internal'
+        end
+
+        # @public_api
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+require_relative '../../core/environment/ext'
+
+require_relative 'ext'
+
+module Datadog
+  module Tracing
+    module Metadata
+      # Adds metadata & metric tag behavior
+      # @public_api
+      module Tagging
+        # This limit is for numeric tags because uint64 could end up rounded.
+        NUMERIC_TAG_SIZE_RANGE = (-1 << 53..1 << 53).freeze
+
+        # Some associated values should always be sent as Tags, never as Metrics, regardless
+        # if their value is numeric or not.
+        # The Datadog agent will look for these values only as Tags, not Metrics.
+        # @see https://github.com/DataDog/datadog-agent/blob/2ae2cdd315bcda53166dd8fa0dedcfc448087b9d/pkg/trace/stats/aggregation.go#L13-L17
+        ENSURE_AGENT_TAGS = {
+          Ext::Distributed::TAG_ORIGIN => true,
+          Core::Environment::Ext::TAG_VERSION => true,
+          Ext::HTTP::TAG_STATUS_CODE => true,
+          Ext::NET::TAG_HOSTNAME => true
+        }.freeze
+
+        # Return the tag with the given key, nil if it doesn't exist.
+        def get_tag(key)
+          meta[key] || metrics[key]
+        end
+
+        # Set the given key / value tag pair on the span. Keys and values
+        # must be strings. A valid example is:
+        #
+        #   span.set_tag('http.method', request.method)
+        def set_tag(key, value = nil)
+          # Keys must be unique between tags and metrics
+          metrics.delete(key)
+
+          # DEV: This is necessary because the agent looks at `meta[key]`, not `metrics[key]`.
+          value = value.to_s if ENSURE_AGENT_TAGS[key]
+
+          # NOTE: Adding numeric tags as metrics is stop-gap support
+          #       for numeric typed tags. Eventually they will become
+          #       tags again.
+          # Any numeric that is not an integer greater than max size is logged as a metric.
+          # Everything else gets logged as a tag.
+          if value.is_a?(Numeric) && !(value.is_a?(Integer) && !NUMERIC_TAG_SIZE_RANGE.cover?(value))
+            set_metric(key, value)
+          else
+            # Encode strings in UTF-8 to facilitate downstream serialization
+            meta[Core::Utils.utf8_encode(key)] = Core::Utils.utf8_encode(value)
+          end
+        rescue StandardError => e
+          Datadog.logger.debug("Unable to set the tag #{key}, ignoring it. Caused by: #{e}")
+        end
+
+        # Sets tags from given hash, for each key in hash it sets the tag with that key
+        # and associated value from the hash. It is shortcut for `set_tag`. Keys and values
+        # of the hash must be strings. Note that nested hashes are not supported.
+        # A valid example is:
+        #
+        #   span.set_tags({ "http.method" => "GET", "user.id" => "234" })
+        def set_tags(hash)
+          hash.each { |k, v| set_tag(k, v) }
+        end
+
+        # Returns true if the provided `tag` was set to a non-nil value.
+        # False otherwise.
+        #
+        # @param [String] tag the tag or metric to check for presence
+        # @return [Boolean] if the tag is present and not nil
+        def has_tag?(tag) # rubocop:disable Naming/PredicateName
+          !get_tag(tag).nil? # nil is considered not present, thus we can't use `Hash#has_key?`
+        end
+
+        # This method removes a tag for the given key.
+        def clear_tag(key)
+          meta.delete(key)
+        end
+
+        # Convenient interface for setting a single tag.
+        alias []= set_tag
+
+        # Convenient interface for getting a single tag.
+        alias [] get_tag
+
+        # Return the metric with the given key, nil if it doesn't exist.
+        def get_metric(key)
+          metrics[key] || meta[key]
+        end
+
+        # This method sets a tag with a floating point value for the given key. It acts
+        # like `set_tag()` and it simply add a tag without further processing.
+        def set_metric(key, value)
+          # Keys must be unique between tags and metrics
+          meta.delete(key)
+
+          # enforce that the value is a floating point number
+          value = Float(value)
+
+          # Encode strings in UTF-8 to facilitate downstream serialization
+          metrics[Core::Utils.utf8_encode(key)] = value
+        rescue StandardError => e
+          Datadog.logger.debug("Unable to set the metric #{key}, ignoring it. Caused by: #{e}")
+        end
+
+        # This method removes a metric for the given key. It acts like {#clear_tag}.
+        def clear_metric(key)
+          metrics.delete(key)
+        end
+
+        # Returns a copy of all metadata.
+        # Keys for `@meta` and `@metrics` don't collide, by construction.
+        def tags
+          meta.merge(metrics)
+        end
+
+        protected
+
+        def meta
+          @meta ||= {}
+        end
+
+        def metrics
+          @metrics ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/metadata.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'metadata/analytics'
+require_relative 'metadata/tagging'
+require_relative 'metadata/errors'
+
+module Datadog
+  module Tracing
+    # Adds common tagging behavior
+    module Metadata
+      def self.included(base)
+        base.include(Metadata::Tagging)
+        base.include(Metadata::Errors)
+
+        # Additional extensions
+        base.prepend(Metadata::Analytics)
+      end
+    end
+  end
+end

data/lib/datadog/tracing/pipeline/span_filter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative 'span_processor'
+
+module Datadog
+  module Tracing
+    module Pipeline
+      # SpanFilter implements a processor that filters entire span subtrees
+      # This processor executes the configured `operation` for each {Datadog::Tracing::Span}
+      # in a {Datadog::Tracing::TraceSegment}.
+      #
+      # If `operation` returns a truthy value for a span, that span is kept,
+      # otherwise the span is removed from the trace.
+      #
+      # @public_api
+      class SpanFilter < SpanProcessor
+        # NOTE: This SpanFilter implementation only handles traces in which child spans appear
+        # before parent spans in the trace array. If in the future child spans can be after
+        # parent spans, then the code below will need to be updated.
+        # @!visibility private
+        def call(trace)
+          deleted = Set.new
+
+          span_count = trace.spans.length
+          trace.spans.reverse_each.with_index do |span, i|
+            should_delete = deleted.include?(span.parent_id) || drop_it?(span)
+
+            if should_delete
+              deleted << span.id
+              trace.spans.delete_at(span_count - 1 - i)
+            end
+          end
+
+          trace
+        end
+
+        private
+
+        def drop_it?(span)
+          @operation.call(span) rescue false
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/pipeline/span_processor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Pipeline
+      # This processor executes the configured `operation` for each {Datadog::Tracing::Span}
+      # in a {Datadog::Tracing::TraceSegment}.
+      #
+      # @public_api
+      class SpanProcessor
+        # You can either provide an `operation` object or a block to this method.
+        #
+        # Both have the same semantics as `operation`.
+        # `operation` is used if both `operation` and a block are present.
+        #
+        # @param [#call(Datadog::Tracing::Span)] operation a callable that can modify the span.
+        def initialize(operation = nil, &block)
+          callable = operation || block
+
+          raise(ArgumentError) unless callable.respond_to?(:call)
+
+          @operation = operation || block
+        end
+
+        # Invokes `operation#call` for each spans in the `trace` argument.
+        # @param [Datadog::Tracing::TraceSegment] trace a trace segment.
+        # @return [Datadog::Tracing::TraceSegment] the `trace` provided as an argument.
+        # @!visibility private
+        def call(trace)
+          trace.spans.each do |span|
+            @operation.call(span) rescue next
+          end
+
+          trace
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/pipeline.rb

@@ -0,0 +1,61 @@
+require_relative 'pipeline/span_filter'
+require_relative 'pipeline/span_processor'
+
+module Datadog
+  module Tracing
+    # Modifies traces through a set of filters and processors
+    module Pipeline
+      @mutex = Mutex.new
+      @processors = []
+
+      # @see file:docs/GettingStarted.md#configuring-the-transport-layer Configuring the transport layer
+      #
+      # @overload before_flush(*processors)
+      #   @param [Array<Datadog::Tracing::Pipeline::SpanProcessor>] processors a list of processors that can modify
+      #     or filter the trace.
+      #   @param [Array<#call(Datadog::Tracing::TraceSegment)>] processors a list of callable objects that receive a
+      #     {Datadog::Tracing::TraceSegment} and can modify or filter the trace.
+      # @overload before_flush(&processor_block)
+      #   @yield Receive a {Datadog::Tracing::TraceSegment} and can modify or filter the trace.
+      #   @yieldparam [Datadog::Tracing::TraceSegment] trace trace object that can be modified or filtered.
+      #   @yieldreturn [Datadog::Tracing::TraceSegment] the trace object that will be passed to the next processor. Normally
+      #     the same `trace` parameter object should be returned.
+      def self.before_flush(*processors, &processor_block)
+        processors << processor_block if processor_block
+
+        @mutex.synchronize do
+          @processors.concat(processors)
+        end
+      end
+
+      def self.process!(traces)
+        @mutex.synchronize do
+          traces
+            .map { |trace| apply_processors!(trace) }
+            .compact
+        end
+      end
+
+      def self.processors=(value)
+        @processors = value
+      end
+
+      def self.apply_processors!(trace)
+        @processors.inject(trace) do |current_trace, processor|
+          next nil if current_trace.nil? || current_trace.empty?
+
+          process_result = processor.call(current_trace)
+          process_result && process_result.empty? ? nil : process_result
+        end
+      rescue => e
+        Datadog.logger.debug(
+          "trace dropped entirely due to `Pipeline.before_flush` error: #{e}"
+        )
+
+        nil
+      end
+
+      private_class_method :apply_processors!
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+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
+      HTTP = Tracing::Contrib::HTTP::Distributed::Propagation.new
+    end
+  end
+end