dogstatsd-ruby 4.8.3 → 5.6.1

data/lib/datadog/statsd.rb

@@ -5,8 +5,13 @@ require_relative 'statsd/version'
 require_relative 'statsd/telemetry'
 require_relative 'statsd/udp_connection'
 require_relative 'statsd/uds_connection'
-require_relative 'statsd/batch'
+require_relative 'statsd/connection_cfg'
+require_relative 'statsd/message_buffer'
 require_relative 'statsd/serialization'
+require_relative 'statsd/sender'
+require_relative 'statsd/single_thread_sender'
+require_relative 'statsd/forwarder'
+require_relative 'statsd/timer'
 
 # = Datadog::Statsd: A DogStatsd client (https://www.datadoghq.com)
 #
@@ -26,13 +31,23 @@ require_relative 'statsd/serialization'
 #   statsd = Datadog::Statsd.new 'localhost', 8125, tags: 'tag1:true'
 module Datadog
   class Statsd
+    class Error < StandardError
+    end
+
     OK       = 0
     WARNING  = 1
     CRITICAL = 2
     UNKNOWN  = 3
 
-    DEFAULT_BUFFER_SIZE = 8 * 1_024
+    UDP_DEFAULT_BUFFER_SIZE = 1_432
+    UDS_DEFAULT_BUFFER_SIZE = 8_192
+    DEFAULT_BUFFER_POOL_SIZE = Float::INFINITY
+
+    UDP_DEFAULT_SENDER_QUEUE_SIZE = 2048
+    UDS_DEFAULT_SENDER_QUEUE_SIZE = 512
+
     MAX_EVENT_SIZE = 8 * 1_024
+
     # minimum flush interval for the telemetry in seconds
     DEFAULT_TELEMETRY_FLUSH_INTERVAL = 10
 
@@ -51,77 +66,89 @@ module Datadog
       serializer.global_tags
     end
 
-    # Buffer containing the statsd message before they are sent in batch
-    attr_reader :buffer
-
-    # Maximum buffer size in bytes before it is flushed
-    attr_reader :max_buffer_bytes
-
     # Default sample rate
     attr_reader :sample_rate
 
-    # Connection
-    attr_reader :connection
-
     # @param [String] host your statsd host
     # @param [Integer] port your statsd port
     # @option [String] namespace set a namespace to be prepended to every metric name
     # @option [Array<String>|Hash] tags tags to be added to every metric
     # @option [Logger] logger for debugging
-    # @option [Integer] max_buffer_bytes max bytes to buffer when using #batch
+    # @option [Integer] buffer_max_payload_size max bytes to buffer
+    # @option [Integer] buffer_max_pool_size max messages to buffer
+    # @option [Integer] sender_queue_size size of the sender queue in number of buffers
+    # @option [Numeric] buffer_flush_interval interval in second to flush buffer
     # @option [String] socket_path unix socket path
     # @option [Float] default sample rate if not overridden
+    # @option [Boolean] single_thread flushes the metrics on the main thread instead of in a companion thread
+    # @option [Boolean] delay_serialization delays stat serialization
     def initialize(
       host = nil,
       port = nil,
+      socket_path: nil,
+
       namespace: nil,
       tags: nil,
-      max_buffer_bytes: DEFAULT_BUFFER_SIZE,
-      socket_path: nil,
-      logger: nil,
       sample_rate: nil,
-      disable_telemetry: false,
+
+      buffer_max_payload_size: nil,
+      buffer_max_pool_size: nil,
+      buffer_overflowing_stategy: :drop,
+      buffer_flush_interval: nil,
+
+      sender_queue_size: nil,
+
+      logger: nil,
+
+      single_thread: false,
+      delay_serialization: false,
+
+      telemetry_enable: true,
       telemetry_flush_interval: DEFAULT_TELEMETRY_FLUSH_INTERVAL
     )
       unless tags.nil? || tags.is_a?(Array) || tags.is_a?(Hash)
-        raise ArgumentError, 'tags must be a Array<String> or a Hash'
+        raise ArgumentError, 'tags must be an array of string tags or a Hash'
       end
 
       @namespace = namespace
       @prefix = @namespace ? "#{@namespace}.".freeze : nil
-
       @serializer = Serialization::Serializer.new(prefix: @prefix, global_tags: tags)
