statsd-instrument 2.5.1 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 921e9b4ecf3a6a74cfb1460767ba4374121723d9ef2a7bd76b747904a25a7b48
-  data.tar.gz: b62df176782d7aca1f24608015db7b68b610af386c7c30309517e39de3551dfe
+  metadata.gz: 0e0581a0deec7cbdfae1ca0b03d336b3e08cf1d14599087678f1a6a6ec35b321
+  data.tar.gz: f10c0f102d13bb71a8365a1cc9707c848af954adb02eea3b8bbb95a9bbc2f0b7
 SHA512:
-  metadata.gz: 3d1ff5390d8cd5dc611e42dc4667894a0c82e406d92cd51d6a71ff4cd7ffa1e747e56f8f19d483c28335a4b5a616848356fc23f50787276883aafe17b043316d
-  data.tar.gz: 542ad17d646c28b691287db6debc18a6386a332aa148d2549c60602aaab0427bb836bd755e701495aec9db856a7fa387ddbea5de3e85f7d5c973ec9d52d3c008
+  metadata.gz: 0fc4c808a257a72bf0d86edb1e9ec9ae6c700f80408f83d574e466e1ce7cf2d627aee5e71dc5fdbb998850395881421cba97172db446fc102d04314546d55f60
+  data.tar.gz: 748ffe0481def020345c33029a630b266f033d84dcf80429316e0ec95a7394b82e20f82e9ee568efa3f455ac853fcbb3fec99243da482f8af3967069dffae13e

data/.rubocop-https---shopify-github-io-ruby-style-guide-rubocop-yml

@@ -892,7 +892,7 @@ Lint/FormatParameterMismatch:
   Enabled: true
 
 Lint/HandleExceptions:
-  Enabled: true
+  AllowComments: true
 
 Lint/ImplicitStringConcatenation:
   Description: Checks for adjacent string literals on the same line, which could

data/.rubocop.yml

@@ -2,11 +2,7 @@ inherit_from:
   - https://shopify.github.io/ruby-style-guide/rubocop.yml
 
 require:
-  - ./lib/statsd/instrument/rubocop/metric_return_value.rb
-  - ./lib/statsd/instrument/rubocop/metric_value_keyword_argument.rb
-  - ./lib/statsd/instrument/rubocop/positional_arguments.rb
-  - ./lib/statsd/instrument/rubocop/splat_arguments.rb
-  - ./lib/statsd/instrument/rubocop/metaprogramming_positional_arguments.rb
+  - ./lib/statsd/instrument/rubocop.rb
 
 AllCops:
   TargetRubyVersion: 2.3
@@ -27,7 +23,10 @@ Style/ClassAndModuleChildren:
 Style/MethodCallWithArgsParentheses:
   Enabled: false # TODO: enable later
 
-# Enable our own cops on our own repos
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+# Enable our own cops on our own repo
 
 StatsD/MetricReturnValue:
   Enabled: true
@@ -43,3 +42,9 @@ StatsD/SplatArguments:
 
 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

@@ -6,6 +6,75 @@ 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
@@ -19,7 +88,7 @@ section below.
   Consider the following example:
 
   ``` ruby
-  assert_raises(RuntimeError)
+  assert_raises(RuntimeError) do
     assert_statsd_increment('foo') do
       raise 'something unexpected'
     end
@@ -39,7 +108,7 @@ section below.
   This means that the following test will fail:
 
   ``` ruby
-  assert_raises(RuntimeError)
+  assert_raises(RuntimeError) do
     assert_statsd_increment('foo') do
       StatsD.increment('foo')
       raise 'something unexpected'
@@ -53,7 +122,7 @@ section below.
 
   ``` ruby
   assert_statsd_increment('foo') do
-    assert_raises(RuntimeError)
+    assert_raises(RuntimeError) do
       StatsD.increment('foo')
       raise 'something unexpected'
     end
@@ -62,7 +131,7 @@ section below.
 
   See #193, #184, and #166 for more information.
 
-## Version 2.5.1
+## Verison 2.5.1
 
 - **Bugfix:** when using metaprogramming methods, changes to `StatsD.prefix` after
   the metaprogramming method was evaluated would not be respected. This
@@ -73,7 +142,7 @@ section below.
 
 ## Version 2.5.0
 
-- **DEPRECATION**: Providing a sample rate and tags to your metrics and method
+- **⚠️ 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.
@@ -115,7 +184,7 @@ section below.
 
   ```
 
