instana 0.15.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b08a1d3bea72c56da148e02e24c9095a49d4c0f6
-  data.tar.gz: efcbc529c115a5dba077b4e590528b32c98698ba
+  metadata.gz: cbc400b87081fe4c927cb2f437faf8597ac217bf
+  data.tar.gz: 247eb9b4db84239ebbf7ec934c5427f94a5b1771
 SHA512:
-  metadata.gz: 72c20b92c83aa59a7e0b21c5eb9127e696f782ddd7b077294adf9185469629e0f7922027e881dd52c717f1ac3c64929ffc04e1bcef2eb2893e59f94ddd2e0e67
-  data.tar.gz: 9d9cd6654f148a0142faeeab2ef9875bdfa2f9d31db700859a1c44e3d3f195c364c99fbc9a0f33342ce8ea4f07c9caf71cb1a63c7100e90f924f471d345cf154
+  metadata.gz: 9299e4b9ed9aaeabd40dd6c5df7f21b8a76e849b083a152e133b9d8f10e2e8c2787bc711cf5cae75ee9d9f4f2f624a8418bac1b38cf275ab1c1ad46045ccb42a
+  data.tar.gz: 38ea273e84533d1a9be4e3373a0962a44fa3bf8b96c8aa4937f466b77062995b168630bf146d79d8c21f0680beb26ead6ff0ae90b06c235f3f3f19cb6789e27c

data/Troubleshooting.md

