Fix for 238 and doc update for 264 (#298)

* Fix for 238 and doc update for 264

* Fix changelog

* README updates

* README fix

* Another README fix

Author: bdeitte

CHANGES.md

@@ -1,6 +1,9 @@
 CHANGELOG
 =========
 
+* @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.
+
 ## 13.0.0 (2026-1-19)
 
 * @bdeitte Breaking: Prefix and suffix now automatically include period separators if needed. If you specify `prefix: 'myapp'`, it will be normalized to `'myapp.'`. Similarly, `suffix: 'prod'` becomes `'.prod'`. This ensures metrics like `myapp.request.time` instead of `myapprequest.time`. If your prefix/suffix already includes the period, no change is needed.

README.md

@@ -1,6 +1,6 @@
 # hot-shots
 
-A Node.js client for [Etsy](http://etsy.com)'s [StatsD](https://github.com/etsy/statsd) server, Datadog's [DogStatsD](http://docs.datadoghq.com/guides/dogstatsd/) server, and [InfluxDB's](http://influxdb.com) [Telegraf](https://github.com/influxdb/telegraf) StatsD server.
+A Node.js client for Datadog's [DogStatsD](http://docs.datadoghq.com/guides/dogstatsd/) server, InfluxDB's [Telegraf](https://github.com/influxdb/telegraf) StatsD server, the OpenTelemetry Collector [StatsD receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/statsdreceiver), and Etsy's [StatsD](https://github.com/etsy/statsd) server.
 
 This project was originally a fork off of [node-statsd](https://github.com/sivy/node-statsd).  This project
 includes all changes in the latest node-statsd and many additional changes, including:
@@ -264,18 +264,63 @@ The check method has the following API:
   });
 ```
 
-## DogStatsD and Telegraf functionality
-
-Some of the functionality mentioned above is specific to DogStatsD or Telegraf.  They will not do anything if you are using the regular statsd client.
-* globalTags parameter- DogStatsD or Telegraf
-* tags parameter- DogStatsD or Telegraf.
-* telegraf parameter- Telegraf
-* uds option in protocol parameter- DogStatsD
-* histogram method- DogStatsD or Telegraf
-* event method- DogStatsD
-* check method- DogStatsD
-* includeDatadogTelemetry parameter- DogStatsD
-* telemetryFlushInterval parameter- DogStatsD
+## DogStatsD, Telegraf, and OpenTelemetry functionality
+
+Some of the functionality mentioned above is specific to certain backends and will not work with others.
+
+* globalTags parameter - DogStatsD, Telegraf, or OpenTelemetry
+* tags parameter - DogStatsD, Telegraf, or OpenTelemetry
+* histogram method - DogStatsD, Telegraf, or OpenTelemetry
+* telegraf parameter - Telegraf
+* uds option in protocol parameter - DogStatsD
+* distribution method - DogStatsD
+* set / unique method - DogStatsD or Telegraf (not OpenTelemetry)
+* event method - DogStatsD
+* check method - DogStatsD
+* timestamp option - DogStatsD
+* includeDatadogTelemetry parameter - DogStatsD
+* telemetryFlushInterval parameter - DogStatsD
+
+## OpenTelemetry Collector Compatibility
+
+hot-shots is compatible with the [OpenTelemetry Collector's StatsD receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/statsdreceiver). The following features work out of the box:
+
+| Feature | hot-shots Method | OTel Support |
+|---------|------------------|--------------|
+| Counter | `increment()`, `decrement()` | Yes |
+| Gauge | `gauge()` | Yes |
+| Gauge delta (+/-) | `gaugeDelta()` | Yes |
+| Timer | `timing()` | Yes (converted to gauge/summary/histogram) |
+| Histogram | `histogram()` | Yes (treated as timer) |
+| Sample rate | All methods | Yes |
+| Tags | All methods | Yes |
+
+Example configuration for OpenTelemetry Collector:
+
+```javascript
+var client = new StatsD({
+  host: 'localhost',
+  port: 8125,
+  protocol: 'udp'  // or 'tcp'
+});
+
+// These all work with OpenTelemetry
+client.increment('requests');
+client.gauge('queue_size', 100);
+client.gaugeDelta('connections', 1);
+client.timing('response_time', 250);
+client.histogram('request_size', 1024);
+```
+
+## Sanitization
+
+To prevent malformed packets, hot-shots automatically replaces protocol-breaking characters with underscores (`_`).
+
+* **Metric names**: `:`, `|`, `\n`
+* **Tag keys**: `:`, `|`, `,`, `\n`, plus `@` and `#` for StatsD/DogStatsD
+* **Tag values**: `|`, `,`, `\n`, plus `@` and `#` for StatsD/DogStatsD
+
+Colons are allowed in tag values (e.g., `url:https://example.com:8080`).
 
 ## Errors
 

lib/helpers.js

@@ -1,10 +1,18 @@
 const fs = require('fs');
 
 /**
- * Replace any characters that can't be sent on with an underscore
+ * Replace any characters that can't be sent on with an underscore.
+ * Used for tag keys where colons are not allowed (colon separates key from value).
  */
 function sanitizeTags(value, telegraf) {
-  const blacklist = telegraf ? /:|\||,/g : /:|\||@|,/g;
+  // Characters that break the protocol in tag keys:
+  // : - separates tag key from value (not allowed in keys)
+  // | - separates metric components
+  // , - separates tags
+  // @ - used for sample rate (StatsD only)
+  // # - tag prefix character (DogStatsD only)
+  // \n - breaks the line protocol
+  const blacklist = telegraf ? /:|\||,|\n/g : /:|\||@|,|#|\n/g;
   // Replace reserved chars with underscores.
   let sanitized = String(value).replace(blacklist, '_');
 
@@ -17,16 +25,64 @@ function sanitizeTags(value, telegraf) {
   return sanitized;
 }
 
+/**
+ * Replace any characters that can't be sent on with an underscore.
+ * Used for tag values where colons ARE allowed (e.g., URLs).
+ */
+function sanitizeTagValue(value, telegraf) {
+  // Characters that break the protocol in tag values:
+  // | - separates metric components
+  // , - separates tags
+  // @ - used for sample rate (StatsD only)
+  // # - tag prefix character (DogStatsD only)
+  // \n - breaks the line protocol
+  // Note: colons ARE allowed in tag values
+  const blacklist = telegraf ? /\||,|\n/g : /\||@|,|#|\n/g;
+  // Replace reserved chars with underscores.
+  let sanitized = String(value).replace(blacklist, '_');
+
+  // For telegraf, replace trailing backslashes as they break the line protocol
+  // by escaping the delimiter that comes after the tag value
+  if (telegraf && sanitized.endsWith('\\')) {
+    sanitized = sanitized.slice(0, -1) + '_';
+  }
+
+  return sanitized;
+}
+
+/**
+ * Replace any characters in metric names that can't be sent on with an underscore
+ */
+function sanitizeMetricName(value) {
+  // Characters that break the protocol in metric names:
+  // : - separates metric name from value
+  // | - separates metric components
+  // \n - breaks the line protocol
+  const blacklist = /:|\||\n/g;
+  return String(value).replace(blacklist, '_');
+}
+
 /**
  * Format tags properly before sending on
  */
 function formatTags(tags, telegraf) {
   if (Array.isArray(tags)) {
-    return tags;
+    // Sanitize each tag in the array
+    return tags.map(tag => {
+      // If tag contains a colon (not at position 0), sanitize key and value separately
+      const colonIndex = typeof tag === 'string' ? tag.indexOf(':') : -1;
+      if (colonIndex > 0) {
+        const key = tag.substring(0, colonIndex);
+        const value = tag.substring(colonIndex + 1);
+        return `${sanitizeTags(key, telegraf)}:${sanitizeTagValue(value, telegraf)}`;
+      }
+      // For tags without colons (or colon at start), sanitize as a key (most restrictive)
+      return sanitizeTags(tag, telegraf);
+    });
 
   } else {
     return Object.keys(tags).map(key => {
-      return `${sanitizeTags(key, telegraf)}:${sanitizeTags(tags[key], telegraf)}`;
+      return `${sanitizeTags(key, telegraf)}:${sanitizeTagValue(tags[key], telegraf)}`;
     });
   }
 }
@@ -149,6 +205,8 @@ module.exports = {
   formatDate: formatDate,
   getDefaultRoute: getDefaultRoute,
   sanitizeTags: sanitizeTags,
+  sanitizeTagValue: sanitizeTagValue,
+  sanitizeMetricName: sanitizeMetricName,
   normalizePrefix: normalizePrefix,
   normalizeSuffix: normalizeSuffix,
   // Expose intToIP for testing purposes

lib/statsd.js

@@ -298,7 +298,9 @@ Client.prototype.sendStat = function (stat, value, type, sampleRate, tags, times
     this.telemetry.recordMetric(type);
   }
 
-  let message = `${this.prefix + stat + this.suffix}:${value}|${type}`;
+  // Sanitize metric name to prevent protocol-breaking characters
+  const sanitizedStat = helpers.sanitizeMetricName(stat);
+  let message = `${this.prefix + sanitizedStat + this.suffix}:${value}|${type}`;
   sampleRate = sampleRate || this.sampleRate;
   if (sampleRate && sampleRate < 1) {
     if (Math.random() < sampleRate) {

test/childClient.js

@@ -38,7 +38,8 @@ describe('#childClient', () => {
         assert.strictEqual(child.prefix, 'preff.prefix.');
         assert.strictEqual(child.suffix, '.suffix.suff');
         assert.strictEqual(statsd, global.statsd);
-        assert.deepEqual(child.globalTags, ['gtag', 'awesomeness:over9000', 'tag1:xxx', 'bar', ':baz']);
+        // Note: ':baz' is sanitized to '_baz' because tags starting with colon are malformed
+        assert.deepEqual(child.globalTags, ['gtag', 'awesomeness:over9000', 'tag1:xxx', 'bar', '_baz']);
       });
     });
 

test/helpers.js

@@ -213,6 +213,115 @@ describe('#helpersExtended', () => {
       const result = helpers.sanitizeTags('tag:with|chars\\', true);
       assert.strictEqual(result, 'tag_with_chars_');
     });
+
+    it('should sanitize newlines for StatsD (default)', () => {
+      const result = helpers.sanitizeTags('tag\nvalue');
+      assert.strictEqual(result, 'tag_value');
+    });
+
+    it('should sanitize newlines for Telegraf', () => {
+      const result = helpers.sanitizeTags('tag\nvalue', true);
+      assert.strictEqual(result, 'tag_value');
+    });
+
+    it('should sanitize hash character for StatsD (default)', () => {
+      const result = helpers.sanitizeTags('tag#value');
+      assert.strictEqual(result, 'tag_value');
+    });
+
+    it('should not sanitize hash character for Telegraf', () => {
+      const result = helpers.sanitizeTags('tag#value', true);
+      assert.strictEqual(result, 'tag#value');
+    });
+
+    it('should sanitize multiple protocol-breaking characters', () => {
+      const result = helpers.sanitizeTags('tag1,tag2,\ntag3#value');
+      assert.strictEqual(result, 'tag1_tag2__tag3_value');
+    });
+  });
+
+  describe('#sanitizeTagValue', () => {
+    it('should not sanitize colons in tag values (they are valid)', () => {
+      const result = helpers.sanitizeTagValue('https://example.com:8080');
+      assert.strictEqual(result, 'https://example.com:8080');
+    });
+
+    it('should sanitize pipes in tag values', () => {
+      const result = helpers.sanitizeTagValue('value|with|pipes');
+      assert.strictEqual(result, 'value_with_pipes');
+    });
+
+    it('should sanitize newlines in tag values', () => {
+      const result = helpers.sanitizeTagValue('value\nwith\nnewlines');
+      assert.strictEqual(result, 'value_with_newlines');
+    });
+
+    it('should sanitize commas in tag values', () => {
+      const result = helpers.sanitizeTagValue('value,with,commas');
+      assert.strictEqual(result, 'value_with_commas');
+    });
+
+    it('should sanitize hash in tag values for StatsD (default)', () => {
+      const result = helpers.sanitizeTagValue('value#with#hash');
+      assert.strictEqual(result, 'value_with_hash');
+    });
+
+    it('should not sanitize hash in tag values for Telegraf', () => {
+      const result = helpers.sanitizeTagValue('value#with#hash', true);
+      assert.strictEqual(result, 'value#with#hash');
+    });
+
+    it('should sanitize at sign in tag values for StatsD (default)', () => {
+      const result = helpers.sanitizeTagValue('value@with@at');
+      assert.strictEqual(result, 'value_with_at');
+    });
+
+    it('should not sanitize at sign in tag values for Telegraf', () => {
+      const result = helpers.sanitizeTagValue('value@with@at', true);
+      assert.strictEqual(result, 'value@with@at');
+    });
+  });
+
+  describe('#sanitizeMetricName', () => {
+    it('should sanitize colons in metric names', () => {
+      const result = helpers.sanitizeMetricName('check:value');
+      assert.strictEqual(result, 'check_value');
+    });
+
+    it('should sanitize pipes in metric names', () => {
+      const result = helpers.sanitizeMetricName('check|value');
+      assert.strictEqual(result, 'check_value');
+    });
+
+    it('should sanitize newlines in metric names', () => {
+      const result = helpers.sanitizeMetricName('check\nvalue');
+      assert.strictEqual(result, 'check_value');
+    });
+
+    it('should sanitize multiple protocol-breaking characters', () => {
+      const result = helpers.sanitizeMetricName('check:11|g#this:out');
+      assert.strictEqual(result, 'check_11_g#this_out');
+    });
+
+    it('should handle non-string values', () => {
+      const result = helpers.sanitizeMetricName(123);
+      assert.strictEqual(result, '123');
+    });
+
+    it('should handle null values', () => {
+      const result = helpers.sanitizeMetricName(null);
+      assert.strictEqual(result, 'null');
+    });
+
+    it('should handle undefined values', () => {
+      const result = helpers.sanitizeMetricName(undefined);
+      assert.strictEqual(result, 'undefined');
+    });
+
+    it('should preserve valid metric name characters', () => {
+      const result = helpers.sanitizeMetricName('my.metric_name-123');
+      assert.strictEqual(result, 'my.metric_name-123');
+    });
   });
 
   describe('#overrideTags - exact results verification', () => {
@@ -278,15 +387,17 @@ describe('#helpersExtended', () => {
         const child = [123, null, undefined, 'env:dev'];
         const result = helpers.overrideTags(parent, child);
 
-        assert.deepStrictEqual(result, ['version:1.0', 'env:dev', 123, null, undefined]);
+        // Non-string values are converted to strings during sanitization
+        assert.deepStrictEqual(result, ['version:1.0', 'env:dev', '123', 'null', 'undefined']);
       });
 
       it('should handle tags with colon as first character', () => {
         const parent = ['normal:tag'];
         const child = [':invalid', 'valid:tag'];
         const result = helpers.overrideTags(parent, child);
 
-        assert.deepStrictEqual(result, ['normal:tag', 'valid:tag', ':invalid']);
+        // ':invalid' is sanitized to '_invalid' because leading colons are invalid in tags
+        assert.deepStrictEqual(result, ['normal:tag', 'valid:tag', '_invalid']);
       });
     });
 
@@ -465,7 +576,8 @@ describe('#helpersExtended', () => {
       const child = [':invalid', 'valid:tag'];
       const result = helpers.overrideTags(parent, child);
 
-      assert(result.includes(':invalid'));
+      // ':invalid' is sanitized to '_invalid' because leading colons are invalid
+      assert(result.includes('_invalid'));
       assert(result.includes('valid:tag'));
       // normal:tag should remain because child doesn't override 'normal' key
       assert(result.includes('normal:tag'));