statsd-instrument 2.4.0 → 2.5.0

data/lib/statsd/instrument.rb

@@ -62,26 +62,26 @@ module StatsD
       metric_name.respond_to?(:call) ? metric_name.call(callee, args).gsub('::', '.') : metric_name.gsub('::', '.')
     end
 
-    if Process.respond_to?(:clock_gettime)
-      # @private
-      def self.current_timestamp
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-    else
-      # @private
-      def self.current_timestamp
-        Time.now
-      end
+    # Even though this method is considered private, and is no longer used internally,
+    # applications in the wild rely on it. As a result, we cannot remove this method
+    # until the next major version.
+    #
+    # @deprecated Use Process.clock_gettime(Process::CLOCK_MONOTONIC) instead.
+    def self.current_timestamp
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     # Even though this method is considered private, and is no longer used internally,
     # applications in the wild rely on it. As a result, we cannot remove this method
     # until the next major version.
-    # @private
+    #
+    # @deprecated You can implement similar functionality yourself using
+    #   `Process.clock_gettime(Process::CLOCK_MONOTONIC)`. Think about what will
+    #   happen if an exception happens during the block execution though.
     def self.duration
-      start = current_timestamp
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       yield
-      current_timestamp - start
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
     end
 
     # Adds execution duration instrumentation to a method as a timing.
@@ -91,11 +91,17 @@ module StatsD
     #    callable to dynamically generate a metric name
     # @param metric_options (see StatsD#measure)
     # @return [void]
-    def statsd_measure(method, name, *metric_options)
+    def statsd_measure(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil, as_dist: false,
+      sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: StatsD.prefix, no_prefix: false)
+
       add_to_method(method, name, :measure) do
         define_method(method) do |*args, &block|
-          metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
-          StatsD.measure(metric_name, *metric_options) { super(*args, &block) }
+          key = StatsD::Instrument.generate_metric_name(name, self, *args)
+          StatsD.measure(
+            key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix, as_dist: as_dist
+          ) do
+            super(*args, &block)
+          end
         end
       end
     end
@@ -108,11 +114,15 @@ module StatsD
     # @param metric_options (see StatsD#measure)
     # @return [void]
     # @note Supported by the datadog implementation only (in beta)
-    def statsd_distribution(method, name, *metric_options)
+    def statsd_distribution(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+      sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: StatsD.prefix, no_prefix: false)
+
       add_to_method(method, name, :distribution) do
         define_method(method) do |*args, &block|
-          metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
-          StatsD.distribution(metric_name, *metric_options) { super(*args, &block) }
+          key = StatsD::Instrument.generate_metric_name(name, self, *args)
+          StatsD.distribution(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix) do
+            super(*args, &block)
+          end
         end
       end
     end
@@ -132,7 +142,9 @@ module StatsD
     # @yieldreturn [Boolean] Return true iff the return value is consisered a success, false otherwise.
     # @return [void]
     # @see #statsd_count_if
-    def statsd_count_success(method, name, *metric_options)
+    def statsd_count_success(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+      sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: StatsD.prefix, no_prefix: false)
+
       add_to_method(method, name, :count_success) do
         define_method(method) do |*args, &block|
           begin
@@ -151,8 +163,8 @@ module StatsD
             result
           ensure
             suffix = truthiness == false ? 'failure' : 'success'
-            metric_name = "#{StatsD::Instrument.generate_metric_name(name, self, *args)}.#{suffix}"
-            StatsD.increment(metric_name, 1, *metric_options)
+            key = "#{StatsD::Instrument.generate_metric_name(name, self, *args)}.#{suffix}"
+            StatsD.increment(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix)
           end
         end
       end
@@ -165,13 +177,14 @@ module StatsD
     #
     # @param method (see #statsd_measure)
     # @param name (see #statsd_measure)
-    # @param metric_options (see #statsd_measure)
     # @yield (see #statsd_count_success)
     # @yieldparam result (see #statsd_count_success)
     # @yieldreturn (see #statsd_count_success)
     # @return [void]
     # @see #statsd_count_success
-    def statsd_count_if(method, name, *metric_options)
+    def statsd_count_if(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+      sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: StatsD.prefix, no_prefix: false)
+
       add_to_method(method, name, :count_if) do
         define_method(method) do |*args, &block|
           begin
@@ -190,8 +203,8 @@ module StatsD
             result
           ensure
             if truthiness
-              metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
-              StatsD.increment(metric_name, *metric_options)
+              key = StatsD::Instrument.generate_metric_name(name, self, *args)
+              StatsD.increment(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix)
             end
           end
         end
