dogstatsd-ruby 5.3.0 → 5.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 828679b3ff6ef3a2acce023e8b3cc5d362fe8c41ac17acee8bd2d5662ae3b2f3
-  data.tar.gz: 0c836007b9b82eb7e0cf056f86d9426e8f43b1e1543876c53819b8e0f46c8235
+  metadata.gz: 539ec3d4e02bd8784df4d032b0f8e96ebb2a582b510ff5e27c6e7cfff4515926
+  data.tar.gz: d8ecf4c6724e491aaea6d738cc255891b55119987b1ca5665087d506552135ee
 SHA512:
-  metadata.gz: dc31df8c212fa4ab0854075528a03729d8600fabbc2e387ec4bf4c3c712a5106600c68065d5204d082f3d9fbaeafa74c8dc6cee15c8dea03fe7de192bcfb654e
-  data.tar.gz: 552b383c99f0071662d83991dc5e3472b0cc73125ef9fa3c558de1a59b8bf48fed3dc0d7b96e62808cf0bb044e65c4e332e569e7c9add6dcaf72a0300bfb4ca3
+  metadata.gz: d615efd205f7858c55b9864e1d001d607dcb39a47a26c87f5e27402b25834cf750fb3904d10d667c63a437587d38ba315d7a3c609b7709bc28a8bc8138d30eef
+  data.tar.gz: 254bf33695141f521d55d5f5b9c4d6b3abf2408b6b231263949094cbc2c9f531bf3ff2aea92ae0f11d505bbb8d25a789a2c0da76d9a065b713f9dc9b5b9d836d

data/README.md

@@ -46,14 +46,14 @@ 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 companion thread will automatically flush the buffered metrics if the buffer gets full or when you are closing the instance.
+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 companion thread or the buffering mode, you can instantiate a client that behaves exactly as in v4.x (i.e. no companion thread and flush on every metric submission):
+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
@@ -73,9 +73,9 @@ statsd.close()
 
 ### v5.x Common Pitfalls
 
-Version v5.x of `dogstatsd-ruby` is using a companion thread for flushing. This provides better performance, but you need to consider the following 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 companion thread to flush metrics.
+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.
 
@@ -83,7 +83,7 @@ If you are using [Sidekiq](https://github.com/mperham/sidekiq), please make sure
 
 If you are using [Puma](https://github.com/puma/puma) or [Unicorn](https://yhbt.net/unicorn.git), please make sure to create the instance of DogStatsD in the workers, not in the main process before it forks to create its workers. See [this comment for more details](https://github.com/DataDog/dogstatsd-ruby/issues/179#issuecomment-845570345).
 
-Applications that run into issues but can't apply these recommendations should use the `single_thread` mode which disables the use of the companion thread.
+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
@@ -152,7 +152,7 @@ statsd.close()
 
 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 companion 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.
+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.
 
@@ -196,6 +196,12 @@ Doing so means the caller thread is blocked and waiting until the data has been
 
 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.
+
 ## 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.

data/lib/datadog/statsd/connection.rb

@@ -12,6 +12,7 @@ module Datadog
         telemetry.reset
       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
 

data/lib/datadog/statsd/udp_connection.rb

@@ -20,7 +20,6 @@ module Datadog
         @host = host || ENV.fetch('DD_AGENT_HOST', DEFAULT_HOST)
         @port = port || ENV.fetch('DD_DOGSTATSD_PORT', DEFAULT_PORT).to_i
         @socket = nil
-        connect
       end
 
       def close
@@ -37,7 +36,12 @@ module Datadog
         @socket.connect(host, port)
       end
 
+      # send_message is writing the message in the socket, it may create the socket if nil
+      # It is not thread-safe but since it is called by either the Sender bg thread or the
+      # SingleThreadSender (which is using a mutex while Flushing), only one thread must call
+      # it at a time.
       def send_message(message)
+        connect unless @socket
         @socket.send(message, 0)
       end
     end

data/lib/datadog/statsd/uds_connection.rb

@@ -15,7 +15,6 @@ module Datadog
 
         @socket_path = socket_path
         @socket = nil
-        connect
       end
 
       def close
@@ -32,7 +31,12 @@ module Datadog
         @socket.connect(Socket.pack_sockaddr_un(@socket_path))
       end
 
+      # send_message is writing the message in the socket, it may create the socket if nil
+      # It is not thread-safe but since it is called by either the Sender bg thread or the
+      # SingleThreadSender (which is using a mutex while Flushing), only one thread must call
+      # it at a time.
       def send_message(message)
+        connect unless @socket
         @socket.sendmsg_nonblock(message)
       rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ENOENT => e
         # TODO: FIXME: This error should be considered as a retryable error in the

data/lib/datadog/statsd/version.rb

@@ -4,6 +4,6 @@ require_relative 'connection'
 
 module Datadog
   class Statsd
-    VERSION = '5.3.0'
+    VERSION = '5.3.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dogstatsd-ruby
 version: !ruby/object:Gem::Version
-  version: 5.3.0
+  version: 5.3.1
 platform: ruby
 authors:
 - Rein Henrichs
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-06 00:00:00.000000000 Z
+date: 2021-10-21 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby DogStatsd client
 email: code@datadoghq.com
@@ -43,9 +43,9 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/DataDog/dogstatsd-ruby/issues
-  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v5.3.0/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/5.3.0
-  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v5.3.0
+  changelog_uri: https://github.com/DataDog/dogstatsd-ruby/blob/v5.3.1/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/dogstatsd-ruby/5.3.1
+  source_code_uri: https://github.com/DataDog/dogstatsd-ruby/tree/v5.3.1
 post_install_message:
 rdoc_options: []
 require_paths: