ddtrace 0.13.0 → 0.47.0

data/lib/ddtrace/opentracer/thread_local_scope.rb

@@ -0,0 +1,31 @@
+module Datadog
+  module OpenTracer
+    # OpenTracing adapter for thread local scopes
+    class ThreadLocalScope < Scope
+      attr_reader \
+        :finish_on_close
+
+      def initialize(
+        manager:,
+        span:,
+        finish_on_close: true
+      )
+        super(manager: manager, span: span)
+        @finish_on_close = finish_on_close
+        @previous_scope = manager.active
+      end
+
+      # Mark the end of the active period for the current thread and Scope,
+      # updating the ScopeManager#active in the process.
+      #
+      # NOTE: Calling close more than once on a single Scope instance leads to
+      # undefined behavior.
+      def close
+        return unless equal?(manager.active)
+
+        span.finish if finish_on_close
+        manager.send(:set_scope, @previous_scope)
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/thread_local_scope_manager.rb

@@ -0,0 +1,40 @@
+module Datadog
+  module OpenTracer
+    # OpenTracing adapter for thread local scope management
+    class ThreadLocalScopeManager < ScopeManager
+      # Make a span instance active.
+      #
+      # @param span [Span] the Span that should become active
+      # @param finish_on_close [Boolean] whether the Span should automatically be
+      #   finished when Scope#close is called
+      # @return [Scope] instance to control the end of the active period for the
+      #  Span. It is a programming error to neglect to call Scope#close on the
+      #  returned instance.
+      def activate(span, finish_on_close: true)
+        ThreadLocalScope.new(
+          manager: self,
+          span: span,
+          finish_on_close: finish_on_close
+        ).tap do |scope|
+          set_scope(scope)
+        end
+      end
+
+      # @return [Scope] the currently active Scope which can be used to access the
+      # currently active Span.
+      #
+      # If there is a non-null Scope, its wrapped Span becomes an implicit parent
+      # (as Reference#CHILD_OF) of any newly-created Span at Tracer#start_active_span
+      # or Tracer#start_span time.
+      def active
+        Thread.current[object_id.to_s]
+      end
+
+      private
+
+      def set_scope(scope)
+        Thread.current[object_id.to_s] = scope
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/tracer.rb

