ddtrace 0.13.0 → 0.47.0

data/integration/images/ruby/3.0/Dockerfile

@@ -0,0 +1,54 @@
+FROM ruby:3.0
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install prerequisites
+RUN set -ex && \
+        echo "===> Installing dependencies" && \
+        apt-get -y update && \
+        apt-get install -y --force-yes --no-install-recommends \
+            curl wget tar gzip gnupg apt-transport-https ca-certificates tzdata locales && \
+        \
+        echo "===> Installing NodeJS" && \
+        apt-get install -y --force-yes --no-install-recommends nodejs && \
+        \
+        echo "===> Installing Yarn" && \
+        curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - && \
+        echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list && \
+        apt-get update && \
+        apt-get install -y --force-yes --no-install-recommends yarn && \
+        \
+        echo "===> Installing database libraries" && \
+        apt-get install -y --force-yes --no-install-recommends \
+            postgresql-client sqlite3 && \
+        \
+        echo "===> Installing dev tools" && \
+        mkdir -p /usr/share/man/man1 && \
+        apt-get install -y --force-yes --no-install-recommends \
+            sudo git openssh-client rsync vim \
+            net-tools netcat parallel unzip zip bzip2 && \
+        \
+        echo "===> Cleaning up" && \
+        rm -rf /var/lib/apt/lists/*;
+
+# Set timezone to UTC by default
+RUN ln -sf /usr/share/zoneinfo/Etc/UTC /etc/localtime
+
+# Set language
+RUN locale-gen en_US.UTF-8
+ENV LANG en_US.UTF-8
+ENV LANGUAGE en_US:en
+
+# Install RubyGems
+RUN gem update --system
+RUN mkdir -p "$GEM_HOME" && chmod -R 777 "$GEM_HOME"
+
+# Upgrade RubyGems and Bundler
+RUN gem update --system
+RUN gem install bundler
+ENV BUNDLE_SILENCE_ROOT_WARNING 1
+
+# Setup demo environment includes
+COPY ./include /vendor/dd-demo
+ENV RUBYLIB /vendor/dd-demo
+ENV RUBYOPT -rdatadog/demo_env

data/integration/images/wrk/Dockerfile

@@ -0,0 +1,33 @@
+FROM debian:jessie
+
+RUN echo "===> Installing  tools..."  && \
+    apt-get -y update && \
+    apt-get -y install build-essential curl && \
+    \
+    echo "===> Installing wrk" && \
+    WRK_VERSION=$(curl -L https://github.com/wg/wrk/raw/master/CHANGES 2>/dev/null | \
+                  egrep '^wrk' | head -n 1 | awk '{print $2}') && \
+    echo $WRK_VERSION  && \
+    mkdir /opt/wrk && \
+    cd /opt/wrk && \
+    curl -L https://github.com/wg/wrk/archive/$WRK_VERSION.tar.gz | \
+       tar zx --strip 1 && \
+    make && \
+    cp wrk /usr/local/bin/ && \
+    \
+    echo "===> Cleaning the system" && \
+    apt-get -f -y --auto-remove remove build-essential && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /opt/wrk/
+
+# Setup directory
+RUN mkdir /scripts
+RUN mkdir /data
+WORKDIR /scripts
+
+# Add scripts
+COPY ./include /vendor/dd-demo
+COPY ./wrk/scripts /scripts
+
+# Set entrypoint
+ENTRYPOINT ["./entrypoint.sh"]

data/integration/images/wrk/scripts/entrypoint.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+bash /vendor/dd-demo/http-health-check
+
+# Start the load test
+echo "== Starting load test... =="
+
+if [[ $# -eq 0 ]] ; then
+  echo "** No load test specified: pass wrk args as a command. **"
+  echo "== Load test aborted. =="
+  exit 1
+else
+  COMMAND="wrk $@"
+  echo "Command: $COMMAND"
+  /bin/bash -c "$COMMAND"
+  echo "== Load test done. =="
+  exit 0
+fi

data/integration/images/wrk/scripts/scenarios/basic/default.lua

@@ -0,0 +1 @@
+wrk.method = "GET"

data/integration/images/wrk/scripts/scenarios/basic/fibonacci.lua

@@ -0,0 +1 @@
+wrk.method = "GET"

data/integration/script/build-images

@@ -0,0 +1,43 @@
+#!/bin/bash
+set -euo pipefail
+
+INTEGRATION_SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+INTEGRATION_DIR=${INTEGRATION_SCRIPT_DIR%/script}
+cd $INTEGRATION_DIR
+
+# Parse options
+while getopts ":v:" opt; do
+  case $opt in
+    v)
+      APP_RUBY_VERSION=$OPTARG
+      ;;
+    \?)
+      echo "Invalid option: -$OPTARG" >&2
+      exit 1
+      ;;
+    :)
+      echo "Option -$OPTARG requires an argument." >&2
+      exit 1
+      ;;
+  esac
+done
+
+echo "== Building base images... =="
+# "wrk" not necessary for CI: will be auto-built by local apps via docker-compose.
+# docker build -t datadog/dd-apm-demo:wrk -f $INTEGRATION_DIR/images/wrk/Dockerfile $INTEGRATION_DIR/images
+docker build -t datadog/dd-apm-demo:agent -f $INTEGRATION_DIR/images/agent/Dockerfile $INTEGRATION_DIR/images/agent
+
+if [ -v APP_RUBY_VERSION ]; then
+  docker build -t datadog/dd-apm-demo:rb-$APP_RUBY_VERSION -f $INTEGRATION_DIR/images/ruby/$APP_RUBY_VERSION/Dockerfile $INTEGRATION_DIR/images
+else
+  docker build -t datadog/dd-apm-demo:rb-2.0 -f $INTEGRATION_DIR/images/ruby/2.0/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-2.1 -f $INTEGRATION_DIR/images/ruby/2.1/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-2.2 -f $INTEGRATION_DIR/images/ruby/2.2/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-2.3 -f $INTEGRATION_DIR/images/ruby/2.3/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-2.4 -f $INTEGRATION_DIR/images/ruby/2.4/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-2.5 -f $INTEGRATION_DIR/images/ruby/2.5/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-2.6 -f $INTEGRATION_DIR/images/ruby/2.6/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-2.7 -f $INTEGRATION_DIR/images/ruby/2.7/Dockerfile $INTEGRATION_DIR/images
+  docker build -t datadog/dd-apm-demo:rb-3.0 -f $INTEGRATION_DIR/images/ruby/3.0/Dockerfile $INTEGRATION_DIR/images
+fi
+echo "== Done building base images. =="

data/lib/ddtrace.rb

@@ -1,6 +1,10 @@
-require 'thread'
+# During development, we load `ddtrace` by through `ddtrace.gemspec`,
+# which in turn eager loads 'ddtrace/version'.
+#
+# Users load this gem by requiring this file.
+# We need to ensure that any files loaded in our gemspec are also loaded here.
+require 'ddtrace/version'
 
-require 'ddtrace/registry'
 require 'ddtrace/pin'
 require 'ddtrace/tracer'
 require 'ddtrace/error'
@@ -9,72 +13,71 @@ require 'ddtrace/quantization/http'
 require 'ddtrace/pipeline'
 require 'ddtrace/configuration'
 require 'ddtrace/patcher'
+require 'ddtrace/metrics'
+require 'ddtrace/auto_instrument_base'
 
 # \Datadog global namespace that includes all tracing functionality for Tracer and Span classes.
 module Datadog
-  @tracer = Tracer.new
-  @registry = Registry.new
+  extend Configuration
+  extend AutoInstrumentBase
 
-  # Default tracer that can be used as soon as +ddtrace+ is required:
-  #
-  #   require 'ddtrace'
-  #
-  #   span = Datadog.tracer.trace('web.request')
-  #   span.finish()
-  #
-  # If you want to override the default tracer, the recommended way
-  # is to "pin" your own tracer onto your traced component:
-  #
-  #   tracer = Datadog::Tracer.new
-  #   pin = Datadog::Pin.get_from(mypatchcomponent)
-  #   pin.tracer = tracer
+  # Load and extend Contrib by default
+  require 'ddtrace/contrib/extensions'
+  extend Contrib::Extensions
 
-  def self.tracer
-    @tracer
-  end
+  # Load and extend OpenTelemetry compatibility by default
+  require 'ddtrace/opentelemetry/extensions'
+  extend OpenTelemetry::Extensions
 
-  def self.registry
-    @registry
-  end
+  # Load and extend AutoInstrument
+  require 'ddtrace/contrib/auto_instrument'
+  extend Contrib::AutoInstrument
 
-  class << self
-    attr_writer :configuration
-
-    def configuration
-      @configuration ||= Configuration.new
-    end
-
-    def configure(target = configuration, opts = {})
-      if target.is_a?(Configuration)
-        yield(target)
-      else
-        Configuration::PinSetup.new(target, opts).call
-      end
-    end
-  end
+  # Add shutdown hook:
+  # Ensures the tracer has an opportunity to flush traces
+  # and cleanup before terminating the process.
+  at_exit { Datadog.shutdown! }
 end
 
-require 'ddtrace/contrib/base'
-require 'ddtrace/contrib/rack/patcher'
-require 'ddtrace/contrib/rails/patcher'
-require 'ddtrace/contrib/active_model_serializers/patcher'
-require 'ddtrace/contrib/active_record/patcher'
-require 'ddtrace/contrib/sequel/patcher'
-require 'ddtrace/contrib/elasticsearch/patcher'
-require 'ddtrace/contrib/faraday/patcher'
-require 'ddtrace/contrib/grape/patcher'
-require 'ddtrace/contrib/graphql/patcher'
-require 'ddtrace/contrib/grpc/patcher'
-require 'ddtrace/contrib/redis/patcher'
-require 'ddtrace/contrib/http/patcher'
-require 'ddtrace/contrib/aws/patcher'
-require 'ddtrace/contrib/sucker_punch/patcher'
-require 'ddtrace/contrib/mongodb/patcher'
-require 'ddtrace/contrib/dalli/patcher'
-require 'ddtrace/contrib/rake/patcher'
-require 'ddtrace/contrib/resque/patcher'
-require 'ddtrace/contrib/racecar/patcher'
-require 'ddtrace/contrib/sidekiq/patcher'
-require 'ddtrace/contrib/excon/patcher'
-require 'ddtrace/contrib/mysql2/patcher'
-require 'ddtrace/monkey'
+require 'ddtrace/contrib/action_cable/integration'
+require 'ddtrace/contrib/action_pack/integration'
+require 'ddtrace/contrib/action_view/integration'
+require 'ddtrace/contrib/active_model_serializers/integration'
+require 'ddtrace/contrib/active_record/integration'
+require 'ddtrace/contrib/active_support/integration'
+require 'ddtrace/contrib/aws/integration'
+require 'ddtrace/contrib/concurrent_ruby/integration'
+require 'ddtrace/contrib/cucumber/integration'
+require 'ddtrace/contrib/dalli/integration'
+require 'ddtrace/contrib/delayed_job/integration'
+require 'ddtrace/contrib/elasticsearch/integration'
+require 'ddtrace/contrib/ethon/integration'
+require 'ddtrace/contrib/excon/integration'
+require 'ddtrace/contrib/faraday/integration'
+require 'ddtrace/contrib/grape/integration'
+require 'ddtrace/contrib/graphql/integration'
+require 'ddtrace/contrib/grpc/integration'
+require 'ddtrace/contrib/http/integration'
+require 'ddtrace/contrib/httpclient/integration'
+require 'ddtrace/contrib/httprb/integration'
+require 'ddtrace/contrib/integration'
+require 'ddtrace/contrib/kafka/integration'
+require 'ddtrace/contrib/presto/integration'
+require 'ddtrace/contrib/que/integration'
+require 'ddtrace/contrib/mysql2/integration'
+require 'ddtrace/contrib/mongodb/integration'
+require 'ddtrace/contrib/qless/integration'
+require 'ddtrace/contrib/racecar/integration'
+require 'ddtrace/contrib/rack/integration'
+require 'ddtrace/contrib/rails/integration'
+require 'ddtrace/contrib/rake/integration'
+require 'ddtrace/contrib/redis/integration'
+require 'ddtrace/contrib/resque/integration'
+require 'ddtrace/contrib/rest_client/integration'
+require 'ddtrace/contrib/rspec/integration'
+require 'ddtrace/contrib/sequel/integration'
+require 'ddtrace/contrib/shoryuken/integration'
+require 'ddtrace/contrib/sidekiq/integration'
+require 'ddtrace/contrib/sinatra/integration'
+require 'ddtrace/contrib/sneakers/integration'
+require 'ddtrace/contrib/sucker_punch/integration'

data/lib/ddtrace/analytics.rb

@@ -0,0 +1,38 @@
+require 'ddtrace/ext/analytics'
+
+module Datadog
+  # Defines analytics behavior
+  module Analytics
+    class << self
+      def set_sample_rate(span, sample_rate)
+        return if span.nil? || !sample_rate.is_a?(Numeric)
+
+        span.set_metric(Datadog::Ext::Analytics::TAG_SAMPLE_RATE, sample_rate)
+      end
+
+      def set_measured(span, value = true)
+        return if span.nil?
+
+        # rubocop:disable Style/MultipleComparison
+        value = value == true || value == 1 ? 1 : 0
+        span.set_metric(Datadog::Ext::Analytics::TAG_MEASURED, value)
+      end
+    end
+
+    # Extension for Datadog::Span
+    module Span
+      def set_tag(key, value)
+        case key
+        when Ext::Analytics::TAG_ENABLED
+          # If true, set rate to 1.0, otherwise set 0.0.
+          value = value == true ? Ext::Analytics::DEFAULT_SAMPLE_RATE : 0.0
+          Analytics.set_sample_rate(self, value)
+        when Ext::Analytics::TAG_SAMPLE_RATE
+          Analytics.set_sample_rate(self, value)
+        else
+          super if defined?(super)
+        end
+      end
+    end
+  end
+end

data/lib/ddtrace/auto_instrument.rb

@@ -0,0 +1,3 @@
+require 'ddtrace'
+
+Datadog.add_auto_instrument

data/lib/ddtrace/auto_instrument_base.rb

@@ -0,0 +1,6 @@
+module Datadog
+  # base methods stubbed for adding auto instrument extensions
+  module AutoInstrumentBase
+    def add_auto_instrument; end
+  end
+end

data/lib/ddtrace/buffer.rb

@@ -1,60 +1,326 @@
-require 'thread'
+require 'ddtrace/diagnostics/health'
+require 'ddtrace/runtime/object_space'
 
+# Trace buffer that accumulates traces for a consumer.
+# Consumption can happen from a different thread.
 module Datadog
-  # Trace buffer that stores application traces. The buffer has a maximum size and when
-  # the buffer is full, a random trace is discarded. This class is thread-safe and is used
-  # automatically by the ``Tracer`` instance when a ``Span`` is finished.
-  class TraceBuffer
+  # Buffer that stores objects. The buffer has a maximum size and when
+  # the buffer is full, a random object is discarded.
+  class Buffer
     def initialize(max_size)
       @max_size = max_size
-
-      @mutex = Mutex.new()
-      @traces = []
+      @items = []
       @closed = false
     end
 
-    # Add a new ``trace`` in the local queue. This method doesn't block the execution
-    # even if the buffer is full. In that case, a random trace is discarded.
-    def push(trace)
-      @mutex.synchronize do
-        return if @closed
-        len = @traces.length
-        if len < @max_size || @max_size <= 0
-          @traces << trace
+    # Add a new ``item`` in the local queue. This method doesn't block the execution
+    # even if the buffer is full. In that case, a random item is discarded.
+    def push(item)
+      return if closed?
+
+      full? ? replace!(item) : add!(item)
+      item
+    end
+
+    # A bulk push alternative to +#push+. Use this method if
+    # pushing more than one item for efficiency.
+    def concat(items)
+      return if closed?
+
+      # Segment items into underflow and overflow
+      underflow, overflow = overflow_segments(items)
+
+      # Concatenate items do not exceed capacity.
+      add_all!(underflow) unless underflow.nil?
+
+      # Iteratively replace items, to ensure pseudo-random replacement.
+      overflow.each { |item| replace!(item) } unless overflow.nil?
+    end
+
+    # Stored items are returned and the local buffer is reset.
+    def pop
+      drain!
+    end
+
+    # Return the current number of stored traces.
+    def length
+      @items.length
+    end
+
+    # Return if the buffer is empty.
+    def empty?
+      @items.empty?
+    end
+
+    # Closes this buffer, preventing further pushing.
+    # Draining is still allowed.
+    def close
+      @closed = true
+    end
+
+    def closed?
+      @closed
+    end
+
+    protected
+
+    # Segment items into two distinct segments: underflow and overflow.
+    # Underflow are items that will fit into buffer.
+    # Overflow are items that will exceed capacity, after underflow is added.
+    # Returns each array, and nil if there is no underflow/overflow.
+    def overflow_segments(items)
+      underflow = nil
+      overflow = nil
+
+      overflow_size = @max_size > 0 ? (@items.length + items.length) - @max_size : 0
+
+      if overflow_size > 0
+        # Items will overflow
+        if overflow_size < items.length
+          # Partial overflow
+          underflow_end_index = items.length - overflow_size - 1
+          underflow = items[0..underflow_end_index]
+          overflow = items[(underflow_end_index + 1)..-1]
         else
-          # we should replace a random trace with the new one
-          @traces[rand(len)] = trace
+          # Total overflow
+          overflow = items
         end
+      else
+        # Items do not exceed capacity.
+        underflow = items
       end
+
+      [underflow, overflow]
+    end
+
+    def full?
+      @max_size > 0 && @items.length >= @max_size
+    end
+
+    def add_all!(items)
+      @items.concat(items)
+    end
+
+    def add!(item)
+      @items << item
+    end
+
+    def replace!(item)
+      # Choose random item to be replaced
+      replace_index = rand(@items.length)
+
+      # Replace random item
+      discarded_item = @items[replace_index]
+      @items[replace_index] = item
+
+      # Return discarded item
+      discarded_item
+    end
+
+    def drain!
+      items = @items
+      @items = []
+      items
+    end
+  end
+
+  # Buffer that stores objects, has a maximum size, and
+  # can be safely used concurrently on any environment.
+  #
+  # This implementation uses a {Mutex} around public methods, incurring
+  # overhead in order to ensure thread-safety.
+  #
+  # This is implementation is recommended for non-CRuby environments.
+  # If using CRuby, {Datadog::CRubyBuffer} is a faster implementation with minimal compromise.
+  class ThreadSafeBuffer < Buffer
+    def initialize(max_size)
+      super
+
+      @mutex = Mutex.new
+    end
+
+    # Add a new ``item`` in the local queue. This method doesn't block the execution
+    # even if the buffer is full. In that case, a random item is discarded.
+    def push(item)
+      synchronize { super }
+    end
+
+    def concat(items)
+      synchronize { super }
     end
 
     # Return the current number of stored traces.
     def length
-      @mutex.synchronize do
-        return @traces.length
-      end
+      synchronize { super }
     end
 
     # Return if the buffer is empty.
     def empty?
-      @mutex.synchronize do
-        return @traces.empty?
-      end
+      synchronize { super }
     end
 
     # Stored traces are returned and the local buffer is reset.
     def pop
-      @mutex.synchronize do
-        traces = @traces
-        @traces = []
-        return traces
-      end
+      synchronize { super }
     end
 
     def close
-      @mutex.synchronize do
-        @closed = true
-      end
+      synchronize { super }
+    end
+
+    def synchronize(&block)
+      @mutex.synchronize(&block)
+    end
+  end
+
+  # Buffer that stores objects, has a maximum size, and
+  # can be safely used concurrently with CRuby.
+  #
+  # Under extreme concurrency scenarios, this class can exceed
+  # its +max_size+ by up to 4%.
+  #
+  # Because singular +Array+ operations are thread-safe in CRuby,
+  # we can implement the trace buffer without an explicit lock,
+  # while making the compromise of allowing the buffer to go
+  # over its maximum limit under extreme circumstances.
+  #
+  # On the following scenario:
+  # * 4.5 million spans/second.
+  # * Pushed into a single CRubyTraceBuffer from 1000 threads.
+  # The buffer can exceed its maximum size by no more than 4%.
+  #
+  # This implementation allocates less memory and is faster
+  # than {Datadog::ThreadSafeBuffer}.
+  #
+  # @see spec/ddtrace/benchmark/buffer_benchmark_spec.rb Buffer benchmarks
+  # @see https://github.com/ruby-concurrency/concurrent-ruby/blob/c1114a0c6891d9634f019f1f9fe58dcae8658964/lib/concurrent-ruby/concurrent/array.rb#L23-L27
+  class CRubyBuffer < Buffer
+    # Add a new ``trace`` in the local queue. This method doesn't block the execution
+    # even if the buffer is full. In that case, a random trace is discarded.
+    def replace!(item)
+      # we should replace a random trace with the new one
+      replace_index = rand(@items.size)
+      replaced_trace = @items.delete_at(replace_index)
+      @items << item
+
+      # We might have deleted an element right when the buffer
+      # was drained, thus +replaced_trace+ will be +nil+.
+      # In that case, nothing was replaced, and this method
+      # performed a simple insertion into the buffer.
+      replaced_trace
     end
   end
+
+  # Health metrics for trace buffers.
+  module MeasuredBuffer
+    def initialize(*_)
+      super
+
+      @buffer_accepted = 0
+      @buffer_accepted_lengths = 0
+      @buffer_dropped = 0
+      @buffer_spans = 0
+    end
+
+    def add!(trace)
+      super
+
+      # Emit health metrics
+      measure_accept(trace)
+    end
+
+    def add_all!(traces)
+      super
+
+      # Emit health metrics
+      traces.each { |trace| measure_accept(trace) }
+    end
+
+    def replace!(trace)
+      discarded_trace = super
+
+      # Emit health metrics
+      measure_accept(trace)
+      measure_drop(discarded_trace) if discarded_trace
+
+      discarded_trace
+    end
+
+    # Stored traces are returned and the local buffer is reset.
+    def drain!
+      traces = super
+      measure_pop(traces)
+      traces
+    end
+
+    def measure_accept(trace)
+      @buffer_accepted += 1
+      @buffer_accepted_lengths += trace.length
+
+      @buffer_spans += trace.length
+    rescue StandardError => e
+      Datadog.logger.debug("Failed to measure queue accept. Cause: #{e.message} Source: #{e.backtrace.first}")
+    end
+
+    def measure_drop(trace)
+      @buffer_dropped += 1
+
+      @buffer_spans -= trace.length
+    rescue StandardError => e
+      Datadog.logger.debug("Failed to measure queue drop. Cause: #{e.message} Source: #{e.backtrace.first}")
+    end
+
+    def measure_pop(traces)
+      # Accepted, cumulative totals
+      Datadog.health_metrics.queue_accepted(@buffer_accepted)
+      Datadog.health_metrics.queue_accepted_lengths(@buffer_accepted_lengths)
+
+      # Dropped, cumulative totals
+      Datadog.health_metrics.queue_dropped(@buffer_dropped)
+      # TODO: are we missing a +queue_dropped_lengths+ metric?
+
+      # Queue gauges, current values
+      Datadog.health_metrics.queue_max_length(@max_size)
+      Datadog.health_metrics.queue_spans(@buffer_spans)
+      Datadog.health_metrics.queue_length(traces.length)
+
+      # Reset aggregated metrics
+      @buffer_accepted = 0
+      @buffer_accepted_lengths = 0
+      @buffer_dropped = 0
+      @buffer_spans = 0
+    rescue StandardError => e
+      Datadog.logger.debug("Failed to measure queue. Cause: #{e.message} Source: #{e.backtrace.first}")
+    end
+  end
+
+  # Trace buffer that stores application traces, has a maximum size, and
+  # can be safely used concurrently on any environment.
+  #
+  # @see {Datadog::ThreadSafeBuffer}
+  class ThreadSafeTraceBuffer < ThreadSafeBuffer
+    prepend MeasuredBuffer
+  end
+
+  # Trace buffer that stores application traces, has a maximum size, and
+  # can be safely used concurrently with CRuby.
+  #
+  # @see {Datadog::CRubyBuffer}
+  class CRubyTraceBuffer < CRubyBuffer
+    prepend MeasuredBuffer
+  end
+
+  # Trace buffer that stores application traces. The buffer has a maximum size and when
+  # the buffer is full, a random trace is discarded. This class is thread-safe and is used
+  # automatically by the ``Tracer`` instance when a ``Span`` is finished.
+  #
+  # We choose the default TraceBuffer implementation for current platform dynamically here.
+  #
+  # TODO We should restructure this module, so that classes are not declared at top-level ::Datadog.
+  # TODO Making such a change is potentially breaking for users manually configuring the tracer.
+  TraceBuffer = if Datadog::Ext::Runtime::RUBY_ENGINE == 'ruby'
+                  CRubyTraceBuffer
+                else
+                  ThreadSafeTraceBuffer
+                end
 end