+      @sample_rate = sample_rate
+      @delay_serialization = delay_serialization
 
-      transport_type = socket_path.nil? ? :udp : :uds
+      @forwarder = Forwarder.new(
+        connection_cfg: ConnectionCfg.new(
+          host: host,
+          port: port,
+          socket_path: socket_path,
+        ),
 
-      @telemetry = Telemetry.new(disable_telemetry, telemetry_flush_interval,
         global_tags: tags,
-        transport_type: transport_type
-      )
+        logger: logger,
 
-      @connection = case transport_type
-                    when :udp
-                      UDPConnection.new(host, port, logger, telemetry)
-                    when :uds
-                      UDSConnection.new(socket_path, logger, telemetry)
-                    end
+        single_thread: single_thread,
 
-      @logger = logger
+        buffer_max_payload_size: buffer_max_payload_size,
+        buffer_max_pool_size: buffer_max_pool_size,
+        buffer_overflowing_stategy: buffer_overflowing_stategy,
+        buffer_flush_interval: buffer_flush_interval,
 
-      @sample_rate = sample_rate
+        sender_queue_size: sender_queue_size,
 
-      # we reduce max_buffer_bytes by a the rough estimate of the telemetry payload
-      @batch = Batch.new(connection, (max_buffer_bytes - telemetry.estimate_max_size))
+        telemetry_flush_interval: telemetry_enable ? telemetry_flush_interval : nil,
+        serializer: serializer
+      )
     end
 
     # yield a new instance to a block and close it when done
     # for short-term use-cases that don't want to close the socket manually
-    def self.open(*args)
-      instance = new(*args)
+    # TODO: replace with ... once we are on ruby 2.7
+    def self.open(*args, **kwargs)
+      instance = new(*args, **kwargs)
 
       yield instance
     ensure
-      instance.close
+      instance.close if instance
     end
 
     # Sends an increment (count = 1) for the given stat to the statsd server.
@@ -129,6 +156,7 @@ module Datadog
     # @param [String] stat stat name
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @option opts [Numeric] :by increment value, default 1
     # @see #count
@@ -143,6 +171,7 @@ module Datadog
     # @param [String] stat stat name
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @option opts [Numeric] :by decrement value, default 1
     # @see #count
@@ -158,13 +187,14 @@ module Datadog
     # @param [Integer] count count
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     def count(stat, count, opts = EMPTY_OPTIONS)
       opts = { sample_rate: opts } if opts.is_a?(Numeric)
       send_stats(stat, count, COUNTER_TYPE, opts)
     end
 
-    # Sends an arbitary gauge value for the given stat to the statsd server.
+    # Sends an arbitrary gauge value for the given stat to the statsd server.
     #
     # This is useful for recording things like available disk space,
     # memory usage, and the like, which have different semantics than
@@ -174,6 +204,7 @@ module Datadog
     # @param [Numeric] value gauge value.
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @example Report the current user count:
     #   $statsd.gauge('user.count', User.count)
@@ -188,6 +219,7 @@ module Datadog
     # @param [Numeric] value histogram value.
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @example Report the current user count:
     #   $statsd.histogram('user.count', User.count)
@@ -201,6 +233,7 @@ module Datadog
     # @param [Numeric] value distribution value.
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @example Report the current user count:
     #   $statsd.distribution('user.count', User.count)
@@ -208,6 +241,26 @@ module Datadog
       send_stats(stat, value, DISTRIBUTION_TYPE, opts)
     end
 
+    # Reports execution time of the provided block as a distribution.
+    #
+    # If the block fails, the stat is still reported, then the error
+    # is reraised
+    #
+    # @param [String] stat stat name.
+    # @param [Numeric] value distribution value.
+    # @param [Hash] opts the options to create the metric with
+    # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Array<String>] :tags An array of tags
+    # @example Report the time (in ms) taken to activate an account
+    #   $statsd.distribution_time('account.activate') { @account.activate! }
+    def distribution_time(stat, opts = EMPTY_OPTIONS)
+      opts = { sample_rate: opts } if opts.is_a?(Numeric)
+      start = now
+      yield
+    ensure
+      distribution(stat, ((now - start) * 1000).round, opts)
+    end
+
     # Sends a timing (in ms) for the given stat to the statsd server. The
     # sample_rate determines what percentage of the time this report is sent. The
     # statsd server then uses the sample_rate to correctly track the average
