Konfiguracja logowania i monitoringu w Cursor

Jest 2 w nocy i twój pager się odzywa. Alert mówi “wysoki wskaźnik błędów na API zamówień.” Otwierasz dashboard monitoringu i widzisz skok błędów 500, ale logi mówią tylko “Internal Server Error” bez stack trace, bez ID żądania, bez kontekstu o tym, który endpoint lub który użytkownik był dotknięty. Łączysz się przez SSH do serwera produkcyjnego, robisz tail na logach i znajdujesz tysiące linii nieustrukturyzowanego tekstu zmieszanego z debugowym outputem, który ktoś zapomniał usunąć. Po trzydziestu minutach nadal nie wiesz, co jest zepsute.

To jest koszt pominięcia obserwowalności. Ustrukturyzowane logowanie, metryki aplikacji i rozproszone śledzenie to różnica między 5-minutową diagnozą a 2-godzinną gorączką. Cursor Agent może wygenerować twój cały stos obserwowalności, ponieważ wzorce są dobrze zdefiniowane: ustrukturyzowane loggery, kolektory metryk, propagacja trace’ów i reguły alertowania — wszystko to podlega standardowym schematom, które AI generuje niezawodnie.

Co wyniesiesz z tej lekcji

• Konfigurację ustrukturyzowanego logowania z ID korelacji i kontekstem żądania
• Zbieranie metryk aplikacji z instrumentacją kompatybilną z Prometheus
• Konfigurację rozproszonego śledzenia dla architektur wieloserwisowych
• Reguły alertowania, które wyzwalają się na istotnych warunkach, a nie na szumie
• Gotowe do skopiowania prompty do generowania każdej warstwy obserwowalności

Ustrukturyzowane logowanie

Fundamentem obserwowalności jest ustrukturyzowane logowanie. Każda linia logu powinna być parsowalnym JSON z konsekwentnymi polami, abyś mógł przeszukiwać, filtrować i agregować w całym systemie.

Wskazówka

Prompt do skopiowania — Konfiguracja ustrukturyzowanego logowania:

@src/lib @package.json

Utwórz moduł ustrukturyzowanego logowania w src/lib/logger.ts, który:

1. Używa pino do ustrukturyzowanego logowania JSON w Node.js
2. Zawiera te pola w każdej linii logu:
   - timestamp (ISO 8601)
   - level (trace, debug, info, warn, error, fatal)
   - service (ze zmiennej środowiskowej SERVICE_NAME)
   - environment (z NODE_ENV)
   - correlation_id (z async local storage, jeśli dostępny)
   - request_id (z async local storage, jeśli dostępny)
3. Tworzy child loggery z dodatkowym kontekstem (np. user_id, order_id)
4. Redaguje wrażliwe pola: password, token, authorization, cookie, ssn
5. W developmencie: ładne formatowanie z kolorami
6. Na produkcji: jednoliniowy JSON do agregacji logów
7. Wspiera konfigurację poziomu logowania przez zmienną środowiskową LOG_LEVEL

Utwórz również middleware Express w src/middleware/request-logger.ts, które:
- Generuje unikalny request_id dla każdego żądania
- Przechowuje correlation_id (z nagłówka x-correlation-id) w async local storage
- Loguje początek żądania (method, path, query params)
- Loguje koniec żądania (status code, czas trwania w ms, rozmiar odpowiedzi)
- Loguje błędy z pełnym stack trace i kontekstem żądania
- NIE loguje żądań health check (/health, /ready)

Po wygenerowaniu zweryfikuj, że logger produkuje prawidłowy output:

Przetestuj logger wklejając to do trybu Agent:

"Napisz szybki test, który importuje nasz logger, tworzy child logger
z kontekstem user_id, loguje wiadomość info i error ze stack trace.
Pokaż mi, jak wygląda output JSON zarówno w trybie development, jak i production."

Dodawanie kontekstu do każdego logu

Najcenniejsza poprawa logowania to dodanie kontekstu biznesowego. Gdy możesz wyszukać wszystkie logi związane z zamówieniem ord_abc123, debugowanie staje się dramatycznie szybsze.

Wskazówka

Prompt do skopiowania — Kontekstowe logowanie zamówień:

@src/lib/logger.ts @src/services/orders.ts

Dodaj kontekstowe logowanie do serwisu zamówień:

1. Przy przetwarzaniu zamówienia utwórz child logger z:
   - order_id
   - customer_id
   - total_amount
   - payment_method
2. Loguj na każdym etapie przetwarzania zamówienia:
   - Zamówienie otrzymane (info)
   - Sprawdzanie stanu magazynowego rozpoczęte/zakończone (debug)
   - Płatność zainicjowana/zakończona/nieudana (info/error)
   - Zamówienie potwierdzone/anulowane (info)
3. Przy błędzie dołącz pełny obiekt error ze stack trace
4. Dołącz chronometraż dla każdego etapu (started_at, duration_ms)

