ddtrace 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83a0125cb996a905f1d25812abb1f64d4703b4ba870b378dbb746675322ea7f4
-  data.tar.gz: 98dbbbffe51a7912106269183b12f41fea114f1b7fa7dc42e3266ad910ba57ff
+  metadata.gz: e4c07e2d55c825aa80fda2d80abd0be7bce884c47a869d54fc5ca32f4e60653e
+  data.tar.gz: a58bd25922fa32c3c921395a9a00b37e5b0941399f3a48cf15735ef11935808f
 SHA512:
-  metadata.gz: 4f750d5f3418be21196ee9109f1faa9eb904baf7bd5d4f8eb07b00e6bce5f1b7dc393e080a4be53e350bbfbeedf3216823b4b58df7720fa64688fb9c1ab10f64
-  data.tar.gz: 4c056618940a40462006828d0ede6613a51e78c062555544605480f540a471747a9fb76c9ee496dc3b9b82f7595a77df4a933d14eed3db18457a61c9c76ff880
+  metadata.gz: cd1c737a23055b67ccd2a0c081bfd64cd6156d744ca9c6b982623406b04be282de3c7b0328757dafef0bd9916f822c8a59a742be37f04f3225e192574fd7f0b9
+  data.tar.gz: 9418e24136ab3721c4404cce92dbf637d86139b5d574356e6918a5cf618de2a881add70f1420ca419afe6a751b1fd9a58871e780d22294187a5327787e5ebba4

data/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 ## [Unreleased (beta)]
 
