statsd-ruby 1.0.0 → 1.1.0

data/README.rdoc

@@ -1,4 +1,4 @@
-= statsd-ruby {<img src="https://secure.travis-ci.org/reinh/statsd-ruby.png" />}[http://travis-ci.org/reinh/statsd-ruby]
+= statsd-ruby {<img src="https://secure.travis-ci.org/reinh/statsd.png" />}[http://travis-ci.org/reinh/statsd]
 
 A Ruby client for {StatsD}[https://github.com/etsy/statsd]
 
@@ -7,6 +7,23 @@ A Ruby client for {StatsD}[https://github.com/etsy/statsd]
 Bundler:
   gem "statsd-ruby", :require => "statsd"
 
+= Basic Usage
+
+  # Set up a global Statsd client for a server on localhost:9125
+  $statsd = Statsd.new 'localhost', 9125
+
+  # Send some stats
+  $statsd.increment 'garets'
+  $statsd.timing 'glork', 320
+  $statsd.gauge 'bork', 100
+
+  # Use {#time} to time the execution of a block
+  $statsd.time('account.activate') { @account.activate! }
+
+  # Create a namespaced statsd client and increment 'account.activate'
+  statsd = Statsd.new('localhost').tap{|sd| sd.namespace = 'account'}
+  statsd.increment 'activate'
+
 = Testing
 
 Run the specs with <tt>rake spec</tt>

data/lib/statsd.rb

@@ -1,4 +1,5 @@
 require 'socket'
+require 'forwardable'
 
 # = Statsd: A Statsd client (https://github.com/etsy/statsd)
 #
@@ -21,6 +22,68 @@ require 'socket'
 # users either mutex around their Statsd object, or create separate objects for
 # each namespace / host+port combination.
 class Statsd
+
+  # = Batch: A batching statsd proxy
+  #
+  # @example Batch a set of instruments using Batch and manual flush:
+  #   $statsd = Statsd.new 'localhost', 8125
+  #   batch = Statsd::Batch.new($statsd)
+  #   batch.increment 'garets'
+  #   batch.timing 'glork', 320
+  #   batch.gauge 'bork', 100
+  #   batch.flush
+  #
+  # Batch is a subclass of Statsd, but with a constructor that proxies to a
+  # normal Statsd instance. It has it's own batch_size and namespace parameters
+  # (that inherit defaults from the supplied Statsd instance). It is recommended
+  # that some care is taken if setting very large batch sizes. If the batch size
+  # exceeds the allowed packet size for UDP on your network, communication
+  # troubles may occur and data will be lost.
+  class Batch < Statsd
+
+    extend Forwardable
+    def_delegators :@statsd,
+      :namespace, :namespace=, :host, :port, :prefix, :postfix
+
+    attr_accessor :batch_size
+
+    # @param [Statsd] requires a configured Statsd instance
+    def initialize(statsd)
+      @statsd = statsd
+      @batch_size = statsd.batch_size
+      @backlog = []
+    end
+
+    # @yields [Batch] yields itself
+    #
+    # A convenience method to ensure that data is not lost in the event of an
+    # exception being thrown. Batches will be transmitted on the parent socket
+    # as soon as the batch is full, and when the block finishes.
+    def easy
+      yield self
+    ensure
+      flush
+    end
+
+    def flush
+      unless @backlog.empty?
+        @statsd.send_to_socket @backlog.join("\n")
+        @backlog.clear
+      end
+    end
+
+    protected
+
+    def send_to_socket(message)
+      @backlog << message
+      if @backlog.size >= @batch_size
+        flush
+      end
+    end
+
+  end
+
+
   # A namespace to prepend to all statsd calls.
   attr_reader :namespace
 
@@ -30,6 +93,15 @@ class Statsd
   # StatsD port. Defaults to 8125.
   attr_reader :port
 
+  # StatsD namespace prefix, generated from #namespace
+  attr_reader :prefix
+
+  # The default batch size for new batches (default: 10)
+  attr_accessor :batch_size
+
+  # a postfix to append to all metrics
+  attr_reader :postfix
+
   class << self
     # Set to a standard logger instance to enable debug logging.
     attr_accessor :logger
@@ -40,6 +112,8 @@ class Statsd
   def initialize(host = '127.0.0.1', port = 8125)
     self.host, self.port = host, port
     @prefix = nil
+    @batch_size = 10
+    @postfix = nil
   end
 
   # @attribute [w] namespace
@@ -49,6 +123,10 @@ class Statsd
     @prefix = "#{namespace}."
   end
 
+  def postfix=(pf)
+    @postfix = ".#{pf}"
+  end
+
   # @attribute [w] host
   #   Writes are not thread safe.
   def host=(host)
@@ -95,7 +173,7 @@ class Statsd
   # counters.
   #
   # @param [String] stat stat name.
-  # @param [Numeric] gauge value.
+  # @param [Numeric] value gauge value.
   # @param [Numeric] sample_rate sample rate, 1 for always
   # @example Report the current user count:
   #   $statsd.gauge('user.count', User.count)
@@ -130,17 +208,22 @@ class Statsd
     result
   end
 
-  private
-
-  def send_stats(stat, delta, type, sample_rate=1)
-    if sample_rate == 1 or rand < sample_rate
-      # Replace Ruby module scoping with '.' and reserved chars (: | @) with underscores.
-      stat = stat.to_s.gsub('::', '.').tr(':|@', '_')
-      rate = "|@#{sample_rate}" unless sample_rate == 1
-      send_to_socket "#{@prefix}#{stat}:#{delta}|#{type}#{rate}"
-    end
+  # Creates and yields a Batch that can be used to batch instrument reports into
+  # larger packets. Batches are sent either when the packet is "full" (defined
+  # by batch_size), or when the block completes, whichever is the sooner.
+  #
+  # @yield [Batch] a statsd subclass that collects and batches instruments
+  # @example Batch two instument operations:
+  #   $statsd.batch do |batch|
+  #     batch.increment 'sys.requests'
+  #     batch.gauge('user.count', User.count)
+  #   end
+  def batch(&block)
+    Batch.new(self).easy &block
   end
 
+  protected
+
   def send_to_socket(message)
     self.class.logger.debug { "Statsd: #{message}" } if self.class.logger
     socket.send(message, 0, @host, @port)
@@ -149,6 +232,17 @@ class Statsd
     nil
   end
 
+  private
+
+  def send_stats(stat, delta, type, sample_rate=1)
+    if sample_rate == 1 or rand < sample_rate
+      # Replace Ruby module scoping with '.' and reserved chars (: | @) with underscores.
+      stat = stat.to_s.gsub('::', '.').tr(':|@', '_')
+      rate = "|@#{sample_rate}" unless sample_rate == 1
+      send_to_socket "#{prefix}#{stat}#{postfix}:#{delta}|#{type}#{rate}"
+    end
+  end
+
   def socket
     Thread.current[:statsd_socket] ||= UDPSocket.new
   end

data/spec/helper.rb

@@ -17,7 +17,7 @@ class FakeUDPSocket
   end
 
   def recv
-    res = @buffer.shift
+    @buffer.shift
   end
 
   def clear

data/spec/statsd_spec.rb

@@ -113,12 +113,12 @@ describe Statsd do
 
   describe "#time" do
     it "should format the message according to the statsd spec" do
-      @statsd.time('foobar') { sleep(0.001); 'test' }
-      @socket.recv.must_equal ['foobar:1|ms']
+      @statsd.time('foobar') { 'test' }
+      @socket.recv.must_equal ['foobar:0|ms']
     end
 
     it "should return the result of the block" do
-      result = @statsd.time('foobar') { sleep(0.001); 'test' }
+      result = @statsd.time('foobar') { 'test' }
       result.must_equal 'test'
     end
 
@@ -126,8 +126,8 @@ describe Statsd do
       before { class << @statsd; def rand; 0; end; end } # ensure delivery
 
       it "should format the message according to the statsd spec" do
-        result = @statsd.time('foobar', 0.5) { sleep(0.001); 'test' }
-        @socket.recv.must_equal ['foobar:1|ms|@0.5']
+        @statsd.time('foobar', 0.5) { 'test' }
+        @socket.recv.must_equal ['foobar:0|ms|@0.5']
       end
     end
   end
@@ -189,6 +189,30 @@ describe Statsd do
     end
   end
 
+  describe "with postfix" do
+    before { @statsd.postfix = 'ip-23-45-56-78' }
+
+    it "should add postfix to increment" do
+      @statsd.increment('foobar')
+      @socket.recv.must_equal ['foobar.ip-23-45-56-78:1|c']
+    end
+
+    it "should add postfix to decrement" do
+      @statsd.decrement('foobar')
+      @socket.recv.must_equal ['foobar.ip-23-45-56-78:-1|c']
+    end
+
+    it "should add namespace to timing" do
+      @statsd.timing('foobar', 500)
+      @socket.recv.must_equal ['foobar.ip-23-45-56-78:500|ms']
+    end
+
+    it "should add namespace to gauge" do
+      @statsd.gauge('foobar', 500)
+      @socket.recv.must_equal ['foobar.ip-23-45-56-78:500|g']
+    end
+  end
+
   describe "with logging" do
     require 'stringio'
     before { Statsd.logger = Logger.new(@log = StringIO.new)}
@@ -245,6 +269,45 @@ describe Statsd do
     end
   end
 
+  describe "batching" do
+    it "should have a default batch size of 10" do
+      @statsd.batch_size.must_equal 10
+    end
+
+    it "should have a modifiable batch size" do
+      @statsd.batch_size = 7
+      @statsd.batch_size.must_equal 7
+      @statsd.batch do |b|
+        b.batch_size.must_equal 7
+      end
+    end
+
+    it "should flush the batch at the batch size or at the end of the block" do
+      @statsd.batch do |b|
+        b.batch_size = 3
+
+        # The first three should flush, the next two will be flushed when the
+        # block is done.
+        5.times { b.increment('foobar') }
+
+        @socket.recv.must_equal [(["foobar:1|c"] * 3).join("\n")]
+      end
+
+      @socket.recv.must_equal [(["foobar:1|c"] * 2).join("\n")]
+    end
+
+    it "should not flush to the socket if the backlog is empty" do
+      batch = Statsd::Batch.new(@statsd)
+      batch.flush
+      @socket.recv.must_be :nil?
+
+      batch.increment 'foobar'
+      batch.flush
+      @socket.recv.must_equal %w[foobar:1|c]
+    end
+
+  end
+
   describe "thread safety" do
 
     it "should use a thread local socket" do

data/statsd-ruby.gemspec

@@ -1,13 +1,13 @@
 # -*- encoding: utf-8 -*-
 
-Gem::Specification.new("statsd-ruby", "1.0.0") do |s|
+Gem::Specification.new("statsd-ruby", "1.1.0") do |s|
   s.authors = ["Rein Henrichs"]
   s.email = "rein@phpfog.com"
 
   s.summary = "A Ruby StatsD client"
   s.description = "A Ruby StatsD client (https://github.com/etsy/statsd)"
 
-  s.homepage = "https://github.com/reinh/statsd-ruby"
+  s.homepage = "https://github.com/reinh/statsd"
   s.licenses = %w[MIT]
 
   s.extra_rdoc_files = %w[LICENSE.txt README.rdoc]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: statsd-ruby
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: 
   segments: 
   - 1
+  - 1
   - 0
-  - 0
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Rein Henrichs
@@ -15,11 +15,12 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-07-02 00:00:00 Z
+date: 2012-12-05 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
+  name: minitest
   prerelease: false
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -30,12 +31,12 @@ dependencies:
         - 2
         - 0
         version: 3.2.0
-  requirement: *id001
-  name: minitest
   type: :development
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
+  name: yard
   prerelease: false
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -44,12 +45,12 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  requirement: *id002
-  name: yard
   type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
+  name: simplecov
   prerelease: false
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -60,12 +61,12 @@ dependencies:
         - 6
         - 4
         version: 0.6.4
-  requirement: *id003
-  name: simplecov
   type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
+  name: rake
   prerelease: false
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -74,9 +75,8 @@ dependencies:
         segments: 
         - 0
         version: "0"
-  requirement: *id004
-  name: rake
   type: :development
+  version_requirements: *id004
 description: A Ruby StatsD client (https://github.com/etsy/statsd)
 email: rein@phpfog.com
 executables: []
@@ -98,7 +98,7 @@ files:
 - spec/helper.rb
 - spec/statsd_spec.rb
 - statsd-ruby.gemspec
-homepage: https://github.com/reinh/statsd-ruby
+homepage: https://github.com/reinh/statsd
 licenses: 
 - MIT
 post_install_message: 
@@ -127,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A Ruby StatsD client