instana 0.12.1 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eaaf893ffa35a79234320530e0d0d6d0631fb37e
-  data.tar.gz: 47ef832a84ff8e5746eb459cd905400742a9d80e
+  metadata.gz: fff8c1b1ed4764301a7f1a45dec8973df279b2d8
+  data.tar.gz: 8947536ba2a71f9916712d55980f77f57af8fde7
 SHA512:
-  metadata.gz: 77065dc8af02060b4196969bde7e7c05584d2a4544b32f3e177ccf49d97bc899145dc38d315c3a48b0fa8dd260930e95dfc1ecbf3b0ca9d0e262ec8a27069996
-  data.tar.gz: cc288b3c9b9954b10bb4b1bf4d63dfb37c31b6d8e8f0847aa8ef9224b1e5022858bd0905bc00d61bca5c678edd6c9c5c752cf7df08f26611bb6e23230efd4578
+  metadata.gz: 1626e65166c81355c55105db86179e22c8cf9a1ae7ee7292e17574015f0acf2590eb0ed06b667d20d6d1294bd2d79eddaef584951119fc750880950401caa2ff
+  data.tar.gz: 18c6581dbaece4419c1fd6edb59e4fabd30efab3789c24bc0b006420c3bce83f774ae4a239a37dc47b7c8ea1d0e99bf2f981c59d692b39b0e4ac00870010820e

data/Configuration.md

@@ -1,5 +1,76 @@
 # Configuration
 
