instana 0.8.6 → 0.9.0.pre.slywolf3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 42faa21829471a9c09aef2c82c1bdf79cee9bb2a
-  data.tar.gz: 7f4d358d30c2bb53b3dc97a39fbcdbfb950a0db5
+  metadata.gz: 23defe3c2a845b3d6b8c92da8a08989e0b65085a
+  data.tar.gz: 7f2064a969abebbf119a994981b3b0915f069e05
 SHA512:
-  metadata.gz: d1b63875713111313dae3ba16b1374df8d3d70f78074c5617728eead258311d9a65cb537e03b44dc0f2e5a4b15fea7c7a0940f86957f78d91b29fd9bce81e5f9
-  data.tar.gz: 602264940c06d3e4d8ebae06f56e91af16729ead2af6c3bf5add6b434d3b6bd6576d6388dbefdc8d963fe1f4f11e5310fdf4fa9c8a014a7dcd5d0840aadf61bc
+  metadata.gz: 6e31e6dd3ec166b5152519d53b65e6e5af003f22cbc28a5d56262eeb9cf15b11f288a25cd91714af94c2984c3aab644876844fdfc8be8d05332db18be376e4c4
+  data.tar.gz: f76e9995ff846378f4b95ee33677fe077395f3e705d37ec6a683749689363b110339a05193b51c71283a23eeed17413c40eebae8b9e7f139853bae443947915e

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.ruby-version

data/Gemfile

@@ -5,7 +5,15 @@ group :development, :test do
   gem 'minitest'
   gem 'minitest-reporters'
   gem 'minitest-debugger', :require => false
+  gem 'rack-test'
   gem 'webmock'
+
+  gem "puma"
+
+  # Rack v2 dropped support for Ruby 2.2 and higher.
+  if RUBY_VERSION < '2.2'
+    gem 'rack', '< 2.0'
+  end
 end
 
 group :development do

data/examples/tracing.rb

@@ -0,0 +1,73 @@
+#######################################
+## Block tracing
+#######################################
+
+#Instana::Tracer.start_or_continue_trace(name, kvs, incoming_id) - Initiates tracing
+#Instana::Tracer.trace(name, kvs) - starts a new span in an existing Trace
+
+# <start_or_continue_trace> will initiate a new trace.  Often used at entry
+# points in webservers, it will initialize tracing and instrument the passed
+# block.  <incoming_id> is for continuing remote traces (remote in terms
+# of service calls, or message queues).
+Instana::Tracer.start_or_continue_trace(:my_block_name, {}, incoming_id) do
+  # Code block
+end
+
+# <trace> will instrument a block of code in an already running trace.
+# This is the most common use case (instead of initiating new
+# traces).
+Instana::Tracer.trace(:postgres, {:user => 'postgres'}) do
+  @postgres.select(1)
+end
+
+#######################################
+## Lower level logging
+#######################################
+
+# <log_start_or_continue_trace> will initiate a new trace.  Often used at entry
+# points in webservers, it will establish a new trace (for web request, 
+# background jobs etc.).
+# <incoming_id> is for continuing remote traces (remote in terms
+# of service calls, or message queues).
+Instana::Tracer.log_start_or_continue(:rack, {}, incoming_id)
+
+# <log_entry> will start a new span from the current span within
+# a trace.
+Instana::Tracer.log_entry(name, kvs)
+
+# <log_exit> will close out the current span
+Instana::Tracer.log_exit(name, kvs)
+
+# <log_info> will append information to the current span in the
+# trace.  Examples could be redis options, contextual data, user
+# login status etc...
+Instana::Tracer.log_info({:some_key => 'some_value'})
+
+# <log_error> will log an exception to the current span in the
+# trace.
+Instana::Tracer.log_error(Exception)
+
+# <log_end> closes out the current span, finishes
+# the trace and adds it to ::Instana.processor
+# for reporting.
+Instana::Tracer.log_end(:rack, {})
+
+#######################################
+# Lower level API Example
+######################################
+
+# Full Tracing Lifecycle example
+#
+Instana::Tracer.log_start_or_continue(:mywebserver, {:user_id => @user_id})
+
+begin
+  Instana::Tracer.log_entry(:redis_lookup, {:redisdb => @redisdb.url})
+  @redisdb.get(@user_id.session_id)
+rescue => e
+  Instana::Tracer.log_error(e)
+ensure
+  Instana::Tracer.log_exit(:redis_lookup)
+end
+
+Instana::Tracer.log_end(:mywebserver)
+