+## [0.16.0] - 2018-09-18
+
+Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.16.0
+
+Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.15.0...v0.16.0
+
+### Added
+
+- OpenTracing support (#517)
+- `middleware` option for disabling Rails trace middleware. (#552)
+
 ## [0.15.0] - 2018-09-12
 
 Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.15.0
@@ -500,8 +511,9 @@ Release notes: https://github.com/DataDog/dd-trace-rb/releases/tag/v0.3.1
 
 Git diff: https://github.com/DataDog/dd-trace-rb/compare/v0.3.0...v0.3.1
 
-[Unreleased (stable)]: https://github.com/DataDog/dd-trace-rb/compare/v0.15.0...master
-[Unreleased (beta)]: https://github.com/DataDog/dd-trace-rb/compare/v0.15.0...0.16-dev
+[Unreleased (stable)]: https://github.com/DataDog/dd-trace-rb/compare/v0.16.0...master
+[Unreleased (beta)]: https://github.com/DataDog/dd-trace-rb/compare/v0.16.0...0.17-dev
+[0.15.0]: https://github.com/DataDog/dd-trace-rb/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/DataDog/dd-trace-rb/compare/v0.14.2...v0.15.0
 [0.14.2]: https://github.com/DataDog/dd-trace-rb/compare/v0.14.1...v0.14.2
 [0.14.1]: https://github.com/DataDog/dd-trace-rb/compare/v0.14.0...v0.14.1

data/Rakefile

@@ -15,7 +15,11 @@ namespace :spec do
 
   RSpec::Core::RakeTask.new(:main) do |t|
     t.pattern = 'spec/**/*_spec.rb'
-    t.exclude_pattern = 'spec/**/{contrib,benchmark,redis}/**/*_spec.rb'
+    t.exclude_pattern = 'spec/**/{contrib,benchmark,redis,opentracer}/**/*_spec.rb'
+  end
+
+  RSpec::Core::RakeTask.new(:opentracer) do |t|
+    t.pattern = 'spec/ddtrace/opentracer/**/*_spec.rb'
   end
 
   RSpec::Core::RakeTask.new(:rails) do |t|
@@ -311,6 +315,7 @@ task :ci do
     sh 'bundle exec rake test:main'
     sh 'bundle exec rake spec:main'
     sh 'bundle exec rake spec:contrib'
+    sh 'bundle exec rake spec:opentracer'
 
     if RUBY_PLATFORM != 'java'
       # Contrib minitests
@@ -366,6 +371,7 @@ task :ci do
     sh 'bundle exec rake test:main'
     sh 'bundle exec rake spec:main'
     sh 'bundle exec rake spec:contrib'
+    sh 'bundle exec rake spec:opentracer'
 
     if RUBY_PLATFORM != 'java'
       # Contrib minitests
@@ -432,6 +438,7 @@ task :ci do
     sh 'bundle exec rake test:main'
     sh 'bundle exec rake spec:main'
     sh 'bundle exec rake spec:contrib'
+    sh 'bundle exec rake spec:opentracer'
 
     if RUBY_PLATFORM != 'java'
       # Contrib minitests
@@ -497,6 +504,7 @@ task :ci do
     sh 'bundle exec rake test:main'
     sh 'bundle exec rake spec:main'
     sh 'bundle exec rake spec:contrib'
+    sh 'bundle exec rake spec:opentracer'
 
     if RUBY_PLATFORM != 'java'
       # Contrib minitests

data/ddtrace.gemspec

@@ -33,6 +33,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'msgpack'
+  # TODO: Move this to Appraisals?
+  spec.add_dependency 'opentracing', '>= 0.4.1'
 
   spec.add_development_dependency 'rake', '>= 10.5'
   spec.add_development_dependency 'rubocop', '= 0.49.1' if RUBY_VERSION >= '2.1.0'

data/docs/GettingStarted.md

@@ -21,6 +21,7 @@ For descriptions of terminology used in APM, take a look at the [official docume
  - [Installation](#installation)
      - [Quickstart for Rails applications](#quickstart-for-rails-applications)
      - [Quickstart for Ruby applications](#quickstart-for-ruby-applications)
+     - [Quickstart for OpenTracing](#quickstart-for-opentracing)
  - [Manual instrumentation](#manual-instrumentation)
  - [Integration instrumentation](#integration-instrumentation)
      - [Active Record](#active-record)
@@ -59,6 +60,7 @@ For descriptions of terminology used in APM, take a look at the [official docume
      - [Processing pipeline](#processing-pipeline)
          - [Filtering](#filtering)
          - [Processing](#processing)
+     - [OpenTracing](#opentracing)
 
 ## Compatibility
 
@@ -75,10 +77,6 @@ For descriptions of terminology used in APM, take a look at the [official docume
 |       |                            | 2.4     | Full         |
 | JRuby | http://jruby.org/          | 9.1.5   | Experimental |
 
-*Full* support indicates all tracer features are available.
-
-*Experimental* indicates most features should be available, but unverified.
-
 **Supported web servers**:
 
 | Type      | Documentation                     | Version      | Support type |
@@ -87,6 +85,16 @@ For descriptions of terminology used in APM, take a look at the [official docume
 | Unicorn   | https://bogomips.org/unicorn/     | 4.8+ / 5.1+  | Full         |
 | Passenger | https://www.phusionpassenger.com/ | 5.0+         | Full         |
 
+**Supported tracing frameworks**:
+
+| Type        | Documentation                                   | Version               | Support type |
+| ----------- | ----------------------------------------------- | --------------------- | ------------ |
+| OpenTracing | https://github.com/opentracing/opentracing-ruby | 0.4.1+ (w/ Ruby 2.1+) | Experimental |
+
+*Full* support indicates all tracer features are available.
+
+*Experimental* indicates most features should be available, but unverified.
+
 ## Installation
 
 The following steps will help you quickly start tracing your Ruby application.
@@ -136,6 +144,36 @@ The Ruby APM tracer sends trace data through the Datadog Agent.
     1. Activate integration instrumentation (see [Integration instrumentation](#integration-instrumentation))
     2. Add manual instrumentation around your code (see [Manual instrumentation](#manual-instrumentation))
 
+### Quickstart for OpenTracing
+
+1. Install the gem with `gem install ddtrace`
+2. To your OpenTracing configuration file, add the following:
+
+    ```ruby
+    require 'opentracing'
+    require 'ddtrace'
+    require 'ddtrace/opentracer'
+
+    # Activate the Datadog tracer for OpenTracing
+    OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new
+    ```
+
+3. (Optional) Add a configuration block to your Ruby application to configure Datadog with:
+
+    ```ruby
+    Datadog.configure do |c|
+      # Configure the Datadog tracer here.
+      # Activate integrations, change tracer settings, etc...
+      # By default without additional configuration,
+      # no additional integrations will be traced, only
+      # what you have instrumented with OpenTracing.
+    end
+    ```
+
+4. (Optional) Add or activate additional instrumentation by doing either of the following:
+    1. Activate Datadog integration instrumentation (see [Integration instrumentation](#integration-instrumentation))
+    2. Add Datadog manual instrumentation around your code (see [Manual instrumentation](#manual-instrumentation))
+
 ### Final steps for installation
 
 After setting up, your services will appear on the [APM services page](https://app.datadoghq.com/apm/services) within a few minutes. Learn more about [using the APM UI][visualization docs].
@@ -869,6 +907,7 @@ Where `options` is an optional `Hash` that accepts the following parameters:
 | ``database_service`` | Database service name used when tracing database activity | ``<app_name>-<adapter_name>`` |
 | ``exception_controller`` | Class or Module which identifies a custom exception controller class. Tracer provides improved error behavior when it can identify custom exception controllers. By default, without this option, it 'guesses' what a custom exception controller looks like. Providing this option aids this identification. | ``nil`` |
 | ``distributed_tracing`` | Enables [distributed tracing](#distributed-tracing) so that this service trace is connected with a trace of another service if tracing headers are received | `false` |
+| ``middleware`` | Add the trace middleware to the Rails application. Set to `false` if you don't want the middleware to load. | `true` |
 | ``middleware_names`` | Enables any short-circuited middleware requests to display the middleware name as resource for the trace. | `false` |
 | ``template_base_path`` | Used when the template name is parsed. If you don't store your templates in the ``views/`` folder, you may need to change this value | ``views/`` |
 | ``tracer`` | A ``Datadog::Tracer`` instance used to instrument the application. Usually you don't need to set that. | ``Datadog.tracer`` |
@@ -1510,3 +1549,32 @@ Datadog::Pipeline.before_flush(
   Datadog::Pipeline::SpanProcessor.new { |span| span.resource.gsub!(/password=.*/, '') }
 )
 ```
+
+### OpenTracing
+
+For setting up Datadog with OpenTracing, see out [Quickstart for OpenTracing](#quickstart-for-opentracing) section for details.
+
+**Configuring Datadog tracer settings**
+
+The underlying Datadog tracer can be configured by passing options (which match `Datadog::Tracer`) when configuring the global tracer:
+
+```ruby
+# Where `options` is a Hash of options provided to Datadog::Tracer
+OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new(options)
+```
+
+It can also be configured by using `Datadog.configure` described in the [Tracer settings](#tracer-settings) section.
+
+**Activating and configuring integrations**
+
+By default, configuring OpenTracing with Datadog will not automatically activate any additional instrumentation provided by Datadog. You will only receive spans and traces from OpenTracing instrumentation you have in your application.
+
+However, additional instrumentation provided by Datadog can be activated alongside OpenTracing using `Datadog.configure`, which can be used to further enhance your tracing. To activate this, see [Integration instrumentation](#integration-instrumentation) for more details.
+
+**Supported serialization formats**
+
+| Type                           | Supported? | Additional information |
+| ------------------------------ | ---------- | ---------------------- |
+| `OpenTracing::FORMAT_TEXT_MAP` | Yes        |                        |
+| `OpenTracing::FORMAT_RACK`     | Yes        | Because of the loss of resolution in the Rack format, please note that baggage items with names containing either upper case characters or `-` will be converted to lower case and `_` in a round-trip respectively. We recommend avoiding these characters, or accommodating accordingly on the receiving end. |
+| `OpenTracing::FORMAT_BINARY`   | No         |                        |

data/lib/ddtrace/contrib/rack/patcher.rb

@@ -39,7 +39,8 @@ module Datadog
             @patched = true
           end
 
-          if !@middleware_patched && get_option(:middleware_names)
+          if (!instance_variable_defined?(:@middleware_patched) || !@middleware_patched) \
+             && get_option(:middleware_names)
             if get_option(:application)
               enable_middleware_names
               @middleware_patched = true

data/lib/ddtrace/contrib/rails/patcher.rb

@@ -1,4 +1,7 @@
 require 'ddtrace/contrib/rails/utils'
+require 'ddtrace/contrib/rails/framework'
+require 'ddtrace/contrib/rails/middlewares'
+require 'ddtrace/contrib/rack/middlewares'
 
 module Datadog
   module Contrib
@@ -17,6 +20,7 @@ module Datadog
             Datadog.configuration[:active_record][:service_name] = value
           end
         end
+        option :middleware, default: true
         option :middleware_names, default: false
         option :distributed_tracing, default: false
         option :template_base_path, default: 'views/'
@@ -28,7 +32,41 @@ module Datadog
         class << self
           def patch
             return @patched if patched? || !compatible?
-            require_relative 'framework'
+
+            # Add a callback hook to add the trace middleware before the application initializes.
+            # Otherwise the middleware stack will be frozen.
+            do_once(:rails_before_initialize_hook) do
+              ::ActiveSupport.on_load(:before_initialize) do
+                # Sometimes we don't want to activate middleware e.g. OpenTracing, etc.
+                if Datadog.configuration[:rails][:middleware]
+                  # Add trace middleware
+                  config.middleware.insert_before(0, Datadog::Contrib::Rack::TraceMiddleware)
+
+                  # Insert right after Rails exception handling middleware, because if it's before,
+                  # it catches and swallows the error. If it's too far after, custom middleware can find itself
+                  # between, and raise exceptions that don't end up getting tagged on the request properly.
+                  # e.g lost stack trace.
+                  config.middleware.insert_after(
+                    ActionDispatch::ShowExceptions,
+                    Datadog::Contrib::Rails::ExceptionMiddleware
+                  )
+                end
+              end
+            end
+
+            # Add a callback hook to finish configuring the tracer after the application is initialized.
+            # We need to wait for some things, like application name, middleware stack, etc.
+            do_once(:rails_after_initialize_hook) do
+              ::ActiveSupport.on_load(:after_initialize) do
+                Datadog::Contrib::Rails::Framework.setup
+
+                # Add instrumentation to Rails components
+                Datadog::Contrib::Rails::ActionController.instrument
+                Datadog::Contrib::Rails::ActionView.instrument
+                Datadog::Contrib::Rails::ActiveSupport.instrument
+              end
+            end
+
             @patched = true
           rescue => e
             Datadog::Tracer.log.error("Unable to apply Rails integration: #{e}")
@@ -49,5 +87,3 @@ module Datadog
     end
   end
 end
-
-require 'ddtrace/contrib/rails/railtie' if Datadog.registry[:rails].compatible?

data/lib/ddtrace/contrib/rails/railtie.rb

@@ -5,11 +5,14 @@ require 'ddtrace/contrib/rack/middlewares'
 module Datadog
   # Railtie class initializes
   class Railtie < Rails::Railtie
-    config.app_middleware.insert_before(0, Datadog::Contrib::Rack::TraceMiddleware)
-    # Insert right after Rails exception handling middleware, because if it's before,
-    # it catches and swallows the error. If it's too far after, custom middleware can find itself
-    # between, and raise exceptions that don't end up getting tagged on the request properly (e.g lost stack trace.)
-    config.app_middleware.insert_after(ActionDispatch::ShowExceptions, Datadog::Contrib::Rails::ExceptionMiddleware)
+    # Add the trace middleware to the application stack
+    initializer 'datadog.add_middleware' do |app|
+      app.middleware.insert_before(0, Datadog::Contrib::Rack::TraceMiddleware)
+      # Insert right after Rails exception handling middleware, because if it's before,
+      # it catches and swallows the error. If it's too far after, custom middleware can find itself
+      # between, and raise exceptions that don't end up getting tagged on the request properly (e.g lost stack trace.)
+      app.middleware.insert_after(ActionDispatch::ShowExceptions, Datadog::Contrib::Rails::ExceptionMiddleware)
+    end
 
     config.after_initialize do
       Datadog::Contrib::Rails::Framework.setup

data/lib/ddtrace/opentracer.rb

@@ -0,0 +1,40 @@
+module Datadog
+  # Namespace for ddtrace OpenTracing implementation
+  module OpenTracer
+    module_function
+
+    def supported?
+      Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.1')
+    end
+
+    def load_opentracer
+      require 'opentracing'
+      require 'opentracing/carrier'
+      require 'ddtrace'
+      require 'ddtrace/opentracer/carrier'
+      require 'ddtrace/opentracer/tracer'
+      require 'ddtrace/opentracer/span'
+      require 'ddtrace/opentracer/span_context'
+      require 'ddtrace/opentracer/span_context_factory'
+      require 'ddtrace/opentracer/scope'
+      require 'ddtrace/opentracer/scope_manager'
+      require 'ddtrace/opentracer/thread_local_scope'
+      require 'ddtrace/opentracer/thread_local_scope_manager'
+      require 'ddtrace/opentracer/distributed_headers'
+      require 'ddtrace/opentracer/propagator'
+      require 'ddtrace/opentracer/text_map_propagator'
+      require 'ddtrace/opentracer/binary_propagator'
+      require 'ddtrace/opentracer/rack_propagator'
+      require 'ddtrace/opentracer/global_tracer'
+
+      # Modify the OpenTracing module functions
+      OpenTracing.module_eval do
+        class << self
+          prepend Datadog::OpenTracer::GlobalTracer
+        end
+      end
+    end
+
+    load_opentracer if supported?
+  end
+end

data/lib/ddtrace/opentracer/binary_propagator.rb

@@ -0,0 +1,24 @@
+module Datadog
+  module OpenTracer
+    # OpenTracing propagator for Datadog::OpenTracer::Tracer
+    module BinaryPropagator
+      extend Propagator
+
+      # Inject a SpanContext into the given carrier
+      #
+      # @param span_context [SpanContext]
+      # @param carrier [Carrier] A carrier object of Binary type
+      def self.inject(span_context, carrier)
+        nil
+      end
+
+      # Extract a SpanContext in Binary format from the given carrier.
+      #
+      # @param carrier [Carrier] A carrier object of Binary type
+      # @return [SpanContext, nil] the extracted SpanContext or nil if none could be found
+      def self.extract(carrier)
+        SpanContext::NOOP_INSTANCE
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/carrier.rb

@@ -0,0 +1,6 @@
+module Datadog
+  module OpenTracer
+    class Carrier < ::OpenTracing::Carrier
+    end
+  end
+end

data/lib/ddtrace/opentracer/distributed_headers.rb

@@ -0,0 +1,46 @@
+require 'ddtrace/span'
+require 'ddtrace/ext/distributed'
+
+module Datadog
+  module OpenTracer
+    # DistributedHeaders provides easy access and validation to headers
+    class DistributedHeaders
+      include Datadog::Ext::DistributedTracing
+
+      def initialize(carrier)
+        @carrier = carrier
+      end
+
+      def valid?
+        # Sampling priority is optional.
+        !trace_id.nil? && !parent_id.nil?
+      end
+
+      def trace_id
+        id HTTP_HEADER_TRACE_ID
+      end
+
+      def parent_id
+        id HTTP_HEADER_PARENT_ID
+      end
+
+      def sampling_priority
+        hdr = @carrier[HTTP_HEADER_SAMPLING_PRIORITY]
+        # It's important to make a difference between no header,
+        # and a header defined to zero.
+        return unless hdr
+        value = hdr.to_i
+        return if value < 0
+        value
+      end
+
+      private
+
+      def id(header)
+        value = @carrier[header].to_i
+        return if value.zero? || value >= Datadog::Span::MAX_ID
+        value < 0 ? value + 0x1_0000_0000_0000_0000 : value
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/global_tracer.rb

@@ -0,0 +1,15 @@
+module Datadog
+  module OpenTracer
+    # Patch for OpenTracing module
+    module GlobalTracer
+      def global_tracer=(tracer)
+        super.tap do
+          if tracer.class <= Datadog::OpenTracer::Tracer
+            # Update the Datadog global tracer, too.
+            Datadog.instance_variable_set(:@tracer, tracer.datadog_tracer)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/propagator.rb

@@ -0,0 +1,22 @@
+module Datadog
+  module OpenTracer
+    # OpenTracing propagator for Datadog::OpenTracer::Tracer
+    module Propagator
+      # Inject a SpanContext into the given carrier
+      #
+      # @param span_context [SpanContext]
+      # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
+      def inject(span_context, carrier)
+        raise NotImplementedError
+      end
+
+      # Extract a SpanContext in the given format from the given carrier.
+      #
+      # @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(carrier)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/rack_propagator.rb

@@ -0,0 +1,60 @@
+require 'ddtrace/propagation/http_propagator'
+
+module Datadog
+  module OpenTracer
+    # OpenTracing propagator for Datadog::OpenTracer::Tracer
+    module RackPropagator
+      extend Propagator
+      extend Datadog::Ext::DistributedTracing
+      include Datadog::Ext::DistributedTracing
+
+      BAGGAGE_PREFIX = 'ot-baggage-'.freeze
+      BAGGAGE_PREFIX_FORMATTED = 'HTTP_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
+          Datadog::HTTPPropagator.inject!(span_context.datadog_context, carrier)
+
+          # Inject baggage
+          span_context.baggage.each do |key, value|
+            carrier[BAGGAGE_PREFIX + key] = value
+          end
+
+          nil
+        end
+
+        # Extract a SpanContext in Rack format from the given carrier.
+        #
+        # @param carrier [Carrier] A carrier object of Rack type
+        # @return [SpanContext, nil] the extracted SpanContext or nil if none could be found
+        def extract(carrier)
+          # First extract & build a Datadog context
+          datadog_context = Datadog::HTTPPropagator.extract(carrier)
+
+          # Then extract any other baggage
+          baggage = {}
+          carrier.each do |key, value|
+            baggage[header_to_baggage(key)] = value if baggage_header?(key)
+          end
+
+          SpanContextFactory.build(datadog_context: datadog_context, baggage: baggage)
+        end
+
+        private
+
+        def baggage_header?(header)
+          header.to_s.start_with?(BAGGAGE_PREFIX_FORMATTED)
+        end
+
+        def header_to_baggage(key)
+          key[BAGGAGE_PREFIX_FORMATTED.length, key.length].downcase
+        end
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/scope.rb

@@ -0,0 +1,15 @@
+module Datadog
+  module OpenTracer
+    # OpenTracing adapter for scope
+    class Scope < ::OpenTracing::Scope
+      attr_reader \
+        :manager,
+        :span
+
+      def initialize(manager:, span:)
+        @manager = manager
+        @span = span
+      end
+    end
+  end
+end

data/lib/ddtrace/opentracer/scope_manager.rb

@@ -0,0 +1,6 @@
+module Datadog
+  module OpenTracer
+    class ScopeManager < ::OpenTracing::ScopeManager
+    end
+  end
+end

data/lib/ddtrace/opentracer/span.rb

@@ -0,0 +1,90 @@
+module Datadog
+  module OpenTracer
+    # OpenTracing adapter for Datadog::Span
+    class Span < ::OpenTracing::Span
+      attr_reader \
+        :datadog_span
+
+      def initialize(datadog_span:, span_context:)
+        @datadog_span = datadog_span
+        @span_context = span_context
+      end
+
+      # Set the name of the operation
+      #
+      # @param [String] name
+      def operation_name=(name)
+        datadog_span.name = name
+      end
+
+      # Span Context
+      #
+      # @return [SpanContext]
+      def context
+        @span_context
+      end
+
+      # Set a tag value on this span
+      # @param key [String] the key of the tag
+      # @param value [String, Numeric, Boolean] the value of the tag. If it's not
+      # a String, Numeric, or Boolean it will be encoded with to_s
+      def set_tag(key, value)
+        tap { datadog_span.set_tag(key, value) }
+      end
+
+      # Set a baggage item on the span
+      # @param key [String] the key of the baggage item
+      # @param value [String] the value of the baggage item
+      def set_baggage_item(key, value)
+        tap do
+          # SpanContext is immutable, so to make changes
+          # build a new span context.
+          @span_context = SpanContextFactory.clone(
+            span_context: context,
+            baggage: { key => value }
+          )
+        end
+      end
+
+      # Get a baggage item
+      # @param key [String] the key of the baggage item
+      # @return [String] value of the baggage item
+      def get_baggage_item(key)
+        context.baggage[key]
+      end
+
+      # @deprecated Use {#log_kv} instead.
+      # Reason: event is an optional standard log field defined in spec and not required.  Also,
+      # method name {#log_kv} is more consistent with other language implementations such as Python and Go.
+      #
+      # Add a log entry to this span
+      # @param event [String] event name for the log
+      # @param timestamp [Time] time of the log
+      # @param fields [Hash] Additional information to log
+      def log(event: nil, timestamp: Time.now, **fields)
+        super # Log deprecation warning
+
+        # If the fields specify an error
+        if fields.key?(:'error.object')
+          datadog_span.set_error(fields[:'error.object'])
+        end
+      end
+
+      # Add a log entry to this span
+      # @param timestamp [Time] time of the log
+      # @param fields [Hash] Additional information to log
+      def log_kv(timestamp: Time.now, **fields)
+        # If the fields specify an error
+        if fields.key?(:'error.object')
+          datadog_span.set_error(fields[:'error.object'])
+        end
+      end
+
+      # Finish the {Span}
+      # @param end_time [Time] custom end time, if not now
+      def finish(end_time: Time.now)
+        datadog_span.finish(end_time)
+      end
+    end
+  end
+end

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,73 @@
+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
+          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
+                              )
+                            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/version.rb

@@ -1,7 +1,7 @@
 module Datadog
   module VERSION
     MAJOR = 0
-    MINOR = 15
+    MINOR = 16
     PATCH = 0
     PRE = nil
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ddtrace
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Datadog, Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-09-12 00:00:00.000000000 Z
+date: 2018-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: opentracing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -400,6 +414,22 @@ files:
 - lib/ddtrace/ext/sql.rb
 - lib/ddtrace/logger.rb
 - lib/ddtrace/monkey.rb
+- lib/ddtrace/opentracer.rb
+- lib/ddtrace/opentracer/binary_propagator.rb
+- lib/ddtrace/opentracer/carrier.rb
+- lib/ddtrace/opentracer/distributed_headers.rb
+- lib/ddtrace/opentracer/global_tracer.rb
+- lib/ddtrace/opentracer/propagator.rb
+- lib/ddtrace/opentracer/rack_propagator.rb
+- lib/ddtrace/opentracer/scope.rb
+- lib/ddtrace/opentracer/scope_manager.rb
+- lib/ddtrace/opentracer/span.rb
+- lib/ddtrace/opentracer/span_context.rb
+- lib/ddtrace/opentracer/span_context_factory.rb
+- lib/ddtrace/opentracer/text_map_propagator.rb
+- lib/ddtrace/opentracer/thread_local_scope.rb
+- lib/ddtrace/opentracer/thread_local_scope_manager.rb
+- lib/ddtrace/opentracer/tracer.rb
 - lib/ddtrace/patcher.rb
 - lib/ddtrace/pin.rb
 - lib/ddtrace/pipeline.rb