@@ -0,0 +1,208 @@
+require 'ddtrace/tracer'
+
+module Datadog
+  module OpenTracer
+    # OpenTracing adapter for Datadog::Tracer
+    class Tracer < ::OpenTracing::Tracer
+      extend Forwardable
+
+      attr_reader \
+        :datadog_tracer
+
+      def_delegators \
+        :datadog_tracer,
+        :configure
+
+      def initialize(options = {})
+        super()
+        @datadog_tracer = Datadog::Tracer.new(options)
+      end
+
+      # @return [ScopeManager] the current ScopeManager.
+      def scope_manager
+        @scope_manager ||= ThreadLocalScopeManager.new
+      end
+
+      # Returns a newly started and activated Scope.
+      #
+      # If the Tracer's ScopeManager#active is not nil, no explicit references
+      # are provided, and `ignore_active_scope` is false, then an inferred
+      # References#CHILD_OF reference is created to the ScopeManager#active's
+      # SpanContext when start_active is invoked.
+      #
+      # @param operation_name [String] The operation name for the Span
+      # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
+      #        the newly-started Span. If a Span instance is provided, its
+      #        context is automatically substituted. See [Reference] for more
+      #        information.
+      #
+      #   If specified, the `references` parameter must be omitted.
+      # @param references [Array<Reference>] An array of reference
+      #   objects that identify one or more parent SpanContexts.
+      # @param start_time [Time] When the Span started, if not now
+      # @param tags [Hash] Tags to assign to the Span at start time
+      # @param ignore_active_scope [Boolean] whether to create an implicit
+      #   References#CHILD_OF reference to the ScopeManager#active.
+      # @param finish_on_close [Boolean] whether span should automatically be
+      #   finished when Scope#close is called
+      # @yield [Scope] If an optional block is passed to start_active it will
+      #   yield the newly-started Scope. If `finish_on_close` is true then the
+      #   Span will be finished automatically after the block is executed.
+      # @return [Scope] The newly-started and activated Scope
+      def start_active_span(operation_name,
+                            child_of: nil,
+                            references: nil,
+                            start_time: Time.now,
+                            tags: nil,
+                            ignore_active_scope: false,
+                            finish_on_close: true)
+
+        # When meant to automatically determine the parent,
+        # Use the active scope first, otherwise fall back to any
+        # context generated by Datadog, so as to append to it and gain
+        # the benefit of any out-of-the-box tracing from Datadog preceding
+        # the OpenTracer::Tracer.
+        #
+        # We do this here instead of in #start_span because #start_span generates
+        # spans that are not assigned to a scope, a.k.a not supposed to be used by
+        # subsequent spans implicitly. By using the existing Datadog context, the span
+        # effectively ends up "assigned to a scope", by virtue of being added to the
+        # Context. Hence, it would behave more like an active span, which is why it
+        # should only be here.
+        unless child_of || ignore_active_scope
+          child_of = if scope_manager.active
+                       scope_manager.active.span.context
+                     else
+                       SpanContextFactory.build(datadog_context: datadog_tracer.call_context)
+                     end
+        end
+
+        # Create the span, and auto-add it to the Datadog context.
+        span = start_span(
+          operation_name,
+          child_of: child_of,
+          references: references,
+          start_time: start_time,
+          tags: tags,
+          ignore_active_scope: ignore_active_scope
+        )
+
+        # Overwrite the tracer context with the OpenTracing managed context.
+        # This is mostly for the benefit of any out-of-the-box tracing from Datadog,
+        # such that spans generated by that tracing will be attached to the OpenTracer
+        # parent span.
+        datadog_tracer.provider.context = span.datadog_span.context
+
+        scope_manager.activate(span, finish_on_close: finish_on_close).tap do |scope|
+          if block_given?
+            begin
+              yield(scope)
+            ensure
+              scope.close
+            end
+          end
+        end
+      end
+
+      # Like #start_active_span, but the returned Span has not been registered via the
+      # ScopeManager.
+      #
+      # @param operation_name [String] The operation name for the Span
+      # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
+      #        the newly-started Span. If a Span instance is provided, its
+      #        context is automatically substituted. See [Reference] for more
+      #        information.
+      #
+      #   If specified, the `references` parameter must be omitted.
+      # @param references [Array<Reference>] An array of reference
+      #   objects that identify one or more parent SpanContexts.
+      # @param start_time [Time] When the Span started, if not now
+      # @param tags [Hash] Tags to assign to the Span at start time
+      # @param ignore_active_scope [Boolean] whether to create an implicit
+      #   References#CHILD_OF reference to the ScopeManager#active.
+      # @return [Span] the newly-started Span instance, which has not been
+      #   automatically registered via the ScopeManager
+      def start_span(operation_name,
+                     child_of: nil,
+                     references: nil,
+                     start_time: Time.now,
+                     tags: nil,
+                     ignore_active_scope: false)
+
+        # Derive the OpenTracer::SpanContext to inherit from.
+        parent_span_context = inherited_span_context(child_of, ignore_active_scope: ignore_active_scope)
+
+        # Retrieve Datadog::Context from parent SpanContext.
+        datadog_context = parent_span_context.nil? ? nil : parent_span_context.datadog_context
+
+        # Build the new Datadog span
+        datadog_span = datadog_tracer.start_span(
+          operation_name,
+          child_of: datadog_context,
+          start_time: start_time,
+          tags: tags || {}
+        )
+
+        # Build or extend the OpenTracer::SpanContext
+        span_context = if parent_span_context
+                         SpanContextFactory.clone(span_context: parent_span_context)
+                       else
+                         SpanContextFactory.build(datadog_context: datadog_span.context)
+                       end
+
+        # Wrap the Datadog span and OpenTracer::Span context in a OpenTracer::Span
+        Span.new(datadog_span: datadog_span, span_context: span_context)
+      end
+
+      # Inject a SpanContext into the given carrier
+      #
+      # @param span_context [SpanContext]
+      # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
+      # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
+      def inject(span_context, format, carrier)
+        case format
+        when OpenTracing::FORMAT_TEXT_MAP
+          TextMapPropagator.inject(span_context, carrier)
+        when OpenTracing::FORMAT_BINARY
+          BinaryPropagator.inject(span_context, carrier)
+        when OpenTracing::FORMAT_RACK
+          RackPropagator.inject(span_context, carrier)
+        else
+          warn 'Unknown inject format'
+        end
+      end
+
+      # Extract a SpanContext in the given format from the given carrier.
+      #
+      # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
+      # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
+      # @return [SpanContext, nil] the extracted SpanContext or nil if none could be found
+      def extract(format, carrier)
+        case format
+        when OpenTracing::FORMAT_TEXT_MAP
+          TextMapPropagator.extract(carrier)
+        when OpenTracing::FORMAT_BINARY
+          BinaryPropagator.extract(carrier)
+        when OpenTracing::FORMAT_RACK
+          RackPropagator.extract(carrier)
+        else
+          warn 'Unknown extract format'
+          nil
+        end
+      end
+
+      private
+
+      def inherited_span_context(parent, ignore_active_scope: false)
+        case parent
+        when Span
+          parent.context
+        when SpanContext
+          parent
+        else
+          ignore_active_scope ? nil : scope_manager.active && scope_manager.active.span.context
+        end
+      end
+    end
+  end
+end