data/lib/instana.rb

@@ -7,6 +7,8 @@ module Instana
   class << self
     attr_accessor :agent
     attr_accessor :collectors
+    attr_accessor :tracer
+    attr_accessor :processor
     attr_accessor :config
     attr_accessor :logger
     attr_accessor :pid
@@ -17,7 +19,9 @@ module Instana
     # Initialize the Instana language agent
     #
     def start
-      @agent = Instana::Agent.new
+      @agent  = ::Instana::Agent.new
+      @tracer = ::Instana::Tracer.new
+      @processor = ::Instana::Processor.new
       @collectors = []
 
       @logger = Logger.new(STDOUT)
@@ -30,11 +34,11 @@ module Instana
 
       # Store the current pid so we can detect a potential fork
       # later on
-      @pid = Process.pid
+      @pid = ::Process.pid
     end
 
     def pid_change?
-      @pid != Process.pid
+      @pid != ::Process.pid
     end
   end
 end
@@ -42,9 +46,12 @@ end
 
 require "instana/config"
 require "instana/agent"
+require "instana/tracer"
+require "instana/tracing/processor"
 
 ::Instana.start
 
 require "instana/collectors"
+require "instana/instrumentation"
 
 ::Instana.agent.start

data/lib/instana/agent.rb

@@ -8,6 +8,7 @@ include Sys
 module Instana
   class Agent
     attr_accessor :state
+    attr_accessor :agent_uuid
 
     LOCALHOST = '127.0.0.1'.freeze
     MIME_JSON = 'application/json'.freeze
@@ -62,9 +63,7 @@ module Instana
       @process[:report_pid] = nil
     end
 
-    ##
-    # start
-    #
+    # Sets up periodic timers and starts the agent in a background thread.
     #
     def start
       # The announce timer
@@ -90,6 +89,7 @@ module Instana
               transition_to(:unannounced)
             end
           end
+          ::Instana.processor.send
         end
       end
 
@@ -109,9 +109,22 @@ module Instana
       end
     end
 
-    ##
-    # announce_sensor
+    # Indicates if the agent is ready to send metrics
+    # or data.
+    #
+    def ready?
+      # In test, we're always ready :-)
+      return true if ENV['INSTANA_GEM_TEST']
+
+      @state == :announced
+    end
+
+    # Returns the PID that we are reporting to
     #
+    def report_pid
+      @process[:report_pid]
+    end
+
     # Collect process ID, name and arguments to notify
     # the host agent.
     #
@@ -142,11 +155,10 @@ module Instana
       return false
     end
 
-    ##
-    # report_entity_data
-    #
     # Method to report metrics data to the host agent.
     #
+    # @param paylod [Hash] The collection of metrics to report.
+    #
     def report_entity_data(payload)
       with_snapshot = false
       path = "com.instana.plugin.ruby.#{@process[:report_pid]}"
@@ -187,9 +199,36 @@ module Instana
       Instana.logger.debug e.backtrace.join("\r\n")
     end
 
-    ##
-    # host_agent_ready?
+    # Accept and report spans to the host agent.
     #
+    # @param traces [Array] An array of [Span]
+    # @return [Boolean]
+    #
+    def report_spans(spans)
+      return unless @state == :announced
+
+      path = "com.instana.plugin.ruby/traces.#{@process[:report_pid]}"
+      uri = URI.parse("http://#{@host}:#{@port}/#{path}")
+      req = Net::HTTP::Post.new(uri)
+
+      req.body = spans.to_json
+      response = make_host_agent_request(req)
+
+      if response
+        last_trace_response = response.code.to_i
+
+        #::Instana.logger.debug "traces response #{last_trace_response}: #{spans.to_json}"
+
+        if [200, 204].include?(last_trace_response)
+          return true
+        end
+      end
+      false
+    rescue => e
+      Instana.logger.debug "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
+      Instana.logger.debug e.backtrace.join("\r\n")
+    end
+
     # Check that the host agent is available and can be contacted.  This will
     # first check localhost and if not, then attempt on the default gateway
     # for docker in bridged mode.  It will save where it found the host agent