-- **DEPRECATION**: Relying on the return value of the StatsD metric methods
+- **⚠️ 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.
 

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/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

data/lib/statsd/instrument/assertions.rb

@@ -1,121 +1,232 @@
 # frozen_string_literal: true
 
+# This module defines several assertion methods that can be used to verify that
+# your application is emitting the right StatsD metrics.
+#
+# Every metric type has its own assertion method, like {#assert_statsd_increment}
+# to assert `StatsD.increment` calls. You can also assert other properties of the
+# metric that was emitted, lioke the sample rate or presence of tags.
+# To check for the absence of metrics, use {#assert_no_statsd_calls}.
+#
+# @example Check for metric properties:
+#   assert_statsd_measure('foo', sample_rate: 0.1, tags: ["bar"]) do
+#     StatsD.measure('foo', sample_rate: 0.5, tags: ['bar','baz']) do
+#       some_code_to_measure
+#     end
+#   end
+#
+# @example Check for multiple occurrences:
+#   assert_statsd_increment('foo', times: 2) do
+#     StatsD.increment('foo')
+#     StatsD.increment('foo')
+#   end
+#
+# @example Absence of metrics
+#   assert_no_statsd_calls do
+#     foo
+#   end
+#
+# @example Handling exceptions
+#   assert_statsd_increment('foo.error') do
+#     # If we expect exceptions to occur, we have to handle them inside
+#     # the block we pass to assert_statsd_increment.
+#     assert_raises(RuntimeError) do
+#       begin
+#         attempt_foo
+#       rescue
+#         StatsD.increment('foo.error')
+#         raise 'foo failed'
+#       end
+#     end
+#   end
 module StatsD::Instrument::Assertions
   include StatsD::Instrument::Helpers
 
+  # Asserts no metric occurred during the execution of the provided block.
+  #
+  # @param [String] metric_name (default: nil) The metric name that is not allowed
+  #   to happen inside the block. If this is set to `nil`, the assertion will fail
+  #   if any metric occurs.
+  # @yield A block in which the specified metric should not occur. This block
+  #   should not raise any exceptions.
+  # @return [void]
+  # @raise [Minitest::Assertion] If an exception occurs, or if any metric (with the
+  #   provided name, or any), occurred during the execution of the provided block.
   def assert_no_statsd_calls(metric_name = nil, &block)
     metrics = capture_statsd_calls(&block)
     metrics.select! { |m| m.name == metric_name } if metric_name
     assert(metrics.empty?, "No StatsD calls for metric #{metrics.map(&:name).join(', ')} expected.")
+  rescue => exception
+    flunk(<<~MESSAGE)
+      An exception occurred in the block provided to the StatsD assertion.
+
+      #{exception.class.name}: #{exception.message}
+      \t#{exception.backtrace.join("\n\t")}
+
+      If this exception is expected, make sure to handle it using `assert_raises`
+      inside the block provided to the StatsD assertion.
+    MESSAGE
   end
 
+  # Asserts that a given counter metric occurred inside the provided block.
+  #
+  # @param [String] metric_name The name of the metric that should occur.
+  # @param [Hash] options (see StatsD::Instrument::MetricExpectation.new)
+  # @yield A block in which the specified metric should occur. This block
+  #   should not raise any exceptions.
+  # @return [void]
+  # @raise [Minitest::Assertion] If an exception occurs, or if the metric did
+  #   not occur as specified during the execution the block.
   def assert_statsd_increment(metric_name, options = {}, &block)
     assert_statsd_call(:c, metric_name, options, &block)
   end
 
