ddtrace 0.52.0 → 1.8.0

data/lib/datadog/tracing/workers/trace_writer.rb

@@ -0,0 +1,195 @@
+# typed: false
+
+require_relative '../../core'
+require_relative '../../core/worker'
+require_relative '../../core/workers/async'
+require_relative '../../core/workers/polling'
+require_relative '../../core/workers/queue'
+
+require_relative '../buffer'
+require_relative '../pipeline'
+require_relative '../event'
+
+require_relative '../../../ddtrace/transport/http'
+
+module Datadog
+  module Tracing
+    module Workers
+      # Writes traces to transport synchronously
+      class TraceWriter < Core::Worker
+        attr_reader \
+          :transport
+
+        # rubocop:disable Lint/MissingSuper
+        def initialize(options = {})
+          transport_options = options.fetch(:transport_options, {})
+
+          transport_options[:agent_settings] = options[:agent_settings] if options.key?(:agent_settings)
+
+          @transport = options.fetch(:transport) do
+            Transport::HTTP.default(**transport_options)
+          end
+        end
+        # rubocop:enable Lint/MissingSuper
+
+        def perform(traces)
+          write_traces(traces)
+        end
+
+        def write(trace)
+          write_traces([trace])
+        end
+
+        def write_traces(traces)
+          traces = process_traces(traces)
+          flush_traces(traces)
+        rescue StandardError => e
+          Datadog.logger.error(
+            "Error while writing traces: dropped #{traces.length} items. Cause: #{e} Location: #{Array(e.backtrace).first}"
+          )
+        end
+
+        def process_traces(traces)
+          # Run traces through the processing pipeline
+          Pipeline.process!(traces)
+        end
+
+        def flush_traces(traces)
+          transport.send_traces(traces).tap do |response|
+            flush_completed.publish(response)
+          end
+        end
+
+        # TODO: Register `Datadog::Core::Diagnostics::EnvironmentLogger.log!`
+        # TODO: as a flush_completed subscriber when the `TraceWriter`
+        # TODO: instantiation code is implemented.
+        def flush_completed
+          @flush_completed ||= FlushCompleted.new
+        end
+
+        # Flush completed event for worker
+        class FlushCompleted < Event
+          def initialize
+            super(:flush_completed)
+          end
+        end
+      end
+
+      # Writes traces to transport asynchronously,
+      # using a thread & buffer.
+      class AsyncTraceWriter < TraceWriter
+        include Core::Workers::Queue
+        include Core::Workers::Polling
+
+        DEFAULT_BUFFER_MAX_SIZE = 1000
+        FORK_POLICY_ASYNC = :async
+        FORK_POLICY_SYNC = :sync
+
+        attr_writer \
+          :async
+
+        def initialize(options = {})
+          # Workers::TraceWriter settings
+          super
+
+          # Workers::Polling settings
+          self.enabled = options.fetch(:enabled, true)
+
+          # Workers::Async::Thread settings
+          @async = true
+          self.fork_policy = options.fetch(:fork_policy, FORK_POLICY_ASYNC)
+
+          # Workers::IntervalLoop settings
+          self.loop_base_interval = options[:interval] if options.key?(:interval)
+          self.loop_back_off_ratio = options[:back_off_ratio] if options.key?(:back_off_ratio)
+          self.loop_back_off_max = options[:back_off_max] if options.key?(:back_off_max)
+
+          # Workers::Queue settings
+          @buffer_size = options.fetch(:buffer_size, DEFAULT_BUFFER_MAX_SIZE)
+          self.buffer = TraceBuffer.new(@buffer_size)
+        end
+
+        # NOTE: #perform is wrapped by other modules:
+        #       Polling --> Async --> IntervalLoop --> AsyncTraceWriter --> TraceWriter
+        #
+        # WARNING: This method breaks the Liskov Substitution Principle -- TraceWriter#perform is spec'd to return the
+        # result from the writer, whereas this method always returns nil.
+        def perform(traces)
+          super(traces).tap do |responses|
+            loop_back_off! if responses.find(&:server_error?)
+          end
+
+          nil
+        end
+
+        def stop(*args)
+          buffer.close if running?
+          super
+        end
+
+        def enqueue(trace)
+          buffer.push(trace)
+        end
+
+        def dequeue
+          # Wrap results in Array because they are
+          # splatted as args against TraceWriter#perform.
+          [buffer.pop]
+        end
+
+        # Are there more traces to be processed next?
+        def work_pending?
+          !buffer.empty?
+        end
+
+        def async?
+          @async == true
+        end
+
+        def fork_policy=(policy)
+          # Translate to Workers::Async::Thread policy
+          thread_fork_policy =  case policy
+                                when Core::Workers::Async::Thread::FORK_POLICY_STOP
+                                  policy
+                                when FORK_POLICY_SYNC
+                                  # Stop the async thread because the writer
+                                  # will bypass and run synchronously.
+                                  Core::Workers::Async::Thread::FORK_POLICY_STOP
+                                else
+                                  Core::Workers::Async::Thread::FORK_POLICY_RESTART
+                                end
+
+          # Update thread fork policy
+          super(thread_fork_policy)
+
+          # Update local policy
+          @writer_fork_policy = policy
+        end
+
+        def after_fork
+          # In multiprocess environments, forks will share the same buffer until its written to.
+          # A.K.A. copy-on-write. We don't want forks to write traces generated from another process.
+          # Instead, we reset it after the fork. (Make sure any enqueue operations happen after this.)
+          self.buffer = TraceBuffer.new(@buffer_size)
+
+          # Switch to synchronous mode if configured to do so.
+          # In some cases synchronous writing is preferred because the fork will be short lived.
+          @async = false if @writer_fork_policy == FORK_POLICY_SYNC
+        end
+
+        # WARNING: This method breaks the Liskov Substitution Principle -- TraceWriter#write is spec'd to return the
+        # result from the writer, whereas this method returns something else when running in async mode.
+        def write(trace)
+          # Start worker thread. If the process has forked, it will trigger #after_fork to
+          # reconfigure the worker accordingly.
+          # NOTE: It's important we do this before queuing or it will drop the current trace,
+          #       because #after_fork resets the buffer.
+          perform
+
+          # Queue the trace if running asynchronously, otherwise short-circuit and write it directly.
+          async? ? enqueue(trace) : write_traces([trace])
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/workers.rb