@@ -229,12 +268,12 @@ module Instana
 
     private
 
-    ##
-    # transition_to
-    #
     # Handles any/all steps required in the transtion
     # between states.
     #
+    # @param state [Symbol] Can be 1 of 2 possible states:
+    #   `:announced`, `:unannounced`
+    #
     def transition_to(state)
       case state
       when :announced
@@ -254,13 +293,13 @@ module Instana
       end
     end
 
-    ##
-    # make host_agent_request
-    #
     # Centralization of the net/http communications
     # with the host agent. Pass in a prepared <req>
     # of type Net::HTTP::Get|Put|Head
     #
+    # @param req [Net::HTTP::Req] A prepared Net::HTTP request object of the type
+    #  you wish to make (Get, Put, Post etc.)
+    #
     def make_host_agent_request(req)
       req['Accept'] = MIME_JSON
       req['Content-Type'] = MIME_JSON
@@ -278,9 +317,6 @@ module Instana
       return nil
     end
 
-    ##
-    # pid_namespace?
-    #
     # Indicates whether we are running in a pid namespace (such as
     # Docker).
     #
@@ -289,9 +325,6 @@ module Instana
       Process.pid != get_real_pid
     end
 
-    ##
-    # get_real_pid
-    #
     # Attempts to determine the true process ID by querying the
     # /proc/<pid>/sched file.  This works on linux currently.
     #
@@ -301,9 +334,6 @@ module Instana
       v.match(/\d+/).to_s.to_i
     end
 
-    ##
-    # take_snapshot
-    #
     # Method to collect up process info for snapshots.  This
     # is generally used once per process.
     #

data/lib/instana/instrumentation.rb

@@ -0,0 +1,12 @@
+#
+# Load all of the files in the instrumentation subdirectory
+#
+pattern = File.join(File.dirname(__FILE__), 'instrumentation', '*.rb')
+Dir.glob(pattern) do |f|
+  begin
+    require f
+  rescue => e
+    Instana.logger.error "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
+    Instana.logger.debug e.backtrace.join("\r\n")
+  end
+end

data/lib/instana/instrumentation/net-http.rb

@@ -0,0 +1,50 @@
+require 'net/http'
+
+Net::HTTP.class_eval {
+
+  def request_with_instana(*args, &block)
+    if !Instana.tracer.tracing? || !started?
+      return request_without_instana(*args, &block)
+    end
+
+    ::Instana.tracer.log_entry(:'net-http')
+
+    # Send out the tracing context with the request
+    request = args[0]
+    our_trace_id = ::Instana.tracer.trace_id
+    our_span_id  = ::Instana.tracer.span_id
+
+    # Set request headers; encode IDs as hexadecimal strings
+    request['X-Instana-T'] = ::Instana.tracer.id_to_header(our_trace_id)
+    request['X-Instana-S'] = ::Instana.tracer.id_to_header(our_span_id)
+
+    response = request_without_instana(*args, &block)
+
+    # Pickup response headers; convert back to base 10 integer
+    if response.key?('X-Instana-T')
+      their_trace_id = ::Instana.tracer.header_to_id(response.header['X-Instana-T'])
+
+      if our_trace_id != their_trace_id
+        ::Instana.logger.debug "#{Thread.current}: Trace ID mismatch on net/http response! ours: #{our_trace_id} theirs: #{their_trace_id}"
+      end
+    end
+
+    kv_payload = { :http => {} }
+    kv_payload[:http][:status] = response.code
+    kv_payload[:http][:url] = request.uri.to_s
+    kv_payload[:http][:method] = request.method
+    ::Instana.tracer.log_info(kv_payload)
+
+    response
+  rescue => e
+    ::Instana.tracer.log_error(e)
+    raise
+  ensure
+    ::Instana.tracer.log_exit(:'net-http')
+  end
+
+  Instana.logger.info "Instrumenting net/http"
+
+  alias request_without_instana request
+  alias request request_with_instana
+}