Każda linia logu z przetwarzania zamówienia powinna być filtrowalna po order_id.

Metryki aplikacji

Metryki mówią ci, co dzieje się w twoim systemie w ujęciu zagregowanym. Podczas gdy logi pokazują pojedyncze zdarzenia, metryki pokazują trendy: wskaźniki żądań, wskaźniki błędów, rozkłady latencji i wykorzystanie zasobów.

Wskazówka

Prompt do skopiowania — Metryki kompatybilne z Prometheus:

@src/lib/logger.ts @src/middleware

Utwórz moduł metryk w src/lib/metrics.ts za pomocą prom-client, który eksponuje:

1. Metryki HTTP (auto-instrumentowane):
   - http_requests_total (counter, etykiety: method, path, status_code)
   - http_request_duration_seconds (histogram, etykiety: method, path)
   - http_request_size_bytes (histogram)
   - http_response_size_bytes (histogram)

2. Metryki biznesowe:
   - orders_created_total (counter, etykiety: payment_method, status)
   - order_processing_duration_seconds (histogram)
   - payment_attempts_total (counter, etykiety: provider, result)
   - active_users_gauge (gauge)

3. Metryki systemowe:
   - nodejs_event_loop_lag_seconds (histogram)
   - nodejs_active_handles_total (gauge)
   - Domyślne metryki Node.js (pamięć, CPU, GC)

Utwórz middleware Express, które:
- Rejestruje metryki HTTP dla każdego żądania automatycznie
- Eksponuje endpoint GET /metrics w formacie tekstowym Prometheus
- NIE rejestruje metryk dla endpointów /metrics i /health

Utwórz funkcje pomocnicze do rejestrowania metryk biznesowych:
- recordOrderCreated(paymentMethod, status)
- recordPaymentAttempt(provider, result)
- observeOrderDuration(durationMs)

Rozproszone śledzenie

Dla architektur mikroserwisowych rozproszone śledzenie łączy pojedyncze żądanie użytkownika przez wiele serwisów. Trace pokazuje pełną podróż: API gateway do serwisu auth, do serwisu zamówień, do serwisu płatności i z powrotem.

Wskazówka

Prompt do skopiowania — Śledzenie OpenTelemetry:

@src/lib/logger.ts @src/middleware

Skonfiguruj rozproszone śledzenie OpenTelemetry w src/lib/tracing.ts:

1. Skonfiguruj SDK OpenTelemetry z:
   - Eksporterem OTLP (konfigurowalny endpoint przez OTEL_EXPORTER_OTLP_ENDPOINT)
   - Nazwą serwisu ze zmiennej środowiskowej SERVICE_NAME
   - Auto-instrumentacją dla: HTTP, Express, PostgreSQL, Redis
   - Procesorem spanów wsadowym z 5-sekundowym interwałem flush

2. Utwórz middleware propagacji kontekstu trace:
   - Wyodrębnij kontekst trace z przychodzącego nagłówka W3C traceparent
   - Utwórz nowy span dla każdego przychodzącego żądania
   - Dodaj atrybuty spanu: http.method, http.url, http.status_code
   - Propaguj kontekst trace do wychodzących żądań HTTP

3. Utwórz funkcje pomocnicze dla niestandardowych spanów:
   - startSpan(name, attributes) -> span
   - withSpan(name, fn) -> opakowuje funkcję w span
   - addSpanEvent(name, attributes) -> dodaje zdarzenie do bieżącego spanu

4. Połącz śledzenie z naszym loggerem:
   - Dołącz trace_id i span_id do każdej linii logu
   - To pozwala korelować logi z trace'ami w naszej platformie obserwowalności

W developmencie eksportuj trace'y na konsolę.
Na produkcji eksportuj do kolektora OTLP.

Reguły alertowania

Metryki i trace’y są bezużyteczne, jeśli nikt na nie nie patrzy. Alerty łączą zbieranie danych z reagowaniem na incydenty. Kluczem jest alertowanie na symptomy (wpływ na użytkownika), a nie na przyczyny (wysokie CPU).

Wskazówka

Prompt do skopiowania — Reguły alertowania Prometheus:

Utwórz konfiguracje reguł alertowania w monitoring/alerts/:

1. monitoring/alerts/api.yml - Alerty zdrowia API:
   - Wskaźnik błędów > 1% przez 5 minut (ostrzeżenie)
   - Wskaźnik błędów > 5% przez 2 minuty (krytyczny)
   - Latencja p99 > 2 sekundy przez 5 minut (ostrzeżenie)
   - Latencja p99 > 5 sekund przez 2 minuty (krytyczny)
   - Zero żądań przez 1 minutę (krytyczny - serwis prawdopodobnie nie działa)

