statsd-instrument 2.5.1 → 2.6.0

data/lib/statsd/instrument/environment.rb

@@ -4,24 +4,62 @@ 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.
-module StatsD::Instrument::Environment
-  extend self
+class StatsD::Instrument::Environment
+  class << self
+    def from_env
+      @from_env ||= StatsD::Instrument::Environment.new(ENV)
+    end
 
-  # Instantiates a default backend for the current environment.
-  #
-  # @return [StatsD::Instrument::Backend]
-  # @see #environment
-  def default_backend
-    case environment
-    when 'production', 'staging'
-      StatsD::Instrument::Backends::UDPBackend.new(ENV['STATSD_ADDR'], ENV['STATSD_IMPLEMENTATION'])
-    when 'test'
-      StatsD::Instrument::Backends::NullBackend.new
-    else
-      StatsD::Instrument::Backends::LoggerBackend.new(StatsD.logger)
+    # Detects the current environment, either by asking Rails, or by inspecting environment variables.
+    #
+    # - Within a Rails application, <tt>Rails.env</tt> is used.
+    # - It will check the following environment variables in order: <tt>RAILS_ENV</tt>, <tt>RACK_ENV</tt>, <tt>ENV</tt>.
+    # - If none of these are set, it will return <tt>development</tt>
+    #
+    # @return [String] The detected environment.
+    def environment
+      from_env.environment
+    end
+
+    # Instantiates a default backend for the current environment.
+    #
+    # @return [StatsD::Instrument::Backend]
+    # @see #environment
+    def default_backend
+      case environment
+      when 'production', 'staging'
+        StatsD::Instrument::Backends::UDPBackend.new(from_env.statsd_addr, from_env.statsd_implementation)
+      when 'test'
+        StatsD::Instrument::Backends::NullBackend.new
+      else
+        StatsD::Instrument::Backends::LoggerBackend.new(StatsD.logger)
+      end
+    end
+
+    # Sets default values for sample rate and logger.
+    #
+    # - Default sample rate is set to the value in the STATSD_SAMPLE_RATE environment variable,
+    #   or 1.0 otherwise. See {StatsD#default_sample_rate}
+    # - {StatsD#logger} is set to a logger that send output to stderr.
+    #
+    # If you are including this library inside a Rails environment, additional initialization will
+    # be done as part of the {StatsD::Instrument::Railtie}.
+    #
+    # @return [void]
+    def setup
+      StatsD.prefix = from_env.statsd_prefix
+      StatsD.default_tags = from_env.statsd_default_tags
+      StatsD.default_sample_rate = from_env.statsd_sample_rate
+      StatsD.logger = Logger.new($stderr)
     end
   end
 
+  attr_reader :env
+
+  def initialize(env)
+    @env = env
+  end
+
   # Detects the current environment, either by asking Rails, or by inspecting environment variables.
   #
   # - Within a Rails application, <tt>Rails.env</tt> is used.
@@ -30,26 +68,65 @@ module StatsD::Instrument::Environment
   #
   # @return [String] The detected environment.
   def environment
-    if defined?(Rails) && Rails.respond_to?(:env)
+    if env['STATSD_ENV']
+      env['STATSD_ENV']
+    elsif defined?(Rails) && Rails.respond_to?(:env)
       Rails.env.to_s
     else
-      ENV['RAILS_ENV'] || ENV['RACK_ENV'] || ENV['ENV'] || 'development'
+      env['RAILS_ENV'] || env['RACK_ENV'] || env['ENV'] || 'development'
     end
   end
 
