statsd-instrument 2.3.2 → 2.6.0

data/benchmark/send-metrics-to-dev-null-log

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'benchmark/ips'
+require 'logger'
+
+revision = %x(git rev-parse HEAD).rstrip
+master_revision = %x(git rev-parse origin/master).rstrip
+branch = if revision == master_revision
+  'master'
+else
+  %x(git rev-parse --abbrev-ref HEAD).rstrip
+end
+
+intermediate_results_filename = "#{Dir.tmpdir}/statsd-instrument-benchmarks/#{File.basename($PROGRAM_NAME)}"
+FileUtils.mkdir_p(File.dirname(intermediate_results_filename))
+
+ENV['ENV'] = "development"
+require 'statsd-instrument'
+StatsD.logger = Logger.new(File::NULL)
+
+report = Benchmark.ips do |bench|
+  bench.report("StatsD metrics to /dev/null log (branch: #{branch}, sha: #{revision[0, 7]})") do
+    StatsD.increment('StatsD.increment', 10, sample_rate: 15)
+    StatsD.measure('StatsD.measure') { 1 + 1 }
+    StatsD.gauge('StatsD.gauge', 12.0, tags: ["foo:bar", "quc"])
+    StatsD.set('StatsD.set', 'value', tags: { foo: 'bar', baz: 'quc' })
+    StatsD.event('StasD.event', "12345")
+    StatsD.service_check("StatsD.service_check", "ok")
+  end
+
+  # Store the results in between runs
+  bench.save!(intermediate_results_filename)
+  bench.compare!
+end
+
+if report.entries.length == 1
+  puts
+  puts "To compare the performance of this revision against another revision (e.g. master),"
+  puts "check out a different branch and run this benchmark script again."
+elsif ENV['KEEP_RESULTS']
+  puts
+  puts "The intermediate results have been stored in #{intermediate_results_filename}"
+else
+  File.unlink(intermediate_results_filename)
+end

data/benchmark/send-metrics-to-local-udp-receiver

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'benchmark/ips'
+require 'socket'
+
+revision = %x(git rev-parse HEAD).rstrip
+master_revision = %x(git rev-parse origin/master).rstrip
+branch = if revision == master_revision
+  'master'
+else
+  %x(git rev-parse --abbrev-ref HEAD).rstrip
+end
+
+intermediate_results_filename = "#{Dir.tmpdir}/statsd-instrument-benchmarks/#{File.basename($PROGRAM_NAME)}"
+FileUtils.mkdir_p(File.dirname(intermediate_results_filename))
+
+# Set up an UDP listener to which we can send StatsD packets
+receiver = UDPSocket.new
+receiver.bind('localhost', 0)
+
+ENV['ENV'] = "production"
+ENV['STATSD_ADDR'] = "#{receiver.addr[2]}:#{receiver.addr[1]}"
+ENV['STATSD_IMPLEMENTATION'] ||= 'datadog'
+
+require 'statsd-instrument'
+
+report = Benchmark.ips do |bench|
+  bench.report("StatsD metrics to local UDP receiver (branch: #{branch}, sha: #{revision[0, 7]})") do
+    StatsD.increment('StatsD.increment', 10)
+    StatsD.measure('StatsD.measure') { 1 + 1 }
+    StatsD.gauge('StatsD.gauge', 12.0, tags: ["foo:bar", "quc"])
+    StatsD.set('StatsD.set', 'value', tags: { foo: 'bar', baz: 'quc' })
+    if StatsD.backend.implementation == :datadog
+      StatsD.event('StasD.event', "12345")
+      StatsD.service_check("StatsD.service_check", "ok")
+    end
+  end
+
+  # Store the results in between runs
+  bench.save!(intermediate_results_filename)
+  bench.compare!
+end
+
+receiver.close
+
+if report.entries.length == 1
+  puts
+  puts "To compare the performance of this revision against another revision (e.g. master),"
+  puts "check out a different branch and run this benchmark script again."
+elsif ENV['KEEP_RESULTS']
+  puts
+  puts "The intermediate results have been stored in #{intermediate_results_filename}"
+else
+  File.unlink(intermediate_results_filename)
+end

data/lib/statsd/instrument/assertions.rb

@@ -1,79 +1,228 @@
+# 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."
+    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)
-    unless block
-      raise ArgumentError, "block must be given"
-    end
+  # @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
+      begin
+        yield
+      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
+
+      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("No StatsD calls for metric #{expected_metric.name} of type #{expected_metric.type} were made.")
+        end
+
+        filtered_metrics.each do |metric|
+          next unless expected_metric.matches(metric)
+
+          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
 
-    metrics = capture_statsd_calls(&block)
-    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 }
-      assert filtered_metrics.length > 0,
-        "No StatsD calls for metric #{expected_metric.name} of type #{expected_metric.type} were made."
-
-      filtered_metrics.each do |metric|
-        assert within_numeric_range?(metric.sample_rate),
-          "Unexpected sample rate type for metric #{metric.name}, must be numeric"
-        if expected_metric.matches(metric)
-          assert expected_metric_times_remaining > 0,
-            "Unexpected StatsD call; number of times this metric was expected exceeded: #{expected_metric.inspect}"
           expected_metric_times_remaining -= 1
           metrics.delete(metric)
           if expected_metric_times_remaining == 0
             matched_expected_metrics << expected_metric
           end
         end