+  # Asserts that a given timing metric occurred inside the provided block.
+  #
+  # @param metric_name (see #assert_statsd_increment)
+  # @param options (see #assert_statsd_increment)
+  # @yield (see #assert_statsd_increment)
+  # @return [void]
+  # @raise (see #assert_statsd_increment)
   def assert_statsd_measure(metric_name, options = {}, &block)
     assert_statsd_call(:ms, metric_name, options, &block)
   end
 
+  # Asserts that a given gauge metric occurred inside the provided block.
+  #
+  # @param metric_name (see #assert_statsd_increment)
+  # @param options (see #assert_statsd_increment)
+  # @yield (see #assert_statsd_increment)
+  # @return [void]
+  # @raise (see #assert_statsd_increment)
   def assert_statsd_gauge(metric_name, options = {}, &block)
     assert_statsd_call(:g, metric_name, options, &block)
   end
 
+  # Asserts that a given histogram metric occurred inside the provided block.
+  #
+  # @param metric_name (see #assert_statsd_increment)
+  # @param options (see #assert_statsd_increment)
+  # @yield (see #assert_statsd_increment)
+  # @return [void]
+  # @raise (see #assert_statsd_increment)
   def assert_statsd_histogram(metric_name, options = {}, &block)
     assert_statsd_call(:h, metric_name, options, &block)
   end
 
+  # Asserts that a given distribution metric occurred inside the provided block.
+  #
+  # @param metric_name (see #assert_statsd_increment)
+  # @param options (see #assert_statsd_increment)
+  # @yield (see #assert_statsd_increment)
+  # @return [void]
+  # @raise (see #assert_statsd_increment)
   def assert_statsd_distribution(metric_name, options = {}, &block)
     assert_statsd_call(:d, metric_name, options, &block)
   end
 
+  # Asserts that a given set metric occurred inside the provided block.
+  #
+  # @param metric_name (see #assert_statsd_increment)
+  # @param options (see #assert_statsd_increment)
+  # @yield (see #assert_statsd_increment)
+  # @return [void]
+  # @raise (see #assert_statsd_increment)
   def assert_statsd_set(metric_name, options = {}, &block)
     assert_statsd_call(:s, metric_name, options, &block)
   end
 
+  # Asserts that a given key/value metric occurred inside the provided block.
+  #
+  # @param metric_name (see #assert_statsd_increment)
+  # @param options (see #assert_statsd_increment)
+  # @yield (see #assert_statsd_increment)
+  # @return [void]
+  # @raise (see #assert_statsd_increment)
   def assert_statsd_key_value(metric_name, options = {}, &block)
     assert_statsd_call(:kv, metric_name, options, &block)
   end
 
+  # Asserts that the set of provided metric expectations came true.
+  #
+  # Generally, it's recommended to  use more specific assertion methods, like
+  # {#assert_statsd_increment} and others.
+  #
   # @private
-  def assert_statsd_calls(expected_metrics, &block)
+  # @param [Array<StatsD::Instrument::MetricExpectation>] expected_metrics The set of
+  #   metric expectations to verify.
+  # @yield (see #assert_statsd_increment)
+  # @return [void]
+  # @raise (see #assert_statsd_increment)
+  def assert_statsd_calls(expected_metrics)
     raise ArgumentError, "block must be given" unless block_given?
 
     capture_backend = StatsD::Instrument::Backends::CaptureBackend.new
     with_capture_backend(capture_backend) do
-      exception_occurred = nil
       begin
-        block.call
+        yield
       rescue => exception
-        exception_occurred = exception
-        raise
-      ensure
-        metrics = capture_backend.collected_metrics
-        matched_expected_metrics = []
-        expected_metrics.each do |expected_metric|
-          expected_metric_times = expected_metric.times
-          expected_metric_times_remaining = expected_metric.times
-          filtered_metrics = metrics.select { |m| m.type == expected_metric.type && m.name == expected_metric.name }
-
-          if filtered_metrics.empty?
-            flunk_with_exception_info(exception_occurred, "No StatsD calls for metric #{expected_metric.name} " \
-              "of type #{expected_metric.type} were made.")
-          end
+        flunk(<<~MESSAGE)
+          An exception occurred in the block provided to the StatsD assertion.
 
