instana 0.9.2 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e4e0afa7990ec121d8542873c665d2ddda7e1ee9
-  data.tar.gz: 33143dc761cf85e27ab21ed22c9f64f8670c3a2b
+  metadata.gz: 7e188f12fcff2a78ced457b2640b460b257e5684
+  data.tar.gz: c149e734156bf8b02ffd757cc564618c83ba7153
 SHA512:
-  metadata.gz: 85b7857890a0da50ef837027a1c5e0e7f413189b60175d1f26e682f5c109c7f98534efa2a84ef0f2cbf0e1162eb00f88b10604118fc18ca8036b3aef94e4c02e
-  data.tar.gz: 57d956387066525d20f4e6efc108115f4b02d001418fdad0cdf639143be00e32bfc26173eccc96cfed2bf63be36dbc3b0e09fd96db9209c1037f44ff27a36801
+  metadata.gz: 46e488894d84fa5b4afd32b486ae5c4af61ce30ceee001b6395f5c4dbb7fdfe68421093d765e59ecab0c647ef63992d0ebeb9c6abc1eed7af401cd69ad742cb1
+  data.tar.gz: 26be2c7a4a825baa23897a143ddbaabf631a1797e43716066509f984f84aa0d9c85054f7a67e3f9b8d59e3c9054f952c1769fd2b73a6d880c50df204585f46f1

data/README.md

@@ -1,17 +1,17 @@
 <div align="center">
-<img src="https://www.instana.com/wp-content/uploads/2016/04/stan@2x.png">
+<img src="https://www.instana.com/wp-content/uploads/2016/04/stan@2x.png" height="300px"/>
 </div>
 
 # Instana
 
