Changelog

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 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) is now a subclass of Object rather than BasicObject, which means that common methods will work as expected (#class, #tap).

Version 2.9.0

  • ⚠️ DEPRECATION: The StatsD.key_value metric method is deprecated and will be removed in version 3.0. The new client does not have StatSite support. Due to the lack of active contributors that can port this metric type to the new client, we have decided to drop it until somebody else steps up and re-adds it to the new client.
  • Fix: metaprogramming methods will send metrics to the client assifgned to StatsD.singleton_client when the metric is emitted, rather than the client when the metaprogramming method was called.
  • Metric methods (e.g. StatsD.increment) on the new client will now return a VOID object that evaluates to true rather than nil. This is for better backwards compatibility with the legacy client.
  • Add support for variadic arguments to assert_no_statsd_calls. This allows consolidation of assertions about specific metrics. For example: diff -assert_no_statsd_calls('foo') do - assert_no_statsd_calls('bar') do - assert_no_statsd_calls('biz.baz') do +assert_no_statsd_calls('foo', 'bar', 'biz.baz') do # do work... - end - end end

Version 2.8.0

  • ⚠️ Remove support for assert_statsd_*(..., ignore_tags: ...). This feature was never documented, and the only use case we were aware of has been addressed since. It's highly unlikely that you are using this feature. However, if you are, you can capture StatsD datagrams using the capture_statsd_datagrams method, and run your own assertions on the list.
  • ⚠️ Remove StatsD.client. This was added in version 2.6.0 in order to experiment with the new client. However, at this point there are better ways to do this.
    • You can set StatsD.singleton_client to a new client, which causes the calls to the StatsD singleton to be handled by a new client. If you set STATSD_USE_NEW_CLIENT, it will be initialized to a new client.
    • If that doesn't work for you, you can instantiate a client using StatsD::Instrument::Client.from_env and assign it to a variable of your own choosing.
  • Fix some compatibility issues when using assert_statsd_* methods when using a new client with prefix.

Version 2.7.1

This release has some small fixes related to the new client only:

  • Bugfix: Fix the metaprogramming methods so they work with a new client when strict mode is not enabled.
  • Make it easier to instantiate new clients by specifying an implementation (e.g. datadog) rather than a DatagramBuilder class.
  • Change NullSink#sample? to always return true, so it's easier to verify business rules by using a different DatagramBuilder in test suites.

Version 2.7.0

This release allows you to switch the StatsD singleton to use the new, more performant client. By setting STATSD_USE_NEW_CLIENT as environment variable methods called on the StatsD singleton (e.g. StatsD.increment) will be delegated to an instance of the new client, configured using environment variables.

The new client should be mostly compatible with the legacy client, but some deprecated functionality will no longer work. See the changelog for version 2.6.0 and 2.5.0 for more information about the deprecations, and how to find and fix deprecations in your code base.

  • The old legacy client that was implemented on the StatsD singleton has been moved to StatsD::LegacyClient.singleton. By default, all method calls on the StatsD singleton will be delegated to this legacy client.
  • By setting STATSD_USE_NEW_CLIENT as environment variable, these method calls will be delegated to an instance of the new client instead. This client is configured using the existing STATSD_* environment variables, like STATSD_ADDR and STATSD_IMPLEMENTATION.
  • You can also assign a custom client to StatsD.singleton_client.

The assert_statsd_* methods have been reworked to support asserting StatsD datagrams coming from a legacy client, or from a new client.

  • By default, the assertion methods will capture metrics emitted from StatsD.singleton_client.
  • You can provide a client argument if you want to assert metrics being emitted by a different client. E.g.
    assert_statsd_increment('foo', client: my_custom_client) do
      my_custom_client.increment('foo')
    end
  • You can also capture metrics yourself, and then run assertions on them by providing a datagrams argument:
    datagrams = my_custom_client.capture do
      my_custom_client.increment('foo')
    end
    assert_statsd_increment('foo', datagrams: datagrams)

This makes it easy to run multiple assertions on the set of metrics that was emitted without having to nest calls.

  • ⚠️ DEPRECATION The assert_statsd_*-family of methods now use keyword arguments, rather than option hashes. This means that calls that use unsupported arguments will raise an ArgumentError now, rather than silently ignoring unknown keys.

  • ⚠️ DEPRECATION: The following methods to configure the legacy client are deprecated:

    • Statsd.backend
    • StatsD.default_sample_rate
    • StatsD.default_tags
    • StatsD.prefix

We recommend configuring StatsD using environment variables, which will be picked up by the new client as well. You can also instantiate a new client yourself; you can provide similar configuration options to StatsD::Instrument::Client.new.

You can use the following Rubocop invocation to find any occurrences of these deprecated method calls:

    rubocop --require `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb \
      --only StatsD/SingletonConfiguration

Version 2.6.0

This release contains a new StatsD::Instrument::Client class, which is slated to replace the current implementation in the next major release.

The main reasons for this rewrite are two folds:

  • Improved performance.
  • Being able to instantiate multiple clients.

We have worked hard to make the new client as compatible as possible. However, to accomplish some of our goals we have deprecated some stuff that we think is unlikely to be used. See the rest of the release notes of this version, and version 2.5.0 to see what is deprecated.

You can test compatibility with the new client by replacing StatsD with StatsD.client, which points to a client that will be instantiated using the same environment variables that you can already use for this library. You can also use strict mode, and rubocop rules to check whether you are using any deprecated patterns. See below for more info.

  • ⚠️ DEPRECATION: Using the prefix: "foo" argument for StatsD.metric calls (and the metaprogramming macros) is deprecated.

    • You can include the prefix in the metric name.
    • If you want to override the global prefix, set no_prefix: true and include the desired prefix in the metric name

This library ships with a Rubocop rule to detect uses of this keyword argument in your codebase:

  # Check for the prefix arguments on your StatsD.metric calls
  rubocop --only StatsD/MetricPrefixArgument \
    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb

Strict mode has also been updated to no longer allow this argument.

  • ⚠️ DEPRECATION: Using the as_dist: true argument for StatsD.measure and statsd_measure methods is deprecated. This argument was only available for internal use, but was exposed in the public API. It is unlikely that you are using this argument, but you can check to make sure using this Rubocop invocation:
  # Check for the as_dist arguments on your StatsD.measure calls
  rubocop --only StatsD/MeasureAsDistArgument \
    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop.rb

Strict mode has also been updated to no longer allow this argument.

  • You can now enable strict mode by setting the STATSD_STRICT_MODE environment variable. No more need to change your Gemfile! Note that it is still not recommended to enable strict mode in production due to the performance penalty, but is recommended for development and test. E.g. use STATSD_STRICT_MODE=1 rails test to run your test suite with strict mode enabled to expose any deprecations in your codebase.

  • Add support for STATSD_PREFIX and STATSD_DEFAULT_TAGS environment variables to configure the prefix to use for metrics and the comma-separated list of tags to apply to every metric, respectively.

These environment variables are preferred over using StatsD.prefix and StatsD.default_tags: it's best practice to configure the StatsD library using environment variables.

  • Several improvements to StatsD.event and StatsD.service_check (both are Datadog-only). The previous implementation would sometimes construct invalid datagrams based on the input. The method signatures have been made more explicit, and documentation of these methods is now also more clear.

  • Slight behaviour change when using the assert_statsd_* assertion methods in combination with assert_raises: we now do not allow the block passed to the assert_statsd_ call to raise an exception. This may cause tests to fail that previously were succeeding.

Consider the following example:

  assert_raises(RuntimeError) do
    assert_statsd_increment('foo') do
      raise 'something unexpected'
    end
  end

In versions before 2.3.3, the assert assert_statsd_* calls would silently pass when an exception would occur, which would later be handled by assert_raises. So the test would pass, even though no foo metric would be emitted.

Version 2.3.3 changed this by failing the test because no metric was being emitted. However, this would hide the the exception from the assertion message, complicating debugging efforts.

Now, we fail the test because an unexpected exception occurred inside the block. This means that the following test will fail: s

  assert_raises(RuntimeError) do
    assert_statsd_increment('foo') do
      StatsD.increment('foo')
      raise 'something unexpected'
    end
  end

To fix, you will need to nest the assert_raises inside the block passed to assert_statsd_instrument so that assert_statsd_increment will not see any exceptions:

  assert_statsd_increment('foo') do
    assert_raises(RuntimeError) do
      StatsD.increment('foo')
      raise 'something unexpected'
    end
  end

See #193, #184, and #166 for more information.

Version 2.5.1

  • Bugfix: when using metaprogramming methods, changes to StatsD.prefix after the metaprogramming method was evaluated would not be respected. This unfortunately is quite common when you set the StatsD prefix inside an initializer. This issue is now addressed: the prefix is evaluated at the moment the metric is emitted, not when the metaprogramming method is being evaluated. (#202)

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.
  # 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:

  # 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:

  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:

  # In your Gemfile
  gem 'statsd-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 significantly 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 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)
  • Fix all Ruby warnings. (#162)

Version 2.3.5

  • Re-add StatsD::Instrument.duration, which was accidentally removed since version 2.5.3 (#157)

Version 2.3.4

  • Improve performance of Metric#to_s (#152)
  • Fix bug in escaping newlines for events with Datadog Backend (#153)

Version 2.3.3

  • Capture measure and distribution metrics on exception and early return (#134)

NOTE: Now that exceptions are measured statistics may behave differently. An exception example:

StatsD.measure('myhttpcall') do
  my_http_object.invoke
end

Version 2.3.2 and below did not track metrics whenever a HTTP Timeout exception was raised. 2.3.3 and above will include those metrics which may increase the values included.

A return example:

StatsD.measure('myexpensivecalculation') do
  return if expensive_calculation_disabled?
  expensive_calculation
end

If expensive_calculation_disabled? is true 50% of the time version 2.3.2 will drop the average metric considerably.

Version 2.3.2

  • Add option to override global prefix for metrics (#148)

Version 2.3.1

  • Add mutex around UDP socket invalidation (#147)

Version 2.3.0

  • No changes from beta6, distributions are GA at DataDog so making the distribution changes GA in gem

Version 2.3.0.beta6

  • Fix invalidate socket on connectivity issues in UDP (#135)

Version 2.3.0.beta5

  • Fixes bug in return value for blocks used in distributions (#132)

Version 2.3.0.beta4

  • Add support for distribution to accept a block
  • Add class method for defining and removing a distribution from a method (same as a measure)
  • Refactor most instrument methods to reduce code duplication

Version 2.3.0.beta3

  • fix for :as_dist parameter in the statsd_measure class method

Version 2.3.0.beta2

  • Add support for specifying a measure to emit as a distribution using :as_dist parameter

Version 2.3.0.beta

  • Add support for beta, Datadog specific distribution metrics
  • Invalidate socket on connectivity issues

Version 2.2.1

  • Fix performance regression from v2.2.0

Version 2.2.0

  • Add support for two new Datadog specific metric types: events and service checks.

Version 2.1.3

  • The assert_statsd_calls test helper will now raise an exception whenever a block isn't passed.
  • Sending stats inside an exit handler will no longer cause programs to exit abruptly.

Version 2.1.2

  • Use prepend instead of rewriting classes for metaprogramming methods.
  • RSpec: make matchers more flexible.
  • Bugfix: Only ask Rails for the environment when it's actually loaded.

Version 2.1.1

  • Add assert_statsd_calls to from validating cases where one has multiple metrics with the same name and type being recorded, but with different options.

Version 2.1.0

  • Fix rspec-rails compatibility
  • Add value keyword argument to all metric types.

Version 2.0.12

  • Make StatsD client thread-safe
  • Assertions: Ensure sample rates have proper values.
  • Assertions: Make tag assertions work more intuitively
  • RSpec: Add backwards compatibility for RSpec 2

Version 2.0.11

  • Don't change method visibility when adding instrumentation to methods using metaprogramming
  • RSpec: add support for Compound expectations

Version 2.0.10

  • Assertions: allow ignoring certain tags when asserting for other tags to be present.

Version 2.0.9

  • Better error message for assert_no_statsd_calls

Version 2.0.8

  • More tag handling performance improvements.
  • RSpec matchers documentation improvements

Version 2.0.7

  • Tag handling performance improvements.
  • Test against Ruby 2.2.
  • Drop support for Ruby 1.9.3.

Version 2.0.6

  • Fix some loading order issues in Rails environments.
  • Default behavior: in a staging environment, the defaults are now the same as in a production environment.
  • Documentation overhaul

Version 2.0.5

  • Allow for nested assertions using the assert_statsd_* assertion methods.

Version 2.0.4

  • Add a Railtie to fix some initialization issues.

Version 2.0.3

  • Assertion method bugfixes

Version 2.0.2

  • Documentation fixes

Version 2.0.1

  • Add assertion methods assert_statsd_histogram, assert_statsd_set, and assert_statsd_key_value.

Version 2.0.0

  • Complete rewrite using pluggable backends.
  • Add assertion methods in StatsD::Instrument::Assertions to make testing easier and less brittle.
  • Drop support for Ruby 1.8