data/lib/instana/instrumentation/rack.rb

@@ -0,0 +1,50 @@
+module Instana
+  class Rack
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      kvs = { :http => {} }
+      kvs[:http][:method] = env['REQUEST_METHOD']
+      kvs[:http][:url] = ::CGI.unescape(env['PATH_INFO'])
+
+      if env.key?('HTTP_HOST')
+        kvs[:http][:host] = env['HTTP_HOST']
+      elsif env.key?('SERVER_NAME')
+        kvs[:http][:host] = env['SERVER_NAME']
+      end
+
+      # Check incoming context
+      incoming_context = {}
+      if env.key?('HTTP_X_INSTANA_T')
+        incoming_context[:trace_id]  = ::Instana.tracer.header_to_id(env['HTTP_X_INSTANA_T'])
+        incoming_context[:parent_id] = ::Instana.tracer.header_to_id(env['HTTP_X_INSTANA_S']) if env.key?('HTTP_X_INSTANA_S')
+        incoming_context[:level]     = env['HTTP_X_INSTANA_L'] if env.key?('HTTP_X_INSTANA_L')
+      end
+
+      ::Instana.tracer.log_start_or_continue(:rack, {}, incoming_context)
+
+      status, headers, response = @app.call(env)
+
+      kvs[:http][:status] = status
+
+      # Save the IDs before the trace ends so we can place
+      # them in the response headers in the ensure block
+      trace_id = ::Instana.tracer.trace_id
+      span_id = ::Instana.tracer.span_id
+
+      [status, headers, response]
+    rescue Exception => e
+      ::Instana.tracer.log_error(e)
+      raise
+    ensure
+      if headers
+        # Set reponse headers; encode as hex string
+        headers['X-Instana-T'] = ::Instana.tracer.id_to_header(trace_id)
+        headers['X-Instana-S'] = ::Instana.tracer.id_to_header(span_id)
+      end
+      ::Instana.tracer.log_end(:rack, kvs)
+    end
+  end
+end

data/lib/instana/rack.rb

@@ -0,0 +1,10 @@
+# This file exists to just make the Instana::Rack require calls a bit more
+# user friendly.
+#
+# The real file is in the instrumentation subdirectory:
+# lib/instana/instrumentation/rack.rb
+#
+# require 'instana/rack'
+# config.middleware.use ::Instana::Rack
+#
+require 'instana/instrumentation/rack'

data/lib/instana/thread_local.rb

@@ -0,0 +1,15 @@
+module Instana
+  module ThreadLocal
+    def thread_local(name)
+      key = "__#{self}_#{name}__".intern
+
+      define_method(name) do
+        Thread.current[key]
+      end
+
+      define_method(name.to_s + '=') do |value|
+        Thread.current[key] = value
+      end
+    end
+  end
+end

data/lib/instana/tracer.rb

