statsd-instrument 2.0.5 → 2.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4676e97c70d4ea8a412d1835d5b341e86f7eb056
-  data.tar.gz: 9f3cb9257f3d0e6c3edc152dd45f53e30ad2301c
+  metadata.gz: 852b64cbebc0760778a4d3332d4611f4652e64bd
+  data.tar.gz: fb0025c42ec04d18f7bdd1553d48dd75656e083f
 SHA512:
-  metadata.gz: 272ec7539100efa9e4572114e20f36b6584f3a4a604b4574e7cf3b496c13a125691f102af649d8279317e86bd4758adacabc68b4d5a3c8949149ae18292747fa
-  data.tar.gz: 97fa56c8eff9da0754b0f1ff437c27b365ab701cb3894023caa3eefbbb001a0a66d38d69a8cf52fd46a2061a882e221c71b33e2eb3abe9cdd6bb87b658047a40
+  metadata.gz: 58f1b9bf3fee6706e3bc543d4f0146dda3217c0dab443a624d9700f02083917d6a76169dbf0cd1d9372ed8f36ff9b51a9bfbf6cb121f62fa8c4e0798b48f86cc
+  data.tar.gz: f9a3abf6573ac684c6573c64dec24108ab0e6c56227ced05a6fa167dc0e4c4d0245b83dcdd53f2de2666e9138096b3668ed1f86529937ae06a70833e57849dc5

data/.gitignore

@@ -1,3 +1,5 @@
+.yardoc
+doc
 *.gem
 .bundle
 Gemfile.lock

data/.travis.yml

@@ -4,6 +4,11 @@ rvm:
   - 2.0.0
   - 2.1.1
   - ruby-head
+  - jruby-19mode
+  - rbx-2
+
 matrix:
   allow_failures:
     - rvm: ruby-head
+
+sudo: false

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+This file documents the changes between releases of this library. When creating a pull request,
+please at an entry to the "unreleased changes" section below.
+
+### Unreleased changes
+
+- Nothing yet!
+
+---
+
+### Version 2.0.6
+
+- Fix some loading order issues in Rails environments.
+- Default behavior: in a **staging** environment, the defaults are now the same as in a **production environment**.
+- Documentation overhaul
+
+
+### Version 2.0.5
+
+- Allow for nested assertions using the `assert_statsd_*` assertion methods.
+
+### Version 2.0.4
+
+- Add a Railtie to fix some initialization issues.
+
+### Version 2.0.3
+
+- Assertion method bugfixes
+
+### Version 2.0.2
+
+- Documentation fixes
+
+### Version 2.0.1
+
+- Add assertion methods `assert_statsd_histogram`, `assert_statsd_set`, and `assert_statsd_key_value`.
+
+### Version 2.0.0
+
+- Complete rewrite using pluggable backends.
+- Add assertion methods in `StatsD::Instrument::Assertions` to make testing easier and less brittle.
+- Drop support for Ruby 1.8

