statsd-instrument 3.0.0.pre1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec03c4f1452d2b5bca53c83faf68955d8095ad75ed0484103091789764e02233
-  data.tar.gz: 6037bd8e41bfc3b7d726c9f1120d10ce202a206dbfdd1e3368d550ed90f0bcc9
+  metadata.gz: 3a481f6cd0897b93e3e992fc5315b496c033a98a8cccd02948146cb638e0a6b2
+  data.tar.gz: ab454f2fecc89aa662ac2f16632fe2fc3c4e4b2b102d3c4058642e5706bf64c1
 SHA512:
-  metadata.gz: f282acf3e05dac8b66eddc5b2fb8e11501543bc2125c92d7154835bd832304d706e35dc831c7c4ea879f05f4f1b0568b67bd19e4a657ef45c8272c81aa29b0af
-  data.tar.gz: 65546513cc2e0fb9ea06ab220d63102ba354963397c96ae8d81983d3b9178ca8ca03ed1536c29a8d2938b125e7644a37cdc40c0707d9eab1ccca2298bd3b6ad1
+  metadata.gz: f3fae39281925135491d66805ff8dada34b0ea798d3403fdf0e6d3b9c1e2d3eda4a78295d7eea046ba7a0db55fb5d357d72e853558f12fdf81c71eff3713c816
+  data.tar.gz: 852e0838027594b8451d4fb617ca9aa5f614b570c50180bd513fb2986419adf3e9ea4f59ce86e63fbe799ccc3a07720954c87778c9a9dca63cd62fb339906d43

data/.github/workflows/lint.yml

@@ -0,0 +1,22 @@
+name: Lint
+
+on: push
+
+jobs:
+  test:
+    name: Rubocop
+    runs-on: ubuntu-18.04
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Setup Ruby
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6
+
+    - name: Install dependencies
+      run: gem install bundler && bundle install --jobs 4 --retry 3
+
+    - name: Run Rubocop
+      run: bin/rubocop

data/.github/workflows/tests.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on: push
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }} on ubuntu-18.04
+    runs-on: ubuntu-18.04
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['2.6', '2.7', '3.0']
+
+        # Windows on macOS builds started failing, so they are disabled for noew
+        # platform: [windows-2019, macOS-10.14, ubuntu-18.04]
+        # exclude:
+        # ...
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Setup Ruby
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+
+    - name: Install dependencies
+      run: gem install bundler && bundle install --jobs 4 --retry 3
+
+    - name: Run test suite
+      run: rake test

data/.rubocop.yml

@@ -1,11 +1,11 @@
-inherit_from:
-  - https://shopify.github.io/ruby-style-guide/rubocop.yml
+inherit_gem:
+  rubocop-shopify: rubocop.yml
 
 require:
   - ./lib/statsd/instrument/rubocop.rb
 
 AllCops:
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.6
   UseCache: true
   CacheRootDirectory: tmp/rubocop
   Exclude:
@@ -16,16 +16,6 @@ Naming/FileName:
   Exclude:
     - lib/statsd-instrument.rb
 
-Style/ClassAndModuleChildren:
-  Enabled: false # TODO: enable later
-
-
-Style/MethodCallWithArgsParentheses:
-  Enabled: false # TODO: enable later
-
-Lint/UnusedMethodArgument:
-  AllowUnusedKeywordArguments: true
-
 # Enable our own cops on our own repo
 
 StatsD/MetricReturnValue:

data/CHANGELOG.md

@@ -8,6 +8,56 @@ section below.
 
 _Nothing yet_
 