@@ -0,0 +1,125 @@
+# typed: true
+
+require_relative '../core'
+
+require_relative 'buffer'
+require_relative 'pipeline'
+
+module Datadog
+  module Tracing
+    module Workers
+      # Asynchronous worker that executes a +Send()+ operation after given
+      # seconds. Under the hood, it uses +Concurrent::TimerTask+ so that the thread
+      # will perform a task at regular intervals. The thread can be stopped
+      # with the +stop()+ method and can start with the +start()+ method.
+      class AsyncTransport
+        DEFAULT_BUFFER_MAX_SIZE = 1000
+        DEFAULT_FLUSH_INTERVAL = 1
+        DEFAULT_TIMEOUT = 5
+        BACK_OFF_RATIO = 1.2
+        BACK_OFF_MAX = 5
+        SHUTDOWN_TIMEOUT = 1
+
+        attr_reader \
+          :trace_buffer
+
+        def initialize(options = {})
+          @transport = options[:transport]
+
+          # Callbacks
+          @trace_task = options[:on_trace]
+
+          # Intervals
+          interval = options.fetch(:interval, DEFAULT_FLUSH_INTERVAL)
+          @flush_interval = interval
+          @back_off = interval
+
+          # Buffers
+          buffer_size = options.fetch(:buffer_size, DEFAULT_BUFFER_MAX_SIZE)
+          @trace_buffer = TraceBuffer.new(buffer_size)
+
+          # Threading
+          @shutdown = ConditionVariable.new
+          @mutex = Mutex.new
+          @worker = nil
+          @run = false
+        end
+
+        # Callback function that process traces and executes the +send_traces()+ method.
+        def callback_traces
+          return true if @trace_buffer.empty?
+
+          begin
+            traces = @trace_buffer.pop
+            traces = Pipeline.process!(traces)
+            @trace_task.call(traces, @transport) unless @trace_task.nil? || traces.empty?
+          rescue StandardError => e
+            # ensures that the thread will not die because of an exception.
+            # TODO[manu]: findout the reason and reschedule the send if it's not
+            # a fatal exception
+            Datadog.logger.error(
+              "Error during traces flush: dropped #{traces.length} items. Cause: #{e} Location: #{Array(e.backtrace).first}"
+            )
+          end
+        end
+
+        # Start the timer execution.
+        def start
+          @mutex.synchronize do
+            return if @run
+
+            @run = true
+            Datadog.logger.debug { "Starting thread for: #{self}" }
+            @worker = Thread.new { perform }
+            @worker.name = self.class.name unless Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.3')
+
+            nil
+          end
+        end
+
+        # Closes all available queues and waits for the trace buffer to flush
+        def stop
+          @mutex.synchronize do
+            return unless @run
+
+            @trace_buffer.close
+            @run = false
+            @shutdown.signal
+          end
+
+          join
+          true
+        end
+
+        # Block until executor shutdown is complete or until timeout seconds have passed.
+        def join
+          @worker.join(SHUTDOWN_TIMEOUT)
+        end
+
+        # Enqueue an item in the trace internal buffer. This operation is thread-safe
+        # because uses the +TraceBuffer+ data structure.
+        def enqueue_trace(trace)
+          return unless trace && !trace.empty?
+
+          @trace_buffer.push(trace)
+        end
+
+        private
+
+        alias flush_data callback_traces
+
+        def perform
+          loop do
+            @back_off = flush_data ? @flush_interval : [@back_off * BACK_OFF_RATIO, BACK_OFF_MAX].min
+
+            @mutex.synchronize do
+              return if !@run && @trace_buffer.empty?
+
+              @shutdown.wait(@mutex, @back_off) if @run # do not wait when shutting down
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/writer.rb

