statsd-instrument 2.4.0 → 2.5.0

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

@@ -9,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
@@ -18,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/helpers.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
 
 module StatsD::Instrument::Helpers
-  def capture_statsd_calls(&block)
-    mock_backend = StatsD::Instrument::Backends::CaptureBackend.new
+  def with_capture_backend(backend, &block)
+    if StatsD.backend.is_a?(StatsD::Instrument::Backends::CaptureBackend)
+      backend.parent = StatsD.backend
+    end
+
     old_backend = StatsD.backend
-    StatsD.backend = mock_backend
+    StatsD.backend = backend
 
     block.call
-    mock_backend.collected_metrics
   ensure
-    if old_backend.is_a?(StatsD::Instrument::Backends::CaptureBackend)
-      old_backend.collected_metrics.concat(mock_backend.collected_metrics)
-    end
-
     StatsD.backend = old_backend
   end
+
+  def capture_statsd_calls(&block)
+    capture_backend = StatsD::Instrument::Backends::CaptureBackend.new
+    with_capture_backend(capture_backend, &block)
+    capture_backend.collected_metrics
+  end
 end

data/lib/statsd/instrument/metric.rb

@@ -31,50 +31,24 @@
 # @see StatsD::Instrument::Backend A StatsD::Instrument::Backend is used to collect metrics.
 #
 class StatsD::Instrument::Metric
-  attr_accessor :type, :name, :value, :sample_rate, :tags, :metadata
-
-  # Initializes a new metric instance.
-  # Normally, you don't want to call this method directly, but use one of the metric collection
-  # methods on the {StatsD} module.
-  #
-  # @option options [Symbol] :type The type of the metric.
-  # @option options [String] :name The name of the metric without prefix.
-  # @option options [String] :prefix Override the default StatsD prefix.
-  # @option options [Boolean] :no_prefix Set to <tt>true</tt> if you don't want to apply a prefix.
-  # @option options [Numeric, String, nil] :value The value to collect for the metric. If set to
-  #   <tt>nil>/tt>, {#default_value} will be used.
-  # @option options [Numeric, nil] :sample_rate The sample rate to use. If not set, it will use
-  #   {StatsD#default_sample_rate}.
-  # @option options [Array<String>, Hash<String, String>, nil] :tags The tags to apply to this metric.
-  #   See {.normalize_tags} for more information.
-  def initialize(options = {})
-    if options[:type]
-      @type = options[:type]
-    else
-      raise ArgumentError, "Metric :type is required."
-    end
-
-    if options[:name]
-      @name = normalize_name(options[:name])
-    else
-      raise ArgumentError, "Metric :name is required."
-    end
-
-    unless options[:no_prefix]
-      @name = if options[:prefix]
-        "#{options[:prefix]}.#{@name}"
-      else
-        StatsD.prefix ? "#{StatsD.prefix}.#{@name}" : @name
+  unless Regexp.method_defined?(:match?) # for ruby 2.3
+    module RubyBackports
+      refine Regexp do
+        def match?(str)
+          (self =~ str) != nil
+        end
       end
     end
 
-    @value = options[:value] || default_value
-    @sample_rate = options[:sample_rate] || StatsD.default_sample_rate
-    @tags = StatsD::Instrument::Metric.normalize_tags(options[:tags])
-    if StatsD.default_tags
-      @tags = Array(@tags) + StatsD.default_tags
-    end
-    @metadata = options.reject { |k, _| [:type, :name, :value, :sample_rate, :tags].include?(k) }
+    using RubyBackports
+  end
+
+  def self.new(
+    type:, name:, value: default_value(type), sample_rate: StatsD.default_sample_rate, tags: nil, metadata: nil
+  )
+    # pass keyword arguments as positional arguments for performance reasons,
+    # since MRI's C implementation of new turns keyword arguments into a hash
+    super(type, name, value, sample_rate, tags, metadata)
   end
 
   # The default value for this metric, which will be used if it is not set.
@@ -82,15 +56,48 @@ class StatsD::Instrument::Metric
   # A default value is only defined for counter metrics (<tt>1</tt>). For all other
   # metric types, this emthod will raise an <tt>ArgumentError</tt>.
   #