@@ -0,0 +1,178 @@
+require "instana/thread_local"
+require "instana/tracing/trace"
+require "instana/tracing/span"
+
+module Instana
+  class Tracer
+    extend ::Instana::ThreadLocal
+
+    thread_local :current_trace
+
+    #######################################
+    # Tracing blocks helper methods
+    #######################################
+
+    # Will start a new trace or continue an on-going one (such as
+    # from incoming remote requests with context headers).
+    #
+    # @param name [String] the name of the span to start
+    # @param kvs [Hash] list of key values to be reported in the span
+    # @param incoming_context [Hash] specifies the incoming context.  At a
+    #   minimum, it should specify :trace_id and :parent_id from the following:
+    #     @:trace_id the trace ID (must be an unsigned hex-string)
+    #     :parent_id the ID of the parent span (must be an unsigned hex-string)
+    #     :level specifies data collection level (optional)
+    #
+    def start_or_continue_trace(name, kvs = {}, incoming_context = {}, &block)
+      log_start_or_continue(name, kvs, incoming_context)
+      block.call
+    rescue Exception => e
+      log_error(e)
+      raise
+    ensure
+      log_end(name)
+    end
+
+    # Trace a block of code within the context of the exiting trace
+    #
+    # @param name [String] the name of the span to start
+    # @param kvs [Hash] list of key values to be reported in this new span
+    #
+    def trace(name, kvs = {}, &block)
+      log_entry(name, kvs)
+      result = block.call
+      result
+    rescue Exception => e
+      log_error(e)
+      raise
+    ensure
+      log_exit(name)
+    end
+
+    #######################################
+    # Lower level tracing methods
+    #######################################
+
+    # Will start a new trace or continue an on-going one (such as
+    # from incoming remote requests with context headers).
+    #
+    # @param name [String] the name of the span to start
+    # @param kvs [Hash] list of key values to be reported in the span
+    # @param incoming_context [Hash] specifies the incoming context.  At a
+    #   minimum, it should specify :trace_id and :parent_id from the following:
+    #     :trace_id the trace ID (must be an unsigned hex-string)
+    #     :parent_id the ID of the parent span (must be an unsigned hex-string)
+    #     :level specifies data collection level (optional)
+    #
+    def log_start_or_continue(name, kvs = {}, incoming_context = {})
+      return unless ::Instana.agent.ready?
+      self.current_trace = ::Instana::Trace.new(name, kvs, incoming_context)
+    end
+
+    # Will establish a new span as a child of the current span
+    # in an existing trace
+    #
+    # @param name [String] the name of the span to create
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def log_entry(name, kvs = {})
+      return unless tracing?
+      self.current_trace.new_span(name, kvs)
+    end
+
+    # Add info to the current span
+    #
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def log_info(kvs)
+      return unless tracing?
+      self.current_trace.add_info(kvs)
+    end
+
+    # Add an error to the current span
+    #
+    # @param e [Exception] Add exception to the current span
+    #
+    def log_error(e)
+      return unless tracing?
+      self.current_trace.add_error(e)
+    end
+
+    # Will close out the current span
+    #
+    # @note `name` isn't really required but helps keep sanity that
+    # we're closing out the span that we really want to close out.
+    #
+    # @param name [String] the name of the span to exit (close out)
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def log_exit(name, kvs = {})
+      return unless tracing?
+      self.current_trace.end_span(kvs)
+    end
+
+    # Closes out the current span in the current trace
+    # and queues the trace for reporting
+    #
+    # @note `name` isn't really required but helps keep sanity that
+    # we're ending the span that we really want to close out.
+    #
+    # @param name [String] the name of the span to end
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def log_end(name, kvs = {})
+      return unless tracing?
+
+      self.current_trace.finish(kvs)
+      Instana.processor.add(self.current_trace)
+      self.current_trace = nil
+    end
+
+    # Indicates if we're are currently in the process of
+    # collecting a trace.  This is false when the host agent isn
+    # available.
+    #
+    # @return [Boolean] true or false on whether we are currently tracing or not
+    #
+    def tracing?
+      # The non-nil value of this instance variable
+      # indicates if we are currently tracing
+      # in this thread or not.
+      self.current_trace ? true : false
+    end
+
+    # Convert an ID to a value appropriate to pass in a header.
+    #
+    # @param id [Integer] the id to be converted
+    #
+    # @return [String]
+    #
+    def id_to_header(id)
+      id.to_s(16)
+    end
+
+    # Convert a received header value into a valid ID
+    #
+    # @param header_id [String] the header value to be converted
+    #
+    # @return [Integer]
+    #
+    def header_to_id(header_id)
+      header_id.to_i(16)
+    end
+
+    # Returns the trace ID for the active trace (if there is one),
+    # otherwise nil.
+    #
+    def trace_id
+      self.current_trace ? self.current_trace.id : nil
+    end
+
+    # Returns the current [Span] ID for the active trace (if there is one),
+    # otherwise nil.
+    #
+    def span_id
+      self.current_trace  ? current_trace.current_span_id : nil
+    end
+  end
+end

data/lib/instana/tracing/processor.rb