@@ -207,11 +220,13 @@ module StatsD
     # @param name (see #statsd_measure)
     # @param metric_options (see #statsd_measure)
     # @return [void]
-    def statsd_count(method, name, *metric_options)
+    def statsd_count(method, name, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+      sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg, prefix: StatsD.prefix, no_prefix: false)
+
       add_to_method(method, name, :count) do
         define_method(method) do |*args, &block|
-          metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
-          StatsD.increment(metric_name, 1, *metric_options)
+          key = StatsD::Instrument.generate_metric_name(name, self, *args)
+          StatsD.increment(key, sample_rate: sample_rate, tags: tags, prefix: prefix, no_prefix: no_prefix)
           super(*args, &block)
         end
       end
@@ -346,19 +361,25 @@ module StatsD
   #      http_response = StatsD.measure('HTTP.call.duration') do
   #        HTTP.get(url)
   #      end
-  def measure(key, value = nil, *metric_options, &block)
-    value, metric_options = parse_options(value, metric_options)
-    type = (!metric_options.empty? && metric_options.first[:as_dist] ? :d : :ms)
-
-    return collect_metric(type, key, value, metric_options) unless block_given?
+  def measure(
+    key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false, as_dist: false,
+    &block
+  )
+    prefix = nil if no_prefix
+    type = as_dist ? :d : :ms
+    unless block_given?
+      return collect_metric(type, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix, &block)
+    end
 
-    start = StatsD::Instrument.current_timestamp
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     begin
       block.call
     ensure
       # Ensure catches both a raised exception and a return in the invoked block
