statsd-instrument 2.3.2 → 2.6.0

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

@@ -0,0 +1,37 @@
+# frozen-string-literal: true
+
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
+module RuboCop
+  module Cop
+    module StatsD
+      # This Rubocop will check for specifying the `prefix` keyword argument on `StatsD` metric
+      # methods and `statsd_*` metaprogramming methods. To run this cop on your codebase:
+      #
+      #     rubocop --require `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb \
+      #       --only StatsD/MetricPrefixArgument
+      #
+      # This cop will not autocorrect offenses.
+      class MetricPrefixArgument < Cop
+        include RuboCop::Cop::StatsD
+
+        MSG = <<~MSG
+          Do not use StatsD.metric(..., prefix: "foo"). The prefix argument is deprecated.
+
+          You can simply include the prefix in the metric name instead.
+          If you want to override the global prefix, you can set `no_prefix: true`.
+        MSG
+
+        def on_send(node)
+          if metric_method?(node)
+            add_offense(node) if has_keyword_argument?(node, :prefix)
+          end
+
+          if metaprogramming_method?(node)
+            add_offense(node) if has_keyword_argument?(node, :prefix)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen-string-literal: true
+
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
+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.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
+        include RuboCop::Cop::StatsD
+
+        MSG = 'Do not use the return value of StatsD metric methods'
+
+        INVALID_PARENTS = %i{lvasgn array pair send return yield}
+
+        def on_send(node)
+          if metric_method?(node) && node.arguments.last&.type != :block_pass
+            add_offense(node.parent) if INVALID_PARENTS.include?(node.parent&.type)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen-string-literal: true
+
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
+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.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
+        include RuboCop::Cop::StatsD
+
+        MSG = <<~MSG
+          Do not use the StatsD.metric('name', value: <value>, ...). The `value` keyword argument is deprecated.
+
+          Use a positional argument instead: StatsD.metric('name', <value>, ...).
+        MSG
+
+        def on_send(node)
+          if metric_method?(node) && has_keyword_argument?(node, :value)
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen-string-literal: true
+
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
+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.rb \
+      #       --only StatsD/PositionalArguments
+      #
+      # This cop can autocorrect some offenses it finds, but not all of them.
+      class PositionalArguments < Cop
+        include RuboCop::Cop::StatsD
+
+        MSG = 'Use keyword arguments for StatsD calls'
+
+        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 metric_method?(node) && 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
+
+        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,31 @@
+# frozen-string-literal: true
+
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
+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.rb \
+      #      --only StatsD/SplatArguments
+      #
+      # This cop will not autocorrect offenses.
+      class SplatArguments < Cop
+        include RuboCop::Cop::StatsD
+
+        MSG = 'Do not use splat arguments in StatsD metric calls'
+
+        def on_send(node)
+          if metric_method?(node)
+            if node.arguments.any? { |arg| arg.type == :splat }
+              add_offense(node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/statsd/instrument/rubocop.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module StatsD
+      METRIC_METHODS = %i{
+        increment
+        gauge
+        measure
+        set
+        histogram
+        distribution
+        key_value
+      }
+
+      METAPROGRAMMING_METHODS = %i{
+        statsd_measure
+        statsd_distribution
+        statsd_count_success
+        statsd_count_if
+        statsd_count
+      }
+
+      private
+
+      def metaprogramming_method?(node)
+        METAPROGRAMMING_METHODS.include?(node.method_name)
+      end
+
+      def metric_method?(node)
+        node.receiver&.type == :const &&
+          node.receiver&.const_name == "StatsD" &&
+          METRIC_METHODS.include?(node.method_name)
+      end
+
+      def has_keyword_argument?(node, sym)
+        if (kwargs = keyword_arguments(node))
+          kwargs.child_nodes.detect do |pair|
+            pair.child_nodes[0]&.type == :sym && pair.child_nodes[0].value == sym
+          end
+        end
+      end
+
+      def keyword_arguments(node)
+        return nil if node.arguments.empty?
+        last_argument = if node.arguments.last&.type == :block_pass
+          node.arguments[node.arguments.length - 2]
+        else
+          node.arguments[node.arguments.length - 1]
+        end
+
+        last_argument&.type == :hash ? last_argument : nil
+      end
+    end
+  end
+end
+
+require_relative 'rubocop/metaprogramming_positional_arguments'
+require_relative 'rubocop/metric_return_value'
+require_relative 'rubocop/metric_value_keyword_argument'
+require_relative 'rubocop/positional_arguments'
+require_relative 'rubocop/splat_arguments'
+require_relative 'rubocop/measure_as_dist_argument'
+require_relative 'rubocop/metric_prefix_argument'

data/lib/statsd/instrument/statsd_datagram_builder.rb

@@ -0,0 +1,14 @@
+# 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::StatsDDatagramBuilder < StatsD::Instrument::DatagramBuilder
+  unsupported_datagram_types :h, :d, :kv
+
+  protected
+
+  def normalize_tags(tags)
+    raise NotImplementedError, "#{self.class.name} does not support tags" if tags
+    super
+  end
+end

data/lib/statsd/instrument/strict.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'statsd-instrument' unless Object.const_defined?(:StatsD)
+
+module StatsD
+  module Instrument
+    UNSPECIFIED = Object.new.freeze
+    private_constant :UNSPECIFIED
+
+    # The Strict monkeypatch can be loaded to see if you're using the StatsD library in
+    # a deprecated way.
+    #
+    # - The metric methods are not retuning a Metric instance.
+    # - Only accept keyword arguments for tags and sample_rate, rather than position arguments.
+    # - Only accept a position argument for value, rather than a keyword argument.
+    # - The provided arguments have the right type.
+    #
+    # You can enable thois monkeypatch by changing your Gemfile as follows:
+    #
+    #     gem 'statsd-instrument', require: 'statsd/instrument/strict'
+    #
+    # By doing this as part of your QA/CI, you can find where you are still using deprecated patterns,
+    # and fix them before the deprecated behavior is removed in the next major version.
+    #
+    # This monkeypatch is not meant to be used in production.
+    module Strict
+      def increment(key, value = 1, sample_rate: nil, tags: nil, no_prefix: false)
+        raise ArgumentError, "StatsD.increment does not accept a block" if block_given?
+        raise ArgumentError, "The value argument should be an integer, got #{value.inspect}" unless value.is_a?(Integer)
+        check_tags_and_sample_rate(sample_rate, tags)
+
+        super
+      end
+
+      def gauge(key, value, sample_rate: nil, tags: nil, no_prefix: false)
+        raise ArgumentError, "StatsD.increment does not accept a block" if block_given?
+        raise ArgumentError, "The value argument should be an integer, got #{value.inspect}" unless value.is_a?(Numeric)
+        check_tags_and_sample_rate(sample_rate, tags)
+
+        super
+      end
+
+      def histogram(key, value, sample_rate: nil, tags: nil, no_prefix: false)
+        raise ArgumentError, "StatsD.increment does not accept a block" if block_given?
+        raise ArgumentError, "The value argument should be an integer, got #{value.inspect}" unless value.is_a?(Numeric)
+        check_tags_and_sample_rate(sample_rate, tags)
+
+        super
+      end
+
+      def set(key, value, sample_rate: nil, tags: nil, no_prefix: false)
+        raise ArgumentError, "StatsD.set does not accept a block" if block_given?
+        check_tags_and_sample_rate(sample_rate, tags)
+
+        super
+      end
+
+      def service_check(name, status, tags: nil, no_prefix: false,
+        hostname: nil, timestamp: nil, message: nil)
+
+        super
+      end
+
+      def event(title, text, tags: nil, no_prefix: false,
+        hostname: nil, timestamp: nil, aggregation_key: nil, priority: nil, source_type_name: nil, alert_type: nil)
+
+        super
+      end
+
+      def measure(key, value = UNSPECIFIED, sample_rate: nil, tags: nil, no_prefix: false, &block)
+        check_block_or_numeric_value(value, &block)
+        check_tags_and_sample_rate(sample_rate, tags)
+
+        super
+      end
+
+      def distribution(key, value = UNSPECIFIED, sample_rate: nil, tags: nil, no_prefix: false, &block)
+        check_block_or_numeric_value(value, &block)
+        check_tags_and_sample_rate(sample_rate, tags)
+
+        super
+      end
+
+      private
+
+      def check_block_or_numeric_value(value)
+        if block_given?
+          raise ArgumentError, "The value argument should not be set when providing a block" unless value == UNSPECIFIED
+        else
+          raise ArgumentError, "The value argument should be a number, got #{value.inspect}" unless value.is_a?(Numeric)
+        end
+      end
+
+      def check_tags_and_sample_rate(sample_rate, tags)
+        unless sample_rate.nil? || sample_rate.is_a?(Numeric)
+          raise ArgumentError, "The sample_rate argument should be a number, got #{sample_rate}"
+        end
+        unless tags.nil? || tags.is_a?(Hash) || tags.is_a?(Array)
+          raise ArgumentError, "The tags argument should be a hash or an array, got #{tags.inspect}"
+        end
+      end
+
+      def collect_metric(type, name, value, sample_rate:, tags: nil, prefix:, metadata: nil)
+        super
+        nil # We explicitly discard the return value, so people cannot depend on it.
+      end
+    end
+
+    module StrictMetaprogramming
+      def statsd_measure(method, name, sample_rate: nil, tags: nil, no_prefix: false)
+        check_method_and_metric_name(method, name)
+
+        # Unfortunately, we have to inline the new method implementation ebcause we have to fix the
+        # Stats.measure call to not use the `as_dist` and `prefix` arguments.
+        add_to_method(method, name, :measure) do
+          define_method(method) do |*args, &block|
+            key = StatsD::Instrument.generate_metric_name(name, self, *args)
+            StatsD.measure(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) do
+              super(*args, &block)
+            end
+          end
+        end
+      end
+
+      def statsd_distribution(method, name, sample_rate: nil, tags: nil, no_prefix: false)
+        check_method_and_metric_name(method, name)
+
+        # Unfortunately, we have to inline the new method implementation ebcause we have to fix the
+        # Stats.distribution call to not use the `prefix` argument.
+
+        add_to_method(method, name, :distribution) do
+          define_method(method) do |*args, &block|
+            key = StatsD::Instrument.generate_metric_name(name, self, *args)
+            StatsD.distribution(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) do
+              super(*args, &block)
+            end
+          end
+        end
+      end
+
+      def statsd_count_success(method, name, sample_rate: nil, tags: nil, no_prefix: false)
+        check_method_and_metric_name(method, name)
+
+        # Unfortunately, we have to inline the new method implementation ebcause we have to fix the
+        # Stats.increment call to not use the `prefix` argument.
+
+        add_to_method(method, name, :count_success) do
+          define_method(method) do |*args, &block|
+            begin
+              truthiness = result = super(*args, &block)
+            rescue
+              truthiness = false
+              raise
+            else
+              if block_given?
+                begin
+                  truthiness = yield(result)
+                rescue
+                  truthiness = false
+                end
+              end
+              result
+            ensure
+              suffix = truthiness == false ? 'failure' : 'success'
+              key = "#{StatsD::Instrument.generate_metric_name(name, self, *args)}.#{suffix}"
+              StatsD.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
+            end
+          end
+        end
+      end
+
+      def statsd_count_if(method, name, sample_rate: nil, tags: nil, no_prefix: false)
+        check_method_and_metric_name(method, name)
+
+        # Unfortunately, we have to inline the new method implementation ebcause we have to fix the
+        # Stats.increment call to not use the `prefix` argument.
+
+        add_to_method(method, name, :count_if) do
+          define_method(method) do |*args, &block|
+            begin
+              truthiness = result = super(*args, &block)
+            rescue
+              truthiness = false
+              raise
+            else
+              if block_given?
+                begin
+                  truthiness = yield(result)
+                rescue
+                  truthiness = false
+                end
+              end
+              result
+            ensure
+              if truthiness
+                key = StatsD::Instrument.generate_metric_name(name, self, *args)
+                StatsD.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
+              end
+            end
+          end
+        end
+      end
+
+      def statsd_count(method, name, sample_rate: nil, tags: nil, no_prefix: false)
+        check_method_and_metric_name(method, name)
+
+        # Unfortunately, we have to inline the new method implementation ebcause we have to fix the
+        # Stats.increment call to not use the `prefix` argument.
+
+        add_to_method(method, name, :count) do
+          define_method(method) do |*args, &block|
+            key = StatsD::Instrument.generate_metric_name(name, self, *args)
+            StatsD.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
+            super(*args, &block)
+          end
+        end
+      end
+
+      private
+
+      def check_method_and_metric_name(method, metric_name)
+        unless method.is_a?(Symbol)
+          raise ArgumentError, "The method name should be provided as symbol, got #{method.inspect}"
+        end
+
+        unless metric_name.is_a?(String) || metric_name.is_a?(Proc)
+          raise ArgumentError, "The metric name should be a proc or string, got #{metric_name.inspect}"
+        end
+      end
+    end
+  end
+end
+
+StatsD.singleton_class.prepend(StatsD::Instrument::Strict)
+StatsD::Instrument.prepend(StatsD::Instrument::StrictMetaprogramming)

data/lib/statsd/instrument/udp_sink.rb

@@ -0,0 +1,62 @@
+# 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::UDPSink
+  def self.for_addr(addr)
+    host, port_as_string = addr.split(':', 2)
+    new(host, Integer(port_as_string))
+  end
+
+  attr_reader :host, :port
+
+  def initialize(host, port)
+    @host = host
+    @port = port
+    @mutex = Mutex.new
+    @socket = nil
+  end
+
+  def sample?(sample_rate)
+    sample_rate == 1 || rand < sample_rate
+  end
+
+  def <<(datagram)
+    with_socket { |socket| socket.send(datagram, 0) > 0 }
+    self
+
+  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 datagram without a lock.
+    socket.send(datagram, 0) > 0
+
+  rescue SocketError, IOError, SystemCallError
+    # TODO: log?
+    invalidate_socket
+  end
+
+  def addr
+    "#{host}:#{port}"
+  end
+
+  private
+
+  def with_socket
+    @mutex.synchronize { yield(socket) }
+  end
+
+  def socket
+    if @socket.nil?
+      @socket = UDPSocket.new
+      @socket.connect(@host, @port)
+    end
+    @socket
+  end
+
+  def invalidate_socket
+    @mutex.synchronize do
+      @socket = nil
+    end
+  end
+end

data/lib/statsd/instrument/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module StatsD
   module Instrument
-    VERSION = "2.3.2"
+    VERSION = "2.6.0"
   end
 end