statsd-instrument 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c681ce1c0c9bd2755808d3b89ed7a56a924deaf384bf842e5e0a2b600a06c251
-  data.tar.gz: 8d4fbba3f23be9603861fff38a0dd604d00faa9d0105051a3e08d83e464fdf71
+  metadata.gz: 19c798557b1db75029e1efded949cee656fe0b33b77e3c1c13edde73be5e4957
+  data.tar.gz: 46b43c2589e9d0628cab7d070a4163e6bfa6d54e7b03b8d85681e0bf29d2c733
 SHA512:
-  metadata.gz: 15cbe3f85876c3e47658c8c15b65840e1bf97d4423199beedaef54e7843e469fd0958cf95a3960b11c5651e0fb8b3be3cf75543c22f98a5f0942e84ed6c4140f
-  data.tar.gz: '0590c1766ab84f54901568e98d273ddb3d6a7b59494223904cb5bfe9625473bfea40724f4f3b2d854cd4496a7f3b50d042fce082719bfab6596e5cbe467b4e51'
+  metadata.gz: 6b09c458ef308d1afbf8264a44f1399a00863e607afd0ad3bd43b297976130e50663e9c4cd9fa17490ad4f283faef9f15b41fc9283bac7500b87dbd21af89a5a
+  data.tar.gz: d52f9d40110e812ece11a3d87d52013df1f18e96f0a88ea8c1411950d17926a7936954839cb5e6d374c63745499e3f9e379607bf5432880643bb03b32b7eabb2

data/.github/workflows/benchmark.yml

@@ -0,0 +1,32 @@
+name: Benchmarks
+
+on: push
+
+jobs:
+  test:
+    name: Send metric over UDP
+    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 benchmark on branch
+      run: benchmark/send-metrics-to-local-udp-receiver
+
+    - uses: actions/checkout@v1
+      with:
+        ref: 'master'
+
+    - name: Install dependencies if needed
+      run: bundle check || bundle install --jobs 4 --retry 3
+
+    - name: Run benchmark on master
+      run: benchmark/send-metrics-to-local-udp-receiver

data/.github/workflows/ci.yml

@@ -4,11 +4,30 @@ on: push
 
 jobs:
   test:
-    name: Ruby ${{ matrix.ruby }}
-    runs-on: ubuntu-18.04
+    name: Ruby ${{ matrix.ruby }} on ${{ matrix.platform }}
+    runs-on: ${{ matrix.platform }}
     strategy:
+      fail-fast: false
       matrix:
-        ruby: ['2.3', '2.4', '2.5', '2.6']
+        platform: [ubuntu-18.04, windows-2019, macOS-10.14]
+        ruby: [2.3, 2.4, 2.5, 2.6]
+
+        exclude:
+        # The Windows environment does not support older Ruby versions. We only test against the latest version
+        - platform: windows-2019
+          ruby: 2.3
+        - platform: windows-2019
+          ruby: 2.4
+        - platform: windows-2019
+          ruby: 2.5
+
+        # On macOS, we only test against the Ruby version macOS ships with (2.3)
+        - platform: macOS-10.14
+          ruby: 2.4
+        - platform: macOS-10.14
+          ruby: 2.5
+        - platform: macOS-10.14
+          ruby: 2.6
 
     steps:
     - uses: actions/checkout@v1
@@ -16,13 +35,10 @@ jobs:
     - name: Setup Ruby
       uses: actions/setup-ruby@v1
       with:
-        version: ${{ matrix.ruby }}
-        architecture: 'x64'
+        ruby-version: ${{ matrix.ruby }}
 
     - name: Install dependencies
-      run: |
-        gem install bundler
-        bundle install --jobs 4 --retry 3
+      run: gem install bundler && bundle install --jobs 4 --retry 3
 
     - name: Run test suite
       run: bundle exec rake

data/.rubocop.yml

@@ -1,6 +1,13 @@
 inherit_from:
   - https://shopify.github.io/ruby-style-guide/rubocop.yml
 
+require:
+  - ./lib/statsd/instrument/rubocop/metric_return_value.rb
+  - ./lib/statsd/instrument/rubocop/metric_value_keyword_argument.rb
+  - ./lib/statsd/instrument/rubocop/positional_arguments.rb
+  - ./lib/statsd/instrument/rubocop/splat_arguments.rb
+  - ./lib/statsd/instrument/rubocop/metaprogramming_positional_arguments.rb
+
 AllCops:
   TargetRubyVersion: 2.3
   UseCache: true
@@ -19,3 +26,20 @@ Style/ClassAndModuleChildren:
 
 Style/MethodCallWithArgsParentheses:
   Enabled: false # TODO: enable later
