statsd-instrument 2.3.5 → 2.4.0

data/.rubocop.yml

@@ -0,0 +1,21 @@
+inherit_from:
+  - https://shopify.github.io/ruby-style-guide/rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 2.3
+  UseCache: true
+  CacheRootDirectory: tmp/rubocop
+  Exclude:
+    - statsd-instrument.gemspec
+
+Naming/FileName:
+  Enabled: true
+  Exclude:
+    - lib/statsd-instrument.rb
+
+Style/ClassAndModuleChildren:
+  Enabled: false # TODO: enable later
+
+
+Style/MethodCallWithArgsParentheses:
+  Enabled: false # TODO: enable later

data/CHANGELOG.md

@@ -5,6 +5,15 @@ please at an entry to the "unreleased changes" section below.
 
 ### Unreleased changes
 
+## Version 2.4.0
+
+- Add `StatsD.default_tags` to specify tags that should be included in all metrics. (#159)
+- Improve assertion message when assertying metrics whose tags do not match. (#100)
+- Enforce the Shopify Ruby style guide. (#164)
+- Migrate CI to Github actions. (#158)
+- Make the library frozen string literal-compatible. (#161, #163)
+- Fix all Ruby warnings. (#162)
+
 ## Version 2.3.5
 
 - Re-add `StatsD::Instrument.duration`, which was accidentally removed since verison 2.5.3 (#157)

data/CONTRIBUTING.md

@@ -17,21 +17,41 @@ When reporting issues, please include the following information:
 - The statsd-instrument version. **Note:** only the latest version is supported.
 - The StatsD backend you are using.
 
-## Pull request
+## Opening pull requests
 
 1. Fork the repository, and create a branch.
 2. Implement the feature or bugfix, and add tests that cover the changed functionality.
-3. Create a pull request. Make sure that you get Travis CI passes.
+3. Create a pull request. Make sure that you get a green CI status on your commit.
 
 Some notes:
 
-- Make sure to follow to coding style.
+- Make sure to follow to coding style. This is enforced by Rubocop
 - Make sure your changes are properly documented using [yardoc syntax](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md).
 - Add an entry to the "unreleased changes" section of [CHANGELOG.md](./CHANGELOG.md).
 - **Do not** update `StatsD::Instrument::VERSION`. This will be done during the release prodecure.
 
-> **Important:** if you change anything in the hot code path (sending a StatsD metric), please
-> include benchmarks to show the performance impact of your changes.
+### On perfomance & benchmarking
+
+This gem is used in production at Shopify, and is used to instrument some of
+our hottest code paths. This means that we are very careful about not
+introducing performance regressions in this library.
+
+**Important:** Whenever you make changes to the metric emission code path in this library,
+you **must** include benchmark results to show the impact of your changes.
+
+The `test/benchmark/` folder contains some example benchmark script that you
+can use, or can serve as a starting point. Please run your benchmark on your
+pull request revision, as well as the latest revision on `master`.
+
+### On backwards compatibility
+
+Shopify's codebases are heavily instrumented using this library. As a result, we cannot
+accept changes that are backwards incompatible:
+
+- Changes that will require us to update our codebases.
+- Changes that will cause metrics emitted by this library to change in form or shape.
+
+This means that we may not be able to accept fixes for what you consider a bug.
 
 ## Release procedure
 

data/Gemfile

@@ -1,2 +1,4 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 gemspec

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
@@ -7,4 +9,4 @@ Rake::TestTask.new('test') do |t|
   t.test_files = FileList['test/*.rb']
 end
 
-task :default => :test
+task default: :test

data/lib/statsd-instrument.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'statsd/instrument'

data/lib/statsd/instrument.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'socket'
 require 'logger'
 
@@ -28,6 +30,10 @@ require 'logger'
 #   The logger to use in case of any errors. The logger is also used as default logger
 #   for the LoggerBackend (although this can be overwritten).
 #
+# @!attribute default_tags
+#   The tags to apply to all metrics.
+#   @return [Array<String>, Hash<String, String>, nil] The default tags, or <tt>nil</tt> when no default tags is used
+#
 #   @see StatsD::Instrument::Backends::LoggerBackend
 #   @return [Logger]
 #
@@ -88,7 +94,8 @@ module StatsD
     def statsd_measure(method, name, *metric_options)
       add_to_method(method, name, :measure) do
         define_method(method) do |*args, &block|
-          StatsD.measure(StatsD::Instrument.generate_metric_name(name, self, *args), *metric_options) { super(*args, &block) }
+          metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
+          StatsD.measure(metric_name, *metric_options) { super(*args, &block) }
         end
       end
     end
@@ -104,7 +111,8 @@ module StatsD
     def statsd_distribution(method, name, *metric_options)
       add_to_method(method, name, :distribution) do
         define_method(method) do |*args, &block|
-          StatsD.distribution(StatsD::Instrument.generate_metric_name(name, self, *args), *metric_options) { super(*args, &block) }
+          metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
+          StatsD.distribution(metric_name, *metric_options) { super(*args, &block) }
         end
       end
     end
@@ -133,20 +141,27 @@ module StatsD
             truthiness = false
             raise
           else
-            truthiness = (yield(result) rescue false) if block_given?
+            if block_given?
+              begin
+                truthiness = yield(result)
+              rescue
+                truthiness = false
+              end
+            end
             result
           ensure
             suffix = truthiness == false ? 'failure' : 'success'
-            StatsD.increment("#{StatsD::Instrument.generate_metric_name(name, self, *args)}.#{suffix}", 1, *metric_options)
+            metric_name = "#{StatsD::Instrument.generate_metric_name(name, self, *args)}.#{suffix}"
+            StatsD.increment(metric_name, 1, *metric_options)
           end
         end
       end
     end
 
-    # Adds success and failure counter instrumentation to a method.
+    # Adds success counter instrumentation to a method.
     #
     # A method call will be considered successful if it does not raise an exception, and the result is true-y.
-    # Only for successful calls, the metric will be icnremented
+    # Only for successful calls, the metric will be incremented.
     #
     # @param method (see #statsd_measure)
     # @param name (see #statsd_measure)
@@ -165,10 +180,19 @@ module StatsD
             truthiness = false
             raise
           else
-            truthiness = (yield(result) rescue false) if block_given?
+            if block_given?
+              begin
+                truthiness = yield(result)
+              rescue
+                truthiness = false
+              end
+            end
             result
           ensure
-            StatsD.increment(StatsD::Instrument.generate_metric_name(name, self, *args), *metric_options) if truthiness
+            if truthiness
+              metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
+              StatsD.increment(metric_name, *metric_options)
+            end
           end
         end
       end
@@ -186,7 +210,8 @@ module StatsD
     def statsd_count(method, name, *metric_options)
       add_to_method(method, name, :count) do
         define_method(method) do |*args, &block|
-          StatsD.increment(StatsD::Instrument.generate_metric_name(name, self, *args), 1, *metric_options)
+          metric_name = StatsD::Instrument.generate_metric_name(name, self, *args)
+          StatsD.increment(metric_name, 1, *metric_options)
           super(*args, &block)
         end
       end
@@ -254,8 +279,13 @@ module StatsD
     def add_to_method(method, name, action, &block)
       instrumentation_module = statsd_instrumentation_for(method, name, action)
 
-      raise ArgumentError, "already instrumented #{method} for #{self.name}" if instrumentation_module.method_defined?(method)
-      raise ArgumentError, "could not find method #{method} for #{self.name}" unless method_defined?(method) || private_method_defined?(method)
+      if instrumentation_module.method_defined?(method)
+        raise ArgumentError, "Already instrumented #{method} for #{self.name}"
+      end
+
+      unless method_defined?(method) || private_method_defined?(method)
+        raise ArgumentError, "could not find method #{method} for #{self.name}"
+      end
 
       method_scope = method_visibility(method)
 
@@ -269,10 +299,9 @@ module StatsD
     end
 
     def method_visibility(method)
-      case
-      when private_method_defined?(method)
+      if private_method_defined?(method)
         :private
-      when protected_method_defined?(method)
+      elsif protected_method_defined?(method)
         :protected
       else
         :public
@@ -282,6 +311,11 @@ module StatsD
 
   attr_accessor :logger, :default_sample_rate, :prefix
   attr_writer :backend
+  attr_reader :default_tags
+
+  def default_tags=(tags)
+    @default_tags = StatsD::Instrument::Metric.normalize_tags(tags)
+  end
 
   def backend
     @backend ||= StatsD::Instrument::Environment.default_backend
@@ -382,7 +416,7 @@ module StatsD
   #      http_response = StatsD.distribution('HTTP.call.duration') do
   #        HTTP.get(url)
   #      end
-  def distribution(key, value=nil, *metric_options, &block)
+  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?
@@ -442,7 +476,7 @@ module StatsD
   # @param args [Array] The list of non-required arguments.
   # @return [Hash] The hash of optional arguments.
   def hash_argument(args)
-    return {} if args.length == 0
+    return {} if args.empty?
     return args.first if args.length == 1 && args.first.is_a?(Hash)
 
     order = [:sample_rate, :tags]
@@ -450,8 +484,7 @@ module StatsD
     args.each_with_index do |value, index|
       hash[order[index]] = value
     end
-
-    return hash
+    hash
   end
 
   def parse_options(value, metric_options)

data/lib/statsd/instrument/assertions.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module StatsD::Instrument::Assertions
   include StatsD::Instrument::Helpers
 
   def assert_no_statsd_calls(metric_name = nil, &block)
     metrics = capture_statsd_calls(&block)
     metrics.select! { |m| m.name == metric_name } if metric_name
-    assert metrics.empty?, "No StatsD calls for metric #{metrics.map(&:name).join(', ')} expected."
+    assert(metrics.empty?, "No StatsD calls for metric #{metrics.map(&:name).join(', ')} expected.")
   end
 
   def assert_statsd_increment(metric_name, options = {}, &block)
@@ -48,32 +50,36 @@ module StatsD::Instrument::Assertions
       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 }
-      assert filtered_metrics.length > 0,
-        "No StatsD calls for metric #{expected_metric.name} of type #{expected_metric.type} were made."
+      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"
-        if expected_metric.matches(metric)
-          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
-          end
+
+        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
         end
       end
 
-      assert expected_metric_times_remaining == 0,
-          "Metric expected #{expected_metric_times} times but seen"\
-          " #{expected_metric_times-expected_metric_times_remaining}"\
-          " times: #{expected_metric.inspect}"
+      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?
+
+      assert(expected_metric_times_remaining == 0, msg)
     end
     expected_metrics -= matched_expected_metrics
 
-    assert expected_metrics.empty?,
-      "Unexpected StatsD calls; the following metric expectations were not satisfied: #{expected_metrics.inspect}"
+    assert(expected_metrics.empty?,
+      "Unexpected StatsD calls; the following metric expectations were not satisfied: #{expected_metrics.inspect}")
   end
 
   private
@@ -87,6 +93,6 @@ module StatsD::Instrument::Assertions
   end
 
   def within_numeric_range?(object)
-    object.kind_of?(Numeric) && (0.0..1.0).cover?(object)
+    object.is_a?(Numeric) && (0.0..1.0).cover?(object)
   end
 end

data/lib/statsd/instrument/backend.rb

@@ -1,12 +1,13 @@
+# frozen_string_literal: true
+
 # This abstract class specifies the interface a backend implementation should conform to.
 # @abstract
 class StatsD::Instrument::Backend
-
   # Collects a metric.
   #
   # @param metric [StatsD::Instrument::Metric] The metric to collect
   # @return [void]
-  def collect_metric(metric)
+  def collect_metric(_metric)
     raise NotImplementedError, "Use a concerete backend implementation"
   end
 end

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

@@ -1,5 +1,6 @@
-module StatsD::Instrument::Backends
+# frozen_string_literal: true
 
+module StatsD::Instrument::Backends
   # The capture backend is used to capture the metrics that are collected, so you can
   # run assertions on them.
   #

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

@@ -1,10 +1,10 @@
-module StatsD::Instrument::Backends
+# frozen_string_literal: true
 
+module StatsD::Instrument::Backends
   # The logger backend simply logs every metric to a logger
   # @!attribute logger
   #    @return [Logger]
   class LoggerBackend < StatsD::Instrument::Backend
-
     attr_accessor :logger
 
     def initialize(logger)
@@ -14,7 +14,7 @@ module StatsD::Instrument::Backends
     # @param metric [StatsD::Instrument::Metric]
     # @return [void]
     def collect_metric(metric)
-      logger.info "[StatsD] #{metric}"
+      logger.info("[StatsD] #{metric}")
     end
   end
 end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StatsD::Instrument::Backends
   # The null backend does nothing when receiving a metric, effectively disabling the gem completely.
   class NullBackend < StatsD::Instrument::Backend

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

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 require 'monitor'
 
 module StatsD::Instrument::Backends
   class UDPBackend < StatsD::Instrument::Backend
-
     BASE_SUPPORTED_METRIC_TYPES = { c: true, ms: true, g: true, s: true }
 
     class DogStatsDProtocol
@@ -24,7 +25,7 @@ module StatsD::Instrument::Backends
       SUPPORTED_METRIC_TYPES = BASE_SUPPORTED_METRIC_TYPES.merge(h: true, _e: true, _sc: true, d: true)
 
       def generate_packet(metric)
-        packet = ""
+        packet = +""
 
         if metric.type == :_e
           escaped_title = metric.name.gsub("\n", "\\n")
@@ -41,6 +42,7 @@ module StatsD::Instrument::Backends
 
         packet << "|@#{metric.sample_rate}" if metric.sample_rate < 1
         packet << "|##{metric.tags.join(',')}" if metric.tags
+
         packet
       end
 
@@ -57,7 +59,7 @@ module StatsD::Instrument::Backends
       SUPPORTED_METRIC_TYPES = BASE_SUPPORTED_METRIC_TYPES.merge(kv: true)
 
       def generate_packet(metric)
-        packet = "#{metric.name}:#{metric.value}|#{metric.type}"
+        packet = +"#{metric.name}:#{metric.value}|#{metric.type}"
         packet << "|@#{metric.sample_rate}" unless metric.sample_rate == 1
         packet << "\n"
         packet
@@ -68,7 +70,7 @@ module StatsD::Instrument::Backends
       SUPPORTED_METRIC_TYPES = BASE_SUPPORTED_METRIC_TYPES
 
       def generate_packet(metric)
-        packet = "#{metric.name}:#{metric.value}|#{metric.type}"
+        packet = +"#{metric.name}:#{metric.value}|#{metric.type}"
         packet << "|@#{metric.sample_rate}" if metric.sample_rate < 1
         packet
       end
@@ -88,19 +90,20 @@ module StatsD::Instrument::Backends
 
     def implementation=(value)
       @packet_factory = case value
-        when :datadog
-          DogStatsDProtocol.new
-        when :statsite
-          StatsiteStatsDProtocol.new
-        else
-          StatsDProtocol.new
-        end
+      when :datadog
+        DogStatsDProtocol.new
+      when :statsite
+        StatsiteStatsDProtocol.new
+      else
+        StatsDProtocol.new
+      end
       @implementation = value
     end
 
     def collect_metric(metric)
       unless @packet_factory.class::SUPPORTED_METRIC_TYPES[metric.type]
-        StatsD.logger.warn("[StatsD] Metric type #{metric.type.inspect} not supported on #{implementation} implementation.")
+        StatsD.logger.warn("[StatsD] Metric type #{metric.type.inspect} is not supported " \
+          "on #{implementation} implementation.")
         return false
       end
 
@@ -139,13 +142,13 @@ module StatsD::Instrument::Backends
       synchronize do
         socket.send(command, 0) > 0
       end
-    rescue ThreadError => e
+    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 command without a lock.
       socket.send(command, 0) > 0
-    rescue SocketError, IOError, SystemCallError, Errno::ECONNREFUSED => e
-      StatsD.logger.error "[StatsD] #{e.class.name}: #{e.message}"
+    rescue SocketError, IOError, SystemCallError => e
+      StatsD.logger.error("[StatsD] #{e.class.name}: #{e.message}")
       invalidate_socket
     end