instrumental_agent 0.9.1 → 0.9.5

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+### 0.9.5 [March 23rd, 2012]
+* Defer startup of agent thread until metrics are submitted - this update is strongly recommended for anyone using Ruby Enterprise Edition in concert w/ a preforking application server (like Phusion Passenger).  See the [REE wiki page](https://github.com/fastestforward/instrumental_agent/wiki/Using-with-Ruby-Enterprise-Edition) for more information.
+* Add .stop method for cancelling agent processing
+* Changes to how defaults are processed at initialization
+* Documentation for usage w/ Resque and Resque like scenarios
+
 ### 0.9.1 [March 6th, 2012]
 * No longer install system_timer on Ruby 1.8.x, but warn if it's not installed
 

data/README.md

@@ -89,6 +89,22 @@ after  "deploy:migrations", "instrumental:util:deploy_end"
 after  "instrumental:util:deploy_end", "instrumental:record_deploy_notice"
 ```
 
+## Tracking metrics in Resque jobs (and Resque-like scenarios)
+
+If you plan on tracking metrics in your Resque jobs, you will need to explicitly flush your metrics when the jobs are finished.  You can accomplish this by adding the following code to your app initializers:
+
+```ruby
+Resque.after_perform { I.flush }
+Resque.on_failure { I.flush }
+```
+
+You're required to do this because Resque calls `exit!` when a worker has finished processing, which bypasses Ruby's `at_exit` hooks.  The Instrumental Agent installs an `at_exit` hook to flush any pending metrics to the servers, but this hook is bypassed by the `exit!` call; any other code you rely that uses `exit!` should call `I.flush` to ensure any pending metrics are correctly sent to the server before exiting the process.
+
+## Using with Ruby Enterprise Edition
+
+Users of Ruby Enterprise Edition should plan on using version 0.9.5 of the Instrumental Agent or greater. Please see the [REE wiki page](https://github.com/fastestforward/instrumental_agent/wiki/Using-with-Ruby-Enterprise-Edition) for more information.
+
+
 ## Troubleshooting & Help
 
 We are here to help. Email us at [support@instrumentalapp.com](mailto:support@instrumentalapp.com), or visit the [Instrumental Support](https://fastestforward.campfirenow.com/6b934) Campfire room.

data/lib/instrumental/agent.rb

@@ -3,6 +3,7 @@ require 'instrumental/version'
 require 'logger'
 require 'thread'
 require 'socket'
+
 if RUBY_VERSION < "1.9" && RUBY_PLATFORM != "java"
   begin
     gem 'system_timer'
@@ -69,32 +70,28 @@ module Instrumental
     #  Instrumental::Agent.new(API_KEY)
     #  Instrumental::Agent.new(API_KEY, :collector => 'hostname:port')
     def initialize(api_key, options = {})
-      default_options = {
-        :collector  => 'instrumentalapp.com:8000',
-        :enabled    => true,
-        :test_mode  => false,
-        :synchronous => false
-      }
-      options   = default_options.merge(options)
-      collector = options[:collector].split(':')
-
-      @api_key     = api_key
-      @host        = collector[0]
-      @port        = (collector[1] || 8000).to_i
-      @enabled     = options[:enabled]
-      @test_mode   = options[:test_mode]
-      @synchronous = options[:synchronous]
+      # symbolize options keys
+      options.replace(
+        options.inject({}) { |m, (k, v)| m[(k.to_sym rescue k) || k] = v; m }
+      )
+
+      # defaults
+      # host:        instrumentalapp.com
+      # port:        8000
+      # enabled:     true
+      # test_mode:   false
+      # synchronous: false
+      @api_key         = api_key
+      @host, @port     = options[:collector].to_s.split(':')
+      @host          ||= 'instrumentalapp.com'
+      @port            = (@port || 8000).to_i
+      @enabled         = options.has_key?(:enabled) ? !!options[:enabled] : true
+      @test_mode       = !!options[:test_mode]
+      @synchronous     = !!options[:synchronous]
+      @pid             = Process.pid
       @allow_reconnect = true
-      @pid = Process.pid
-
 
-      if @enabled
-        @failures = 0
-        @queue = Queue.new
-        @sync_mutex = Mutex.new
-        start_connection_worker
-        setup_cleanup_at_exit
-      end
+      setup_cleanup_at_exit if @enabled
     end
 
     # Store a gauge for a metric, optionally at a specific time.
@@ -204,6 +201,23 @@ module Instrumental
       @logger ||= self.class.logger
     end
 
+    # Stopping the agent will immediately stop all communication 
+    # to Instrumental.  If you call this and submit another metric,
+    # the agent will start again.
+    #
+    # Calling stop will cause all metrics waiting to be sent to be
+    # discarded.  Don't call it unless you are expecting this behavior.
+    #
+    # agent.stop
+    #
+    def stop
+      disconnect
+      if @thread
+        @thread.kill
+        @thread = nil
+      end
+    end
+
     private
 
     def with_timeout(time, &block)
@@ -242,13 +256,7 @@ module Instrumental
 
     def send_command(cmd, *args)
       if enabled?
-        if @pid != Process.pid
-          logger.info "Detected fork"
-          @pid = Process.pid
-          @socket = nil
-          @queue = Queue.new
-          start_connection_worker
-        end
+        start_connection_worker if !running?
 
         cmd = "%s %s\n" % [cmd, args.collect { |a| a.to_s }.join(" ")]
         if @queue.size < MAX_BUFFER
@@ -293,6 +301,10 @@ module Instrumental
     def start_connection_worker
       if enabled?
         disconnect
+        @pid = Process.pid
+        @queue = Queue.new
+        @sync_mutex = Mutex.new
+        @failures = 0
         logger.info "Starting thread"
         @thread = Thread.new do
           run_worker_loop
@@ -364,23 +376,28 @@ module Instrumental
 
     def setup_cleanup_at_exit
       at_exit do
-        logger.info "Cleaning up agent, queue empty: #{@queue.empty?}, thread running: #{@thread.alive?}"
-        @allow_reconnect = false
-        logger.info "exit received, currently #{@queue.size} commands to be sent"
-        queue_message('exit')
-        begin
-          with_timeout(EXIT_FLUSH_TIMEOUT) { @thread.join }
-        rescue Timeout::Error
-          if @queue.size > 0
-            logger.error "Timed out working agent thread on exit, dropping #{@queue.size} metrics"
-          else
-            logger.error "Timed out Instrumental Agent, exiting"
+        if running?
+          logger.info "Cleaning up agent, queue empty: #{@queue.empty?}, thread running: #{@thread.alive?}"
+          @allow_reconnect = false
+          logger.info "exit received, currently #{@queue.size} commands to be sent"
+          queue_message('exit')
+          begin
+            with_timeout(EXIT_FLUSH_TIMEOUT) { @thread.join }
+          rescue Timeout::Error
+            if @queue.size > 0
+              logger.error "Timed out working agent thread on exit, dropping #{@queue.size} metrics"
+            else
+              logger.error "Timed out Instrumental Agent, exiting"
+            end
           end
         end
-
       end
     end
 
+    def running?
+      !@thread.nil? && @pid == Process.pid
+    end
+
     def disconnect
       if connected?
         logger.info "Disconnecting..."

data/lib/instrumental/version.rb

@@ -1,3 +1,3 @@
 module Instrumental
-  VERSION = '0.9.1'
+  VERSION = '0.9.5'
 end

data/spec/agent_spec.rb

@@ -12,6 +12,8 @@ describe Instrumental::Agent, "disabled" do
   end
 
   after do
+    @agent.stop
+    @agent = nil
     @server.stop
   end
 
@@ -43,26 +45,36 @@ describe Instrumental::Agent, "disabled" do
 end
 
 describe Instrumental::Agent, "enabled in test_mode" do
-  before do
+  before(:each) do
     @server = TestServer.new
     @agent = Instrumental::Agent.new('test_token', :collector => @server.host_and_port, :test_mode => true)
   end
 
-  after do
+  after(:each) do
+    @agent.stop
+    @agent = nil
     @server.stop
   end
 
-  it "should connect to the server" do
+  it "should not connect to the server" do
+    wait
+    @server.connect_count.should == 0
+  end
+
+  it "should connect to the server when the user sends a metric" do
+    @agent.increment("test.foo")
     wait
     @server.connect_count.should == 1
   end
 
   it "should announce itself, and include version and test_mode flag" do
+    @agent.increment("test.foo")
     wait
     @server.commands[0].should =~ /hello .*version .*test_mode true/
   end
 
   it "should authenticate using the token" do
+    @agent.increment("test.foo")
     wait
     @server.commands[1].should == "authenticate test_token"
   end
@@ -110,7 +122,7 @@ describe Instrumental::Agent, "enabled in test_mode" do
     wait
     @server.commands.last.should =~ /gauge time_ms_test .* #{now.to_i}/
     time = @server.commands.last.scan(/gauge time_ms_test (.*) #{now.to_i}/)[0][0].to_f
-    time.should > 100
+    time.should > 100.0
   end
 
   it "should report an increment" do
@@ -126,6 +138,17 @@ describe Instrumental::Agent, "enabled in test_mode" do
     wait
     @server.commands.join("\n").should include("notice #{tm.to_i} 0 Test note")
   end
+
+  it "should allow outgoing metrics to be stopped" do
+    tm = Time.now
+    @agent.increment("foo.bar", 1, tm)
+    @agent.stop
+    wait
+    @agent.increment("foo.baz", 1, tm)
+    wait
+    @server.commands.join("\n").should include("increment foo.baz 1 #{tm.to_i}")
+    @server.commands.join("\n").should_not include("increment foo.bar 1 #{tm.to_i}")
+  end
 end
 
 describe Instrumental::Agent, "enabled" do
@@ -135,20 +158,30 @@ describe Instrumental::Agent, "enabled" do
   end
 
   after do
+    @agent.stop
+    @agent = nil
     @server.stop
   end
 
-  it "should connect to the server" do
+  it "should not connect to the server" do
+    wait
+    @server.connect_count.should == 0
+  end
+
+  it "should connect to the server after sending a metric" do
+    @agent.increment("test.foo")
     wait
     @server.connect_count.should == 1
   end
 
   it "should announce itself, and include version" do
+    @agent.increment("test.foo")
     wait
     @server.commands[0].should =~ /hello .*version /
   end
 
   it "should authenticate using the token" do
+    @agent.increment("test.foo")
     wait
     @server.commands[1].should == "authenticate test_token"
   end
@@ -267,10 +300,10 @@ describe Instrumental::Agent, "enabled" do
   end
 
   it "should return nil if the user overflows the MAX_BUFFER" do
-    thread = @agent.instance_variable_get(:@thread)
-    thread.kill
     1.upto(Instrumental::Agent::MAX_BUFFER) do
       @agent.increment("test").should == 1
+      thread = @agent.instance_variable_get(:@thread)
+      thread.kill
     end
     @agent.increment("test").should be_nil
   end
@@ -324,6 +357,17 @@ describe Instrumental::Agent, "enabled" do
     @server.commands.join("\n").should_not include("notice Test note")
   end
 
+  it "should allow outgoing metrics to be stopped" do
+    tm = Time.now
+    @agent.increment("foo.bar", 1, tm)
+    @agent.stop
+    wait
+    @agent.increment("foo.baz", 1, tm)
+    wait
+    @server.commands.join("\n").should include("increment foo.baz 1 #{tm.to_i}")
+    @server.commands.join("\n").should_not include("increment foo.bar 1 #{tm.to_i}")
+  end
+
   it "should allow flushing pending values to the server" do
     1.upto(100) { @agent.gauge('a', rand(50)) }
     @agent.instance_variable_get(:@queue).size.should >= 100
@@ -336,18 +380,20 @@ end
 
 describe Instrumental::Agent, "connection problems" do
   after do
+    @agent.stop
     @server.stop
   end
 
   it "should automatically reconnect on disconnect" do
     @server = TestServer.new
     @agent = Instrumental::Agent.new('test_token', :collector => @server.host_and_port, :synchronous => false)
+    @agent.increment("reconnect_test", 1, 1234)
     wait
     @server.disconnect_all
-    @agent.increment('reconnect_test', 1, 1234) # triggers reconnect
+    @agent.increment('reconnect_test', 1, 5678) # triggers reconnect
     wait
     @server.connect_count.should == 2
-    @server.commands.last.should == "increment reconnect_test 1 1234"
+    @server.commands.last.should == "increment reconnect_test 1 5678"
   end
 
   it "should buffer commands when server is down" do
@@ -408,6 +454,11 @@ describe Instrumental::Agent, "enabled with sync option" do
     @agent = Instrumental::Agent.new('test_token', :collector => @server.host_and_port, :synchronous => true)
   end
 
+  after do
+    @agent.stop
+    @server.stop
+  end
+
   it "should send all data in synchronous mode" do
     with_constants('Instrumental::Agent::MAX_BUFFER' => 3) do
       5.times do |i|
@@ -421,4 +472,5 @@ describe Instrumental::Agent, "enabled with sync option" do
       @server.commands.should include("increment overflow_test 5 300")
     end
   end
+
 end

data/spec/test_server.rb

@@ -13,36 +13,50 @@ class TestServer
     @connections = []
     @commands = []
     @host = 'localhost'
+    @main_thread = nil
+    @client_threads = []
+    @fd_to_thread = {}
     listen if @options[:listen]
   end
 
+
   def listen
     @port ||= 10001
     @server = TCPServer.new(port)
-    Thread.new do
+    @main_thread = Thread.new do
       begin
         # puts "listening"
         loop do
-          socket = @server.accept
-          Thread.new do
-            @connect_count += 1
-            @connections << socket
+          client = @server.accept
+          @connections << client
+          @connect_count += 1
+          @fd_to_thread[client.to_i] = Thread.new(client) do |socket|
             # puts "connection received"
             loop do
-              command = socket.gets.strip
-              # puts "got: #{command}"
-              commands << command
-              if %w[hello authenticate].include?(command.split(' ')[0])
-                if @options[:response]
-                  if @options[:authenticate]
-                    socket.puts "ok"
-                  else
-                    socket.puts "gtfo"
+              begin
+                command = ""
+                while (c = socket.read(1)) != "\n"
+                  command << c unless c.nil?
+                end
+                if !command.empty?
+                  # puts "got: #{command}"
+                  commands << command
+                  if %w[hello authenticate].include?(command.split(' ')[0])
+                    if @options[:response]
+                      if @options[:authenticate]
+                        socket.puts "ok"
+                      else
+                        socket.puts "gtfo"
+                      end
+                    end
                   end
                 end
+              rescue Exception => e
+                break
               end
             end
           end
+          @client_threads << @fd_to_thread[client.to_i]
         end
       rescue Exception => err
         unless @stopping
@@ -67,10 +81,24 @@ class TestServer
   def stop
     @stopping = true
     disconnect_all
-    @server.close if @server
+    @main_thread.kill if @main_thread
+    @main_thread = nil
+    @client_threads.each { |thread| thread.kill }
+    @client_threads = []
+    begin
+      @server.close if @server
+    rescue Exception => e
+    end
   end
 
   def disconnect_all
-    @connections.each { |c| c.close rescue false }
+    @connections.each { |c| 
+      if (thr = @fd_to_thread[c.to_i])
+        thr.kill
+      end
+      @fd_to_thread.delete(c.to_i)
+      c.close rescue false 
+    }
+    @connections = []
   end
 end

metadata

@@ -1,10 +1,15 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: instrumental_agent
-version: !ruby/object:Gem::Version
-  version: 0.9.1
+version: !ruby/object:Gem::Version 
+  hash: 49
   prerelease: 
+  segments: 
+  - 0
+  - 9
+  - 5
+  version: 0.9.5
 platform: ruby
-authors:
+authors: 
 - Elijah Miller
 - Christopher Zelenak
 - Kristopher Chambers
@@ -12,92 +17,118 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-06 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: &70101951414580 !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+
+date: 2012-03-23 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   type: :development
   prerelease: false
-  version_requirements: *70101951414580
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: &70101951413720 !ruby/object:Gem::Requirement
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '2.0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id001
+  name: rake
+- !ruby/object:Gem::Dependency 
   type: :development
   prerelease: false
-  version_requirements: *70101951413720
-- !ruby/object:Gem::Dependency
-  name: fuubar
-  requirement: &70101951429080 !ruby/object:Gem::Requirement
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 0
+        version: "2.0"
+  requirement: *id002
+  name: rspec
+- !ruby/object:Gem::Dependency 
   type: :development
   prerelease: false
-  version_requirements: *70101951429080
-- !ruby/object:Gem::Dependency
-  name: guard
-  requirement: &70101951428440 !ruby/object:Gem::Requirement
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id003
+  name: fuubar
+- !ruby/object:Gem::Dependency 
   type: :development
   prerelease: false
-  version_requirements: *70101951428440
-- !ruby/object:Gem::Dependency
-  name: guard-rspec
-  requirement: &70101951427760 !ruby/object:Gem::Requirement
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id004
+  name: guard
+- !ruby/object:Gem::Dependency 
   type: :development
   prerelease: false
-  version_requirements: *70101951427760
-- !ruby/object:Gem::Dependency
-  name: growl
-  requirement: &70101951424880 !ruby/object:Gem::Requirement
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id005
+  name: guard-rspec
+- !ruby/object:Gem::Dependency 
   type: :development
   prerelease: false
-  version_requirements: *70101951424880
-- !ruby/object:Gem::Dependency
-  name: rb-fsevent
-  requirement: &70101951423500 !ruby/object:Gem::Requirement
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id006
+  name: growl
+- !ruby/object:Gem::Dependency 
   type: :development
   prerelease: false
-  version_requirements: *70101951423500
+  version_requirements: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id007
+  name: rb-fsevent
 description: Track anything.
-email:
+email: 
 - support@instrumentalapp.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .rspec
 - CHANGELOG.md
@@ -116,35 +147,38 @@ files:
 - spec/test_server.rb
 homepage: http://github.com/fastestforward/instrumental_agent
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
       - 0
-      hash: -1711513508284611167
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
       - 0
-      hash: -1711513508284611167
+      version: "0"
 requirements: []
+
 rubyforge_project: 
 rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Agent for reporting data to instrumentalapp.com
-test_files:
+test_files: 
 - spec/agent_spec.rb
 - spec/spec_helper.rb
 - spec/test_server.rb