ddtrace 0.3.1

data/lib/ddtrace/tracer.rb

@@ -0,0 +1,180 @@
+require 'pp'
+require 'thread'
+require 'logger'
+
+require 'ddtrace/span'
+require 'ddtrace/buffer'
+require 'ddtrace/writer'
+
+# \Datadog global namespace that includes all tracing functionality for Tracer and Span classes.
+module Datadog
+  # A \Tracer keeps track of the time spent by an application processing a single operation. For
+  # example, a trace can be used to track the entire time spent processing a complicated web request.
+  # Even though the request may require multiple resources and machines to handle the request, all
+  # of these function calls and sub-requests would be encapsulated within a single trace.
+  class Tracer
+    attr_reader :writer, :services
+    attr_accessor :enabled
+
+    # Global, memoized, lazy initialized instance of a logger that is used within the the Datadog
+    # namespace. This logger outputs to +STDOUT+ by default, and is considered thread-safe.
+    def self.log
+      unless defined? @logger
+        @logger = Logger.new(STDOUT)
+        @logger.level = Logger::INFO
+      end
+      @logger
+    end
+
+    # Activate the debug mode providing more information related to tracer usage
+    def self.debug_logging=(value)
+      log.level = value ? Logger::DEBUG : Logger::INFO
+    end
+
+    # Return if the debug mode is activated or not
+    def self.debug_logging
+      log.level == Logger::DEBUG
+    end
+
+    # Initialize a new \Tracer used to create, sample and submit spans that measure the
+    # time of sections of code. Available +options+ are:
+    #
+    # * +enabled+: set if the tracer submits or not spans to the local agent. It's enabled
+    #   by default.
+    def initialize(options = {})
+      @enabled = options.fetch(:enabled, true)
+      @writer = options.fetch(:writer, Datadog::Writer.new)
+      @buffer = Datadog::SpanBuffer.new()
+
+      @mutex = Mutex.new
+      @spans = []
+      @services = {}
+    end
+
+    # Updates the current \Tracer instance, so that the tracer can be configured after the
+    # initialization. Available +options+ are:
+    #
+    # * +enabled+: set if the tracer submits or not spans to the trace agent
+    # * +hostname+: change the location of the trace agent
+    # * +port+: change the port of the trace agent
+    #
+    # For instance, if the trace agent runs in a different location, just:
+    #
+    #   tracer.configure(hostname: 'agent.service.consul', port: '8777')
+    #
+    def configure(options = {})
+      enabled = options.fetch(:enabled, nil)
+      hostname = options.fetch(:hostname, nil)
+      port = options.fetch(:port, nil)
+
+      @enabled = enabled unless enabled.nil?
+      @writer.transport.hostname = hostname unless hostname.nil?
+      @writer.transport.port = port unless port.nil?
+    end
+
+    # Set the information about the given service. A valid example is:
+    #
+    #   tracer.set_service_info('web-application', 'rails', 'web')
+    def set_service_info(service, app, app_type)
+      @services[service] = {
+        'app' => app,
+        'app_type' => app_type
+      }
+
+      return unless Datadog::Tracer.debug_logging
+      Datadog::Tracer.log.debug("set_service_info: service: #{service} app: #{app} type: #{app_type}")
+    end
+
+    # Return a +span+ that will trace an operation called +name+. You could trace your code
+    # using a <tt>do-block</tt> like:
+    #
+    #   tracer.trace('web.request') do |span|
+    #     span.service = 'my-web-site'
+    #     span.resource = '/'
+    #     span.set_tag('http.method', request.request_method)
+    #     do_something()
+    #   end
+    #
+    # The <tt>tracer.trace()</tt> method can also be used without a block in this way:
+    #
+    #   span = tracer.trace('web.request', service: 'my-web-site')
+    #   do_something()
+    #   span.finish()
+    #
+    # Remember that in this case, calling <tt>span.finish()</tt> is mandatory.
+    #
+    # When a Trace is started, <tt>trace()</tt> will store the created span; subsequent spans will
+    # become it's children and will inherit some properties:
+    #
+    #   parent = tracer.trace('parent')     # has no parent span
+    #   child  = tracer.trace('child')      # is a child of 'parent'
+    #   child.finish()
+    #   parent.finish()
+    #   parent2 = tracer.trace('parent2')   # has no parent span
+    #   parent2.finish()
+    #
+    def trace(name, options = {})
+      span = Span.new(self, name, options)
+
+      # set up inheritance
+      parent = @buffer.get()
+      span.set_parent(parent)
+      @buffer.set(span)
+
+      # call the finish only if a block is given; this ensures
+      # that a call to tracer.trace() without a block, returns
+      # a span that should be manually finished.
+      if block_given?
+        begin
+          yield(span)
+        rescue StandardError => e
+          span.set_error(e)
+          raise
+        ensure
+          span.finish()
+        end
+      else
+        span
+      end
+    end
+
+    # Record the given finished span in the +spans+ list. When a +span+ is recorded, it will be sent
+    # to the Datadog trace agent as soon as the trace is finished.
+    def record(span)
+      spans = []
+      @mutex.synchronize do
+        @spans << span
+        parent = span.parent
+        # Bubble up until we find a non-finished parent. This is necessary for
+        # the case when the parent finished after its parent.
+        parent = parent.parent while !parent.nil? && parent.finished?
+        @buffer.set(parent)
+
+        return unless parent.nil?
+        spans = @spans
+        @spans = []
+      end
+
+      return if spans.empty?
+      write(spans)
+    end
+
+    # Return the current active span or +nil+.
+    def active_span
+      @buffer.get()
+    end
+
+    def write(spans)
+      return if @writer.nil? || !@enabled
+
+      if Datadog::Tracer.debug_logging
+        Datadog::Tracer.log.debug("Writing #{spans.length} spans (enabled: #{@enabled})")
+        PP.pp(spans)
+      end
+
+      @writer.write(spans, @services)
+    end
+
+    private :write
+  end
+end

