statsy 0.1.3 → 0.2.0

data/README.md

@@ -1,28 +1,44 @@
 # Statsy
 
-[Cal made simple stat aggregation][cal].  And it was good.
+[Cal made simple stat aggregation][cal] - And it was good.
 
-[Etsy also made simple stat aggregation][etsy].  And it was also good.
+[Etsy also made simple stat aggregation][etsy] - And it was also good.
 
-This is a simple client.  It does 2 things, increment and measure.  Oh 3 things if you count batching too.
+This is a simple client. It supports:
 
-Usage: Default to UDP to a host in the current search domain called 'stats' on port 8125.
+* counts
+* time measurements
+* recording gauges
+* sampling
+* batching
+
+## Requirements
+
+This client is compatible with a [Statsd][statsd] server version >= 0.1.0.
+
+## Installation
+
+    gem install statsy
+
+## Usage
+
+Default to UDP to a host in the current search domain called 'stats' on port 8125.
 
     client = Statsy::Client.new
 
-Usage: Use a custom transport or change the host/port pair for UDP.
+Use a custom transport or change the host/port pair for UDP.
 
     client = Statsy::Client.new(Statsy::Transport::UDP.new("graphite.acme.com", 8125))
     client = Statsy::Client.new(Acme::Transport::Statsd) # <- you made that
     client = Statsy::Client.new(Statsy::Transport::Queue.new) # <- if you want to test stuff
 
-Usage: Increment by 1, arbitrary integer, or arbitrary integer at a uniform random distribution
+Increment by 1, arbitrary integer, or arbitrary integer at a uniform random distribution
 
     client.increment("coffee.single-espresso")
     client.increment("coffee.single-espresso", 1)
     client.increment("coffee.single-espresso", 1, 0.5) # 50% of the time
 
-Usage: Measure a timing stat that will calculate the mean, min, max, upper\_90 and count
+Measure a timing stat that will calculate the mean, min, max, upper\_90 and count
 
     client.measure("acme.backend-runtime", response.headers["X-Runtime"].to_i)
 
@@ -33,7 +49,7 @@ Bonus points: Batch up many things into a fewer packets like in a shell script
       client.batch do |batch|
         $stdin.each do |log_line|
           metric, timing = parse(log_line) # <- you made that
-          client.measure metric, timing
+          batch.measure metric, timing
           break if (batch_lines -= 1) <= 0
         end
       end
@@ -45,9 +61,8 @@ These stats end up in your graphite interface under the top level keys. Look for
     stats/timings
     stats
 
-Fork it out of love.  Enjoy.
+Fork it out of love. Enjoy.
 
 [cal]:http://code.flickr.com/blog/2008/10/27/counting-timing/
 [etsy]:http://codeascraft.etsy.com/2011/02/15/measure-anything-measure-everything/
-
-
+[statsd]:https://github.com/etsy/statsd

data/lib/statsy.rb

@@ -1,7 +1,7 @@
 # Client to access statsd service authored by etsy. Yay etsy!
 # https://github.com/etsy/statsd
 module Statsy
-  VERSION="0.1.3"
+  VERSION='0.2.0'
 
   module Transport
     require 'socket'
@@ -49,7 +49,8 @@ module Statsy
       @transport = transport
     end
 
-    # Increment a count optionally at a random sample rate
+    # Increment a count optionally at a random sample rate.  These keys will
+    # live under the stats and stats_counts keys.
     #
     # Usage:
     #   client.increment("coffee.single-espresso")
@@ -57,17 +58,49 @@ module Statsy
     #   client.increment("coffee.single-espresso", 1, 0.5) # 50% of the time
     #
     def increment(stat, count=1, sampling=1)
-      write(stat, count, 'c', sampling)
+      if sampling < 1
+        if Kernel.rand < sampling
+          write(stat, count, 'c', sampling)
+        end
+      else
+        write(stat, count, 'c', 1)
+      end
       self
     end
 
