statsd-instrument 3.0.0.pre1 → 3.1.0

data/lib/statsd/instrument/dogstatsd_datagram_builder.rb

@@ -1,75 +1,79 @@
 # frozen_string_literal: true
 
-# @note This class is part of the new Client implementation that is intended
-#   to become the new default in the next major release of this library.
-class StatsD::Instrument::DogStatsDDatagramBuilder < StatsD::Instrument::DatagramBuilder
-  unsupported_datagram_types :kv
+module StatsD
+  module Instrument
+    # @note This class is part of the new Client implementation that is intended
+    #   to become the new default in the next major release of this library.
+    class DogStatsDDatagramBuilder < StatsD::Instrument::DatagramBuilder
+      unsupported_datagram_types :kv
 
-  def self.datagram_class
-    StatsD::Instrument::DogStatsDDatagram
-  end
+      def self.datagram_class
+        StatsD::Instrument::DogStatsDDatagram
+      end
 
-  def latency_metric_type
-    :d
-  end
+      def latency_metric_type
+        :d
+      end
 
-  # Constricts an event datagram.
-  #
-  # @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.
-  # @return [String] The correctly formatted service check datagram
-  #
-  # @see https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/#events
-  def _e(title, text, timestamp: nil, hostname: nil, aggregation_key: nil, priority: nil,
-    source_type_name: nil, alert_type: nil, tags: nil)
+      # Constricts an event datagram.
+      #
+      # @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.
+      # @return [String] The correctly formatted service check datagram
+      #
+      # @see https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/#events
+      def _e(title, text, timestamp: nil, hostname: nil, aggregation_key: nil, priority: nil,
+        source_type_name: nil, alert_type: nil, tags: nil)
 
-    escaped_title = "#{@prefix}#{title}".gsub("\n", '\n')
-    escaped_text = text.gsub("\n", '\n')
-    tags = normalize_tags(tags) + default_tags
+        escaped_title = "#{@prefix}#{title}".gsub("\n", '\n')
+        escaped_text = text.gsub("\n", '\n')
+        tags = normalize_tags(tags) + default_tags
 
-    datagram = +"_e{#{escaped_title.length},#{escaped_text.length}}:#{escaped_title}|#{escaped_text}"
-    datagram << "|h:#{hostname}" if hostname
-    datagram << "|d:#{timestamp.to_i}" if timestamp
-    datagram << "|k:#{aggregation_key}" if aggregation_key
-    datagram << "|p:#{priority}" if priority
-    datagram << "|s:#{source_type_name}" if source_type_name
-    datagram << "|t:#{alert_type}" if alert_type
-    datagram << "|##{tags.join(',')}" unless tags.empty?
-    datagram
-  end
+        datagram = +"_e{#{escaped_title.length},#{escaped_text.length}}:#{escaped_title}|#{escaped_text}"
+        datagram << "|h:#{hostname}" if hostname
+        datagram << "|d:#{timestamp.to_i}" if timestamp
+        datagram << "|k:#{aggregation_key}" if aggregation_key
+        datagram << "|p:#{priority}" if priority
+        datagram << "|s:#{source_type_name}" if source_type_name
+        datagram << "|t:#{alert_type}" if alert_type
+        datagram << "|##{tags.join(",")}" unless tags.empty?
+        datagram
+      end
 
-  # Constricts a service check datagram.
-  #
-  # @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.
-  # @return [String] The correctly formatted service check datagram
-  #
-  # @see https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/#service-checks
-  def _sc(name, status, timestamp: nil, hostname: nil, tags: nil, message: nil)
-    status_number = status.is_a?(Integer) ? status : SERVICE_CHECK_STATUS_VALUES.fetch(status.to_sym)
-    tags = normalize_tags(tags) + default_tags
+      # Constricts a service check datagram.
+      #
+      # @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.
+      # @return [String] The correctly formatted service check datagram
+      #
+      # @see https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/#service-checks
+      def _sc(name, status, timestamp: nil, hostname: nil, tags: nil, message: nil)
+        status_number = status.is_a?(Integer) ? status : SERVICE_CHECK_STATUS_VALUES.fetch(status.to_sym)
+        tags = normalize_tags(tags) + default_tags
 
-    datagram = +"_sc|#{@prefix}#{normalize_name(name)}|#{status_number}"
-    datagram << "|h:#{hostname}" if hostname
-    datagram << "|d:#{timestamp.to_i}" if timestamp
-    datagram << "|##{tags.join(',')}" unless tags.empty?
-    datagram << "|m:#{normalize_name(message)}" if message
-    datagram
-  end
+        datagram = +"_sc|#{@prefix}#{normalize_name(name)}|#{status_number}"
+        datagram << "|h:#{hostname}" if hostname
+        datagram << "|d:#{timestamp.to_i}" if timestamp
+        datagram << "|##{tags.join(",")}" unless tags.empty?
+        datagram << "|m:#{normalize_name(message)}" if message
+        datagram
+      end
 