+## Version 3.1.0
+
+- Introduced UDP batching using a dispatcher thread, and made it the
+  production default.
+- Dropped support for Ruby 2.4 and 2.5.
+
+## Version 3.0.2
+
+- Properly handle no_prefix when using StatsD assertions.
+
+## Version 3.0.1
+
+- Fix metaprograming methods to not print keyword argument warnings on
+  Ruby 2.7.
+- Fix the gemspec to no longer register `rake` and `rubocop` as executables.
+
+## Version 3.0.0
+
+This version makes the new client that was added in version 2.6+ the default
+client, and removes the legacy client.
+
+- All previously deprecated functionality has been removed (since version 2.5,
+  see below).
+- Support for the StatSite implementation has been dropped.
+- Support for Ruby version older than 2.4 has been dropped.
+- The default implementation has been changed to DataDog. To use the standard
+  StatsD implementation (which was the default in v2), set the
+  `STATSD_IMPLEMENTATION` environment variable to `statsd`.
+
+To upgrade, follow the following process:
+
+1. Upgrade to version 2.9.2.
+2. Switch to the new client by setting the `STATSD_USE_NEW_CLIENT` environment
+   variable to 1.
+   - You may want to use the Rubocop rules that ship with this library, and
+     strict mode to find and fix deprecated usage patterns. See below for more
+     information about strict mode and the available Rubocop rules.
+3. Upgrade to version 3.0.0, and unset `STATSD_USE_NEW_CLIENT`.
+
+## Version 2.9.2
+
+- Allow providing a value as second positional argument to `assert_statsd_*`
+  methods, rather than as keyword argument. This matches the arguments to the
+  StatsD metric call.
+  ``` ruby
+    assert_statsd_increment('batch_size', 10) do
+      StatsD.increment('batch_size', 10)
+    end
+  ```
+
 ## Version 2.9.1
 
 - The `VOID` object being returned by metric methods (e.g. `StatsD.increment`)

data/Gemfile

@@ -3,5 +3,11 @@
 source "https://rubygems.org"
 gemspec
 
-# benchmark-ips save! method is not part of a released version yet.
-gem 'benchmark-ips', git: 'https://github.com/evanphx/benchmark-ips', branch: 'master'
+gem "rake"
+gem "minitest"
+gem "rspec"
+gem "mocha"
+gem "yard"
+gem "rubocop", ">= 1.0"
+gem "rubocop-shopify", require: false
+gem "benchmark-ips"

data/README.md

@@ -20,7 +20,7 @@ The following environment variables are supported:
 
 - `STATSD_ADDR`: (default `localhost:8125`) The address to send the StatsD UDP
   datagrams to.
-- `STATSD_IMPLEMENTATION`: (default: `statsd`). The StatsD implementation you
+- `STATSD_IMPLEMENTATION`: (default: `datadog`). The StatsD implementation you
   are using. `statsd`, `statsite` and `datadog` are supported. Some features
   are only available on certain implementations,
 - `STATSD_ENV`: The environment StatsD will run in. If this is not set
@@ -42,6 +42,9 @@ The following environment variables are supported:
   overridden in a metric method call.
 - `STATSD_DEFAULT_TAGS`: A comma-separated list of tags to apply to all metrics.
   (Note: tags are not supported by all implementations.)
+- `STATSD_FLUSH_INTERVAL`: (default: `1.0`) The interval in seconds at which
+  events are sent in batch. Only applicable to the UDP configuration. If set
+  to `0.0`, metrics are sent immediately.
 
 ## StatsD keys
 
@@ -105,7 +108,7 @@ Because you are counting unique values, the results of using a sampling value le
 Builds a histogram of numeric values.
 ``` ruby
 
-StatsD.histogram('Order.value', order.value_in_usd.to_f tags: { source: 'POS' })
+StatsD.histogram('Order.value', order.value_in_usd.to_f, tags: { source: 'POS' })
 ```
 
 Because you are counting unique values, the results of using a sampling value less than 1.0 can lead to unexpected, hard to interpret results.