data/lib/ddtrace/transport.rb

@@ -0,0 +1,149 @@
+require 'thread'
+require 'net/http'
+
+require 'ddtrace/encoding'
+
+module Datadog
+  # Transport class that handles the spans delivery to the
+  # local trace-agent. The class wraps a Net:HTTP instance
+  # so that the Transport is thread-safe.
+  class HTTPTransport
+    attr_accessor :hostname, :port
+
+    # seconds before the transport timeout
+    TIMEOUT = 1
+
+    def initialize(hostname, port, options = {})
+      @hostname = hostname
+      @port = port
+      @traces_endpoint = '/v0.3/traces'.freeze
+      @services_endpoint = '/v0.3/services'.freeze
+      @compatibility_mode = false
+      @encoder = options.fetch(:encoder, Datadog::Encoding::MsgpackEncoder.new())
+
+      # overwrite the Content-type with the one chosen in the Encoder
+      @headers = options.fetch(:headers, {})
+      @headers['Content-Type'] = @encoder.content_type
+
+      # stats
+      @mutex = Mutex.new
+      @count_success = 0
+      @count_client_error = 0
+      @count_server_error = 0
+      @count_internal_error = 0
+    end
+
+    # route the send to the right endpoint
+    def send(endpoint, data)
+      case endpoint
+      when :services
+        payload = @encoder.encode_services(data)
+        status_code = post(@services_endpoint, payload)
+      when :traces
+        payload = @encoder.encode_traces(data)
+        status_code = post(@traces_endpoint, payload)
+      else
+        Datadog::Tracer.log.error("Unsupported endpoint: #{endpoint}")
+        return nil
+      end
+
+      return status_code unless downgrade?(status_code) && !@compatibility_mode
+
+      # the API endpoint is not available so we should downgrade the connection and re-try the call
+      downgrade!
+      send(endpoint, data)
+    end
+
+    # send data to the trace-agent; the method is thread-safe
+    def post(url, data)
+      Datadog::Tracer.log.debug("Sending data from process: #{Process.pid}")
+      request = Net::HTTP::Post.new(url, @headers)
+      request.body = data
+
+      response = Net::HTTP.start(@hostname, @port, read_timeout: TIMEOUT) { |http| http.request(request) }
+      handle_response(response)
+    rescue StandardError => e
+      Datadog::Tracer.log.error(e.message)
+      500
+    end
+
+    # Downgrade the connection to a compatibility version of the HTTPTransport;
+    # this method should target a stable API that works whatever is the agent
+    # or the tracing client versions.
+    def downgrade!
+      @compatibility_mode = true
+      @traces_endpoint = '/v0.2/traces'.freeze
+      @services_endpoint = '/v0.2/services'.freeze
+      @encoder = Datadog::Encoding::JSONEncoder.new()
+      @headers['Content-Type'] = @encoder.content_type
+    end
+
+    def informational?(code)
+      code.between?(100, 199)
+    end
+
+    def success?(code)
+      code.between?(200, 299)
+    end
+
+    def redirect?(code)
+      code.between?(300, 399)
+    end
+
+    def client_error?(code)
+      code.between?(400, 499)
+    end
+
+    def server_error?(code)
+      code.between?(500, 599)
+    end
+
+    # receiving a 404 means that we're targeting an endpoint that is not available
+    # in the trace agent. Usually this means that we've an up-to-date tracing client,
+    # while running an obsolete agent.
+    # receiving a 415 means that we're using an unsupported content-type with an existing
+    # endpoint. Usually this means that we're using a newer encoder with a previous
+    # endpoint. In both cases, we're going to downgrade the transporter encoder so that
+    # it will target a stable API.
+    def downgrade?(code)
+      code == 404 || code == 415
+    end
+
+    # handles the server response; here you can log the trace-agent response
+    # or do something more complex to recover from a possible error. This
+    # function is handled within the HTTP mutex.synchronize so it's thread-safe.
+    def handle_response(response)
+      status_code = response.code.to_i
+
+      if success?(status_code)
+        Datadog::Tracer.log.debug('Payload correctly sent to the trace agent.')
+        @mutex.synchronize { @count_success += 1 }
+      elsif downgrade?(status_code)
+        Datadog::Tracer.log.debug("calling the endpoint but received #{status_code}; downgrading the API")
+      elsif client_error?(status_code)
+        Datadog::Tracer.log.error("Client error: #{response.message}")
+        @mutex.synchronize { @count_client_error += 1 }
+      elsif server_error?(status_code)
+        Datadog::Tracer.log.error("Server error: #{response.message}")
+        @mutex.synchronize { @count_server_error += 1 }
+      end
+
+      status_code
+    rescue StandardError => e
+      Datadog::Tracer.log.error(e.message)
+      @mutex.synchronize { @count_internal_error += 1 }
+      500
+    end
+
+    def stats
+      @mutex.synchronize do
+        {
+          success: @count_success,
+          client_error: @count_client_error,
+          server_error: @count_server_error,
+          internal_error: @count_internal_error
+        }
+      end
+    end
+  end
+end