-  SERVICE_CHECK_STATUS_VALUES = { ok: 0, warning: 1, critical: 2, unknown: 3 }.freeze
-  private_constant :SERVICE_CHECK_STATUS_VALUES
+      SERVICE_CHECK_STATUS_VALUES = { ok: 0, warning: 1, critical: 2, unknown: 3 }.freeze
+      private_constant :SERVICE_CHECK_STATUS_VALUES
+    end
+  end
 end

data/lib/statsd/instrument/environment.rb

@@ -1,94 +1,105 @@
 # frozen_string_literal: true
 
-# The environment module is used to detect, and initialize the environment in
-# which this library is active. It will use different default values based on the environment.
-class StatsD::Instrument::Environment
-  class << self
-    def current
-      @current ||= StatsD::Instrument::Environment.new(ENV)
-    end
+module StatsD
+  module Instrument
+    # The environment module is used to detect, and initialize the environment in
+    # which this library is active. It will use different default values based on the environment.
+    class Environment
+      class << self
+        def current
+          @current ||= StatsD::Instrument::Environment.new(ENV)
+        end
 
-    # Detects the current environment, either by asking Rails, or by inspecting environment variables.
-    #
-    # - Within a Rails application, <tt>Rails.env</tt> is used.
-    # - It will check the following environment variables in order: <tt>RAILS_ENV</tt>, <tt>RACK_ENV</tt>, <tt>ENV</tt>.
-    # - If none of these are set, it will return <tt>development</tt>
-    #
-    # @return [String] The detected environment.
-    def environment
-      current.environment
-    end
+        # @deprecated For backwards compatibility only. Use {StatsD::Instrument::Environment#environment}
+        #   through {StatsD::Instrument::Environment.current} instead.
+        def environment
+          current.environment
+        end
 
-    # Sets default values for sample rate and logger.
-    #
-    # - Default sample rate is set to the value in the STATSD_SAMPLE_RATE environment variable,
-    #   or 1.0 otherwise. See {StatsD#default_sample_rate}
-    # - {StatsD#logger} is set to a logger that send output to stderr.
-    #
-    # If you are including this library inside a Rails environment, additional initialization will
-    # be done as part of the {StatsD::Instrument::Railtie}.
-    #
-    # @return [void]
-    def setup
-      StatsD.logger = Logger.new($stderr)
-    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,
+        #   or 1.0 otherwise. See {StatsD#default_sample_rate}
+        # - {StatsD#logger} is set to a logger that send output to stderr.
+        #
+        # If you are including this library inside a Rails environment, additional initialization will
+        # be done as part of the {StatsD::Instrument::Railtie}.
+        #
+        # @return [void]
+        def setup
+          StatsD.logger = Logger.new($stderr)
+        end
+      end
 
-  attr_reader :env
+      attr_reader :env
 
-  def initialize(env)
-    @env = env
-  end
+      def initialize(env)
+        @env = env
+      end
 
-  # Detects the current environment, either by asking Rails, or by inspecting environment variables.
-  #
-  # - Within a Rails application, <tt>Rails.env</tt> is used.
-  # - It will check the following environment variables in order: <tt>RAILS_ENV</tt>, <tt>RACK_ENV</tt>, <tt>ENV</tt>.
-  # - If none of these are set, it will return <tt>development</tt>
-  #
-  # @return [String] The detected environment.
-  def environment
-    if env['STATSD_ENV']
-      env['STATSD_ENV']
-    elsif defined?(Rails) && Rails.respond_to?(:env)
-      Rails.env.to_s
-    else
-      env['RAILS_ENV'] || env['RACK_ENV'] || env['ENV'] || 'development'
-    end
-  end
+      # Detects the current environment, either by asking Rails, or by inspecting environment variables.
+      #
+      # - It will prefer the value set in <tt>ENV['STATSD_ENV']</tt>
+      # - Within a Rails application, <tt>Rails.env</tt> is used.
+      # - It will check the following environment variables in order:
+      #   - <tt>RAILS_ENV</tt>,
+      #   - <tt>RACK_ENV</tt>
+      #   - <tt>ENV</tt>.
+      # - If none of these are set, it will return <tt>development</tt>
+      #
+      # @return [String] The detected environment.
+      def environment
+        if env["STATSD_ENV"]
+          env["STATSD_ENV"]
+        elsif defined?(Rails) && Rails.respond_to?(:env)
+          Rails.env.to_s
+        else
+          env["RAILS_ENV"] || env["RACK_ENV"] || env["ENV"] || "development"
+        end
+      end
 
