ddtrace 0.38.0

data/lib/ddtrace/opentracer/span_context.rb

@@ -0,0 +1,14 @@
+module Datadog
+  module OpenTracer
+    # OpenTracing adapter for SpanContext
+    class SpanContext < ::OpenTracing::SpanContext
+      attr_reader \
+        :datadog_context
+
+      def initialize(datadog_context:, baggage: {})
+        @datadog_context = datadog_context
+        @baggage = baggage.freeze
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/span_context_factory.rb

@@ -0,0 +1,23 @@
+module Datadog
+  module OpenTracer
+    # Creates new Datadog::OpenTracer::SpanContext
+    module SpanContextFactory
+      module_function
+
+      def build(datadog_context:, baggage: {})
+        SpanContext.new(
+          datadog_context: datadog_context,
+          baggage: baggage.dup
+        )
+      end
+
+      def clone(span_context:, baggage: {})
+        SpanContext.new(
+          datadog_context: span_context.datadog_context,
+          # Merge baggage from previous SpanContext
+          baggage: span_context.baggage.merge(baggage)
+        )
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/text_map_propagator.rb

@@ -0,0 +1,75 @@
+require 'ddtrace/ext/distributed'
+
+module Datadog
+  module OpenTracer
+    # OpenTracing propagator for Datadog::OpenTracer::Tracer
+    module TextMapPropagator
+      extend Propagator
+      extend Datadog::Ext::DistributedTracing
+      include Datadog::Ext::DistributedTracing
+
+      BAGGAGE_PREFIX = 'ot-baggage-'.freeze
+
+      class << self
+        # Inject a SpanContext into the given carrier
+        #
+        # @param span_context [SpanContext]
+        # @param carrier [Carrier] A carrier object of Rack type
+        def inject(span_context, carrier)
+          # Inject Datadog trace properties
+          span_context.datadog_context.tap do |datadog_context|
+            carrier[HTTP_HEADER_TRACE_ID] = datadog_context.trace_id
+            carrier[HTTP_HEADER_PARENT_ID] = datadog_context.span_id
+            carrier[HTTP_HEADER_SAMPLING_PRIORITY] = datadog_context.sampling_priority
+            carrier[HTTP_HEADER_ORIGIN] = datadog_context.origin
+          end
+
+          # Inject baggage
+          span_context.baggage.each do |key, value|
+            carrier[BAGGAGE_PREFIX + key] = value
+          end
+
+          nil
+        end
+
+        # Extract a SpanContext in TextMap format from the given carrier.
+        #
+        # @param carrier [Carrier] A carrier object of TextMap type
+        # @return [SpanContext, nil] the extracted SpanContext or nil if none could be found
+        def extract(carrier)
+          # First extract & build a Datadog context
+          headers = DistributedHeaders.new(carrier)
+
+          datadog_context = if headers.valid?
+                              Datadog::Context.new(
+                                trace_id: headers.trace_id,
+                                span_id: headers.parent_id,
+                                sampling_priority: headers.sampling_priority,
+                                origin: headers.origin
+                              )
+                            else
+                              Datadog::Context.new
+                            end
+
+          # Then extract any other baggage
+          baggage = {}
+          carrier.each do |key, value|
+            baggage[item_to_baggage(key)] = value if baggage_item?(key)
+          end
+
+          SpanContextFactory.build(datadog_context: datadog_context, baggage: baggage)
+        end
+
+        private
+
+        def baggage_item?(item)
+          item.to_s.start_with?(BAGGAGE_PREFIX)
+        end
+
+        def item_to_baggage(key)
+          key[BAGGAGE_PREFIX.length, key.length]
+        end
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/thread_local_scope.rb

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

