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

Monitoring i Alerting - systemy wczesnego ostrzegania

5 min czytania ·
W tej lekcji6

Aplikacja działa. Żaden wyjątek nie poleciał, logi milczą, health check świeci na zielono. A jednak użytkownicy piszą, że „strona zamula". Sprawdzasz - odpowiedzi przychodzą po ośmiuset milisekundach zamiast po stu. Od kiedy? Nie wiadomo. Logi zapisują zdarzenia, a to jest trend: coś, co narastało tygodniami i czego nie widać w żadnym pojedynczym wpisie.

Rzym stawiał na granicach wieże sygnałowe. Nie meldowały pojedynczych zdarzeń - mierzyły ruch: ilu jeźdźców przejechało, jak długo trwa przeprawa, ilu wartowników nie wróciło. Dopiero z tych liczb widać było, że coś się psuje, zanim padła brama. Tym są metryki.

Cztery typy metryk

Standardem zbierania metryk jest Prometheus - system, który zbiera i przechowuje liczby opisujące aplikację. Oferuje cztery typy pomiaru, od najprostszego do najbardziej złożonego:

  1. Counter - tylko rośnie. Liczba obsłużonych żądań, liczba błędów. Nigdy nie maleje; przy restarcie zaczyna od zera.
  2. Gauge - może rosnąć i maleć. Liczba aktywnych połączeń, zajęta pamięć, długość kolejki. Zdejmuje bieżącą wartość, jak wskazówka na mierniku.
  3. Histogram - rozkład wartości w kubełkach (buckets). Zamiast jednej liczby zapamiętuje, ile pomiarów wpadło w przedział 0-100 ms, ile w 100-500 ms i tak dalej.
  4. Summary - podobnie jak histogram, ale percentyle liczone po stronie klienta, czyli w Twojej aplikacji, a nie w Prometheusie.

Do czasu trwania żądań HTTP właściwy jest Histogram. Counter powiedziałby tylko, ile żądań było, a Gauge - ile trwało ostatnie. Histogram pokazuje kształt: że dziewięć na dziesięć żądań mieści się poniżej 200 ms, a co dziesiąte przekracza sekundę. To ten kształt zdradza problem, którego średnia by nie pokazała.

Definicja metryki

Metrykę tworzysz raz, opisując ją trzema polami:

import { Counter } from 'prom-client';

@Injectable()
export class PrometheusService {
  private readonly httpRequestCounter = new Counter({
    name: 'http_requests_total',
    help: 'Total HTTP requests',
    labelNames: ['method', 'route', 'status'],
  });

  recordRequest(method: string, route: string, status: number) {
    this.httpRequestCounter.inc({ method, route, status: String(status) });
  }
}

Kolejność pól jest umowna, ale zawsze ta sama: name to identyfikator metryki, help - opis czytany przez człowieka, labelNames - lista wymiarów, po których będzie można ciąć dane.

Etykiety są tu najciekawsze. Dzięki nim jeden licznik odpowiada na wiele pytań: ile było żądań POST, ile trafiło na /legions, ile zakończyło się kodem 500. Bez etykiet potrzebowałbyś osobnego licznika na każdą kombinację.

Uwaga na pułapkę: etykieta o wielu możliwych wartościach mnoży liczbę serii danych. Wstawienie identyfikatora użytkownika jako etykiety utworzy tyle serii, ilu masz użytkowników - i położy Prometheusa. Etykiety mają mieć skończony, mały zbiór wartości.

Metryki systemowe za darmo

Zanim napiszesz własne metryki, warto włączyć te wbudowane:

import { collectDefaultMetrics, register } from 'prom-client';

collectDefaultMetrics();

collectDefaultMetrics() zbiera domyślne metryki systemowe - zużycie procesora, pamięci i opóźnienie pętli zdarzeń Node.js. Ta ostatnia jest szczególnie cenna: rosnące opóźnienie event loopu znaczy, że coś blokuje wątek i aplikacja przestaje nadążać, choć żaden endpoint jeszcze nie pada.

Zwróć uwagę, czego ta funkcja nie robi: niczego nie wysyła, nie tworzy wykresów ani nie zeruje liczników. Jedynie zaczyna zbierać.