-          filtered_metrics.each do |metric|
-            next unless expected_metric.matches(metric)
+          #{exception.class.name}: #{exception.message}
+          \t#{exception.backtrace.join("\n\t")}
 
-            assert(within_numeric_range?(metric.sample_rate),
-              "Unexpected sample rate type for metric #{metric.name}, must be numeric")
+          If this exception is expected, make sure to handle it using `assert_raises`
+          inside the block provided to the StatsD assertion.
+        MESSAGE
+      end
 
-            if expected_metric_times_remaining == 0
-              flunk_with_exception_info(exception_occurred, "Unexpected StatsD call; number of times this metric " \
-                "was expected exceeded: #{expected_metric.inspect}")
-            end
+      metrics = capture_backend.collected_metrics
+      matched_expected_metrics = []
+      expected_metrics.each do |expected_metric|
+        expected_metric_times = expected_metric.times
+        expected_metric_times_remaining = expected_metric.times
+        filtered_metrics = metrics.select { |m| m.type == expected_metric.type && m.name == expected_metric.name }
 
-            expected_metric_times_remaining -= 1
-            metrics.delete(metric)
-            if expected_metric_times_remaining == 0
-              matched_expected_metrics << expected_metric
-            end
-          end
+        if filtered_metrics.empty?
+          flunk("No StatsD calls for metric #{expected_metric.name} of type #{expected_metric.type} were made.")
+        end
 
-          next if expected_metric_times_remaining == 0
+        filtered_metrics.each do |metric|
+          next unless expected_metric.matches(metric)
 
-          msg = +"Metric expected #{expected_metric_times} times but seen " \
-            "#{expected_metric_times - expected_metric_times_remaining} " \
-            "times: #{expected_metric.inspect}."
-          msg << "\nCaptured metrics with the same key: #{filtered_metrics}" if filtered_metrics.any?
-          flunk_with_exception_info(exception_occurred, msg)
-        end
-        expected_metrics -= matched_expected_metrics
+          assert(within_numeric_range?(metric.sample_rate),
+            "Unexpected sample rate type for metric #{metric.name}, must be numeric")
+
+          if expected_metric_times_remaining == 0
+            flunk("Unexpected StatsD call; number of times this metric " \
+              "was expected exceeded: #{expected_metric.inspect}")
+          end
 
-        unless expected_metrics.empty?
-          flunk_with_exception_info(exception_occurred, "Unexpected StatsD calls; the following metric expectations " \
-            "were not satisfied: #{expected_metrics.inspect}")
+          expected_metric_times_remaining -= 1
+          metrics.delete(metric)
+          if expected_metric_times_remaining == 0
+            matched_expected_metrics << expected_metric
+          end
         end
 
-        pass
+        next if expected_metric_times_remaining == 0
+
+        msg = +"Metric expected #{expected_metric_times} times but seen " \
+          "#{expected_metric_times - expected_metric_times_remaining} " \
+          "times: #{expected_metric.inspect}."
+        msg << "\nCaptured metrics with the same key: #{filtered_metrics}" if filtered_metrics.any?
+        flunk(msg)
       end
-    end
-  end
+      expected_metrics -= matched_expected_metrics
 
-  private
+      unless expected_metrics.empty?
+        flunk("Unexpected StatsD calls; the following metric expectations " \
+          "were not satisfied: #{expected_metrics.inspect}")
+      end
 
-  def flunk_with_exception_info(exception, message)
-    if exception
-      flunk(<<~EXCEPTION)
-        #{message}
-
-        This could be due to the exception that occurred inside the block:
-        #{exception.class.name}: #{exception.message}
-        \t#{exception.backtrace.join("\n\t")}
-      EXCEPTION
-    else
-      flunk(message)
+      pass
     end
   end
 
+  private
+
   def assert_statsd_call(metric_type, metric_name, options = {}, &block)
     options[:name] = metric_name
     options[:type] = metric_type