@@ -0,0 +1,93 @@
+require 'thread'
+
+module Instana
+  class Processor
+
+    def initialize
+      @queue = Queue.new
+    end
+
+    # Adds a trace to the queue to be processed and
+    # sent to the host agent
+    #
+    # @param [Trace] the trace to be added to the queue
+    def add(trace)
+      @queue.push(trace)
+    end
+
+    ##
+    # send
+    #
+    # Sends all traces in @queue to the host
+    # agent
+    #
+    # FIXME: Add limits checking here in regards to:
+    #   - Max HTTP Post size
+    #   - Out of control/growing queue
+    #   - Prevent another run of the timer while this is running
+    #
+    def send
+      return if @queue.empty?
+
+      size = @queue.size
+      if size > 10
+        Instana.logger.debug "Trace queue is #{size}"
+      end
+
+      ::Instana.agent.report_spans(queued_spans)
+    end
+
+    # Get the number traces currently in the queue
+    #
+    def queue_count
+      @queue.size
+    end
+
+    # Retrieves all of the traces in @queue and returns
+    # the sum of their raw spans.
+    # This is used by Processor::send and in the test suite.
+    # Note that traces retrieved with this method are removed
+    # entirely from the queue.
+    #
+    def queued_spans
+      return [] if @queue.empty?
+
+      spans = []
+      until @queue.empty? do
+        # Non-blocking pop; ignore exception
+        trace = @queue.pop(true) rescue nil
+        trace.spans.each do |s|
+          spans << s.raw
+        end
+      end
+      spans
+    end
+
+    # Retrieves all of the traces that are in @queue.
+    # Note that traces retrieved with this method are removed
+    # entirely from the queue.
+    #
+    def queued_traces
+      return [] if @queue.empty?
+
+      traces = []
+      until @queue.empty? do
+        # Non-blocking pop; ignore exception
+        traces << @queue.pop(true) rescue nil
+      end
+      traces
+    end
+
+    # Removes all traces from the @queue.  Used in the
+    # test suite.
+    #
+    def clear!
+      return [] if @queue.empty?
+
+      until @queue.empty? do
+        # Non-blocking pop; ignore exception
+        @queue.pop(true) rescue nil
+      end
+    end
+  end
+end

data/lib/instana/tracing/span.rb

@@ -0,0 +1,37 @@
+module Instana
+  class Span
+    attr_accessor :parent
+
+    def initialize(data)
+      @data = data
+    end
+
+    def id
+      @data[:s]
+    end
+
+    def parent_id
+      @data[:p]
+    end
+
+    def is_root?
+      @data[:s] == @data[:t]
+    end
+
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    def []=(key, value)
+      @data[key.to_sym] = value
+    end
+
+    def key?(k)
+      @data.key?(k.to_sym)
+    end
+
+    def raw
+      @data
+    end
+  end
+end

data/lib/instana/tracing/trace.rb

