statsd-instrument 2.9.0 → 3.0.0

data/lib/statsd/instrument/assertions.rb

@@ -71,8 +71,8 @@ module StatsD::Instrument::Assertions
   # @return [void]
   # @raise [Minitest::Assertion] If an exception occurs, or if the metric did
   #   not occur as specified during the execution the block.
-  def assert_statsd_increment(metric_name, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.increment(metric_name, **options)
+  def assert_statsd_increment(metric_name, value = nil, datagrams: nil, client: nil, **options, &block)
+    expectation = StatsD::Instrument::Expectation.increment(metric_name, value, **options)
     assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
   end
 
@@ -83,8 +83,8 @@ module StatsD::Instrument::Assertions
   # @yield (see #assert_statsd_increment)
   # @return [void]
   # @raise (see #assert_statsd_increment)
-  def assert_statsd_measure(metric_name, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.measure(metric_name, **options)
+  def assert_statsd_measure(metric_name, value = nil, datagrams: nil, client: nil, **options, &block)
+    expectation = StatsD::Instrument::Expectation.measure(metric_name, value, **options)
     assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
   end
 
@@ -95,8 +95,8 @@ module StatsD::Instrument::Assertions
   # @yield (see #assert_statsd_increment)
   # @return [void]
   # @raise (see #assert_statsd_increment)
-  def assert_statsd_gauge(metric_name, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.gauge(metric_name, **options)
+  def assert_statsd_gauge(metric_name, value = nil, datagrams: nil, client: nil, **options, &block)
+    expectation = StatsD::Instrument::Expectation.gauge(metric_name, value, **options)
     assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
   end
 
@@ -107,8 +107,8 @@ module StatsD::Instrument::Assertions
   # @yield (see #assert_statsd_increment)
   # @return [void]
   # @raise (see #assert_statsd_increment)
-  def assert_statsd_histogram(metric_name, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.histogram(metric_name, **options)
+  def assert_statsd_histogram(metric_name, value = nil, datagrams: nil, client: nil, **options, &block)
+    expectation = StatsD::Instrument::Expectation.histogram(metric_name, value, **options)
     assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
   end
 
@@ -119,8 +119,8 @@ module StatsD::Instrument::Assertions
   # @yield (see #assert_statsd_increment)
   # @return [void]
   # @raise (see #assert_statsd_increment)
-  def assert_statsd_distribution(metric_name, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.distribution(metric_name, **options)
+  def assert_statsd_distribution(metric_name, value = nil, datagrams: nil, client: nil, **options, &block)
+    expectation = StatsD::Instrument::Expectation.distribution(metric_name, value, **options)
     assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
   end
 
@@ -131,20 +131,8 @@ module StatsD::Instrument::Assertions
   # @yield (see #assert_statsd_increment)
   # @return [void]
   # @raise (see #assert_statsd_increment)
-  def assert_statsd_set(metric_name, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.set(metric_name, **options)
-    assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
-  end
-
-  # Asserts that a given key/value metric occurred inside the provided block.
-  #
-  # @param metric_name (see #assert_statsd_increment)
-  # @param options (see #assert_statsd_increment)
-  # @yield (see #assert_statsd_increment)
-  # @return [void]
-  # @raise (see #assert_statsd_increment)
-  def assert_statsd_key_value(metric_name, datagrams: nil, client: nil, **options, &block)
-    expectation = StatsD::Instrument::Expectation.key_value(metric_name, **options)
+  def assert_statsd_set(metric_name, value = nil, datagrams: nil, client: nil, **options, &block)
+    expectation = StatsD::Instrument::Expectation.set(metric_name, value, **options)
     assert_statsd_expectation(expectation, datagrams: datagrams, client: client, &block)
   end
 

data/lib/statsd/instrument/client.rb

@@ -1,22 +1,27 @@
 # frozen_string_literal: true
 
-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'
-
-# The Client is the main interface for using StatsD.
+# The Client is the main interface for using StatsD. It defines the metric
+# methods that you would normally call from your application.
 #
-# @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.
+# The client set to {StatsD.singleton_client} will handle all metric calls made
+# against the StatsD singleton, e.g. `StatsD.increment`.
+#
+# We recommend that the configuration of the StatsD setup is provided through
+# environment variables
+#
+# You are encouraged to instantiate multiple clients, and instantiate variants
+# of an existing clients using {#clone_with_options}. We recommend instantiating
+# a separate client for every logical component of your application using
+# `clone_with_options`, and setting a different metric `prefix`.
+#
+# @see StatsD.singleton_client
+# @see #clone_with_options
 class StatsD::Instrument::Client
   class << self
+    # Instantiates a StatsD::Instrument::Client using configuration values provided in
+    # environment variables.
+    #
+    # @see StatsD::Instrument::Environment
     def from_env(
       env = StatsD::Instrument::Environment.current,
       prefix: env.statsd_prefix,
@@ -36,7 +41,14 @@ class StatsD::Instrument::Client
       )
     end
 
+    # Finds the right DatagramBuilder class for a given implementation.
     # @private
+    # @param [Symbol, String] implementation The name of the implementation, e.g.
+    #   `"statsd"` or `:datadog`.
+    # @return [Class] The subclass of {StatsD::Instrument::DatagramBuilder}
+    #   builder to use to generate UDP datagrams for the given implementation.
+    # @raise `NotImplementedError` if the implementation is not recognized or
+    #   supported.
     def datagram_builder_class_for_implementation(implementation)
       case implementation.to_s
       when 'statsd'
@@ -49,8 +61,87 @@ class StatsD::Instrument::Client
     end
   end
 
-  attr_reader :sink, :datagram_builder_class, :prefix, :default_tags, :default_sample_rate
+  # The class to use to build StatsD datagrams. To build the actual datagrams,
+  # the class will be instantiated, potentially multiple times, by the client.
+  #
+  # @return [Class] A subclass of {StatsD::Instrument::DatagramBuilder}
+  # @see .datagram_builder_class_for_implementation
+  attr_reader :datagram_builder_class
+
+  # The sink to send UDP datagrams to.
+  #
+  # This can be set to any object that responds to the following methods:
+  #
+  # - `sample?` which should return true if the metric should be sampled, i.e.
+  #   actually sent to the sink.
+  # - `#<<` which takes a UDP datagram as string to emit the datagram. This
+  #   method will only be called if `sample?` returned `true`.
+  #
+  # Generally, you should use an instance of one of the following classes that
+  # ship with this library:
+  #
+  # - {StatsD::Instrument::UDPSink} A sink that will actually emit the provided
+  #   datagrams over UDP.
+  # - {StatsD::Instrument::NullSink} A sink that will simply swallow every
+  #   datagram. This sink is for use when testing your application.
+  # - {StatsD::Instrument::LogSink} A sink that log all provided datagrams to
+  #   a Logger, normally {StatsD.logger}.
+  #
+  # @return [#sample?, #<<]
+  attr_reader :sink
+
+  # The prefix to prepend to the metric names that are emitted through this
+  # client, using a dot (`.`) as namespace separator. E.g. when the prefix is
+  # set to `foo`, and you emit a metric named `bar`, the metric name will be
+  # `foo.bar`.
+  #
+  # Generally all the metrics you emit to the same StatsD server will share a
+  # single, global namespace. If you are emitting metrics from multiple
+  # applications, using a prefix is recommended to prevent metric name
+  # collisions.
+  #
+  # You can also leave this value to be `nil` if you don't want to prefix your
+  # metric names.
+  #
+  # @return [String, nil]
+  #
+  # @note The `prefix` can be overriden by any metric call by setting the
+  #   `no_prefix` keyword argument to `true`. We recommend against doing this,
+  #   but this behavior is retained for backwards compatibility.
+  #   Rather, when you feel the need to do this, we recommend instantiating
+  #   a new client without prefix (using {#clone_with_options}), and using it
+  #   to emit the metric.
+  attr_reader :prefix
+
+  # The tags to apply to all the metrics emitted through this client.
+  #
+  # The tags can be supplied in normal form: an array of strings. You can also
+  # provide a hash, which will be turned into normal form by concatanting the
+  # key and the value using a colon. To not use any default tags, set to `nil`.
+  # Note that other components of your StatsD metric pipeline may also add tags
+  # to metrics. E.g. the DataDog agent may add add tags like `hostname`.
+  #
+  # We generally recommend to not use default tags, or use them sparingly.
+  # Adding tags to every metric easily introduces carninality explosions, which
+  # will make metrics less precise due to the lossy nature of aggregation. It
+  # also makes your infrastructure more expsnive to run, and the user interface
+  # of your metric explorer less responsive.
+  #
+  # @return [Array<String>, Hash, nil]
+  attr_reader :default_tags
 
+  # The default sample rate to use for metrics that are emitted without a
+  # sample rate set. This should be a value between 0 (never emit a metric) and
+  # 1.0 (always emit). If it is not set, the default value 1.0 is used.
+  #
+  # We generally recommend setting sample rates on individual metrics based
+  # on their frequency, rather than changing the default sample rate.
+  #
+  # @return [Float] (default: 1.0) A value between 0.0 and 1.0.
+  attr_reader :default_sample_rate
+
+  # Instantiates a new client.
+  # @see .from_env to instantiate a client using environment variables.
   def initialize(
     prefix: nil,
     default_sample_rate: 1.0,
@@ -226,18 +317,15 @@ class StatsD::Instrument::Client
     end
   end
 
-  # Emits a service check.
-  #
-  # @param [String] title Event title.
-  # @param [String] text Event description. Newlines are allowed.
-  # @param [Time] timestamp The of the event. If not provided,
-  #   Datadog will interpret it as the current timestamp.
-  # @param [String] hostname A hostname to associate with the event.
-  # @param [String] aggregation_key An aggregation key to group events with the same key.
-  # @param [String] priority Priority of the event. Either "normal" (default) or "low".
-  # @param [String] source_type_name The source type of the event.
-  # @param [String] alert_type Either "error", "warning", "info" (default) or "success".
-  # @param [Array, Hash] tags Tags to associate with the event.
+  # Emits a service check. Services Checks allow you to characterize the status
+  # of a service in order to monitor it within Datadog.
+  #
+  # @param name (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
+  # @param status (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
+  # @param timestamp (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
+  # @param hostname (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
+  # @param tags (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
+  # @param message (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
   # @return [void]
   #
   # @note Supported by the Datadog implementation only.
@@ -246,15 +334,17 @@ class StatsD::Instrument::Client
       timestamp: timestamp, hostname: hostname, tags: tags, message: message))
   end
 
-  # Emits an event.
+  # Emits an event. An event represents any record of activity noteworthy for engineers.
   #
-  # @param [String] name Name of the service
-  # @param [Symbol] status Either `:ok`, `:warning`, `:critical` or `:unknown`
-  # @param [Time] timestamp The moment when the service was checked. If not provided,
-  #   Datadog will interpret it as the current timestamp.
-  # @param [String] hostname A hostname to associate with the check.
-  # @param [Array, Hash] tags Tags to associate with the check.
-  # @param [String] message A message describing the current state of the service check.
+  # @param title (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param text (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param timestamp (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param hostname (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param aggregation_key (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param priority (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param source_type_name (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param alert_type (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
+  # @param tags (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
   # @return [void]
   #
   # @note Supported by the Datadog implementation only.

data/lib/statsd/instrument/environment.rb

@@ -19,21 +19,6 @@ class StatsD::Instrument::Environment
       current.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(current.statsd_addr, current.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,
@@ -45,9 +30,6 @@ class StatsD::Instrument::Environment
     #
     # @return [void]
     def setup
-      StatsD.prefix = current.statsd_prefix
-      StatsD.default_tags = current.statsd_default_tags
-      StatsD.default_sample_rate = current.statsd_sample_rate
       StatsD.logger = Logger.new($stderr)
     end
   end
@@ -96,11 +78,7 @@ class StatsD::Instrument::Environment
   end
 
   def client
-    if env.key?('STATSD_USE_NEW_CLIENT')
-      StatsD::Instrument::Client.from_env(self)
-    else
-      StatsD::Instrument::LegacyClient.singleton
-    end
+    StatsD::Instrument::Client.from_env(self)
   end
 
   def default_sink_for_environment

data/lib/statsd/instrument/expectation.rb

@@ -3,32 +3,28 @@
 # @private
 class StatsD::Instrument::Expectation
   class << self
-    def increment(name, **options)
-      new(type: :c, name: name, **options)
+    def increment(name, value = nil, **options)
+      new(type: :c, name: name, value: value, **options)
     end
 
-    def measure(name, **options)
-      new(type: :ms, name: name, **options)
+    def measure(name, value = nil, **options)
+      new(type: :ms, name: name, value: value, **options)
     end
 
-    def gauge(name, **options)
-      new(type: :g, name: name, **options)
+    def gauge(name, value = nil, **options)
+      new(type: :g, name: name, value: value, **options)
     end
 
-    def set(name, **options)
-      new(type: :s, name: name, **options)
+    def set(name, value = nil, **options)
+      new(type: :s, name: name, value: value, **options)
     end
 
-    def key_value(name, **options)
-      new(type: :kv, name: name, **options)
+    def distribution(name, value = nil, **options)
+      new(type: :d, name: name, value: value, **options)
     end
 
-    def distribution(name, **options)
-      new(type: :d, name: name, **options)
-    end
-
-    def histogram(name, **options)
-      new(type: :h, name: name, **options)
+    def histogram(name, value = nil, **options)
+      new(type: :h, name: name, value: value, **options)
     end
   end
 

data/lib/statsd/instrument/helpers.rb

@@ -3,38 +3,9 @@
 module StatsD::Instrument::Helpers
   def capture_statsd_datagrams(client: nil, &block)
     client ||= StatsD.singleton_client
-    case client
-    when StatsD.legacy_singleton_client
-      capture_statsd_metrics_on_legacy_client(&block)
-    when StatsD::Instrument::Client
-      client.capture(&block)
-    else
-      raise ArgumentError, "Don't know how to capture StatsD datagrams from #{client.inspect}!"
-    end
+    client.capture(&block)
   end
 
   # For backwards compatibility
   alias_method :capture_statsd_calls, :capture_statsd_datagrams
-
-  def capture_statsd_metrics_on_legacy_client(&block)
-    capture_backend = StatsD::Instrument::Backends::CaptureBackend.new
-    with_capture_backend(capture_backend, &block)
-    capture_backend.collected_metrics
-  end
-
-  private
-
-  def with_capture_backend(backend)
-    if StatsD.legacy_singleton_client.backend.is_a?(StatsD::Instrument::Backends::CaptureBackend)
-      backend.parent = StatsD.legacy_singleton_client.backend
-    end
-
-    old_backend = StatsD.legacy_singleton_client.backend
-    begin
-      StatsD.legacy_singleton_client.backend = backend
-      yield
-    ensure
-      StatsD.legacy_singleton_client.backend = old_backend
-    end
-  end
 end

data/lib/statsd/instrument/matchers.rb

@@ -11,7 +11,6 @@ module StatsD::Instrument::Matchers
     histogram: :h,
     distribution: :d,
     set: :s,
-    key_value: :kv,
   }
 
   class Matcher

data/lib/statsd/instrument/railtie.rb

@@ -8,8 +8,4 @@ class StatsD::Instrument::Railtie < Rails::Railtie
   initializer 'statsd-instrument.use_rails_logger' do
     ::StatsD.logger = Rails.logger
   end
-
-  initializer 'statsd-instrument.setup_backend', after: 'statsd-instrument.use_rails_logger' do
-    ::StatsD.backend = ::StatsD::Instrument::Environment.default_backend
-  end
 end

data/lib/statsd/instrument/strict.rb

@@ -55,9 +55,7 @@ module StatsD
         super
       end
 
-      def service_check(name, status, tags: nil, no_prefix: false,
-        hostname: nil, timestamp: nil, message: nil)
-
+      def service_check(name, status, tags: nil, no_prefix: false, hostname: nil, timestamp: nil, message: nil)
         super
       end
 
@@ -81,11 +79,6 @@ module StatsD
         super
       end
 
-      def key_value(*)
-        raise NotImplementedError, "The key_value metric type will be removed " \
-          "from the next major version of statsd-instrument"
-      end
-
       private
 
       def check_block_or_numeric_value(value)
@@ -106,133 +99,30 @@ module StatsD
       end
     end
 
-    module VoidCollectMetric
-      protected
-
-      def collect_metric(type, name, value, sample_rate:, tags: nil, prefix:, metadata: nil)
-        super
-        StatsD::Instrument::VOID
-      end
-    end
-
     module StrictMetaprogramming
-      def statsd_measure(method, name, sample_rate: nil, tags: nil,
-        no_prefix: false, client: StatsD.singleton_client)
-
+      def statsd_measure(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil)
         check_method_and_metric_name(method, name)
-
-        # Unfortunately, we have to inline the new method implementation because we have to fix the
-        # Stats.measure call to not use the `as_dist` and `prefix` arguments.
-        add_to_method(method, name, :measure) do
-          define_method(method) do |*args, &block|
-            key = StatsD::Instrument.generate_metric_name(nil, name, self, *args)
-            client.measure(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) do
-              super(*args, &block)
-            end
-          end
-        end
+        super
       end
 
-      def statsd_distribution(method, name, sample_rate: nil, tags: nil,
-        no_prefix: false, client: StatsD.singleton_client)
-
+      def statsd_distribution(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil)
         check_method_and_metric_name(method, name)
-
-        # Unfortunately, we have to inline the new method implementation because we have to fix the
-        # Stats.distribution call to not use the `prefix` argument.
-
-        add_to_method(method, name, :distribution) do
-          define_method(method) do |*args, &block|
-            key = StatsD::Instrument.generate_metric_name(nil, name, self, *args)
-            client.distribution(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix) do
-              super(*args, &block)
-            end
-          end
-        end
+        super
       end
 
-      def statsd_count_success(method, name, sample_rate: nil, tags: nil,
-        no_prefix: false, client: StatsD.singleton_client)
-
+      def statsd_count_success(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil)
         check_method_and_metric_name(method, name)
-
-        # Unfortunately, we have to inline the new method implementation because we have to fix the
-        # Stats.increment call to not use the `prefix` argument.
-
-        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
-              end
-              result
-            ensure
-              suffix = truthiness == false ? 'failure' : 'success'
-              key = "#{StatsD::Instrument.generate_metric_name(nil, name, self, *args)}.#{suffix}"
-              client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
-            end
-          end
-        end
+        super
       end
 
-      def statsd_count_if(method, name, sample_rate: nil, tags: nil,
-        no_prefix: false, client: StatsD.singleton_client)
-
+      def statsd_count_if(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil)
         check_method_and_metric_name(method, name)
-
-        # Unfortunately, we have to inline the new method implementation because we have to fix the
-        # Stats.increment call to not use the `prefix` argument.
-
-        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
-                key = StatsD::Instrument.generate_metric_name(nil, name, self, *args)
-                client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
-              end
-            end
-          end
-        end
+        super
       end
 
-      def statsd_count(method, name, sample_rate: nil, tags: nil,
-        no_prefix: false, client: StatsD.singleton_client)
-
+      def statsd_count(method, name, sample_rate: nil, tags: nil, no_prefix: false, client: nil)
         check_method_and_metric_name(method, name)
-
-        # Unfortunately, we have to inline the new method implementation because we have to fix the
-        # Stats.increment call to not use the `prefix` argument.
-
-        add_to_method(method, name, :count) do
-          define_method(method) do |*args, &block|
-            key = StatsD::Instrument.generate_metric_name(nil, name, self, *args)
-            client.increment(key, sample_rate: sample_rate, tags: tags, no_prefix: no_prefix)
-            super(*args, &block)
-          end
-        end
+        super
       end
 
       private
@@ -250,6 +140,5 @@ module StatsD
   end
 end
 
-StatsD.singleton_class.prepend(StatsD::Instrument::Strict)
-StatsD::Instrument::LegacyClient.prepend(StatsD::Instrument::VoidCollectMetric)
+StatsD::Instrument::Client.prepend(StatsD::Instrument::Strict)
 StatsD::Instrument.prepend(StatsD::Instrument::StrictMetaprogramming)