mouth-instrument 1.0.0

data/.gitignore

@@ -0,0 +1,7 @@
+.rvmrc
+*.log
+*.pid
+log/*.log
+log/*.pid
+Gemfile.lock
+*.gem

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Jonathan Novak - http://github.com/cypriss
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# mouth-instrument
+
+Mouth-instrument is a very lightweight Ruby gem that you can use to instrument your apps to collect metrics.  It sends these metrics via UDP to a [mouth](http://www.github.com/cypriss/mouth) daemon for storage and analysis.
+
+## What is Mouth?
+
+[Mouth](http://www.github.com/cypriss/mouth) is a Ruby daemon that collects metrics via UDP and stores them in Mongo.  It comes with a modern UI that allows you to view graphs and create dashboards of these statistics.
+
+## Using mouth-instrument
+
+First, install the gem via your Gemfile or do so manually:
+
+    gem install mouth-instrument
+
+Then, include it in your app:
+
+    require 'mouth-instrument'
+
+Configure it to point to your daemon. In a Rails app, you might want to put this in config/initializers/mouth.rb
+
+    Mouth.daemon_hostport = "localhost:8889"
+
+Then, instrument your app:
+
+    # Count things like this:
+    Mouth.increment("myapp.occurrences")          # Basic
+    Mouth.increment("myapp.occurrences", 10)      # Occurrences occurred 10 times!
+    Mouth.increment("myapp.occurrences", 1, 0.1)  # Sample at a 1/10 rate.  Lose a bit of accuracy, but sends less packets.  Good for super-high volume metrics.
+    
+    # Measure timings like this:
+    Mouth.measure("myapp.happening") do
+      do_happening!
+    end
+    
+    # Or, like this (23.9 is in milliseconds):
+    Mouth.measure("myapp.happening", 23.9)
+    
+    # Gauge values like this:
+    Mouth.gauge("myapp.subscriber_count", 1230) # I have 1230 customers right now!
+
+## View your metrics
+
+Please see the [Mouth](http://www.github.com/cypriss/mouth) project for more information!  This gem plays a supporting role to core Mouth gem.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+Rake::TestTask.new('test') do |t|
+  t.ruby_opts << '-rubygems'
+  t.libs << 'lib'
+  t.test_files = FileList['test/*.rb']
+end
+
+task :default => :test

data/lib/mouth-instrument.rb

@@ -0,0 +1,63 @@
+require 'socket'
+require 'benchmark'
+
+module Mouth
+  
+  INSTRUMENT_VERSION = '1.0.0'
+  
+  unless self.respond_to?(:measure)
+    class << self
+      attr_accessor :daemon_host, :daemon_port, :disabled
+      
+      # Mouth.server = 'localhost:1234'
+      def daemon_hostport=(hostport)
+        self.daemon_host, port = hostport.split(':')
+        self.daemon_port = port.to_i
+      end
+      
+      def daemon_host
+        @daemon_host || "localhost"
+      end
+      
+      def daemon_port
+        @daemon_port || 8889
+      end
+
+      def measure(key, milli = nil)
+        result = nil
+        ms = milli || (Benchmark.realtime { result = yield } * 1000).to_i
+
+        write(key, ms, :ms)
+
+        result
+      end
+
+      def increment(key, delta = 1, sample_rate = nil)
+        write(key, delta, :c, sample_rate)
+      end
+      
+      def gauge(key, value)
+        write(key, value, :g)
+      end
+
+      protected
+
+      def socket
+        @socket ||= UDPSocket.new
+      end
+
+      def write(k, v, op, sample_rate = nil)
+        return if self.disabled
+        if sample_rate
+          sample_rate = 1 if sample_rate > 1
+          return if rand > sample_rate
+        end
+        
+        command = "#{k}:#{v}|#{op}"
+        command << "|@#{sample_rate}" if sample_rate
+        
+        socket.send(command, 0, self.daemon_host, self.daemon_port) 
+      end
+    end
+  end
+end

data/mouth-instrument.gemspec

@@ -0,0 +1,14 @@
+require './lib/mouth-instrument'
+
+Gem::Specification.new do |s|
+  s.name = 'mouth-instrument'
+  s.version = Mouth::INSTRUMENT_VERSION
+  s.author = 'Jonathan Novak'
+  s.email = 'jnovak@gmail.com'
+  s.homepage = 'http://github.com/cypriss/mouth-instrument'
+  s.summary = 'Instrument your app to send metrics to a Mouth'
+  s.description = 'Instrument your app to send metrics to a Mouth.  Sends UDP packets to Mouth for Counters, Timers, and Gauges.'
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files test`.split("\n")
+end

data/test/mouth-instrument_test.rb

@@ -0,0 +1,79 @@
+$LOAD_PATH.unshift 'test'
+require 'test_helper'
+
+class MouthInstrumentTest < Test::Unit::TestCase
+  def setup
+    @@udp ||= UDPSocket.new.tap do |u|
+      u.bind("127.0.0.1", 32123)
+    end
+    @udp = @@udp
+    Mouth.daemon_hostport = "127.0.0.1:32123"
+  end
+  
+  def test_increment
+    Mouth.increment("bob")
+    
+    res =  @udp.recvfrom(1024)
+    assert_equal "bob:1|c", res[0]
+  end
+  
+  def test_increment_delta
+    Mouth.increment("bob.rob", 123)
+    
+    res =  @udp.recvfrom(1024)
+    assert_equal "bob.rob:123|c", res[0]
+  end
+  
+  def test_increment_sample
+    # Clear out anything on the UDP packet
+    100.times { @udp.recvfrom_nonblock(1024) } rescue nil
+    
+    pack = nil
+    nothing = false
+     
+    100.times do
+      Mouth.increment("bob.rob/blah-haha", 123, 0.1)
+      
+      begin
+        pack ||= @udp.recvfrom_nonblock(1024)
+        break if nothing
+      rescue IO::WaitReadable
+        nothing = true
+      end
+    end
+    
+    assert nothing
+    assert_equal "bob.rob/blah-haha:123|c|@0.1", pack[0]
+  end
+  
+  def test_gauge
+    Mouth.gauge("bob", 77)
+    
+    res =  @udp.recvfrom(1024)
+    assert_equal "bob:77|g", res[0]
+  end
+  
+  def test_measure
+    Mouth.measure("bob", 1.2)
+    
+    res =  @udp.recvfrom(1024)
+    assert_equal "bob:1.2|ms", res[0]
+  end
+  
+  def test_measure_block
+    result = Mouth.measure("bob") do
+      sleep 0.2
+      9876
+    end
+    
+    assert_equal 9876, result
+    
+    res =  @udp.recvfrom(1024)[0]
+    m = res.match(/bob:(\d+)\|ms/)
+    assert m
+    
+    # Make sure the number is within a resonable range
+    assert m[1].to_i > 180
+    assert m[1].to_i < 220
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'test/unit'
+require 'pp'
+
+$LOAD_PATH.unshift 'lib'
+require 'mouth-instrument'

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: mouth-instrument
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Jonathan Novak
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-07 00:00:00.000000000Z
+dependencies: []
+description: Instrument your app to send metrics to a Mouth.  Sends UDP packets to
+  Mouth for Counters, Timers, and Gauges.
+email: jnovak@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/mouth-instrument.rb
+- mouth-instrument.gemspec
+- test/mouth-instrument_test.rb
+- test/test_helper.rb
+homepage: http://github.com/cypriss/mouth-instrument
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Instrument your app to send metrics to a Mouth
+test_files:
+- test/mouth-instrument_test.rb
+- test/test_helper.rb