Kurs NestJS · Moduł 6: Obsługa błędów i monitoring
Monitoring i Alerting - systemy wczesnego ostrzegania
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:
- Counter - tylko rośnie. Liczba obsłużonych żądań, liczba błędów. Nigdy nie maleje; przy restarcie zaczyna od zera.
- 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.
- 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.
- 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:
- Instalacja pakietu
prom-client. - Zdefiniowanie metryk - Counter, Histogram, tyle ile potrzeba.
- Utworzenie endpointu
/metrics. - Konfiguracja scrapera Prometheus, żeby wiedział, gdzie i jak często pytać.
- 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
/metricszContent-Typeustawionym na tekst zwykły przezregister.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. Do czego służy Prometheus w kontekście monitorowania aplikacji NestJS?
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
Zadania po tej lekcji
- PytaniePrometheus w NestJS
- PytanieTypy metryk Prometheus
- Zadanie z kodemPrometheusService z metrykami
- Ułóż w kolejnościMetryki Prometheus - typy
- PytaniecollectDefaultMetrics
- Kliknij w kolejnościLabel w metrykach Prometheus
- Zadanie z kodemEndpoint /metrics dla Prometheus
- Ułóż w kolejnościEtapy konfiguracji monitoringu w NestJS