ddtrace 0.34.1 → 1.23.1

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

data/lib/datadog/tracing/remote.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative '../core/remote/dispatcher'
+require_relative 'configuration/dynamic'
+
+module Datadog
+  module Tracing
+    # Remote configuration declaration
+    module Remote
+      class ReadError < StandardError; end
+
+      class << self
+        PRODUCT = 'APM_TRACING'
+
+        def products
+          [PRODUCT]
+        end
+
+        def capabilities
+          [] # No capabilities advertised
+        end
+
+        def process_config(config, content)
+          lib_config = config['lib_config']
+
+          env_vars = Datadog::Tracing::Configuration::Dynamic::OPTIONS.map do |name, env_var, option|
+            value = lib_config[name]
+
+            # Guard for RBS/Steep
+            raise "option is a #{option.class}, expected Option" unless option.is_a?(Configuration::Dynamic::Option)
+
+            option.call(value)
+
+            [env_var, value]
+          end
+
+          content.applied
+
+          Datadog.send(:components).telemetry.client_configuration_change!(env_vars)
+        rescue => e
+          content.errored("#{e.class.name} #{e.message}: #{Array(e.backtrace).join("\n")}")
+        end
+
+        def receivers
+          receiver do |repository, _changes|
+            # DEV: Filter our by product. Given it will be very common
+            # DEV: we can filter this out before we receive the data in this method.
+            # DEV: Apply this refactor to AppSec as well if implemented.
+            repository.contents.map do |content|
+              case content.path.product
+              when PRODUCT
+                config = parse_content(content)
+                process_config(config, content)
+              end
+            end
+          end
+        end
+
+        def receiver(products = [PRODUCT], &block)
+          matcher = Core::Remote::Dispatcher::Matcher::Product.new(products)
+          [Core::Remote::Dispatcher::Receiver.new(matcher, &block)]
+        end
+
+        private
+
+        def parse_content(content)
+          data = content.data.read
+
+          content.data.rewind
+
+          raise ReadError, 'EOF reached' if data.nil?
+
+          JSON.parse(data)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/runtime/metrics.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Runtime
+      # Decorates runtime metrics feature
+      module Metrics
+        def self.associate_trace(trace)
+          return unless trace && !trace.empty?
+
+          # Register service as associated with metrics
+          Datadog.send(:components).runtime_metrics.register_service(trace.service) unless trace.service.nil?
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/sampling/all_sampler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'sampler'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # {Datadog::Tracing::Sampling::AllSampler} samples all the traces.
+      # @public_api
+      class AllSampler < Sampler
+        def sample?(_trace)
+          true
+        end
+
+        def sample!(trace)
+          trace.sampled = true
+        end
+
+        def sample_rate(*_)
+          1.0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Sampling
+      module Ext
+        # Priority is a hint given to the backend so that it knows which traces to reject or kept.
+        # In a distributed context, it should be set before any context propagation (fork, RPC calls) to be effective.
+        # @public_api
+        module Priority
+          # Use this to explicitly inform the backend that a trace MUST be rejected and not stored.
+          # This includes rules and rate limits configured by the user
+          # through the {Datadog::Tracing::Sampling::RuleSampler}.
+          USER_REJECT = -1
+          # Used by the {PrioritySampler} to inform the backend that a trace should be rejected and not stored.
+          AUTO_REJECT = 0
+          # Used by the {PrioritySampler} to inform the backend that a trace should be kept and stored.
+          AUTO_KEEP = 1
+          # Use this to explicitly inform the backend that a trace MUST be kept and stored.
+          # This includes rules and rate limits configured by the user
+          # through the {Datadog::Tracing::Sampling::RuleSampler}.
+          USER_KEEP = 2
+        end
+
+        # List of what mechanism was used to make the trace-level sampling decision.
+        module Mechanism
+          # Single Span Sampled.
+          SPAN_SAMPLING_RATE = 8
+        end
+
+        # List of how the decision was made for the trace-level sampling.
+        #
+        # These values used to populate the {Datadog::Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER} tag.
+        #
+        # The decision has two parts, separated by a `-`:
+        # `part1-sampling_mechanism`. `part1` is currently not populated, thus
+        # this tag is currently formatted as `"-sampling_mechanism"`.
+        module Decision
+          # Used before the tracer receives any rates from agent and there are no rules configured.
+          DEFAULT = '-0'
+          # The sampling rate received in the agent's http response.
+          AGENT_RATE = '-1'
+          # Sampling rule or sampling rate based on tracer config.
+          TRACE_SAMPLING_RULE = '-3'
+          # User directly sets sampling priority via {Tracing.reject!} or {Tracing.keep!},
+          # or by a custom sampler implementation.
+          MANUAL = '-4'
+          # Formerly AppSec.
+          ASM = '-5'
+          # Single Span Sampled.
+          SPAN_SAMPLING_RATE = '-8'
+        end
+      end
+    end
+  end
+end