-  # Sets default values for sample rate and logger.
-  #
-  # - Default sample rate is set to the value in the STATSD_SAMPLE_RATE environment variable,
-  #   or 1.0 otherwise. See {StatsD#default_sample_rate}
-  # - {StatsD#logger} is set to a logger that send output to stderr.
-  #
-  # If you are including this library inside a Rails environment, additional initialization will
-  # be done as part of the {StatsD::Instrument::Railtie}.
-  #
-  # @return [void]
-  def setup
-    StatsD.default_sample_rate = ENV.fetch('STATSD_SAMPLE_RATE', 1.0).to_f
-    StatsD.logger = Logger.new($stderr)
+  def statsd_implementation
+    env.fetch('STATSD_IMPLEMENTATION', 'statsd')
+  end
+
+  def statsd_sample_rate
+    env.fetch('STATSD_SAMPLE_RATE', 1.0).to_f
+  end
+
+  def statsd_prefix
+    env.fetch('STATSD_PREFIX', nil)
+  end
+
+  def statsd_addr
+    env.fetch('STATSD_ADDR', 'localhost:8125')
+  end
+
+  def statsd_default_tags
+    env.key?('STATSD_DEFAULT_TAGS') ? env.fetch('STATSD_DEFAULT_TAGS').split(',') : nil
+  end
+
+  def default_client
+    @default_client ||= StatsD::Instrument::Client.new(
+      sink: default_sink_for_environment,
+      datagram_builder_class: default_datagram_builder_class_for_implementation,
+      default_sample_rate: statsd_sample_rate,
+      prefix: statsd_prefix,
+      default_tags: statsd_default_tags,
+    )
+  end
+
+  def default_datagram_builder_class_for_implementation
+    case statsd_implementation
+    when 'statsd'
+      StatsD::Instrument::StatsDDatagramBuilder
+    when 'datadog', 'dogstatsd'
+      StatsD::Instrument::DogStatsDDatagramBuilder
+    else
+      raise NotImplementedError, "No implementation for #{statsd_implementation}"
+    end
+  end
+
+  def default_sink_for_environment
+    case environment
+    when 'production', 'staging'
+      StatsD::Instrument::UDPSink.for_addr(statsd_addr)
+    when 'test'
+      StatsD::Instrument::NullSink.new
+    else
+      StatsD::Instrument::LogSink.new(StatsD.logger)
+    end
   end
 end
 

data/lib/statsd/instrument/log_sink.rb

@@ -0,0 +1,24 @@
+# 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::LogSink
+  attr_reader :logger, :severity
+
+  def initialize(logger, severity: Logger::DEBUG)
+    @logger = logger
+    @severity = severity
+  end
+
+  def sample?(_sample_rate)
+    true
+  end
+
+  def <<(datagram)
+    # Some implementations require a newline at the end of datagrams.
+    # When logging, we make sure those newlines are removed using chomp.
+
+    logger.add(severity, "[StatsD] #{datagram.chomp}")
+    self
+  end
+end

data/lib/statsd/instrument/null_sink.rb

@@ -0,0 +1,13 @@
+# 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::NullSink
+  def sample?(_sample_rate)
+    false
+  end
+
+  def <<(_datagram)
+    self # noop
+  end
+end

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

@@ -0,0 +1,39 @@
+# 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 `as_dist: true` keyword argument on `StatsD.measure`
+      # and `statsd_measure`. This argument is deprecated. Instead, you can use `StatsD.distribution`
+      # (or `statsd_distribution`) directly.
+      #
+      # To run this cop on your codebase:
+      #
+      #     rubocop --require `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb \
+      #       --only StatsD/MeasureAsDistArgument
+      #
+      # This cop will not autocorrect offenses.
+      class MeasureAsDistArgument < Cop
+        include RuboCop::Cop::StatsD
+
+        MSG = <<~MSG
+          Do not use StatsD.measure(..., as_dist: true). This is deprecated.
+
+          Use StatsD.distribution (or statsd_distribution) instead.
+        MSG
+
+        def on_send(node)
+          if metric_method?(node) && node.method_name == :measure
+            add_offense(node) if has_keyword_argument?(node, :as_dist)
+          end
+
+          if metaprogramming_method?(node) && node.method_name == :statsd_measure
+            add_offense(node) if has_keyword_argument?(node, :as_dist)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,7 @@
 # frozen-string-literal: true
 
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
 module RuboCop
   module Cop
     module StatsD
