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
Dział zatytułowany „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
Dział zatytułowany „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.
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 loggerz 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
Dział zatytułowany „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.
@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_method2. 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 trace4. 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
Dział zatytułowany „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.
Rozproszone śledzenie
Dział zatytułowany „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.
@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
Dział zatytułowany „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).
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.Generowanie dashboardów
Dział zatytułowany „Generowanie dashboardów”Gdy masz metryki i trace’y, potrzebujesz dashboardów do ich wizualizacji. Cursor może generować konfiguracje dashboardów:
Kiedy to się psuje
Dział zatytułowany „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.”