+  #
+  # A default value is only defined for counter metrics (<tt>1</tt>). For all other
+  # metric types, this emthod will raise an <tt>ArgumentError</tt>.
+  #
   # @return [Numeric, String] The default value for this metric.
   # @raise ArgumentError if the metric type doesn't have a default value
-  def default_value
+  def self.default_value(type)
     case type
     when :c then 1
     else raise ArgumentError, "A value is required for metric type #{type.inspect}."
     end
   end
 
+  attr_accessor :type, :name, :value, :sample_rate, :tags, :metadata
+
+  # Initializes a new metric instance.
+  # Normally, you don't want to call this method directly, but use one of the metric collection
+  # methods on the {StatsD} module.
+  #
+  # @param type [Symbol] The type of the metric.
+  # @option name [String] :name The name of the metric without prefix.
+  # @option value [Numeric, String, nil] The value to collect for the metric.
+  # @option sample_rate [Numeric, nil] The sample rate to use. If not set, it will use
+  #   {StatsD#default_sample_rate}.
+  # @option tags [Array<String>, Hash<String, String>, nil] :tags The tags to apply to this metric.
+  #   See {.normalize_tags} for more information.
+  def initialize(type, name, value, sample_rate, tags, metadata) # rubocop:disable Metrics/ParameterLists
+    raise ArgumentError, "Metric :type is required." unless type
+    raise ArgumentError, "Metric :name is required." unless name
+    raise ArgumentError, "Metric :value is required." unless value
+
+    @type = type
+    @name = normalize_name(name)
+    @value = value
+    @sample_rate = sample_rate
+    @tags = StatsD::Instrument::Metric.normalize_tags(tags)
+    if StatsD.default_tags
+      @tags = Array(@tags) + StatsD.default_tags
+    end
+    @metadata = metadata
+  end
+
   # @private
   # @return [String]
   def to_s
@@ -123,6 +130,9 @@ class StatsD::Instrument::Metric
   # @param name [String]
   # @return [String]
   def normalize_name(name)
+    # fast path when no normalization is needed to avoid copying the string
+    return name unless /[:|@]/.match?(name)
+
     name.tr(':|@', '_')
   end
 
@@ -136,6 +146,10 @@ class StatsD::Instrument::Metric
   def self.normalize_tags(tags)
     return unless tags
     tags = tags.map { |k, v| k.to_s + ":" + v.to_s } if tags.is_a?(Hash)
+
+    # fast path when no string replacement is needed
+    return tags unless tags.any? { |tag| /[|,]/.match?(tag) }
+
     tags.map { |tag| tag.tr('|,', '') }
   end
 end

data/lib/statsd/instrument/rubocop/metaprogramming_positional_arguments.rb

