ddtrace 0.54.2 → 1.2.0

data/lib/datadog/tracing/event.rb

@@ -0,0 +1,78 @@
+# 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.class.name} #{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,176 @@
+# 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'
+
+        TAG_KIND = 'span.kind'
+
+        # Set this tag to `1.0` if the span is a Service Entry span.
+        TAG_TOP_LEVEL = '_dd.top_level'
+
+        # 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'
+          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 DB
+          TAG_INSTANCE = 'db.instance'
+          TAG_USER = 'db.user'
+          TAG_SYSTEM = 'db.system'
+          TAG_STATEMENT = 'db.statement'
+          TAG_ROW_COUNT = 'db.row_count'
+        end
+
+        # @public_api
+        module SpanKind
+          TAG_SERVER = 'server'
+          TAG_CLIENT = 'client'
+          TAG_PRODUCER = 'producer'
+          TAG_CONSUMER = 'consumer'
+          TAG_INTERNAL = 'internal'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# typed: false
+
+require 'datadog/core/environment/ext'
+
+require 'datadog/tracing/metadata/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(tags)
+          tags.each { |k, v| set_tag(k, v) }
+        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
+
+        protected
+
+        def meta
+          @meta ||= {}
+        end
+
+        def metrics
+          @metrics ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/metadata.rb

@@ -0,0 +1,20 @@
+# typed: true
+
+require 'datadog/tracing/metadata/analytics'
+require 'datadog/tracing/metadata/tagging'
+require 'datadog/tracing/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,42 @@
+# typed: true
+
+require 'set'
+require 'datadog/tracing/pipeline/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
+        # after parent spans in the trace array. If in the future child spans can be before
+        # parent spans, then the code below will need to be updated.
+        # @!visibility private
+        def call(trace)
+          deleted = Set.new
+
+          trace.spans.delete_if do |span|
+            should_delete = deleted.include?(span.parent_id) || drop_it?(span)
+            deleted << span.id if should_delete
+            should_delete
+          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 @@
+# typed: 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,65 @@
+# typed: true
+
+require 'datadog/core'
+
+require 'datadog/tracing/pipeline/span_filter'
+require 'datadog/tracing/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