statsd-instrument 3.0.0.pre1 → 3.1.0

data/lib/statsd/instrument/assertions.rb

@@ -1,231 +1,223 @@
 # 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, like 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 [Array<String>] metric_names (default: []) The metric names that are not
-  #   allowed to happen inside the block. If this is set to `[]`, 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 names, or any), occurred during the execution of the provided block.
-  def assert_no_statsd_calls(*metric_names, datagrams: nil, client: nil, &block)
-    if datagrams.nil?
-      raise LocalJumpError, "assert_no_statsd_calls requires a block" unless block_given?
-      datagrams = capture_statsd_datagrams_with_exception_handling(client: client, &block)
-    end
-
-    datagrams.select! { |metric| metric_names.include?(metric.name) } unless metric_names.empty?
-    assert(datagrams.empty?, "No StatsD calls for metric #{datagrams.map(&:name).join(', ')} expected.")
-  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, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.increment(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &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, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.measure(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &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, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.gauge(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &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, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.histogram(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
-  end
+module StatsD
+  module Instrument
+    # 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, like 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 Assertions
+      include StatsD::Instrument::Helpers
+
+      # Asserts no metric occurred during the execution of the provided block.
+      #
+      # @param [Array<String>] metric_names (default: []) The metric names that are not
+      #   allowed to happen inside the block. If this is set to `[]`, 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 names, or any), occurred during the execution of the provided block.
+      def assert_no_statsd_calls(*metric_names, datagrams: nil, client: nil, &block)
+        if datagrams.nil?
+          raise LocalJumpError, "assert_no_statsd_calls requires a block" unless block_given?
+          datagrams = capture_statsd_datagrams_with_exception_handling(client: client, &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, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.distribution(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
-  end
+        datagrams.select! { |metric| metric_names.include?(metric.name) } unless metric_names.empty?
+        assert(datagrams.empty?, "No StatsD calls for metric #{datagrams.map(&:name).join(", ")} expected.")
+      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, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.set(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
-  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, value = nil, datagrams: nil, client: nil, **options, &block)
+        expectation = StatsD::Instrument::Expectation.increment(metric_name, value, **options)
+        assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &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, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.key_value(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &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, value = nil, datagrams: nil, client: nil, **options, &block)
+        expectation = StatsD::Instrument::Expectation.measure(metric_name, value, **options)
+        assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &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
-  # @param [Array<StatsD::Instrument::Expectation>] expectations The set of
-  #   expectations to verify.
-  # @yield (see #assert_statsd_increment)
-  # @return [void]
-  # @raise (see #assert_statsd_increment)
-  def assert_statsd_expectations(expectations, datagrams: nil, client: nil, &block)
-    if datagrams.nil?
-      raise LocalJumpError, "assert_statsd_expectations requires a block" unless block_given?
-      datagrams = capture_statsd_datagrams_with_exception_handling(client: client, &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, value = nil, datagrams: nil, client: nil, **options, &block)
+        expectation = StatsD::Instrument::Expectation.gauge(metric_name, value, **options)
+        assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
+      end
 
-    expectations = Array(expectations)
-    matched_expectations = []
-    expectations.each do |expectation|
-      expectation_times = expectation.times
-      expectation_times_remaining = expectation.times
-      filtered_datagrams = datagrams.select { |m| m.type == expectation.type && m.name == expectation.name }
+      # 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, value = nil, datagrams: nil, client: nil, **options, &block)
+        expectation = StatsD::Instrument::Expectation.histogram(metric_name, value, **options)
+        assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
+      end
 
-      if filtered_datagrams.empty?
-        flunk("No StatsD calls for metric #{expectation.name} of type #{expectation.type} were made.")
+      # 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, value = nil, datagrams: nil, client: nil, **options, &block)
+        expectation = StatsD::Instrument::Expectation.distribution(metric_name, value, **options)
+        assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
       end
 
-      filtered_datagrams.each do |datagram|
-        next unless expectation.matches(datagram)
+      # 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, value = nil, datagrams: nil, client: nil, **options, &block)
+        expectation = StatsD::Instrument::Expectation.set(metric_name, value, **options)
+        assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
+      end
 
-        if expectation_times_remaining == 0
-          flunk("Unexpected StatsD call; number of times this metric " \
-            "was expected exceeded: #{expectation.inspect}")
+      # 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
+      # @param [Array<StatsD::Instrument::Expectation>] expectations The set of
+      #   expectations to verify.
+      # @yield (see #assert_statsd_increment)
+      # @return [void]
+      # @raise (see #assert_statsd_increment)
+      def assert_statsd_expectations(expectations, datagrams: nil, client: nil, &block)
+        if datagrams.nil?
+          raise LocalJumpError, "assert_statsd_expectations requires a block" unless block_given?
+          datagrams = capture_statsd_datagrams_with_exception_handling(client: client, &block)
         end
 
-        expectation_times_remaining -= 1
-        datagrams.delete(datagram)
-        if expectation_times_remaining == 0
-          matched_expectations << expectation
+        expectations = Array(expectations)
+        matched_expectations = []
+        expectations.each do |expectation|
+          expectation_times = expectation.times
+          expectation_times_remaining = expectation.times
+          filtered_datagrams = datagrams.select { |m| m.type == expectation.type && m.name == expectation.name }
+
+          if filtered_datagrams.empty?
+            flunk("No StatsD calls for metric #{expectation.name} of type #{expectation.type} were made.")
+          end
+
+          filtered_datagrams.each do |datagram|
+            next unless expectation.matches(datagram)
+
+            if expectation_times_remaining == 0
+              flunk("Unexpected StatsD call; number of times this metric " \
+                "was expected exceeded: #{expectation.inspect}")
+            end
+
+            expectation_times_remaining -= 1
+            datagrams.delete(datagram)
+            if expectation_times_remaining == 0
+              matched_expectations << expectation
+            end
+          end
+
+          next if expectation_times_remaining == 0
+
+          msg = +"Metric expected #{expectation_times} times but seen " \
+            "#{expectation_times - expectation_times_remaining} " \
+            "times: #{expectation.inspect}."
+          msg << "\nCaptured metrics with the same key: #{filtered_datagrams}" if filtered_datagrams.any?
+          flunk(msg)
         end
-      end
-
-      next if expectation_times_remaining == 0
+        expectations -= matched_expectations
 
-      msg = +"Metric expected #{expectation_times} times but seen " \
-        "#{expectation_times - expectation_times_remaining} " \
-        "times: #{expectation.inspect}."
-      msg << "\nCaptured metrics with the same key: #{filtered_datagrams}" if filtered_datagrams.any?
-      flunk(msg)
-    end
-    expectations -= matched_expectations
-
-    unless expectations.empty?
-      flunk("Unexpected StatsD calls; the following metric expectations " \
-        "were not satisfied: #{expectations.inspect}")
-    end
+        unless expectations.empty?
+          flunk("Unexpected StatsD calls; the following metric expectations " \
+            "were not satisfied: #{expectations.inspect}")
+        end
 
-    pass
-  end
+        pass
+      end
 
-  # For backwards compatibility
-  alias_method :assert_statsd_calls, :assert_statsd_expectations
-  alias_method :assert_statsd_expectation, :assert_statsd_expectations
+      # For backwards compatibility
+      alias_method :assert_statsd_calls, :assert_statsd_expectations
+      alias_method :assert_statsd_expectation, :assert_statsd_expectations
 
-  private
+      private
 
-  def capture_statsd_datagrams_with_exception_handling(client:, &block)
-    capture_statsd_datagrams(client: client, &block)
-  rescue => exception
-    flunk(<<~MESSAGE)
-      An exception occurred in the block provided to the StatsD assertion.
+      def capture_statsd_datagrams_with_exception_handling(client:, &block)
+        capture_statsd_datagrams(client: client, &block)
+      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")}
+          #{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
+          If this exception is expected, make sure to handle it using `assert_raises`
+          inside the block provided to the StatsD assertion.
+        MESSAGE
+      end
+    end
   end
 end

data/lib/statsd/instrument/batched_udp_sink.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module StatsD
+  module Instrument
+    # @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 BatchedUDPSink
+      DEFAULT_FLUSH_INTERVAL = 1.0
+      MAX_PACKET_SIZE = 508
+
+      def self.for_addr(addr, flush_interval: DEFAULT_FLUSH_INTERVAL)
+        host, port_as_string = addr.split(":", 2)
+        new(host, Integer(port_as_string), flush_interval: flush_interval)
+      end
+
+      attr_reader :host, :port
+
+      class << self
+        def finalize(dispatcher)
+          proc { dispatcher.shutdown }
+        end
+      end
+
+      def initialize(host, port, flush_interval: DEFAULT_FLUSH_INTERVAL)
+        @host = host
+        @port = port
+        @dispatcher = Dispatcher.new(host, port, flush_interval)
+        ObjectSpace.define_finalizer(self, self.class.finalize(@dispatcher))
+      end
+
+      def sample?(sample_rate)
+        sample_rate == 1 || rand < sample_rate
+      end
+
+      def <<(datagram)
+        @dispatcher << datagram
+        self
+      end
+
+      class Dispatcher
+        BUFFER_CLASS = if !::Object.const_defined?(:RUBY_ENGINE) || RUBY_ENGINE == "ruby"
+          ::Array
+        else
+          begin
+            gem("concurrent-ruby")
+          rescue Gem::MissingSpecError
+            raise Gem::MissingSpecError, "statsd-instrument depends on `concurrent-ruby` on #{RUBY_ENGINE}"
+          end
+          require "concurrent/array"
+          Concurrent::Array
+        end
+
+        def initialize(host, port, flush_interval)
+          @host = host
+          @port = port
+          @interrupted = false
+          @flush_interval = flush_interval
+          @buffer = BUFFER_CLASS.new
+          @dispatcher_thread = Thread.new { dispatch }
+        end
+
+        def <<(datagram)
+          unless @dispatcher_thread&.alive?
+            # If the dispatcher thread is dead, we assume it is because
+            # the process was forked. So to avoid ending datagrams twice
+            # we clear the buffer.
+            @buffer.clear
+            @dispatcher_thread = Thread.new { dispatch }
+          end
+          @buffer << datagram
+          self
+        end
+
+        def shutdown
+          @interrupted = true
+        end
+
+        private
+
+        NEWLINE = "\n".b.freeze
+        def flush
+          return if @buffer.empty?
+
+          datagrams = @buffer.shift(@buffer.size)
+
+          until datagrams.empty?
+            packet = String.new(datagrams.pop, encoding: Encoding::BINARY, capacity: MAX_PACKET_SIZE)
+
+            until datagrams.empty? || packet.bytesize + datagrams.first.bytesize + 1 > MAX_PACKET_SIZE
+              packet << NEWLINE << datagrams.shift
+            end
+
+            send_packet(packet)
+          end
+        end
+
+        def dispatch
+          until @interrupted
+            begin
+              start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              flush
+              next_sleep_duration = @flush_interval - (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start)
+
+              sleep(next_sleep_duration) if next_sleep_duration > 0
+            rescue => error
+              report_error(error)
+            end
+          end
+
+          flush
+          invalidate_socket
+        end
+
+        def report_error(error)
+          StatsD.logger.error do
+            "[#{self.class.name}] The dispatcher thread encountered an error #{error.class}: #{error.message}"
+          end
+        end
+
+        def send_packet(packet)
+          retried = false
+          socket.send(packet, 0)
+        rescue SocketError, IOError, SystemCallError => error
+          StatsD.logger.debug do
+            "[#{self.class.name}] Resetting connection because of #{error.class}: #{error.message}"
+          end
+          invalidate_socket
+          if retried
+            StatsD.logger.warning do
+              "[#{self.class.name}] Events were dropped because of #{error.class}: #{error.message}"
+            end
+          else
+            retried = true
+            retry
+          end
+        end
+
+        def socket
+          @socket ||= begin
+            socket = UDPSocket.new
+            socket.connect(@host, @port)
+            socket
+          end
+        end
+
+        def invalidate_socket
+          @socket&.close
+        ensure
+          @socket = nil
+        end
+      end
+    end
+  end
+end