@@ -0,0 +1,32 @@
+# Troubleshooting
+
+The Instana gem has been designed to be fully automatic in process metric reporting and trace reporting.  But if something
+goes wrong, you can use the following steps and tips to potentially diagnose any issues that may exist.
+
+# Supported Components
+
+Make sure that the component that you want to get visibility into has been added to the support matrix.  A list of all
+supported components can be found in the [documentation](https://instana.atlassian.net/wiki/display/DOCS/Ruby).
+
+# Logging & Environment Variables
+
+By default, the gem will log informational messages on boot that will indicate if any problems were encountered.  If you
+set the `INSTANA_GEM_DEV` environment variable, it will increase the amount of logging output.
+
+![instana console output](https://s3.amazonaws.com/instana/Instana+Ruby+boot+console+logging+output.png)
+
+In the example above, you can see that the host agent isn't available.  Once the host agent is available, the Instana
+gem will automatically re-connect without any intervention.
+
+There are even more methods to control logging output.  See the [Configuration](https://github.com/instana/ruby-sensor/blob/master/Configuration.md#logging)
+document for details.
+
+# Testing in your Application
+
+To diagnose the Instana gem from your application, often simply opening an application console with verbose logging can be
+enough to identify any potential issues:
+
+![rails console](https://s3.amazonaws.com/instana/Instana+Ruby+Rails+console+output.png)
+
+In the example above, you can see the Instana Ruby gem initialize, instrument some components and a success notification: `Host agent available. We're
+in business`.

data/lib/instana/agent.rb

@@ -215,7 +215,7 @@ module Instana
       response = make_host_agent_request(req)
 
       if response
-        if response.body.length > 2
+        if response.body && response.body.length > 2
           # The host agent returned something indicating that is has a request for us that we
           # need to process.
           handle_response(response.body)

data/lib/instana/instrumentation/excon.rb

@@ -19,8 +19,9 @@ if defined?(::Excon) && ::Instana.config[:excon][:enabled]
           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
+          t_context = ::Instana.tracer.context
+          datum[:headers]['X-Instana-T'] = t_context.trace_id_header
+          datum[:headers]['X-Instana-S'] = t_context.span_id_header
 
           @stack.request_call(datum)
         end

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

@@ -13,8 +13,9 @@ Net::HTTP.class_eval {
     request = args[0]
 
     # Set request headers; encode IDs as hexadecimal strings
-    request['X-Instana-T'] = ::Instana.tracer.trace_id_header
-    request['X-Instana-S'] = ::Instana.tracer.span_id_header
+    t_context = ::Instana.tracer.context
+    request['X-Instana-T'] = t_context.trace_id_header
+    request['X-Instana-S'] = t_context.span_id_header
 
     # Collect up KV info now in case any exception is raised
     kv_payload = { :http => {} }

data/lib/instana/instrumentation/rack.rb

@@ -18,8 +18,8 @@ module Instana
       # 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[:span_id]   = ::Instana.tracer.header_to_id(env['HTTP_X_INSTANA_S']) if env.key?('HTTP_X_INSTANA_S')
+        incoming_context[:trace_id]  = ::Instana::Util.header_to_id(env['HTTP_X_INSTANA_T'])
+        incoming_context[:span_id]   = ::Instana::Util.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
 
@@ -49,8 +49,8 @@ module Instana
     ensure
       if headers && ::Instana.tracer.tracing?
         # 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)
+        headers['X-Instana-T'] = ::Instana::Util.id_to_header(trace_id)
+        headers['X-Instana-S'] = ::Instana::Util.id_to_header(span_id)
       end
       ::Instana.tracer.log_end(:rack, kvs)
     end

data/lib/instana/logger.rb

@@ -2,7 +2,7 @@ require "logger"
 
 module Instana
   class XLogger < Logger
-    LEVELS = [:agent, :agent_comm, :trace, :agent_response].freeze
+    LEVELS = [:agent, :agent_comm, :trace, :agent_response, :tracing].freeze
     STAMP = "Instana: ".freeze
 
     def initialize(*args)
@@ -22,8 +22,9 @@ module Instana
     #
     # :agent          - All agent related messages such as state & announcements
     # :agent_comm     - Output all payload comm sent between this Ruby gem and the host agent
-    # :trace          - Output all traces reported to the host agent
     # :agent_response - Outputs messages related to handling requests received by the host agent
+    # :trace          - Output all traces reported to the host agent
+    # :tracing        - Output messages related to tracing components, spans and management
     #
     # To use:
     # ::Instana.logger.debug_level = [:agent_comm, :trace]
@@ -52,13 +53,18 @@ module Instana
       self.debug(msg)
     end
 
+    def agent_response(msg)
+      return unless @level_agent_response
+      self.debug(msg)
+    end
+
     def trace(msg)
       return unless @level_trace
       self.debug(msg)
     end
 
-    def agent_response(msg)
-      return unless @level_agent_response
+    def tracing(msg)
+      return unless @level_tracing
       self.debug(msg)
     end
 

data/lib/instana/opentracing/carrier.rb

@@ -0,0 +1,4 @@
+module OpenTracing
+  class Carrier < Hash
+  end
+end

data/lib/instana/opentracing/tracer.rb

@@ -0,0 +1,18 @@
+module OpenTracing
+  class << self
+    # Text format for #inject and #extract
+    FORMAT_TEXT_MAP = 1
+
+    # Binary format for #inject and #extract
+    FORMAT_BINARY = 2
+
+    # Ruby Specific format to handle how Rack changes environment variables.
+    FORMAT_RACK = 3
+
+    attr_accessor :global_tracer
+
+    def method_missing(method_name, *args, &block)
+      @global_tracer.send(method_name, *args, &block)
+    end
+  end
+end

data/lib/instana/setup.rb

@@ -11,6 +11,9 @@ require "instana/instrumentation"
 
 ::Instana.agent.setup
 
+# Require supported OpenTracing interfaces
+require "opentracing"
+
 # The Instana agent is now setup.  The only remaining
 # task for a complete boot is to call
 # `Instana.agent.start` in the thread of your choice.

data/lib/instana/tracer.rb

@@ -1,6 +1,7 @@
 require "instana/thread_local"
 require "instana/tracing/trace"
 require "instana/tracing/span"
+require "instana/tracing/span_context"
 
 module Instana
   class Tracer
@@ -126,10 +127,10 @@ module Instana
     # @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 = {})
+    def log_end(name, kvs = {}, end_time = Time.now)
       return unless tracing?
 
-      self.current_trace.finish(kvs)
+      self.current_trace.finish(kvs, end_time)
 
       if !self.current_trace.has_async? ||
           (self.current_trace.has_async? && self.current_trace.complete?)
@@ -156,7 +157,7 @@ module Instana
     #   :trace_id => 12345
     #   :span_id => 12345
     #
-    def log_async_entry(name, kvs, incoming_context = nil)
+    def log_async_entry(name, kvs)
       return unless tracing?
       self.current_trace.new_async_span(name, kvs)
     end
@@ -164,41 +165,38 @@ module Instana
     # 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
+    # @param span [Span] the span for this Async op (previously returned
+    #   from `log_async_entry`)
     #
-    def log_async_info(kvs, ids)
+    def log_async_info(kvs, span)
       # 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)
+      if tracing? && self.current_trace.id == span.context.trace_id
+        self.current_trace.add_async_info(kvs, span)
       else
-        trace = ::Instana.processor.staged_trace(ids)
-        trace.add_async_info(kvs, ids)
+        trace = ::Instana.processor.staged_trace(span.context.trace_id)
+        trace.add_async_info(kvs, span)
       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
+    # @param span [Span] the span for this Async op (previously returned
+    #   from `log_async_entry`)
     #
-    def log_async_error(e, ids)
+    def log_async_error(e, span)
       # 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)
+      if tracing? && self.current_trace.id == span.context.trace_id
+        self.current_trace.add_async_error(e, span)
       else
-        trace = ::Instana.processor.staged_trace(ids)
-        trace.add_async_error(e, ids)
+        trace = ::Instana.processor.staged_trace(span.context.trace_id)
+        trace.add_async_error(e, span)
       end
     end
 
@@ -206,29 +204,92 @@ module Instana
     #
     # @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
+    # @param span [Span] the span for this Async op (previously returned
+    #   from `log_async_entry`)
     #
-    def log_async_exit(name, kvs, ids)
+    def log_async_exit(name, kvs, span)
       # 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)
+      if tracing? && self.current_trace.id == span.context.trace_id
+        self.current_trace.end_async_span(kvs, span)
       else
         # Different trace from current so find the staged trace
         # and close out the span on it.
-        trace = ::Instana.processor.staged_trace(ids)
+        trace = ::Instana.processor.staged_trace(span.context.trace_id)
         if trace
-          trace.end_async_span(kvs, ids)
+          trace.end_async_span(kvs, span)
         else
-          ::Instana.logger.debug "log_async_exit: Couldn't find staged trace. #{ids.inspect}"
+          ::Instana.logger.debug "log_async_exit: Couldn't find staged trace. #{span.inspect}"
         end
       end
     end
 
+    ###########################################################################
+    # OpenTracing Support
+    ###########################################################################
+
+    # Start a new span
+    #
+    # @param operation_name [String] The name of the operation represented by the span
+    # @param child_of [Span] A span to be used as the ChildOf reference
+    # @param start_time [Time] the start time of the span
+    # @param tags [Hash] Starting tags for the span
+    #
+    # @return [Span]
+    #
+    def start_span(operation_name, child_of: nil, start_time: Time.now, tags: nil)
+      return unless ::Instana.agent.ready?
+
+      if tracing?
+        span = self.current_trace.new_span(operation_name, tags, start_time, child_of)
+      else
+        self.current_trace = ::Instana::Trace.new(operation_name, tags, nil, start_time)
+        span = self.current_trace.current_span
+      end
+      span.set_tags(tags)
+      span
+    end
+
+    # Inject a span into the given carrier
+    #
+    # @param span_context [SpanContext]
+    # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
+    # @param carrier [Carrier]
+    #
+    def inject(span_context, format, carrier)
+      case format
+      when OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY
+        ::Instana.logger.debug 'Unsupported inject format'
+      when OpenTracing::FORMAT_RACK
+        carrier['X-Instana-T'] = ::Instana::Util.id_to_header(span_context.trace_id)
+        carrier['X-Instana-S'] = ::Instana::Util.id_to_header(span_context.span_id)
+      else
+        ::Instana.logger.debug 'Unknown inject format'
+      end
+    end
+
+    # Extract a span from a carrier
+    #
+    # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
+    # @param carrier [Carrier]
+    #
+    # @return [SpanContext]
+    #
+    def extract(format, carrier)
+      case format
+      when OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY
+        ::Instana.logger.debug 'Unsupported extract format'
+      when OpenTracing::FORMAT_RACK
+        ::Instana::SpanContext.new(::Instana::Util.header_to_id(carrier['HTTP_X_INSTANA_T']),
+                                     ::Instana::Util.header_to_id(carrier['HTTP_X_INSTANA_S']))
+      else
+        ::Instana.logger.debug 'Unknown inject format'
+        nil
+      end
+    end
+
     ###########################################################################
     # Helper methods
     ###########################################################################
@@ -248,11 +309,11 @@ module Instana
 
     # Retrieve the current context of the tracer.
     #
+    # @return [SpanContext] or nil if not tracing
+    #
     def context
       return nil unless tracing?
-
-      { :trace_id => self.current_trace.id,
-        :span_id => self.current_trace.current_span_id }
+      self.current_trace.current_span.context
     end
 
     # Take the current trace_id and convert it to a header compatible
@@ -261,7 +322,7 @@ module Instana
     # @return [String] a hexadecimal representation of the current trace ID
     #
     def trace_id_header
-      id_to_header(trace_id)
+      ::Instana::Util.id_to_header(trace_id)
     end
 
     # Take the current span_id and convert it to a header compatible
@@ -270,41 +331,7 @@ module Instana
     # @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
-    #
-    # @return [String]
-    #
-    def id_to_header(id)
-      unless id.is_a?(Integer) || id.is_a?(String)
-        Instana.logger.debug "id_to_header received a #{id.class}: returning empty string"
-        return String.new
-      end
-      [id.to_i].pack('q>').unpack('H*')[0]
-    rescue => e
-      Instana.logger.error "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
-      Instana.logger.debug e.backtrace.join("\r\n")
-    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)
-      if !header_id.is_a?(String)
-        Instana.logger.debug "header_to_id received a #{header_id.class}: returning 0"
-        return 0
-      end
-      [header_id].pack("H*").unpack("q>")[0]
-    rescue => e
-      Instana.logger.error "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
-      Instana.logger.debug e.backtrace.join("\r\n")
+      ::Instana::Util.id_to_header(span_id)
     end
 
     # Returns the trace ID for the active trace (if there is one),
@@ -320,5 +347,17 @@ module Instana
     def span_id
       self.current_trace  ? current_trace.current_span_id : nil
     end
+
+    # Helper method to retrieve the currently active span for the active trace.
+    #
+    def current_span
+      self.current_trace ? self.current_trace.current_span : nil
+    end
+
+    # Used in the test suite, this resets the tracer to non-tracing state.
+    #
+    def clear!
+      self.current_trace = nil
+    end
   end
 end