-The Instana gem provides Ruby metrics for [Instana](https://www.instana.com/).
+The Instana gem provides Ruby metrics and traces (request, queue & cross-host) for [Instana](https://www.instana.com/).
 
 [![Build Status](https://travis-ci.org/instana/ruby-sensor.svg?branch=master)](https://travis-ci.org/instana/ruby-sensor)
 [![Gem Version](https://badge.fury.io/rb/instana.svg)](https://badge.fury.io/rb/instana)
 
 ## Note
 
-This gem is currently in beta and supports Ruby versions 2.0 or greater.
+This gem supports Ruby versions 2.0 or greater.
 
 Any and all feedback is welcome.  Happy Ruby visibility.
 
@@ -37,7 +37,33 @@ The instana gem is a zero configuration tool that will automatically collect key
 
 ## Configuration
 
-Although the gem has no configuration required for metrics, individual components can be disabled with a local config.
+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
+```
+
+### 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:
 
@@ -46,6 +72,17 @@ To disable a single component in the gem, you can disable a single component wit
 ```
 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 Ruby on Rails is present.  We are currently adding support for more frameworks.  If you are using a framework other than Ruby on Rails, 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.
+
 ## 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/lib/instana.rb

@@ -1,57 +1,13 @@
-
-require 'logger'
-require "instana/version"
-require "instana/util"
-
-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
-
-    ##
-    # start
-    #
-    # Initialize the Instana language agent
-    #
-    def start
-      @agent  = ::Instana::Agent.new
-      @tracer = ::Instana::Tracer.new
-      @processor = ::Instana::Processor.new
-      @collectors = []
-
-      @logger = Logger.new(STDOUT)
-      if ENV.key?('INSTANA_GEM_TEST') || ENV.key?('INSTANA_GEM_DEV')
-        @logger.level = Logger::DEBUG
-      else
-        @logger.level = Logger::WARN
-      end
-      @logger.unknown "Stan is on the scene.  Starting Instana instrumentation."
-
-      # Store the current pid so we can detect a potential fork
-      # later on
-      @pid = ::Process.pid
-    end
-
-    def pid_change?
-      @pid != ::Process.pid
-    end
-  end
+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"
+#
+# ...and manually call ::Instana.agent.start in the thread
+# of your choice
+#
+Thread.new do
+  ::Instana.agent.start
 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

@@ -94,33 +94,50 @@ module Instana
     # the host agent.
     #
     def after_fork
-      ::Instana.logger.debug "after_fork hook called. Falling back to unannounced state."
+      ::Instana.logger.debug "after_fork hook called. Falling back to unannounced state and spawning a new background agent thread."
 
       # Re-collect process information post fork
       @pid = Process.pid
       collect_process_info
 
-      # Set last snapshot to 10 minutes ago
-      # so we send a snapshot sooner than later
-      @last_snapshot = Time.now - 600
-
       transition_to(:unannounced)
-      start
+      setup
+      spawn_background_thread
+    end
+
+    # Spawns the background thread and calls start.  This method is separated
+    # out for those who wish to control which thread the background agent will
+    # run in.
+    #
+    # This method can be overridden with the following:
+    #
+    # module Instana
+    #   class Agent
+    #     def spawn_background_thread
+    #       # start thread
+    #       start
+    #     end
+    #   end
+    # end
+    #
+    def spawn_background_thread
+      # The thread calling fork is the only thread in the created child process.
+      # fork doesn’t copy other threads.
+      # Restart our background thread
+      Thread.new do
+        start
+      end
     end
 
     # Sets up periodic timers and starts the agent in a background thread.
     #
-    def start
+    def setup
       # The announce timer
       # We attempt to announce this ruby sensor to the host agent.
       # In case of failure, we try again in 30 seconds.
       @announce_timer = @timers.now_and_every(30) do
-        if forked?
-          after_fork
-          break
-        end
         if host_agent_ready? && announce_sensor
-          ::Instana.logger.debug "Announce successful. Switching to metrics collection."
+          ::Instana.logger.debug "Announce successful. Switching to metrics collection. pid: #{Process.pid}"
           transition_to(:announced)
         end
       end
@@ -130,10 +147,6 @@ module Instana
       # every ::Instana::Collector.interval seconds.
       @collect_timer = @timers.every(::Instana::Collector.interval) do
         if @state == :announced
-          if forked?
-            after_fork
-            break
-          end
           unless ::Instana::Collector.collect_and_report
             # If report has been failing for more than 1 minute,
             # fall back to unannounced state
@@ -145,31 +158,44 @@ module Instana
           ::Instana.processor.send
         end
       end
+    end
 
-      # Start the background ruby sensor thread.  It works off of timers and
-      # is sleeping otherwise
-      Thread.new do
-        loop {
-          if @state == :unannounced
-            @collect_timer.pause
-            @announce_timer.resume
-          else
-            @announce_timer.pause
-            @collect_timer.resume
-          end
-          @timers.wait
-        }
+    # Starts the timer loop for the timers that were initialized
+    # in the setup method.  This is blocking and should only be
+    # called from an already initialized background thread.
+    #
+    def start
+      loop do
+        if @state == :unannounced
+          @collect_timer.pause
+          @announce_timer.resume
+        else
+          @announce_timer.pause
+          @collect_timer.resume
+        end
+        @timers.wait
       end
+    ensure
+      Instana.logger.debug "Agent start method exiting.  state: #{@state} pid: #{Process.pid}"
     end
 
     # Indicates if the agent is ready to send metrics
-    # or data.
+    # and/or data.
     #
     def ready?
       # In test, we're always ready :-)
       return true if ENV['INSTANA_GEM_TEST']
 
+      if forked?
+        ::Instana.logger.debug "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
@@ -341,6 +367,10 @@ module Instana
         @last_snapshot = Time.now - 601
       when :unannounced
         @state = :unannounced
+
+        # Set last snapshot to 10 minutes ago
+        # so we send a snapshot on first report
+        @last_snapshot = Time.now - 601
       else
         ::Instana.logger.warn "Uknown agent state: #{state}"
       end

data/lib/instana/base.rb

@@ -0,0 +1,44 @@
+require 'logger'
+require "instana/version"
+require "instana/util"
+
+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
+
+    ##
+    # setup
+    #
+    # Setup the Instana language agent to an informal "ready
+    # to run" state.
+    #
+    def setup
+      @logger = Logger.new(STDOUT)
+      if ENV.key?('INSTANA_GEM_TEST') || ENV.key?('INSTANA_GEM_DEV')
+        @logger.level = Logger::DEBUG
+      else
+        @logger.level = Logger::WARN
+      end
+      @logger.unknown "Stan is on the scene.  Starting Instana instrumentation."
+
+      @agent  = ::Instana::Agent.new
+      @tracer = ::Instana::Tracer.new
+      @processor = ::Instana::Processor.new
+      @collectors = []
+
+      # Store the current pid so we can detect a potential fork
+      # later on
+      @pid = ::Process.pid
+    end
+
+    def pid_change?
+      @pid != ::Process.pid
+    end
+  end
+end

data/lib/instana/frameworks/rails.rb

@@ -0,0 +1,22 @@
+require "instana/rack"
+
+if defined?(::Rails)
+  # In Rails, let's use the Rails logger
+  ::Instana.logger = ::Rails.logger if ::Rails.logger
+
+  if ::Rails::VERSION::MAJOR < 3
+    ::Rails.configuration.after_initialization do
+      ::Instana.logger.warn "Instana: Instrumenting Rack"
+      ::Rails.configuration.middleware.insert 0, ::Instana::Rack
+    end
+  else
+    module ::Instana
+      class Railtie < ::Rails::Railtie
+        initializer 'instana.rack' do |app|
+          ::Instana.logger.warn "Instana: Instrumenting Rack"
+          app.config.middleware.insert 0, ::Instana::Rack
+        end
+      end
+    end
+  end
+end

data/lib/instana/instrumentation.rb

@@ -10,3 +10,16 @@ Dir.glob(pattern) do |f|
     Instana.logger.debug e.backtrace.join("\r\n")
   end
 end
+
+#
+# Load all of the files in the frameworks subdirectory
+#
+pattern = File.join(File.dirname(__FILE__), 'frameworks', '*.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/setup.rb

@@ -0,0 +1,25 @@
+require "instana/base"
+require "instana/config"
+require "instana/agent"
+require "instana/tracer"
+require "instana/tracing/processor"
+
+::Instana.setup
+
+require "instana/collectors"
+require "instana/instrumentation"
+
+::Instana.agent.setup
+
+# 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.
+# This can be in a simple `Thread.new` block or
+# any other thread system you may use (e.g. actor
+# threads).
+#
+# Note that `start` should only be called once per process.
+#
+# Thread.new do
+#   ::Instana.agent.start
+# end

data/lib/instana/tracer.rb

@@ -152,7 +152,10 @@ module Instana
         Instana.logger.debug "id_to_header received a #{id.class}: returning empty string"
         return String.new
       end
-      id.to_i.to_s(16)
+      [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
@@ -166,7 +169,10 @@ module Instana
         Instana.logger.debug "header_to_id received a #{header_id.class}: returning 0"
         return 0
       end
-      header_id.to_i(16)
+      [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")
     end
 
     # Returns the trace ID for the active trace (if there is one),

data/lib/instana/tracing/trace.rb

@@ -164,7 +164,7 @@ module Instana
     #
     def generate_id
       # Max value is 9223372036854775807 (signed long in Java)
-      rand(2**32..2**63-1)
+      rand(-2**63..2**63-1)
     end
   end
 end

data/lib/instana/version.rb

@@ -1,3 +1,3 @@
 module Instana
-  VERSION = "0.9.2"
+  VERSION = "0.10.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: instana
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.1
 platform: ruby
 authors:
 - Peter Giacomo Lombardo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-24 00:00:00.000000000 Z
+date: 2016-11-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -126,15 +126,18 @@ files:
 - instana.gemspec
 - lib/instana.rb
 - lib/instana/agent.rb
+- lib/instana/base.rb
 - lib/instana/collectors.rb
 - lib/instana/collectors/gc.rb
 - lib/instana/collectors/memory.rb
 - lib/instana/collectors/thread.rb
 - lib/instana/config.rb
+- lib/instana/frameworks/rails.rb
 - lib/instana/instrumentation.rb
 - lib/instana/instrumentation/net-http.rb
 - lib/instana/instrumentation/rack.rb
 - lib/instana/rack.rb
+- lib/instana/setup.rb
 - lib/instana/thread_local.rb
 - lib/instana/tracer.rb
 - lib/instana/tracing/processor.rb