data/lib/ddtrace/patcher.rb

@@ -1,7 +1,21 @@
+require 'ddtrace/utils/only_once'
+
 module Datadog
-  # Defines some useful patching methods for integrations
+  # Deprecated: This module should no longer be included. It's only being kept around for backwards compatibility
+  # concerns regarding customer usage.
   module Patcher
+    INCLUDED_WARN_ONLY_ONCE = Datadog::Utils::OnlyOnce.new
+    DO_ONCE_USAGE_WARN_ONLY_ONCE = Datadog::Utils::OnlyOnce.new
+
     def self.included(base)
+      INCLUDED_WARN_ONLY_ONCE.run do
+        Datadog.logger.warn(
+          'Including Datadog::Patcher is deprecated. ' \
+          'For the #do_once behavior, use Datadog::Utils::OnlyOnce instead. ' \
+          'For the #without_warnings behavior, use Datadog::Patcher.without_warnings { ... } as a module function.'
+        )
+      end
+
       base.send(:extend, CommonMethods)
       base.send(:include, CommonMethods)
     end
@@ -21,17 +35,31 @@ module Datadog
         end
       end
 
-      def do_once(key = nil)
+      def do_once(key = nil, options = {})
+        DO_ONCE_USAGE_WARN_ONLY_ONCE.run do
+          Datadog.logger.warn('Datadog::Patcher#do_once is deprecated. Use Datadog::Utils::OnlyOnce instead.')
+        end
+
         # If already done, don't do again
-        @done_once ||= {}
-        return @done_once[key] if @done_once.key?(key)
+        @done_once ||= Hash.new { |h, k| h[k] = {} }
+        return @done_once[key][options[:for]] if @done_once.key?(key) && @done_once[key].key?(options[:for])
 
         # Otherwise 'do'
         yield.tap do
           # Then add the key so we don't do again.
-          @done_once[key] = true
+          @done_once[key][options[:for]] = true
         end
       end
+
+      def done?(key, options = {})
+        DO_ONCE_USAGE_WARN_ONLY_ONCE.run do
+          Datadog.logger.warn('Datadog::Patcher#done? is deprecated. Use Datadog::Utils::OnlyOnce instead.')
+        end
+
+        return false unless instance_variable_defined?(:@done_once)
+
+        !@done_once.nil? && @done_once.key?(key) && @done_once[key].key?(options[:for])
+      end
     end
 
     # Extend the common methods so they're available as a module function.

data/lib/ddtrace/pin.rb