-  def statsd_implementation
-    env.fetch('STATSD_IMPLEMENTATION', 'datadog')
-  end
+      def statsd_implementation
+        env.fetch("STATSD_IMPLEMENTATION", "datadog")
+      end
 
-  def statsd_sample_rate
-    env.fetch('STATSD_SAMPLE_RATE', 1.0).to_f
-  end
+      def statsd_sample_rate
+        env.fetch("STATSD_SAMPLE_RATE", 1.0).to_f
+      end
 
-  def statsd_prefix
-    env.fetch('STATSD_PREFIX', nil)
-  end
+      def statsd_prefix
+        env.fetch("STATSD_PREFIX", nil)
+      end
 
-  def statsd_addr
-    env.fetch('STATSD_ADDR', 'localhost:8125')
-  end
+      def statsd_addr
+        env.fetch("STATSD_ADDR", "localhost:8125")
+      end
 
-  def statsd_default_tags
-    env.key?('STATSD_DEFAULT_TAGS') ? env.fetch('STATSD_DEFAULT_TAGS').split(',') : nil
-  end
+      def statsd_default_tags
+        env.key?("STATSD_DEFAULT_TAGS") ? env.fetch("STATSD_DEFAULT_TAGS").split(",") : nil
+      end
 
-  def client
-    StatsD::Instrument::Client.from_env(self)
-  end
+      def statsd_flush_interval
+        Float(env.fetch("STATSD_FLUSH_INTERVAL", 1.0))
+      end
+
+      def client
+        StatsD::Instrument::Client.from_env(self)
+      end
 
-  def default_sink_for_environment
-    case environment
-    when 'production', 'staging'
-      StatsD::Instrument::UDPSink.for_addr(statsd_addr)
-    when 'test'
-      StatsD::Instrument::NullSink.new
-    else
-      StatsD::Instrument::LogSink.new(StatsD.logger)
+      def default_sink_for_environment
+        case environment
+        when "production", "staging"
+          if statsd_flush_interval > 0.0
+            StatsD::Instrument::BatchedUDPSink.for_addr(statsd_addr, flush_interval: statsd_flush_interval)
+          else
+            StatsD::Instrument::UDPSink.for_addr(statsd_addr)
+          end
+        when "test"
+          StatsD::Instrument::NullSink.new
+        else
+          StatsD::Instrument::LogSink.new(StatsD.logger)
+        end
+      end
     end
   end
 end

data/lib/statsd/instrument/expectation.rb

@@ -1,119 +1,119 @@
 # frozen_string_literal: true
 
-# @private
-class StatsD::Instrument::Expectation
-  class << self
-    def increment(name, **options)
-      new(type: :c, name: name, **options)
-    end
-
-    def measure(name, **options)
-      new(type: :ms, name: name, **options)
-    end
+module StatsD
+  module Instrument
+    # @private
+    class Expectation
+      class << self
+        def increment(name, value = nil, **options)
+          new(type: :c, name: name, value: value, **options)
+        end
 
-    def gauge(name, **options)
-      new(type: :g, name: name, **options)
-    end
+        def measure(name, value = nil, **options)
+          new(type: :ms, name: name, value: value, **options)
+        end
 
-    def set(name, **options)
-      new(type: :s, name: name, **options)
-    end
+        def gauge(name, value = nil, **options)
+          new(type: :g, name: name, value: value, **options)
+        end
 
-    def key_value(name, **options)
-      new(type: :kv, name: name, **options)
-    end
+        def set(name, value = nil, **options)
+          new(type: :s, name: name, value: value, **options)
+        end
 
-    def distribution(name, **options)
-      new(type: :d, name: name, **options)
-    end
+        def distribution(name, value = nil, **options)
+          new(type: :d, name: name, value: value, **options)
+        end
 
-    def histogram(name, **options)
-      new(type: :h, name: name, **options)
-    end
-  end
+        def histogram(name, value = nil, **options)
+          new(type: :h, name: name, value: value, **options)
+        end
+      end
 
-  attr_accessor :times, :type, :name, :value, :sample_rate, :tags
+      attr_accessor :times, :type, :name, :value, :sample_rate, :tags
 
-  def initialize(client: StatsD.singleton_client, type:, name:, value: nil,
-    sample_rate: nil, tags: nil, no_prefix: false, times: 1)
+      def initialize(client: StatsD.singleton_client, type:, name:, value: nil,
+        sample_rate: nil, tags: nil, no_prefix: false, times: 1)
 
-    @type = type
-    @name = client.prefix ? "#{client.prefix}.#{name}" : name unless no_prefix
-    @value = normalized_value_for_type(type, value) if value
-    @sample_rate = sample_rate
-    @tags = normalize_tags(tags)
-    @times = times
-  end
+        @type = type
+        @name = no_prefix || !client.prefix ? name : "#{client.prefix}.#{name}"
+        @value = normalized_value_for_type(type, value) if value
+        @sample_rate = sample_rate
+        @tags = normalize_tags(tags)
+        @times = times
+      end
 
