# nestjs-monitoring

> debug assistant for the NestJS framework. It provides insight into the Requests coming into your application, Exceptions, Database queries and Jobs

Latest version **1.5.10** (published 2025-03-26) · ISC license · 0 weekly downloads

## Install

```sh
npm install nestjs-monitoring
pnpm add nestjs-monitoring
yarn add nestjs-monitoring
bun add nestjs-monitoring
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; large bundle.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.10 |
| Published | 2025-03-26 |
| First published | 2024-03-02 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 21 |
| Unpacked size | 15.7 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Aghiad Odeh |
| Maintainers | aghiadodeh |
| Keywords | NestJS, monitoring, monitor, mongoose, sequelize, database queries, requests, exceptions, jobs, logs, backend |

## Links

- npm: https://www.npmjs.com/package/nestjs-monitoring
- Repository: https://github.com/aghiadodeh/Nestjs-Monitoring
- Homepage: https://github.com/aghiadodeh/Nestjs-Monitoring#readme
- Issues: https://github.com/aghiadodeh/Nestjs-Monitoring/issues
- npm.io page: https://npm.io/package/nestjs-monitoring

## Dependencies (21)

- [bull](https://npm.io/package/bull.md) ^4.12.9
- [rxjs](https://npm.io/package/rxjs.md) ^7.8.1
- [mysql2](https://npm.io/package/mysql2.md) ^3.9.2
- [mongoose](https://npm.io/package/mongoose.md) ^8.1.3
- [passport](https://npm.io/package/passport.md) ^0.7.0
- [sequelize](https://npm.io/package/sequelize.md) ^6.37.1
- [@nestjs/jwt](https://npm.io/package/@nestjs/jwt.md) ^11.0.0
- [nestjs-i18n](https://npm.io/package/nestjs-i18n.md) ^10.5.0
- [@nestjs/bull](https://npm.io/package/@nestjs/bull.md) ^11.0.2
- [@nestjs/core](https://npm.io/package/@nestjs/core.md) ^11.0.10
- [passport-jwt](https://npm.io/package/passport-jwt.md) ^4.0.1
- [@nestjs/common](https://npm.io/package/@nestjs/common.md) ^11.0.10
- [class-validator](https://npm.io/package/class-validator.md) ^0.14.1
- [moment-timezone](https://npm.io/package/moment-timezone.md) ^0.5.45
- [@nestjs/mongoose](https://npm.io/package/@nestjs/mongoose.md) ^11.0.1
- [@nestjs/passport](https://npm.io/package/@nestjs/passport.md) ^11.0.5
- [@nestjs/sequelize](https://npm.io/package/@nestjs/sequelize.md) ^11.0.0
- [class-transformer](https://npm.io/package/class-transformer.md) ^0.5.1
- [@nestjs/serve-static](https://npm.io/package/@nestjs/serve-static.md) ^5.0.3
- [sequelize-typescript](https://npm.io/package/sequelize-typescript.md) ^2.1.6
- [@nestjs/event-emitter](https://npm.io/package/@nestjs/event-emitter.md) ^3.0.0

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 1.5.10 (latest) — 2025-03-26
- 1.5.9 — 2025-03-26
- 1.5.8 — 2025-03-26
- 1.5.7 — 2025-03-15
- 1.5.6 — 2025-03-15
- 1.5.5 — 2025-03-14
- 1.5.4 — 2025-03-14
- 1.5.3 — 2025-02-21
- 1.5.2 — 2025-02-21
- 1.5.1 — 2024-09-19
- 1.5.0 — 2024-07-04
- 1.4.9 — 2024-07-01
- 1.4.8 — 2024-06-28
- 1.4.6 — 2024-06-27
- 1.4.5 — 2024-06-27
- … 40 more at https://npm.io/package/nestjs-monitoring/versions

## README

# NestJs Monitoring
Debug assistant for the **NestJS** framework. It provides insight into the **Requests** coming into your application, **Exceptions**, **Database queries** and **Jobs**


## Screenshots:
| | |
|:-------------------------:|:-------------------------:|
|<img src="https://github.com/aghiadodeh/Nestjs-Monitoring-Dashboard/blob/main/screenshots/Analyze.png?raw=true">|<img src="https://github.com/aghiadodeh/Nestjs-Monitoring-Dashboard/blob/main/screenshots/Requests.png?raw=true">
|<img src="https://github.com/aghiadodeh/Nestjs-Monitoring-Dashboard/blob/main/screenshots/Request_Exception.png?raw=true">|<img src="https://github.com/aghiadodeh/Nestjs-Monitoring-Dashboard/blob/main/screenshots/DB.png?raw=true">
|<img src="https://github.com/aghiadodeh/Nestjs-Monitoring-Dashboard/blob/main/screenshots/Job.png?raw=true">|<img src="https://github.com/aghiadodeh/Nestjs-Monitoring-Dashboard/blob/main/screenshots/Request_Details.png?raw=true">


## Installation:
```shell
npm i nestjs-monitoring
```

## Usage:
**NestJs Monitoring** provide debugging through ***apis***, You can use it by:

* Use built-in package dashboard by accessing: `http://localhost:3000/monitoring`.
* Create your own dashboard using monitoring REST-APIs


