{"id":16376,"library":"hot-shots","title":"Hot Shots StatsD Client","description":"Hot Shots is a robust and actively maintained Node.js client designed for sending metrics to StatsD, DogStatsD (Datadog), Telegraf, and OpenTelemetry Collector StatsD receivers. As of version 14.3.1, it provides comprehensive support for various protocols including UDP, Unix Domain Sockets (UDS), and TCP, catering to diverse deployment environments. The library differentiates itself from its `node-statsd` origin by offering advanced features such as TypeScript types, raw stream protocol, child clients for scoped metrics, mock mode for testing without real sockets, and asynchronous timer methods. It is regularly updated, with a stable release cadence, and requires Node.js 18.x or higher, and TypeScript 4.0+ for its type definitions. Its extensive configuration options allow for fine-grained control over host, port, prefixes, suffixes, global tags, and automatic Datadog tag inclusion from environment variables.","status":"active","version":"14.3.1","language":"javascript","source_language":"en","source_url":"git://github.com/bdeitte/hot-shots","tags":["javascript","statsd","dogstatsd","datadog","metrics","telegraf","backend","typescript"],"install":[{"cmd":"npm install hot-shots","lang":"bash","label":"npm"},{"cmd":"yarn add hot-shots","lang":"bash","label":"yarn"},{"cmd":"pnpm add hot-shots","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"StatsD is a default export. Attempting a named import for the main class will fail.","wrong":"import { StatsD } from 'hot-shots';","symbol":"StatsD","correct":"import StatsD from 'hot-shots';"},{"note":"For CommonJS, the module exports StatsD as the default. Destructuring will result in `undefined`.","wrong":"const { StatsD } = require('hot-shots');","symbol":"StatsD (CommonJS)","correct":"const StatsD = require('hot-shots');"},{"note":"Import types using `import type` for clarity and to ensure they are stripped from the JavaScript output.","wrong":"import { StatsDOptions } from 'hot-shots';","symbol":"StatsDOptions","correct":"import type { StatsDOptions } from 'hot-shots';"}],"quickstart":{"code":"import StatsD, { StatsDOptions } from 'hot-shots';\n\nconst options: StatsDOptions = {\n  host: process.env.STATSD_HOST ?? '127.0.0.1',\n  port: parseInt(process.env.STATSD_PORT ?? '8125', 10),\n  prefix: 'my_app.',\n  globalTags: ['env:dev', 'service:api'],\n  mock: false, // Set to true for testing without sending real metrics\n  protocol: 'udp' // Or 'tcp', 'uds'\n};\n\nconst client = new StatsD(options);\n\n// Increment a counter\nclient.increment('requests.total');\n\n// Gauge a value\nclient.gauge('memory.usage', process.memoryUsage().heapUsed);\n\n// Time a function execution\nconst timer = client.startTimer();\nsetTimeout(() => {\n  client.endTimer(timer, 'operation.duration');\n}, 100);\n\n// Send a custom event (DogStatsD specific)\nclient.event('Deployment Alert', 'New version deployed to production', {\n  tags: ['version:1.0.1'],\n  alert_type: 'success'\n});\n\nconsole.log('Metrics sent: requests.total, memory.usage, operation.duration, Deployment Alert');\n\n// Best practice: close the client when the application shuts down\n// For UDP, this might not be strictly necessary, but good for TCP/UDS.\nprocess.on('SIGTERM', () => {\n  client.close();\n  console.log('StatsD client closed.');\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18.x or later.","message":"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.","severity":"breaking","affected_versions":"<18.0.0"},{"fix":"Upgrade your TypeScript compiler to version 4.0 or later.","message":"When using TypeScript types, hot-shots requires TypeScript 4.0 or higher. Older TypeScript versions may not correctly interpret the provided type definitions.","severity":"breaking","affected_versions":"<4.0"},{"fix":"Only use `mock: true` for testing purposes and ensure `mockBuffer` is periodically cleared or reset if tests generate a large volume of metrics.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid using `tagPrefix` or `tagSeparator` when configuring the client for Telegraf. Telegraf's tag handling is automatic based on its protocol.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The configured host for the StatsD agent could not be resolved by DNS or is unreachable.","error":"Error: getaddrinfo ENOTFOUND <host>"},{"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.","cause":"Attempting to instantiate `StatsD` incorrectly due to CommonJS/ESM module mismatch or incorrect import syntax.","error":"TypeError: StatsD is not a constructor"},{"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.","cause":"TypeScript compiler cannot locate the type definitions for the `hot-shots` package.","error":"TS2307: Cannot find module 'hot-shots' or its corresponding type declarations."},{"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.","cause":"Incorrect host, port, protocol, or a firewall blocking UDP/TCP traffic to the StatsD agent.","error":"Metrics are not appearing in monitoring system."}],"ecosystem":"npm"}