jashmenn-statsd-instrument 1.1.3

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - ree
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+group :test do
+  gem 'rake'
+end
+
+# Specify your gem's dependencies in statsd-instrument.gemspec
+gemspec
+
+gem 'SystemTimer', :platform => :mri_18, :require => ''

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Shopify
+
+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,156 @@
+# StatsD client for Ruby apps
+
+![Built on Travis](https://secure.travis-ci.org/Shopify/statsd-instrument.png?branch=master)
+
+This is a ruby client for statsd (http://github.com/etsy/statsd). It provides a lightweight way to track and measure metrics in your application. 
+
+We call out to statsd by sending data over a UDP socket. UDP sockets are fast, but unreliable, there is no guarantee that your data will ever arrive at it's location. In other words, fire and forget. This is perfect for this use case because it means your code doesn't get bogged down trying to log statistics. We send data to statsd several times per request and haven't noticed a performance hit.
+
+The fact that all of your stats data may not make it into statsd is no issue. Graphite (the graph database that statsd is built on) will only show you trends in your data. Internally it only keeps enough data to satisfy the levels of granularity we specify. As well as satisfying it's requirement as a fixed size database. We can throw as much data at it as we want it and it will do it's best to show us the trends over time and get rid of the fluff.
+
+For Shopify, our retention periods are:
+
+1. 10 seconds of granularity for the last 6 hours
+2. 60 seconds of granularity for the last week
+3. 10 minutes of granularity for the last 5 years
+
+This is the same as what Etsy uses (mentioned in the README for http://github.com/etsy/statsd).
+
+## Configuration
+
+``` ruby
+StatsD.server = 'statsd.myservice.com:8125'
+StatsD.logger = Rails.logger
+StatsD.mode = :production
+StatsD.prefix = 'my_app' # An optional prefix to be added to each stat.
+StatsD.default_sample_rate = 0.1 # Sample 10% of events. By default all events are reported.
+```
+
+If you set the mode to anything besides production then the library will print its calls to the logger, rather than sending them over the wire.
+
+## StatsD keys
+
+StatsD keys look like 'admin.logins.api.success'. Each dot in the key represents a 'folder' in the graphite interface. You can include any data you want in the keys.
+
+## Usage
+
+### StatsD.measure
+
+Lets you benchmark how long the execution of a specific method takes.
+
+``` ruby
+# You can pass a key and a ms value
+StatsD.measure('GoogleBase.insert', 2.55)
+
+# or more commonly pass a block that calls your code
+StatsD.measure('GoogleBase.insert') do
+  GoogleBase.insert(product)
+end
+```
+
+Rather than using this method directly it's more common to use the metaprogramming methods made available.
+
+``` ruby
+GoogleBase.extend StatsD::Instrument
+GoogleBase.statsd_measure :insert, 'GoogleBase.insert'
+```
+		
+### StatsD.increment
+
+Lets you increment a key in statsd to keep a count of something. If the specified key doesn't exist it will create it for you.
+
+``` ruby
+# increments default to +1
+StatsD.increment('GoogleBase.insert')
+# you can also specify how much to increment the key by
+StatsD.increment('GoogleBase.insert', 10)
+# you can also specify a sample rate, so only 1/10 of events
+# actually get to statsd. Useful for very high volume data
+StatsD.increment('GoogleBase.insert', 1, 0.1)
+```
+
+Again it's more common to use the metaprogramming methods.
+
+## Metaprogramming Methods
+
+As mentioned, it's most common to use the provided metaprogramming methods. This lets you define all of your instrumentation in one file and not litter your code with instrumentation details. You should enable a class for instrumentation by extending it with the `StatsD::Instrument` class.
+
+``` ruby
+GoogleBase.extend StatsD::Instrument
+```
+
+Then use the methods provided below to instrument methods in your class.
+
+### statsd\_count
+
+This will increment the given key even if the method doesn't finish (ie. raises).
+
+``` ruby
+GoogleBase.statsd_count :insert, 'GoogleBase.insert'
+```
+
+Note how I used the 'GoogleBase.insert' key above when measuring this method, and I reused here when counting the method calls. StatsD automatically separates these two kinds of stats into namespaces so there won't be a key collision here.
+
+### statsd\_count\_if
+
+This will only increment the given key if the method executes successfully.
+
+``` ruby
+GoogleBase.statsd_count_if :insert, 'GoogleBase.insert'
+```
+
+So now, if GoogleBase#insert raises an exception or returns false (ie. result == false), we won't increment the key. If you want to define what success means for a given method you can pass a block that takes the result of the method.
+
+``` ruby
+GoogleBase.statsd_count_if :insert, 'GoogleBase.insert' do |response|
+  response.code == 200
+end
+```
+
+In the above example we will only increment the key in statsd if the result of the block returns true. So the method is returning a Net::HTTP response and we're checking the status code.
+
+### statsd\_count\_success
+
+Similar to statsd_count_if, except this will increment one key in the case of success and another key in the case of failure.
+
+``` ruby
+GoogleBase.statsd_count_success :insert, 'GoogleBase.insert'
+```
+
+So if this method fails execution (raises or returns false) we'll increment the failure key ('GoogleBase.insert.failure'), otherwise we'll increment the success key ('GoogleBase.insert.success'). Notice that we're modifying the given key before sending it to statsd.
+
+Again you can pass a block to define what success means.
+
+``` ruby
+GoogleBase.statsd_count_success :insert, 'GoogleBase.insert' do |response|
+  response.code == 200
+end
+```
+
+### Instrumenting Class Methods
+
+You can instrument class methods, just like instance methods, using the metaprogramming methods. You simply have to configure the instrumentation on the singleton class of the Class you want to instrument.
+
+```ruby
+AWS::S3::Base.singleton_class.extend StatsD::Instrument
+AWS::S3::Base.singleton_class.statsd_measure :request, 'S3.request'
+```
+
+## Reliance on DNS
+Out of the box StatsD is set up to be unidirectional fire-and-forget over UDP. Configuring the StatsD host to be a non-ip will trigger a DNS lookup (ie synchronous round trip network call) for each metric sent. This can be particularly problematic in clouds that have a shared DNS infrastructure such as AWS.
+
+### Common Workarounds
+1. Using an IP avoids the DNS lookup but generally requires an application deploy to change.
+2. Hardcoding the DNS/IP pair in /etc/hosts allows the IP to change without redeploying your application but fails to scale as the number of servers increases.
+3. Installing caching software such as nscd that uses the DNS TTL avoids most DNS lookups but makes the exact moment of change indeterminate.
+
+## Compatibility
+
+Tested on:
+
+* Ruby 1.8.7
+* Ruby Enterprise Edition 1.8.7
+* Ruby 1.9.2
+* Ruby 1.9.3
+
+Ruby 1.9 compatibility is planned for the long term. Your mileage may vary with other Ruby environments.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+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/statsd-instrument.rb

@@ -0,0 +1 @@
+require 'statsd/instrument'

data/lib/statsd/instrument.rb

@@ -0,0 +1,157 @@
+require 'socket'
+require 'benchmark'
+require 'timeout'
+
+class << Benchmark
+  def ms
+    1000 * realtime { yield }
+  end
+end
+
+
+module StatsD
+  class << self
+    attr_accessor :host, :port, :mode, :logger, :enabled, :default_sample_rate,
+                  :prefix
+  end
+  self.enabled = true
+  self.default_sample_rate = 1
+  
+  TimeoutClass = defined?(::SystemTimer) ? ::SystemTimer : ::Timeout
+
+  # StatsD.server = 'localhost:1234'
+  def self.server=(conn)
+    self.host, port = conn.split(':')
+    self.port = port.to_i
+  end
+
+  module Instrument
+    def statsd_measure(method, name)
+      add_to_method(method, name, :measure) do |old_method, new_method, metric_name, *args|
+        define_method(new_method) do |*args|
+          StatsD.measure(metric_name) { send(old_method, *args) }
+        end
+      end
+    end
+
+    def statsd_count_success(method, name)
+      add_to_method(method, name, :count_success) do |old_method, new_method, metric_name|
+        define_method(new_method) do |*args|
+          begin
+            truthiness = result = send(old_method, *args)
+          rescue
+            truthiness = false
+            raise
+          else
+            truthiness = (yield(result) rescue false) if block_given?
+            result
+          ensure
+            StatsD.increment("#{metric_name}." + (truthiness == false ? 'failure' : 'success'))
+          end
+        end
+      end
+    end
+
+    def statsd_count_if(method, name)
+      add_to_method(method, name, :count_if) do |old_method, new_method, metric_name|
+        define_method(new_method) do |*args|
+          begin
+            truthiness = result = send(old_method, *args)
+          rescue
+            truthiness = false
+            raise
+          else
+            truthiness = (yield(result) rescue false) if block_given?
+            result
+          ensure
+            StatsD.increment(metric_name) if truthiness
+          end
+        end
+      end
+    end
+
+    def statsd_count(method, name)
+      add_to_method(method, name, :count) do |old_method, new_method, metric_name|
+        define_method(new_method) do |*args|
+          StatsD.increment(metric_name)
+          send(old_method, *args)
+        end
+      end
+    end
+
+    private
+    def add_to_method(method, name, action, &block)
+      metric_name = name
+
+      method_name_without_statsd = :"#{method}_for_#{action}_on_#{self.name}_without_#{name}"
+      # raw_ssl_request_for_measure_on_FedEx_without_ActiveMerchant.Shipping.#{self.class.name}.ssl_request
+
+      method_name_with_statsd = :"#{method}_for_#{action}_on_#{self.name}_with_#{name}"
+      # raw_ssl_request_for_measure_on_FedEx_with_ActiveMerchant.Shipping.#{self.class.name}.ssl_request
+
+      raise ArgumentError, "already instrumented #{method} for #{self.name}" if method_defined? method_name_without_statsd
+      raise ArgumentError, "could not find method #{method} for #{self.name}" unless method_defined?(method) || private_method_defined?(method)
+
+      alias_method method_name_without_statsd, method
+      yield method_name_without_statsd, method_name_with_statsd, metric_name
+      alias_method method, method_name_with_statsd
+    end
+  end
+
+  # glork:320|ms
+  def self.measure(key, milli = nil)
+    result = nil
+    ms = milli || Benchmark.ms do
+      result = yield 
+    end
+
+    write(key, ms, :ms)
+    result
+  end
+
+  # gorets:1|c
+  def self.increment(key, delta = 1, sample_rate = default_sample_rate)
+    write(key, delta, :incr, sample_rate)
+  end
+
+  # gerbals:30|g
+  def self.gauge(key, amount)
+    write(key, amount, :gauge)
+  end
+
+  private
+
+  def self.socket
+    @socket ||= UDPSocket.new
+  end
+
+  def self.write(k,v,op, sample_rate = default_sample_rate)
+    return unless enabled
+    return if sample_rate < 1 && rand > sample_rate
+
+    command = "#{self.prefix + '.' if self.prefix}#{k}:#{v}"
+    case op
+    when :incr
+      command << '|c'
+    when :ms
+      command << '|ms'
+    when :gauge
+      command << '|g'
+    end
+
+    command << "|@#{sample_rate}" if sample_rate < 1
+
+    if mode.to_s == 'production'
+      socket_wrapper { socket.send(command, 0, host, port) }
+    else
+      logger.info "[StatsD] #{command}"
+    end
+  end
+
+  def self.socket_wrapper(options = {})
+    TimeoutClass.timeout(options.fetch(:timeout, 0.1)) { yield }
+  rescue Timeout::Error, SocketError, IOError, SystemCallError => e
+    logger.error e
+  end
+end
+

data/statsd-instrument.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |s|
+  s.name        = "jashmenn-statsd-instrument"
+  s.version     = '1.1.3'
+  s.authors     = ["Jesse Storimer"]
+  s.email       = ["jesse@shopify.com"]
+  s.homepage    = "http://github.com/shopify/statsd-instrument"
+
+  s.summary     = %q{A StatsD client for Ruby apps}
+  s.description = %q{A StatsD client for Ruby apps. Provides metaprogramming methods to inject StatsD instrumentation into your code.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.add_development_dependency 'mocha'
+end

data/test/statsd-instrument_test.rb

@@ -0,0 +1,230 @@
+# Allow testing with the SystemTimer gem on 1.8
+if RUBY_VERSION =~ /^1.8/
+  puts "Loading SystemTimer gem"
+  require 'system_timer'
+end
+
+require 'statsd-instrument'
+require 'test/unit'
+require 'mocha'
+require 'logger'
+
+StatsD.logger = Logger.new('/dev/null')
+
+module ActiveMerchant; end
+class ActiveMerchant::Base
+  def ssl_post(arg)
+    if arg
+      'OK'
+    else
+      raise 'Not OK'
+    end
+  end
+end
+
+class ActiveMerchant::Gateway < ActiveMerchant::Base
+  def purchase(arg)
+    ssl_post(arg)
+    true
+  rescue
+    false
+  end
+
+  def self.sync
+    true
+  end 
+
+  def self.singleton_class
+    class << self; self; end
+  end
+end
+
+class ActiveMerchant::UniqueGateway < ActiveMerchant::Base
+  def ssl_post(arg)
+    {:success => arg}
+  end
+
+  def purchase(arg)
+    ssl_post(arg)
+  end
+end
+
+ActiveMerchant::Base.extend StatsD::Instrument
+
+class StatsDTest < Test::Unit::TestCase
+  def setup
+    StatsD.mode = nil
+    StatsD.stubs(:increment)
+  end
+
+  def test_statsd_count_if
+    ActiveMerchant::Gateway.statsd_count_if :ssl_post, 'ActiveMerchant.Gateway.if'
+
+    StatsD.expects(:increment).with(includes('if')).once
+    ActiveMerchant::Gateway.new.purchase(true)
+    ActiveMerchant::Gateway.new.purchase(false)
+  end
+
+  def test_statsd_count_if_with_block
+    ActiveMerchant::UniqueGateway.statsd_count_if :ssl_post, 'ActiveMerchant.Gateway.block' do |result|
+      result[:success]
+    end
+
+    StatsD.expects(:increment).with(includes('block')).once
+    ActiveMerchant::UniqueGateway.new.purchase(true)
+    ActiveMerchant::UniqueGateway.new.purchase(false)
+  end
+
+  def test_statsd_count_success
+    ActiveMerchant::Gateway.statsd_count_success :ssl_post, 'ActiveMerchant.Gateway'
+
+    StatsD.expects(:increment).with(includes('success'))
+    ActiveMerchant::Gateway.new.purchase(true)
+
+    StatsD.expects(:increment).with(includes('failure'))
+    ActiveMerchant::Gateway.new.purchase(false)
+  end
+
+  def test_statsd_count_success_with_block
+    ActiveMerchant::UniqueGateway.statsd_count_success :ssl_post, 'ActiveMerchant.Gateway' do |result|
+      result[:success]
+    end
+
+    StatsD.expects(:increment).with(includes('success'))
+    ActiveMerchant::UniqueGateway.new.purchase(true)
+
+    StatsD.expects(:increment).with(includes('failure'))
+    ActiveMerchant::UniqueGateway.new.purchase(false)
+  end
+
+  def test_statsd_count
+    ActiveMerchant::Gateway.statsd_count :ssl_post, 'ActiveMerchant.Gateway.ssl_post'
+
+    StatsD.expects(:increment).with(includes('ssl_post'))
+    ActiveMerchant::Gateway.new.purchase(true)
+  end
+
+  def test_statsd_measure
+    ActiveMerchant::UniqueGateway.statsd_measure :ssl_post, 'ActiveMerchant.Gateway.ssl_post'
+
+    StatsD.expects(:write).with('ActiveMerchant.Gateway.ssl_post', is_a(Float), :ms).returns({:success => true})
+    ActiveMerchant::UniqueGateway.new.purchase(true)
+  end
+
+  def test_instrumenting_class_method
+    ActiveMerchant::Gateway.singleton_class.extend StatsD::Instrument
+    ActiveMerchant::Gateway.singleton_class.statsd_count :sync, 'ActiveMerchant.Gateway.sync'
+
+    StatsD.expects(:increment).with(includes('sync'))
+    ActiveMerchant::Gateway.sync
+  end
+
+  def test_count_with_sampling
+    StatsD.unstub(:increment)
+    StatsD.stubs(:rand).returns(0.6)
+    StatsD.logger.expects(:info).never
+
+    StatsD.increment('sampling.foo.bar', 1, 0.1)
+  end
+
+  def test_count_with_successful_sample
+    StatsD.unstub(:increment)
+    StatsD.stubs(:rand).returns(0.01)
+    StatsD.logger.expects(:info).once.with do |string|
+      string.include?('@0.1')
+    end
+
+    StatsD.increment('sampling.foo.bar', 1, 0.1)
+  end
+
+  def test_production_mode_should_use_udp_socket
+    StatsD.unstub(:increment)
+
+    StatsD.mode = :production
+    StatsD.server = 'localhost:123'
+    UDPSocket.any_instance.expects(:send)
+
+    StatsD.increment('fooz')
+    StatsD.mode = :test
+  end
+
+  def test_should_not_write_when_disabled
+    StatsD.enabled = false
+    StatsD.expects(:logger).never
+    StatsD.increment('fooz')
+    StatsD.enabled = true
+  end
+
+  def test_statsd_mode
+    StatsD.unstub(:increment)
+    StatsD.logger.expects(:info).once
+    StatsD.expects(:socket_wrapper).twice
+    StatsD.mode = :foo
+    StatsD.increment('foo')
+    StatsD.mode = :production
+    StatsD.increment('foo')
+    StatsD.mode = 'production'
+    StatsD.increment('foo')
+  end
+
+  def test_statsd_prefix
+    StatsD.unstub(:increment)
+    StatsD.prefix = 'my_app'
+    StatsD.logger.expects(:info).once.with do |string|
+      string.include?('my_app.foo')
+    end
+    StatsD.logger.expects(:info).once.with do |string|
+      string.include?('food')
+    end
+    StatsD.increment('foo')
+    StatsD.prefix = nil
+    StatsD.increment('food')
+  end
+
+  def test_statsd_measure_with_explicit_value
+    StatsD.expects(:write).with('values.foobar', 42, :ms)
+
+    StatsD.measure('values.foobar', 42)
+  end
+
+  def test_socket_error_should_not_raise
+    StatsD.mode = :production
+    UDPSocket.any_instance.expects(:send).raises(SocketError)
+    StatsD.measure('values.foobar', 42)
+    StatsD.mode = :test
+  end
+
+  def test_timeout_error_should_not_raise
+    StatsD.mode = :production
+    UDPSocket.any_instance.expects(:send).raises(Timeout::Error)
+    StatsD.measure('values.foobar', 42)
+    StatsD.mode = :test
+  end
+
+  def test_system_call_error_should_not_raise
+    StatsD.mode = :production
+    UDPSocket.any_instance.expects(:send).raises(Errno::ETIMEDOUT)
+    StatsD.measure('values.foobar', 42)
+    StatsD.mode = :test
+  end
+
+  def test_io_error_should_not_raise
+    StatsD.mode = :production
+    UDPSocket.any_instance.expects(:send).raises(IOError)
+    StatsD.measure('values.foobar', 42)
+    StatsD.mode = :test
+  end
+
+  def test_long_request_should_timeout
+    StatsD.mode = :production
+    UDPSocket.any_instance.expects(:send).yields do
+      begin
+        Timeout.timeout(0.5) { sleep 1 }
+      rescue Timeout::Error
+        raise "Allowed long running request"
+      end
+    end
+    StatsD.measure('values.foobar', 42)
+    StatsD.mode = :test
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification 
+name: jashmenn-statsd-instrument
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 1
+  - 3
+  version: 1.1.3
+platform: ruby
+authors: 
+- Jesse Storimer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-04-05 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: A StatsD client for Ruby apps. Provides metaprogramming methods to inject StatsD instrumentation into your code.
+email: 
+- jesse@shopify.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/statsd-instrument.rb
+- lib/statsd/instrument.rb
+- statsd-instrument.gemspec
+- test/statsd-instrument_test.rb
+has_rdoc: true
+homepage: http://github.com/shopify/statsd-instrument
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A StatsD client for Ruby apps
+test_files: 
+- test/statsd-instrument_test.rb