+
+        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
+      expected_metrics -= matched_expected_metrics
 
-      assert expected_metric_times_remaining == 0,
-          "Metric expected #{expected_metric_times} times but seen"\
-          " #{expected_metric_times-expected_metric_times_remaining}"\
-          " times: #{expected_metric.inspect}"
-    end
-    expected_metrics -= matched_expected_metrics
+      unless expected_metrics.empty?
+        flunk("Unexpected StatsD calls; the following metric expectations " \
+          "were not satisfied: #{expected_metrics.inspect}")
+      end
 
-    assert expected_metrics.empty?,
-      "Unexpected StatsD calls; the following metric expectations were not satisfied: #{expected_metrics.inspect}"
+      pass
+    end
   end
 
   private
@@ -87,6 +236,6 @@ module StatsD::Instrument::Assertions
   end
 
   def within_numeric_range?(object)
-    object.kind_of?(Numeric) && (0.0..1.0).cover?(object)
+    object.is_a?(Numeric) && (0.0..1.0).cover?(object)
   end
 end

data/lib/statsd/instrument/backend.rb

@@ -1,12 +1,13 @@
+# frozen_string_literal: true
+
 # 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)
+  def collect_metric(_metric)
     raise NotImplementedError, "Use a concerete backend implementation"
   end
 end

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

@@ -1,5 +1,6 @@
-module StatsD::Instrument::Backends
+# frozen_string_literal: true
 
+module StatsD::Instrument::Backends
   # The capture backend is used to capture the metrics that are collected, so you can
   # run assertions on them.
   #
@@ -8,6 +9,7 @@ module StatsD::Instrument::Backends
   # @see StatsD::Instrument::Assertions
   class CaptureBackend < StatsD::Instrument::Backend
     attr_reader :collected_metrics
+    attr_accessor :parent
 
     def initialize
       reset
@@ -17,6 +19,7 @@ module StatsD::Instrument::Backends
     # @param metric [StatsD::Instrument::Metric]  The metric to collect.
     # @return [void]
     def collect_metric(metric)
+      parent&.collect_metric(metric)
       @collected_metrics << metric
     end
 

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

@@ -1,10 +1,10 @@
-module StatsD::Instrument::Backends
+# frozen_string_literal: true
 
+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)
@@ -14,7 +14,7 @@ module StatsD::Instrument::Backends
     # @param metric [StatsD::Instrument::Metric]
     # @return [void]
     def collect_metric(metric)
-      logger.info "[StatsD] #{metric}"
+      logger.info("[StatsD] #{metric}")
     end
   end
 end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StatsD::Instrument::Backends
   # The null backend does nothing when receiving a metric, effectively disabling the gem completely.
   class NullBackend < StatsD::Instrument::Backend

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

@@ -1,63 +1,56 @@
+# frozen_string_literal: true
+
 require 'monitor'
 
 module StatsD::Instrument::Backends
   class UDPBackend < StatsD::Instrument::Backend
-
     BASE_SUPPORTED_METRIC_TYPES = { c: true, ms: true, g: true, s: true }
 
     class DogStatsDProtocol
-      EVENT_OPTIONS = {
-        date_happened: 'd',
-        hostname: 'h',
-        aggregation_key: 'k',
-        priority: 'p',
-        source_type_name: 's',
-        alert_type: 't',
-      }
-
-      SERVICE_CHECK_OPTIONS = {
-        timestamp: 'd',
-        hostname: 'h',
-        message: 'm',
-      }
-
       SUPPORTED_METRIC_TYPES = BASE_SUPPORTED_METRIC_TYPES.merge(h: true, _e: true, _sc: true, d: true)
 
+      SERVICE_CHECK_STATUSES = { ok: 0, warning: 1, critical: 2, unknown: 3 }
+
       def generate_packet(metric)
-        packet = ""
+        packet = +""
 
         if metric.type == :_e
-          escaped_title = metric.name.tr('\n', '\\n')
-          escaped_text = metric.value.tr('\n', '\\n')
+          escaped_title = metric.name.gsub("\n", "\\n")
+          escaped_text = metric.value.gsub("\n", "\\n")
 
           packet << "_e{#{escaped_title.size},#{escaped_text.size}}:#{escaped_title}|#{escaped_text}"
-          packet << generate_metadata(metric, EVENT_OPTIONS)
+          packet << "|h:#{metric.metadata[:hostname]}" if metric.metadata[:hostname]
+          packet << "|d:#{metric.metadata[:timestamp].to_i}" if metric.metadata[:timestamp]
+          packet << "|k:#{metric.metadata[:aggregation_key]}" if metric.metadata[:aggregation_key]
+          packet << "|p:#{metric.metadata[:priority]}" if metric.metadata[:priority]
+          packet << "|s:#{metric.metadata[:source_type_name]}" if metric.metadata[:source_type_name]
+          packet << "|t:#{metric.metadata[:alert_type]}" if metric.metadata[:alert_type]
+          packet << "|##{metric.tags.join(',')}" if metric.tags
+
         elsif metric.type == :_sc
