statsd-instrument 2.6.0 → 2.7.0

data/lib/statsd/instrument/assertions.rb

@@ -52,20 +52,14 @@ module StatsD::Instrument::Assertions
   # @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")}
+  def assert_no_statsd_calls(metric_name = nil, 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
 
-      If this exception is expected, make sure to handle it using `assert_raises`
-      inside the block provided to the StatsD assertion.
-    MESSAGE
+    datagrams.select! { |m| m.name == metric_name } if metric_name
+    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.
@@ -77,8 +71,9 @@ module StatsD::Instrument::Assertions
   # @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)
+  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.
@@ -88,8 +83,9 @@ module StatsD::Instrument::Assertions
   # @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)
+  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.
@@ -99,8 +95,9 @@ module StatsD::Instrument::Assertions
   # @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)
+  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.
@@ -110,8 +107,9 @@ module StatsD::Instrument::Assertions
   # @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)
+  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
 
   # Asserts that a given distribution metric occurred inside the provided block.
@@ -121,8 +119,9 @@ module StatsD::Instrument::Assertions
   # @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)
+  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
 
   # Asserts that a given set metric occurred inside the provided block.
@@ -132,8 +131,9 @@ module StatsD::Instrument::Assertions
   # @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)
+  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 key/value metric occurred inside the provided block.
@@ -143,8 +143,9 @@ module StatsD::Instrument::Assertions
   # @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)
+  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 the set of provided metric expectations came true.
@@ -153,89 +154,78 @@ module StatsD::Instrument::Assertions
   # {#assert_statsd_increment} and others.
   #
   # @private
-  # @param [Array<StatsD::Instrument::MetricExpectation>] expected_metrics The set of
-  #   metric expectations to verify.
+  # @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_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
+  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
 
-        filtered_metrics.each do |metric|
-          next unless expected_metric.matches(metric)
+    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 }
 
-          assert(within_numeric_range?(metric.sample_rate),
-            "Unexpected sample rate type for metric #{metric.name}, must be numeric")
+      if filtered_datagrams.empty?
+        flunk("No StatsD calls for metric #{expectation.name} of type #{expectation.type} were made.")
+      end
 
-          if expected_metric_times_remaining == 0
-            flunk("Unexpected StatsD call; number of times this metric " \
-              "was expected exceeded: #{expected_metric.inspect}")
-          end
+      filtered_datagrams.each do |datagram|
+        next unless expectation.matches(datagram)
 
-          expected_metric_times_remaining -= 1
-          metrics.delete(metric)
-          if expected_metric_times_remaining == 0
-            matched_expected_metrics << expected_metric
-          end
+        if expectation_times_remaining == 0
+          flunk("Unexpected StatsD call; number of times this metric " \
+            "was expected exceeded: #{expectation.inspect}")
         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)
+        expectation_times_remaining -= 1
+        datagrams.delete(datagram)
+        if expectation_times_remaining == 0
+          matched_expectations << expectation
+        end
       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
+      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
+    expectations -= matched_expectations
 
-      pass
+    unless expectations.empty?
+      flunk("Unexpected StatsD calls; the following metric expectations " \
+        "were not satisfied: #{expectations.inspect}")
     end
+
+    pass
   end
 
+  # For backwards compatibility
+  alias_method :assert_statsd_calls, :assert_statsd_expectations
+  alias_method :assert_statsd_expectation, :assert_statsd_expectations
+
   private
 
-  def assert_statsd_call(metric_type, metric_name, options = {}, &block)
-    options[:name] = metric_name
-    options[:type] = metric_type
-    options[:times] ||= 1
-    expected_metric = StatsD::Instrument::MetricExpectation.new(options)
-    assert_statsd_calls([expected_metric], &block)
-  end
+  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")}
 
-  def within_numeric_range?(object)
-    object.is_a?(Numeric) && (0.0..1.0).cover?(object)
+      If this exception is expected, make sure to handle it using `assert_raises`
+      inside the block provided to the StatsD assertion.
+    MESSAGE
   end
 end

