ddtrace 0.54.2 → 1.4.0

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

@@ -0,0 +1,73 @@
+require_relative '../headers/ext'
+require_relative '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_relative '../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

data/lib/datadog/tracing/event.rb

@@ -0,0 +1,78 @@
+# typed: false
+
+require_relative '../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_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 @@
+# typed: false
+
+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,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_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(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_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 @@
+# typed: 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