@@ -0,0 +1,187 @@
+# typed: true
+
+require_relative '../core'
+
+require_relative 'event'
+require_relative 'runtime/metrics'
+require_relative 'workers'
+
+require_relative '../../ddtrace/transport/http'
+
+module Datadog
+  module Tracing
+    # Processor that sends traces and metadata to the agent
+    # DEV: Our goal is for {Datadog::Tracing::Workers::TraceWriter} to replace this class in the future
+    # @public_api
+    class Writer
+      attr_reader \
+        :transport,
+        :worker,
+        :events
+
+      def initialize(options = {})
+        # writer and transport parameters
+        @buff_size = options.fetch(:buffer_size, Workers::AsyncTransport::DEFAULT_BUFFER_MAX_SIZE)
+        @flush_interval = options.fetch(:flush_interval, Workers::AsyncTransport::DEFAULT_FLUSH_INTERVAL)
+        transport_options = options.fetch(:transport_options, {})
+
+        transport_options[:agent_settings] = options[:agent_settings] if options.key?(:agent_settings)
+
+        # transport and buffers
+        @transport = options.fetch(:transport) do
+          Transport::HTTP.default(**transport_options)
+        end
+
+        # handles the thread creation after an eventual fork
+        @mutex_after_fork = Mutex.new
+        @pid = nil
+
+        @traces_flushed = 0
+
+        # one worker for traces
+        @worker = nil
+
+        # Once stopped, this writer instance cannot be restarted.
+        # This allow for graceful shutdown, while preventing
+        # the host application from inadvertently start new
+        # threads during shutdown.
+        @stopped = false
+
+        # Callback handler
+        @events = Events.new
+      end
+
+      # Explicitly starts the {Writer}'s internal worker.
+      #
+      # The {Writer} is also automatically started when necessary during calls to {.write}.
+      def start
+        @mutex_after_fork.synchronize do
+          return false if @stopped
+
+          pid = Process.pid
+          return if @worker && pid == @pid
+
+          @pid = pid
+
+          start_worker
+          true
+        end
+      end
+
+      # spawns a worker for spans; they share the same transport which is thread-safe
+      # @!visibility private
+      def start_worker
+        @trace_handler = ->(items, transport) { send_spans(items, transport) }
+        @worker = Workers::AsyncTransport.new(
+          transport: @transport,
+          buffer_size: @buff_size,
+          on_trace: @trace_handler,
+          interval: @flush_interval
+        )
+
+        @worker.start
+      end
+
+      # Gracefully shuts down this writer.
+      #
+      # Once stopped methods calls won't fail, but
+      # no internal work will be performed.
+      #
+      # It is not possible to restart a stopped writer instance.
+      def stop
+        @mutex_after_fork.synchronize { stop_worker }
+      end
+
+      def stop_worker
+        @stopped = true
+
+        return if @worker.nil?
+
+        @worker.stop
+        @worker = nil
+
+        true
+      end
+
+      private :start_worker, :stop_worker
+
+      # flush spans to the trace-agent, handles spans only
+      # @!visibility private
+      def send_spans(traces, transport)
+        return true if traces.empty?
+
+        # Send traces and get responses
+        responses = transport.send_traces(traces)
+
+        # Tally up successful flushes
+        responses.reject { |x| x.internal_error? || x.server_error? }.each do |response|
+          @traces_flushed += response.trace_count
+        end
+
+        events.after_send.publish(self, responses)
+
+        # Return if server error occurred.
+        !responses.find(&:server_error?)
+      end
+
+      # enqueue the trace for submission to the API
+      def write(trace)
+        # In multiprocess environments, the main process initializes the +Writer+ instance and if
+        # the process forks (i.e. a web server like Unicorn or Puma with multiple workers) the new
+        # processes will share the same +Writer+ until the first write (COW). Because of that,
+        # each process owns a different copy of the +@buffer+ after each write and so the
+        # +AsyncTransport+ will not send data to the trace agent.
+        #
+        # This check ensures that if a process doesn't own the current +Writer+, async workers
+        # will be initialized again (but only once for each process).
+        start if @worker.nil? || @pid != Process.pid
+
+        # TODO: Remove this, and have the tracer pump traces directly to runtime metrics
+        #       instead of working through the trace writer.
+        # Associate trace with runtime metrics
+        Runtime::Metrics.associate_trace(trace)
+
+        worker_local = @worker
+
+        if worker_local
+          worker_local.enqueue_trace(trace)
+        elsif !@stopped
+          Datadog.logger.debug('Writer either failed to start or was stopped before #write could complete')
+        end
+      end
+
+      # stats returns a dictionary of stats about the writer.
+      def stats
+        {
+          traces_flushed: @traces_flushed,
+          transport: @transport.stats
+        }
+      end
+
+      # Callback behavior
+      class Events
+        attr_reader \
+          :after_send
+
+        def initialize
+          @after_send = AfterSend.new
+        end
+
+        # Triggered after the writer sends traces through the transport.
+        # Provides the Writer instance and transport response list to the callback.
+        class AfterSend < Tracing::Event
+          def initialize
+            super(:after_send)
+          end
+        end
+      end
+
+      private
+
+      def reset_stats!
+        @traces_flushed = 0
+        @transport.stats.reset!
+      end
+    end
+  end
+end

