dogstatsd-ruby 4.8.2 → 5.4.0

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,85 @@ 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 (multi-thread only)
+    # @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
     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,
+
+      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
 
-      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,
+      )
     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 +152,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 +167,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 +183,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 +200,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 +215,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 +229,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)
@@ -217,6 +246,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 +261,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 +281,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 +302,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.
@@ -290,17 +322,25 @@ module Datadog
     # @option opts [String, nil] :priority ('normal') Can be "normal" or "low"
     # @option opts [String, nil] :source_type_name (nil) Assign a source type to the event
     # @option opts [String, nil] :alert_type ('info') Can be "error", "warning", "info" or "success".
+    # @option opts [Boolean, false] :truncate_if_too_long (false) Truncate the event if it is too long
     # @option opts [Array<String>] :tags tags to be added to every metric
     # @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|
@@ -308,50 +348,66 @@ 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
+      if sample_rate == 1 || opts[:pre_sampled] || rand <= sample_rate
         full_stat = serializer.to_stat(stat, delta, type, tags: opts[:tags], sample_rate: sample_rate)
 
-        send_stat(full_stat)
-      end
-    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.2
+  version: 5.4.0
 platform: ruby
 authors:
 - Rein Henrichs
-autorequire:
+- Karim Bogtob
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-16 00:00:00.000000000 Z
+date: 2022-03-01 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.2/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/4.8.2
-  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v4.8.2
-post_install_message:
+  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v5.4.0/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/5.4.0
+  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v5.4.0
+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,15 @@ 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
-signing_key:
+rubygems_version: 3.2.22
+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