statsd-instrument 2.3.2 → 2.6.0

data/.rubocop.yml

@@ -0,0 +1,50 @@
+inherit_from:
+  - https://shopify.github.io/ruby-style-guide/rubocop.yml
+
+require:
+  - ./lib/statsd/instrument/rubocop.rb
+
+AllCops:
+  TargetRubyVersion: 2.3
+  UseCache: true
+  CacheRootDirectory: tmp/rubocop
+  Exclude:
+    - statsd-instrument.gemspec
+
+Naming/FileName:
+  Enabled: true
+  Exclude:
+    - lib/statsd-instrument.rb
+
+Style/ClassAndModuleChildren:
+  Enabled: false # TODO: enable later
+
+
+Style/MethodCallWithArgsParentheses:
+  Enabled: false # TODO: enable later
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+# Enable our own cops on our own repo
+
+StatsD/MetricReturnValue:
+  Enabled: true
+
+StatsD/MetricValueKeywordArgument:
+  Enabled: true
+
+StatsD/PositionalArguments:
+  Enabled: true
+
+StatsD/SplatArguments:
+  Enabled: true
+
+StatsD/MetaprogrammingPositionalArguments:
+  Enabled: true
+
+StatsD/MeasureAsDistArgument:
+  Enabled: true
+
+StatsD/MetricPrefixArgument:
+  Enabled: true

data/.yardopts

@@ -0,0 +1,5 @@
+--markup=markdown
+-
+README.md
+CHANGELOG.md
+CONTRIBUTING.md

data/CHANGELOG.md

@@ -1,10 +1,296 @@
 # 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.
+This file documents the changes between releases of this library. When
+creating a pull request, please add an entry to the "unreleased changes"
+section below.
 
 ### Unreleased changes
 