data/lib/datadog/tracing.rb

@@ -0,0 +1,142 @@
+# typed: false
+
+require_relative 'core'
+require_relative 'tracing/pipeline'
+
+module Datadog
+  # Datadog APM tracing public API.
+  #
+  # The Datadog team ensures that public methods in this module
+  # only receive backwards compatible changes, and breaking changes
+  # will only occur in new major versions releases.
+  # @public_api
+  module Tracing
+    class << self
+      # (see Datadog::Tracing::Tracer#trace)
+      # @public_api
+      def trace(name, continue_from: nil, **span_options, &block)
+        tracer.trace(name, continue_from: continue_from, **span_options, &block)
+      end
+
+      # (see Datadog::Tracing::Tracer#continue_trace!)
+      # @public_api
+      def continue_trace!(digest, &block)
+        tracer.continue_trace!(digest, &block)
+      end
+
+      # The tracer's internal logger instance.
+      # All tracing log output is handled by this object.
+      #
+      # The logger can be configured through {.configure},
+      # through {Datadog::Core::Configuration::Settings::DSL::Logger} options.
+      #
+      # @!attribute [r] logger
+      # @public_api
+      def logger
+        Datadog.logger
+      end
+
+      # (see Datadog::Tracing::Tracer#active_trace)
+      # @public_api
+      def active_trace
+        current_tracer = tracer
+        return unless current_tracer
+
+        current_tracer.active_trace
+      end
+
+      # (see Datadog::Tracing::Tracer#active_span)
+      # @public_api
+      def active_span
+        current_tracer = tracer
+        return unless current_tracer
+
+        current_tracer.active_span
+      end
+
+      # (see Datadog::Tracing::TraceSegment#keep!)
+      # If no trace is active, no action is taken.
+      # @public_api
+      def keep!
+        trace = active_trace
+        active_trace.keep! if trace
+      end
+
+      # (see Datadog::Tracing::TraceSegment#reject!)
+      # If no trace is active, no action is taken.
+      # @public_api
+      def reject!
+        trace = active_trace
+        active_trace.reject! if trace
+      end
+
+      # (see Datadog::Tracing::Tracer#active_correlation)
+      # @public_api
+      def correlation
+        current_tracer = tracer
+        return unless current_tracer
+
+        current_tracer.active_correlation
+      end
+
+      # Textual representation of {.correlation}, which can be
+      # added to individual log lines in order to correlate them with the active
+      # trace.
+      #
+      # Example:
+      #
+      # ```
+      # MyLogger.log("#{Datadog::Tracing.log_correlation}] My message")
+      # # dd.env=prod dd.service=auth dd.version=13.8 dd.trace_id=5458478252992251 dd.span_id=7117552347370098 My message
+      # ```
+      #
+      # @return [String] correlation information
+      # @public_api
+      def log_correlation
+        correlation.to_log_format
+      end
+
+      # Gracefully shuts down the tracer.
+      #
+      # The public tracing API will still respond to method calls as usual
+      # but might not internally perform the expected internal work after shutdown.
+      #
+      # This avoids errors being raised across the host application
+      # during shutdown while allowing for the graceful decommission of resources.
+      #
+      # {.shutdown!} cannot be reversed.
+      # @public_api
+      def shutdown!
+        current_tracer = tracer
+        return unless current_tracer
+
+        current_tracer.shutdown!
+      end
+
+      # (see Datadog::Tracing::Pipeline.before_flush)
+      def before_flush(*processors, &processor_block)
+        Pipeline.before_flush(*processors, &processor_block)
+      end
+
+      # Is the tracer collecting telemetry data in this process?
+      # @return [Boolean] `true` if the tracer is collecting data in this process, otherwise `false`.
+      def enabled?
+        current_tracer = tracer
+        return false unless current_tracer
+
+        current_tracer.enabled
+      end
+
+      private
+
+      # DEV: components hosts both tracing and profiling inner objects today
+      def components
+        Datadog.send(:components)
+      end
+
+      def tracer
+        components.tracer
+      end
+    end
+  end
+end

data/lib/ddtrace/auto_instrument.rb

@@ -1,5 +1,16 @@
 # typed: strict
-require 'ddtrace'
 
-Datadog.add_auto_instrument
-Datadog.profiler.start if Datadog.profiler
+# Entrypoint file for auto instrumentation.
+#
+# This file's path is part of the @public_api.
+require_relative '../ddtrace'
+require_relative '../datadog/tracing/contrib/auto_instrument'
+
+Datadog::Profiling.start_if_enabled
+
+module Datadog
+  module AutoInstrument
+    # Flag to determine if Auto Instrumentation was used
+    LOADED = true
+  end
+end

data/lib/ddtrace/auto_instrument_base.rb

@@ -1,4 +1,5 @@
 # typed: true
+
 module Datadog
   # base methods stubbed for adding auto instrument extensions
   module AutoInstrumentBase

data/lib/ddtrace/profiling/preload.rb

@@ -1,4 +1,4 @@
 # typed: strict
-require 'ddtrace'
 
-Datadog.profiler.start if Datadog.profiler
+# TODO: Warns users after 1.0 upgrade. Remove this file in 2.0.
+raise LoadError, 'This file has been moved to `datadog/profiling/preload` in 1.0.0'