@@ -10,23 +12,17 @@ module RuboCop
       # 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
+      #       -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.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'
+        include RuboCop::Cop::StatsD
 
-        METAPROGRAMMING_METHODS = %i{
-          statsd_measure
-          statsd_distribution
-          statsd_count_success
-          statsd_count_if
-          statsd_count
-        }
+        MSG = 'Use keyword arguments for StatsD metaprogramming macros'
 
         def on_send(node)
-          if METAPROGRAMMING_METHODS.include?(node.method_name)
+          if metaprogramming_method?(node)
             arguments = node.arguments.dup
             arguments.shift # method
             arguments.shift # metric

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

@@ -1,28 +1,29 @@
 # 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/metric_return_value.rb \
+      #     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'
 
-        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
+          if metric_method?(node) && node.arguments.last&.type != :block_pass
+            add_offense(node.parent) if INVALID_PARENTS.include?(node.parent&.type)
           end
         end
       end

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

@@ -1,5 +1,7 @@
 # frozen-string-literal: true
 
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
 module RuboCop
   module Cop
     module StatsD
@@ -7,7 +9,7 @@ module RuboCop
       # 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 \
+      #      `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
@@ -15,29 +17,18 @@ module RuboCop
       #
       # `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}
+        include RuboCop::Cop::StatsD
 
-        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
+        MSG = <<~MSG
+          Do not use the StatsD.metric('name', value: <value>, ...). The `value` keyword argument is deprecated.
 
-              check_keyword_arguments_for_value_entry(node, last_argument) if last_argument&.type == :hash
-            end
-          end
-        end
+          Use a positional argument instead: StatsD.metric('name', <value>, ...).
+        MSG
 
-        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
+        def on_send(node)
+          if metric_method?(node) && has_keyword_argument?(node, :value)
+            add_offense(node)
           end
-          add_offense(node) if value_pair_found
         end
       end
     end

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

@@ -1,5 +1,7 @@
 # frozen-string-literal: true
 
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
 module RuboCop
   module Cop
     module StatsD
@@ -8,14 +10,14 @@ module RuboCop
       #
       # Use the following Rubocop invocation to check your project's codebase:
       #
-      #     rubocop --require `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/positional_arguments.rb \
+      #     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
-        MSG = 'Use keyword arguments for StatsD calls'
+        include RuboCop::Cop::StatsD
 
-        STATSD_SINGLETON_METHODS = %i{increment gauge measure set histogram distribution key_value}
+        MSG = 'Use keyword arguments for StatsD calls'
 
         POSITIONAL_ARGUMENT_TYPES = Set[:int, :float, :nil]
         UNKNOWN_ARGUMENT_TYPES = Set[:send, :const, :lvar, :splat]
@@ -26,16 +28,14 @@ module RuboCop
         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
+          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

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

@@ -1,5 +1,7 @@
 # frozen-string-literal: true
 
+require_relative '../rubocop' unless defined?(RuboCop::Cop::StatsD)
+
 module RuboCop
   module Cop
     module StatsD
@@ -7,30 +9,22 @@ module RuboCop
       # this rule on your codebase, invoke Rubocop this way:
       #
       #    rubocop --require \
-      #      `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/splat_arguments.rb \
+      #      `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb \
       #      --only StatsD/SplatArguments
       #
       # This cop will not autocorrect offenses.
       class SplatArguments < Cop
-        MSG = 'Do not use splat arguments in StatsD metric calls'
+        include RuboCop::Cop::StatsD
 
-        STATSD_METRIC_METHODS = %i{increment gauge measure set histogram distribution key_value}
+        MSG = 'Do not use splat arguments in StatsD metric calls'
 
         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)
+          if metric_method?(node)
+            if node.arguments.any? { |arg| arg.type == :splat }
+              add_offense(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

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