hot-shots

library14.3.1jsnpmunverified

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.

observability devops http-networking testing

npm install hot-shots

github ↗package ↗

INSTALL

IMPORT

SIG · HOT-SHOTS

hot-shots

observabilityjavascriptv14.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StatsD

✓ import StatsD from 'hot-shots';

✗ import { StatsD } from 'hot-shots';

StatsD is a default export. Attempting a named import for the main class will fail.

StatsD (CommonJS)

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

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

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

StatsDOptions

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

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

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

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.'); });

Debug

Known issues

breakinghot-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.

affects: <18.0.0

breakingWhen 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.

affects: <4.0

gotchaThe `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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaIf `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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: getaddrinfo ENOTFOUND <host>

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

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.

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.

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.

Upgrade

Version history

14.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bdeitte/hot-shots ↗

packagehttps://www.npmjs.com/package/hot-shots ↗