Profiling Node.js with clinic.js and 0x

1# Install globally
2npm install -g clinic
3# or: npm install -g 0x  # alternative flamegraph tool
4
5# Profile your NestJS API while running k6 load test
6# Terminal 1: Start API with profiling
7clinic flame -- node dist/main.js
8
9# Terminal 2: Drive load for 60 seconds
10k6 run --vus 20 --duration 60s tests/perf/scenarios/load.js
11
12# After k6 finishes, Ctrl+C the clinic process
13# clinic.js generates an HTML flamegraph report
14clinic flame -- node dist/main.js
15# Opens: file:///tmp/my-app.clinic-flame-4231/flamegraph.html

1# Compile TypeScript
2pnpm build  # or: npx nest build
3
4# Profile compiled output
5clinic flame -- node dist/main.js
6
7# OR profile with ts-node for development
8clinic flame -- npx ts-node -r tsconfig-paths/register src/main.ts

1clinic doctor -- node dist/main.js
2# Generates a doctor report showing:
3# - Event loop delay over time
4# - CPU usage patterns
5# - Memory growth trends
6# - I/O throughput

1  ┌─────────────────────────────────────────────┐ ← application code (hot path)
2  │  JSON.parse (wide = expensive)             │
3  └─────────────────────────────────────────────┘
4     ┌────────────────┐
5     │ formatResponse │
6     └────────────────┘
7        ┌──────────┐
8        │ serialize│
9        └──────────┘
10           ┌──────────────────────────────────┐
11           │ handleRequest                    │
12           └──────────────────────────────────┘
13              ┌──────────────────────────────────────────┐
14              │ (anonymous) / router / express.Layer.handle│
15              └──────────────────────────────────────────┘
16                 ┌──────────────────────────────────────────────────────┐
17                 │ (platform internals — V8, libuv, node http_parser)   │
18                 └──────────────────────────────────────────────────────┘

1// BAD: fs.readFileSync blocks the event loop during load
2@Get('/config')
3getConfig() {
4  const data = fs.readFileSync('./config.json', 'utf8'); // BLOCKS
5  return JSON.parse(data);
6}
7
8// GOOD: async + cached
9const configCache = new Map<string, unknown>();
10
11@Get('/config')
12async getConfig() {
13  if (configCache.has('main')) return configCache.get('main');
14  const data = await fs.promises.readFile('./config.json', 'utf8');
15  const parsed = JSON.parse(data);
16  configCache.set('main', parsed);
17  return parsed;
18}

1// BAD: 20 awaits sequentially = 20x latency
2async getCourseDetails(ids: string[]) {
3  const results = [];
4  for (const id of ids) {
5    results.push(await this.courseService.findById(id)); // sequential!
6  }
7  return results;
8}
9
10// GOOD: Promise.all runs all in parallel
11async getCourseDetails(ids: string[]) {
12  return Promise.all(ids.map((id) => this.courseService.findById(id)));
13}

1// BAD: parse Redis JSON on every request
2async getUser(id: string) {
3  const raw = await redis.get(`user:${id}`);
4  return JSON.parse(raw); // expensive if called 1000x/second
5}
6
7// GOOD: use Redis OBJECT ENCODING or cache the parsed object in memory
8const parsedCache = new LRUCache<string, User>({ max: 1000, ttl: 30_000 });
9
10async getUser(id: string) {
11  if (parsedCache.has(id)) return parsedCache.get(id);
12  const raw = await redis.get(`user:${id}`);
13  const parsed = JSON.parse(raw);
14  parsedCache.set(id, parsed);
15  return parsed;
16}

1# Run with --expose-gc to enable manual GC in heap snapshots
2clinic doctor -- node --expose-gc dist/main.js

1// NestJS endpoint to capture heap snapshot during load testing
2import { Controller, Get, Res } from '@nestjs/common';
3import { Response } from 'express';
4import v8 from 'v8';
5import fs from 'fs';
6
7@Controller('debug')
8export class DebugController {
9  @Get('heap-snapshot')
10  // IMPORTANT: Only expose in development/staging, never production
11  captureHeap(@Res() res: Response) {
12    const filename = `heap-${Date.now()}.heapsnapshot`;
13    const writeStream = fs.createWriteStream(filename);
14    const session = new v8.Session();
15    session.connect();
16    session.post('HeapProfiler.takeHeapSnapshot', null, (err, chunk) => {
17      if (chunk?.chunk) writeStream.write(chunk.chunk);
18    });
19    session.on('HeapProfiler.addHeapSnapshotChunk', ({ params }) => {
20      writeStream.write(params.chunk);
21    });
22    // Load the .heapsnapshot file in Chrome DevTools Memory tab
23    // Look for objects that grow between two snapshots taken 5 minutes apart
24    res.json({ filename });
25  }
26}

1# clinic doctor shows event loop delay over time
2clinic doctor -- node dist/main.js
3# After load test: generates report with:
4# - Event loop delay timeline
5# - CPU usage (if >80% for sustained periods = CPU bottleneck)
6# - I/O wait (if high = database or file I/O bottleneck)

1// Measure event loop delay programmatically
2import { monitorEventLoopDelay } from 'perf_hooks';
3
4const histogram = monitorEventLoopDelay({ resolution: 20 });
5histogram.enable();
6
7// In your NestJS health check endpoint:
8@Get('health')
9getHealth() {
10  return {
11    status: 'ok',
12    eventLoopDelay: {
13      p50: histogram.percentile(50),   // median delay
14      p99: histogram.percentile(99),   // tail delay
15      max: histogram.max,
16    },
17    memoryMB: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
18    uptime: process.uptime(),
19  };
20}