@@ -217,6 +270,7 @@ module Datadog
     # @param [Integer] ms timing in milliseconds
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     def timing(stat, ms, opts = EMPTY_OPTIONS)
       opts = { sample_rate: opts } if opts.is_a?(Numeric)
@@ -231,6 +285,7 @@ module Datadog
     # @param [String] stat stat name
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @yield The operation to be timed
     # @see #timing
@@ -250,6 +305,7 @@ module Datadog
     # @param [Numeric] value set value.
     # @param [Hash] opts the options to create the metric with
     # @option opts [Numeric] :sample_rate sample rate, 1 for always
+    # @option opts [Boolean] :pre_sampled If true, the client assumes the caller has already sampled metrics at :sample_rate, and doesn't perform sampling.
     # @option opts [Array<String>] :tags An array of tags
     # @example Record a unique visitory by id:
     #   $statsd.set('visitors.uniques', User.id)
@@ -270,9 +326,9 @@ module Datadog
     # @example Report a critical service check status
     #   $statsd.service_check('my.service.check', Statsd::CRITICAL, :tags=>['urgent'])
     def service_check(name, status, opts = EMPTY_OPTIONS)
-      telemetry.sent(service_checks: 1)
+      telemetry.sent(service_checks: 1) if telemetry
 
-      send_stat(serializer.to_service_check(name, status, opts))
+      forwarder.send_message(serializer.to_service_check(name, status, opts))
     end
 
     # This end point allows you to post events to the stream. You can tag them, set priority and even aggregate them with other events.
@@ -295,13 +351,20 @@ module Datadog
     # @example Report an awful event:
     #   $statsd.event('Something terrible happened', 'The end is near if we do nothing', :alert_type=>'warning', :tags=>['end_of_times','urgent'])
     def event(title, text, opts = EMPTY_OPTIONS)
-      telemetry.sent(events: 1)
+      telemetry.sent(events: 1) if telemetry
 
-      send_stat(serializer.to_event(title, text, opts))
+      forwarder.send_message(serializer.to_event(title, text, opts))
     end
 
-    # Send several metrics in the same UDP Packet
-    # They will be buffered and flushed when the block finishes
+    # Send several metrics in the same packet.
+    # They will be buffered and flushed when the block finishes.
+    #
+    # This method exists for compatibility with v4.x versions, it is not needed
+    # anymore since the batching is now automatically done internally.
+    # It also means that an automatic flush could occur if the buffer is filled
+    # during the execution of the batch block.
+    #
+    # This method is DEPRECATED and will be removed in future v6.x API.
     #
     # @example Send several metrics in one packet:
     #   $statsd.batch do |s|
@@ -309,50 +372,71 @@ module Datadog
     #      s.increment('page.views')
     #    end
     def batch
-      @batch.open do
-        yield self
-      end
+      yield self
+      flush(sync: true)
     end
 
     # Close the underlying socket
-    def close
-      connection.close
+    #
+    # @param [Boolean, true] flush Should we flush the metrics before closing
+    def close(flush: true)
+      flush(sync: true) if flush
+      forwarder.close
+    end
+
+    def sync_with_outbound_io
+      forwarder.sync_with_outbound_io
+    end
+
+    # Flush the buffer into the connection
+    def flush(flush_telemetry: false, sync: false)
+      forwarder.flush(flush_telemetry: flush_telemetry, sync: sync)
+    end
+
+    def telemetry
+      forwarder.telemetry
+    end
+
+    def host
+      forwarder.host
+    end
+
+    def port
+      forwarder.port
+    end
+
+    def socket_path
+      forwarder.socket_path
+    end
+
+    def transport_type
+      forwarder.transport_type
     end
 
     private
     attr_reader :serializer
-    attr_reader :telemetry
+    attr_reader :forwarder
 
-    PROCESS_TIME_SUPPORTED = (RUBY_VERSION >= '2.1.0')
     EMPTY_OPTIONS = {}.freeze
 
-    if PROCESS_TIME_SUPPORTED
-      def now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-    else
-      def now
-        Time.now.to_f
-      end
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     def send_stats(stat, delta, type, opts = EMPTY_OPTIONS)
-      telemetry.sent(metrics: 1)
+      telemetry.sent(metrics: 1) if telemetry
 
       sample_rate = opts[:sample_rate] || @sample_rate || 1
 