## Setup:
package can be managed by `.env` file
```env
# enable call monitoring apis (ex: disable it in production environment)
MONITORING_APIS_ENABLED = 'true'

# enable monitoring with browser (dashboard)
MONITORING_DASHBOARD_ENABLED = 'true'

# require authentication to get monitoring data
MONITORING_AUTH_REQUIRED = 'true'

# authentication credentials
MONITORING_USERNAME = 'monitoring'
MONITORING_PASSWORD = '123456'
MONITORING_JWT_SECRET = '*******' # change with strong secret-key

# log all db queries in console
MONITORING_DB_LOG_ENABLED = 'true'

# save all db queries
MONITORING_DB_LOG_SAVE_ENABLED = 'true'

# save all requests traffic in application
MONITORING_REQUEST_SAVE_ENABLED = 'true'
```

And you must use the Monitoring `GlobalFilters` and exclude **Monitoring APIs** from `GlobalPrefix` in your `src/main.ts`:
```typescript
import { MonitoringExceptionFilter } from "nestjs-monitoring";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // add monitoring exception-filter
  app.useGlobalFilters(new MonitoringExceptionFilter());

  // global prefix `/api` is required
  app.setGlobalPrefix("api", {
    exclude: [{ path: "api/monitoring/*", method: RequestMethod.ALL }],
  });

  await app.listen(3000);
}

bootstrap();
```