data/lib/statsd/instrument/client.rb

@@ -11,8 +11,8 @@ require 'statsd/instrument/log_sink'
 
 # The Client is the main interface for using StatsD.
 #
-# @note This new new Client implementation that is intended to become the new default in
-#   the next major release of this library. While this class may already be functional,
+# @note This new Client implementation is intended to become the new default in the
+#   next major release of this library. While this class may already be functional,
 #   we provide no guarantees about the API and the behavior may change.
 class StatsD::Instrument::Client
   attr_reader :sink, :datagram_builder_class, :prefix, :default_tags, :default_sample_rate

data/lib/statsd/instrument/datagram.rb

@@ -17,7 +17,7 @@ class StatsD::Instrument::Datagram
   end
 
   def type
-    parsed_datagram[:type]
+    @type ||= parsed_datagram[:type].to_sym
   end
 
   def name
@@ -25,7 +25,16 @@ class StatsD::Instrument::Datagram
   end
 
   def value
-    parsed_datagram[:value]
+    @value ||= case type
+    when :c
+      Integer(parsed_datagram[:value])
+    when :g, :h, :d, :kv, :ms
+      Float(parsed_datagram[:value])
+    when :s
+      String(parsed_datagram[:value])
+    else
+      parsed_datagram[:value]
+    end
   end
 
   def tags
@@ -59,7 +68,7 @@ class StatsD::Instrument::Datagram
     \A
     (?<name>[^\:\|\@]+)\:(?<value>[^\:\|\@]+)\|(?<type>c|ms|g|s|h|d)
     (?:\|\@(?<sample_rate>\d*(?:\.\d*)?))?