-      value = 1000 * (StatsD::Instrument.current_timestamp - start)
-      collect_metric(type, key, value, metric_options)
+      value = 1000.0 * (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start)
+      collect_metric(type, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
     end
   end
 
@@ -372,9 +393,14 @@ module StatsD
   #   should know how to handle it.
   #
   # @param metric_options [Hash] (default: {}) Metric options
-  # @return (see #collect_metric)
-  def increment(key, value = 1, *metric_options)
-    collect_metric(:c, key, value, metric_options)
+  # @return [void]
+  def increment(
+    key, value_arg = 1, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false
+  )
+    prefix = nil if no_prefix
+    collect_metric(:c, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
   end
 
   # Emits a gauge metric.
@@ -382,8 +408,13 @@ module StatsD
   # @param value [Numeric] The current value to record.
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
-  def gauge(key, value, *metric_options)
-    collect_metric(:g, key, value, metric_options)
+  def gauge(
+    key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false
+  )
+    prefix = nil if no_prefix
+    collect_metric(:g, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
   end
 
   # Emits a histogram metric.
@@ -392,8 +423,13 @@ module StatsD
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
-  def histogram(key, value, *metric_options)
-    collect_metric(:h, key, value, metric_options)
+  def histogram(
+    key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false
+  )
+    prefix = nil if no_prefix
+    collect_metric(:h, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
   end
 
   # Emits a distribution metric.
@@ -416,18 +452,14 @@ module StatsD
   #      http_response = StatsD.distribution('HTTP.call.duration') do
   #        HTTP.get(url)
   #      end
-  def distribution(key, value = nil, *metric_options, &block)
-    value, metric_options = parse_options(value, metric_options)
-
-    return collect_metric(:d, key, value, metric_options) unless block_given?
-
-    start = StatsD::Instrument.current_timestamp
-    begin
-      block.call
-    ensure
-      value = 1000 * (StatsD::Instrument.current_timestamp - start)
-      collect_metric(:d, key, value, metric_options)
-    end
+  def distribution(
+    key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false,
+    &block
+  )
+    prefix = nil if no_prefix
+    measure(key, value, as_dist: true, sample_rate: sample_rate, tags: tags, prefix: prefix, &block)
   end
 
   # Emits a key/value metric.
@@ -436,8 +468,12 @@ module StatsD
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the statsite implementation only.
-  def key_value(key, value, *metric_options)
-    collect_metric(:kv, key, value, metric_options)
+  def key_value(
+    key, value_arg = nil, deprecated_sample_rate_arg = nil,
+    value: value_arg, sample_rate: deprecated_sample_rate_arg, no_prefix: false
+  )
+    prefix = nil if no_prefix
+    collect_metric(:kv, key, value, sample_rate: sample_rate, prefix: prefix)
   end
 
   # Emits a set metric.
@@ -446,8 +482,13 @@ module StatsD
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
-  def set(key, value, *metric_options)
-    collect_metric(:s, key, value, metric_options)
+  def set(
+    key, value_arg = nil, deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    value: value_arg, sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false
+  )
+    prefix = nil if no_prefix
+    collect_metric(:s, key, value, sample_rate: sample_rate, tags: tags, prefix: prefix)
   end
 
   # Emits an event metric.
@@ -456,8 +497,14 @@ module StatsD
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
-  def event(title, text, *metric_options)
-    collect_metric(:_e, title, text, metric_options)
+  def event(
+    title, text,
+    deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false, **metadata
+  )
+    prefix = nil if no_prefix
+    collect_metric(:_e, title, text, sample_rate: sample_rate, tags: tags, prefix: prefix, metadata: metadata)
   end
 
   # Emits a service check metric.
@@ -466,44 +513,29 @@ module StatsD
   # @param metric_options [Hash] (default: {}) Metric options
   # @return (see #collect_metric)
   # @note Supported by the datadog implementation only.
-  def service_check(name, status, *metric_options)
-    collect_metric(:_sc, name, status, metric_options)
+  def service_check(
+    name, status,
+    deprecated_sample_rate_arg = nil, deprecated_tags_arg = nil,
+    sample_rate: deprecated_sample_rate_arg, tags: deprecated_tags_arg,
+    prefix: StatsD.prefix, no_prefix: false, **metadata
+  )
+    prefix = nil if no_prefix
+    collect_metric(:_sc, name, status, sample_rate: sample_rate, tags: tags, prefix: prefix, metadata: metadata)
   end
 
   private
 
-  # Converts old-style ordered arguments in an argument hash for backwards compatibility.
-  # @param args [Array] The list of non-required arguments.
-  # @return [Hash] The hash of optional arguments.
-  def hash_argument(args)
-    return {} if args.empty?
-    return args.first if args.length == 1 && args.first.is_a?(Hash)
-
-    order = [:sample_rate, :tags]
-    hash = {}
-    args.each_with_index do |value, index|
-      hash[order[index]] = value
-    end
-    hash
-  end
-
-  def parse_options(value, metric_options)
-    if value.is_a?(Hash) && metric_options.empty?
-      metric_options = [value]
-      value = value.fetch(:value, nil)
-    end
-    [value, metric_options]
-  end
-
   # Instantiates a metric, and sends it to the backend for further processing.
   # @param options (see StatsD::Instrument::Metric#initialize)
-  # @return [StatsD::Instrument::Metric] The metric that was sent to the backend.
-  def collect_metric(type, name, value, metric_options)
-    value, metric_options = parse_options(value, metric_options)
-
-    options = hash_argument(metric_options).merge(type: type, name: name, value: value)
-    backend.collect_metric(metric = StatsD::Instrument::Metric.new(options))
-    metric
+  # @return [void]
+  def collect_metric(type, name, value, sample_rate:, tags: nil, prefix:, metadata: nil)
+    sample_rate ||= default_sample_rate
+    name = "#{prefix}.#{name}" if prefix
+
+    metric = StatsD::Instrument::Metric.new(type: type, name: name, value: value,
+      sample_rate: sample_rate, tags: tags, metadata: metadata)
+    backend.collect_metric(metric)
+    metric # TODO: return `nil` in the next major version
   end
 end
 

data/lib/statsd/instrument/assertions.rb

@@ -39,51 +39,83 @@ module StatsD::Instrument::Assertions
 
   # @private
   def assert_statsd_calls(expected_metrics, &block)
-    unless block
-      raise ArgumentError, "block must be given"
-    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 }
-      refute(filtered_metrics.empty?,
-        "No StatsD calls for metric #{expected_metric.name} of type #{expected_metric.type} were made.")
-
-      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"
-
-        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
+    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
+      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
+
+          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_with_exception_info(exception_occurred, "Unexpected StatsD call; number of times this metric " \
+                "was expected exceeded: #{expected_metric.inspect}")
+            end
+
+            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_with_exception_info(exception_occurred, msg)
         end
-      end
+        expected_metrics -= matched_expected_metrics
 
-      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?
+        unless expected_metrics.empty?
+          flunk_with_exception_info(exception_occurred, "Unexpected StatsD calls; the following metric expectations " \
+            "were not satisfied: #{expected_metrics.inspect}")
+        end
 
-      assert(expected_metric_times_remaining == 0, msg)
+        pass
+      end
     end
-    expected_metrics -= matched_expected_metrics
-
-    assert(expected_metrics.empty?,
-      "Unexpected StatsD calls; the following metric expectations were not satisfied: #{expected_metrics.inspect}")
   end
 
   private
 
+  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)
+    end
+  end
+
   def assert_statsd_call(metric_type, metric_name, options = {}, &block)
     options[:name] = metric_name
     options[:type] = metric_type