statsd-ruby 0.2.0 → 0.2.1

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/statsd.rb

@@ -2,16 +2,23 @@ require 'socket'
 
 # = Statsd: A Statsd client (https://github.com/etsy/statsd)
 #
-# Example:
-#
-#     statsd = Statsd.new 'localhost', 8125
-#
-#     statsd.increment 'garets'
-#     statsd.timing 'glork', 320
+# @example Set up a global Statsd client for a server on localhost:9125
+#   $statsd = Statsd.new 'localhost', 8125
+# @example Send some stats
+#   $statsd.increment 'garets'
+#   $statsd.timing 'glork', 320
+# @example Use {#time} to time the execution of a block
+#   $statsd.time('account.activate') { @account.activate! }
+# @example Create a namespaced statsd client and increment 'account.activate'
+#   statsd = Statsd.new('localhost').tap{|sd| sd.namespace = 'account'}
+#   statsd.increment 'activate'
 class Statsd
+  # A namespace to prepend to all statsd calls.
   attr_accessor :namespace
 
   class << self
+    # Set to any standard logger instance (including stdlib's Logger) to enable
+    # stat logging using logger.debug
     attr_accessor :logger
   end
   
@@ -21,24 +28,45 @@ class Statsd
     @host, @port = host, port
   end
 
-  # @param [String] stat stat name
-  # @param [Integer] sample_rate sample rate, 1 for always
+  # Sends an increment (count = 1) for the given stat to the statsd server. 
+  #
+  # @param stat (see #count)
+  # @param sample_rate (see #count)
+  # @see #count
   def increment(stat, sample_rate=1); count stat, 1, sample_rate end
 
-  # @param [String] stat stat name
-  # @param [Integer] sample_rate sample rate, 1 for always
+  # Sends a decrement (count = -1) for the given stat to the statsd server. 
+  #
+  # @param stat (see #count)
+  # @param sample_rate (see #count)
+  # @see #count
   def decrement(stat, sample_rate=1); count stat, -1, sample_rate end
 
+  # Sends an arbitrary count for the given stat to the statsd server.
+  #
   # @param [String] stat stat name
   # @param [Integer] count count
   # @param [Integer] sample_rate sample rate, 1 for always
   def count(stat, count, sample_rate=1); send stat, count, 'c', sample_rate end
 
-  # @param [String] stat stat name
+  # Sends a timing (in ms) for the given stat to the statsd server. The
+  # sample_rate determines what percentage of the time this report is sent. The
+  # statsd server then uses the sample_rate to correctly track the average
+  # timing for the stat.
+  #
+  # @param stat stat name
   # @param [Integer] ms timing in milliseconds
   # @param [Integer] sample_rate sample rate, 1 for always
   def timing(stat, ms, sample_rate=1); send stat, ms, 'ms', sample_rate end
 
+  # Reports execution time of the provided block using {#timing}.
+  #
+  # @param stat (see #timing)
+  # @param sample_rate (see #timing)
+  # @yield The operation to be timed
+  # @see #timing
+  # @example Report the time (in ms) taken to activate an account
+  #   $statsd.time('account.activate') { @account.activate! }
   def time(stat, sample_rate=1)
     start = Time.now
     result = yield

data/statsd-ruby.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{statsd-ruby}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Rein Henrichs"]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: statsd-ruby
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: 
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Rein Henrichs