-    (?:\|\#(?<tags>(?:[^\|\#,]+(?:,[^\|\#,]+)*)))?
+    (?:\|\#(?<tags>(?:[^\|,]+(?:,[^\|,]+)*)))?
     \n? # In some implementations, the datagram may include a trailing newline.
     \z
   }x

data/lib/statsd/instrument/environment.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'logger'
-
 # The environment module is used to detect, and initialize the environment in
 # which this library is active. It will use different default values based on the environment.
 class StatsD::Instrument::Environment
@@ -78,7 +76,7 @@ class StatsD::Instrument::Environment
   end
 
   def statsd_implementation
-    env.fetch('STATSD_IMPLEMENTATION', 'statsd')
+    env.fetch('STATSD_IMPLEMENTATION', 'datadog')
   end
 
   def statsd_sample_rate
@@ -97,6 +95,14 @@ class StatsD::Instrument::Environment
     env.key?('STATSD_DEFAULT_TAGS') ? env.fetch('STATSD_DEFAULT_TAGS').split(',') : nil
   end
 
+  def client
+    if env.key?('STATSD_USE_NEW_CLIENT')
+      default_client
+    else
+      StatsD::Instrument::LegacyClient.singleton
+    end
+  end
+
   def default_client
     @default_client ||= StatsD::Instrument::Client.new(
       sink: default_sink_for_environment,

data/lib/statsd/instrument/expectation.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# @private
+class StatsD::Instrument::Expectation
+  class << self
+    def increment(name, **options)
+      new(type: :c, name: name, **options)
+    end
+
+    def measure(name, **options)
+      new(type: :ms, name: name, **options)
+    end
+
+    def gauge(name, **options)
+      new(type: :g, name: name, **options)
+    end
+
+    def set(name, **options)
+      new(type: :s, name: name, **options)
+    end
+
+    def key_value(name, **options)
+      new(type: :kv, name: name, **options)
+    end
+
+    def distribution(name, **options)
+      new(type: :d, name: name, **options)
+    end
+
+    def histogram(name, **options)
+      new(type: :h, name: name, **options)
+    end
+  end
+
+  attr_accessor :times, :type, :name, :value, :sample_rate, :tags
+  attr_reader :ignore_tags
+
+  def initialize(type:, name:, value: nil, sample_rate: nil, tags: nil, ignore_tags: nil, no_prefix: false, times: 1)
+    @type = type
+    @name = StatsD.prefix ? "#{StatsD.prefix}.#{name}" : name unless no_prefix
+    @value = normalized_value_for_type(type, value) if value
+    @sample_rate = sample_rate
+    @tags = StatsD::Instrument::Metric.normalize_tags(tags)
+    @ignore_tags = StatsD::Instrument::Metric.normalize_tags(ignore_tags)
+    @times = times
+  end
+
+  def normalized_value_for_type(type, value)
+    case type
+    when :c then Integer(value)
+    when :g, :h, :d, :kv, :ms then Float(value)
+    when :s then String(value)
+    else value
+    end
+  end
+
+  def matches(actual_metric)
+    return false if sample_rate && sample_rate != actual_metric.sample_rate
+    return false if value && value != normalized_value_for_type(actual_metric.type, actual_metric.value)
+
+    if tags
+      expected_tags = Set.new(tags)
+      actual_tags = Set.new(actual_metric.tags)
+
+      if ignore_tags
+        ignored_tags = Set.new(ignore_tags) - expected_tags
+        actual_tags -= ignored_tags
+
+        if ignore_tags.is_a?(Array)
+          actual_tags.delete_if { |key| ignore_tags.include?(key.split(":").first) }
+        end
+      end
+
+      return expected_tags.subset?(actual_tags)
+    end
+    true
+  end
+
+  def to_s
+    str = +"#{name}:#{value || '<anything>'}|#{type}"
+    str << "|@#{sample_rate}" if sample_rate
+    str << "|#" << tags.join(',') if tags
+    str << " (expected #{times} times)" if times > 1
+    str
+  end
+
+  def inspect
+    "#<StatsD::Instrument::Expectation:\"#{self}\">"
+  end
+end
+
+# For backwards compatibility
+StatsD::Instrument::MetricExpectation = StatsD::Instrument::Expectation

data/lib/statsd/instrument/helpers.rb

@@ -1,22 +1,40 @@
 # frozen_string_literal: true
 
 module StatsD::Instrument::Helpers
-  def with_capture_backend(backend, &block)
-    if StatsD.backend.is_a?(StatsD::Instrument::Backends::CaptureBackend)
-      backend.parent = StatsD.backend
+  def capture_statsd_datagrams(client: nil, &block)
+    client ||= StatsD.singleton_client
+    case client
+    when StatsD.legacy_singleton_client
+      capture_statsd_metrics_on_legacy_client(&block)
+    when StatsD::Instrument::Client
+      client.capture(&block)
+    else
+      raise ArgumentError, "Don't know how to capture StatsD datagrams from #{client.inspect}!"
     end
-
-    old_backend = StatsD.backend
-    StatsD.backend = backend
-
-    block.call
-  ensure
-    StatsD.backend = old_backend
   end
 
-  def capture_statsd_calls(&block)
+  # For backwards compatibility
+  alias_method :capture_statsd_calls, :capture_statsd_datagrams
+
+  def capture_statsd_metrics_on_legacy_client(&block)
     capture_backend = StatsD::Instrument::Backends::CaptureBackend.new
     with_capture_backend(capture_backend, &block)
     capture_backend.collected_metrics
   end
+
+  private
+
+  def with_capture_backend(backend)
+    if StatsD.legacy_singleton_client.backend.is_a?(StatsD::Instrument::Backends::CaptureBackend)
+      backend.parent = StatsD.legacy_singleton_client.backend
+    end
+
+    old_backend = StatsD.legacy_singleton_client.backend
+    begin
+      StatsD.legacy_singleton_client.backend = backend
+      yield
+    ensure
+      StatsD.legacy_singleton_client.backend = old_backend
+    end
+  end
 end