Fix 247 and docs on 239 (#297)

* Fix 247 and docs on 239

* Update lib/transport.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update test/transport.js

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* CHANGES updates

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: bdeitte

CHANGES.md

@@ -1,8 +1,12 @@
 CHANGELOG
 =========
 
+## 13.1.0 (2026-1-24)
+
 * @bdeitte Add documentation for OpenTelemetry Collector StatsD receiver compatibility
 * @bdeitte Sanitize protocol-breaking characters in metric names and tags. Fixes #238. Characters like `|`, `:`, `\n`, `#`, and `,` in metric names or tags are now replaced with `_` to prevent malformed packets.
+* @bdeitte Document how to handle metrics on shutdown
+* @bdeitte Prevent "socket ended" errors and handle the client disconnection errors more gracefully. Fixes #247
 
 ## 13.0.0 (2026-1-19)
 

README.md

@@ -350,6 +350,46 @@ it is probably because you are sending large volumes of metrics to a single agen
 This error only arises when using the UDS protocol and means that packages are being dropped.
 Take a look at the [Datadog docs](https://docs.datadoghq.com/developers/dogstatsd/high_throughput/?#over-uds-unix-domain-socket) for some tips on tuning your connection.
 
+### Sending metrics during process shutdown
+
+Metrics sent from `process.on('exit')` handlers will **not** be delivered. This is a fundamental Node.js limitation, not a bug in hot-shots. When the `exit` event fires, the event loop has stopped processing async operations, so socket send callbacks will never execute.
+
+The same applies to `process.on('uncaughtExceptionMonitor')` since that handler is also synchronous.
+
+**Alternatives that work:**
+
+Use `beforeExit` for graceful shutdown (fires when event loop is empty but before exit):
+```javascript
+process.on('beforeExit', (code) => {
+  client.increment('app.shutdown');
+  client.close();
+});
+```
+
+Use signal handlers for external shutdown requests:
+```javascript
+function gracefulShutdown(signal) {
+  client.increment('app.shutdown', [`signal:${signal}`]);
+  client.close(() => {
+    process.exit(0);
+  });
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+```
+
+For uncaught exceptions, use `uncaughtException` (not `uncaughtExceptionMonitor`) and delay exit:
+```javascript
+process.on('uncaughtException', (err) => {
+  client.increment('app.crash');
+  client.close(() => {
+    console.error('Uncaught exception:', err);
+    process.exit(1);
+  });
+});
+```
+
 ## Debugging
 
 If you're having issues with metrics not being sent or want to understand what hot-shots is doing

lib/transport.js

@@ -52,6 +52,17 @@ const createTcpTransport = args => {
     removeListener: socket.removeListener.bind(socket),
     send: (buf, callback) => {
       debug('hot-shots createTcpTransport: sending %d bytes to %s:%s', buf.length, args.host, args.port);
+      // Check if socket is destroyed before attempting to write
+      // This prevents ERR_STREAM_DESTROYED and "socket ended" errors (issue #247)
+      if (socket.destroyed) {
+        const err = new Error('Socket is destroyed');
+        err.code = 'ERR_SOCKET_DESTROYED';
+        debug('hot-shots createTcpTransport: socket destroyed, skipping send');
+        if (callback) {
+          callback(err);
+        }
+        return;
+      }
       socket.write(addEol(buf), 'ascii', (err) => {
         if (err) {
           debug('hot-shots createTcpTransport: send error - %s', err.message);
@@ -362,6 +373,17 @@ const createStreamTransport = (args) => {
     removeListener: stream.removeListener.bind(stream),
     send: (buf, callback) => {
       debug('hot-shots stream transport: sending %d bytes', buf.length);
+      // Check if stream is destroyed before attempting to write
+      // This prevents ERR_STREAM_DESTROYED errors (issue #247)
+      if (stream.destroyed) {
+        const err = new Error('Stream is destroyed');
+        err.code = 'ERR_STREAM_DESTROYED';
+        debug('hot-shots stream transport: stream destroyed, skipping send');
+        if (callback) {
+          callback(err);
+        }
+        return;
+      }
       stream.write(addEol(buf), (err) => {
         if (err) {
           debug('hot-shots stream transport: send error - %s', err.message);

test/transport.js

@@ -126,4 +126,57 @@ describe('#transportExtended', () => {
     client.increment('test.metric');
   });
 
+  it('should handle write to destroyed stream gracefully (issue #247)', done => {
+    let writeAttempted = false;
+
+    class TestStream extends Writable {
+      _write(chunk, encoding, callback) { // eslint-disable-line class-methods-use-this
+        writeAttempted = true;
+        callback();
+      }
+    }
+
+    const stream = new TestStream();
+    const client = new StatsD({
+      protocol: 'stream',
+      stream: stream,
+      errorHandler: (error) => {
+        // Error should be handled gracefully and identified by the expected error code
+        assert.strictEqual(error.code, 'ERR_STREAM_DESTROYED');
+        assert.strictEqual(writeAttempted, false, 'Should not attempt write to destroyed stream');
+        client.close();
+        done();
+      }
+    });
+
+    // Destroy the stream before sending - this sets stream.destroyed = true
+    stream.destroy();
+
+    // This should call errorHandler with a graceful error, not throw ERR_STREAM_DESTROYED
+    client.increment('test.metric');
+  });
+
+  it('should send metric when stream is writable', done => {
+    let writeAttempted = false;
+
+    class TestStream extends Writable {
+      _write(chunk, encoding, callback) { // eslint-disable-line class-methods-use-this
+        writeAttempted = true;
+        callback();
+        // Verify write was attempted
+        assert.strictEqual(writeAttempted, true);
+        client.close();
+        done();
+      }
+    }
+
+    const stream = new TestStream();
+    const client = new StatsD({
+      protocol: 'stream',
+      stream: stream
+    });
+
+    client.increment('test.metric');
+  });
+
 });