Kurs NestJS · Moduł 6: Obsługa błędów i monitoring
Health Checks - diagnostyka stanu
W tej lekcji6
Aplikacja wstała, proces działa, port odpowiada. Ale czy naprawdę jest zdolna do służby? Baza mogła nie przyjąć połączenia, dysk może być pełen, zewnętrzne API może milczeć. Proces żyje, a każde żądanie i tak skończy się błędem.
Rzymski obóz miał na to poranny apel. Nie liczono, ilu legionistów oddycha - sprawdzano po kolei: czy studnia daje wodę, czy magazyn nie jest pusty, czy posłaniec z sąsiedniego fortu dotarł. Dopiero suma tych odpowiedzi mówiła, czy kohorta może wymaszerować. Tym jest health check.
Pakiet i jego serce
W NestJS służy do tego pakiet @nestjs/terminus. Nazwa jest nieoczywista - nie ma tam słowa „health" - więc łatwo szukać czegoś w rodzaju @nestjs/health czy @nestjs/monitor. Takie pakiety nie istnieją.
Jego głównym elementem jest HealthCheckService, który uruchamia zestaw wskaźników i zwraca zagregowany status aplikacji. Sam niczego nie mierzy i - co ważne - nie restartuje aplikacji ani nie wysyła alertów. Zbiera odpowiedzi i podaje wynik; co z nim zrobić, decyduje ten, kto pyta.
Apel poranny
Kontroler zdrowia wygląda tak:
@Controller('health')
export class HealthController {
constructor(
private health: HealthCheckService,
private db: TypeOrmHealthIndicator,
private memory: MemoryHealthIndicator,
) {}
@Get()
@HealthCheck()
check() {
return this.health.check([
() => this.db.pingCheck('database'),
() => this.memory.checkHeap('memory', 150 * 1024 * 1024),
]);
}
}Kolejność wywołania jest zawsze ta sama: this.health.check([ otwiera listę, wewnątrz stoją poszczególne wskaźniki, a ]) ją zamyka.
Zwróć uwagę, że każdy wskaźnik podajesz jako funkcję, nie jako wynik jej wywołania. Zapis () => this.db.pingCheck('database') pozwala serwisowi uruchomić sprawdzenia samodzielnie - równolegle i z obsługą błędów. Gdybyś napisał this.db.pingCheck('database') bez strzałki, sprawdzenie wykonałoby się natychmiast, poza kontrolą serwisu, a rzucony wyjątek wywróciłby cały endpoint.
Pierwszy argument każdego wskaźnika to klucz - nazwa, pod którą wynik pojawi się w odpowiedzi. To Ty ją wybierasz.
Wskaźniki wbudowane
Terminus daje kilka gotowych wskaźników, po jednym na typ zasobu:
TypeOrmHealthIndicator- sprawdza połączenie z bazą danych metodąpingCheck.HttpHealthIndicator- odpytuje zewnętrzny adres HTTP, żeby sprawdzić, czy cudze API odpowiada.MemoryHealthIndicator- pilnuje zużycia pamięci;checkHeapprzyjmuje próg w bajtach.DiskHealthIndicator- sprawdza wolne miejsce na dysku.
Nazwy są na tyle podobne, że warto je zapamiętać po zasobie, którego dotyczą: TypeOrm - baza, Http - cudze API, Memory - pamięć, Disk - dysk.
Kształt odpowiedzi
Wynik apelu ma trzy poziomy szczegółowości, od ogółu do szczegółu:
{
"status": "ok",
"info": { "database": { "status": "up" } },
"details": { "database": { "status": "up" }, "memory": { "status": "up" } }
}status to jedno słowo dla całości - 'ok', gdy wszystko przeszło, albo 'error', gdy cokolwiek zawiodło. To jego czyta system, który co kilkanaście sekund pyta o zdrowie aplikacji.
info zawiera tylko sprawne wskaźniki, a bliźniacze pole error - tylko te, które zawiodły. details to komplet: wszystkie wskaźniki niezależnie od wyniku.
Podział ma sens praktyczny: człowiek zagląda w details, żeby zobaczyć pełny obraz, a automat czyta status, bo tylko ta jedna wartość decyduje o akcji.
Własny wskaźnik
Wbudowane wskaźniki pilnują infrastruktury. Gdy chcesz sprawdzić coś z własnej dziedziny - czy skarbiec przyjmuje wpłaty, czy legion ma komplet - piszesz wskaźnik sam:
@Injectable()
export class LegionHealthIndicator extends HealthIndicator {
constructor(private legionsService: LegionsService) {
super();
}
async isHealthy(key: string): Promise<HealthIndicatorResult> {
const count = await this.legionsService.countActive();
if (count > 0) {
return this.getStatus(key, true, { activeLegions: count });
}
throw new HealthCheckError(
'Brak aktywnych legionów',
this.getStatus(key, false, { activeLegions: 0 }),
);
}
}Klasa dziedziczy po HealthIndicator i implementuje metodę isHealthy(key). Kontrakt jest dwustronny i warto go zapamiętać: przy sukcesie zwracasz this.getStatus(key, true), a przy niepowodzeniu rzucasz HealthCheckError z takim samym statusem, tylko z false.
Dlaczego wyjątek zamiast zwrócenia false? Bo HealthCheckService uruchamia wskaźniki równolegle i musi odróżnić „sprawdziłem, jest źle" od „sprawdzenie samo się wywaliło". Rzucony HealthCheckError niesie oba: informację o awarii i gotowy status do wstawienia w odpowiedź.
Trzeci argument getStatus to dowolne dane dodatkowe - trafią do details obok statusu. To dobre miejsce na liczby, które pomogą przy diagnozie: ile legionów, ile wolnego miejsca, jak długo trwało sprawdzenie.
Podsumowanie
Apel odbyty, kohorta zdolna do służby:
- health check odpowiada, czy aplikacja jest zdolna do pracy - działający proces tego nie gwarantuje,
- służy do tego pakiet
@nestjs/terminus;@nestjs/health,@nestjs/diagnosticsi@nestjs/monitornie istnieją, HealthCheckServiceuruchamia zestaw wskaźników i zwraca zagregowany status - nie restartuje aplikacji ani nie wysyła alertów,- kolejność:
this.health.check([, wskaźniki,]), - każdy wskaźnik podajesz jako funkcję
() => ..., żeby serwis mógł uruchomić go sam, TypeOrmHealthIndicatorsprawdza bazę danych,HttpHealthIndicator- zewnętrzne API,MemoryHealthIndicator- pamięć,DiskHealthIndicator- dysk,- odpowiedź od ogółu do szczegółu:
status(jedno słowo),info(tylko sprawne),details(wszystkie), - własny wskaźnik dziedziczy po
HealthIndicatori implementujeisHealthy(key), - sukces:
return this.getStatus(key, true); porażka:throw new HealthCheckError(...)- wyjątek pozwala odróżnić awarię od nieudanego sprawdzenia, - dane dodatkowe z
getStatuslądują wdetailsi przydają się przy diagnozie.
W następnej lekcji przejdziemy od pojedynczego apelu do stałej obserwacji - poznasz metryki i systemy wczesnego ostrzegania. A na razie zapamiętaj: proces, który żyje, to nie to samo co aplikacja zdolna do służby - i tylko apel to rozstrzyga.
Kod do tej lekcji: src/health/health-checks.ts
// Health Checks - Diagnostyka Stanu Imperium
// Monitorowanie zdrowia aplikacji z @nestjs/terminus
import { Injectable, Logger } from '@nestjs/common';
import { Controller, Get } from '@nestjs/common';
// ===========================================
// 1. Health Indicator - wskaznik zdrowia
// ===========================================
@Injectable()
export class DatabaseHealthIndicator {
private logger = new Logger('DBHealth');
async isHealthy(): Promise<{
status: 'up' | 'down';
details: Record<string, any>;
}> {
try {
// Symulacja sprawdzenia polaczenia z baza
const startTime = Date.now();
// await this.connection.query('SELECT 1');
const responseTime = Date.now() - startTime;
this.logger.log('Baza danych: OK (' + responseTime + 'ms)');
return {
status: 'up',
details: {
responseTime: responseTime + 'ms',
connections: 5,
maxConnections: 20,
},
};
} catch (error) {
this.logger.error('Baza danych: BLAD - ' + error.message);
return {
status: 'down',
details: { error: error.message },
};
}
}
}
@Injectable()
export class MemoryHealthIndicator {
isHealthy() {
const used = process.memoryUsage();
const heapUsedMB = Math.round(used.heapUsed / 1024 / 1024);
const heapTotalMB = Math.round(used.heapTotal / 1024 / 1024);
const usagePercent = Math.round((heapUsedMB / heapTotalMB) * 100);
return {
status: usagePercent < 90 ? 'up' : 'down',
details: {
heapUsed: heapUsedMB + 'MB',
heapTotal: heapTotalMB + 'MB',
usage: usagePercent + '%',
},
};
}
}
// ===========================================
// 2. Health Controller
// ===========================================
@Controller('health')
export class HealthController {
constructor(
private dbHealth: DatabaseHealthIndicator,
private memoryHealth: MemoryHealthIndicator,
) {}
@Get()
async check() {
const db = await this.dbHealth.isHealthy();
const memory = this.memoryHealth.isHealthy();
const overallStatus = db.status === 'up' && memory.status === 'up'
? 'ok' : 'error';
return {
status: overallStatus,
info: {
database: db,
memory: memory,
},
timestamp: new Date().toISOString(),
};
}
@Get('liveness')
liveness() {
return { status: 'ok', uptime: process.uptime() };
}
@Get('readiness')
async readiness() {
const db = await this.dbHealth.isHealthy();
return {
status: db.status === 'up' ? 'ready' : 'not_ready',
database: db,
};
}
}
console.log('=== Health Checks ===');
console.log('/health - pelny status aplikacji');
console.log('/health/liveness - czy aplikacja zyje');
console.log('/health/readiness - czy gotowa na ruch');
console.log('HealthIndicator - sprawdza konkretny komponent');
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jaki pakiet NestJS służy do implementacji Health Checks?
2. Co robi HealthCheckService z @nestjs/terminus?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Uzupełnij HealthController z @Get('/health'), który używa HealthCheckService.check() z TypeOrmHealthIndicator.pingCheck('database') i HttpHealthIndicator.pingCheck('api', 'http://localhost:4000')
- Klikanie w kolejności
Ułóż elementy wywołania HealthCheckService.check() w poprawnej kolejności
- Edytor kodu
Uzupełnij klasę LegionHealthIndicator rozszerzającą HealthIndicator, z metodą isHealthy(key) która zwraca this.getStatus(key, true) przy sukcesie lub rzuca HealthCheckError przy błędzie
- Układanie w pionie
Ułóż pola odpowiedzi Health Check od statusu ogólnego do szczegółów