@@ -0,0 +1,46 @@
+# frozen-string-literal: true
+
+module RuboCop
+  module Cop
+    module StatsD
+      # This Rubocop will check for using the metaprogramming macros for positional
+      # argument usage, which is deprecated. These macros include `statd_count_if`,
+      # `statsd_measure`, etc.
+      #
+      # Use the following Rubocop invocation to check your project's codebase:
+      #
+      #     rubocop --only StatsD/MetaprogrammingPositionalArguments
+      #       -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metaprogramming_positional_arguments.rb
+      #
+      #
+      # This cop will not autocorrect the offenses it finds, but generally the fixes are easy to fix
+      class MetaprogrammingPositionalArguments < Cop
+        MSG = 'Use keyword arguments for StatsD metaprogramming macros'
+
+        METAPROGRAMMING_METHODS = %i{
+          statsd_measure
+          statsd_distribution
+          statsd_count_success
+          statsd_count_if
+          statsd_count
+        }
+
+        def on_send(node)
+          if METAPROGRAMMING_METHODS.include?(node.method_name)
+            arguments = node.arguments.dup
+            arguments.shift # method
+            arguments.shift # metric
+            arguments.pop if arguments.last&.type == :block_pass
+            case arguments.length
+            when 0
+            when 1
+              add_offense(node) if arguments.first.type != :hash
+            else
+              add_offense(node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/statsd/instrument/rubocop/metric_return_value.rb

@@ -0,0 +1,31 @@
+# frozen-string-literal: true
+
+module RuboCop
+  module Cop
+    module StatsD
+      # This Rubocop will check for using the return value of StatsD metric calls, which is deprecated.
+      # To check your codebase, use the following Rubocop invocation:
+      #
+      #     rubocop --require `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_return_value.rb \
+      #       --only StatsD/MetricReturnValue
+      #
+      # This cop cannot autocorrect offenses. In production code, StatsD should be used in a fire-and-forget
+      # fashion. This means that you shouldn't rely on the return value. If you really need to access the
+      # emitted metrics, you can look into `capture_statsd_calls`
+      class MetricReturnValue < Cop
+        MSG = 'Do not use the return value of StatsD metric methods'
+
+        STATSD_METRIC_METHODS = %i{increment gauge measure set histogram distribution key_value}
+        INVALID_PARENTS = %i{lvasgn array pair send return yield}
+
+        def on_send(node)
+          if node.receiver&.type == :const && node.receiver&.const_name == "StatsD"
+            if STATSD_METRIC_METHODS.include?(node.method_name) && node.arguments.last&.type != :block_pass
+              add_offense(node.parent) if INVALID_PARENTS.include?(node.parent&.type)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/statsd/instrument/rubocop/metric_value_keyword_argument.rb

@@ -0,0 +1,45 @@
+# frozen-string-literal: true
+
+module RuboCop
+  module Cop
+    module StatsD
+      # This Rubocop will check for providing the value for a metric using a keyword argument, which is
+      # deprecated. Use the following Rubocop invocation to check your project's codebase:
+      #
+      #    rubocop --require \
+      #      `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_value_keyword_argument.rb \
+      #      --only StatsD/MetricValueKeywordArgument
+      #
+      # This cop will not autocorrect offenses. Most of the time, these are easy to fix by providing the
+      # value as the second argument, rather than a keyword argument.
+      #
+      # `StatsD.increment('foo', value: 3)` => `StatsD.increment('foo', 3)`
+      class MetricValueKeywordArgument < Cop
+        MSG = 'Do not use the value keyword argument, but use a positional argument'
+
+        STATSD_METRIC_METHODS = %i{increment gauge measure set histogram distribution key_value}
+
+        def on_send(node)
+          if node.receiver&.type == :const && node.receiver&.const_name == "StatsD"
+            if STATSD_METRIC_METHODS.include?(node.method_name)
+              last_argument = if node.arguments.last&.type == :block_pass
+                node.arguments[node.arguments.length - 2]
+              else
+                node.arguments[node.arguments.length - 1]
+              end
+
+              check_keyword_arguments_for_value_entry(node, last_argument) if last_argument&.type == :hash
+            end
+          end
+        end
+
+        def check_keyword_arguments_for_value_entry(node, keyword_arguments)
+          value_pair_found = keyword_arguments.child_nodes.any? do |pair|
+            pair.child_nodes[0].type == :sym && pair.child_nodes[0].value == :value
+          end
+          add_offense(node) if value_pair_found
+        end
+      end
+    end
+  end
+end

data/lib/statsd/instrument/rubocop/positional_arguments.rb

@@ -0,0 +1,99 @@
+# frozen-string-literal: true
+
+module RuboCop
+  module Cop
+    module StatsD
+      # This Rubocop will check for using the StatsD metric methods (e.g. `StatsD.instrument`)
+      # for positional argument usage, which is deprecated.
+      #
+      # Use the following Rubocop invocation to check your project's codebase:
+      #
+      #     rubocop --require `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/positional_arguments.rb \
+      #       --only StatsD/PositionalArguments
+      #
+      # This cop can autocorrect some offenses it finds, but not all of them.
+      class PositionalArguments < Cop
+        MSG = 'Use keyword arguments for StatsD calls'
+
+        STATSD_SINGLETON_METHODS = %i{increment gauge measure set histogram distribution key_value}
+
+        POSITIONAL_ARGUMENT_TYPES = Set[:int, :float, :nil]
+        UNKNOWN_ARGUMENT_TYPES = Set[:send, :const, :lvar, :splat]
+        REFUSED_ARGUMENT_TYPES = POSITIONAL_ARGUMENT_TYPES | UNKNOWN_ARGUMENT_TYPES
+
+        KEYWORD_ARGUMENT_TYPES = Set[:hash]
+        BLOCK_ARGUMENT_TYPES = Set[:block_pass]
+        ACCEPTED_ARGUMENT_TYPES = KEYWORD_ARGUMENT_TYPES | BLOCK_ARGUMENT_TYPES
+
+        def on_send(node)
+          if node.receiver&.type == :const && node.receiver&.const_name == "StatsD"
+            if STATSD_SINGLETON_METHODS.include?(node.method_name) && node.arguments.length >= 3
+              case node.arguments[2].type
+              when *REFUSED_ARGUMENT_TYPES
+                add_offense(node)
+              when *ACCEPTED_ARGUMENT_TYPES
+                nil
+              else
+                $stderr.puts "[StatsD/PositionalArguments] Unhandled argument type: #{node.arguments[2].type.inspect}"
+              end
+            end
+          end
+        end
+
+        def autocorrect(node)
+          -> (corrector) do
+            positial_arguments = if node.arguments.last.type == :block_pass
+              node.arguments[2...node.arguments.length - 1]
+            else
+              node.arguments[2...node.arguments.length]
+            end
+
+            case positial_arguments[0].type
+            when *UNKNOWN_ARGUMENT_TYPES
+              # We don't know whether the method returns a hash, in which case it would be interpreted
+              # as keyword arguments. In this case, the fix would be to add a keywordf splat:
+              #
+              # `StatsD.instrument('foo', 1, method_call)`
+              # => `StatsD.instrument('foo', 1, **method_call)`
+              #
+              # However, it's also possible this method returns a sample rate, in which case the fix
+              # above will not do the right thing.
+              #
+              # `StatsD.instrument('foo', 1, SAMPLE_RATE_CONSTANT)`
+              # => `StatsD.instrument('foo', 1, sample_rate: SAMPLE_RATE_CONSTANT)`
+              #
+              # Because of this, we will not auto-correct and let the user fix the issue manually.
+              return
+
+            when *POSITIONAL_ARGUMENT_TYPES
+              value_argument = node.arguments[1]
+              from = value_argument.source_range.end_pos
+              to = positial_arguments.last.source_range.end_pos
+              range = Parser::Source::Range.new(node.source_range.source_buffer, from, to)
+              corrector.remove(range)
+
+              keyword_arguments = []
+              sample_rate = positial_arguments[0]
+              if sample_rate && sample_rate.type != :nil
+                keyword_arguments << "sample_rate: #{sample_rate.source}"
+              end
+
+              tags = positial_arguments[1]
+              if tags && tags.type != :nil
+                keyword_arguments << if tags.type == :hash && tags.source[0] != '{'
+                  "tags: { #{tags.source} }"
+                else
+                  "tags: #{tags.source}"
+                end
+              end
+
+              unless keyword_arguments.empty?
+                corrector.insert_after(value_argument.source_range, ", #{keyword_arguments.join(', ')}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/statsd/instrument/rubocop/splat_arguments.rb

@@ -0,0 +1,37 @@
+# frozen-string-literal: true
+
+module RuboCop
+  module Cop
+    module StatsD
+      # This Rubocop will check for using splat arguments (*args) in StatsD metric calls. To run
+      # this rule on your codebase, invoke Rubocop this way:
+      #
+      #    rubocop --require \
+      #      `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/splat_arguments.rb \
+      #      --only StatsD/SplatArguments
+      #
+      # This cop will not autocorrect offenses.
+      class SplatArguments < Cop
+        MSG = 'Do not use splat arguments in StatsD metric calls'
+
+        STATSD_METRIC_METHODS = %i{increment gauge measure set histogram distribution key_value}
+
+        def on_send(node)
+          if node.receiver&.type == :const && node.receiver&.const_name == "StatsD"
+            if STATSD_METRIC_METHODS.include?(node.method_name)
+              check_for_splat_arguments(node)
+            end
+          end
+        end
+
+        private
+
+        def check_for_splat_arguments(node)
+          if node.arguments.any? { |arg| arg.type == :splat }
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end