-      if sample_rate == 1 || rand <= sample_rate
-        full_stat = serializer.to_stat(stat, delta, type, tags: opts[:tags], sample_rate: sample_rate)
-
-        send_stat(full_stat)
-      end
-    end
+      if sample_rate == 1 || opts[:pre_sampled] || rand <= sample_rate
+        full_stat =
+          if @delay_serialization
+            [[stat, delta, type], {tags: opts[:tags], sample_rate: sample_rate}]
+          else
+            serializer.to_stat(stat, delta, type, tags: opts[:tags], sample_rate: sample_rate)
+          end
 
-    def send_stat(message)
-      if @batch.open?
-        @batch.add(message)
-      else
-        @connection.write(message)
+        forwarder.send_message(full_stat)
       end
     end
   end

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: dogstatsd-ruby
 version: !ruby/object:Gem::Version
-  version: 4.8.3
+  version: 5.6.1
 platform: ruby
 authors:
 - Rein Henrichs
+- Karim Bogtob
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-22 00:00:00.000000000 Z
+date: 2023-09-07 00:00:00.000000000 Z
 dependencies: []
-description: A Ruby DogStastd client
+description: A Ruby DogStatsd client
 email: code@datadoghq.com
 executables: []
 extensions: []
@@ -21,15 +22,20 @@ files:
 - LICENSE.txt
 - README.md
 - lib/datadog/statsd.rb
-- lib/datadog/statsd/batch.rb
 - lib/datadog/statsd/connection.rb
+- lib/datadog/statsd/connection_cfg.rb
+- lib/datadog/statsd/forwarder.rb
+- lib/datadog/statsd/message_buffer.rb
+- lib/datadog/statsd/sender.rb
 - lib/datadog/statsd/serialization.rb
 - lib/datadog/statsd/serialization/event_serializer.rb
 - lib/datadog/statsd/serialization/serializer.rb
 - lib/datadog/statsd/serialization/service_check_serializer.rb
 - lib/datadog/statsd/serialization/stat_serializer.rb
 - lib/datadog/statsd/serialization/tag_serializer.rb
+- lib/datadog/statsd/single_thread_sender.rb
 - lib/datadog/statsd/telemetry.rb
+- lib/datadog/statsd/timer.rb
 - lib/datadog/statsd/udp_connection.rb
 - lib/datadog/statsd/uds_connection.rb
 - lib/datadog/statsd/version.rb
@@ -38,10 +44,14 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/DataDog/dogstatsd-ruby/issues
-  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v4.8.3/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/4.8.3
-  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v4.8.3
-post_install_message:
+  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v5.6.1/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/5.6.1
+  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v5.6.1
+post_install_message: |2+
+
+  If you are upgrading from v4.x of the dogstatsd-ruby library, note the major change to the threading model:
+  https://github.com/DataDog/dogstatsd-ruby#migrating-from-v4x-to-v5x
+
 rdoc_options: []
 require_paths:
 - lib
@@ -49,16 +59,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project:
-rubygems_version: 2.7.10
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: A Ruby DogStatsd client
 test_files: []
+...

data/lib/datadog/statsd/batch.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-module Datadog
-  class Statsd
-    class Batch
-      def initialize(connection, max_buffer_bytes)
-        @connection = connection
-        @max_buffer_bytes = max_buffer_bytes
-        @depth = 0
-        reset
-      end
-
-      def open
-        @depth += 1
-
-        yield
-      ensure
-        @depth -= 1
-        flush if !open?
-      end
-
-      def open?
-        @depth > 0
-      end
-
-      def add(message)
-        message_bytes = message.bytesize
-
-        unless @buffer_bytes == 0
-          if @buffer_bytes + 1 + message_bytes >= @max_buffer_bytes
-            flush
-          else
-            @buffer << "\n"
-            @buffer_bytes += 1
-          end
-        end
-
-        @buffer << message
-        @buffer_bytes += message_bytes
-      end
-
-      def flush
-        return if @buffer_bytes == 0
-        @connection.write(@buffer)
-        reset
-      end
-
-      private
-
-      def reset
-        @buffer = String.new
-        @buffer_bytes = 0
-      end
-    end
-  end
-end