instana 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fff8c1b1ed4764301a7f1a45dec8973df279b2d8
-  data.tar.gz: 8947536ba2a71f9916712d55980f77f57af8fde7
+  metadata.gz: 72f8c1fa60c3d84f52025ce41ebb803ce83b36d8
+  data.tar.gz: cb85eb7203cc6d028712351d642dc153a28a6468
 SHA512:
-  metadata.gz: 1626e65166c81355c55105db86179e22c8cf9a1ae7ee7292e17574015f0acf2590eb0ed06b667d20d6d1294bd2d79eddaef584951119fc750880950401caa2ff
-  data.tar.gz: 18c6581dbaece4419c1fd6edb59e4fabd30efab3789c24bc0b006420c3bce83f774ae4a239a37dc47b7c8ea1d0e99bf2f981c59d692b39b0e4ac00870010820e
+  metadata.gz: 21b2723fc3ee132868586e0f4dd0ad218dafc0a6e39c0fd56ff18c508fe984c32f1431134d1f467a91c687b2b3eb1f34976b76629a675bbe0d829011415e70ad
+  data.tar.gz: af75b8240335a5c8484400c6d1dca6197b0121d7a0d20569af8bbd0911ab336b68b935b352809f841a571b36cbbe789767dd99d54eeabdacb6084467d6a6c59c

data/README.md

@@ -48,6 +48,10 @@ The instana gem is a zero configuration tool that will automatically collect key
 
 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).
 