@@ -1,3 +1,6 @@
+require 'ddtrace/patcher'
+require 'ddtrace/utils/only_once'
+
 # \Datadog global namespace that includes all tracing functionality for Tracer and Span classes.
 module Datadog
   # A \Pin (a.k.a Patch INfo) is a small class which is used to
@@ -5,31 +8,38 @@ module Datadog
   # This is useful if you wanted to, say, trace two different
   # database clusters.
   class Pin
+    DEPRECATION_WARN_ONLY_ONCE = Datadog::Utils::OnlyOnce.new
+
     def self.get_from(obj)
       return nil unless obj.respond_to? :datadog_pin
+
       obj.datadog_pin
     end
 
-    attr_accessor :service_name
-    attr_accessor :app
-    attr_accessor :tags
-    attr_accessor :app_type
-    attr_accessor :name
-    attr_accessor :tracer
-    attr_accessor :config
+    attr_accessor :app, :app_type, :config, :name, :service_name, :tags, :writer
+
+    alias service= service_name=
+    alias service service_name
 
     def initialize(service_name, options = {})
+      deprecation_warning unless options[:tracer].is_a?(Proc) || options[:tracer].nil?
+
       @app = options[:app]
-      @tags = options[:tags]
       @app_type = options[:app_type]
-      @name = nil # this would rarely be overriden as it's really span-specific
-      @tracer = options[:tracer] || Datadog.tracer
       @config = options[:config]
-      self.service_name = service_name
+      @name = nil # this would rarely be overriden as it's really span-specific
+      @service_name = service_name
+      @tags = options[:tags]
+      @tracer = options[:tracer]
+    end
+
+    def tracer
+      @tracer.is_a?(Proc) ? @tracer.call : (@tracer || Datadog.tracer)
     end
 
     def enabled?
-      return @tracer.enabled if @tracer
+      return tracer.enabled if tracer
+
       false
     end
 
@@ -54,17 +64,22 @@ module Datadog
       obj.datadog_pin = self
     end
 
-    def service_name=(name)
-      tracer.set_service_info(name, app, app_type) if name && app && app_type
-
-      @service_name = name
+    def to_s
+      "Pin(service:#{service},app:#{app},app_type:#{app_type},name:#{name})"
     end
 
-    alias service= service_name=
-    alias service service_name
+    private
 
-    def to_s
-      "Pin(service:#{service},app:#{app},app_type:#{app_type},name:#{name})"
+    DEPRECATION_WARNING = %(
+      Explicitly providing a tracer instance is DEPRECATED.
+      It's recommended to not provide an explicit tracer instance
+      and let Datadog::Pin resolve the correct tracer internally.
+      ).freeze
+
+    def deprecation_warning
+      DEPRECATION_WARN_ONLY_ONCE.run do
+        Datadog.logger.warn("Datadog::Pin.new:#{DEPRECATION_WARNING}")
+      end
     end
   end
 end

data/lib/ddtrace/pipeline.rb

@@ -34,7 +34,7 @@ module Datadog
 
       result || []
     rescue => e
-      Datadog::Tracer.log.debug(
+      Datadog.logger.debug(
         "trace dropped entirely due to `Pipeline.before_flush` error: #{e}"
       )
 

data/lib/ddtrace/pipeline/span_filter.rb

@@ -10,12 +10,22 @@ module Datadog
         @criteria = filter || block
       end
 
+      # 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.
       def call(trace)
-        black_list = trace.select(&method(:drop_it?))
-
-        clean_trace(black_list, trace) while black_list.any?
-
-        trace
+        deleted = Set.new
+
+        trace.delete_if do |span|
+          if deleted.include?(span.parent)
+            deleted << span
+            true
+          else
+            drop = drop_it?(span)
+            deleted << span if drop
+            drop
+          end
+        end
       end
 
       private
@@ -23,16 +33,6 @@ module Datadog
       def drop_it?(span)
         @criteria.call(span) rescue false
       end
-
-      def clean_trace(black_list, trace)
-        current = black_list.shift
-
-        trace.delete(current)
-
-        trace.each do |span|
-          black_list << span if span.parent == current
-        end
-      end
     end
   end
 end