@@ -0,0 +1,169 @@
+module Instana
+  class Trace
+    # @return [Integer] the ID for this trace
+    attr_reader :id
+
+    # The collection of `Span` for this trace
+    # @return [Set] the collection of spans for this trace
+    attr_reader :spans
+
+    # Initializes a new instance of Trace
+    #
+    # @param name [String] the name of the span to start
+    # @param kvs [Hash] list of key values to be reported in the span
+    # @param incoming_context [Hash] specifies the incoming context.  At a
+    #   minimum, it should specify :trace_id and :parent_id from the following:
+    #     :trace_id the trace ID (must be an unsigned hex-string)
+    #     :parent_id the ID of the parent span (must be an unsigned hex-string)
+    #     :level specifies data collection level (optional)
+    #
+    def initialize(name, kvs = {}, incoming_context = {})
+      # The collection of spans that make
+      # up this trace.
+      @spans = Set.new
+
+      # The current active span
+      @current_span = nil
+
+      # Generate a random 64bit ID for this trace
+      @id = generate_id
+
+      # This is a new trace so open the first span with the proper
+      # root span IDs.
+      @current_span = Span.new({
+        :s => @id,      # Span ID
+        :n => name,     # Span name
+        :ts => ts_now,  # Timestamp
+        :ta => :ruby,   # Agent
+        :data => kvs,   # Data
+        :f => { :e => ::Instana.agent.report_pid, :h => ::Instana.agent.agent_uuid } # Entity Source
+      })
+
+      # Handle potential incoming context
+      if incoming_context.empty?
+        # No incoming context. Set trace ID the same
+        # as this first span.
+        @current_span[:t] = @id
+      else
+        @id = incoming_context[:trace_id]
+        @current_span[:t] = incoming_context[:trace_id]
+        @current_span[:p] = incoming_context[:parent_id]
+      end
+
+      @spans.add(@current_span)
+    end
+
+    # Start a new span as a child of @current_span
+    #
+    # @param name [String] the name of the span to start
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def new_span(name, kvs)
+      return unless @current_span
+
+      new_span = Span.new({
+        :s => generate_id,          # Span ID
+        :t => @id,                  # Trace ID (same as :s for root span)
+        :p => @current_span[:s],    # Parent ID
+        :n => name,                 # Span name
+        :ts => ts_now,              # Timestamp
+        :ta => :ruby,               # Agent
+        :data => kvs,               # Data
+        :f => { :e => Process.pid, :h => :agent_id } # Entity Source
+      })
+      new_span.parent = @current_span
+      @spans.add(new_span)
+      @current_span = new_span
+    end
+
+    # Add KVs to the current span
+    #
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def add_info(kvs)
+      @current_span[:data].merge!(kvs)
+    end
+
+    # Log an error into the current span
+    #
+    # @param e [Exception] Add exception to the current span
+    #
+    def add_error(e)
+      @current_span[:error] = true
+    end
+
+    # Close out the current span and set the parent as
+    # the current span
+    #
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def end_span(kvs = {})
+      @current_span[:d] = ts_now - @current_span[:ts]
+      add_info(kvs) unless kvs.empty?
+      @current_span = @current_span.parent unless @current_span.is_root?
+    end
+
+    # Closes out the final span in this trace and runs any finalizer
+    # steps required.
+    # This should be called only on the root span to end the trace.
+    #
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def finish(kvs = {})
+      end_span(kvs)
+    end
+
+    # Indicates whether all seems ok with this
+    # trace in it's current state.  Should be only
+    # called on finished traces.
+    #
+    # @return [Boolean] true or false on whether this trace is valid
+    #
+    def valid?
+      # TODO
+      true
+    end
+
+    # Searches the set of spans and indicates if there
+    # is an error logged in one of them.
+    #
+    # @return [Boolean] true or false indicating the presence
+    #   of an error
+    #
+    def has_error?
+      @spans.each do |s|
+        if s.key?(:error)
+          return s[:error]
+        end
+      end
+      false
+    end
+
+    # Get the ID of the current span for this trace.
+    # Used often to place in HTTP response headers.
+    #
+    # @return [Integer] a random 64bit integer
+    #
+    def current_span_id
+      @current_span.id
+    end
+
+    private
+
+    # Get the current time in milliseconds
+    #
+    # @return [Integer] the current time in milliseconds
+    #
+    def ts_now
+      (Time.now.to_f * 1000).floor
+    end
+
+    # Generate a random 64bit ID
+    #
+    # @return [Integer] a random 64bit integer
+    #
+    def generate_id
+      rand(2**32..2**64-1)
+    end
+  end
+end

data/lib/instana/version.rb

@@ -1,3 +1,3 @@
 module Instana
-  VERSION = "0.8.6"
+  VERSION = "0.9.0-slywolf3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: instana
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.9.0.pre.slywolf3
 platform: ruby
 authors:
 - Peter Giacomo Lombardo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-18 00:00:00.000000000 Z
+date: 2016-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- examples/tracing.rb
 - instana.gemspec
 - lib/instana.rb
 - lib/instana/agent.rb
@@ -130,6 +131,15 @@ files:
 - lib/instana/collectors/memory.rb
 - lib/instana/collectors/thread.rb
 - lib/instana/config.rb
+- lib/instana/instrumentation.rb
+- lib/instana/instrumentation/net-http.rb
+- lib/instana/instrumentation/rack.rb
+- lib/instana/rack.rb
+- lib/instana/thread_local.rb
+- lib/instana/tracer.rb
+- lib/instana/tracing/processor.rb
+- lib/instana/tracing/span.rb
+- lib/instana/tracing/trace.rb
 - lib/instana/util.rb
 - lib/instana/version.rb
 homepage: https://www.instana.com/
@@ -146,9 +156,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.1