+## Tracing
+
+See [Tracing.md](https://github.com/instana/ruby-sensor/blob/master/Tracing.md)
+
 ## Documentation
 
 You can find more documentation covering supported components and minimum versions in the Instana [documentation portal](https://instana.atlassian.net/wiki/display/DOCS/Ruby).

data/Tracing.md

@@ -0,0 +1,109 @@
+# Tracing
+
+Tracing with Instana is automatic but if you want even more visibility into custom code or some in-house
+component, you can use the following API to report additional trace data to Instana.
+
+# The API
+
+The Instana Ruby gem provides a simple to use API to trace any arbitrary part of your application.
+
+To instrument a section of code, it can be simply done with:
+
+```Ruby
+begin
+  ::Instana.tracer.log_entry(:mywork, { :helpful_kvs => @user.id })
+  # The code to be instrumented
+  @id = User.find_by_name('john.smith')
+rescue => e
+  ::Instana.tracer.log_error(e)
+ensure
+  ::Instana.tracer.log_exit(:mywork, { :found_id => @id })
+end
+```
+
+The above is a simple example but shows how easy it is to instrument any code you like.  Instana will
+take care of the rest.
+
+See the [examples directory](https://github.com/instana/ruby-sensor/blob/master/examples/tracing.rb) for
+an expanded view and quick cheat sheet on tracing.
+
+# Asynchronous Tracing
+
+Some operations that you want to trace might be asynchronous meaning that they may return immediately
+but will still continue to work out of band.  To do this, you can use  the `log_async_*` related 
+tracing methods:
+
+```Ruby
+::Instana.tracer.log_entry(:prep_job, { :helpful_kvs => @job.name })
+
+http_ops = {:get => "/", :post => "/post_data"}
+
+cb_block = Proc.new do |response, payload|
+  # The callback block that is invoked on HTTP response (payload == t_context)
+  #
+  # process response
+  #
+  ::Instana.tracer.log_async_exit(:http_op, :status => response.status, payload)
+end
+
+http_ops.each do |op|
+  t_context = ::Instana.tracer.log_async_entry(:http_op)
+  
+  # Example op that returns immediately
+  request_id = connection.async_request(op, cb_block, t_context)
+  
+  ::Instana.tracer.log_async_info({:request_id => request_id}, t_context)
+end  
+```
+
+# Carrying Context into New Threads
+
+Tracing is thread local.  If you spawn a new thread the context must be carried to that new thread and then picked up.
+
+```Ruby
+# Get the tracing context
+t_context = ::Instana.tracer.context
+
+# Spawn new thread
+Thread.new do
+  # Pickup context in this thread with `t_context`
+  ::Instana.tracer.log_start_or_continue(:async_thread, { :async_start => 1 }, t_context)
+  
+  # Continue tracing work as usual
+  begin
+    ::Instana.tracer.log_entry(:mywork, { :helpful_kvs => @user.id })
+    # The code to be instrumented
+    @id = User.find_by_name('john.smith')
+  rescue => e
+    ::Instana.tracer.log_error(e)
+  ensure
+    ::Instana.tracer.log_exit(:mywork, { :found_id => @id })
+  end
+end
+```
+# Tracing Jobs Scheduled for Later
+
+Jobs that are queued to be run later can be instrumented as such:
+
+```Ruby
+::Instana.tracer.log_entry(:prep_job, { :job_name => @job.name })
+
+# Get the current tracing context
+t_context = ::Instana.tracer.context
+
+# The Async proc (job) that will be executed out of band.
+block = Proc.new do 
+  # This will pickup context and link the two traces (root + job)
+  t_context = ::Instana.tracer.log_start_or_continue_trace(:my_async_op, { :helpful_kvs => true }, t_context)
+  #
+  # Some Asynchronous work to be done
+  #
+  ::Instana.tracer.log_info({:job_name => Job.get(id).name})
+  # More Asynchronous work
+  ::Instana.tracer.log_end(:my_async_op, { :job_success => true })
+end
+
+MyClass.run_in_5_minutes(block)
+
+::Instana.tracer.log_exit(:prep_job, { :prep_successful => true })
+```

data/lib/instana/agent.rb

@@ -27,7 +27,7 @@ module Instana
 
       # Snapshot data is collected once per process but resent
       # every 10 minutes along side process metrics.
-      @snapshot = take_snapshot
+      @snapshot = ::Instana::Util.take_snapshot
 
       # Set last snapshot to just under 10 minutes ago
       # so we send a snapshot sooner than later
@@ -82,14 +82,6 @@ module Instana
       @process[:report_pid] = nil
     end
 
-    # Determine whether the pid has changed since Agent start.
-    #
-    # @ return [Boolean] true or false to indicate if forked
-    #
-    def forked?
-      @pid != Process.pid
-    end
-
     # Used post fork to re-initialize state and restart communications with
     # the host agent.
     #
@@ -137,7 +129,7 @@ module Instana
       # In case of failure, we try again in 30 seconds.
       @announce_timer = @timers.now_and_every(30) do
         if host_agent_ready? && announce_sensor
-          ::Instana.logger.debug "Announce successful. Switching to metrics collection."
+          ::Instana.logger.warn "Host agent available. We're in business."
           transition_to(:announced)
         end
       end
@@ -147,11 +139,11 @@ module Instana
       # every ::Instana::Collector.interval seconds.
       @collect_timer = @timers.every(::Instana::Collector.interval) do
         if @state == :announced
-          unless ::Instana::Collector.collect_and_report
+          if !::Instana::Collector.collect_and_report
             # If report has been failing for more than 1 minute,
             # fall back to unannounced state
             if (Time.now - @entity_last_seen) > 60
-              ::Instana.logger.debug "Metrics reporting failed for >1 min.  Falling back to unannounced state."
+              ::Instana.logger.warn "Host agent offline for >1 min.  Going to sit in a corner..."
               transition_to(:unannounced)
             end
           end
@@ -188,31 +180,6 @@ module Instana
       end
     end
 
-    # Indicates if the agent is ready to send metrics
-    # and/or data.
-    #
-    def ready?
-      # In test, we're always ready :-)
-      return true if ENV['INSTANA_GEM_TEST']
-
-      if forked?
-        ::Instana.logger.agent "Instana: detected fork.  Calling after_fork"
-        after_fork
-      end
-
-      @state == :announced
-    rescue => e
-      Instana.logger.debug "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
-      Instana.logger.debug e.backtrace.join("\r\n")
-      return false
-    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.
     #
@@ -270,14 +237,18 @@ module Instana
       response = make_host_agent_request(req)
 
       if response
-        last_entity_response = response.code.to_i
+        if 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)
+        end
 
-        if last_entity_response == 200
+        if response.code.to_i == 200
           @entity_last_seen = Time.now
           @last_snapshot = Time.now if with_snapshot
-
           return true
         end
+
       end
       false
     rescue => e
@@ -285,6 +256,32 @@ module Instana
       Instana.logger.debug e.backtrace.join("\r\n")
     end
 
+    # When a request is received by the host agent, it is sent here
+    # from processing and response.
+    #
+    # @param json_string [String] the request from the host agent
+    #
+    def handle_response(json_string)
+      their_request = JSON.parse(json_string).first
+
+      if their_request.key?("action")
+        if their_request["action"] == "ruby.source"
+          payload = ::Instana::Util.get_rb_source(their_request["args"]["file"])
+        else
+          payload = { :error => "Unrecognized action: #{their_request["action"]}. An newer Instana gem may be required for this. Current version: #{::Instana::VERSION}" }
+        end
+      else
+        payload = { :error => "Instana Ruby: No action specified in request." }
+      end
+
+      path = "com.instana.plugin.ruby/response.#{@process[:report_pid]}?messageId=#{URI.encode(their_request['messageId'])}"
+      uri = URI.parse("http://#{@host}:#{@port}/#{path}")
+      req = Net::HTTP::Post.new(uri)
+      req.body = payload.to_json
+      ::Instana.logger.agent_response "Responding to agent: #{req.inspect}"
+      make_host_agent_request(req)
+    end
+
     # Accept and report spans to the host agent.
     #
     # @param traces [Array] An array of [Span]
@@ -350,6 +347,31 @@ module Instana
       return false
     end
 
+    # Returns the PID that we are reporting to
+    #
+    def report_pid
+      @process[:report_pid]
+    end
+
+    # Indicates if the agent is ready to send metrics
+    # and/or data.
+    #
+    def ready?
+      # In test, we're always ready :-)
+      return true if ENV['INSTANA_GEM_TEST']
+
+      if forked?
+        ::Instana.logger.agent "Instana: detected fork.  Calling after_fork"
+        after_fork
+      end
+
+      @state == :announced
+    rescue => e
+      Instana.logger.debug "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
+      Instana.logger.debug e.backtrace.join("\r\n")
+      return false
+    end
+
     private
 
     # Handles any/all steps required in the transtion
@@ -424,41 +446,12 @@ module Instana
       v.match(/\d+/).to_s.to_i
     end
 
-    # Method to collect up process info for snapshots.  This
-    # is generally used once per process.
+    # Determine whether the pid has changed since Agent start.
     #
-    def take_snapshot
-      data = {}
-
-      data[:sensorVersion] = ::Instana::VERSION
-      data[:ruby_version] = RUBY_VERSION
-
-      # Since a snapshot is only taken on process boot,
-      # this is ok here.
-      data[:start_time] = Time.now.to_s
-
-      # Framework Detection
-      if defined?(::RailsLts::VERSION)
-        data[:framework] = "Rails on Rails LTS-#{::RailsLts::VERSION}"
-
-      elsif defined?(::Rails.version)
-        data[:framework] = "Ruby on Rails #{::Rails.version}"
-
-      elsif defined?(::Grape::VERSION)
-        data[:framework] = "Grape #{::Grape::VERSION}"
-
-      elsif defined?(::Padrino::VERSION)
-        data[:framework] = "Padrino #{::Padrino::VERSION}"
-
-      elsif defined?(::Sinatra::VERSION)
-        data[:framework] = "Sinatra #{::Sinatra::VERSION}"
-      end
-
-      data
-    rescue => e
-      ::Instana.logger.error "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
-      ::Instana.logger.debug e.backtrace.join("\r\n")
-      return data
+    # @ return [Boolean] true or false to indicate if forked
+    #
+    def forked?
+      @pid != Process.pid
     end
   end
 end

data/lib/instana/collectors.rb

@@ -15,6 +15,8 @@ module Instana
       # Run through each collector, let them collect up
       # data and then report what we have via the agent
       #
+      # @return Boolean true on success
+      #
       def collect_and_report
         payload = {}
 
@@ -27,10 +29,13 @@ module Instana
           end
         end
 
-        # Report all the collected goodies
-        ::Instana.agent.report_entity_data(payload) unless ENV['INSTANA_GEM_TEST']
+        if ENV['INSTANA_GEM_TEST']
+          true
+        else
+          # Report all the collected goodies
+          ::Instana.agent.report_entity_data(payload)
+        end
       end
-
     end
   end
 end

data/lib/instana/instrumentation/excon.rb

@@ -58,7 +58,7 @@ if defined?(::Excon) && ::Instana.config[:excon][:enabled]
     end
   end
 
-  ::Instana.logger.warn "Instrumenting excon"
+  ::Instana.logger.warn "Instrumenting Excon"
   ::Excon.defaults[:middlewares].unshift(::Instana::Instrumentation::Excon)
 end
 

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

@@ -43,7 +43,7 @@ Net::HTTP.class_eval {
     ::Instana.tracer.log_exit(:'net-http')
   end
 
-  Instana.logger.info "Instrumenting net/http"
+  Instana.logger.warn "Instrumenting Net::HTTP"
 
   alias request_without_instana request
   alias request request_with_instana

data/lib/instana/logger.rb

@@ -2,7 +2,7 @@ require "logger"
 
 module Instana
   class XLogger < Logger
-    LEVELS = [:agent, :agent_comm, :trace].freeze
+    LEVELS = [:agent, :agent_comm, :trace, :agent_response].freeze
     STAMP = "Instana: ".freeze
 
     def initialize(*args)
@@ -13,7 +13,12 @@ module Instana
     end
 
     # Sets the debug level for this logger.  The debug level is broken up into various
-    # sub-levels as defined in LEVELS.
+    # sub-levels as defined in LEVELS:
+    #
+    # :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
     #
     # To use:
     # ::Instana.logger.debug_level = [:agent_comm, :trace]
@@ -45,6 +50,11 @@ module Instana
       self.debug(msg)
     end
 
+    def agent_response(msg)
+      return unless @level_agent_response
+      self.debug(msg)
+    end
+
     def error(msg)
       super(STAMP + msg)
     end

data/lib/instana/tracer.rb

@@ -249,6 +249,8 @@ module Instana
     # Retrieve the current context of the tracer.
     #
     def context
+      return nil unless tracing?
+
       { :trace_id => self.current_trace.id,
         :span_id => self.current_trace.current_span_id }
     end

data/lib/instana/tracing/trace.rb

@@ -1,6 +1,8 @@
 module Instana
   class Trace
     REGISTERED_SPANS = [ :rack, :'net-http', :excon ]
+    ENTRY_SPANS = [ :rack ]
+    EXIT_SPANS = [ :'net-http', :excon ]
 
     # @return [Integer] the ID for this trace
     attr_reader :id
@@ -24,9 +26,6 @@ module Instana
       # up this trace.
       @spans = Set.new
 
-      # The current active span
-      @current_span = nil
-
       # Generate a random 64bit ID for this trace
       @id = generate_id
 
@@ -46,6 +45,9 @@ module Instana
         :f => { :e => ::Instana.agent.report_pid, :h => ::Instana.agent.agent_uuid } # Entity Source
       })
 
+      # For entry spans, add a backtrace fingerprint
+      add_stack(2) if ENTRY_SPANS.include?(name)
+
       # Check for custom tracing
       if !REGISTERED_SPANS.include?(name.to_sym)
         configure_custom_span(nil, name, kvs)
@@ -73,7 +75,7 @@ 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
     #
-    def new_span(name, kvs)
+    def new_span(name, kvs = {})
       return unless @current_span
 
       new_span = Span.new({
@@ -96,6 +98,9 @@ module Instana
         @current_span[:n]    = name.to_sym
         @current_span[:data] = kvs
       end
+
+      # Attach a backtrace to all exit spans
+      add_stack if EXIT_SPANS.include?(name)
     end
 
     # Add KVs to the current span
@@ -139,6 +144,10 @@ module Instana
       else
         span[:ec] = 1
       end
+
+      add_info(:log => {
+        :message => e.message,
+        :parameters => e.class })
     end
 
     # Close out the current span and set the parent as
@@ -198,6 +207,9 @@ module Instana
         new_span[:data] = kvs
       end
 
+      # Attach a backtrace to all exit spans
+      add_stack(nil, new_span) if EXIT_SPANS.include?(name)
+
       # Add the new span to the span collection
       @spans.add(new_span)
 
@@ -386,6 +398,40 @@ module Instana
       end
     end
 
+    # Adds a backtrace to the passed in span or on
+    # @current_span if not.
+    #
+    # @param limit [Integer] Limit the backtrace to the top <limit> frames
+    # @param span [Span] the span to add the backtrace to or if unspecified
+    #   the current span
+    #
+    def add_stack(limit = nil, span = nil)
+      span ||= @current_span
+      span[:stack] = []
+      frame_count = 0
+
+      bt = Kernel.caller
+
+      bt.each do |i|
+        # If the stack has the full instana gem version in it's path
+        # then don't include that frame. Also don't exclude the Rack module.
+        if !i.match(/instana\/instrumentation\/rack.rb/).nil? ||
+          (i.match(::Instana::VERSION_FULL).nil? && i.match('lib/instana/').nil?)
+
+          break if limit && frame_count >= limit
+
+          x = i.split(':')
+
+          span[:stack] << {
+            :f => x[0],
+            :n => x[1],
+            :m => x[2]
+          }
+         frame_count = frame_count + 1 if limit
+        end
+      end
+    end
+
     # Get the current time in milliseconds
     #
     # @return [Integer] the current time in milliseconds

data/lib/instana/util.rb

@@ -65,6 +65,58 @@ module Instana
           require 'ruby-debug'; debugger
         end
       end
+
+      # Retrieves and returns the source code for any ruby
+      # files requested by the UI via the host agent
+      #
+      # @param file [String] The fully qualified path to a file
+      #
+      def get_rb_source(file)
+        if (file =~ /.rb$/).nil?
+          { :error => "Only Ruby source files are allowed. (*.rb)" }
+        else
+          { :data => File.read(file) }
+        end
+      rescue => e
+        return { :error => e.inspect }
+      end
+
+      # Method to collect up process info for snapshots.  This
+      # is generally used once per process.
+      #
+      def take_snapshot
+        data = {}
+
+        data[:sensorVersion] = ::Instana::VERSION
+        data[:ruby_version] = RUBY_VERSION
+
+        # Since a snapshot is only taken on process boot,
+        # this is ok here.
+        data[:start_time] = Time.now.to_s
+
+        # Framework Detection
+        if defined?(::RailsLts::VERSION)
+          data[:framework] = "Rails on Rails LTS-#{::RailsLts::VERSION}"
+
+        elsif defined?(::Rails.version)
+          data[:framework] = "Ruby on Rails #{::Rails.version}"
+
+        elsif defined?(::Grape::VERSION)
+          data[:framework] = "Grape #{::Grape::VERSION}"
+
+        elsif defined?(::Padrino::VERSION)
+          data[:framework] = "Padrino #{::Padrino::VERSION}"
+
+        elsif defined?(::Sinatra::VERSION)
+          data[:framework] = "Sinatra #{::Sinatra::VERSION}"
+        end
+
+        data
+      rescue => e
+        ::Instana.logger.error "#{__method__}:#{File.basename(__FILE__)}:#{__LINE__}: #{e.message}"
+        ::Instana.logger.debug e.backtrace.join("\r\n")
+        return data
+      end
     end
   end
 end

data/lib/instana/version.rb

@@ -1,3 +1,4 @@
 module Instana
-  VERSION = "0.13.1"
+  VERSION = "0.14.0"
+  VERSION_FULL = "instana-#{VERSION}"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: instana
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Peter Giacomo Lombardo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-09 00:00:00.000000000 Z
+date: 2016-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -123,6 +123,7 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- Tracing.md
 - bin/console
 - bin/setup
 - examples/tracing.rb