@@ -0,0 +1,47 @@
+module Datadog
+  # Defines some useful patching methods for integrations
+  module Patcher
+    def self.included(base)
+      base.send(:extend, CommonMethods)
+      base.send(:include, CommonMethods)
+    end
+
+    # Defines some common methods for patching, that can be used
+    # at the instance, class, or module level.
+    module CommonMethods
+      def without_warnings
+        # This is typically used when monkey patching functions such as
+        # intialize, which Ruby advices you not to. Use cautiously.
+        v = $VERBOSE
+        $VERBOSE = nil
+        begin
+          yield
+        ensure
+          $VERBOSE = v
+        end
+      end
+
+      def do_once(key = nil, options = {})
+        # If already done, don't do again
+        @done_once ||= Hash.new { |h, k| h[k] = {} }
+        if @done_once.key?(key) && @done_once[key].key?(options[:for])
+          return @done_once[key][options[:for]]
+        end
+
+        # Otherwise 'do'
+        yield.tap do
+          # Then add the key so we don't do again.
+          @done_once[key][options[:for]] = true
+        end
+      end
+
+      def done?(key, options = {})
+        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.
+    extend(CommonMethods)
+  end
+end

data/lib/ddtrace/pin.rb

@@ -0,0 +1,138 @@
+require 'ddtrace/patcher'
+
+# \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
+  # set tracing metadata on a particular traced object.
+  # This is useful if you wanted to, say, trace two different
+  # database clusters.
+  class Pin
+    def self.get_from(obj)
+      return nil unless obj.respond_to? :datadog_pin
+      obj.datadog_pin
+    end
+
+    attr_accessor :app
+    attr_accessor :app_type
+    attr_accessor :config
+    attr_accessor :name
+    attr_accessor :service_name
+    attr_accessor :tags
+    attr_reader :tracer
+    attr_accessor :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]
+      @app_type = options[:app_type]
+      @config = options[:config]
+      @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
+      false
+    end
+
+    # rubocop:disable Style/TrivialAccessors
+    def onto(obj)
+      unless obj.respond_to? :datadog_pin=
+        obj.instance_exec do
+          def datadog_pin=(pin)
+            @datadog_pin = pin
+          end
+        end
+      end
+
+      unless obj.respond_to? :datadog_pin
+        obj.instance_exec do
+          def datadog_pin
+            @datadog_pin
+          end
+        end
+      end
+
+      obj.datadog_pin = self
+    end
+
+    def to_s
+      "Pin(service:#{service},app:#{app},app_type:#{app_type},name:#{name})"
+    end
+
+    private
+
+    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
+      log_deprecation_warning('Datadog::Pin.new')
+    end
+
+    include Datadog::Patcher
+
+    def log_deprecation_warning(method_name)
+      # Only log each deprecation warning once (safeguard against log spam)
+      do_once(method_name) do
+        Datadog.logger.warn("#{method_name}:#{DEPRECATION_WARNING}")
+      end
+    end
+  end
+
+  # Modification to Pin which logs deprecation warnings if accessed.
+  # Will be used by integrations which are phasing out the direct use of #datadog_pin.
+  module DeprecatedPin
+    include Datadog::Patcher
+
+    DEPRECATION_WARNING = %(
+      Use of Datadog::Pin is DEPRECATED.
+      Upgrade to the configuration API using the migration guide here:
+      https://github.com/DataDog/dd-trace-rb/releases/tag/v0.11.0).freeze
+
+    # Raise a deprecation warning when #datadog_pin or #datadog_pin= is accessed.
+    def onto(obj)
+      obj.instance_exec(self) do |pin|
+        @datadog_deprecated_pin = pin
+
+        unless respond_to? :datadog_pin=
+          def datadog_pin=(pin)
+            @datadog_deprecated_pin.log_deprecation_warning('#datadog_pin=')
+            @datadog_pin = pin
+          end
+        end
+
+        unless respond_to? :datadog_pin
+          def datadog_pin
+            @datadog_deprecated_pin.log_deprecation_warning('#datadog_pin')
+            @datadog_pin
+          end
+        end
+
+        # Set instance variable to avoid deprecation warnings
+        @datadog_pin = @datadog_deprecated_pin
+      end
+
+      self
+    end
+
+    def log_deprecation_warning(method_name)
+      # Only log each deprecation warning once (safeguard against log spam)
+      do_once(method_name) do
+        Datadog.logger.warn("#{method_name}:#{DEPRECATION_WARNING}")
+      end
+    end
+  end
+end