documentation

Author: xvello

README.md

@@ -60,6 +60,14 @@ public class Foo {
 
 Unix Domain Socket support
 ---------------------------
-java.io.IOException: No such file or directory
-java.io.IOException: No buffer space available
+
+As an alternative to UDP, Agent6 can receive metrics via a UNIX Socket (on Linux only). This library supports
+transmission via this protocol. To use it, simply pass the socket path as a hostname, and 0 as port.
+
+By default, all exceptions are ignored, mimicking UDP behaviour. When using Unix Sockets, transmission errors will
+trigger exceptions you can choose to handle by passing a `StatsDClientErrorHandler`:
+
+- Connection error because of an invalid/missing socket will trigger a `java.io.IOException: No such file or directory`
+- If dogstatsd's reception buffer were to fill up, the send will timeout after 100ms and throw either a
+`java.io.IOException: No buffer space available` or a `java.io.IOException: Resource temporarily unavailable`
 

src/main/java/com/timgroup/statsd/NonBlockingStatsDClient.java

@@ -319,6 +319,8 @@ public NonBlockingStatsDClient(final String prefix,  final int queueSize, String
             final SocketAddress address = addressLookup.call();
             if (address instanceof UnixSocketAddress) {
                 clientChannel = UnixDatagramChannel.open();
+                // Set send timeout to 100ms, to handle the case where the transmission buffer is full
+                // If no timeout is set, the send becomes blocking
                 clientChannel.setOption(UnixSocketOptions.SO_SNDTIMEO, Integer.valueOf(100));
             } else{
                 clientChannel = DatagramChannel.open();