data/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+This project is MIT licensed and welcomes outside contributions.
+
+## Reporting issues
+
+Report issues using the [Github issues tracker](https://github.com/Shopify/statsd-instrument/issues/new).
+
+When reporting issues, please incldue the following information:
+
+- Your Ruby interpreter version.
+- The statsd-instrument version. **Note:** only the latest version is supported.
+- The StatsD backend you are using.
+
+## Pull request
+
+1. Fork the repository, and create a branch.
+2. Implement the feature or bugfix, and add tests that cover the changed functionality.
+3. Create a pull request. Make sure that you get Travis CI passes.
+4. Ping **@jstorimer** and/or **@wvanbergen** for a code review.
+
+Some notes:
+
+- Make sure to follow to coding style.
+- Make sure your changes are properly documented using [yardoc syntax](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md).
+- Add an entry to the "unreleased changes" section of [CHANGELOG.md](./CHANGELOG.md).
+- **Do not** update `StatsD::Instrument::VERSION`. This will be done during the release prodecure.
+
+## Release procedure
+
+1. Update the version number in `lib/statsd/instrument/version.rb`.
+2. Move the "Unreleased changes" items in [CHANGELOG.md](./CHANGELOG.md) to a new section for the release.
+3. Commit these changes.
+4. Run `bundle exec rake release`.

data/README.md

@@ -2,29 +2,21 @@
 
 [![Built on Travis](https://secure.travis-ci.org/Shopify/statsd-instrument.png?branch=master)](https://secure.travis-ci.org/Shopify/statsd-instrument)
 
-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. 
+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 its 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 its requirement as a fixed size database. We can throw as much data at it as we want it and it will do its 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).
+For more information about StatsD, see the [README of the Etsy project](http://github.com/etsy/statsd).
 
 ## Configuration
 
-The library comes with different backends. Based on your environment (detected using environment 
+The library comes with different backends. Based on your environment (detected using environment
 variables), it will select one of the following backends by default:
 
-- **Production** environment: `StatsD::Instrument::Backends::UDPBackend` will actually send UDP packets. 
-  It will configure itself using environment variables: it uses `STATSD_ADDR` for the address to connect 
+- **Production** and **staging** environment: `StatsD::Instrument::Backends::UDPBackend` will actually send UDP packets.
+  It will configure itself using environment variables: it uses `STATSD_ADDR` for the address to connect
   to (default `"localhost:8125"`), and `STATSD_IMPLEMENTATION` to set the protocol variant. (See below)
-- **Test** environment: `StatsD::Instrument::Backends::NullBackend` will swallow all calls. See below for 
+- **Test** environment: `StatsD::Instrument::Backends::NullBackend` will swallow all calls. See below for
   notes on writing tests.
 - **Development**, and all other, environments: `StatsD::Instrument::Backends::LoggerBackend` will log all
   calls to stdout.
@@ -32,7 +24,7 @@ variables), it will select one of the following backends by default:
 You can override the currently active backend by setting `StatsD.backend`:
 
 ``` ruby
-# Sets up a UDP backend. First argument is the UDP address to send StatsD packets to, 
+# Sets up a UDP backend. First argument is the UDP address to send StatsD packets to,
 # second argument specifies the protocol variant (i.e. `:statsd`, `:statsite`, or `:datadog`).
 StatsD.backend = StatsD::Instrument::Backends::UDPBackend.new("1.2.3.4:8125", :statsite)
 
@@ -44,7 +36,7 @@ The other available settings, with their default, are
 
 ``` ruby
 # Logger to which commands are logged when using the LoggerBackend, which is
-# the default in development environment. Also, any errors or warnings will 
+# the default in development environment. Also, any errors or warnings will
 # be logged here.
 StatsD.logger = defined?(Rails) ? Rails.logger : Logger.new($stderr)
 
@@ -78,7 +70,7 @@ StatsD.measure('GoogleBase.insert') do
   GoogleBase.insert(product)
 end
 ```
-		
+
 #### 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.
@@ -206,7 +198,7 @@ StatsD.increment('my.counter', tags: ['env:production', 'unicorn'])
 GoogleBase.statsd_count :insert, 'GoogleBase.insert', tags: ['env:production']
 ```
 
-If implementation is not set to `:datadog`, tags will not be included in the UDP packets, and a 
+If implementation is not set to `:datadog`, tags will not be included in the UDP packets, and a
 warning is logged to `StatsD.logger`.
 
 ## Testing
@@ -232,24 +224,24 @@ class MyTestcase < Minitest::Test
       StatsD.increment('unrelated') # doesn't match
       StatsD.increment('counter.name', sample_rate: 1.0) # matches
       StatsD.increment('counter.name', sample_rate: 0.1) # matches too
-    end    
+    end
   end
 
   def test_no_udp_traffic
     # Verifies no StatsD calls occured at all.
     assert_no_statsd_calls do
-      do_some_work  
+      do_some_work
     end
 
     # Verifies no StatsD calls occured for the given metric.
     assert_no_statsd_calls('metric_name') do
       do_some_work
-    end    
+    end
   end
 
   def test_more_complicated_stuff
     # capture_statsd_calls will capture all the StatsD calls in the
-    # given block, and returns them as an array. You can then run your 
+    # given block, and returns them as an array. You can then run your
     # own assertions on it.
     metrics = capture_statsd_calls do
       StatsD.increment('mycounter', sample_rate: 0.01)
@@ -265,32 +257,27 @@ end
 
 ```
 
-## Reliance on DNS
+## Notes
 
-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 (i.e. a synchronous TCP round trip). 
-This can be particularly problematic in clouds that have a shared DNS infrastructure such as AWS.
+### Compatibility
 
-### Common Workarounds
+Tested using Travis CI against Ruby 1.9.3, Ruby 2.0.0, Ruby 2.1.1, Rubinius, and JRuby
 
-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.
+### Reliance on DNS
 
-## Compatibility
+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 (i.e. a synchronous TCP round trip).
+This can be particularly problematic in clouds that have a shared DNS infrastructure such as AWS.
 
-Tested on several Ruby versions using Travis CI:
+1. Using a hardcoded 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.
 
-* Ruby 1.9.3
-* Ruby 2.0.0
-* Ruby 2.1.1
 
-## Contributing
+## Links
 
-This project is MIT licensed and welcomes outside contributions.
+This library was developed for shopify.com and is MIT licensed.
 
-1. Fork the repository, and create a feature branch.
-2. Implement the feature, and add tests that cover the new changes functionality.
-3. Update the README.
-4. Create a pull request. Make sure that you get a Travis CI pass on it.
-5. Ping @jstorimer and/or @wvanbergen for review.
+- [API documentation](http://www.rubydoc.info/gems/statsd-instrument/frames)
+- [The changelog](./CHANGELOG.md) covers the changes between releases.
+- [Contributing notes](./CONTRIBUTING.md) if you are interested in contributing to this library.

data/lib/statsd/instrument.rb

@@ -1,20 +1,60 @@
 require 'socket'
 require 'logger'
 
+# The StatsD module contains low-level metrics for collecting metrics and sending them to the backend.
+#
+# @!attribute backend
+#   The backend that is being used to emit the metrics.
+#   @return [StatsD::Instrument::Backend] the currently active backend. If there is no active backend
+#     yet, it will call {StatsD::Instrument::Environment#default_backend} to obtain a
+#     default backend for the environment.
+#   @see StatsD::Instrument::Environment#default_backend
+#
+# @!attribute prefix
+#   The prefix to apply to metric names. This can be useful to group all the metrics
+#   for an application in a shared StatsD server.
+#
+#   When using a prefix a dot will be included automatically to separate the prefix
+#   from the metric name.
+#
+#   @return [String, nil] The prefix, or <tt>nil</tt> when no prefix is used
+#   @see StatsD::Instrument::Metric#name
+#
+# @!attribute default_sample_rate
+#   The sample rate to use if the sample rate is unspecified for a metric call.
+#   @return [Float] Default is 1.0.
+#
+# @!attribute logger
+#   The logger to use in case of any errors. The logger is also used as default logger
+#   for the LoggerBackend (although this can be overwritten).
+#
+#   @see StatsD::Instrument::Backends::LoggerBackend
+#   @return [Logger]
+#
+# @see StatsD::Instrument <tt>StatsD::Instrument</tt> contains module to instrument
+#    existing methods with StatsD metrics.
 module StatsD
+  extend self
+
+  # The StatsD::Instrument module provides metaprogramming methods to instrument your methods with
+  # StatsD metrics. E.g., yopu can create counters on how often a method is called, how often it is
+  # successful, the duration of the methods call, etc.
   module Instrument
 
+    # @private
     def self.generate_metric_name(metric_name, callee, *args)
       metric_name.respond_to?(:call) ? metric_name.call(callee, args).gsub('::', '.') : metric_name.gsub('::', '.')
     end
 
     if Process.respond_to?(:clock_gettime)
+      # @private
       def self.duration
         start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         yield
         Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
       end
     else
+      # @private
       def self.duration
         start = Time.now
         yield
@@ -22,6 +62,13 @@ module StatsD
       end
     end
 
+    # Adds execution duration instrumentation to a method.
+    #
+    # @param method [Symbol] The name of the method to instrument.
+    # @param name [String, #call] The name of the metric to use. You can also pass in a
+    #    callable to dynamically generate a metric name
+    # @param metric_options (see StatsD#measure)
+    # @return [void]
     def statsd_measure(method, name, *metric_options)
       add_to_method(method, name, :measure) do |old_method, new_method, metric_name, *args|
         define_method(new_method) do |*args, &block|
@@ -30,6 +77,21 @@ module StatsD
       end
     end
 
+    # Adds success and failure counter instrumentation to a method.
+    #
+    # A method call will be considered successful if it does not raise an exception, and the result is true-y.
+    # For successful calls, the metric <tt>[name].success</tt> will be incremented; for failed calls, the metric
+    # name is <tt>[name].failure</tt>.
+    #
+    # @param method (see #statsd_measure)
+    # @param name (see #statsd_measure)
+    # @param metric_options (see #statsd_measure)
+    # @yield You can pass a block to this method if you want to define yourself what is a successful call
+    #   based on the return value of the method.
+    # @yieldparam result The return value of the instrumented method.
+    # @yieldreturn [Boolean] Return true iff the return value is consisered a success, false otherwise.
+    # @return [void]
+    # @see #statsd_count_if
     def statsd_count_success(method, name, *metric_options)
       add_to_method(method, name, :count_success) do |old_method, new_method, metric_name|
         define_method(new_method) do |*args, &block|
@@ -49,6 +111,19 @@ module StatsD
       end
     end
 
+    # Adds success and failure counter instrumentation to a method.
+    #
+    # A method call will be considered successful if it does not raise an exception, and the result is true-y.
+    # Only for successful calls, the metric will be icnremented
+    #
+    # @param method (see #statsd_measure)
+    # @param name (see #statsd_measure)
+    # @param metric_options (see #statsd_measure)
+    # @yield (see #statsd_count_success)
+    # @yieldparam result (see #statsd_count_success)
+    # @yieldreturn (see #statsd_count_success)
+    # @return [void]
+    # @see #statsd_count_success
     def statsd_count_if(method, name, *metric_options)
       add_to_method(method, name, :count_if) do |old_method, new_method, metric_name|
         define_method(new_method) do |*args, &block|
@@ -67,6 +142,15 @@ module StatsD
       end
     end
 
+    # Adds counter instrumentation to a method.
+    #
+    # The metric will be incremented for every call of the instrumented method, no matter
+    # whether what the method returns, or whether it raises an exception.
+    #
+    # @param method (see #statsd_measure)
+    # @param name (see #statsd_measure)
+    # @param metric_options (see #statsd_measure)
+    # @return [void]
     def statsd_count(method, name, *metric_options)
       add_to_method(method, name, :count) do |old_method, new_method, metric_name|
         define_method(new_method) do |*args, &block|
@@ -76,18 +160,38 @@ module StatsD
       end
     end
 
+    # Removes StatsD counter instrumentation from a method
+    # @param method [Symbol] The method to remove instrumentation from.
+    # @param name [String] The name of the metric that was used.
+    # @return [void]
+    # @see #statsd_count
     def statsd_remove_count(method, name)
       remove_from_method(method, name, :count)
     end
 
+    # Removes StatsD conditional counter instrumentation from a method
+    # @param method (see #statsd_remove_count)
+    # @param name (see #statsd_remove_count)
+    # @return [void]
+    # @see #statsd_count_if
     def statsd_remove_count_if(method, name)
       remove_from_method(method, name, :count_if)
     end
 
+    # Removes StatsD success counter instrumentation from a method
+    # @param method (see #statsd_remove_count)
+    # @param name (see #statsd_remove_count)
+    # @return [void]
+    # @see #statsd_count_success
     def statsd_remove_count_success(method, name)
       remove_from_method(method, name, :count_success)
     end
 
+    # Removes StatsD measure instrumentation from a method
+    # @param method (see #statsd_remove_count)
+    # @param name (see #statsd_remove_count)
+    # @return [void]
+    # @see #statsd_measure
     def statsd_remove_measure(method, name)
       remove_from_method(method, name, :measure)
     end
@@ -120,83 +224,136 @@ module StatsD
     end
   end
 
-  class << self
-    attr_accessor :logger, :default_sample_rate, :prefix
-    attr_writer :backend
-
-    def backend
-      @backend ||= StatsD::Instrument::Environment.default_backend
-    end
+  attr_accessor :logger, :default_sample_rate, :prefix
+  attr_writer :backend
 
-    # glork:320|ms
-    def measure(key, value = nil, *metric_options, &block)
-      if value.is_a?(Hash) && metric_options.empty?
-        metric_options = [value]
-        value = nil
-      end
+  def backend
+    @backend ||= StatsD::Instrument::Environment.default_backend
+  end
 
-      result = nil
-      value  = 1000 * StatsD::Instrument.duration { result = block.call } if block_given?
-      metric = collect_metric(hash_argument(metric_options).merge(type: :ms, name: key, value: value))
-      result = metric unless block_given?
-      result
+  # Emits a duration metric.
+  #
+  # @overload measure(key, value, metric_options = {})
+  #   Emits a measure metric, by providing a duration in milliseconds.
+  #   @param key [String] The name of the metric.
+  #   @param value [Float] The measured duration in milliseconds
+  #   @param metric_options [Hash] Options for the metric
+  #   @return [StatsD::Instrument::Metric] The metric that was sent to the backend.
+  #
+  # @overload measure(key, metric_options = {}, &block)
+  #   Emits a measure metric, after measuring the execution duration of the
+  #   block passed to this method.
+  #   @param key [String] The name of the metric.
+  #   @param metric_options [Hash] Options for the metric
+  #   @yield The method will yield the block that was passed to this emthod to measure its duration.
+  #   @return The value that was returns by the block passed to this method.
+  #
+  #   @example
+  #      http_response = StatsD.measure('HTTP.call.duration') do
+  #        HTTP.get(url)
+  #      end
+  def measure(key, value = nil, *metric_options, &block)
+    if value.is_a?(Hash) && metric_options.empty?
+      metric_options = [value]
+      value = nil
     end
 
-    # gorets:1|c
-    def increment(key, value = 1, *metric_options)
-      if value.is_a?(Hash) && metric_options.empty?
-        metric_options = [value]
-        value = 1
-      end
+    result = nil
+    value  = 1000 * StatsD::Instrument.duration { result = block.call } if block_given?
+    metric = collect_metric(hash_argument(metric_options).merge(type: :ms, name: key, value: value))
+    result = metric unless block_given?
+    result
+  end
 
-      collect_metric(hash_argument(metric_options).merge(type: :c, name: key, value: value))
+  # Emits a counter metric.
+  # @param key [String] The name of the metric.
+  # @param value [Integer] The value to increment the counter by.
+  #
+  #   You should not compensate for the sample rate using the counter increment. E.g., if
+  #   your sample rate is 0.01, you should <b>not</b> use 100 as increment to compensate for it.
+  #   The sample rate is part of the packet that is being sent to the server, and the server
+  #   should know how to handle it.
+  #
+  # @param metric_options [Hash] (default: {}) Metric options
+  # @return (see #collect_metric)
+  def increment(key, value = 1, *metric_options)
+    if value.is_a?(Hash) && metric_options.empty?
+      metric_options = [value]
+      value = 1
     end
 
-    # gaugor:333|g
-    # guagor:1234|kv|@1339864935 (statsite)
-    def gauge(key, value, *metric_options)
-      collect_metric(hash_argument(metric_options).merge(type: :g, name: key, value: value))
-    end
+    collect_metric(hash_argument(metric_options).merge(type: :c, name: key, value: value))
+  end
 
-    # histogram:123.45|h
-    def histogram(key, value, *metric_options)
-      collect_metric(hash_argument(metric_options).merge(type: :h, name: key, value: value))
-    end
+  # Emits a gauge metric.
+  # @param key [String] The name of the metric.
+  # @param value [Numeric] The current value to record.
+  # @param metric_options [Hash] (default: {}) Metric options
+  # @return (see #collect_metric)
+  def gauge(key, value, *metric_options)
+    collect_metric(hash_argument(metric_options).merge(type: :g, name: key, value: value))
+  end
 
-    def key_value(key, value, *metric_options)
-      collect_metric(hash_argument(metric_options).merge(type: :kv, name: key, value: value))
-    end
+  # Emits a histogram metric.
+  # @param key [String] The name of the metric.
+  # @param value [Numeric] The value to record.
+  # @param metric_options [Hash] (default: {}) Metric options
+  # @return (see #collect_metric)
+  # @note Supported by the datadog implementation only.
+  def histogram(key, value, *metric_options)
+    collect_metric(hash_argument(metric_options).merge(type: :h, name: key, value: value))
+  end
 
-    # uniques:765|s
-    def set(key, value, *metric_options)
-      collect_metric(hash_argument(metric_options).merge(type: :s, name: key, value: value))
-    end
+  # Emits a key/value metric.
+  # @param key [String] The name of the metric.
+  # @param value [Numeric] The value to record.
+  # @param metric_options [Hash] (default: {}) Metric options
+  # @return (see #collect_metric)
+  # @note Supported by the statsite implementation only.
+  def key_value(key, value, *metric_options)
+    collect_metric(hash_argument(metric_options).merge(type: :kv, name: key, value: value))
+  end
 
-    private
+  # Emits a set metric.
+  # @param key [String] The name of the metric.
+  # @param value [Numeric] The value to record.
+  # @param metric_options [Hash] (default: {}) Metric options
+  # @return (see #collect_metric)
+  # @note Supported by the datadog implementation only.
+  def set(key, value, *metric_options)
+    collect_metric(hash_argument(metric_options).merge(type: :s, name: key, value: value))
+  end
 
-    def hash_argument(args)
-      return {} if args.length == 0
-      return args.first if args.length == 1 && args.first.is_a?(Hash)
+  private
 
-      order = [:sample_rate, :tags]
-      hash = {}
-      args.each_with_index do |value, index|
-        hash[order[index]] = value
-      end
+  # Converts old-style ordered arguments in an argument hash for backwards compatibility.
+  # @param args [Array] The list of non-required arguments.
+  # @return [Hash] The hash of optional arguments.
+  def hash_argument(args)
+    return {} if args.length == 0
+    return args.first if args.length == 1 && args.first.is_a?(Hash)
 
-      return hash
+    order = [:sample_rate, :tags]
+    hash = {}
+    args.each_with_index do |value, index|
+      hash[order[index]] = value
     end
 
-    def collect_metric(options)
-      backend.collect_metric(metric = StatsD::Instrument::Metric.new(options))
-      metric
-    end
+    return hash
+  end
+
+  # Instantiates a metric, and sends it to the backend for further processing.
+  # @param options (see StatsD::Instrument::Metric#initialize)
+  # @return [StatsD::Instrument::Metric] The meric that was sent to the backend.
+  def collect_metric(options)
+    backend.collect_metric(metric = StatsD::Instrument::Metric.new(options))
+    metric
   end
 end
 
+require 'statsd/instrument/version'
 require 'statsd/instrument/metric'
 require 'statsd/instrument/backend'
 require 'statsd/instrument/assertions'
 require 'statsd/instrument/environment'
-require 'statsd/instrument/version'
 require 'statsd/instrument/railtie' if defined?(Rails)

data/lib/statsd/instrument/backend.rb

@@ -1,4 +1,11 @@
+# This abstract class specifies the interface a backend implementation should conform to.
+# @abstract
 class StatsD::Instrument::Backend
+
+  # Collects a metric.
+  #
+  # @param metric [StatsD::Instrument::Metric] The metric to collect
+  # @return [void]
   def collect_metric(metric)
     raise NotImplementedError, "Use a concerete backend implementation"
   end

data/lib/statsd/instrument/backends/capture_backend.rb

@@ -1,4 +1,11 @@
 module StatsD::Instrument::Backends
+
+  # The capture backend is used to capture the metrics that are collected, so you can
+  # run assertions on them.
+  #
+  # @!attribute collected_metrics [r]
+  #   @return [Array<StatsD::Instrument::Metric>] The list of metrics that were collected.
+  # @see StatsD::Instrument::Assertions
   class CaptureBackend < StatsD::Instrument::Backend
     attr_reader :collected_metrics
 
@@ -6,10 +13,15 @@ module StatsD::Instrument::Backends
       reset
     end
 
+    # Adds a metric to the ist of collected metrics.
+    # @param metric [StatsD::Instrument::Metric]  The metric to collect.
+    # @return [void]
     def collect_metric(metric)
       @collected_metrics << metric
     end
 
+    # Resets the list of collected metrics to an empty list.
+    # @return [void]
     def reset
       @collected_metrics = []
     end

data/lib/statsd/instrument/backends/logger_backend.rb

@@ -1,12 +1,18 @@
 module StatsD::Instrument::Backends
+
+  # The logger backend simply logs every metric to a logger
+  # @!attribute logger
+  #    @return [Logger]
   class LoggerBackend < StatsD::Instrument::Backend
-    
+
     attr_accessor :logger
-    
+
     def initialize(logger)
       @logger = logger
     end
 
+    # @param metric [StatsD::Instrument::Metric]
+    # @return [void]
     def collect_metric(metric)
       logger.info "[StatsD] #{metric}"
     end

data/lib/statsd/instrument/backends/null_backend.rb

@@ -1,4 +1,5 @@
 module StatsD::Instrument::Backends
+  # The null backend does nothing when receiving a metric, effectively disabling the gem completely.
   class NullBackend < StatsD::Instrument::Backend
     def collect_metric(metric)
     end

data/lib/statsd/instrument/environment.rb

@@ -1,11 +1,17 @@
 require 'logger'
 
+# The environment module is used to detect, and initialize the environment in
+# which this library is active. It will use different default values based on the environment.
 module StatsD::Instrument::Environment
   extend self
 
+  # Instantiates a default backend for the current environment.
+  #
+  # @return [StatsD::Instrument::Backend]
+  # @see #environment
   def default_backend
     case environment
-    when 'production'
+    when 'production', 'staging'
       StatsD::Instrument::Backends::UDPBackend.new(ENV['STATSD_ADDR'], ENV['STATSD_IMPLEMENTATION'])
     when 'test'
       StatsD::Instrument::Backends::NullBackend.new
@@ -14,14 +20,35 @@ module StatsD::Instrument::Environment
     end
   end
 
+  # Detects the current environment, either by asking Rails, or by inspecting environment variables.
+  #
+  # - Within a Rails application, <tt>Rails.env</tt> is used.
+  # - It will check the following environment variables in order: <tt>RAILS_ENV</tt>, <tt>RACK_ENV</tt>, <tt>ENV</tt>.
+  # - If none of these are set, it will return <tt>development</tt>
+  #
+  # @return [String] The detected environment.
   def environment
     if defined?(Rails)
       Rails.env.to_s
     else
       ENV['RAILS_ENV'] || ENV['RACK_ENV'] || ENV['ENV'] || 'development'
     end
-  end  
+  end
+
+  # Sets default values for sample rate and logger.
+  #
+  # - Default sample rate is set to the value in the STATSD_SAMPLE_RATE environment variable,
+  #   or 1.0 otherwise. See {StatsD#default_sample_rate}
+  # - {StatsD#logger} is set to a logger that send output to stderr.
+  #
+  # If you are including this library inside a Rails environment, additional initialization will
+  # be done as part of the {StatsD::Instrument::Railtie}.
+  #
+  # @return [void]
+  def setup
+    StatsD.default_sample_rate = ENV.fetch('STATSD_SAMPLE_RATE', 1.0).to_f
+    StatsD.logger = Logger.new($stderr)
+  end
 end
 
-StatsD.default_sample_rate = ENV.fetch('STATSD_SAMPLE_RATE', 1.0).to_f
-StatsD.logger = Logger.new($stderr)
+StatsD::Instrument::Environment.setup

data/lib/statsd/instrument/metric.rb

@@ -1,7 +1,48 @@
+# The Metric class represents a metric sample to be send by a backend.
+#
+# @!attribute type
+#   @return [Symbol] The metric type. Must be one of {StatsD::Instrument::Metric::TYPES}
+# @!attribute name
+#   @return [String] The name of the metric. {StatsD#prefix} will automatically be applied
+#     to the metric in the constructor, unless the <tt>:no_prefix</tt> option is set.
+# @!attribute value
+#   @see #default_value
+#   @return [Numeric, String] The value to collect for the metric. Depending on the metric
+#     type, <tt>value</tt> can be a string, integer, or float.
+# @!attribute sample_rate
+#   The sample rate to use for the metric. How the sample rate is handled differs per backend.
+#   The UDP backend will actually sample metric submissions based on the sample rate, while
+#   the logger backend will just include the sample rate in its output for debugging purposes.
+#   @see StatsD#default_sample_rate
+#   @return [Float] The sample rate to use for this metric. This should be a value between
+#     0 and 1. If not set, it will use the default sample rate set to {StatsD#default_sample_rate}.
+# @!attribute tags
+#   The tags to associate with the metric.
+#   @note Only the Datadog implementation supports tags.
+#   @see .normalize_tags
+#   @return [Array<String>, Hash<String, String>, nil] the tags to associate with the metric.
+#     You can either specify the tags as an array of strings, or a Hash of key/value pairs.
+#
+# @see StatsD The StatsD module contains methods that generate metric instances.
+# @see StatsD::Instrument::Backend A StatsD::Instrument::Backend is used to collect metrics.
+#
 class StatsD::Instrument::Metric
 
   attr_accessor :type, :name, :value, :sample_rate, :tags
 
+  # Initializes a new metric instance.
+  # Normally, you don't want to call this method directly, but use one of the metric collection
+  # methods on the {StatsD} module.
+  #
+  # @option options [Symbol] :type The type of the metric.
+  # @option options [String] :name The name of the metric without prefix.
+  # @option options [Boolean] :no_prefix Set to <tt>true</tt> if you don't want to apply {StatsD#prefix}
+  # @option options [Numeric, String, nil] :value The value to collect for the metric. If set to
+  #   <tt>nil>/tt>, {#default_value} will be used.
+  # @option options [Numeric, nil] :sample_rate The sample rate to use. If not set, it will use
+  #   {StatsD#default_sample_rate}.
+  # @option options [Array<String>, Hash<String, String>, nil] :tags The tags to apply to this metric.
+  #   See {.normalize_tags} for more information.
   def initialize(options = {})
     @type = options[:type] or raise ArgumentError, "Metric :type is required."
     @name = options[:name] or raise ArgumentError, "Metric :name is required."
@@ -12,6 +53,13 @@ class StatsD::Instrument::Metric
     @tags        = StatsD::Instrument::Metric.normalize_tags(options[:tags])
   end
 
+  # The default value for this metric, which will be used if it is not set.
+  #
+  # A default value is only defined for counter metrics (<tt>1</tt>). For all other
+  # metric types, this emthod will raise an <tt>ArgumentError</tt>.
+  #
+  # @return [Numeric, String] The default value for this metric.
+  # @raise ArgumentError if the metric type doesn't have a default value
   def default_value
     case type
       when :c; 1
@@ -19,6 +67,8 @@ class StatsD::Instrument::Metric
     end
   end
 
+  # @private
+  # @return [String]
   def to_s
     str = "#{TYPES[type]} #{name}:#{value}"
     str << " @#{sample_rate}" if sample_rate != 1.0
@@ -26,10 +76,14 @@ class StatsD::Instrument::Metric
     str
   end
 
+  # @private
+  # @return [String]
   def inspect
     "#<StatsD::Instrument::Metric #{self.to_s}>"
   end
 
+  # The metric types that are supported by this library. Note that every StatsD server
+  # implementation only supports a subset of them.
   TYPES = {
     c:  'increment',
     ms: 'measure',
@@ -39,12 +93,19 @@ class StatsD::Instrument::Metric
     s:  'set',
   }
 
+  # Utility function to convert tags to the canonical form.
+  #
+  # - Tags specified as key value pairs will be converted into an array
+  # - Tags are normalized to only use word characters and underscores.
+  #
+  # @param tags [Array<String>, Hash<String, String>, nil] Tags specified in any form.
+  # @return [Array<String>, nil] the list of tags in canonical form.
   def self.normalize_tags(tags)
     return if tags.nil?
     tags = tags.map { |k, v| "#{k}:#{v}" } if tags.is_a?(Hash)
-    tags.map do |tag| 
+    tags.map do |tag|
       components = tag.split(':', 2)
       components.map { |c| c.gsub(/[^\w\.-]+/, '_') }.join(':')
     end
   end
-end
+end

data/lib/statsd/instrument/railtie.rb

@@ -1,6 +1,14 @@
+# This Railtie runs some initializers that will set the logger to <tt>Rails#logger</tt>,
+# and will initialize the {StatsD#backend} based on the Rails environment.
+#
+# @see StatsD::Instrument::Environment
 class StatsD::Instrument::Railtie < Rails::Railtie
 
-  initializer 'statsd-instrument.railtie' do
-    StatsD.logger = Rails.logger
+  initializer 'statsd-instrument.use_rails_logger' do
+    ::StatsD.logger = Rails.logger
+  end
+
+  initializer 'statsd-instrument.setup_backend', after: 'statsd-instrument.use_rails_logger' do
+    ::StatsD.backend = ::StatsD::Instrument::Environment.default_backend
   end
 end

data/lib/statsd/instrument/version.rb

@@ -1,5 +1,5 @@
 module StatsD
   module Instrument
-    VERSION = "2.0.5"
+    VERSION = "2.0.6"
   end
 end

data/statsd-instrument.gemspec

@@ -6,11 +6,11 @@ require 'statsd/instrument/version'
 Gem::Specification.new do |spec|
   spec.name        = "statsd-instrument"
   spec.version     = StatsD::Instrument::VERSION
-  spec.authors     = ["Jesse Storimer", "Tobias Lutke"]
+  spec.authors     = ["Jesse Storimer", "Tobias Lutke", "Willem van Bergen"]
   spec.email       = ["jesse@shopify.com"]
   spec.homepage    = "https://github.com/Shopify/statsd-instrument"
   spec.summary     = %q{A StatsD client for Ruby apps}
-  spec.description = %q{A StatsD client for Ruby appspec. Provides metaprogramming methods to inject StatsD instrumentation into your code.}
+  spec.description = %q{A StatsD client for Ruby apps. Provides metaprogramming methods to inject StatsD instrumentation into your code.}
   spec.license     = "MIT"
 
   spec.files         = `git ls-files`.split($/)
@@ -21,4 +21,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'minitest'
   spec.add_development_dependency 'mocha'
+  spec.add_development_dependency 'yard'
 end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: statsd-instrument
 version: !ruby/object:Gem::Version
-  version: 2.0.5
+  version: 2.0.6
 platform: ruby
 authors:
 - Jesse Storimer
 - Tobias Lutke
+- Willem van Bergen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-08 00:00:00.000000000 Z
+date: 2015-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -53,8 +54,22 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: A StatsD client for Ruby appspec. Provides metaprogramming methods to
-  inject StatsD instrumentation into your code.
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A StatsD client for Ruby apps. Provides metaprogramming methods to inject
+  StatsD instrumentation into your code.
 email:
 - jesse@shopify.com
 executables: []
@@ -63,6 +78,8 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE
 - README.md
@@ -126,3 +143,4 @@ test_files:
 - test/statsd_test.rb
 - test/test_helper.rb
 - test/udp_backend_test.rb
+has_rdoc: