Kurs NestJS · Moduł 8: Cache i wydajność

Profiling i Benchmarking NestJS - diagnostyka mocy Imperium

8 min czytania ·
W tej lekcji5

Dowódco legionów! Po wdrożeniu użytkownicy piszą, że „jest wolniej”, a zespół spiera się, czy winna jest baza, nowy interceptor czy serializacja. Każdy ma teorię, nikt nie ma liczb. Nawet najlepiej wyszkolona armia rzymska potrzebuje regularnych przeglądów - w NestJS profiling i benchmarking to taka inspekcja: diagnozujesz, gdzie aplikacja traci czas, pamięć i zasoby.

Benchmarking z autocannon

autocannon to narzędzie do testów obciążeniowych - jak wysłanie tysięcy posłańców naraz, żeby sprawdzić przepustowość dróg Imperium:

# -c 100 = 100 równoległych połączeń (100 posłańców naraz)
# -d 10  = test trwa 10 sekund
# -p 10  = 10 żądań w pipeline na połączenie - zawyża wyniki, używaj ostrożnie

# Test obciążeniowy bez instalacji, przez npx
npx autocannon -c 100 -d 10 http://localhost:3000/legions

-c ustala liczbę równoległych połączeń, a -d czas testu w sekundach. Tak wyglądał wynik jednego uruchomienia na laptopie, dla endpointu zwracającego 20 legionów:

Running 10s test @ http://localhost:3000/legions
100 connections

┌─────────┬──────┬──────┬───────┬──────┬─────────┬─────────┬────────┐
│ Stat    │ 2.5% │ 50%  │ 97.5% │ 99%  │ Avg     │ Stdev   │ Max    │
├─────────┼──────┼──────┼───────┼──────┼─────────┼─────────┼────────┤
│ Latency │ 5 ms │ 5 ms │ 7 ms  │ 8 ms │ 5.44 ms │ 3.92 ms │ 352 ms │
└─────────┴──────┴──────┴───────┴──────┴─────────┴─────────┴────────┘
┌───────────┬─────────┬─────────┬────────┬─────────┬───────────┬────────┬─────────┐
│ Stat      │ 1%      │ 2.5%    │ 50%    │ 97.5%   │ Avg       │ Stdev  │ Min     │
├───────────┼─────────┼─────────┼────────┼─────────┼───────────┼────────┼─────────┤
│ Req/Sec   │ 15,519  │ 15,519  │ 16,671 │ 16,831  │ 16,574.19 │ 344.7  │ 15,515  │
├───────────┼─────────┼─────────┼────────┼─────────┼───────────┼────────┼─────────┤
│ Bytes/Sec │ 23.3 MB │ 23.3 MB │ 25 MB  │ 25.3 MB │ 24.9 MB   │ 517 kB │ 23.3 MB │
└───────────┴─────────┴─────────┴────────┴─────────┴───────────┴────────┴─────────┘

182k requests in 11.02s, 274 MB read

Pierwsza tabela to latencja w percentylach, druga - żądania i bajty na sekundę, z innymi kolumnami. Twoje liczby będą inne, bo zależą od sprzętu. Ten sam test z -p 10 podniósł liczbę żądań na sekundę o około 18%, ale średnią latencję z 5,4 do 50 ms, bo żądania czekały w kolejce połączenia; przeglądarki pipeliningu nie używają, więc zostaw go w spokoju.

Autocannon działa też z kodu, co pozwala wpiąć benchmark w testy:

// benchmark.ts - programistyczne użycie autocannon
import autocannon from 'autocannon';

async function runBenchmark() {
  const result = await autocannon({
    url: 'http://localhost:3000/legions',
    connections: 100,       // 100 równoległych połączeń
    duration: 10,           // 10 sekund testu
    headers: {
      'Authorization': 'Bearer test-token',
    },
  });

  console.log('=== Wyniki Benchmarku ===');
  console.log('Requests/sec:', result.requests.average);
  console.log('Latency avg:', result.latency.average, 'ms');
  console.log('Latency p99:', result.latency.p99, 'ms');
  console.log('Throughput:', result.throughput.average, 'bytes/sec');
  console.log('Errors:', result.errors);
  console.log('Timeouts:', result.timeouts);

  // Kryteria sukcesu
  if (result.latency.p99 > 200) {
    console.warn('UWAGA: p99 latency przekracza 200ms!');
  }
  if (result.errors > 0) {
    console.error('BŁĄD: wystąpiły błędy podczas testu!');
  }
}

