Hot Shots StatsD Client

Common errors

• Error: getaddrinfo ENOTFOUND <host>

  cause The configured host for the StatsD agent could not be resolved by DNS or is unreachable.
  fix Verify the `host` option in your StatsD client configuration. Ensure the hostname is correct, the DNS server is reachable, or the IP address is valid and the agent is running.

• TypeError: StatsD is not a constructor

  cause Attempting to instantiate `StatsD` incorrectly due to CommonJS/ESM module mismatch or incorrect import syntax.
  fix For ESM, use `import StatsD from 'hot-shots';`. For CommonJS, use `const StatsD = require('hot-shots');`. Do not use destructuring or named imports for the main `StatsD` class.

• TS2307: Cannot find module 'hot-shots' or its corresponding type declarations.

  cause TypeScript compiler cannot locate the type definitions for the `hot-shots` package.
  fix Ensure `hot-shots` is installed (`npm install hot-shots`) and your `tsconfig.json` is correctly configured to include `node_modules/@types` (usually by default) and a TypeScript version of 4.0 or higher.

• Metrics are not appearing in monitoring system.

  cause Incorrect host, port, protocol, or a firewall blocking UDP/TCP traffic to the StatsD agent.
  fix Double-check the `host`, `port`, and `protocol` options in your `hot-shots` client configuration. Verify that the StatsD agent is running and listening on the specified port and that no firewall rules are preventing communication.

Warnings

• breaking hot-shots officially supports Node.js version 18.x and higher. Running on older Node.js versions may lead to unexpected behavior or compatibility issues.
  Fix: Upgrade your Node.js environment to version 18.x or later.
• breaking When using TypeScript types, hot-shots requires TypeScript 4.0 or higher. Older TypeScript versions may not correctly interpret the provided type definitions.
  Fix: Upgrade your TypeScript compiler to version 4.0 or later.
• gotcha The `mock` option creates a mock StatsD instance with an internal buffer (`mockBuffer`) that stores all generated stats. This buffer continuously grows and is not automatically cleared, which can lead to excessive memory consumption if used in long-running tests or production environments.
  Fix: Only use `mock: true` for testing purposes and ensure `mockBuffer` is periodically cleared or reset if tests generate a large volume of metrics.
• gotcha The `tagPrefix` and `tagSeparator` configuration options are specifically designed for DogStatsD format and do not work when the `telegraf` option is enabled, as Telegraf uses a different tag serialization format.
  Fix: Avoid using `tagPrefix` or `tagSeparator` when configuring the client for Telegraf. Telegraf's tag handling is automatic based on its protocol.
• gotcha If `host` is not explicitly set in the client options, the constructor first attempts to retrieve it from the `DD_AGENT_HOST` environment variable. If `DD_AGENT_HOST` is also undefined, Node.js's `dgram` module defaults to `127.0.0.1` (IPv4) or `::1` (IPv6) for UDP/datagram sockets. This implicit default might not be the intended target for your StatsD agent.
  Fix: Always explicitly set the `host` option, or ensure `DD_AGENT_HOST` is correctly configured in your environment, to avoid metrics being sent to an unintended local address.

Install

• npm install hot-shots npm
• yarn add hot-shots yarn
• pnpm add hot-shots pnpm

Imports

• StatsD
  wrong:

  import { StatsD } from 'hot-shots';

  correct:

  import StatsD from 'hot-shots';

  StatsD is a default export. Attempting a named import for the main class will fail.
• StatsD (CommonJS)
  wrong:

  const { StatsD } = require('hot-shots');

  correct:

  const StatsD = require('hot-shots');

  For CommonJS, the module exports StatsD as the default. Destructuring will result in `undefined`.
• StatsDOptions
  wrong:

  import { StatsDOptions } from 'hot-shots';

  correct:

  import type { StatsDOptions } from 'hot-shots';

  Import types using `import type` for clarity and to ensure they are stripped from the JavaScript output.

Quickstart

Demonstrates initializing a StatsD client with common options, sending various metric types (increment, gauge, timer), and sending a DogStatsD event. It also includes proper client cleanup.

import StatsD, { StatsDOptions } from 'hot-shots';

const options: StatsDOptions = {
  host: process.env.STATSD_HOST ?? '127.0.0.1',
  port: parseInt(process.env.STATSD_PORT ?? '8125', 10),
  prefix: 'my_app.',
  globalTags: ['env:dev', 'service:api'],
  mock: false, // Set to true for testing without sending real metrics
  protocol: 'udp' // Or 'tcp', 'uds'
};

const client = new StatsD(options);

// Increment a counter
client.increment('requests.total');

// Gauge a value
client.gauge('memory.usage', process.memoryUsage().heapUsed);

// Time a function execution
const timer = client.startTimer();
setTimeout(() => {
  client.endTimer(timer, 'operation.duration');
}, 100);

// Send a custom event (DogStatsD specific)
client.event('Deployment Alert', 'New version deployed to production', {
  tags: ['version:1.0.1'],
  alert_type: 'success'
});

console.log('Metrics sent: requests.total, memory.usage, operation.duration, Deployment Alert');

// Best practice: close the client when the application shuts down
// For UDP, this might not be strictly necessary, but good for TCP/UDS.
process.on('SIGTERM', () => {
  client.close();
  console.log('StatsD client closed.');
});