data/lib/ddtrace/utils.rb

@@ -0,0 +1,9 @@
+module Datadog
+  # TODO[manu]: write docs
+  module Utils
+    # Return a span id
+    def self.next_id
+      rand(Datadog::Span::MAX_ID)
+    end
+  end
+end

data/lib/ddtrace/version.rb

@@ -0,0 +1,9 @@
+module Datadog
+  module VERSION
+    MAJOR = 0
+    MINOR = 3
+    PATCH = 1
+
+    STRING = [MAJOR, MINOR, PATCH].compact.join('.')
+  end
+end

data/lib/ddtrace/workers.rb

@@ -0,0 +1,109 @@
+require 'time'
+
+require 'ddtrace/buffer'
+
+module Datadog
+  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
+      def initialize(span_interval, service_interval, transport, buff_size, trace_task, service_task)
+        @trace_task = trace_task
+        @service_task = service_task
+        @span_interval = span_interval
+        @service_interval = service_interval
+        @trace_buffer = TraceBuffer.new(buff_size)
+        @service_buffer = TraceBuffer.new(buff_size)
+        @transport = transport
+
+        @worker = nil
+        @run = false
+      end
+
+      # Callback function that process traces and executes the +send_traces()+ method.
+      def callback_traces
+        return if @trace_buffer.empty?
+
+        begin
+          traces = @trace_buffer.pop()
+          @trace_task.call(traces, @transport)
+        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::Tracer.log.error("Error during traces flush: dropped #{items.length} items. Cause: #{e}")
+        end
+      end
+
+      # Callback function that process traces and executes the +send_services()+ method.
+      def callback_services
+        return if @service_buffer.empty?
+
+        begin
+          services = @service_buffer.pop()
+          # pick up the latest services hash (this is a FIFO list)
+          # that is different from what we sent before.
+          different = services.inject(false) { |acc, elem| elem != @last_flushed_services ? elem : acc }
+          if different
+            if @service_task.call(different, @transport)
+              @last_flushed_services = different.clone
+            end
+          else
+            Datadog::Tracer.log.debug('No new different services, skipping flush.')
+          end
+        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::Tracer.log.error("Error during services flush: dropped #{items.length} items. Cause: #{e}")
+        end
+      end
+
+      # Start the timer execution.
+      def start
+        return if @run
+        @run = true
+        @worker = Thread.new() do
+          Datadog::Tracer.log.debug("Starting thread in the process: #{Process.pid}")
+          @last_flushed_services = nil
+          next_send_services = Time.now
+
+          # this loop assumes spans are flushed more often than services
+          while @run
+            callback_traces
+            if Time.now >= next_send_services
+              next_send_services = Time.now + @service_interval
+              callback_services
+            end
+            sleep(@span_interval)
+          end
+        end
+      end
+
+      # Stop the timer execution. Tasks already in the queue will be executed.
+      def stop
+        @run = false
+      end
+
+      # Block until executor shutdown is complete or until timeout seconds have passed.
+      def join
+        @worker.join(10)
+      end
+
+      # Enqueue an item in the trace internal buffer. This operation is thread-safe
+      # because uses the +TraceBuffer+ data structure.
+      def enqueue_trace(trace)
+        @trace_buffer.push(trace)
+      end
+
+      # Enqueue an item in the service internal buffer. This operation is thread-safe
+      # because uses the +TraceBuffer+ data structure.
+      def enqueue_service(service)
+        return if service == {} # no use to send this, not worth it
+        @service_buffer.push(service)
+      end
+    end
+  end
+end