Kurs NestJS · Moduł 8: Cache i wydajność
Profiling i Benchmarking NestJS - diagnostyka mocy Imperium
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 readPierwsza 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.jsDawny 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 -> PerformanceSession łą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.jsRepozytorium 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?