NestScope

Telescope-inspired observability for NestJS applications. NestScope plugs into any Nest app to capture inbound requests, exceptions, database queries, queues, cron jobs, events, outbound HTTP, mailers, and more, with a zero-config dashboard, live stream, and export CLI.

Feature Highlights

• Request/response logging with correlation IDs and session snapshotting
• Exception and throttle filters wired to Nest's pipeline
• TypeORM query listener with duplicate detection and timing metrics
• Bull queue lifecycle logging (active/completed/failed)
• Cron, event-emitter, Axios, mailer, and WebSocket integrations out of the box
• Realtime dashboard at /nestscope (SSE or Socket.IO)
• CLI exporter (npx nestscope export) for JSON/CSV dumps
• Optional admin guard (x-nestscope-key) and toggleable logging hooks

Installation

npm install nestscope
npm install @nestjs/websockets @nestjs/platform-socket.io socket.io
npm i --save @nestjs/event-emitter
npm install --save @nestjs/schedule

# or: pnpm add nestscope
# or: yarn add nestscope

Peer dependencies: NestJS 11, TypeORM 0.3, Axios 1.x, Socket.IO 4.x, etc. Ensure the versions in your host app satisfy the peer requirements defined in package.json.

Quick Start (Host App)

1. Install required Nest integrations

   npm install @nestjs/schedule @nestjs/event-emitter @nestjs/websockets @nestjs/platform-socket.io

   These packages back NestScope's cron jobs, domain events, and realtime dashboard streaming.

2. Import the module

   import { Module } from '@nestjs/common';
   import { ScheduleModule } from '@nestjs/schedule';
   import { EventEmitterModule } from '@nestjs/event-emitter';
   import { NestScopeTypeOrmLogger } from 'nestscope';
   import { NestScopeModule } from 'nestscope';
   
   @Module({
     imports: [
       ScheduleModule.forRoot(),
       EventEmitterModule.forRoot(),
       NestScopeModule,
       // ...your modules
     ],
   })
   export class AppModule {}

3. Wire NestScope into TypeORM logging Enable query logging so NestScope can associate SQL statements with the request that triggered them.

   import { TypeOrmModule } from '@nestjs/typeorm';
   import { NestScopeTypeOrmLogger } from 'nestscope';
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         // ...your existing options
         logging: ['error', 'warn', 'query'],   // ensure TypeORM emits query events
         logger: new NestScopeTypeOrmLogger(),  // forward events to NestScope
       }),
       NestScopeModule,
       // ...
     ],
   })
   export class AppModule {}

4. Expose the dashboard (already handled by the module). Visit:

   http://localhost:3000/nestscope

5. Secure access (recommended for production):

   • Set NESTSCOPE_ADMIN_KEY=secret to require an x-nestscope-key header.
   • Set DISABLE_NESTSCOPE_GUARD=true during local development if you want to bypass the guard entirely.

6. Optional environment toggles

   • NESTSCOPE_CRON_EXAMPLE_ENABLED=true to enable the sample cron logger.
   • Add your own guard or configuration checks if you want to disable logging middleware in certain environments.

Captured Signals

• HTTP lifecycle: inbound requests, responses, bodies (respecting filters), headers, and correlation IDs.
• Exceptions: uncaught errors, HTTP exceptions, and throttling events via the bundled filters.
• TypeORM: queries, timings, duplicates, and slow query warnings through NestScopeTypeOrmLogger.
• Queues: Bull queue state changes (waiting, active, completed, failed, stalled) with payload previews.
• Cron jobs: schedule begins, completions, and failures provided by @nestjs/schedule.
• Domain events: anything emitted through @nestjs/event-emitter.
• Outbound HTTP/Mailer: Axios interceptors and mailer transport activity.
• WebSockets: gateway connect/disconnect, rooms, and message payloads when Socket.IO is enabled.

Configuration Reference

These environment variables are inspected by the bundled guard and sample cron job. You can also wire your own configuration service and pass options to the module factories if you fork the package.

| Option | Default | Description | | --- | --- | --- | | NESTSCOPE_ADMIN_KEY | unset | When set, requires an x-nestscope-key header for every dashboard/API request. | | DISABLE_NESTSCOPE_GUARD | false | Bypass the admin guard entirely (useful for local development). | | NESTSCOPE_CRON_EXAMPLE_ENABLED | false | Enables the bundled cron example so you can verify scheduler instrumentation quickly. |

To mount the dashboard on a custom path or adjust storage, adapt the controller routes or fork the module—every provider is exported so you can integrate with an existing persistence layer.

Dashboard Overview

• Filters: Apply/reset filters for log type, method, status, user, date range, and minimum duration. The buttons trigger immediate reloads and can clear stored logs.
• Metrics: Displays recent averages, error rates, and totals.
• Detail drawer: Click a row to open overview, payload tabs, related logs, middleware pipeline, and memory usage (RSS with system percentage, heap breakdown, etc.).
• Realtime: Uses Socket.IO when available, falls back to SSE, or polls if both are unavailable or if an admin key is set.

CLI Exporter

npx nestscope export \
  --api=http://localhost:3000/nestscope \
  --format=csv \
  --type=request \
  --since=2025-01-01

Available flags:

• --api (default http://localhost:3000/nestscope)
• --format (json | csv, default json)
• --type (request, exception, query, etc.)
• --since (ISO date string)

Security Notes

• Always gate the dashboard and stream routes in production (use the built-in guard or wrap with your own auth).
• Logs may contain payloads, headers, and session data, so sanitize or mask sensitive fields.
• The export CLI respects any auth that /nestscope/logs enforces; forward headers via a proxy or custom script if you need to automate exports.

Developing the Library

The repository is structured so nestscope/ can be published as a standalone package.

1. Clone or split the nestscope/ folder into its own repo.
2. Install and build:

   npm install
   npm run build  # emits dist/

3. Link locally when testing inside another Nest app:

   # inside nestscope/
   npm link
   # inside your host project
   npm link nestscope

4. Publish (optional):

   npm publish        # public or private registry
   npm pack           # produces nestscope-x.y.z.tgz

package.json already includes the right files entries. Bump the version before publishing and keep peer dependency ranges aligned with supported NestJS releases.

Troubleshooting

• Dashboard loads without data: Ensure NestScopeModule is imported only once and that interceptors are not overridden by custom global providers. Verify the admin key header when security is enabled.
• Socket.IO connection errors: Confirm @nestjs/websockets and @nestjs/platform-socket.io are installed and that CORS allows websockets from your client origin.
• TypeORM logs missing: Replace any custom TypeORM logger with new NestScopeTypeOrmLogger() or register it through the NestScope integration helpers.
• Large payloads trimmed: Increase limits with NESTSCOPE_MAX_BODY_SIZE (coming soon) or customize the sanitizer pipeline in your app bootstrap.

Integrating in Another Project

npm install nestscope

Import NestScopeModule as shown in the quick start. Everything else - middleware, filters, TypeORM logger, CLI - is exported via src/index.ts.

Roadmap

• Elastic/Loki exporter
• Cloud storage connectors (S3, BigQuery)
• Fine-grained field masking and retention policies
• Optional integrations for Prisma, MikroORM, and other ORMs

Contributions and issues are welcome! Open a ticket with ideas, bugs, or feature requests.