runBenchmark();

Wynik zawiera m.in. requests.average, latency.p99, throughput.average, errors i timeouts. Próg 200 ms dla p99 zamienia benchmark w test, który może nie przejść.

Node.js --inspect Profiling

Node.js ma wbudowany profiler, który pokazuje, co robi CPU. Flaga --inspect włącza protokół inspektora, a --cpu-prof zapisuje profil do pliku przy wyjściu z procesu:

# Uruchomienie NestJS z inspektorem
node --inspect dist/main.js

# Następnie otwórz w Chrome: chrome://inspect
# Kliknij "Open dedicated DevTools for Node"
# W zakładce "Performance":
# 1. Kliknij "Record"
# 2. Wykonaj operacje na API (wyślij żądania)
# 3. Kliknij "Stop"
# 4. Analizuj flame graph

# Albo zapisz profil CPU do pliku przy wyjściu z procesu
node --cpu-prof dist/main.js

Dawny panel JavaScript Profiler zniknął z Chrome w wersji 124, dlatego Node.js profilujesz w zakładce Performance.

Ten sam profiler da się sterować z kodu przez moduł node:inspector:

// Programistyczne profilowanie CPU
import { Session } from 'node:inspector';
import { writeFileSync } from 'node:fs';

class CpuProfiler {
  private session: Session;

  constructor() {
    this.session = new Session();
    this.session.connect();
  }

  async startProfiling(): Promise<void> {
    await new Promise<void>((resolve) => {
      this.session.post('Profiler.enable', () => {
        this.session.post('Profiler.start', () => {
          console.log('Profiling CPU started...');
          resolve();
        });
      });
    });
  }

  async stopProfiling(filename: string): Promise<void> {
    return new Promise((resolve) => {
      this.session.post('Profiler.stop', (err, params) => {
        // Przy błędzie params jest undefined - nie destrukturyzuj go na ślepo
        if (!err) {
          writeFileSync(filename, JSON.stringify(params.profile));
          console.log('Profil CPU zapisany do: ' + filename);
        }
        resolve();
      });
    });
  }
}

// Użycie:
// const profiler = new CpuProfiler();
// await profiler.startProfiling();
// ... wykonaj operacje ...
// await profiler.stopProfiling('cpu-profile.cpuprofile');
// Otwórz plik w Chrome DevTools -> Performance

Session łączy się z inspektorem bieżącego procesu, a post() wysyła mu polecenia. Poprawka dotyczy stopProfiling(): przy błędzie drugi argument callbacku to undefined, więc stara destrukturyzacja { profile } wywracała proces. Od Node.js 19 istnieje też node:inspector/promises z metodami zwracającymi obietnice.

Flame Graphs - wizualizacja hot spots

Flame graph pokazuje, które funkcje zajmują najwięcej czasu CPU - jak mapa bitwy, na której widać, gdzie toczy się najcięższa walka:

# Jak czytać flame graph:
# - szerokość bloku = jak często funkcja była na stosie (szerszy = więcej CPU)
# - wysokość = głębokość call stacka; oś X to nie jest czas
# - górna krawędź = funkcje, które akurat pracują na CPU
# - szukaj szerokich płaskich bloków na górze - to bottlenecki!

# Generowanie flame graph z clinic.js (projekt nie jest już aktywnie rozwijany)
npm install -g clinic

# 1. clinic doctor - ogólna diagnoza
clinic doctor -- node dist/main.js
# (w drugim terminalu: npx autocannon -c 100 -d 10 http://localhost:3000/legions)
# Ctrl+C -> otwiera raport HTML

# 2. clinic flame - flame graph
clinic flame -- node dist/main.js

# 3. clinic bubbleprof - analiza operacji async (np. zapytań do bazy)
clinic bubbleprof -- node dist/main.js

# Alternatywa utrzymywana na bieżąco: 0x
npx 0x dist/main.js

Repozytorium Clinic.js ostrzega, że projekt nie jest aktywnie rozwijany i jego wyniki mogą być nietrafne, stąd 0x jako alternatywa. Stara wersja tej lekcji kazała szukać szerokich bloków na dole i czytać czerwień jako hot path, ale dół wykresu to zawsze szerokie funkcje nadrzędne, a kolor w klasycznych flame graphach jest losowy - liczy się szerokość na górnej krawędzi.

