ddtrace 0.54.2 → 1.0.0

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

@@ -0,0 +1,110 @@
+# 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
+
+        # 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

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

@@ -0,0 +1,88 @@
+# typed: true
+
+require 'datadog/tracing/distributed/headers/ext'
+require 'datadog/tracing/span'
+require 'datadog/tracing/trace_digest'
+require 'datadog/tracing/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
+        include Distributed::Headers::Ext
+
+        def self.inject!(digest, metadata)
+          return if digest.nil?
+
+          digest = digest.to_digest if digest.is_a?(TraceOperation)
+
+          metadata[GRPC_METADATA_TRACE_ID] = digest.trace_id.to_s
+          metadata[GRPC_METADATA_PARENT_ID] = digest.span_id.to_s
+          metadata[GRPC_METADATA_SAMPLING_PRIORITY] = digest.trace_sampling_priority.to_s if digest.trace_sampling_priority
+          metadata[GRPC_METADATA_ORIGIN] = digest.trace_origin.to_s if digest.trace_origin
+        end
+
+        def self.extract(metadata)
+          metadata = Carrier.new(metadata)
+          return nil unless metadata.valid?
+
+          TraceDigest.new(
+            span_id: metadata.parent_id,
+            trace_id: metadata.trace_id,
+            trace_origin: metadata.origin,
+            trace_sampling_priority: metadata.sampling_priority
+          )
+        end
+
+        # opentracing.io compliant carrier object
+        class Carrier
+          include Distributed::Headers::Ext
+
+          def initialize(metadata = {})
+            @metadata = metadata || {}
+          end
+
+          def valid?
+            trace_id && parent_id
+          end
+
+          def trace_id
+            value = metadata_for_key(GRPC_METADATA_TRACE_ID).to_i
+            value if (1..Span::EXTERNAL_MAX_ID).cover? value
+          end
+
+          def parent_id
+            value = metadata_for_key(GRPC_METADATA_PARENT_ID).to_i
+            value if (1..Span::EXTERNAL_MAX_ID).cover? value
+          end
+
+          def sampling_priority
+            value = metadata_for_key(GRPC_METADATA_SAMPLING_PRIORITY)
+            value && value.to_i
+          end
+
+          def origin
+            value = metadata_for_key(GRPC_METADATA_ORIGIN)
+            value if value != ''
+          end
+
+          private
+
+          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/propagation/http.rb

@@ -0,0 +1,109 @@
+# typed: false
+
+require 'datadog/core'
+
+require 'datadog/tracing/configuration/ext'
+require 'datadog/tracing/sampling/ext'
+require 'datadog/tracing/distributed/headers/b3'
+require 'datadog/tracing/distributed/headers/b3_single'
+require 'datadog/tracing/distributed/headers/datadog'
+
+require 'datadog/tracing/trace_digest'
+require 'datadog/tracing/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 'datadog/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 'datadog/tracing/sampling/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