feat: add http metrics

Author: SocketSomeone

README.md

@@ -2,7 +2,9 @@
 
 <img align="right" width="95" height="148" title="NestJS logotype" src="https://nestjs.com/img/logo-small.svg"  alt='Nest.JS logo'/>
 
-Hot-shots Module for Nest.js Framework. A Node.js client for [Etsy](http://etsy.com)'s [StatsD](https://github.com/statsd/statsd) server, Datadog's [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?tab=hostagent) server, and [InfluxDB's](https://github.com/influxdata/telegraf) Telegraf
+Hot-shots Module for Nest.js Framework. A Node.js client for [Etsy](http://etsy.com)'s [StatsD](https://github.com/statsd/statsd) server,
+Datadog's [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?tab=hostagent) server,
+and [InfluxDB's](https://github.com/influxdata/telegraf) Telegraf
 StatsD server.
 
 **Features**
@@ -64,6 +66,79 @@ export class AppMetrics {
 }
 ```
 
+### Metrics
+
+You can use the `MetricsService` for metrics collection. It`s factory for creating metrics. It provides a set of methods to create different
+types of metrics, such as counters, gauges, and histograms.
+
+```typescript
+import { Controller, Post } from '@nestjs/common';
+import { MetricsService } from 'nestjs-hot-shots';
+import { StatsD } from 'hot-shots';
+
+@Controller
+export class BooksController {
+    private readonly booksAdded = this.metricsService.getCounter('books.added.count');
+
+    public constructor(private readonly metricsService: MetricsService) {
+    }
+
+    @Post()
+    public async addBook() {
+        // some logic
+        this.booksAdded.add();
+    }
+}
+```
+
+| Method                           | Description                                            |
+|----------------------------------|--------------------------------------------------------|
+| `getCounter(name: string)`       | Returns a counter metric with the given name.          |
+| `getGauge(name: string)`         | Returns a gauge metric with the given name.            |
+| `getHistogram(name: string)`     | Returns a histogram metric with the given name.        |
+| `getTimer(name: string)`         | Returns a timer metric with the given name.            |
+| `getUpDownCounter(name: string)` | Returns an up-down counter metric with the given name. |
+
+### HTTP Metrics via Middleware
+
+You can use the `HttpMetricsMiddleware` to collect HTTP metrics. It will automatically collect metrics for all incoming requests and
+outgoing responses.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { HotShotsModule } from 'nestjs-hot-shots';
+import { HttpMetricsMiddleware } from 'nestjs-hot-shots';
+
+@Module({
+    imports: [
+        HotShotsModule.forRoot({
+            ...
+        })
+    ]
+})
+export class AppModule {
+    public configure(consumer: MiddlewareConsumer) {
+        consumer
+            .apply(HttpMetricsMiddleware)
+            .forRoutes('*');
+    }
+}
+```
+
+| Metric                               | Description                                     | Type      |
+|--------------------------------------|-------------------------------------------------|-----------|
+| `http_server_request_count`          | Total number of requests received by the server | Counter   |
+| `http_server_response_count`         | Total number of responses sent by the server    | Counter   |
+| `http_server_duration`               | Total time taken to process requests            | Histogram |
+| `http_server_request_size`           | Size of incoming bytes.                         | Histogram |
+| `http_server_response_size`          | Size of outgoing bytes.                         | Histogram |
+| `http_server_response_success_count` | Total number of all successful responses.       | Counter   |
+| `http_server_response_error_count`   | Total number of server error responses.         | Counter   |
+| `http_client_request_error_count`    | Total number of client error requests.          | Counter   |
+| `http_server_abort_count`            | Total number of aborted requests                | Counter   |
+
+> Inspired by [nestjs-otel](https://github.com/pragmaticivan/nestjs-otel)
+
 See the [hot-shots](https://www.npmjs.com/package/hot-shots) module for more details.
 
 ## Stay in touch

package.json

@@ -39,7 +39,9 @@
 	"contributors": [
 		"Alexey Filippov <socket.someone@gmail.com>"
 	],
-	"dependencies": {},
+	"dependencies": {
+		"response-time": "^2.3.3"
+	},
 	"devDependencies": {
 		"@commitlint/cli": "19.8.0",
 		"@commitlint/config-angular": "19.8.0",
@@ -48,10 +50,13 @@
 		"@favware/npm-deprecate": "2.0.0",
 		"@nestjs/common": "11.0.20",
 		"@nestjs/core": "11.0.20",
+		"@nestjs/platform-express": "^11.0.20",
 		"@nestjs/testing": "^11.0.20",
 		"@release-it/conventional-changelog": "^10.0.0",
 		"@types/jest": "^29.5.14",
 		"@types/node": "22.14.1",
+		"@types/response-time": "^2.3.8",
+		"@types/supertest": "^6.0.3",
 		"eslint": "^9.18.0",
 		"eslint-config-prettier": "10.1.2",
 		"eslint-plugin-import": "^2.31.0",
@@ -65,6 +70,7 @@
 		"release-it": "18.1.2",
 		"rimraf": "6.0.1",
 		"rxjs": "7.8.2",
+		"supertest": "^7.1.0",
 		"ts-jest": "^29.3.2",
 		"typescript": "5.8.3",
 		"typescript-eslint": "^8.21.0"

src/index.ts

@@ -1,3 +1,4 @@
 export * from './metrics';
+export * from './middlewares';
 export * from './hot-shots.module';
 export * from './hot-shots-options.interface';

src/middlewares/http-metrics.middleware.ts

@@ -0,0 +1,96 @@
+import * as urlParser from 'url';
+import * as responseTime from 'response-time';
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { MetricsService } from '../metrics';
+
+@Injectable()
+export class HttpMetricsMiddleware implements NestMiddleware {
+	private httpServerRequestCount = this.metricsService.getCounter('http_server_request_count');
+
+	private httpServerResponseCount = this.metricsService.getCounter('http_server_response_count');
+
+	private httpServerDuration = this.metricsService.getHistogram('http_server_duration');
+
+	private httpServerRequestSize = this.metricsService.getHistogram('http_server_request_size');
+
+	private httpServerResponseSize = this.metricsService.getHistogram('http_server_response_size');
+
+	private httpServerResponseSuccessCount = this.metricsService.getCounter(
+		'http_server_response_success_count'
+	);
+
+	private httpServerResponseErrorCount = this.metricsService.getCounter(
+		'http_server_response_error_count'
+	);
+
+	private httpClientRequestErrorCount = this.metricsService.getCounter(
+		'http_client_request_error_count'
+	);
+
+	private httpServerAbortCount = this.metricsService.getCounter('http_server_abort_count');
+
+	public constructor(private readonly metricsService: MetricsService) {}
+
+	use(req: any, res: any, next: (error?: any) => void) {
+		responseTime((req: any, res: any, time: number) => {
+			const { route, url, method } = req;
+			let path;
+
+			if (route) {
+				path = route.path;
+			} else {
+				path = urlParser.parse(url).pathname;
+			}
+
+			this.httpServerRequestCount.add(1, { method, path });
+
+			const requestLength = parseInt(req.headers['content-length'], 10) || 0;
+			const responseLength: number = parseInt(res.getHeader('Content-Length'), 10) || 0;
+
+			const status = res.statusCode || 500;
+			const attributes = {
+				method,
+				status,
+				path
+			};
+
+			this.httpServerRequestSize.record(requestLength, attributes);
+			this.httpServerResponseSize.record(responseLength, attributes);
+
+			this.httpServerResponseCount.add(1, attributes);
+			this.httpServerDuration.record(time, attributes);
+
+			const codeClass = this.getStatusCodeClass(status);
+
+			switch (codeClass) {
+				case 'success':
+					this.httpServerResponseSuccessCount.add(1);
+					break;
+				case 'redirect':
+					// TODO: Review what should be appropriate for redirects.
+					this.httpServerResponseSuccessCount.add(1);
+					break;
+				case 'client_error':
+					this.httpClientRequestErrorCount.add(1);
+					break;
+				case 'server_error':
+					this.httpServerResponseErrorCount.add(1);
+					break;
+			}
+
+			req.on('end', () => {
+				if (req.aborted === true) {
+					this.httpServerAbortCount.add(1);
+				}
+			});
+		})(req, res, next);
+	}
+
+	private getStatusCodeClass(code: number): string {
+		if (code < 200) return 'info';
+		if (code < 300) return 'success';
+		if (code < 400) return 'redirect';
+		if (code < 500) return 'client_error';
+		return 'server_error';
+	}
+}

src/middlewares/index.ts

@@ -0,0 +1 @@
+export * from './http-metrics.middleware';

test/metrics/collectors/counter.collector.spec.ts

@@ -21,34 +21,34 @@ describe('CounterCollector', () => {
 	});
 
 	it('should create CounterCollector', () => {
-		const instance = metricsService.getCounter('test.metric');
+		const instance = metricsService.getCounter('test_metric');
 		expect(instance).toBeDefined();
 		expect(instance).toBeInstanceOf(CounterCollector);
 	});
 
 	it('should increment counter', () => {
-		const instance = metricsService.getCounter('test.metric');
+		const instance = metricsService.getCounter('test_metric');
 		instance.add(1);
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:1|c');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:1|c');
 	});
 
 	it('should increment counter with tags', () => {
-		const instance = metricsService.getCounter('test.metric');
+		const instance = metricsService.getCounter('test_metric');
 		instance.add(1, { tag1: 'value1', tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:1|c|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:1|c|#tag1:value1,tag2:value2');
 	});
 
 	it('should increment counter with merge tags', () => {
-		const instance = metricsService.getCounter('test.metric', { tags: { tag1: 'value1' } });
+		const instance = metricsService.getCounter('test_metric', { tags: { tag1: 'value1' } });
 		instance.add(1, { tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:1|c|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:1|c|#tag1:value1,tag2:value2');
 	});
 
 	it('should throw error when incrementing with negative value', () => {
-		const instance = metricsService.getCounter('test.metric');
+		const instance = metricsService.getCounter('test_metric');
 		expect(() => instance.add(-1)).toThrowError('Counter value cannot be negative');
 	});
 

test/metrics/collectors/gauge.collector.spec.ts

@@ -20,30 +20,30 @@ describe('GaugeCollector', () => {
 	});
 
 	it('should create GaugeCollector', () => {
-		const instance = metricsService.getGauge('test.metric');
+		const instance = metricsService.getGauge('test_metric');
 		expect(instance).toBeDefined();
 		expect(instance).toBeInstanceOf(GaugeCollector);
 	});
 
 	it('should set gauge value', () => {
-		const instance = metricsService.getGauge('test.metric');
+		const instance = metricsService.getGauge('test_metric');
 		instance.set(10);
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|g');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|g');
 	});
 
 	it('should set gauge value with tags', () => {
-		const instance = metricsService.getGauge('test.metric');
+		const instance = metricsService.getGauge('test_metric');
 		instance.set(10, { tag1: 'value1', tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|g|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|g|#tag1:value1,tag2:value2');
 	});
 
 	it('should set gauge value with merge tags', () => {
-		const instance = metricsService.getGauge('test.metric', { tags: { tag1: 'value1' } });
+		const instance = metricsService.getGauge('test_metric', { tags: { tag1: 'value1' } });
 		instance.set(10, { tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|g|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|g|#tag1:value1,tag2:value2');
 	});
 
 	afterEach(() => {

test/metrics/collectors/histogram.collector.spec.ts

@@ -20,30 +20,30 @@ describe('HistogramCollector', () => {
 	});
 
 	it('should create HistogramCollector', () => {
-		const instance = metricsService.getHistogram('test.metric');
+		const instance = metricsService.getHistogram('test_metric');
 		expect(instance).toBeDefined();
 		expect(instance).toBeInstanceOf(HistogramCollector);
 	});
 
 	it('should record histogram value', () => {
-		const instance = metricsService.getHistogram('test.metric');
+		const instance = metricsService.getHistogram('test_metric');
 		instance.record(10);
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|h');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|h');
 	});
 
 	it('should record histogram value with tags', () => {
-		const instance = metricsService.getHistogram('test.metric');
+		const instance = metricsService.getHistogram('test_metric');
 		instance.record(10, { tag1: 'value1', tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|h|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|h|#tag1:value1,tag2:value2');
 	});
 
 	it('should record histogram value with merge tags', () => {
-		const instance = metricsService.getHistogram('test.metric', { tags: { tag1: 'value1' } });
+		const instance = metricsService.getHistogram('test_metric', { tags: { tag1: 'value1' } });
 		instance.record(10, { tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|h|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|h|#tag1:value1,tag2:value2');
 	});
 
 	afterEach(() => {

test/metrics/collectors/timing.collector.spec.ts

@@ -20,30 +20,30 @@ describe('TimingCollector', () => {
 	});
 
 	it('should create TimingCollector', () => {
-		const instance = metricsService.getTiming('test.metric');
+		const instance = metricsService.getTiming('test_metric');
 		expect(instance).toBeDefined();
 		expect(instance).toBeInstanceOf(TimingCollector);
 	});
 
 	it('should record timing value', () => {
-		const instance = metricsService.getTiming('test.metric');
+		const instance = metricsService.getTiming('test_metric');
 		instance.record(10);
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|ms');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|ms');
 	});
 
 	it('should record timing value with tags', () => {
-		const instance = metricsService.getTiming('test.metric');
+		const instance = metricsService.getTiming('test_metric');
 		instance.record(10, { tag1: 'value1', tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|ms|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|ms|#tag1:value1,tag2:value2');
 	});
 
 	it('should record timing value with merge tags', () => {
-		const instance = metricsService.getTiming('test.metric', { tags: { tag1: 'value1' } });
+		const instance = metricsService.getTiming('test_metric', { tags: { tag1: 'value1' } });
 		instance.record(10, { tag2: 'value2' });
 
-		expect(statsD.mockBuffer[0]).toBe('test.metric:10|ms|#tag1:value1,tag2:value2');
+		expect(statsD.mockBuffer[0]).toBe('test_metric:10|ms|#tag1:value1,tag2:value2');
 	});
 
 	afterEach(() => {