Endpoint /metrics

Prometheus nie przyjmuje danych przysyłanych przez aplikację - sam po nie przychodzi. Twoim zadaniem jest wystawić je pod ustalonym adresem:

@Controller()
export class MetricsController {
  @Get('/metrics')
  async getMetrics(@Res() res: Response) {
    res.set('Content-Type', register.contentType);
    res.send(await register.metrics());
  }
}

register to rejestr wszystkich zdefiniowanych metryk, a register.metrics() zwraca je w formacie tekstowym, który Prometheus rozumie. Nagłówek Content-Type musi wskazywać tekst zwykły, nie JSON - stąd register.contentType, które ustawia właściwą wartość za Ciebie.

Ten model nazywa się scrapingiem: Prometheus co kilkanaście sekund odpytuje ten adres i zapisuje to, co zastał. Aplikacja nie musi wiedzieć, kto ją obserwuje ani czy ktokolwiek w ogóle.

Pięć etapów wdrożenia

Cała droga od zera do wykresu wygląda tak:

  1. Instalacja pakietu prom-client.
  2. Zdefiniowanie metryk - Counter, Histogram, tyle ile potrzeba.
  3. Utworzenie endpointu /metrics.
  4. Konfiguracja scrapera Prometheus, żeby wiedział, gdzie i jak często pytać.
  5. Wizualizacja metryk w Grafanie - i dopiero tu powstają wykresy oraz alerty.

Podział ról między dwoma ostatnimi bywa myląco zacierany. Prometheus zbiera i przechowuje, Grafana rysuje i alarmuje. To rozdzielenie sprawia, że możesz wymienić jedno bez drugiego - i że aplikacja nie zna żadnego z nich.

Podsumowanie

Wieże sygnałowe stoją, ruch jest mierzony:

  • logi zapisują zdarzenia, metryki pokazują trendy - tego drugiego nie widać w żadnym pojedynczym wpisie,
  • Prometheus zbiera i przechowuje metryki; nie loguje błędów ani niczego nie naprawia,
  • cztery typy od najprostszego: Counter (tylko rośnie), Gauge (rośnie i maleje), Histogram (rozkład w kubełkach), Summary (percentyle liczone po stronie klienta),
  • do czasu trwania żądań HTTP właściwy jest Histogram - pokazuje kształt, którego średnia nie zdradzi,
  • metrykę definiują trzy pola: name, help, labelNames,
  • etykiety pozwalają ciąć dane, ale muszą mieć mały zbiór wartości - identyfikator użytkownika jako etykieta położy Prometheusa,
  • collectDefaultMetrics() zbiera metryki systemowe - CPU, pamięć, opóźnienie event loopu; niczego nie wysyła,
  • Prometheus sam przychodzi po dane (scraping), więc wystawiasz endpoint /metrics z Content-Type ustawionym na tekst zwykły przez register.contentType,
  • pięć etapów: instalacja prom-client, zdefiniowanie metryk, endpoint /metrics, konfiguracja scrapera, wizualizacja w Grafanie,
  • Prometheus zbiera, Grafana rysuje i alarmuje.

W następnej lekcji zejdziemy z poziomu trendów do pojedynczego błędu - poznasz techniki debugowania, gdy wiadomo już, że coś jest nie tak, ale nie wiadomo gdzie. A na razie zapamiętaj: log mówi, co się stało raz; metryka mówi, co dzieje się stale - i to ona ostrzega, zanim padnie brama.

Kod do tej lekcji: src/monitoring/monitoring-system.ts
// Monitoring i Alerting - Systemy Wczesnego Ostrzegania
// Metryki, alerty i dashboard dla Imperium
import { Injectable, Logger } from '@nestjs/common';

// ===========================================
// 1. Serwis Metryk (styl Prometheus)
// ===========================================

@Injectable()
export class MetricsService {
  private logger = new Logger('Metrics');

  // Liczniki (Counter) - rosna tylko w gore
  private counters = new Map<string, number>();

  // Histogramy - rozklad wartosci
  private histograms = new Map<string, number[]>();

  // Gauge - wartosc chwilowa (moze rosnac i malec)
  private gauges = new Map<string, number>();

