statsd-instrument 2.3.2 → 2.6.0

data/lib/statsd/instrument/environment.rb

@@ -1,25 +1,65 @@
+# 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.
-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.
@@ -28,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/helpers.rb

@@ -1,14 +1,22 @@
+# frozen_string_literal: true
+
 module StatsD::Instrument::Helpers
-  def capture_statsd_calls(&block)
-    mock_backend = StatsD::Instrument::Backends::CaptureBackend.new
-    old_backend, StatsD.backend = StatsD.backend, mock_backend
-    block.call
-    mock_backend.collected_metrics
-  ensure
-    if old_backend.kind_of?(StatsD::Instrument::Backends::CaptureBackend)
-      old_backend.collected_metrics.concat(mock_backend.collected_metrics)
+  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 = backend
+
+    block.call
+  ensure
     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/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/matchers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rspec/expectations'
 require 'rspec/core/version'
 
@@ -9,7 +11,7 @@ module StatsD::Instrument::Matchers
     histogram: :h,
     distribution: :d,
     set: :s,
-    key_value: :kv
+    key_value: :kv,
   }
 
   class Matcher
@@ -23,13 +25,10 @@ module StatsD::Instrument::Matchers
     end
 
     def matches?(block)
-      begin
-        expect_statsd_call(@metric_type, @metric_name, @options, &block)
-      rescue RSpec::Expectations::ExpectationNotMetError => e
-        @message = e.message
-
-        false
-      end
+      expect_statsd_call(@metric_type, @metric_name, @options, &block)
+    rescue RSpec::Expectations::ExpectationNotMetError => e
+      @message = e.message
+      false
     end
 
     def failure_message
@@ -50,8 +49,12 @@ module StatsD::Instrument::Matchers
       metrics = capture_statsd_calls(&block)
       metrics = metrics.select { |m| m.type == metric_type && m.name == metric_name }
 
-      raise RSpec::Expectations::ExpectationNotMetError, "No StatsD calls for metric #{metric_name} were made." if metrics.empty?
-      raise RSpec::Expectations::ExpectationNotMetError, "The numbers of StatsD calls for metric #{metric_name} was unexpected. Expected #{options[:times].inspect}, got #{metrics.length}" if options[:times] && options[:times] != metrics.length
+      if metrics.empty?
+        raise RSpec::Expectations::ExpectationNotMetError, "No StatsD calls for metric #{metric_name} were made."
+      elsif options[:times] && options[:times] != metrics.length
+        raise RSpec::Expectations::ExpectationNotMetError, "The numbers of StatsD calls for metric #{metric_name} " \
+         "was unexpected. Expected #{options[:times].inspect}, got #{metrics.length}"
+      end
 
       [:sample_rate, :value, :tags].each do |expectation|
         next unless options[expectation]
@@ -63,7 +66,7 @@ module StatsD::Instrument::Matchers
 
         found = options[:times] ? num_matches == options[:times] : num_matches > 0
 
-        if !found
+        unless found
           message = metric_information(metric_name, options, metrics, expectation)
           raise RSpec::Expectations::ExpectationNotMetError, message
         end

data/lib/statsd/instrument/metric.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 # The Metric class represents a metric sample to be send by a backend.
 #
 # @!attribute type
 #   @return [Symbol] The metric type. Must be one of {StatsD::Instrument::Metric::TYPES}
 # @!attribute name
 #   @return [String] The name of the metric. {StatsD#prefix} will automatically be applied
-#     to the metric in the constructor, unless the <tt>:no_prefix</tt> option is set or is 
+#     to the metric in the constructor, unless the <tt>:no_prefix</tt> option is set or is
 #     overridden by the <tt>:prefix</tt> option. Note that <tt>:no_prefix</tt> has greater
 #     precedence than <tt>:prefix</tt>.
 # @!attribute value
@@ -29,39 +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 = {})
-    @type = options[:type] or raise ArgumentError, "Metric :type is required."
-    @name = options[:name] or raise ArgumentError, "Metric :name is required."
-    @name = normalize_name(@name)
-    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])
-    @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.
@@ -69,40 +56,73 @@ 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; 1
-      else raise ArgumentError, "A value is required for metric type #{type.inspect}."
+    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
-    str = "#{TYPES[type]} #{name}:#{value}"
+    str = +"#{TYPES[type]} #{name}:#{value}"
     str << " @#{sample_rate}" if sample_rate != 1.0
-    str << " " << tags.map { |t| "##{t}"}.join(' ') if tags
+    tags&.each { |tag| str << " ##{tag}" }
     str
   end
 
   # @private
   # @return [String]
   def inspect