-    # Sample a timing
+    # Sample a timing.  The units of the timing are up to you and your
+    # consumers, milliseconds is common.
+    #
+    # Including the units in the key name will help communicate the units to
+    # consumers of these measurements.
+    #
+    # The statistics will be aggregated over the sampling period configured in
+    # your statsd.  By default this is every 10 seconds.
+    #
+    # In graphite, these reports will end up under the stats.timings key.
     #
     # Usage:
     #   client.measure("foo.backendtime", response.headers["X-Runtime"].to_i)
     #
-    def measure(stat, time, sampling=1)
-      write(stat, time, 'ms', sampling)
+    # Produces the statistics found per sampling interval.
+    #   stats.timings.foo.backendtime.count
+    #   stats.timings.foo.backendtime.lower
+    #   stats.timings.foo.backendtime.mean_90
+    #   stats.timings.foo.backendtime.upper
+    #   stats.timings.foo.backendtime.upper_90
+    #
+    def measure(stat, time)
+      write(stat, time, 'ms', 1)
+      self
+    end
+
+    # Record an arbitrary value
+    #
+    # Usage:
+    #   client.record("foo.arbitrary", 42)
+    #
+    def record(stat, gauge)
+      write(stat, gauge, 'g', 1)
       self
     end
 
@@ -105,9 +138,7 @@ module Statsy
   protected
     def write(stat, value, modifier, sampling)
       if sampling < 1
-        if Kernel.rand < sampling
-          @transport.write("%s:%d|%s@%f" % [ stat, value, modifier, sampling ])
-        end
+        @transport.write("%s:%d|%s|@%f" % [ stat, value, modifier, sampling ])
       else
         @transport.write("%s:%d|%s" % [ stat, value, modifier ])
       end

data/test/statsy_test.rb

@@ -49,7 +49,7 @@ class Unit < Test::Unit::TestCase
 
   def test_increment_should_sample
     @client.increment("foo.stat", 1, 0.999999)
-    assert_equal "foo.stat:1|c@0.999999", @transport.shift
+    assert_equal "foo.stat:1|c|@0.999999", @transport.shift
   end
 
   def test_measure_should_return_self
@@ -61,16 +61,6 @@ class Unit < Test::Unit::TestCase
     assert_equal "foo.timing:1000|ms", @transport.shift
   end
 
-  def test_measure_should_sample
-    @client.measure("foo.sampled.timing", 100, 0.0000001)
-    assert_equal nil, @transport.shift
-  end
-
-  def test_measure_should_include_sample_rate
-    @client.measure("foo.sampled.timing", 100, 0.999999)
-    assert_equal "foo.sampled.timing:100|ms@0.999999", @transport.shift
-  end
-
   def test_increment_twice_should_write_twice
     @client.increment("foo.inc", 1)
     @client.increment("foo.inc", 2)
@@ -152,4 +142,13 @@ class Unit < Test::Unit::TestCase
     assert_equal "bar.inc:700|ms:900|ms:3|c", @transport.shift
     assert_equal "foo.inc:2|c:9|c:500|ms", @transport.shift
   end
+
+  def test_record_should_return_self
+    assert_equal @client, @client.record("foo.bar", 100)
+  end
+
+  def test_record_should_form_gauge
+    @client.record("foo.bar", 333)
+    assert_equal "foo.bar:333|g", @transport.shift
+  end
 end

metadata

@@ -1,84 +1,67 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: statsy
-version: !ruby/object:Gem::Version 
-  hash: 29
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 3
-  version: 0.1.3
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Sean Treadway
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-29 00:00:00 +02:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: test-unit
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
-description: Simple way to increment counts and measure variance in timings of everything from requests per second to single espressos
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Simple way to increment counts and measure variance in timings of everything
+  from requests per second to single espressos
+email:
 - treadway@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/statsy.rb
 - LICENSE
 - README.md
 - test/statsy_test.rb
-has_rdoc: true
 homepage: http://github.com/streadway/statsy
 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 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: statsy
-rubygems_version: 1.3.7
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Client network library to Statsd
-test_files: 
+test_files:
 - test/statsy_test.rb