ddtrace 0.54.2 → 1.4.0

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_relative '../core'
+
+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/grpc.rb

@@ -0,0 +1,98 @@
+# typed: false
+
+require_relative '../distributed/metadata/datadog'
+require_relative '../distributed/metadata/b3'
+require_relative '../distributed/metadata/b3_single'
+
+require_relative '../span'
+require_relative '../trace_digest'
+require_relative '../trace_operation'
+
+module Datadog
+  module Tracing
+    module Propagation
+      # opentracing.io compliant methods for distributing trace headers
+      # between two or more distributed services. Note this is very close
+      # to the Propagation::HTTP; the key difference is the way gRPC handles
+      # header information (called "metadata") as it operates over HTTP2
+      module GRPC
+        PROPAGATION_STYLES = {
+          Configuration::Ext::Distributed::PROPAGATION_STYLE_B3 => Distributed::Metadata::B3,
+          Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER => Distributed::Metadata::B3Single,
+          Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG => Distributed::Metadata::Datadog
+        }.freeze
+
+        def self.inject!(digest, metadata)
+          return if digest.nil?
+
+          digest = digest.to_digest if digest.is_a?(TraceOperation)
+
+          Datadog.configuration.tracing.distributed_tracing.propagation_inject_style.each do |style|
+            propagator = PROPAGATION_STYLES[style]
+            begin
+              propagator.inject!(digest, metadata) unless propagator.nil?
+            rescue => e
+              Datadog.logger.error(
+                'Error injecting propagated trace headers into the environment. ' \
+                "Cause: #{e} Location: #{Array(e.backtrace).first}"
+              )
+            end
+          end
+        end
+
+        def self.extract(metadata)
+          trace_digest = nil
+          dd_trace_digest = nil
+
+          Datadog.configuration.tracing.distributed_tracing.propagation_extract_style.each do |style|
+            propagator = PROPAGATION_STYLES[style]
+
+            next if propagator.nil?
+
+            # Extract trace headers
+            begin
+              extracted_trace_digest = propagator.extract(metadata)
+            rescue => e
+              Datadog.logger.error(
+                'Error extracting propagated trace headers from the environment. ' \
+                "Cause: #{e} Location: #{Array(e.backtrace).first}"
+              )
+            end
+
+            # Skip this style if no valid headers were found
+            next if extracted_trace_digest.nil?
+
+            # Keep track of the Datadog extract trace headers, we want to return
+            #   this one if we have one
+            if extracted_trace_digest && style == Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG
+              dd_trace_digest = extracted_trace_digest
+            end
+
+            # No previously extracted trace headers, use the one we just extracted
+            if trace_digest.nil?
+              trace_digest = extracted_trace_digest
+            else
+              unless trace_digest.trace_id == extracted_trace_digest.trace_id \
+                      && trace_digest.span_id == extracted_trace_digest.span_id
+                # Return an empty/new trace headers if we have a mismatch in values extracted
+                msg = "#{trace_digest.trace_id} != #{extracted_trace_digest.trace_id} && " \
+                      "#{trace_digest.span_id} != #{extracted_trace_digest.span_id}"
+                Datadog.logger.debug(
+                  "Cannot extract trace headers from HTTP: extracted trace headers differ, #{msg}"
+                )
+                # DEV: This will return from `self.extract` not this `each` block
+                return TraceDigest.new
+              end
+            end
+          end
+
+          # Return the extracted trace headers if we found one or else a new empty trace headers
+          # Always return the Datadog trace headers if one exists since it has more
+          #   information than the B3 headers e.g. origin, expanded priority
+          #   sampling values, etc
+          dd_trace_digest || trace_digest || nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# typed: false
+
+require_relative '../../core'
+
+require_relative '../configuration/ext'
+require_relative '../sampling/ext'
+require_relative '../distributed/headers/b3'
+require_relative '../distributed/headers/b3_single'
+require_relative '../distributed/headers/datadog'
+
+require_relative '../trace_digest'
+require_relative '../trace_operation'
+
+module Datadog
+  module Tracing
+    module Propagation
+      # Propagation::HTTP helps extracting and injecting HTTP headers.
+      # @public_api
+      module HTTP
+        PROPAGATION_STYLES = {
+          Configuration::Ext::Distributed::PROPAGATION_STYLE_B3 => Distributed::Headers::B3,
+          Configuration::Ext::Distributed::PROPAGATION_STYLE_B3_SINGLE_HEADER => Distributed::Headers::B3Single,
+          Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG => Distributed::Headers::Datadog
+        }.freeze
+
+        # inject! popolates the env with span ID, trace ID and sampling priority
+        def self.inject!(digest, env)
+          # Prevent propagation from being attempted if trace headers provided are nil.
+          if digest.nil?
+            Datadog.logger.debug(
+              'Cannot inject trace headers into env to propagate over HTTP: trace headers are nil.'.freeze
+            )
+            return
+          end
+
+          digest = digest.to_digest if digest.is_a?(TraceOperation)
+
+          # Inject all configured propagation styles
+          Datadog.configuration.tracing.distributed_tracing.propagation_inject_style.each do |style|
+            propagator = PROPAGATION_STYLES[style]
+            begin
+              propagator.inject!(digest, env) unless propagator.nil?
+            rescue => e
+              Datadog.logger.error(
+                'Error injecting propagated trace headers into the environment. ' \
+                "Cause: #{e} Location: #{Array(e.backtrace).first}"
+              )
+            end
+          end
+        end
+
+        # extract returns trace headers containing the span ID, trace ID and
+        # sampling priority defined in env.
+        def self.extract(env)
+          trace_digest = nil
+          dd_trace_digest = nil
+
+          Datadog.configuration.tracing.distributed_tracing.propagation_extract_style.each do |style|
+            propagator = PROPAGATION_STYLES[style]
+            next if propagator.nil?
+
+            # Extract trace headers
+            # DEV: `propagator.extract` will return `nil`, where `Propagation::HTTP#extract` will not
+            begin
+              extracted_trace_digest = propagator.extract(env)
+            rescue => e
+              Datadog.logger.error(
+                'Error extracting propagated trace headers from the environment. ' \
+                "Cause: #{e} Location: #{Array(e.backtrace).first}"
+              )
+            end
+
+            # Skip this style if no valid headers were found
+            next if extracted_trace_digest.nil?
+
+            # Keep track of the Datadog extract trace headers, we want to return
+            #   this one if we have one
+            if extracted_trace_digest && style == Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG
+              dd_trace_digest = extracted_trace_digest
+            end
+
+            # No previously extracted trace headers, use the one we just extracted
+            if trace_digest.nil?
+              trace_digest = extracted_trace_digest
+            else
+              unless trace_digest.trace_id == extracted_trace_digest.trace_id \
+                      && trace_digest.span_id == extracted_trace_digest.span_id
+                # Return an empty/new trace headers if we have a mismatch in values extracted
+                msg = "#{trace_digest.trace_id} != #{extracted_trace_digest.trace_id} && " \
+                      "#{trace_digest.span_id} != #{extracted_trace_digest.span_id}"
+                Datadog.logger.debug(
+                  "Cannot extract trace headers from HTTP: extracted trace headers differ, #{msg}"
+                )
+                # DEV: This will return from `self.extract` not this `each` block
+                return TraceDigest.new
+              end
+            end
+          end
+
+          # Return the extracted trace headers if we found one or else a new empty trace headers
+          # Always return the Datadog trace headers if one exists since it has more
+          #   information than the B3 headers e.g. origin, expanded priority
+          #   sampling values, etc
+          dd_trace_digest || trace_digest || nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# typed: true
+
+require_relative '../../core'
+
+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 @@
+# typed: 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,27 @@
+# typed: strict
+
+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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# typed: true
+
+module Datadog
+  module Tracing
+    module Sampling
+      # Checks if a trace conforms to a matching criteria.
+      # @abstract
+      # @public_api
+      class Matcher
+        # Returns `true` if the trace should conforms to this rule, `false` otherwise
+        #
+        # @param [TraceOperation] trace
+        # @return [Boolean]
+        def match?(trace)
+          raise NotImplementedError
+        end
+      end
+
+      # A {Datadog::Sampling::Matcher} that supports matching a trace by
+      # trace name and/or service name.
+      # @public_api
+      class SimpleMatcher < Matcher
+        # Returns `true` for case equality (===) with any object
+        MATCH_ALL = Class.new do
+          # DEV: A class that implements `#===` is ~20% faster than
+          # DEV: a `Proc` that always returns `true`.
+          def ===(other)
+            true
+          end
+        end.new
+
+        attr_reader :name, :service
+
+        # @param name [String,Regexp,Proc] Matcher for case equality (===) with the trace name,
+        #             defaults to always match
+        # @param service [String,Regexp,Proc] Matcher for case equality (===) with the service name,
+        #                defaults to always match
+        def initialize(name: MATCH_ALL, service: MATCH_ALL)
+          super()
+          @name = name
+          @service = service
+        end
+
+        def match?(trace)
+          name === trace.name && service === trace.service
+        end
+      end
+
+      # A {Datadog::Tracing::Sampling::Matcher} that allows for arbitrary trace matching
+      # based on the return value of a provided block.
+      # @public_api
+      class ProcMatcher < Matcher
+        attr_reader :block
+
+        # @yield [name, service] Provides trace name and service to the block
+        # @yieldreturn [Boolean] Whether the trace conforms to this matcher
+        def initialize(&block)
+          super()
+          @block = block
+        end
+
+        def match?(trace)
+          block.call(trace.name, trace.service)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# typed: true
+
+require_relative 'ext'
+require_relative 'all_sampler'
+require_relative 'rate_sampler'
+require_relative 'rate_by_service_sampler'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # {Datadog::Tracing::Sampling::PrioritySampler}
+      # @public_api
+      class PrioritySampler
+        # NOTE: We do not advise using a pre-sampler. It can save resources,
+        # but pre-sampling at rates < 100% may result in partial traces, unless
+        # the pre-sampler knows exactly how to drop a span without dropping its ancestors.
+        #
+        # Additionally, as service metrics are calculated in the Datadog Agent,
+        # the service's throughput will be underestimated.
+        attr_reader :pre_sampler, :priority_sampler
+
+        def initialize(opts = {})
+          @pre_sampler = opts[:base_sampler] || AllSampler.new
+          @priority_sampler = opts[:post_sampler] || RateByServiceSampler.new
+        end
+
+        def sample?(trace)
+          @pre_sampler.sample?(trace)
+        end
+
+        def sample!(trace)
+          # If pre-sampling is configured, do it first. (By default, this will sample at 100%.)
+          # NOTE: Pre-sampling at rates < 100% may result in partial traces; not recommended.
+          trace.sampled = pre_sample?(trace) ? @pre_sampler.sample!(trace) : true
+
+          if trace.sampled?
+            # If priority sampling has already been applied upstream, use that value.
+            return true if priority_assigned?(trace)
+
+            # Check with post sampler how we set the priority.
+            sample = priority_sample!(trace)
+
+            # Check if post sampler has already assigned a priority.
+            return true if priority_assigned?(trace)
+
+            # If not, use agent priority values.
+            priority = sample ? Sampling::Ext::Priority::AUTO_KEEP : Sampling::Ext::Priority::AUTO_REJECT
+            assign_priority!(trace, priority)
+          else
+            # If discarded by pre-sampling, set "reject" priority, so other
+            # services for the same trace don't sample needlessly.
+            assign_priority!(trace, Sampling::Ext::Priority::AUTO_REJECT)
+          end
+
+          trace.sampled?
+        end
+
+        # (see Datadog::Tracing::Sampling::RateByServiceSampler#update)
+        def update(rate_by_service)
+          @priority_sampler.update(rate_by_service)
+        end
+
+        private
+
+        def pre_sample?(trace)
+          case @pre_sampler
+          when RateSampler
+            @pre_sampler.sample_rate < 1.0
+          when RateByServiceSampler
+            @pre_sampler.sample_rate(trace) < 1.0
+          else
+            true
+          end
+        end
+
+        def priority_assigned?(trace)
+          !trace.sampling_priority.nil?
+        end
+
+        def priority_sample!(trace)
+          preserving_sampling(trace) do
+            @priority_sampler.sample!(trace)
+          end
+        end
+
+        # Ensures the trace is always propagated to the writer and that
+        # the sample rate metric represents the true client-side sampling.
+        def preserving_sampling(trace)
+          pre_sample_rate_metric = trace.sample_rate
+
+          yield.tap do
+            # NOTE: We'll want to leave `trace.sampled = true` here; all spans for priority sampling must
+            #       be sent to the agent. Otherwise metrics for traces will not be accurate, since the
+            #       agent will have an incomplete dataset.
+            #
+            #       We also ensure that the agent knows we that our `post_sampler` is not performing true sampling,
+            #       to avoid erroneous metric upscaling.
+            trace.sampled = true
+
+            # Restore true sampling metric, as only the @pre_sampler can reject traces.
+            # otherwise if @pre_sampler is not enabled, sending this metric would be misleading.
+            trace.sample_rate = pre_sample_rate_metric || nil
+          end
+        end
+
+        def assign_priority!(trace, priority)
+          trace.sampling_priority = priority
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# typed: true
+
+require_relative 'sampler'
+require_relative 'rate_sampler'
+
+module Datadog
+  module Tracing
+    module Sampling
+      # Samples at different rates by key.
+      # @public_api
+      class RateByKeySampler < Sampler
+        attr_reader \
+          :default_key
+
+        def initialize(default_key, default_rate = 1.0, &block)
+          super()
+
+          raise ArgumentError, 'No resolver given!' unless block
+
+          @default_key = default_key
+          @resolver = block
+          @mutex = Mutex.new
+          @samplers = {}
+
+          set_rate(default_key, default_rate)
+        end
+
+        def resolve(trace)
+          @resolver.call(trace)
+        end
+
+        def default_sampler
+          @samplers[default_key]
+        end
+
+        def sample?(trace)
+          key = resolve(trace)
+
+          @mutex.synchronize do
+            @samplers.fetch(key, default_sampler).sample?(trace)
+          end
+        end
+
+        def sample!(trace)
+          key = resolve(trace)
+
+          @mutex.synchronize do
+            @samplers.fetch(key, default_sampler).sample!(trace)
+          end
+        end
+
+        def sample_rate(trace)
+          key = resolve(trace)
+
+          @mutex.synchronize do
+            @samplers.fetch(key, default_sampler).sample_rate
+          end
+        end
+
+        def update(key, rate)
+          @mutex.synchronize do
+            set_rate(key, rate)
+          end
+        end
+
+        def update_all(rate_by_key)
+          @mutex.synchronize do
+            rate_by_key.each { |key, rate| set_rate(key, rate) }
+          end
+        end
+
+        def delete(key)
+          @mutex.synchronize do
+            @samplers.delete(key)
+          end
+        end
+
+        def delete_if(&block)
+          @mutex.synchronize do
+            @samplers.delete_if(&block)
+          end
+        end
+
+        def length
+          @samplers.length
+        end
+
+        private
+
+        def set_rate(key, rate)
+          @samplers[key] ||= RateSampler.new(rate)
+          @samplers[key].sample_rate = rate
+        end
+      end
+    end
+  end
+end