@@ -128,7 +131,7 @@ An event is a (title, text) tuple that can be used to correlate metrics with som
 This is a good fit for instance to correlate response time variation with a deploy of the new code.
 
 ```ruby
-StatsD.event('shipit.deploy', 'started', sample_rate: 1.0)
+StatsD.event('shipit.deploy', 'started')
 ```
 
 *Note: This is only supported by the [datadog implementation](https://docs.datadoghq.com/guides/dogstatsd/#events).*

data/Rakefile

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require "bundler/gem_tasks"
+require "rake/testtask"
 
-Rake::TestTask.new('test') do |t|
-  t.ruby_opts << '-r rubygems'
-  t.libs << 'lib' << 'test'
-  t.test_files = FileList['test/**/*_test.rb']
+Rake::TestTask.new("test") do |t|
+  t.ruby_opts << "-r rubygems"
+  t.libs << "lib" << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task default: :test
+task(default: :test)

data/benchmark/send-metrics-to-dev-null-log

@@ -1,13 +1,14 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'benchmark/ips'
+require "bundler/setup"
+require "tmpdir"
+require "benchmark/ips"
 
 revision = %x(git rev-parse HEAD).rstrip
 master_revision = %x(git rev-parse origin/master).rstrip
 branch = if revision == master_revision
-  'master'
+  "master"
 else
   %x(git rev-parse --abbrev-ref HEAD).rstrip
 end
@@ -15,18 +16,18 @@ end
 intermediate_results_filename = "#{Dir.tmpdir}/statsd-instrument-benchmarks/#{File.basename($PROGRAM_NAME)}"
 FileUtils.mkdir_p(File.dirname(intermediate_results_filename))
 
-ENV['ENV'] = "development"
-require 'statsd-instrument'
+ENV["ENV"] = "development"
+require "statsd-instrument"
 StatsD.logger = Logger.new(File::NULL)
 
 report = Benchmark.ips do |bench|
   bench.report("StatsD metrics to /dev/null log (branch: #{branch}, sha: #{revision[0, 7]})") do
-    StatsD.increment('StatsD.increment', 10, sample_rate: 15)
-    StatsD.measure('StatsD.measure') { 1 + 1 }
-    StatsD.gauge('StatsD.gauge', 12.0, tags: ["foo:bar", "quc"])
-    StatsD.set('StatsD.set', 'value', tags: { foo: 'bar', baz: 'quc' })
+    StatsD.increment("StatsD.increment", 10, sample_rate: 15)
+    StatsD.measure("StatsD.measure") { 1 + 1 }
+    StatsD.gauge("StatsD.gauge", 12.0, tags: ["foo:bar", "quc"])
+    StatsD.set("StatsD.set", "value", tags: { foo: "bar", baz: "quc" })
     if StatsD.singleton_client.datagram_builder_class == StatsD::Instrument::DogStatsDDatagramBuilder
-      StatsD.event('StasD.event', "12345")
+      StatsD.event("StasD.event", "12345")
       StatsD.service_check("StatsD.service_check", "ok")
     end
   end
@@ -40,7 +41,7 @@ if report.entries.length == 1
   puts
   puts "To compare the performance of this revision against another revision (e.g. master),"
   puts "check out a different branch and run this benchmark script again."
-elsif ENV['KEEP_RESULTS']
+elsif ENV["KEEP_RESULTS"]
   puts
   puts "The intermediate results have been stored in #{intermediate_results_filename}"
 else

data/benchmark/send-metrics-to-local-udp-receiver

@@ -1,15 +1,16 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'benchmark/ips'
-require 'socket'
-require 'statsd-instrument'
+require "bundler/setup"
+require "benchmark/ips"
+require "tmpdir"
+require "socket"
+require "statsd-instrument"
 
 revision = %x(git rev-parse HEAD).rstrip
 master_revision = %x(git rev-parse origin/master).rstrip
 branch = if revision == master_revision
-  'master'
+  "master"
 else
   %x(git rev-parse --abbrev-ref HEAD).rstrip
 end
@@ -19,22 +20,22 @@ FileUtils.mkdir_p(File.dirname(intermediate_results_filename))
 
 # Set up an UDP listener to which we can send StatsD packets
 receiver = UDPSocket.new
-receiver.bind('localhost', 0)
+receiver.bind("localhost", 0)
 
 StatsD.singleton_client = StatsD::Instrument::Environment.new(
-  'STATSD_ADDR' => "#{receiver.addr[2]}:#{receiver.addr[1]}",
-  'STATSD_IMPLEMENTATION' => 'dogstatsd',
-  'STATSD_ENV' => 'production',
+  "STATSD_ADDR" => "#{receiver.addr[2]}:#{receiver.addr[1]}",
+  "STATSD_IMPLEMENTATION" => "dogstatsd",
+  "STATSD_ENV" => "production",
 ).client
 
 report = Benchmark.ips do |bench|
   bench.report("StatsD metrics to local UDP receiver (branch: #{branch}, sha: #{revision[0, 7]})") do
-    StatsD.increment('StatsD.increment', 10)
-    StatsD.measure('StatsD.measure') { 1 + 1 }
-    StatsD.gauge('StatsD.gauge', 12.0, tags: ["foo:bar", "quc"])
-    StatsD.set('StatsD.set', 'value', tags: { foo: 'bar', baz: 'quc' })
+    StatsD.increment("StatsD.increment", 10)
+    StatsD.measure("StatsD.measure") { 1 + 1 }
+    StatsD.gauge("StatsD.gauge", 12.0, tags: ["foo:bar", "quc"])
+    StatsD.set("StatsD.set", "value", tags: { foo: "bar", baz: "quc" })
     if StatsD.singleton_client.datagram_builder_class == StatsD::Instrument::DogStatsDDatagramBuilder
-      StatsD.event('StasD.event', "12345")
+      StatsD.event("StasD.event", "12345")
       StatsD.service_check("StatsD.service_check", "ok")
     end
   end
@@ -50,7 +51,7 @@ if report.entries.length == 1
   puts
   puts "To compare the performance of this revision against another revision (e.g. master),"
   puts "check out a different branch and run this benchmark script again."
-elsif ENV['KEEP_RESULTS']
+elsif ENV["KEEP_RESULTS"]
   puts
   puts "The intermediate results have been stored in #{intermediate_results_filename}"
 else

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load(Gem.bin_path("rake", "rake"))

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load(Gem.bin_path("rubocop", "rubocop"))

data/lib/statsd-instrument.rb

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

data/lib/statsd/instrument.rb

@@ -1,89 +1,17 @@
 # frozen_string_literal: true
 
-require 'socket'
-require 'logger'
-require 'forwardable'
+require "socket"
+require "logger"
+require "forwardable"
 
-# The StatsD module contains low-level metrics for collecting metrics and sending them to the backend.
+# The `StatsD` module contains low-level metrics for collecting metrics and
+# sending them to the backend.
 #
-# @!attribute client
-#   @return [StatsD::Instrument::Backend] The client that will handle singleton method calls in the next
-#     major version of this library.
-#   @note This new Client implementation is intended to become the new default in
-#     the next major release of this library. While this class may already be functional,
-#     we provide no guarantees about the API and the behavior may change.
-#
-# @!attribute backend
-#   The backend that is being used to emit the metrics.
-#   @return [StatsD::Instrument::Backend] the currently active backend. If there is no active backend
-#     yet, it will call {StatsD::Instrument::Environment#default_backend} to obtain a
-#     default backend for the environment.
-#   @see StatsD::Instrument::Environment#default_backend
-#   @deprecated
-#
-# @!attribute prefix
-#   The prefix to apply to metric names. This can be useful to group all the metrics
-#   for an application in a shared StatsD server.
-#
-#   When using a prefix a dot will be included automatically to separate the prefix
-#   from the metric name.
-#
-#   @return [String, nil] The prefix, or <tt>nil</tt> when no prefix is used
-#   @see StatsD::Instrument::Metric#name
-#   @deprecated
-#
-# @!attribute default_sample_rate
-#   The sample rate to use if the sample rate is unspecified for a metric call.
-#   @return [Float] Default is 1.0.
-#   @deprecated
-#
-# @!attribute 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).
-#   @see StatsD::Instrument::Backends::LoggerBackend
-#   @return [Logger]
-#
-# @!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
-#   @deprecated
-#
-# @!attribute singleton_client
-#   @nodoc
-#   @deprecated
-#
-# @!method measure(name, value = nil, sample_rate: nil, tags: nil, &block)
-#   (see StatsD::Instrument::Client#measure)
-#
-# @!method increment(name, value = 1, sample_rate: nil, tags: nil)
-#   (see StatsD::Instrument::Client#increment)
-#
-# @!method gauge(name, value, sample_rate: nil, tags: nil)
-#   (see StatsD::Instrument::Client#gauge)
-#
-# @!method set(name, value, sample_rate: nil, tags: nil)
-#   (see StatsD::Instrument::Client#set)
-#
-# @!method histogram(name, value, sample_rate: nil, tags: nil)
-#   (see StatsD::Instrument::Client#histogram)
-#
-# @!method distribution(name, value = nil, sample_rate: nil, tags: nil, &block)
-#   (see StatsD::Instrument::Client#distribution)
-#
-# @!method key_value(name, value)
-#   (see StatsD::Instrument::Client#key_value)
-#
-# @!method event(title, text, tags: nil, hostname: nil, timestamp: nil, aggregation_key: nil, priority: nil, source_type_name: nil, alert_type: nil) # rubocop:disable Metrics/LineLength
-#   (see StatsD::Instrument::Client#event)
-#
-# @!method service_check(name, status, tags: nil, hostname: nil, timestamp: nil, message: nil)
-#   (see StatsD::Instrument::Client#service_check)
-#
-# @see StatsD::Instrument <tt>StatsD::Instrument</tt> contains module to instrument
+# @see .singleton_client Metric method calls on the `StatsD` singleton will
+#   be handled by the client assigned to `StatsD.singleton_client`.
+# @see StatsD::Instrument `StatsD::Instrument` contains module to instrument
 #    existing methods with StatsD metrics
 module StatsD
-  extend self
-
   # The StatsD::Instrument module provides metaprogramming methods to instrument your methods with
   # StatsD metrics. E.g., you can create counters on how often a method is called, how often it is
   # successful, the duration of the methods call, etc.
@@ -99,9 +27,11 @@ module StatsD
       end
     end
 
+    # Generates a metric name for an instrumented method.
     # @private
+    # @return [String]
     def self.generate_metric_name(name, callee, *args)
-      name.respond_to?(:call) ? name.call(callee, args).gsub('::', '.') : name.gsub('::', '.')
+      name.respond_to?(:call) ? name.call(callee, args).gsub("::", ".") : name.gsub("::", ".")
     end
 
     # Even though this method is considered private, and is no longer used internally,
@@ -183,26 +113,24 @@ module StatsD
     def statsd_count_success(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil)
       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
+          truthiness = result = super(*args, &block)
+        rescue
+          truthiness = false
+          raise
+        else
+          if block_given?
+            begin
+              truthiness = yield(result)
+            rescue
+              truthiness = false
             end
-            result
-          ensure
-            client ||= StatsD.singleton_client
-            suffix = truthiness == false ? 'failure' : 'success'
-            key = StatsD::Instrument.generate_metric_name(name, self, *args)
-            client.increment("#{key}.#{suffix}", sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
           end
+          result
+        ensure
+          client ||= StatsD.singleton_client
+          suffix = truthiness == false ? "failure" : "success"
+          key = StatsD::Instrument.generate_metric_name(name, self, *args)
+          client.increment("#{key}.#{suffix}", sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
         end
       end
     end
@@ -222,27 +150,25 @@ module StatsD
     def statsd_count_if(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil)
       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
-              client ||= StatsD.singleton_client
-              key = StatsD::Instrument.generate_metric_name(name, self, *args)
-              client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
+          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
+            client ||= StatsD.singleton_client
+            key = StatsD::Instrument.generate_metric_name(name, self, *args)
+            client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
+          end
         end
       end
     end
@@ -345,6 +271,9 @@ module StatsD
 
       instrumentation_module.module_eval(&block)
       instrumentation_module.send(method_scope, method)
+      if instrumentation_module.respond_to?(:ruby2_keywords, true)
+        instrumentation_module.send(:ruby2_keywords, method)
+      end
       prepend(instrumentation_module) unless self < instrumentation_module
     end
 
@@ -363,35 +292,73 @@ module StatsD
     end
   end
 
-  attr_accessor :logger
-  attr_writer :singleton_client
+  class << self
+    extend Forwardable
 
-  extend Forwardable
+    # The logger to use in case of any errors.
+    #
+    # @return [Logger]
+    # @see StatsD::Instrument::LogSink
+    attr_accessor :logger
 
-  def singleton_client
-    @singleton_client ||= StatsD::Instrument::Environment.current.client
-  end
+    # The StatsD client that handles method calls on the StatsD singleton.
+    #
+    # E.g. a call to `StatsD.increment` will be handled by this client.
+    #
+    # @return [StatsD::Instrument::Client]
+    attr_writer :singleton_client
 
-  # Singleton methods will be delegated to the singleton client.
-  def_delegators :singleton_client, :increment, :gauge, :set, :measure,
-    :histogram, :distribution, :key_value, :event, :service_check
+    # The StatsD client that handles method calls on the StatsD singleton
+    # @return [StatsD::Instrument::Client]
+    def singleton_client
+      @singleton_client ||= StatsD::Instrument::Environment.current.client
+    end
+
+    # @!method measure(name, value = nil, sample_rate: nil, tags: nil, &block)
+    #   (see StatsD::Instrument::Client#measure)
+    #
+    # @!method increment(name, value = 1, sample_rate: nil, tags: nil)
+    #   (see StatsD::Instrument::Client#increment)
+    #
+    # @!method gauge(name, value, sample_rate: nil, tags: nil)
+    #   (see StatsD::Instrument::Client#gauge)
+    #
+    # @!method set(name, value, sample_rate: nil, tags: nil)
+    #   (see StatsD::Instrument::Client#set)
+    #
+    # @!method histogram(name, value, sample_rate: nil, tags: nil)
+    #   (see StatsD::Instrument::Client#histogram)
+    #
+    # @!method distribution(name, value = nil, sample_rate: nil, tags: nil, &block)
+    #   (see StatsD::Instrument::Client#distribution)
+    #
+    # @!method event(title, text, tags: nil, hostname: nil, timestamp: nil, aggregation_key: nil, priority: nil, source_type_name: nil, alert_type: nil) # rubocop:disable Layout/LineLength
+    #   (see StatsD::Instrument::Client#event)
+    #
+    # @!method service_check(name, status, tags: nil, hostname: nil, timestamp: nil, message: nil)
+    #   (see StatsD::Instrument::Client#service_check)
+
+    def_delegators :singleton_client, :increment, :gauge, :set, :measure,
+      :histogram, :distribution, :event, :service_check
+  end
 end
 
-require 'statsd/instrument/version'
-require 'statsd/instrument/client'
-require 'statsd/instrument/datagram'
-require 'statsd/instrument/dogstatsd_datagram'
-require 'statsd/instrument/datagram_builder'
-require 'statsd/instrument/statsd_datagram_builder'
-require 'statsd/instrument/dogstatsd_datagram_builder'
-require 'statsd/instrument/null_sink'
-require 'statsd/instrument/udp_sink'
-require 'statsd/instrument/capture_sink'
-require 'statsd/instrument/log_sink'
-require 'statsd/instrument/environment'
-require 'statsd/instrument/helpers'
-require 'statsd/instrument/assertions'
-require 'statsd/instrument/expectation'
-require 'statsd/instrument/matchers' if defined?(::RSpec)
-require 'statsd/instrument/railtie' if defined?(::Rails::Railtie)
-require 'statsd/instrument/strict' if ENV['STATSD_STRICT_MODE']
+require "statsd/instrument/version"
+require "statsd/instrument/client"
+require "statsd/instrument/datagram"
+require "statsd/instrument/dogstatsd_datagram"
+require "statsd/instrument/datagram_builder"
+require "statsd/instrument/statsd_datagram_builder"
+require "statsd/instrument/dogstatsd_datagram_builder"
+require "statsd/instrument/null_sink"
+require "statsd/instrument/udp_sink"
+require "statsd/instrument/batched_udp_sink"
+require "statsd/instrument/capture_sink"
+require "statsd/instrument/log_sink"
+require "statsd/instrument/environment"
+require "statsd/instrument/helpers"
+require "statsd/instrument/assertions"
+require "statsd/instrument/expectation"
+require "statsd/instrument/matchers" if defined?(::RSpec)
+require "statsd/instrument/railtie" if defined?(::Rails::Railtie)
+require "statsd/instrument/strict" if ENV["STATSD_STRICT_MODE"]