-    "#<StatsD::Instrument::Metric #{self.to_s}>"
+    "#<StatsD::Instrument::Metric #{self}>"
   end
 
   # The metric types that are supported by this library. Note that every StatsD server
   # implementation only supports a subset of them.
   TYPES = {
-    c:  'increment',
+    c: 'increment',
     ms: 'measure',
-    g:  'gauge',
-    h:  'histogram',
-    d:  'distribution',
+    g: 'gauge',
+    h: 'histogram',
+    d: 'distribution',
     kv: 'key/value',
-    s:  'set',
+    s: 'set',
   }
 
   # Strip metric names of special characters used by StatsD line protocol, replace with underscore
@@ -110,7 +130,10 @@ class StatsD::Instrument::Metric
   # @param name [String]
   # @return [String]
   def normalize_name(name)
-    name.tr(':|@'.freeze, '_')
+    # fast path when no normalization is needed to avoid copying the string
+    return name unless /[:|@]/.match?(name)
+
+    name.tr(':|@', '_')
   end
 
   # Utility function to convert tags to the canonical form.
@@ -122,7 +145,11 @@ class StatsD::Instrument::Metric
   # @return [Array<String>, nil] the list of tags in canonical form.
   def self.normalize_tags(tags)
     return unless tags
-    tags = tags.map { |k, v| k.to_s + ":".freeze + v.to_s } if tags.is_a?(Hash)
-    tags.map { |tag| tag.tr('|,'.freeze, ''.freeze) }
+    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/metric_expectation.rb

@@ -1,15 +1,31 @@
+# frozen_string_literal: true
+
 # @private
 class StatsD::Instrument::MetricExpectation
-
   attr_accessor :times, :type, :name, :value, :sample_rate, :tags
   attr_reader :ignore_tags
 
   def initialize(options = {})
-    @type = options[:type] or raise ArgumentError, "Metric :type is required."
-    @name = options[:name] or raise ArgumentError, "Metric :name is required."
+    if options[:type]
+      @type = options[:type]
+    else
+      raise ArgumentError, "Metric :type is required."
+    end
+
+    if options[:name]
+      @name = options[:name]
+    else
+      raise ArgumentError, "Metric :name is required."
+    end
+
+    if options[:times]
+      @times = options[:times]
+    else
+      raise ArgumentError, "Metric :times is required."
+    end
+
     @name = StatsD.prefix ? "#{StatsD.prefix}.#{@name}" : @name unless options[:no_prefix]
     @tags = StatsD::Instrument::Metric.normalize_tags(options[:tags])
-    @times = options[:times] or raise ArgumentError, "Metric :times is required."
     @sample_rate = options[:sample_rate]
     @value = options[:value]
     @ignore_tags = StatsD::Instrument::Metric.normalize_tags(options[:ignore_tags])
@@ -29,7 +45,7 @@ class StatsD::Instrument::MetricExpectation
         actual_tags -= ignored_tags
 
         if ignore_tags.is_a?(Array)
-          actual_tags.delete_if{ |key| ignore_tags.include?(key.split(":").first) }
+          actual_tags.delete_if { |key| ignore_tags.include?(key.split(":").first) }
         end
       end
 
@@ -39,30 +55,28 @@ class StatsD::Instrument::MetricExpectation
   end
 
   def default_value
-    case type
-      when :c; 1
-    end
+    1 if type == :c
   end
 
   TYPES = {
-      c:  'increment',
-      ms: 'measure',
-      g:  'gauge',
-      h:  'histogram',
-      d:  'distribution',
-      kv: 'key/value',
-      s:  'set',
+    c: 'increment',
+    ms: 'measure',
+    g: 'gauge',
+    h: 'histogram',
+    d: 'distribution',
+    kv: 'key/value',
+    s: 'set',
   }
 
   def to_s
-    str = "#{TYPES[type]} #{name}:#{value}"
+    str = +"#{TYPES[type]} #{name}:#{value}"
     str << " @#{sample_rate}" if sample_rate != 1.0
-    str << " " << tags.map { |t| "##{t}"}.join(' ') if tags
+    str << " " << tags.map { |t| "##{t}" }.join(' ') if tags
     str << " times:#{times}" if times > 1
     str
   end
 
   def inspect
-    "#<StatsD::Instrument::MetricExpectation #{self.to_s}>"
+    "#<StatsD::Instrument::MetricExpectation #{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/railtie.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 # This Railtie runs some initializers that will set the logger to <tt>Rails#logger</tt>,
 # and will initialize the {StatsD#backend} based on the Rails environment.
 #
 # @see StatsD::Instrument::Environment
 class StatsD::Instrument::Railtie < Rails::Railtie
-
   initializer 'statsd-instrument.use_rails_logger' do
     ::StatsD.logger = Rails.logger
   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

@@ -0,0 +1,42 @@
+# 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 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.rb
+      #
+      #
+      # This cop will not autocorrect the offenses it finds, but generally the fixes are easy to fix
+      class MetaprogrammingPositionalArguments < Cop
+        include RuboCop::Cop::StatsD
+
+        MSG = 'Use keyword arguments for StatsD metaprogramming macros'
+
+        def on_send(node)
+          if metaprogramming_method?(node)
+            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