Heap Snapshots - analiza pamięci

Heap snapshot to zrzut całej sterty - jak spis ludności Imperium, który pokazuje, kto zajmuje ile miejsca:

// heap-snapshot.service.ts
import { Injectable, Logger } from '@nestjs/common';
import * as v8 from 'node:v8';

@Injectable()
export class HeapSnapshotService {
  private readonly logger = new Logger(HeapSnapshotService.name);

  // Zrób zrzut pamięci (synchronicznie - blokuje event loop!)
  takeSnapshot(filename?: string): string {
    const snapshotFile = filename ||
      'heap-' + new Date().toISOString().replace(/[:.]/g, '-') + '.heapsnapshot';

    const writtenFile = v8.writeHeapSnapshot(snapshotFile);
    this.logger.log('Heap snapshot zapisany: ' + writtenFile);

    return writtenFile;
  }

  // Pobierz statystyki heap
  getHeapStatistics() {
    const stats = v8.getHeapStatistics();
    return {
      totalHeapSize: Math.round(stats.total_heap_size / 1024 / 1024) + ' MB',
      usedHeapSize: Math.round(stats.used_heap_size / 1024 / 1024) + ' MB',
      heapSizeLimit: Math.round(stats.heap_size_limit / 1024 / 1024) + ' MB',
      mallocedMemory: Math.round(stats.malloced_memory / 1024 / 1024) + ' MB',
      usagePercent: ((stats.used_heap_size / stats.heap_size_limit) * 100).toFixed(1) + '%',
    };
  }

  // Porównanie statystyk sterty przed i po operacji
  async compareHeapUsage(operation: () => Promise<unknown>) {
    const before = v8.getHeapStatistics();
    await operation();
    const after = v8.getHeapStatistics();

    const diff = {
      heapGrowth: after.used_heap_size - before.used_heap_size,
      // Rosnąca liczba kontekstów (np. z modułu vm) to osobny rodzaj wycieku
      nativeContextGrowth: after.number_of_native_contexts - before.number_of_native_contexts,
    };

    if (diff.heapGrowth > 10 * 1024 * 1024) { // > 10MB growth
      this.logger.warn('Potencjalny memory leak! Heap wzrósł o ' +
        Math.round(diff.heapGrowth / 1024 / 1024) + ' MB');
    }

    return diff;
  }
}

v8.writeHeapSnapshot() zwraca nazwę zapisanego pliku, a nie strumień. Zrzut jest synchroniczny i blokuje event loop, a według dokumentacji Node.js wymaga około dwa razy tyle pamięci, ile zajmuje sterta - w teście 40 MB sterty dało plik 78 MB. Nie wystawiaj go więc przez publiczny endpoint: grozi zatrzymaniem produkcji, a zrzut zawiera sekrety z pamięci. Dwa zrzuty porównasz w zakładce Memory w DevTools; compareHeapUsage() robi tylko szybkie porównanie statystyk.

Identyfikowanie bottlenecków - praktyczny workflow

Oto workflow diagnostyczny, jakiego używa doświadczony inżynier Imperium:

// performance-diagnostic.service.ts
import { Injectable, Logger } from '@nestjs/common';

@Injectable()
export class PerformanceDiagnosticService {
  private readonly logger = new Logger('PerformanceDiagnostic');

  // Krok 1: Zmierz czas endpointów
  async measureEndpoint(name: string, operation: () => Promise<any>) {
    const start = process.hrtime.bigint();
    const result = await operation();
    const end = process.hrtime.bigint();
    const durationMs = Number(end - start) / 1_000_000;

    this.logger.log(name + ': ' + durationMs.toFixed(2) + 'ms');

    if (durationMs > 200) {
      this.logger.warn(name + ' przekracza 200ms - wymaga optymalizacji!');
    }

    return { result, durationMs };
  }

  // Krok 2: Sprawdź zużycie pamięci
  checkMemoryUsage() {
    const usage = process.memoryUsage();
    return {
      rss: Math.round(usage.rss / 1024 / 1024) + ' MB',
      heapUsed: Math.round(usage.heapUsed / 1024 / 1024) + ' MB',
      heapTotal: Math.round(usage.heapTotal / 1024 / 1024) + ' MB',
      external: Math.round(usage.external / 1024 / 1024) + ' MB',
    };
  }

