Kurs NestJS · Moduł 6: Obsługa błędów i monitoring

Health Checks - diagnostyka stanu

5 min czytania ·
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; checkHeap przyjmuje 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/diagnostics i @nestjs/monitor nie istnieją,
  • HealthCheckService uruchamia 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,
  • TypeOrmHealthIndicator sprawdza 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 HealthIndicator i implementuje isHealthy(key),
  • sukces: return this.getStatus(key, true); porażka: throw new HealthCheckError(...) - wyjątek pozwala odróżnić awarię od nieudanego sprawdzenia,
  • dane dodatkowe z getStatus lądują w details i 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. 1. Jaki pakiet NestJS służy do implementacji Health Checks?

  2. 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

  1. PytanieModuł @nestjs/terminus
  2. PytanieHealthCheckService
  3. Zadanie z kodemHealth Check Controller
  4. PytanieHealth Indicators w NestJS
  5. Kliknij w kolejnościSkładnia health.check()
  6. Zadanie z kodemCustom Health Indicator
  7. Ułóż w kolejnościOdpowiedź Health Check

Przydatne artykuły