Registry / observability / nestjs-hot-shots

nestjs-hot-shots

library4.0.0jsnpmunverified

The nestjs-hot-shots package provides a dedicated module for integrating the `hot-shots` (StatsD client) library into NestJS applications. It simplifies sending metrics to StatsD, DogStatsD, or Telegraf servers. Currently stable at version 4.0.0 (released January 2026), it typically sees releases aligning with major NestJS versions or significant feature additions/bug fixes. Key differentiators include full TypeScript support, out-of-the-box integration for common NestJS patterns like dependency injection for the `StatsD` client, a dedicated `MetricsService` for creating various metric types (counters, gauges, histograms), and a convenient `HttpMetricsMiddleware` for automated HTTP request metric collection. This module abstracts much of the boilerplate associated with setting up and using a StatsD client in a NestJS project, offering a streamlined experience for metric reporting.

observability web-framework

npm install nestjs-hot-shots

github ↗package ↗

INSTALL

IMPORT

SIG · NESTJS-HOT-SHOTS

nestjs-hot-shots

observabilityjavascriptv4.0.0

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.

HotShotsModule

✓ import { HotShotsModule } from 'nestjs-hot-shots';

✗ const HotShotsModule = require('nestjs-hot-shots').HotShotsModule;

Used for module registration, typically with `.forRoot()` or `.register()`.

StatsD (client)

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

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

This is the core StatsD client type and class from the `hot-shots` package itself, which is then injected by the NestJS module.

MetricsService

✓ import { MetricsService } from 'nestjs-hot-shots';

✗ const MetricsService = require('nestjs-hot-shots').MetricsService;

A NestJS-specific service for conveniently creating and managing various metric types (counters, gauges, etc.).

HttpMetricsMiddleware

✓ import { HttpMetricsMiddleware } from 'nestjs-hot-shots';

✗ const HttpMetricsMiddleware = require('nestjs-hot-shots').HttpMetricsMiddleware;

A NestJS middleware for automatically collecting HTTP request and response metrics.

Demonstrates how to configure the `HotShotsModule` with environment variables, inject the underlying `StatsD` client, use the `MetricsService` for custom metrics, and apply `HttpMetricsMiddleware` for automated HTTP request tracking.

import { Injectable, Module, MiddlewareConsumer, NestModule } from '@nestjs/common'; import { HotShotsModule, MetricsService, HttpMetricsMiddleware } from 'nestjs-hot-shots'; import { StatsD } from 'hot-shots'; @Injectable() export class AppMetrics { private readonly processedEventsCounter; public constructor( private readonly metricsClient: StatsD, private readonly metricsService: MetricsService ) { this.processedEventsCounter = this.metricsService.getCounter('app.events.processed'); } public recordEventProcessed() { this.metricsClient.increment('app.custom_metric'); this.processedEventsCounter.add(); } public sendGauge(value: number) { this.metricsClient.gauge('app.current_value', value); } } @Module({ imports: [ HotShotsModule.forRoot({ host: process.env.STATSD_HOST ?? '127.0.0.1', port: parseInt(process.env.STATSD_PORT ?? '8125', 10), globalTags: { env: process.env.NODE_ENV ?? 'development', service: 'my-nest-app' }, // Optional: Enable mock mode for testing without a StatsD server mock: process.env.NODE_ENV === 'test' }) ], providers: [AppMetrics], exports: [AppMetrics] }) export class AppModule implements NestModule { public configure(consumer: MiddlewareConsumer) { consumer .apply(HttpMetricsMiddleware) .forRoutes('*'); // Apply HTTP metrics middleware to all routes } } // Example usage (e.g., in main.ts or another module) // async function bootstrap() { // const app = await NestFactory.create(AppModule); // const appMetrics = app.get(AppMetrics); // appMetrics.recordEventProcessed(); // appMetrics.sendGauge(42); // await app.listen(3000); // } // bootstrap();

Debug

Known issues

breakingVersion 4.0.0 introduces updated peer dependency requirements, including `hot-shots: ^12.0.0` and NestJS versions `^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0`. Ensure your project's `hot-shots` and NestJS core packages are updated to compatible versions.

fix

Update `hot-shots` to `^12.0.0` and your NestJS packages (`@nestjs/common`, `@nestjs/core`) to a compatible version (e.g., 10.x or 11.x) in your `package.json` and reinstall dependencies.

affects: >=4.0.0

breakingVersion 4.0.0 also includes a fix 'remove project field due project service dominating'. This implies that if you were previously configuring a 'project' field in your module options, it might be ignored or behave differently.

fix

Review your `HotShotsModule.forRoot()` configuration. If you were using a `project` field for service naming, consider consolidating service-level tagging into `globalTags` or adjusting your metrics naming strategy.

affects: >=4.0.0

breakingVersion 2.0.0 refactored the internal implementation 'from service to provider'. This change likely affected how the `StatsD` client was injected or accessed, potentially breaking applications that relied on specific service class names.

fix

Migrate your application to use direct `StatsD` injection (from `hot-shots`) or the provided `MetricsService` instead of any deprecated `StatsDService` or similar. Refer to the current usage examples.

affects: >=2.0.0 <3.0.0

gotchaThe `nestjs-hot-shots` package is an integration layer; you still need to install the core `hot-shots` library separately.

fix

Always run `npm install nestjs-hot-shots hot-shots` (or `yarn add` / `pnpm add`) to ensure both packages are present.

affects: >=1.0.0

Errors

Common errors & fixes

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

The core `hot-shots` library is not installed.

fix

Run `npm install hot-shots` or `yarn add hot-shots`.

Nest can't resolve dependencies of the StatsD (?). Please make sure that the argument StatsD at index [0] is available in the HotShotsModule context.

The `HotShotsModule` has not been correctly registered or initialized using `.forRoot()` or `.register()`, preventing `StatsD` from being provided via DI.

fix

Ensure `HotShotsModule.forRoot(...)` is included in the `imports` array of your root or feature module, providing valid configuration options.

Property 'getCounter' does not exist on type 'StatsD'.

Attempting to call methods from `MetricsService` directly on the injected `StatsD` client.

fix

If you intend to use the higher-level metric creation methods, inject `MetricsService` from `nestjs-hot-shots`. The `StatsD` client provides direct `increment`, `gauge`, etc., methods.

Type 'AppModule' is not assignable to type 'NestModule'. Property 'configure' is missing in type 'AppModule' but required in type 'NestModule'.

You declared `AppModule implements NestModule` but did not implement the `configure(consumer: MiddlewareConsumer)` method or incorrectly typed it.

fix

Add the `configure` method to your `AppModule` with the correct signature: `public configure(consumer: MiddlewareConsumer) { ... }`.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

hot-shotsrequiredThe underlying StatsD client library that this NestJS module integrates.

@nestjs/commonrequiredCore NestJS framework dependency.

@nestjs/corerequiredCore NestJS framework dependency.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/SocketSomeone/nestjs-hot-shots ↗

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