  // Krok 3: Monitoruj event loop delay
  measureEventLoopDelay(): Promise<number> {
    return new Promise((resolve) => {
      const start = Date.now();
      setImmediate(() => {
        const delay = Date.now() - start;
        if (delay > 10) {
          this.logger.warn('Event loop delay: ' + delay + 'ms');
        }
        resolve(delay);
      });
    });
  }

  // Krok 4: Pełny raport diagnostyczny
  async generateDiagnosticReport() {
    const memory = this.checkMemoryUsage();
    const eventLoopDelay = await this.measureEventLoopDelay();
    const uptime = process.uptime();

    return {
      timestamp: new Date().toISOString(),
      uptime: Math.round(uptime) + 's',
      memory,
      eventLoopDelay: eventLoopDelay + 'ms',
      nodeVersion: process.version,
      platform: process.platform,
    };
  }
}

process.hrtime.bigint() mierzy czas w nanosekundach bez wpływu zmian zegara systemowego. Pomiar przez setImmediate to tylko jednorazowa próbka; stały nadzór daje histogram monitorEventLoopDelay() z lekcji o pamięci.

Polecam Ci stałą kolejność: benchmark ustala punkt odniesienia, profil pokazuje przyczynę, a po poprawce ten sam benchmark potwierdza efekt. W następnym module wyprowadzimy zmierzony i odchudzony fort na produkcję.

Pamiętaj zasadę Pretora Augusta: nie optymalizuj tego, czego nie zmierzyłeś.

Kod do tej lekcji: src/profiling-benchmarking.ts
// Profiling i Benchmarking NestJS
import { Injectable, Logger } from '@nestjs/common';

// ===========================================
// 1. Performance Measurement
// ===========================================

@Injectable()
class PerformanceDiagnostic {
  private readonly logger = new Logger('Diagnostic');

  async measureEndpoint(name: string, operation: () => Promise<any>) {
    const start = process.hrtime.bigint();
    const result = await operation();
    const end = process.hrtime.bigint();
    const durationMs = Number(end - start) / 1_000_000;

    console.log(name + ': ' + durationMs.toFixed(2) + 'ms');

    if (durationMs > 200) {
      console.warn(name + ' przekracza 200ms!');
    }

    return { result, durationMs };
  }

  checkMemoryUsage() {
    const usage = process.memoryUsage();
    return {
      rss: Math.round(usage.rss / 1024 / 1024) + ' MB',
      heapUsed: Math.round(usage.heapUsed / 1024 / 1024) + ' MB',
      heapTotal: Math.round(usage.heapTotal / 1024 / 1024) + ' MB',
    };
  }

  measureEventLoopDelay(): Promise<number> {
    return new Promise((resolve) => {
      const start = Date.now();
      setImmediate(() => {
        resolve(Date.now() - start);
      });
    });
  }
}

// ===========================================
// 2. Heap Statistics (v8)
// ===========================================

// import * as v8 from 'v8';
// const stats = v8.getHeapStatistics();
// {
//   total_heap_size: ...,
//   used_heap_size: ...,
//   heap_size_limit: ...,
// }

// Heap Snapshot:
// v8.writeHeapSnapshot('heap.heapsnapshot');
// Otworz w Chrome DevTools -> Memory

// ===========================================
// 3. Demonstracja
// ===========================================

const diagnostic = new PerformanceDiagnostic();
const memory = diagnostic.checkMemoryUsage();

console.log('=== Profiling & Benchmarking ===');
console.log('Pamiec:', JSON.stringify(memory));
console.log('');
console.log('Narzedzia:');
console.log('  autoballista - load testing (req/sec, latency)');
console.log('  node --inspect - CPU profiling w Chrome');
console.log('  clinic.js - flame graphs, doctor, bubbleprof');
console.log('  v8.writeHeapSnapshot() - zrzut pamieci');
console.log('  process.hrtime.bigint() - pomiar czasu');
console.log('');
console.log('Workflow:');
console.log('  1. Zmierz (autoballista)');
console.log('  2. Profiluj (clinic flame)');
console.log('  3. Zidentyfikuj bottleneck');
console.log('  4. Napraw');
console.log('  5. Zmierz ponownie');

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

  1. Projekt do wysłaniaProjekt: System wydajności aplikacji
  2. WideoPodsumowanie modułu

Przydatne artykuły