If you want to get better performance for inserting logs, monitoring tool uses [Bull](https://www.npmjs.com/package/@nestjs/bull) to insert logs depending on queue.

[Bull](https://www.npmjs.com/package/@nestjs/bull) depends on Redis, so you need adding Redis config in your `.env` file:
```env
# monitoring redis config
MONITORING_REDIS_HOST="localhost"
MONITORING_REDIS_PORT=6379
```

## Access Monitoring Dashboard:
You can open built-in monitoring dashboard through

remote: `https://your-domain.com/monitoring`

localhost: `http://localhost:3000/monitoring`

## i18n:
This package use [NestJs-i18n](https://www.npmjs.com/package/nestjs-i18n) for translate the response message, for translate the string from json file successfully you must name your i18n json file with `i18n.json` inside your language folder:

    .
    ├── /node_modules
    ├── /src                    
    │   ├── /i18n          
    │   │    ├── /en                    
    │   │    │    ├── i18n.json # english translate json file
    │   │    ├── /fr       
    │   │    │    ├── i18n.json 
    │   └── main.ts               
    └── ...
 
## Setup Mongoose Monitoring:
Add DB config to `.env` file:
```env
# monitoring db config
MONITORING_DB_NAME = 'monitoring_db'
MONITORING_DB_USERNAME = ''
MONITORING_DB_PASSWORD = ''
MONITORING_MONGO_DB_URL = 'mongodb://127.0.0.1:27017'
```

add `MonitoringModule` to your `src/app.module.ts`:
```typescript
import { MonitoringModule, mongooseTrackingPlugin } from "nestjs-monitoring";
import { EventEmitterModule } from "@nestjs/event-emitter";
import { Connection } from "mongoose";

@Module({
  imports: [
    EventEmitterModule.forRoot(), // <-- add event-emitter
    MongooseModule.forRoot(process.env.MONGO_DB_URL, {
      user: process.env.DB_USERNAME,
      pass: process.env.DB_PASSWORD,
      dbName: process.env.DB_NAME,
      connectionFactory: (connection: Connection) => {
        connection.plugin(mongooseTrackingPlugin); // <-- add `mongooseTrackingPlugin` here for monitoring db
        return connection;
      }
    }),
    MonitoringModule.forRoot({ orm: 'mongoose' }), // <-- add mongoose here
    // ...,
  ],
})
export class AppModule {}
```

## Save Job Logs Manually:

You can create your own job for background operations:
```typescript
import { MongooseMonitoringJobService } from 'nestjs-monitoring';

@Injectable()
export class AuthenticationService {
    constructor(private mentoringJobService: MongooseMonitoringJobService) {}

    async sendVerificationCode(): Promise<void> {
        const number = "+1xxxxxxxxx";
        const code = "111111";
        try {
            await this.smsService.sendMessage(
                number,
                `Your verification code is: ${code}`,
            );
        } catch (error) {
            // add log for sending sms error
            this.mentoringJobService.create({
                name: "send-SMS",
                success: false,
                metadata: [
                    { number, code, datetime: new Date().toISOString() },
                    { error },
                ],
            });
        }
    }
}
```
Create Job params:

```typescript
interface ICreateJob {
    name: string; // tag of job
    success?: boolean; // default is true
    metadata: object[]; // array of results
};
```
## Clear Logs:
Logs take up a lot of storage space in a database, so you have to clear logs every period of time:

```typescript
import { MongooseMonitoringJobService } from "nestjs-monitoring";
import { Injectable } from "@nestjs/common";
import { Cron, CronExpression } from "@nestjs/schedule";

@Injectable()
export class LogsCronJob {
  constructor(private monitoringJobService: MongooseMonitoringJobService) {}

  // clear logs every day
  @Cron(CronExpression.EVERY_DAY_AT_1AM)
  async deleteAllLogs(): Promise<void> {
    await this.monitoringJobService.clearAll();
  }
}
```


## Monitoring APIs:
| API  | End point  |
|:----------|:----------|
| Authentication    | {{baseUrl}}/api/monitoring/authentication    |
| Analyze Requests    | {{baseUrl}}/api/monitoring/mongoose/requests/analyze    |
| Requests Log    | {{baseUrl}}/api/monitoring/mongoose/requests    |
| Jobs Log    | {{baseUrl}}/api/monitoring/mongoose/jobs    |
| Database Queries Log    | {{baseUrl}}/api/monitoring/mongoose/mongo-logs    |
<hr />

 
## Setup Sequelize Monitoring:

add `MonitoringModule` to your `src/app.module.ts`:
```typescript
import { MonitoringModule } from "nestjs-monitoring";

@Module({
  imports: [
    MonitoringModule.forRoot({ orm: 'sequelize' }), // <-- add sequelize here
    // ...,
  ],
})
export class AppModule {}
```

Add Sequelize Models to your SequelizeModule:
```typescript
import { SequelizeModule } from '@nestjs/sequelize';
import { SequelizeJobLog, SequelizeRequestLog, SequelizeDBLog } from "nestjs-monitoring";

export const sequelizeModule = () => SequelizeModule.forRoot({
    dialect: 'mysql',
    host: process.env.DB_HOST,
    port: +process.env.DB_PORT,
    // ...
    models: [
        // add models here
        SequelizeRequestLog,
        SequelizeJobLog,
        SequelizeDBLog,
        // ...
    ],
    // ...
});
```

## Save Job Logs Manually:

You can create your own job for background operations:
```typescript
import { SequelizeMonitoringJobService } from 'nestjs-monitoring';

@Injectable()
export class AuthenticationService {
    constructor(private mentoringJobService: SequelizeMonitoringJobService) {}

    async sendVerificationCode(): Promise<void> {
        const number = "+1xxxxxxxxx";
        const code = "111111";
        try {
            await this.smsService.sendMessage(
                number,
                `Your verification code is: ${code}`,
            );
        } catch (error) {
            // add log for sending sms error
            this.mentoringJobService.create({
                name: "send-SMS",
                success: false,
                metadata: [
                    { number, code, datetime: new Date().toISOString() },
                    { error },
                ],
            });
        }
    }
}
```
Create Job params:

```typescript
interface ICreateJob {
    name: string; // tag of job
    success?: boolean; // default is true
    metadata: object[]; // array of results
};
```
## Clear Logs:
Logs take up a lot of storage space in a database, so you have to clear logs every period of time:

```typescript
import { SequelizeMonitoringJobService } from "nestjs-monitoring";
import { Injectable } from "@nestjs/common";
import { Cron, CronExpression } from "@nestjs/schedule";

@Injectable()
export class LogsCronJob {
  constructor(private monitoringJobService: SequelizeMonitoringJobService) {}

  // clear logs every day
  @Cron(CronExpression.EVERY_DAY_AT_1AM)
  async deleteAllLogs(): Promise<void> {
    await this.monitoringJobService.clearAll();
  }
}
```


## Monitoring APIs:
| API  | End point  |
|:----------|:----------|
| Authentication    | {{baseUrl}}/api/monitoring/authentication    |
| Analyze Requests    | {{baseUrl}}/api/monitoring/sequelize/requests/analyze    |
| Requests Log    | {{baseUrl}}/api/monitoring/sequelize/requests    |
| Jobs Log    | {{baseUrl}}/api/monitoring/sequelize/jobs    |
| Database Queries Log    | {{baseUrl}}/api/monitoring/sequelize/db-logs    |
<hr />

---
_Source: https://npm.io/package/nestjs-monitoring · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._