-  def normalized_value_for_type(type, value)
-    case type
-    when :c then Integer(value)
-    when :g, :h, :d, :kv, :ms then Float(value)
-    when :s then String(value)
-    else value
-    end
-  end
+      def normalized_value_for_type(type, value)
+        case type
+        when :c then Integer(value)
+        when :g, :h, :d, :kv, :ms then Float(value)
+        when :s then String(value)
+        else value
+        end
+      end
 
-  def matches(actual_metric)
-    return false if sample_rate && sample_rate != actual_metric.sample_rate
-    return false if value && value != normalized_value_for_type(actual_metric.type, actual_metric.value)
+      def matches(actual_metric)
+        return false if sample_rate && sample_rate != actual_metric.sample_rate
+        return false if value && value != normalized_value_for_type(actual_metric.type, actual_metric.value)
 
-    if tags
-      expected_tags = Set.new(tags)
-      actual_tags = Set.new(actual_metric.tags)
-      return expected_tags.subset?(actual_tags)
-    end
-    true
-  end
+        if tags
+          expected_tags = Set.new(tags)
+          actual_tags = Set.new(actual_metric.tags)
+          return expected_tags.subset?(actual_tags)
+        end
+        true
+      end
 
-  def to_s
-    str = +"#{name}:#{value || '<anything>'}|#{type}"
-    str << "|@#{sample_rate}" if sample_rate
-    str << "|#" << tags.join(',') if tags
-    str << " (expected #{times} times)" if times > 1
-    str
-  end
+      def to_s
+        str = +"#{name}:#{value || "<anything>"}|#{type}"
+        str << "|@#{sample_rate}" if sample_rate
+        str << "|#" << tags.join(",") if tags
+        str << " (expected #{times} times)" if times > 1
+        str
+      end
 
-  def inspect
-    "#<StatsD::Instrument::Expectation:\"#{self}\">"
-  end
+      def inspect
+        "#<StatsD::Instrument::Expectation:\"#{self}\">"
+      end
 
-  private
+      private
 
-  # Needed for normalize_tags
-  unless Regexp.method_defined?(:match?) # for ruby 2.3
-    module RubyBackports
-      refine Regexp do
-        def match?(str)
-          (self =~ str) != nil
+      # Needed for normalize_tags
+      unless Regexp.method_defined?(:match?) # for ruby 2.3
+        module RubyBackports
+          refine Regexp do
+            def match?(str)
+              (self =~ str) != nil
+            end
+          end
         end
+
+        using(RubyBackports)
       end
-    end
 
-    using RubyBackports
-  end
+      # @private
+      #
+      # Utility function to convert tags to the canonical form.
+      #
+      # - Tags specified as key value pairs will be converted into an array
+      # - Tags are normalized to remove unsupported characters
+      #
+      # @param tags [Array<String>, Hash<String, String>, nil] Tags specified in any form.
+      # @return [Array<String>, nil] the list of tags in canonical form.
+      #
+      # @todo We should delegate this to thje datagram builder of the current client,
+      #   to ensure that this logic matches the logic of the active datagram builder.
+      def normalize_tags(tags)
+        return [] unless tags
+        tags = tags.map { |k, v| "#{k}:#{v}" } if tags.is_a?(Hash)
+
+        # Fast path when no string replacement is needed
+        return tags unless tags.any? { |tag| /[|,]/.match?(tag) }
+        tags.map { |tag| tag.tr("|,", "") }
+      end
+    end
 
-  # @private
-  #
-  # Utility function to convert tags to the canonical form.
-  #
-  # - Tags specified as key value pairs will be converted into an array
-  # - Tags are normalized to remove unsupported characters
-  #
-  # @param tags [Array<String>, Hash<String, String>, nil] Tags specified in any form.
-  # @return [Array<String>, nil] the list of tags in canonical form.
-  #
-  # @todo We should delegate this to thje datagram builder of the current client,
-  #   to ensure that this logic matches the logic of the active datagram builder.
-  def normalize_tags(tags)
-    return [] unless tags
-    tags = tags.map { |k, v| "#{k}:#{v}" } if tags.is_a?(Hash)
-
-    # Fast path when no string replacement is needed
-    return tags unless tags.any? { |tag| /[|,]/.match?(tag) }
-    tags.map { |tag| tag.tr('|,', '') }
+    # For backwards compatibility
+    MetricExpectation = Expectation
   end
 end
-
-# For backwards compatibility
-StatsD::Instrument::MetricExpectation = StatsD::Instrument::Expectation