dogstatsd-ruby 4.8.1 → 5.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9657b1d27b4367d96457d57faaed215c8ed07343d5d0803549b9078bd9713fbe
-  data.tar.gz: ad7c7fb2638790a3fe0300c23d81e87c33dc0fa9f7d496bc164e148e67e18992
+  metadata.gz: 8069234fd7b43382f85606fa53a858c502025937168c275347a0ec5552f566fc
+  data.tar.gz: 81945812b5810033cc2f511364d3a962a1c932e771d4faa2a4366391fe447414
 SHA512:
-  metadata.gz: a6b5a0217129bdb2bb2e7da14711395775b2d8897f74ffd8bd9925dc6a5b8dd3503fe7ee8427e1840617197de251d5b46abe99284cf8df41928ad9b69399c814
-  data.tar.gz: c129849337907f82ddbeba16484371e18aa1f155d5fac46b1a62be31b178ceddcb3c47d04bf6ce59b1ea485770050918377dec4422d78f8b2c0d0e894794182f
+  metadata.gz: 5b589a6f599dc547f980587c8902eed4012b4d627fd6abe28c21829f299ee695e33f38f2fe386fb3d9f7828327134f69831f0365ee4ff16d84b7de3830178081
+  data.tar.gz: 05cb95baf12dbe3b2f17c835c8278f32198ce21d2d66ca14b4714aa90a12dd6a4976c48e9d9f326ca51cc66d95c83dd269e55aa6fe6e08409c61cec8866a9798

data/README.md

@@ -22,22 +22,81 @@ To instantiate a DogStatsd client:
 # Import the library
 require 'datadog/statsd'
 
-# Create a DogStatsD client instance.
+# Create a DogStatsD client instance
 statsd = Datadog::Statsd.new('localhost', 8125)
+# ...
+# release resources used by the client instance
+statsd.close()
 ```
 Or if you want to connect over Unix Domain Socket:
 ```ruby
 # Connection over Unix Domain Socket
 statsd = Datadog::Statsd.new(socket_path: '/path/to/socket/file')
