nestwatch-sdk

Open-source Application Performance Monitoring SDK for NestJS

What is NestWatch?

NestWatch is a free, open-source APM (Application Performance Monitoring) tool designed specifically for NestJS applications. It provides:

• 📊 Real-time Metrics - Request rates, latency percentiles, error rates
• 🔍 Distributed Tracing - Track requests across your services
• 🔗 Dependency Graph - Visualize module relationships
• 🛤️ Route Discovery - Auto-detect all HTTP endpoints
• 🚨 Alerting - Get notified when issues occur

Installation

npm install nestwatch-sdk

or with yarn:

yarn add nestwatch-sdk

Quick Start

1. Import and Configure

// app.module.ts
import { Module } from '@nestjs/common';
import { NestWatchModule } from 'nestwatch-sdk';

@Module({
  imports: [
    NestWatchModule.forRoot({
      serviceName: 'my-api',           // Required: Your service name
      collectorUrl: 'http://localhost:4317', // Collector URL
      debug: true,                     // Enable debug logging
    }),
    // ... other modules
  ],
})
export class AppModule {}

2. Start the Collector

The SDK sends telemetry data to a NestWatch Collector:

# Clone and run the collector
git clone https://github.com/UGilfoyle/nestjs-monitor.git
cd nestjs-monitor
docker-compose up -d
pnpm dev

3. View Your Dashboard

Open http://localhost:3100 to see your service metrics!

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | serviceName | string | required | Unique identifier for your service | | collectorUrl | string | http://localhost:4317 | URL of the NestWatch collector | | version | string | 1.0.0 | Service version (shown in dashboard) | | environment | string | development | Environment name | | debug | boolean | false | Enable verbose logging | | enabled | boolean | true | Enable/disable SDK | | resourceAttributes | object | {} | Additional OpenTelemetry attributes |

Advanced Configuration

Async Configuration

NestWatchModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    serviceName: config.get('SERVICE_NAME'),
    collectorUrl: config.get('COLLECTOR_URL'),
    debug: config.get('NODE_ENV') === 'development',
  }),
  inject: [ConfigService],
});

Custom Decorators

@Trace() Decorator

Add tracing to any method:

import { Trace } from 'nestwatch-sdk';

@Injectable()
export class UserService {
  @Trace('fetch-user')
  async findOne(id: string) {
    return this.userRepo.findOne(id);
  }
}

@Metric() Decorator

Record custom metrics:

import { Metric } from 'nestwatch-sdk';

@Injectable()
export class PaymentService {
  @Metric('payment.processed', { type: 'counter' })
  async processPayment(amount: number) {
    // Payment logic
  }
}

What Data is Collected?

| Data Type | Description | |-----------|-------------| | Traces | HTTP requests, method calls with timing | | Metrics | Request rate, latency, error rate | | Module Graph | NestJS module dependencies | | Routes | All HTTP endpoints with metadata |

Dashboard Features

• Overview - Service health at a glance
• Traces - Request waterfall visualization
• Metrics - Time-series graphs (P50/P95/P99)
• Dependency Graph - Interactive module visualization
• Route Explorer - All endpoints with guards/interceptors

Self-Hosting

NestWatch is designed to be self-hosted. You need:

1. Collector (NestJS backend) - Ingests telemetry
2. Dashboard (Next.js frontend) - Visualizes data
3. PostgreSQL - Stores telemetry data

See the main repository for deployment instructions.

Requirements

• NestJS 10.x or higher
• Node.js 18.x or higher

License

MIT License - Free for personal and commercial use.

Links

• GitHub Repository
• npm Package
• Report Issues