2. monitoring/alerts/business.yml - Alerty metryk biznesowych:
   - Wskaźnik tworzenia zamówień spada > 50% w porównaniu z tą samą porą wczoraj (ostrzeżenie)
   - Wskaźnik niepowodzeń płatności > 10% przez 10 minut (krytyczny)
   - Zero zamówień przez 15 minut w godzinach roboczych (krytyczny)

3. monitoring/alerts/infrastructure.yml - Alerty zasobów:
   - Wykorzystanie pamięci > 85% przez 10 minut (ostrzeżenie)
   - Wykorzystanie dysku > 90% (krytyczny)
   - Liczba restartów poda > 3 w ciągu 10 minut (ostrzeżenie)

Użyj formatu reguł alertowania Prometheus.
Dołącz URL-e runbooków w adnotacjach każdego alertu.
Każdy alert musi mieć: summary, description, severity i runbook_url.

Notatka

Najczęstszy błąd w alertowaniu to ustawianie zbyt ciasnych progów, co powoduje zmęczenie alertami. Zacznij od hojnych progów i zaostrzaj je na podstawie faktycznych wzorców incydentów. Alert, który odpala się codziennie i jest ignorowany, jest gorszy niż brak alertu.

Generowanie dashboardów

Gdy masz metryki i trace’y, potrzebujesz dashboardów do ich wizualizacji. Cursor może generować konfiguracje dashboardów:

Wskazówka

Prompt do skopiowania — Generowanie dashboardu Grafana:

Utwórz JSON dashboardu Grafana w monitoring/dashboards/api-overview.json z:

Wiersz 1 - Ruch:
- Wskaźnik żądań (żądania/sekundę, per endpoint)
- Wskaźnik błędów (procent odpowiedzi 5xx)
- Aktywne żądania (gauge)

Wiersz 2 - Latencja:
- Latencja p50, p95, p99 w czasie (wykres liniowy)
- Rozkład latencji (mapa cieplna)
- Najwolniejsze endpointy (tabela, ostatnie 5 minut)

Wiersz 3 - Biznes:
- Zamówienia utworzone na minutę
- Wskaźnik sukcesu/porażki płatności
- Przychód na godzinę (jeśli dostępny)

Wiersz 4 - Infrastruktura:
- Wykorzystanie CPU i pamięci per pod
- Opóźnienie pętli zdarzeń
- Wykorzystanie puli połączeń bazodanowych

Użyj Prometheus jako źródła danych.
Dołącz zmienne szablonowe dla: środowisko, serwis, zakres czasu.
Ustaw auto-odświeżanie na 30 sekund.

Kiedy to się psuje

Logi są zbyt szczegółowe na produkcji. Jeśli Agent wygeneruje logowanie na poziomie debug wszędzie, twoje koszty przechowywania logów wystrzelą. Ustaw domyślny poziom logowania na info na produkcji i debug tylko w developmencie. Użyj zmiennej środowiskowej LOG_LEVEL, aby zmienić to bez ponownego wdrażania.

Metryki mają zbyt wiele kombinacji etykiet (eksplozja kardynalności). Jeśli Agent użyje user_id lub request_id jako etykiety metryki, utworzysz miliony szeregów czasowych i twoje przechowywanie metryk się zawiesi. Etykiety metryk powinny mieć niską kardynalność: metoda HTTP, kod statusu, wzorzec endpointu (nie pełny URL z parametrami ścieżki). Przeglądaj każdą etykietę metryki, którą Agent generuje.

Trace’y są niekompletne. Jeśli tylko niektóre serwisy mają skonfigurowane śledzenie, trace’y będą miały luki. Kontekst trace’u (nagłówek traceparent) musi być propagowany przez każdy serwis na ścieżce żądania. Poproś Agenta: “Zweryfikuj, że każde wychodzące wywołanie HTTP w naszym serwisie zawiera nagłówek W3C traceparent z bieżącego kontekstu trace’u.”

Alerty odpalają się zbyt często (zmęczenie alertami). Zacznij od wyższych progów i zaostrzaj je dopiero, gdy masz dane bazowe. Dla nowych wdrożeń użyj “recording rules”, aby obliczyć wartości bazowe przez tydzień przed włączeniem alertów.

Brakuje ID korelacji. Jeśli twoje logi nie mają ID korelacji, nie możesz prześledzić żądania między serwisami. Middleware z pierwszego promptu generuje ID żądań, ale musisz też propagować je w wychodzących żądaniach. Poproś Agenta: “Zaktualizuj naszego klienta HTTP, aby zawierał nagłówek x-correlation-id z async local storage w każdym wychodzącym żądaniu.”

Co dalej

DevOps Wdróż swój stos monitoringu z infrastrukturą jako kod.

Mikroserwisy Zastosuj rozproszone śledzenie w swoich mikroserwisach.

CI/CD Dodaj sprawdzenia monitoringu do swojego pipeline'u wdrożeniowego.