+# ...
+# release resources used by the client instance
+statsd.close()
 ```
 
-Find a list of all the available options for your DogStatsD Client in the [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd) or in the [Datadog public DogStatsD documentation](https://docs.datadoghq.com/developers/dogstatsd/?tab=ruby#client-instantiation-parameters).
+Find a list of all the available options for your DogStatsD Client in the [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd) or in the [Datadog public DogStatsD documentation](https://docs.datadoghq.com/developers/dogstatsd/?code-lang=ruby#client-instantiation-parameters).
+
+### Migrating from v4.x to v5.x
+
+If you are already using DogStatsD-ruby v4.x and you want to migrate to a version v5.x, the major
+change concerning you is the new [threading model](#threading-model):
+
+In practice, it means two things:
+
+1. Now that the client is buffering metrics before sending them, you have to call `Datadog::Statsd#flush(sync: true)` if you want synchronous behavior. In most cases, this is not needed, as the sender thread will automatically flush the buffered metrics if the buffer gets full or when you are closing the instance.
+
+2. You have to make sure you are either:
+
+  * Using a singleton instance of the DogStatsD client instead of creating a new instance whenever you need one; this will let the buffering mechanism flush metrics regularly
+  * Or properly disposing of the DogStatsD client instance when it is not needed anymore using the method `Datadog::Statsd#close`
+
+If you have issues with the sender thread or the buffering mode, you can instantiate a client that behaves exactly as in v4.x (i.e. no sender thread and flush on every metric submission):
+
+```ruby
+# Create a DogStatsD client instance using UDP
+statsd = Datadog::Statsd.new('localhost', 8125, single_thread: true, buffer_max_pool_size: 1)
+# ...
+statsd.close()
+```
+
+or
+
+```ruby
+# Create a DogStatsD client instance using UDS
+statsd = Datadog::Statsd.new(socket_path: '/path/to/socket/file', single_thread: true, buffer_max_pool_size: 1)
+# ...
+statsd.close()
+```
+
+### v5.x Common Pitfalls
+
+Version v5.x of `dogstatsd-ruby` is using a sender thread for flushing. This provides better performance, but you need to consider the following pitfalls:
+
+1. Applications that use `fork` after having created the dogstatsd instance: the child process will automatically spawn a new sender thread to flush metrics.
+
+2. Applications that create multiple instances of the client without closing them: it is important to `#close` all instances to free the thread and the socket they are using otherwise you will leak those resources.
+
+If you are using [Sidekiq](https://github.com/mperham/sidekiq), please make sure to close the client instances that are instantiated. [See this example on using DogStatsD-ruby v5.x with Sidekiq](https://github.com/DataDog/dogstatsd-ruby/blob/master/examples/sidekiq_example.rb).
+
+Applications that run into issues but can't apply these recommendations should use the `single_thread` mode which disables the use of the sender thread.
+Here is how to instantiate a client in this mode:
+
+```ruby
+statsd = Datadog::Statsd.new('localhost', 8125, single_thread: true)
+# ...
+# release resources used by the client instance and flush last metrics
+statsd.close()
+```
 
 ### Origin detection over UDP
 
-Origin detection is a method to detect which pod DogStatsD packets are coming from in order to add the pod's tags to the tag list.
+Origin detection is a method to detect which pod DogStatsD packets are coming from, in order to add the pod's tags to the tag list.
+
+To enable origin detection over UDP, add the following lines to your application manifest:
 
-To enable origin detection over UDP, add the following lines to your application manifest
 ```yaml
 env:
   - name: DD_ENTITY_ID
@@ -45,36 +104,134 @@ env:
       fieldRef:
         fieldPath: metadata.uid
 ```
+
 The DogStatsD client attaches an internal tag, `entity_id`. The value of this tag is the content of the `DD_ENTITY_ID` environment variable, which is the pod’s UID.
 
 ## Usage
 
-In order to use DogStatsD metrics, events, and Service Checks the Agent must be [running and available](https://docs.datadoghq.com/developers/dogstatsd/?tab=ruby).
+In order to use DogStatsD metrics, events, and Service Checks the Datadog Agent must be [running and available](https://docs.datadoghq.com/developers/dogstatsd/?tab=ruby).
 
 ### Metrics
 
-After the client is created, you can start sending custom metrics to Datadog. See the dedicated [Metric Submission: DogStatsD documentation](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby) to see how to submit all supported metric types to Datadog with working code examples:
+After the client is created, you can start sending custom metrics to Datadog. See the dedicated [Metric Submission: DogStatsD documentation](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?tab=ruby) to see how to submit all supported metric types to Datadog with working code examples:
 
-* [Submit a COUNT metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#count).
-* [Submit a GAUGE metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#gauge).
-* [Submit a SET metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#set)
-* [Submit a HISTOGRAM metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#histogram)
-* [Submit a DISTRIBUTION metric](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#distribution)
+* [Submit a COUNT metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=ruby#count).
+* [Submit a GAUGE metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=ruby#gauge).
+* [Submit a SET metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=ruby#set)
+* [Submit a HISTOGRAM metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=ruby#histogram)
+* [Submit a DISTRIBUTION metric](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?code-lang=ruby#distribution)
 
-Some options are suppported when submitting metrics, like [applying a Sample Rate to your metrics](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#metric-submission-options) or [tagging your metrics with your custom tags](https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/?tab=ruby#metric-tagging). Find all the available functions to report metrics in the [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd).
+Some options are suppported when submitting metrics, like [applying a Sample Rate to your metrics](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?tab=ruby#metric-submission-options) or [tagging your metrics with your custom tags](https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/?tab=ruby#metric-tagging). Find all the available functions to report metrics in the [DogStatsD-ruby rubydoc](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/Datadog/Statsd).
 
 ### Events
 
-After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated [Event Submission: DogStatsD documentation](https://docs.datadoghq.com/developers/events/dogstatsd/?tab=ruby) to see how to submit an event to Datadog your Event Stream.
+After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated [Event Submission: DogStatsD documentation](https://docs.datadoghq.com/events/guides/dogstatsd/?code-lang=ruby) to see how to submit an event to Datadog your Event Stream.
 
 ### Service Checks
 
 After the client is created, you can start sending Service Checks to Datadog. See the dedicated [Service Check Submission: DogStatsD documentation](https://docs.datadoghq.com/developers/service_checks/dogstatsd_service_checks_submission/?tab=ruby) to see how to submit a Service Check to Datadog.
 
+### Maximum packet size in high-throughput scenarios
+
+In order to have the most efficient use of this library in high-throughput scenarios,
+recommended values for the maximum packet size have already been set for both UDS (8192 bytes)
+and UDP (1432 bytes).
+
+However, if are in control of your network and want to use a different value for the maximum packet
+size, you can do it by setting the `buffer_max_payload_size` parameter:
+
+```ruby
+statsd = Datadog::Statsd.new('localhost', 8125, buffer_max_payload_size: 4096)
+# ...
+statsd.close()
+```
+
+## Threading model
+
+Starting with version 5.0, `dogstatsd-ruby` employs a new threading model where one instance of `Datadog::Statsd` can be shared between threads and where data sending is non-blocking (asynchronous).
+
+When you instantiate a `Datadog::Statsd`, a sender thread is spawned. This thread will be called the Sender thread, as it is modeled by the [Sender](../lib/datadog/statsd/sender.rb) class. You can make use of `single_thread: true` to disable this behavior.
+
+This thread is stopped when you close the statsd client (`Datadog::Statsd#close`). Instantiating a lot of statsd clients without calling `#close` after they are not needed anymore will most likely lead to threads being leaked.
+
+The sender thread has the following logic (from `Datadog::Statsd::Sender#send_loop`):
+
+```
+while the sender message queue is not closed do
+  read message from sender message queue
+
+  if message is a Control message to flush
+    flush buffer in connection
+  else if message is a Control message to synchronize
+    synchronize with calling thread
+  else
+    add message to the buffer
+  end
+end while
+```
+
+There are three different kinds of messages:
+
+1. a control message to flush the buffer in the connection
+2. a control message to synchronize any thread with the sender thread
+3. a message to append to the buffer
+
+There is also an implicit message which closes the queue which will cause the sender thread to finish processing and exit.
+
+
+```ruby
+statsd = Datadog::Statsd.new('localhost', 8125)
+```
+
+The message queue's maximum size (in messages) is given by the `sender_queue_size` argument, and has appropriate defaults for UDP (2048), UDS (512) and `single_thread: true` (1).
+
+The `buffer_flush_interval`, if enabled, is implemented with an additional thread which manages the timing of those flushes.  This additional thread is used even if `single_thread: true`.
+
+### Usual workflow
+
+You push metrics to the statsd client which writes them quickly to the sender message queue. The sender thread receives those message, buffers them and flushes them to the connection when the buffer limit is reached.
+
+### Flushing
+
+When calling `Datadog::Statsd#flush`, a specific control message (`:flush`) is sent to the sender thread. When the sender thread receives it, it flushes its internal buffer into the connection.
+
+### Rendez-vous
+
+It is possible to ensure a message has been consumed by the sender thread and written to the buffer by simply calling a rendez-vous right after. This is done when you are doing a synchronous flush using `Datadog::Statsd#flush(sync: true)`.
+
+Doing so means the caller thread is blocked and waiting until the data has been flushed by the sender thread.
+
+This is useful when preparing to exit the application or when checking unit tests.
+
+### Thread-safety
+
+By default, instances of `Datadog::Statsd` are thread-safe and we recommend that a single instance be reused by all application threads (even in applications that employ forking). The sole exception is the `#close` method — this method is not yet thread safe (work in progress here [#209](https://github.com/DataDog/dogstatsd-ruby/pull/209)).
+
+When using the `single_thread: true` mode, instances of `Datadog::Statsd` are still thread-safe, but you may run into contention on heavily-threaded applications, so we don’t recommend (for performance reasons) reusing these instances.
+
+### Delaying serialization
+
+By default, message serialization happens synchronously whenever stat methods such as `#increment` gets called, blocking the caller. If the blocking is impacting your program's performance, you may want to consider the `delay_serialization: true` mode.
+
+The `delay_serialization: true` mode delays the serialization of metrics to avoid the wait when submitting metrics. Serialization will still have to happen at some point, but it might be postponed until a more convenient time, such as after an HTTP request has completed.
+
+In `single_thread: true` mode, you'll probably want to set `sender_queue_size:` from it's default of `1` to some greater value, so that it can benefit from `delay_serialization: true`. Messages will then be queued unserialized in the sender queue and processed normally whenever `sender_queue_size` is reached or `#flush` is called. You might set `sender_queue_size: Float::INFINITY` to allow for an unbounded queue that will only be processed on explicit `#flush`.
+
+In `single_thread: false` mode, `delay_serialization: true`, will cause serialization to happen inside the sender thread.
+
+## Versioning
+
+This Ruby gem is using [Semantic Versioning](https://guides.rubygems.org/patterns/#semantic-versioning) but please note that supported Ruby versions can change in a minor release of this library.
+As much as possible, we will add a "future deprecation" message in the minor release preceding the one dropping the support.
+
+## Ruby Versions
+
+This gem supports and is tested on Ruby minor versions 2.1 through 3.1.
+Support for Ruby 2.0 was dropped in version 5.4.0.
+
 ## Credits
 
-dogstatsd-ruby is forked from Rien Henrichs [original Statsd
-client](https://github.com/reinh/statsd).
+dogstatsd-ruby is forked from Rein Henrichs' [original Statsd client](https://github.com/reinh/statsd).
 
 Copyright (c) 2011 Rein Henrichs. See LICENSE.txt for
 further details.

data/lib/datadog/statsd/connection.rb

@@ -3,32 +3,24 @@
 module Datadog
   class Statsd
     class Connection
-      def initialize(telemetry)
+      def initialize(telemetry: nil, logger: nil)
         @telemetry = telemetry
+        @logger = logger
       end
 
-      # Close the underlying socket
-      def close
-        begin
-          @socket && @socket.close if instance_variable_defined?(:@socket)
-        rescue StandardError => boom
-          logger.error { "Statsd: #{boom.class} #{boom}" } if logger
-        end
-        @socket = nil
+      def reset_telemetry
+        telemetry.reset if telemetry
       end
 
+      # not thread safe: `Sender` instances that use this are required to properly synchronize or sequence calls to this method
       def write(payload)
         logger.debug { "Statsd: #{payload}" } if logger
 
-        flush_telemetry = telemetry.flush?
-
-        payload += telemetry.flush if flush_telemetry
-
         send_message(payload)
 
-        telemetry.reset if flush_telemetry
+        telemetry.sent(packets: 1, bytes: payload.length) if telemetry
 
-        telemetry.sent(packets: 1, bytes: payload.length)
+        true
       rescue StandardError => boom
         # Try once to reconnect if the socket has been closed
         retries ||= 1
@@ -39,23 +31,29 @@ module Datadog
           retries += 1
           begin
             close
+            connect
             retry
           rescue StandardError => e
             boom = e
           end
         end
 
-        telemetry.dropped(packets: 1, bytes: payload.length)
+        telemetry.dropped_writer(packets: 1, bytes: payload.length) if telemetry
         logger.error { "Statsd: #{boom.class} #{boom}" } if logger
         nil
       end
 
       private
+
       attr_reader :telemetry
       attr_reader :logger
 
-      def socket
-        @socket ||= connect
+      def connect
+        raise 'Should be implemented by subclass'
+      end
+
+      def close
+        raise 'Should be implemented by subclass'
       end
     end
   end

data/lib/datadog/statsd/connection_cfg.rb

@@ -0,0 +1,125 @@
+module Datadog
+  class Statsd
+    class ConnectionCfg
+      attr_reader :host
+      attr_reader :port
+      attr_reader :socket_path
+      attr_reader :transport_type
+
+      def initialize(host: nil, port: nil, socket_path: nil)
+        initialize_with_constructor_args(host: host, port: port, socket_path: socket_path) ||
+          initialize_with_env_vars ||
+          initialize_with_defaults
+      end
+
+      def make_connection(**params)
+        case @transport_type
+        when :udp
+          UDPConnection.new(@host, @port, **params)
+        when :uds
+          UDSConnection.new(@socket_path, **params)
+        end
+      end
+
+      private
+
+      ERROR_MESSAGE = "Valid environment variables combination for connection configuration:\n" +
+                      "  - DD_DOGSTATSD_URL for UDP or UDS connection.\n" +
+                      "     Example for UDP: DD_DOGSTATSD_URL='udp://localhost:8125'\n" +
+                      "     Example for UDS: DD_DOGSTATSD_URL='unix:///path/to/unix.sock'\n" +
+                      "  or\n" +
+                      "  - DD_AGENT_HOST and DD_DOGSTATSD_PORT for an UDP connection. E.g. DD_AGENT_HOST='localhost' DD_DOGSTATSD_PORT=8125\n" +
+                      "  or\n" +
+                      "  - DD_DOGSTATSD_SOCKET for an UDS connection: E.g. DD_DOGSTATSD_SOCKET='/path/to/unix.sock'\n" +
+                      " Note that DD_DOGSTATSD_URL has priority on other environment variables."
+
+      DEFAULT_HOST = '127.0.0.1'
+      DEFAULT_PORT = 8125
+
+      UDP_PREFIX = 'udp://'
+      UDS_PREFIX = 'unix://'
+
+      def initialize_with_constructor_args(host: nil, port: nil, socket_path: nil)
+        try_initialize_with(host: host, port: port, socket_path: socket_path,
+          error_message: 
+            "Both UDP: (host/port #{host}:#{port}) and UDS (socket_path #{socket_path}) " +
+            "constructor arguments were given. Use only one or the other.",
+          )
+      end
+
+      def initialize_with_env_vars()
+        try_initialize_with(
+          dogstatsd_url: ENV['DD_DOGSTATSD_URL'],
+          host: ENV['DD_AGENT_HOST'],
+          port: ENV['DD_DOGSTATSD_PORT'] && ENV['DD_DOGSTATSD_PORT'].to_i,
+          socket_path: ENV['DD_DOGSTATSD_SOCKET'],
+          error_message: ERROR_MESSAGE,
+        )
+      end
+
+      def initialize_with_defaults()
+        try_initialize_with(host: DEFAULT_HOST, port: DEFAULT_PORT)
+      end
+
+      def try_initialize_with(dogstatsd_url: nil, host: nil, port: nil, socket_path: nil, error_message: ERROR_MESSAGE)
+        if (host || port) && socket_path
+          raise ArgumentError, error_message
+        end
+
+        if dogstatsd_url
+          host, port, socket_path = parse_dogstatsd_url(str: dogstatsd_url.to_s)
+        end
+
+        if host || port 
+          @host = host || DEFAULT_HOST
+          @port = port || DEFAULT_PORT
+          @socket_path = nil
+          @transport_type = :udp
+          return true
+        elsif socket_path
+          @host = nil
+          @port = nil
+          @socket_path = socket_path
+          @transport_type = :uds
+          return true
+        end
+
+        return false
+      end
+
+      def parse_dogstatsd_url(str:)
+        # udp socket connection
+
+        if str.start_with?(UDP_PREFIX)
+          dogstatsd_url = str[UDP_PREFIX.size..str.size]
+          host = nil
+          port = nil
+
+          if dogstatsd_url.include?(":")
+            parts = dogstatsd_url.split(":")
+            if parts.size > 2
+              raise ArgumentError, "Error: DD_DOGSTATSD_URL wrong format for an UDP connection. E.g. 'udp://localhost:8125'"
+            end
+
+            host = parts[0]
+            port = parts[1].to_i
+          else
+            host = dogstatsd_url
+          end
+
+          return host, port, nil
+        end
+
+        # unix socket connection
+
+        if str.start_with?(UDS_PREFIX)
+          return nil, nil, str[UDS_PREFIX.size..str.size]
+        end
+
+        # malformed value
+
+        raise ArgumentError, "Error: DD_DOGSTATSD_URL has been provided but is not starting with 'udp://' nor 'unix://'"
+      end
+    end
+  end
+end

data/lib/datadog/statsd/forwarder.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Datadog
+  class Statsd
+    class Forwarder
+      attr_reader :telemetry
+      attr_reader :transport_type
+
+      def initialize(
+        connection_cfg: nil,
+
+        buffer_max_payload_size: nil,
+        buffer_max_pool_size: nil,
+        buffer_overflowing_stategy: :drop,
+        buffer_flush_interval: nil,
+
+        sender_queue_size: nil,
+
+        telemetry_flush_interval: nil,
+        global_tags: [],
+
+        single_thread: false,
+
+        logger: nil,
+
+        serializer:
+      )
+        @transport_type = connection_cfg.transport_type
+
+        @telemetry = if telemetry_flush_interval
+          Telemetry.new(telemetry_flush_interval,
+            global_tags: global_tags,
+            transport_type: @transport_type
+          )
+        else
+          nil
+        end
+
+        @connection = connection_cfg.make_connection(logger: logger, telemetry: telemetry)
+
+        # Initialize buffer
+        buffer_max_payload_size ||= (@transport_type == :udp ?
+                                     UDP_DEFAULT_BUFFER_SIZE : UDS_DEFAULT_BUFFER_SIZE)
+
+        if buffer_max_payload_size <= 0
+          raise ArgumentError, 'buffer_max_payload_size cannot be <= 0'
+        end
+
+        unless telemetry.nil? || telemetry.would_fit_in?(buffer_max_payload_size)
+          raise ArgumentError, "buffer_max_payload_size is not high enough to use telemetry (tags=(#{global_tags.inspect}))"
+        end
+
+        buffer = MessageBuffer.new(@connection,
+          max_payload_size: buffer_max_payload_size,
+          max_pool_size: buffer_max_pool_size || DEFAULT_BUFFER_POOL_SIZE,
+          overflowing_stategy: buffer_overflowing_stategy,
+          serializer: serializer
+        )
+
+        sender_queue_size ||= 1 if single_thread
+        sender_queue_size ||= (@transport_type == :udp ?
+                               UDP_DEFAULT_SENDER_QUEUE_SIZE : UDS_DEFAULT_SENDER_QUEUE_SIZE)
+
+        @sender = single_thread ?
+          SingleThreadSender.new(
+            buffer,
+            logger: logger,
+            flush_interval: buffer_flush_interval,
+            queue_size: sender_queue_size) :
+          Sender.new(
+            buffer,
+            logger: logger,
+            flush_interval: buffer_flush_interval,
+            telemetry: @telemetry,
+            queue_size: sender_queue_size)
+        @sender.start
+      end
+
+      def send_message(message)
+        sender.add(message)
+
+        tick_telemetry
+      end
+
+      def sync_with_outbound_io
+        sender.rendez_vous
+      end
+
+      def flush(flush_telemetry: false, sync: false)
+        do_flush_telemetry if telemetry && flush_telemetry
+
+        sender.flush(sync: sync)
+      end
+
+      def host
+        return nil unless transport_type == :udp
+
+        connection.host
+      end
+
+      def port
+        return nil unless transport_type == :udp
+
+        connection.port
+      end
+
+      def socket_path
+        return nil unless transport_type == :uds
+
+        connection.socket_path
+      end
+
+      def close
+        sender.stop
+        connection.close
+      end
+
+      private
+      attr_reader :sender
+      attr_reader :connection
+
+      def do_flush_telemetry
+        telemetry_snapshot = telemetry.flush
+        telemetry.reset
+
+        telemetry_snapshot.each do |message|
+          sender.add(message)
+        end
+      end
+
+      def tick_telemetry
+        return nil unless telemetry
+
+        do_flush_telemetry if telemetry.should_flush?
+      end
+    end
+  end
+end

data/lib/datadog/statsd/message_buffer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Datadog
+  class Statsd
+    class MessageBuffer
+      PAYLOAD_SIZE_TOLERANCE = 0.05
+
+      def initialize(connection,
+        max_payload_size: nil,
+        max_pool_size: DEFAULT_BUFFER_POOL_SIZE,
+        overflowing_stategy: :drop,
+        serializer:
+      )
+        raise ArgumentError, 'max_payload_size keyword argument must be provided' unless max_payload_size
+        raise ArgumentError, 'max_pool_size keyword argument must be provided' unless max_pool_size
+
+        @connection = connection
+        @max_payload_size = max_payload_size
+        @max_pool_size = max_pool_size
+        @overflowing_stategy = overflowing_stategy
+        @serializer = serializer
+
+        @buffer = String.new
+        clear_buffer
+      end
+
+      def add(message)
+        # Serializes the message if it hasn't been already. Part of the
+        # delay_serialization feature.
+        if message.is_a?(Array)
+          message = @serializer.to_stat(*message[0], **message[1])
+        end
+
+        message_size = message.bytesize
+
+        return nil unless message_size > 0 # to avoid adding empty messages to the buffer
+        return nil unless ensure_sendable!(message_size)
+
+        flush if should_flush?(message_size)
+
+        buffer << "\n" unless buffer.empty?
+        buffer << message
+
+        @message_count += 1
+
+        # flush when we're pretty sure that we won't be able
+        # to add another message to the buffer
+        flush if preemptive_flush?
+
+        true
+      end
+
+      def reset
+        clear_buffer
+        connection.reset_telemetry
+      end
+
+      def flush
+        return if buffer.empty?
+
+        connection.write(buffer)
+        clear_buffer
+      end
+
+      private
+
+      attr :max_payload_size
+      attr :max_pool_size
+
+      attr :overflowing_stategy
+
+      attr :connection
+      attr :buffer
+
+      def should_flush?(message_size)
+        return true if buffer.bytesize + 1 + message_size >= max_payload_size
+
+        false
+      end
+
+      def clear_buffer
+        buffer.clear
+        @message_count = 0
+      end
+
+      def preemptive_flush?
+        @message_count == max_pool_size || buffer.bytesize > bytesize_threshold
+      end
+
+      def ensure_sendable!(message_size)
+        return true if message_size <= max_payload_size
+
+        if overflowing_stategy == :raise
+          raise Error, 'Message too big for payload limit'
+        end
+
+        false
+      end
+
+      def bytesize_threshold
+        @bytesize_threshold ||= (max_payload_size - PAYLOAD_SIZE_TOLERANCE * max_payload_size).to_i
+      end
+    end
+  end
+end