+## Enabling/Disabling Components
+
+Individual components can be enabled and disabled with a local config.
+
+To disable a single component in the gem, you can disable a single component with the following code:
+
+```Ruby
+::Instana.config[:metrics][:gc][:enabled] = false
+```
+Current metric components are `:gc`, `:memory` and `:thread`.
+
+Instrumentation can be disabled as:
+
+```Ruby
+::Instana.config[:excon][:enabled] = false
+::Instana.config[:rack][:enabled] = false
+```
+
+## Rack Middleware
+
+This gem will detect and automagically insert the Instana Rack middleware into the middleware stack when a [supported framework](https://instana.atlassian.net/wiki/display/DOCS/Ruby) is present.  We are currently adding support for more frameworks.  If you are using a yet to be instrumented framework, you can insert the Instana Rack middleware with the following:
+
+```Ruby
+require "instana/rack"
+config.middleware.use ::Instana::Rack
+```
+
+...or whatever specific middleware call is appropriate for your framework.
+
+
+## Managing the Agent Background Thread
+
+This agent spawns a lightweight background thread to periodically collect and report metrics and traces.  Be default, this uses a standard Ruby thread.  If you wish to have greater control and potentially boot the agent reporting manually in an alternative thread system (such as actor based threads), you can do so with the following:
+
+```Ruby
+gem "instana", :require => "instana/setup"
+```
+
+...then in the background thread of your choice simply call:
+
+```Ruby
+::Instana.agent.start
+```
+
+Note that this call is blocking.  It kicks off a loop of timers that periodically collects and reports metrics and trace data.  This should only be called from inside an already initialized background thread:
+
+```Ruby
+Thread.new do
+  ::Instana.agent.start
+end
+```
+
+### Caveat
+
+In the case of forking webservers such as Unicorn or Puma in clustered mode, the agent detects the pid change and re-spawns the background thread.  If you are managing the background thread yourself with the steps above _and_ you are using a forking webserver (or anything else that may fork the original process), you should also do the following.
+
+When a fork is detected, the agent handles the re-initialization and then calls `::Agent.instana.spawn_background_thread`.  This by default uses the standard `Thread.new`.  If you wish to control this, you should override this method by re-defining that method.  For example:
+
+```ruby
+# This method can be overridden with the following:
+#
+module Instana
+  class Agent
+    def spawn_background_thread
+      # start/identify custom thread
+      ::Instana.agent.start
+    end
+  end
+end
+```
+
 ## Logging
 
 The Instana logger is a standard Ruby logger that logs debug, warn, info
@@ -16,6 +87,7 @@ what extra debug info it reports.  It allows for:
 * `:agent` - shows all agent state related debug messages
 * `:agent_comm` - outputs all request/response pairs to and from the
   host agent
+* `:trace` - outputs debug messages related to tracing and trace management
 
 Log messages can be generated for these channels using:
 
@@ -27,7 +99,7 @@ Log messages can be generated for these channels using:
 To set the debug log level:
 
 ```Ruby
-::Instana.logger.debug_level = [:agent, :agent_comm]
+::Instana.logger.debug_level = [:agent, :agent_comm, :trace]
 # or
 ::Instana.logger.debug_level = [:agent_comm]
 # or

data/Gemfile

@@ -13,9 +13,15 @@ group :development, :test do
   gem "cuba"
   gem "roda"
 
+  # HTTP Clients
+  gem 'rest-client'
+
   # Webservers
   gem "puma"
 
+  # HTTP Clients
+  gem 'excon'
+
   # Rack v2 dropped support for Ruby 2.2 and higher.
   if RUBY_VERSION < '2.2'
     gem 'rack', '< 2.0'

data/README.md

@@ -17,12 +17,12 @@ This gem supports Ruby versions 2.0 or greater.
 
 Any and all feedback is welcome.  Happy Ruby visibility.
 
-![rails](https://s3.amazonaws.com/instana/rails-logo.jpg?1)
-![roda](https://s3.amazonaws.com/instana/roda-logo.png?1)
-![cuba](https://s3.amazonaws.com/instana/cuba-logo.png?1)
-![sinatra](https://s3.amazonaws.com/instana/sinatra-logo.png?1)
-![padrino](https://s3.amazonaws.com/instana/padrino-logo.png?1)
-![rack](https://s3.amazonaws.com/instana/rack-logo.png?1)
+[![rails](https://s3.amazonaws.com/instana/rails-logo.jpg?1)](http://rubyonrails.org/)
+[![roda](https://s3.amazonaws.com/instana/roda-logo.png?1)](http://roda.jeremyevans.net/)
+[![cuba](https://s3.amazonaws.com/instana/cuba-logo.png?1)](http://cuba.is/)
+[![sinatra](https://s3.amazonaws.com/instana/sinatra-logo.png?1)](http://www.sinatrarb.com/)
+[![padrino](https://s3.amazonaws.com/instana/padrino-logo.png?1)](http://padrinorb.com/)
+[![rack](https://s3.amazonaws.com/instana/rack-logo.png?1)](https://rack.github.io/)
 
 ## Installation
 
@@ -46,70 +46,7 @@ The instana gem is a zero configuration tool that will automatically collect key
 
 ## Configuration
 
-Although the gem has no configuration required for out of the box metrics and tracing, components can be configured if needed.
-
-### Agent Reporting
-
-This agent spawns a lightweight background thread to periodically collect and report metrics and traces.  Be default, this uses a standard Ruby thread.  If you wish to have greater control and potentially boot the agent reporting manually in an alternative thread system (such as actor based threads), you can do so with the following:
-
-```Ruby
-gem "instana", :require => "instana/setup"
-```
-
-...then in the background thread of your choice simply call:
-
-```Ruby
-::Instana.agent.start
-```
-
-Note that this call is blocking.  It kicks off a loop of timers that periodically collects and reports metrics and trace data.  This should only be called from inside an already initialized background thread:
-
-```Ruby
-Thread.new do
-  ::Instana.agent.start
-end
-```
-
-#### Caveat
-
-In the case of forking webservers such as Unicorn or Puma in clustered mode, the agent detects the pid change and re-spawns the background thread.  If you are managing the background thread yourself with the steps above _and_ you are using a forking webserver (or anything else that may fork the original process), you should also do the following.
-
-When a fork is detected, the agent handles the re-initialization and then calls `::Agent.instana.spawn_background_thread`.  This by default uses the standard `Thread.new`.  If you wish to control this, you should override this method by re-defining that method.  For example:
-
-```ruby
-# This method can be overridden with the following:
-#
-module Instana
-  class Agent
-    def spawn_background_thread
-      # start/identify custom thread
-      ::Instana.agent.start
-    end
-  end
-end
-```
-
-### Components
-
-Individual components can be disabled with a local config.
-
-To disable a single component in the gem, you can disable a single component with the following code:
-
-```Ruby
-::Instana.config[:metrics][:gc][:enabled] = false
-```
-Current components are `:gc`, `:memory` and `:thread`.
-
-### Rack Middleware
-
-This gem will detect and automagically insert the Instana Rack middleware into the middleware stack when a [supported framework](https://instana.atlassian.net/wiki/display/DOCS/Ruby) is present.  We are currently adding support for more frameworks.  If you are using a yet to be instrumented framework, you can insert the Instana Rack middleware with the following:
-
-```Ruby
-require "instana/rack"
-config.middleware.use ::Instana::Rack
-```
-
-...or whatever specific middleware call is appropriate for your framework.
+Although the gem has no configuration required for out of the box metrics and tracing, components can be configured if needed.  See [Configuration.md](https://github.com/instana/ruby-sensor/blob/master/Configuration.md).
 
 ## Documentation
 

data/lib/instana.rb

@@ -3,7 +3,7 @@ require "instana/setup"
 # Boot the instana agent background thread.  If you wish to have greater
 # control on the where and which thread this is run in, instead use
 #
-#   gem "instana", :require "instana/setup"
+#   gem "instana", :require => "instana/setup"
 #
 # ...and manually call ::Instana.agent.start in the thread
 # of your choice

data/lib/instana/collectors.rb

@@ -28,7 +28,7 @@ module Instana
         end
 
         # Report all the collected goodies
-        ::Instana.agent.report_entity_data(payload)
+        ::Instana.agent.report_entity_data(payload) unless ENV['INSTANA_GEM_TEST']
       end
 
     end

data/lib/instana/config.rb

@@ -9,6 +9,9 @@ module Instana
       @config[:metrics][:gc]     = { :enabled => true }
       @config[:metrics][:memory] = { :enabled => true }
       @config[:metrics][:thread] = { :enabled => true }
+
+      # HTTP Clients
+      @config[:excon] = { :enabled => true }
     end
 
     def [](key)

data/lib/instana/instrumentation/excon.rb

@@ -0,0 +1,64 @@
+if defined?(::Excon) && ::Instana.config[:excon][:enabled]
+  module Instana
+    module Instrumentation
+      class Excon < ::Excon::Middleware::Base
+        def request_call(datum)
+          return @stack.request_call(datum) unless ::Instana.tracer.tracing?
+
+          payload = { :http => {} }
+          path = datum[:path].split('?').first
+          payload[:http][:url] = "#{datum[:connection].instance_variable_get(:@socket_key)}#{path}"
+          payload[:http][:method] = datum[:method] if datum.key?(:method)
+
+          if datum[:pipeline] == true
+            # Pass the context along in the datum so we get back on response
+            # and can close out the async span
+            datum[:instana_context] = ::Instana.tracer.log_async_entry(:excon, payload)
+          else
+            ::Instana.tracer.log_entry(:excon, payload)
+          end
+
+          # Set request headers; encode IDs as hexadecimal strings
+          datum[:headers]['X-Instana-T'] = ::Instana.tracer.trace_id_header
+          datum[:headers]['X-Instana-S'] = ::Instana.tracer.span_id_header
+
+          @stack.request_call(datum)
+        end
+
+        def error_call(datum)
+          return @stack.error_call(datum) unless ::Instana.tracer.tracing?
+
+          if datum[:pipeline] == true
+            ::Instana.tracer.log_async_error(datum[:error], datum[:instana_context])
+          else
+            ::Instana.tracer.log_error(datum[:error])
+          end
+          @stack.error_call(datum)
+        end
+
+        def response_call(datum)
+          return @stack.response_call(datum) unless ::Instana.tracer.tracing?
+
+          result =  @stack.response_call(datum)
+
+          status = datum[:status]
+          if !status && datum.key?(:response) && datum[:response].is_a?(Hash)
+            status = datum[:response][:status]
+          end
+
+          if datum[:pipeline] == true
+            # Pickup context of this async span from datum[:instana_id]
+            ::Instana.tracer.log_async_exit(:excon, { :http => {:status => status } }, datum[:instana_context])
+          else
+            ::Instana.tracer.log_exit(:excon, { :http => {:status => status } })
+          end
+          result
+        end
+      end
+    end
+  end
+
+  ::Instana.logger.warn "Instrumenting excon"
+  ::Excon.defaults[:middlewares].unshift(::Instana::Instrumentation::Excon)
+end
+

data/lib/instana/instrumentation/rack.rb

@@ -19,7 +19,7 @@ module Instana
       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[:span_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
 

data/lib/instana/instrumentation/rest-client.rb

@@ -0,0 +1,34 @@
+module Instana
+  module Instrumentation
+    module RestClientRequest
+      def self.included(klass)
+        if klass.method_defined?(:execute)
+          klass.class_eval do
+            alias execute_without_instana execute
+            alias execute execute_with_instana
+          end
+        end
+      end
+
+      def execute_with_instana & block
+        # Since RestClient uses net/http under the covers, we just
+        # provide span visibility here.  HTTP related KVs are reported
+        # in the Net::HTTP instrumentation
+        ::Instana.tracer.log_entry(:'rest-client')
+
+        execute_without_instana(&block)
+      rescue => e
+        ::Instana.tracer.log_error(e)
+        raise
+      ensure
+        ::Instana.tracer.log_exit(:'rest-client')
+      end
+
+    end
+  end
+end
+
+if defined?(::RestClient::Request)
+  ::Instana.logger.warn "Instrumenting RestClient"
+  ::RestClient::Request.send(:include, ::Instana::Instrumentation::RestClientRequest)
+end

data/lib/instana/logger.rb

@@ -2,7 +2,7 @@ require "logger"
 
 module Instana
   class XLogger < Logger
-    LEVELS = [:agent, :agent_comm].freeze
+    LEVELS = [:agent, :agent_comm, :trace].freeze
     STAMP = "Instana: ".freeze
 
     def initialize(*args)
@@ -12,6 +12,12 @@ module Instana
       super(*args)
     end
 
+    # Sets the debug level for this logger.  The debug level is broken up into various
+    # sub-levels as defined in LEVELS.
+    #
+    # To use:
+    # ::Instana.logger.debug_level = [:agent_comm, :trace]
+    #
     def debug_level=(levels)
       LEVELS.each do |l|
         instance_variable_set("@level_#{l}", false)
@@ -34,6 +40,11 @@ module Instana
       self.debug(msg)
     end
 
+    def trace(msg)
+      return unless @level_trace
+      self.debug(msg)
+    end
+
     def error(msg)
       super(STAMP + msg)
     end

data/lib/instana/tracer.rb

@@ -9,7 +9,7 @@ module Instana
     thread_local :current_trace
 
     #######################################
-    # Tracing blocks helper methods
+    # Tracing blocks API methods
     #######################################
 
     # Will start a new trace or continue an on-going one (such as
@@ -18,9 +18,9 @@ module Instana
     # @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:
+    #   minimum, it should specify :trace_id and :span_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)
+    #     :span_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)
@@ -35,6 +35,12 @@ module Instana
 
     # Trace a block of code within the context of the exiting trace
     #
+    # Example usage:
+    #
+    # ::Instana.tracer.trace(:dbwork, { :db_name => @db.name }) do
+    #   @db.select(1)
+    # end
+    #
     # @param name [String] the name of the span to start
     # @param kvs [Hash] list of key values to be reported in this new span
     #
@@ -50,7 +56,7 @@ module Instana
     end
 
     #######################################
-    # Lower level tracing methods
+    # Lower level tracing API methods
     #######################################
 
     # Will start a new trace or continue an on-going one (such as
@@ -59,9 +65,9 @@ module Instana
     # @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:
+    #   minimum, it should specify :trace_id and :span_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)
+    #     :span_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 = {})
@@ -98,7 +104,7 @@ module Instana
       self.current_trace.add_error(e)
     end
 
-    # Will close out the current span
+    # Closes 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.
@@ -124,10 +130,109 @@ module Instana
       return unless tracing?
 
       self.current_trace.finish(kvs)
-      Instana.processor.add(self.current_trace)
+
+      if !self.current_trace.has_async? ||
+          (self.current_trace.has_async? && self.current_trace.complete?)
+        Instana.processor.add(self.current_trace)
+      else
+        # This trace still has outstanding/uncompleted asynchronous spans.
+        # Put it in the staging queue until the async span closes out or
+        # 5 minutes has passed.  Whichever comes first.
+        Instana.processor.stage(self.current_trace)
+      end
       self.current_trace = nil
     end
 
+    ###########################################################################
+    # Asynchronous API methods
+    ###########################################################################
+
+    # Starts a new asynchronous span on the current trace.
+    #
+    # @param name [String] the name of the span to create
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    # @return [Hash] the context: Trace ID and Span ID in the form of
+    #   :trace_id => 12345
+    #   :span_id => 12345
+    #
+    def log_async_entry(name, kvs, incoming_context = nil)
+      return unless tracing?
+      self.current_trace.new_async_span(name, kvs)
+    end
+
+    # Add info to an asynchronous span
+    #
+    # @param kvs [Hash] list of key values to be reported in the span
+    # @param t_context [Hash] the Trace ID and Span ID in the form of
+    #   :trace_id => 12345
+    #   :span_id => 12345
+    #   This can be retrieved by using ::Instana.tracer.context
+    #
+    def log_async_info(kvs, ids)
+      # Asynchronous spans can persist longer than the parent
+      # trace.  With the trace ID, we check the current trace
+      # but otherwise, we search staged traces.
+
+      if tracing? && self.current_trace.id == ids[:trace_id]
+        self.current_trace.add_async_info(kvs, ids)
+      else
+        trace = ::Instana.processor.staged_trace(ids)
+        trace.add_async_info(kvs, ids)
+      end
+    end
+
+    # Add an error to an asynchronous span
+    #
+    # @param e [Exception] Add exception to the current span
+    # @param ids [Hash] the Trace ID and Span ID in the form of
+    #   :trace_id => 12345
+    #   :span_id => 12345
+    #
+    def log_async_error(e, ids)
+      # Asynchronous spans can persist longer than the parent
+      # trace.  With the trace ID, we check the current trace
+      # but otherwise, we search staged traces.
+
+      if tracing? && self.current_trace.id == ids[:trace_id]
+        self.current_trace.add_async_error(e, ids)
+      else
+        trace = ::Instana.processor.staged_trace(ids)
+        trace.add_async_error(e, ids)
+      end
+    end
+
+    # Closes out an asynchronous span
+    #
+    # @param name [String] the name of the async span to exit (close out)
+    # @param kvs [Hash] list of key values to be reported in the span
+    # @param ids [Hash] the Trace ID and Span ID in the form of
+    #   :trace_id => 12345
+    #   :span_id => 12345
+    #
+    def log_async_exit(name, kvs, ids)
+      # An asynchronous span can end after the current trace has
+      # already completed so we make sure that we end the span
+      # on the right trace.
+
+      if tracing? && (self.current_trace.id == ids[:trace_id])
+        self.current_trace.end_async_span(kvs, ids)
+      else
+        # Different trace from current so find the staged trace
+        # and close out the span on it.
+        trace = ::Instana.processor.staged_trace(ids)
+        if trace
+          trace.end_async_span(kvs, ids)
+        else
+          ::Instana.logger.debug "log_async_exit: Couldn't find staged trace. #{ids.inspect}"
+        end
+      end
+    end
+
+    ###########################################################################
+    # Helper methods
+    ###########################################################################
+
     # Indicates if we're are currently in the process of
     # collecting a trace.  This is false when the host agent isn
     # available.
@@ -141,6 +246,31 @@ module Instana
       self.current_trace ? true : false
     end
 
+    # Retrieve the current context of the tracer.
+    #
+    def context
+      { :trace_id => self.current_trace.id,
+        :span_id => self.current_trace.current_span_id }
+    end
+
+    # Take the current trace_id and convert it to a header compatible
+    # format.
+    #
+    # @return [String] a hexadecimal representation of the current trace ID
+    #
+    def trace_id_header
+      id_to_header(trace_id)
+    end
+
+    # Take the current span_id and convert it to a header compatible
+    # formate.
+    #
+    # @return [String] a hexadecimal representation of the current span ID
+    #
+    def span_id_header
+      id_to_header(span_id)
+    end
+
     # Convert an ID to a value appropriate to pass in a header.
     #
     # @param id [Integer] the id to be converted

data/lib/instana/tracing/processor.rb

@@ -4,7 +4,20 @@ module Instana
   class Processor
 
     def initialize
+      # The main queue before being reported to the
+      # host agent.  Traces in this queue are complete
+      # and ready to be sent.
       @queue = Queue.new
+
+      # The staging queue that holds traces that have completed
+      # but still have outstanding async spans.
+      # Traces that have been in this queue for more than
+      # 5 minutes are discarded.
+      @staging_queue = Set.new
+
+      # No access to the @staging_queue until this lock
+      # is taken.
+      @staging_lock = Mutex.new
     end
 
     # Adds a trace to the queue to be processed and
@@ -12,9 +25,41 @@ module Instana
     #
     # @param [Trace] the trace to be added to the queue
     def add(trace)
+      ::Instana.logger.trace("Queuing completed trace id: #{trace.id}")
       @queue.push(trace)
     end
 
+    # Adds a trace to the staging queue.
+    #
+    # @param [Trace] the trace to be added to the queue
+    def stage(trace)
+      ::Instana.logger.trace("Staging incomplete trace id: #{trace.id}")
+      @staging_queue.add(trace)
+    end
+
+    # This will run through the staged traces (if any) to find
+    # completed or timed out incompleted traces.  Completed traces will
+    # be added to the main @queue.  Timed out traces will be discarded
+    #
+    def process_staged
+      @staging_lock.synchronize {
+        if @staging_queue.size > 0
+          @staging_queue.delete_if do |t|
+            if t.complete?
+              ::Instana.logger.trace("Moving staged complete trace to main queue: #{t.id}")
+              add(t)
+              true
+            elsif t.discard?
+              ::Instana.logger.debug("Discarding trace with uncompleted async spans over 5 mins old. id: #{t.id}")
+              true
+            else
+              false
+            end
+          end
+        end
+      }
+    end
+
     ##
     # send
     #
@@ -27,20 +72,21 @@ module Instana
     #   - Prevent another run of the timer while this is running
     #
     def send
-      return if @queue.empty?
+      return if @queue.empty? || ENV['INSTANA_GEM_TEST']
 
       size = @queue.size
       if size > 100
         Instana.logger.debug "Trace queue is #{size}"
       end
 
-      ::Instana.agent.report_spans(queued_spans)
-    end
+      # Scan for any staged but incomplete traces that have now
+      # completed.
+      process_staged
 
-    # Get the number traces currently in the queue
-    #
-    def queue_count
-      @queue.size
+      # Retrieve all spans for queued traces
+      spans = queued_spans
+
+      ::Instana.agent.report_spans(spans)
     end
 
     # Retrieves all of the traces in @queue and returns
@@ -49,6 +95,8 @@ module Instana
     # Note that traces retrieved with this method are removed
     # entirely from the queue.
     #
+    # @return [Array] An array of [Span] or empty
+    #
     def queued_spans
       return [] if @queue.empty?
 
@@ -67,6 +115,8 @@ module Instana
     # Note that traces retrieved with this method are removed
     # entirely from the queue.
     #
+    # @return [Array] An array of [Trace] or empty
+    #
     def queued_traces
       return [] if @queue.empty?
 
@@ -78,16 +128,69 @@ module Instana
       traces
     end
 
-    # Removes all traces from the @queue.  Used in the
-    # test suite.
+    # Retrieves a all staged traces from the staging queue.  Staged traces
+    # are traces that have completed but may have outstanding
+    # asynchronous spans.
     #
-    def clear!
-      return [] if @queue.empty?
+    # @return [Array]
+    #
+    def staged_traces
+      traces = nil
+      @staging_lock.synchronize {
+        traces = @staging_queue.to_a
+        @staging_queue.clear
+      }
+      traces
+    end
 
+    # Retrieves a single staged trace from the staging queue.  Staged traces
+    # are traces that have completed but may have outstanding
+    # asynchronous spans.
+    #
+    # @param ids [Hash] the Trace ID and Span ID in the form of
+    #   :trace_id => 12345
+    #   :span_id => 12345
+    #
+    def staged_trace(ids)
+      candidate = nil
+      @staging_lock.synchronize {
+        @staging_queue.each do |trace|
+          if trace.id == ids[:trace_id]
+            candidate = trace
+          end
+        end
+      }
+      unless candidate
+        ::Instana.logger.trace("Couldn't find staged trace with trace_id: #{ids[:trace_id]}")
+      end
+      candidate
+    end
+
+    # Get the number traces currently in the queue
+    #
+    # @return [Integer] the queue size
+    #
+    def queue_count
+      @queue.size
+    end
+
+    # Get the number traces currently in the staging queue
+    #
+    # @return [Integer] the queue size
+    #
+    def staged_count
+      @staging_queue.size
+    end
+
+    # Removes all traces from the @queue and @staging_queue.  Used in the
+    # test suite to reset state.
+    #
+    def clear!
       until @queue.empty? do
         # Non-blocking pop; ignore exception
         @queue.pop(true) rescue nil
       end
+      @staging_queue.clear
     end
   end
 end

data/lib/instana/tracing/span.rb

@@ -14,6 +14,18 @@ module Instana
       @data[:p]
     end
 
+    def name
+      if custom?
+        @data[:data][:sdk][:name]
+      else
+        @data[:n]
+      end
+    end
+
+    def duration
+      @data[:d]
+    end
+
     def is_root?
       @data[:s] == @data[:t]
     end

data/lib/instana/tracing/trace.rb

@@ -1,6 +1,6 @@
 module Instana
   class Trace
-    REGISTERED_SPANS = [ :rack, :'net-http' ]
+    REGISTERED_SPANS = [ :rack, :'net-http', :excon ]
 
     # @return [Integer] the ID for this trace
     attr_reader :id
@@ -14,9 +14,9 @@ module Instana
     # @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:
+    #   minimum, it should specify :trace_id and :span_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)
+    #     :span_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 = {})
@@ -30,6 +30,13 @@ module Instana
       # Generate a random 64bit ID for this trace
       @id = generate_id
 
+      # Indicates the time when this trace was started.  Used to timeout
+      # traces that have asynchronous spans that never close out.
+      @started_at = Time.now
+
+      # Indicates if this trace has any asynchronous spans within it
+      @has_async = false
+
       # This is a new trace so open the first span with the proper
       # root span IDs.
       @current_span = Span.new({
@@ -41,7 +48,7 @@ module Instana
 
       # Check for custom tracing
       if !REGISTERED_SPANS.include?(name.to_sym)
-        configure_custom_span(name, kvs)
+        configure_custom_span(nil, name, kvs)
       else
         @current_span[:n]    = name.to_sym
         @current_span[:data] = kvs
@@ -55,7 +62,7 @@ module Instana
       else
         @id = incoming_context[:trace_id]
         @current_span[:t] = incoming_context[:trace_id]
-        @current_span[:p] = incoming_context[:parent_id]
+        @current_span[:p] = incoming_context[:span_id]
       end
 
       @spans.add(@current_span)
@@ -72,7 +79,7 @@ module Instana
       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
+        :p => @current_span.id,     # Parent ID
         :ts => ts_now,              # Timestamp
         :ta => :ruby,               # Agent
         :f => { :e => Process.pid, :h => :agent_id } # Entity Source
@@ -84,7 +91,7 @@ module Instana
 
       # Check for custom tracing
       if !REGISTERED_SPANS.include?(name.to_sym)
-        configure_custom_span(name, kvs)
+        configure_custom_span(nil, name, kvs)
       else
         @current_span[:n]    = name.to_sym
         @current_span[:data] = kvs
@@ -93,17 +100,28 @@ module Instana
 
     # Add KVs to the current span
     #
+    # @param span [Span] the span to add kvs to or otherwise the current span
     # @param kvs [Hash] list of key values to be reported in the span
     #
-    def add_info(kvs)
-      if @current_span.custom?
-        if @current_span[:data][:sdk].key?(:custom)
-          @current_span[:data][:sdk][:custom].merge!(kvs)
+    def add_info(kvs, span = nil)
+      span ||= @current_span
+
+      if span.custom?
+        if span[:data][:sdk].key?(:custom)
+          span[:data][:sdk][:custom].merge!(kvs)
         else
-          @current_span[:data][:sdk][:custom] = kvs
+          span[:data][:sdk][:custom] = kvs
         end
       else
-        @current_span[:data].merge!(kvs)
+        kvs.each_pair do |k,v|
+          if !span[:data].key?(k)
+            span[:data][k] = v
+          elsif v.is_a?(Hash) && span[:data][k].is_a?(Hash)
+            span[:data][k].merge!(v)
+          else
+            span[:data][k] = v
+          end
+        end
       end
     end
 
@@ -111,26 +129,16 @@ module Instana
     #
     # @param e [Exception] Add exception to the current span
     #
-    def add_error(e)
-      @current_span[:error] = true
+    def add_error(e, span = nil)
+      span ||= @current_span
+
+      span[:error] = true
 
-      if @current_span.key?(:ec)
-        @current_span[:ec] = @current_span[:ec] + 1
+      if span.key?(:ec)
+        span[:ec] = span[:ec] + 1
       else
-        @current_span[:ec] = 1
+        span[:ec] = 1
       end
-
-      #if e.backtrace && e.backtrace.is_a?(Array)
-      #  @current_span[:stack] = []
-      #  e.backtrace.each do |x|
-      #    file, line, method = x.split(':')
-      #    @current_span[:stack] << {
-      #      :f => file,
-      #      :n => line
-      #      #:m => method
-      #    }
-      #  end
-      #end
     end
 
     # Close out the current span and set the parent as
@@ -154,17 +162,124 @@ module Instana
       end_span(kvs)
     end
 
-    # Indicates whether all seems ok with this
-    # trace in it's current state.  Should be only
-    # called on finished traces.
+    ###########################################################################
+    # Asynchronous Methods
+    ###########################################################################
+
+    # Start a new asynchronous span
+    #
+    # The major differentiator between this method and simple new_span is that
+    # this method doesn't affect @current_trace and instead returns an
+    # ID pair that can be used later to close out the created async 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_async_span(name, kvs)
+
+      new_span = Span.new({
+        :s => generate_id,          # Span ID
+        :t => @id,                  # Trace ID (same as :s for root span)
+        :p => @current_span.id,     # Parent ID
+        :ts => ts_now,              # Timestamp
+        :ta => :ruby,               # Agent
+        :async => true,             # Asynchonous
+        :f => { :e => Process.pid, :h => :agent_id } # Entity Source
+      })
+
+      new_span.parent = @current_span
+      @has_async = true
+
+      # Check for custom tracing
+      if !REGISTERED_SPANS.include?(name.to_sym)
+        configure_custom_span(new_span, name, kvs)
+      else
+        new_span[:n]    = name.to_sym
+        new_span[:data] = kvs
+      end
+
+      # Add the new span to the span collection
+      @spans.add(new_span)
+
+      { :trace_id => new_span[:t], :span_id => new_span.id }
+    end
+
+    # Log info into an asynchronous span
+    #
+    # @param kvs [Hash] list of key values to be reported in the span
+    # @param span [Span] the span to configure
+    #
+    def add_async_info(kvs, ids)
+      @spans.each do |span|
+        if span.id == ids[:span_id]
+          add_info(kvs, span)
+        end
+      end
+    end
+
+    # Log an error into an asynchronous span
+    #
+    # @param span [Span] the span to configure
+    # @param e [Exception] Add exception to the current span
+    #
+    def add_async_error(e, ids)
+      @spans.each do |span|
+        add_error(e, span) if span.id == ids[:span_id]
+      end
+    end
+
+    # End an asynchronous span
+    #
+    # @param name [Symbol] the name of the span
+    # @param kvs [Hash] list of key values to be reported in the span
+    # @param ids [Hash] the Trace ID and Span ID in the form of
+    #   :trace_id => 12345
+    #   :span_id => 12345
+    #
+    def end_async_span(kvs = {}, ids)
+      @spans.each do |span|
+        if span.id == ids[:span_id]
+          span[:d] = ts_now - span[:ts]
+          add_info(kvs, span) unless kvs.empty?
+        end
+      end
+    end
+
+    ###########################################################################
+    # Validator and Helper Methods
+    ###########################################################################
+
+    # 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
+      @spans.each do |span|
+        unless span.key?(:d)
+          return false
+        end
+      end
+    end
+
+    # Indicates if every span of this trace has completed.  Useful when
+    # asynchronous spans potentially could run longer than the parent trace.
+    #
+    def complete?
+      @spans.each do |span|
+        if !span.duration
+          return false
+        end
+      end
       true
     end
 
+    # Indicates whether this trace has any asynchronous spans.
+    #
+    def has_async?
+      @has_async
+    end
+
     # Searches the set of spans and indicates if there
     # is an error logged in one of them.
     #
@@ -191,26 +306,84 @@ module Instana
       @current_span.id
     end
 
+    # Get the name of the current span.  Supports both registered spans
+    # and custom sdk spans.
+    #
+    def current_span_name
+      @current_span.name
+    end
+
+    # Check if the current span has the name value of <name>
+    #
+    # @param name [Symbol] The name to be checked against.
+    #
+    # @return [Boolean]
+    #
+    def current_span_name?(name)
+      @current_span.name == name
+    end
+
+    # For traces that have asynchronous spans, this method indicates
+    # whether we have hit the timeout on waiting for those async
+    # spans to close out.
+    #
+    # @return [Boolean]
+    #
+    def discard?
+      # If this trace has async spans that have not closed
+      # out in 5 minutes, then it's discarded.
+      if has_async? && (Time.now.to_i - @started_at.to_i) > 601
+        return true
+      end
+      false
+    end
+
     private
 
     # Configure @current_span to be a custom span per the
     # SDK generic span type.
     #
-    def configure_custom_span(name, kvs = {})
-      @current_span[:n] = :sdk
-      @current_span[:data] = { :sdk => { :name => name.to_sym } }
-      @current_span[:data][:sdk][:type] = kvs.key?(:type) ? kvs[:type] : :local
+    # @param span [Span] the span to configure or nil
+    # @param name [String] name of the span
+    # @param kvs [Hash] list of key values to be reported in the span
+    #
+    def configure_custom_span(span, name, kvs = {})
+      span ||= @current_span
+
+      span[:n] = :sdk
+      span[:data] = { :sdk => { :name => name.to_sym } }
+      span[:data][:sdk][:type] = kvs.key?(:type) ? kvs[:type] : :local
 
       if kvs.key?(:arguments)
-        @current_span[:data][:sdk][:arguments] = kvs[:arguments]
+        span[:data][:sdk][:arguments] = kvs[:arguments]
       end
 
       if kvs.key?(:return)
-        @current_span[:data][:sdk][:return] = kvs[:return]
+        span[:data][:sdk][:return] = kvs[:return]
+      end
+      span[:data][:sdk][:custom] = kvs unless kvs.empty?
+      #span[:data][:sdk][:custom][:tags] = {}
+      #span[:data][:sdk][:custom][:logs] = {}
+    end
+
+    # Locates the span in the current_trace or
+    # in the staging queue.  This is generally used by async
+    # operations.
+    #
+    # @param ids [Hash] the Trace ID and Span ID in the form of
+    #   :trace_id => 12345
+    #   :span_id => 12345
+    #
+    # @return [Span]
+    #
+    def find_span(ids)
+      if ids[:trace_id] == @id
+        @spans.each do |s|
+          return s if s[:s] == ids[:span_id]
+        end
+      else
+        #::Instana.processor.staged_trace(
       end
-      @current_span[:data][:sdk][:custom] = kvs unless kvs.empty?
-      #@current_span[:data][:sdk][:custom][:tags] = {}
-      #@current_span[:data][:sdk][:custom][:logs] = {}
     end
 
     # Get the current time in milliseconds

data/lib/instana/util.rb

@@ -1,52 +1,70 @@
 module Instana
   module Util
-    ##
-    # enforce_deltas
-    #
-    # Take two hashes, and make sure candidate does not have
-    # any of the same values as `last`.  We only report
-    # when values change.
-    #
-    # Note this is not recursive, so only pass in the single
-    # hashes that you want delta reporting with.
-    #
-    def self.enforce_deltas(candidate, last)
-      return unless last.is_a?(Hash)
-
-      candidate.each do |k,v|
-        if candidate[k] == last[k]
-          candidate.delete(k)
+    class << self
+      # An agnostic approach to method aliasing.
+      #
+      # @param klass [Object] The class or module that holds the method to be alias'd.
+      # @param method [Symbol] The name of the method to be aliased.
+      #
+      def method_alias(klass, method)
+        if klass.method_defined?(method.to_sym)
+
+          with = "#{method}_with_instana"
+          without = "#{method}_without_instana"
+
+          klass.class_eval do
+            alias_method without, method.to_s
+            alias_method method.to_s, with
+          end
+        else
+          ::Instana.logger.debug "No such method (#{method}) to alias on #{klass}"
         end
       end
-      candidate
-    end
-  end
 
-  ##
-  # Debugging helper method
-  #
-  def self.pry!
-    # Only valid for development or test environments
-    #env = ENV['RACK_ENV'] || ENV['RAILS_ENV']
-    #return unless %w(development, test).include? env
-
-    if RUBY_VERSION > '1.8.7'
-      require 'pry-byebug'
-
-      if defined?(PryByebug)
-        Pry.commands.alias_command 'c', 'continue'
-        Pry.commands.alias_command 's', 'step'
-        Pry.commands.alias_command 'n', 'next'
-        Pry.commands.alias_command 'f', 'finish'
-
-        Pry::Commands.command(/^$/, 'repeat last command') do
-          _pry_.run_command Pry.history.to_a.last
+      # Take two hashes, and make sure candidate does not have
+      # any of the same values as `last`.  We only report
+      # when values change.
+      #
+      # Note this is not recursive, so only pass in the single
+      # hashes that you want delta reporting with.
+      #
+      def enforce_deltas(candidate, last)
+        return unless last.is_a?(Hash)
+
+        candidate.each do |k,v|
+          if candidate[k] == last[k]
+            candidate.delete(k)
+          end
         end
+        candidate
       end
 
-      binding.pry
-    else
-      require 'ruby-debug'; debugger
+      # Debugging helper method
+      #
+      def pry!
+        # Only valid for development or test environments
+        #env = ENV['RACK_ENV'] || ENV['RAILS_ENV']
+        #return unless %w(development, test).include? env
+
+        if RUBY_VERSION > '1.8.7'
+          require 'pry-byebug'
+
+          if defined?(PryByebug)
+            Pry.commands.alias_command 'c', 'continue'
+            Pry.commands.alias_command 's', 'step'
+            Pry.commands.alias_command 'n', 'next'
+            Pry.commands.alias_command 'f', 'finish'
+
+            Pry::Commands.command(/^$/, 'repeat last command') do
+              _pry_.run_command Pry.history.to_a.last
+            end
+          end
+
+          binding.pry
+        else
+          require 'ruby-debug'; debugger
+        end
+      end
     end
   end
 end

data/lib/instana/version.rb

@@ -1,3 +1,3 @@
 module Instana
-  VERSION = "0.12.1"
+  VERSION = "0.13.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: instana
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.1
 platform: ruby
 authors:
 - Peter Giacomo Lombardo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-02 00:00:00.000000000 Z
+date: 2016-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -140,8 +140,10 @@ files:
 - lib/instana/frameworks/roda.rb
 - lib/instana/frameworks/sinatra.rb
 - lib/instana/instrumentation.rb
+- lib/instana/instrumentation/excon.rb
 - lib/instana/instrumentation/net-http.rb
 - lib/instana/instrumentation/rack.rb
+- lib/instana/instrumentation/rest-client.rb
 - lib/instana/logger.rb
 - lib/instana/rack.rb
 - lib/instana/setup.rb