+
+# Enable our own cops on our own repos
+
+StatsD/MetricReturnValue:
+  Enabled: true
+
+StatsD/MetricValueKeywordArgument:
+  Enabled: true
+
+StatsD/PositionalArguments:
+  Enabled: true
+
+StatsD/SplatArguments:
+  Enabled: true
+
+StatsD/MetaprogrammingPositionalArguments:
+  Enabled: true

data/CHANGELOG.md

@@ -1,14 +1,127 @@
 # Changelog
 
-This file documents the changes between releases of this library. When creating a pull request,
-please at an entry to the "unreleased changes" section below.
+This file documents the changes between releases of this library. When
+creating a pull request, please add an entry to the "unreleased changes"
+section below.
 
 ### Unreleased changes
 
+_Nothing yet_
+
+## Version 2.5.0
+
+- **DEPRECATION**: Providing a sample rate and tags to your metrics and method
+  instrumentation macros should be done using keyword arguments rather than
+  positional arguments. Also, previously you could provide `value` as a keyword
+  argument, but it should be provided as the second positional argument.
+
+  ``` ruby
+  # DEPRECATED
+  StatsD.increment 'counter', 1, 0.1, ['tag']
+  StatsD.increment 'counter', value: 123, tags: { foo: 'bar' }
+  StatsD.measure('duration', nil, 1.0) { foo }
+  statsd_count_success :method, 'metric-name', 0.1
+
+  # SUPPORTED
+  StatsD.increment 'counter', sample_rate: 0.1, tags: ['tag']
+  StatsD.increment 'counter', 123, tags: { foo: 'bar' }
+  StatsD.measure('duration', sample_rate: 1.0) { foo }
+  statsd_count_success :method, 'metric-name', sample_rate: 0.1
+  ```
+
+  The documentation of the methods has been updated to reflect this change.
+  The behavior of the library is not changed for the time being, so you can
+  safely upgrade to this version. However, in a future major release, we will
+  remove support for the positional arguments.
+
+  The library includes some cops to help with finding issues in your existing
+  codebase, and fixing them:
+
+  ``` sh
+  # Check for positional arguments on your StatsD.metric calls
+  rubocop --only StatsD/PositionalArguments \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/positional_arguments.rb
+
+  # Check for positional arguments on your statsd_instrumentation macros
+  rubocop --only StatsD/MetaprogrammingPositionalArguments \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metaprogramming_positional_arguments.rb
+
+  # Check for value as keyword argument
+  rubocop --only StatsD/MetricValueKeywordArgument \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_value_keyword_argument.rb
+
+  ```
+
+- **DEPRECATION**: Relying on the return value of the StatsD metric methods
+  (e.g. `StatsD.increment`) is deprecated. StatsD is a fire-and-forget
+  protocol, so your code should not depend on the return value of these methods.
+
+  The documentation of the methods has been updated to reflect this change.
+  The behavior of the library is not changed for the time being, so you can
+  safely upgrade to this version. However, in a future major release, we will
+  start to explicitly return `nil`.
+
+  This gem comes with a Rubocop rule that can help verify that your
+  application is not relying on the return value of the metric methods. To use
+  this cop on your codebase, invoke Rubocop with the following arguments:
+
+  ``` sh
+  rubocop --only StatsD/MetricReturnValue \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_return_value.rb
+  ```
+
+- **Strict mode**: These custom Rubocop rules will give you a quick indication
+  of the issues in your codebase, but are not airtight. This library now also
+  ships with strict mode, a mixin module that already disables this deprecated
+  behavior so it will raise exceptions if you are depending on deprecated
+  behavior. It will also do additional input validation, and make sure the
+  `StatsD` metric methods return `nil`.
+
+  You enable strict mode by requiring `statsd/instrument/strict`:
+
+  ``` ruby
+  # In your Gemfile
+  gem 'statd-instrument', require: 'statsd/instrument/strict'
+
+  # Or, in your test helper:
+  require 'statsd/instrument/strict'
+  ```
+
+  It is recommended to enable this in CI to find deprecation issues, but not
+  in production because enabling it comes with a performance penalty.
+
+- **Performance improvements 🎉**: Several internal changes have made the
+  library run singificantly faster. The changes:
+
+  - Improve performance of duration calculations. (#168)
+  - Early exit when no changes are needed to bring tags and metric names to
+    normalized form. (#173)
+  - Refactor method argument handling to reduce object allocations and
+    processing. (#174)
+
+  A benchmark suite was added (#169) and it now runs as part of CI (#170) so we
+  can more easily spot performance regressions before they get merged into the
+  library.
+
+  The result of this work:
+
+  ```
+  Comparison:
+  StatsD metrics to local UDP receiver (branch: master, sha: 2f98046):    10344.9 i/s
+  StatsD metrics to local UDP receiver (branch: v2.4.0, sha: 371d22a):     8556.5 i/s - 1.21x  (± 0.00) slower
+  ```
+
+  The deprecations mentioned above will allows us to provide an even greater
+  performance improvement, so update your code base to not use those
+  deprecations anymore, and keep your eyes open for future releases of the
+  library!
+
+- _Bugfix:_ avoid deadlock when an error occurs in the integration test suite (#175)
+
 ## 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)
+- Improve assertion message when asserting 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)

data/CONTRIBUTING.md

@@ -36,12 +36,13 @@ 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.
+**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`.
+The `benchmark/` folder contains some example benchmark script that you can
+use, or can serve as a starting point. The [benchmark README](benchmark/README.md)
+has instructions on how to benchmark your changes.
 
 ### On backwards compatibility
 
@@ -51,7 +52,8 @@ 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.
+This means that we may not be able to accept fixes for what you consider a bug, because
+we are depending on the current behavior of the library.
 
 ## Release procedure
 

data/Gemfile

@@ -2,3 +2,6 @@
 
 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'

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/testtask'
 Rake::TestTask.new('test') do |t|
   t.ruby_opts << '-r rubygems'
   t.libs << 'lib' << 'test'
-  t.test_files = FileList['test/*.rb']
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
 task default: :test

data/benchmark/README.md

@@ -0,0 +1,29 @@
+# Benchmark scripts
+
+This directory contains benchmark scripts that can be used to gauge the
+performance impact of changes.
+
+As mentioned in the contributing guidelines, this library is used heavily in
+production at Shopify in many of our hot code paths. This means that we care a
+lot about changes not introducing performance regressions. Every pull request
+that changes the code path to send metrics should include benchmarks
+demonstrating the performance impact of the changes.
+
+This directory contains two scripts to help with benchmarking.
+
+- `send-metrics-to-dev-null-log` exercises the code path to construct metrics.
+- `send-metrics-to-local-udp-listener` will also exercise the code path to
+  actually send a StatsD packet over UDP.
+
+To benchmark your changes:
+
+1. Make sure the benchmark script will actually cover your changes.
+   - If not, please create a new benchmark script that does.
+   - Do not commit this script to the repository (yet), so it will continue to
+     be available if you check out another branch.
+2. Run these scripts on your pull request branch. The results will be stored in
+   a temporary file.
+3. Checkout the latest version of `master`.
+4. Run the benchmark again. The benchmark script will now print a comparison
+   between your branch and master.
+5. Include the output in your pull request description.

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'benchmark/ips'
+require 'logger'
+
+revision = %x(git rev-parse HEAD).rstrip
+master_revision = %x(git rev-parse origin/master).rstrip
+branch = if revision == master_revision
+  'master'
+else
+  %x(git rev-parse --abbrev-ref HEAD).rstrip
+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'
+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.event('StasD.event', "12345")
+    StatsD.service_check("StatsD.service_check", "ok")
+  end
+
+  # Store the results in between runs
+  bench.save!(intermediate_results_filename)
+  bench.compare!
+end
+
+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']
+  puts
+  puts "The intermediate results have been stored in #{intermediate_results_filename}"
+else
+  File.unlink(intermediate_results_filename)
+end

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'benchmark/ips'
+require 'socket'
+
+revision = %x(git rev-parse HEAD).rstrip
+master_revision = %x(git rev-parse origin/master).rstrip
+branch = if revision == master_revision
+  'master'
+else
+  %x(git rev-parse --abbrev-ref HEAD).rstrip
+end
+
+intermediate_results_filename = "#{Dir.tmpdir}/statsd-instrument-benchmarks/#{File.basename($PROGRAM_NAME)}"
+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)
+
+ENV['ENV'] = "production"
+ENV['STATSD_ADDR'] = "#{receiver.addr[2]}:#{receiver.addr[1]}"
+ENV['STATSD_IMPLEMENTATION'] ||= 'datadog'
+
+require 'statsd-instrument'
+
+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' })
+    if StatsD.backend.implementation == :datadog
+      StatsD.event('StasD.event', "12345")
+      StatsD.service_check("StatsD.service_check", "ok")
+    end
+  end
+
+  # Store the results in between runs
+  bench.save!(intermediate_results_filename)
+  bench.compare!
+end
+
+receiver.close
+
+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']
+  puts
+  puts "The intermediate results have been stored in #{intermediate_results_filename}"
+else
+  File.unlink(intermediate_results_filename)
+end