  // Zwieksz licznik
  incrementCounter(name: string, value: number = 1) {
    const current = this.counters.get(name) || 0;
    this.counters.set(name, current + value);
  }

  // Zapisz wartosc histogramu
  observeHistogram(name: string, value: number) {
    if (!this.histograms.has(name)) {
      this.histograms.set(name, []);
    }
    this.histograms.get(name).push(value);
  }

  // Ustaw gauge
  setGauge(name: string, value: number) {
    this.gauges.set(name, value);
  }

  // Pobierz wszystkie metryki
  getMetrics() {
    const result: Record<string, any> = {};

    // Counters
    this.counters.forEach((v, k) => {
      result[k + '_total'] = v;
    });

    // Histograms - srednia i percentyle
    this.histograms.forEach((values, k) => {
      const sorted = [...values].sort((a, b) => a - b);
      const sum = values.reduce((a, b) => a + b, 0);
      result[k + '_avg'] = Math.round(sum / values.length);
      result[k + '_p95'] = sorted[Math.floor(sorted.length * 0.95)];
      result[k + '_count'] = values.length;
    });

    // Gauges
    this.gauges.forEach((v, k) => {
      result[k] = v;
    });

    return result;
  }
}

// ===========================================
// 2. Serwis Alertow
// ===========================================

@Injectable()
export class AlertService {
  private logger = new Logger('Alerting');
  private alerts: Array<{
    name: string;
    severity: string;
    message: string;
    timestamp: Date;
  }> = [];

  // Definicje progow alertow
  private thresholds = {
    error_rate: { warn: 0.01, critical: 0.05 },
    response_time_ms: { warn: 500, critical: 2000 },
    memory_percent: { warn: 80, critical: 95 },
  };

  checkThreshold(metric: string, value: number) {
    const threshold = this.thresholds[metric];
    if (!threshold) return;

    if (value >= threshold.critical) {
      this.fireAlert(metric, 'CRITICAL', metric + ' = ' + value);
    } else if (value >= threshold.warn) {
      this.fireAlert(metric, 'WARNING', metric + ' = ' + value);
    }
  }

  private fireAlert(name: string, severity: string, message: string) {
    const alert = { name, severity, message, timestamp: new Date() };
    this.alerts.push(alert);
    this.logger.warn('ALERT [' + severity + ']: ' + message);
  }

  getActiveAlerts() {
    return this.alerts.slice(-20);
  }
}

console.log('=== Monitoring & Alerting ===');
console.log('Counter - zlicza zdarzenia (requesty, bledy)');
console.log('Histogram - rozklad czasow odpowiedzi');
console.log('Gauge - aktualna wartosc (pamiec, polaczenia)');
console.log('Alert thresholds: warn -> critical');

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. Do czego służy Prometheus w kontekście monitorowania aplikacji NestJS?

  2. 2. Który typ metryki Prometheus najlepiej nadaje się do mierzenia czasu trwania żądań HTTP?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Uzupełnij PrometheusService z polem httpRequestCounter (Counter z labelNames: ['method', 'route', 'status_code']) i httpRequestDuration (Histogram z buckets: [0.1, 0.5, 1, 2, 5, 10])

  • Układanie w pionie

    Uporządkuj typy metryk Prometheus od najprostszych do najbardziej złożonych

  • Klikanie w kolejności

    Ułóż elementy definicji Counter z labelNames w poprawnej kolejności

  • Edytor kodu

    Uzupełnij MetricsController z @Get('/metrics'), który ustawia Content-Type na 'text/plain' i zwraca register.metrics() z prom-client

  • Układanie w pionie

    Uporządkuj etapy wdrażania monitoringu Prometheus w aplikacji NestJS od instalacji do wizualizacji

  1. PytaniePrometheus w NestJS
  2. PytanieTypy metryk Prometheus
  3. Zadanie z kodemPrometheusService z metrykami
  4. Ułóż w kolejnościMetryki Prometheus - typy
  5. PytaniecollectDefaultMetrics
  6. Kliknij w kolejnościLabel w metrykach Prometheus
  7. Zadanie z kodemEndpoint /metrics dla Prometheus
  8. Ułóż w kolejnościEtapy konfiguracji monitoringu w NestJS

Przydatne artykuły