-          packet << "_sc|#{metric.name}|#{metric.value}"
-          packet << generate_metadata(metric, SERVICE_CHECK_OPTIONS)
+          status = metric.value.is_a?(Integer) ? metric.value : SERVICE_CHECK_STATUSES.fetch(metric.value.to_sym)
+
+          packet << "_sc|#{metric.name}|#{status}"
+          packet << "|h:#{metric.metadata[:hostname]}" if metric.metadata[:hostname]
+          packet << "|d:#{metric.metadata[:timestamp].to_i}" if metric.metadata[:timestamp]
+          packet << "|##{metric.tags.join(',')}" if metric.tags
+          packet << "|m:#{metric.metadata[:message]}" if metric.metadata[:message]
+
         else
           packet << "#{metric.name}:#{metric.value}|#{metric.type}"
+          packet << "|@#{metric.sample_rate}" if metric.sample_rate < 1
+          packet << "|##{metric.tags.join(',')}" if metric.tags
         end
 
-        packet << "|@#{metric.sample_rate}" if metric.sample_rate < 1
-        packet << "|##{metric.tags.join(',')}" if metric.tags
         packet
       end
-
-      private
-
-      def generate_metadata(metric, options)
-        (metric.metadata.keys & options.keys).map do |key|
-          "|#{options[key]}:#{metric.metadata[key]}"
-        end.join
-      end
     end
 
     class StatsiteStatsDProtocol
       SUPPORTED_METRIC_TYPES = BASE_SUPPORTED_METRIC_TYPES.merge(kv: true)
 
       def generate_packet(metric)
-        packet = "#{metric.name}:#{metric.value}|#{metric.type}"
+        packet = +"#{metric.name}:#{metric.value}|#{metric.type}"
         packet << "|@#{metric.sample_rate}" unless metric.sample_rate == 1
         packet << "\n"
         packet
@@ -68,7 +61,7 @@ module StatsD::Instrument::Backends
       SUPPORTED_METRIC_TYPES = BASE_SUPPORTED_METRIC_TYPES
 
       def generate_packet(metric)
-        packet = "#{metric.name}:#{metric.value}|#{metric.type}"
+        packet = +"#{metric.name}:#{metric.value}|#{metric.type}"
         packet << "|@#{metric.sample_rate}" if metric.sample_rate < 1
         packet
       end
@@ -88,19 +81,20 @@ module StatsD::Instrument::Backends
 
     def implementation=(value)
       @packet_factory = case value
-        when :datadog
-          DogStatsDProtocol.new
-        when :statsite
-          StatsiteStatsDProtocol.new
-        else
-          StatsDProtocol.new
-        end
+      when :datadog
+        DogStatsDProtocol.new
+      when :statsite
+        StatsiteStatsDProtocol.new
+      else
+        StatsDProtocol.new
+      end
       @implementation = value
     end
 
     def collect_metric(metric)
       unless @packet_factory.class::SUPPORTED_METRIC_TYPES[metric.type]
-        StatsD.logger.warn("[StatsD] Metric type #{metric.type.inspect} not supported on #{implementation} implementation.")
+        StatsD.logger.warn("[StatsD] Metric type #{metric.type.inspect} is not supported " \
+          "on #{implementation} implementation.")
         return false
       end
 
@@ -139,13 +133,13 @@ module StatsD::Instrument::Backends
       synchronize do
         socket.send(command, 0) > 0
       end
-    rescue ThreadError => e
+    rescue ThreadError
       # In cases where a TERM or KILL signal has been sent, and we send stats as
       # part of a signal handler, locks cannot be acquired, so we do our best
       # to try and send the command without a lock.
       socket.send(command, 0) > 0
-    rescue SocketError, IOError, SystemCallError, Errno::ECONNREFUSED => e
-      StatsD.logger.error "[StatsD] #{e.class.name}: #{e.message}"
+    rescue SocketError, IOError, SystemCallError => e
+      StatsD.logger.error("[StatsD] #{e.class.name}: #{e.message}")
       invalidate_socket
     end
 

data/lib/statsd/instrument/capture_sink.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# @note This class is part of the new Client implementation that is intended
+#   to become the new default in the next major release of this library.
+class StatsD::Instrument::CaptureSink
+  attr_reader :parent, :datagrams, :datagram_class
+
+  def initialize(parent:, datagram_class: StatsD::Instrument::Datagram)
+    @parent = parent
+    @datagram_class = datagram_class
+    @datagrams = []
+  end
+
+  def sample?(_sample_rate)
+    true
+  end
+
+  def <<(datagram)
+    @datagrams << datagram_class.new(datagram)
+    parent << datagram
+    self
+  end
+
+  def clear
+    @datagrams.clear
+  end
+end