+_Nothing yet!_
+
+## Version 2.6.0
+
+This release contains a new `StatsD::Instrument::Client` class, which is
+slated to replace the current implementation in the next major release.
+
+The main reasons for this rewrite are two folds:
+- Improved performance.
+- Being able to instantiate multiple clients.
+
+We have worked hard to make the new client as compatible as possible. However,
+to accomplish some of our goals we have deprecated some stuff that we think
+is unlikely to be used. See the rest of the release notes of this version, and
+version 2.5.0 to see what is deprecated.
+
+You can test compatibility with the new client by replacing `StatsD` with
+`StatsD.client`, which points to a client that will be instantiated using
+the same environment variables that you can already use for this library. You
+can also use strict mode, and rubocop rules to check whether you are using any
+deprecated patterns. See below for more info.
+
+- **⚠️ DEPRECATION**: Using the `prefix: "foo"` argument for `StatsD.metric`
+  calls (and the metaprogramming macros) is deprecated.
+
+  - You can include the prefix in the metric name.
+  - If you want to override the global prefix, set `no_prefix: true` and
+    include the desired prefix in the metric name
+
+  This library ships with a Rubocop rule to detect uses of this keyword
+  argument in your codebase:
+
+  ``` sh
+  # Check for the prefix arguments on your StatsD.metric calls
+  rubocop --only StatsD/MetricPrefixArgument \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb
+  ```
+
+  Strict mode has also been updated to no longer allow this argument.
+
+- **⚠️ DEPRECATION**: Using the `as_dist: true` argument for `StatsD.measure`
+  and `statsd_measure` methods is deprecated. This argument was only available
+  for internal use, but was exposed in the public API. It is unlikely that you
+  are usijng this argumenr, but you can check to make sure using this Rubocop
+  invocation:
+
+  ``` sh
+  # Check for the as_dist arguments on your StatsD.measure calls
+  rubocop --only StatsD/MeasureAsDistArgument \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb
+  ```
+
+  Strict mode has also been updated to no longer allow this argument.
+
+- You can now enable strict mode by setting the `STATSD_STRICT_MODE`
+  environment variable. No more need to change your Gemfile! Note that it is
+  still not recommended to enable strict mode in production due to the
+  performance penalty, but is recommended for development and test. E.g. use
+  `STATSD_STRICT_MODE=1 rails test` to run your test suite with strict mode
+  enabled to expose any deprecations in your codebase.
+
+- Add support for `STATSD_PREFIX` and `STATSD_DEFAULT_TAGS` environment variables
+  to configure the prefix to use for metrics and the comma-separated list of tags
+  to apply to every metric, respectively.
+
+  These environment variables are preferred over using `StatsD.prefix` and
+  `StatsD.default_tags`: it's best practice to configure the StatsD library
+  using environment variables.
+
+- Several improvements to `StatsD.event` and `StatsD.service_check` (both are
+  Datadog-only). The previous implementation would sometimes construct invalid
+  datagrams based on the input. The method signatures have been made more
+  explicit, and documentation of these methods is now also more clear.
+
+- Slight behaviour change when using the `assert_statsd_*` assertion methods in
+  combination with `assert_raises`: we now do not allow the block passed to the
+  `assert_statsd_` call to raise an exception. This may cause tests to fail that
+  previousloy were succeeding.
+
+  Consider the following example:
+
+  ``` ruby
+  assert_raises(RuntimeError) do
+    assert_statsd_increment('foo') do
+      raise 'something unexpected'
+    end
+  end
+  ```
+
+  In versions before 2.3.3, the assert `assert_statsd_*` calls would silently
+  pass when an exception would occur, which would later be handled by
+  `assert_raises`. So the test would pass, even though no `foo` metric would be
+  emitted.
+
+  Version 2.3.3 changed this by failing the test because no metric was being
+  emitted. However, this would hide the the exception from the assertion message,
+  complicating debugging efforts.
+
+  Now, we fail the test because an unexpected exception occured inside the block.
+  This means that the following test will fail:
+
+  ``` ruby
+  assert_raises(RuntimeError) do
+    assert_statsd_increment('foo') do
+      StatsD.increment('foo')
+      raise 'something unexpected'
+    end
+  end
+  ```
+
+  To fix, you will need to nest the `assert_raises` inside the block passed to
+  `assert_statsd_instrument` so that `assert_statsd_increment` will not see any
+  exceptions:
+
+  ``` ruby
+  assert_statsd_increment('foo') do
+    assert_raises(RuntimeError) do
+      StatsD.increment('foo')
+      raise 'something unexpected'
+    end
+  end
+  ```
+
+  See #193, #184, and #166 for more information.
+
+## Verison 2.5.1
+
+- **Bugfix:** when using metaprogramming methods, changes to `StatsD.prefix` after
+  the metaprogramming method was evaluated would not be respected. This
+  unfortunately is quite common when you set the StatsD prefix inside an
+  initializer. This issue is now addressed: the prefix is evaluated at the
+  mopment the metric is emitted, not when the metaprogramming method is being
+  evaluated. (#202)
+
+## Version 2.5.0
+
+- **⚠️ DEPRECATION**: Providing a sample rate and tags to your metrics and method
+  instrumentation macros should be done using keyword arguments rather than
+  positional arguments. Also, previously you could provide `value` as a keyword
+  argument, but it should be provided as the second positional argument.
+
+  ``` ruby
+  # DEPRECATED
+  StatsD.increment 'counter', 1, 0.1, ['tag']
+  StatsD.increment 'counter', value: 123, tags: { foo: 'bar' }
+  StatsD.measure('duration', nil, 1.0) { foo }
+  statsd_count_success :method, 'metric-name', 0.1
+
+  # SUPPORTED
+  StatsD.increment 'counter', sample_rate: 0.1, tags: ['tag']
+  StatsD.increment 'counter', 123, tags: { foo: 'bar' }
+  StatsD.measure('duration', sample_rate: 1.0) { foo }
+  statsd_count_success :method, 'metric-name', sample_rate: 0.1
+  ```
+
+  The documentation of the methods has been updated to reflect this change.
+  The behavior of the library is not changed for the time being, so you can
+  safely upgrade to this version. However, in a future major release, we will
+  remove support for the positional arguments.
+
+  The library includes some cops to help with finding issues in your existing
+  codebase, and fixing them:
+
+  ``` sh
+  # Check for positional arguments on your StatsD.metric calls
+  rubocop --only StatsD/PositionalArguments \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/positional_arguments.rb
+
+  # Check for positional arguments on your statsd_instrumentation macros
+  rubocop --only StatsD/MetaprogrammingPositionalArguments \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metaprogramming_positional_arguments.rb
+
+  # Check for value as keyword argument
+  rubocop --only StatsD/MetricValueKeywordArgument \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_value_keyword_argument.rb
+
+  ```
+
+- **⚠️ DEPRECATION**: Relying on the return value of the StatsD metric methods
+  (e.g. `StatsD.increment`) is deprecated. StatsD is a fire-and-forget
+  protocol, so your code should not depend on the return value of these methods.
+
+  The documentation of the methods has been updated to reflect this change.
+  The behavior of the library is not changed for the time being, so you can
+  safely upgrade to this version. However, in a future major release, we will
+  start to explicitly return `nil`.
+
+  This gem comes with a Rubocop rule that can help verify that your
+  application is not relying on the return value of the metric methods. To use
+  this cop on your codebase, invoke Rubocop with the following arguments:
+
+  ``` sh
+  rubocop --only StatsD/MetricReturnValue \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_return_value.rb
+  ```
+
+- **Strict mode**: These custom Rubocop rules will give you a quick indication
+  of the issues in your codebase, but are not airtight. This library now also
+  ships with strict mode, a mixin module that already disables this deprecated
+  behavior so it will raise exceptions if you are depending on deprecated
+  behavior. It will also do additional input validation, and make sure the
+  `StatsD` metric methods return `nil`.
+
+  You enable strict mode by requiring `statsd/instrument/strict`:
+
+  ``` ruby
+  # In your Gemfile
+  gem 'statd-instrument', require: 'statsd/instrument/strict'
+
+  # Or, in your test helper:
+  require 'statsd/instrument/strict'
+  ```
+
+  It is recommended to enable this in CI to find deprecation issues, but not
+  in production because enabling it comes with a performance penalty.
+
+- **Performance improvements 🎉**: Several internal changes have made the
+  library run singificantly faster. The changes:
+
+  - Improve performance of duration calculations. (#168)
+  - Early exit when no changes are needed to bring tags and metric names to
+    normalized form. (#173)
+  - Refactor method argument handling to reduce object allocations and
+    processing. (#174)
+
+  A benchmark suite was added (#169) and it now runs as part of CI (#170) so we
+  can more easily spot performance regressions before they get merged into the
+  library.
+
+  The result of this work:
+
+  ```
+  Comparison:
+  StatsD metrics to local UDP receiver (branch: master, sha: 2f98046):    10344.9 i/s
+  StatsD metrics to local UDP receiver (branch: v2.4.0, sha: 371d22a):     8556.5 i/s - 1.21x  (± 0.00) slower
+  ```
+
+  The deprecations mentioned above will allows us to provide an even greater
+  performance improvement, so update your code base to not use those
+  deprecations anymore, and keep your eyes open for future releases of the
+  library!
+
+- _Bugfix:_ avoid deadlock when an error occurs in the integration test suite (#175)
+
+## Version 2.4.0
+
+- Add `StatsD.default_tags` to specify tags that should be included in all metrics. (#159)
+- Improve assertion message when asserting metrics whose tags do not match. (#100)
+- Enforce the Shopify Ruby style guide. (#164)
+- Migrate CI to Github actions. (#158)
+- Make the library frozen string literal-compatible. (#161, #163)
+- Fix all Ruby warnings. (#162)
+
+## Version 2.3.5
+
+- Re-add `StatsD::Instrument.duration`, which was accidentally removed since verison 2.5.3 (#157)
+
+## Version 2.3.4
+
+- Improve performance of `Metric#to_s` (#152)
+- Fix bug in escaping newlines for events with Datadog Backend (#153)
+
+## Version 2.3.3
+
+- Capture measure and distribution metrics on exception and early return (#134)
+
+NOTE: Now that exceptions are measured statistics may behave differently. An exception example:
+```
+StatsD.measure('myhttpcall') do
+  my_http_object.invoke
+end
+```
+Version 2.3.2 and below did not track metrics whenever a HTTP Timeout exception was raised.
+2.3.3 and above will include those metrics which may increase the values included.
+
+A return example:
+```
+StatsD.measure('myexpensivecalculation') do
+  return if expensive_calculation_disabled?
+  expensive_calculation
+end
+```
+If `expensive_calculation_disabled?` is true 50% of the time version 2.3.2 will drop the
+average metric considerably.
+
 ## Version 2.3.2
 
 - Add option to override global prefix for metrics (#148)

data/CONTRIBUTING.md

@@ -11,27 +11,49 @@ This project is MIT licensed.
 
 Report issues using the [Github issues tracker](https://github.com/Shopify/statsd-instrument/issues/new).
 
-When reporting issues, please incldue the following information:
+When reporting issues, please include 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
+## Opening pull requests
 
 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.
+3. Create a pull request. Make sure that you get a green CI status on your commit.
 
 Some notes:
 
-- Make sure to follow to coding style.
+- Make sure to follow to coding style. This is enforced by Rubocop
 - 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.
 
-> **Important:** if you change anything in the hot code path (sending a StatsD metric), please
-> include benchmarks to show the performance impact of your changes.
+### On perfomance & benchmarking
+
+This gem is used in production at Shopify, and is used to instrument some of
+our hottest code paths. This means that we are very careful about not
+introducing performance regressions in this library.
+
+**Important:** Whenever you make changes to the metric emission code path in
+this library, you **must** include benchmark results to show the impact of
+your changes.
+
+The `benchmark/` folder contains some example benchmark script that you can
+use, or can serve as a starting point. The [benchmark README](benchmark/README.md)
+has instructions on how to benchmark your changes.
+
+### On backwards compatibility
+
+Shopify's codebases are heavily instrumented using this library. As a result, we cannot
+accept changes that are backwards incompatible:
+
+- Changes that will require us to update our codebases.
+- Changes that will cause metrics emitted by this library to change in form or shape.
+
+This means that we may not be able to accept fixes for what you consider a bug, because
+we are depending on the current behavior of the library.
 
 ## Release procedure
 

data/Gemfile

@@ -1,2 +1,7 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 gemspec
+
+# benchmark-ips save! method is not part of a released version yet.
+gem 'benchmark-ips', git: 'https://github.com/evanphx/benchmark-ips', branch: 'master'

data/README.md

@@ -1,57 +1,51 @@
 # StatsD client for Ruby apps
 
-[![Built on Travis](https://secure.travis-ci.org/Shopify/statsd-instrument.svg?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.
 
-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.
-
-For more information about StatsD, see the [README of the Etsy project](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
-variables), it will select one of the following backends by default:
-
-- **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
-  notes on writing tests.
-- **Development**, and all other, environments: `StatsD::Instrument::Backends::LoggerBackend` will log all
-  calls to stdout.
-
-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,
-# 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)
-
-# Sets up a logger backend
-StatsD.backend = StatsD::Instrument::Backends::LoggerBackend.new(Rails.logger)
-```
-
-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
-# be logged here.
-StatsD.logger = defined?(Rails) ? Rails.logger : Logger.new($stderr)
-
-# An optional prefix to be added to each metric.
-StatsD.prefix = nil # but can be set to any string
-
-# Sample 10% of events. By default all events are reported, which may overload your network or server.
-# You can, and should vary this on a per metric basis, depending on frequency and accuracy requirements
-StatsD.default_sample_rate = (ENV['STATSD_SAMPLE_RATE'] || 0.1 ).to_f
-```
+It's recommended to configure this librray by setting environment variables.
+The following environment variables are supported:
+
+- `STATSD_ADDR`: (default `localhost:8125`) The address to send the StatsD UDP
+  datagrams to.
+- `STATSD_IMPLEMENTATION`: (default: `statsd`). The StatsD implementation you
+  are using. `statsd`, `statsite` and `datadog` are supported. Some features
+  are only available on certain implementations,
+- `STATSD_ENV`: The environment StatsD will run in. If this is not set
+  explicitly, this will be determined based on other environment variables,
+  like `RAILS_ENV` or `ENV`. The library will behave differently:
+
+  - In the **production** and **staging** environment, thre librray will
+    actually send UDP packets.
+  - In the **test** environment, it will swallow all calls, but allows you to
+    capture them for testing purposes. See below for notes on writing tests.
+  - In **development** and all other environments, it will write all calls to
+    the log (`StatsD.logger`, which by default writes to STDOUT).
+
+- `STATSD_SAMPLE_RATE`: (default: `1.0`) The default sample rate to use for all
+  metrics. This can be used to reduce the amount of network traffic and CPU
+  overhead the usage of this library generates. This can be overridden in a
+  metric method call.
+- `STATSD_PREFIX`: The prefix to apply to all metric names. This can be
+  overridden in a metric method call.
+- `STATSD_DEFAULT_TAGS`: A comma-separated list of tags to apply to all metrics.
+  (Note: tags are not supported by all iomplementations.)
 
 ## StatsD keys
 
 StatsD keys look like 'admin.logins.api.success'. Dots are used as namespace separators.
-In Graphite, they will show up as folders.
 
 ## Usage
 
@@ -82,7 +76,7 @@ StatsD.increment('GoogleBase.insert')
 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, sample_rate: 0.1)
+StatsD.increment('GoogleBase.insert', sample_rate: 0.1)
 ```
 
 #### StatsD.gauge
@@ -106,6 +100,18 @@ StatsD.set('GoogleBase.customers', "12345", sample_rate: 1.0)
 
 Because you are counting unique values, the results of using a sampling value less than 1.0 can lead to unexpected, hard to interpret results.
 
+#### StatsD.histogram
+
+Builds a histogram of numeric values.
+``` ruby
+
+StatsD.histogram('Order.value', order.value_in_usd.to_f tags: { source: 'POS' })
+```
+
+Because you are counting unique values, the results of using a sampling value less than 1.0 can lead to unexpected, hard to interpret results.
+
+*Note: This is only supported by the beta datadog implementatation.*
+
 #### StatsD.distribution
 
 A modified gauge that submits a distribution of values over a sample period. Arithmetic and statistical calculations (percetiles, average, etc.) on the data set are peformed server side rather than client side like a histogram.
@@ -333,7 +339,9 @@ end
 
 ### Compatibility
 
-Tested using Travis CI against Ruby 2.0, 2.1, 2.2, Rubinius, and JRuby.
+The library is tested against Ruby 2.3 and higher. We are not testing on
+different Ruby implementations besides MRI, but we expect it to work on other
+implementations as well.
 
 ### Reliance on DNS
 
@@ -350,6 +358,6 @@ This can be particularly problematic in clouds that have a shared DNS infrastruc
 
 This library was developed for shopify.com and is MIT licensed.
 
-- [API documentation](http://www.rubydoc.info/gems/statsd-instrument/frames)
+- [API documentation](http://www.rubydoc.info/gems/statsd-instrument)
 - [The changelog](./CHANGELOG.md) covers the changes between releases.
 - [Contributing notes](./CONTRIBUTING.md) if you are interested in contributing to this library.

data/Rakefile

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new('test') do |t|
   t.ruby_opts << '-r rubygems'
   t.libs << 'lib' << 'test'
-  t.test_files = FileList['test/*.rb']
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/benchmark/README.md

@@ -0,0 +1,29 @@
+# Benchmark scripts
+
+This directory contains benchmark scripts that can be used to gauge the
+performance impact of changes.
+
+As mentioned in the contributing guidelines, this library is used heavily in
+production at Shopify in many of our hot code paths. This means that we care a
+lot about changes not introducing performance regressions. Every pull request
+that changes the code path to send metrics should include benchmarks
+demonstrating the performance impact of the changes.
+
+This directory contains two scripts to help with benchmarking.
+
+- `send-metrics-to-dev-null-log` exercises the code path to construct metrics.
+- `send-metrics-to-local-udp-listener` will also exercise the code path to
+  actually send a StatsD packet over UDP.
+
+To benchmark your changes:
+
+1. Make sure the benchmark script will actually cover your changes.
+   - If not, please create a new benchmark script that does.
+   - Do not commit this script to the repository (yet), so it will continue to
+     be available if you check out another branch.
+2. Run these scripts on your pull request branch. The results will be stored in
+   a temporary file.
+3. Checkout the latest version of `master`.
+4. Run the benchmark again. The benchmark script will now print a comparison
+   between your branch and master.
+5. Include the output in your pull request description.

data/benchmark/datagram-client

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'benchmark/ips'
+require 'socket'
+
+# Set up an UDP listener to which we can send StatsD packets
+legacy_receiver = UDPSocket.new
+legacy_receiver.bind('localhost', 0)
+
+ENV['ENV'] = "production"
+ENV['STATSD_ADDR'] = "#{legacy_receiver.addr[2]}:#{legacy_receiver.addr[1]}"
+ENV['STATSD_IMPLEMENTATION'] ||= 'datadog'
+
+require 'statsd-instrument'
+require 'statsd/instrument/client'
+
+legacy_client = StatsD
+
+# Set up an UDP listener to which we can send StatsD packets
+new_client_receiver = UDPSocket.new
+new_client_receiver.bind('localhost', 0)
+
+udp_sink = StatsD::Instrument::UDPSink.new(new_client_receiver.addr[2], new_client_receiver.addr[1])
+new_client = StatsD::Instrument::Client.new(sink: udp_sink, default_sample_rate: StatsD.default_sample_rate)
+
+Benchmark.ips do |bench|
+  bench.report("Legacy client (sample rate: #{StatsD.default_sample_rate})") do
+    legacy_client.increment('StatsD.increment')
+  end
+
+  bench.report("New client (sample rate: #{StatsD.default_sample_rate})") do
+    new_client.increment('StatsD.increment')
+  end
+
+  bench.compare!
+end
+
+legacy_receiver.close
+new_client_receiver.close