Pakiet startowy obserwowalności produkcyjnej na dzień pierwszy

Co psuje się pierwsze, gdy nowa aplikacja trafia do prawdziwych użytkowników

Pierwsza rzecz, która się psuje, rzadko obejmuje całą aplikację. Zwykle to jeden krok, który nagle robi się zajęty, jedno zapytanie, które w testach było w porządku, albo jedna zależność, która zaczyna timoutować. Prawdziwi użytkownicy dodają prawdziwą różnorodność: wolniejsze telefony, niestabilne sieci, dziwne wejścia i skoki ruchu w niewygodnych momentach.

Kiedy ktoś mówi „to jest wolne”, może mieć na myśli bardzo różne rzeczy. Strona może ładować się zbyt długo, interakcje mogą się przycinać, jedno wywołanie API może timoutować, zadania tła mogą się kumulować, albo zewnętrzna usługa może wszystko spowalniać.

Dlatego potrzebujesz sygnałów zanim potrzebujesz dashboardów. W dniu pierwszym nie potrzebujesz perfekcyjnych wykresów dla każdego endpointu. Potrzebujesz wystarczająco logów, metryk i śledzeń, żeby szybko odpowiedzieć na jedno pytanie: gdzie ucieka czas?

Jest też realne ryzyko nadmiernego instrumentowania na początku. Za dużo zdarzeń tworzy szum, kosztuje pieniądze i może nawet spowolnić aplikację. Co gorsza, zespoły przestają ufać telemetryce, bo wydaje się chaotyczna i niespójna.

Realistyczny cel na dzień pierwszy jest prosty: kiedy dostaniesz zgłoszenie „to jest wolne”, potrafisz znaleźć wolny krok w mniej niż 15 minut. Powinieneś móc powiedzieć, czy wąskie gardło jest w renderowaniu po stronie klienta, w handlerze API i jego zależnościach, w bazie/cache, czy w zadaniu tła lub usłudze zewnętrznej.

Przykład: nowy flow checkout wydaje się wolny. Nawet bez góry narzędzi chcesz być w stanie powiedzieć „95% czasu to wywołania dostawcy płatności” albo „zapytanie koszyka skanuje za dużo wierszy”. Jeśli budujesz aplikacje szybko z narzędziami takimi jak Koder.ai, ta baza na dzień pierwszy ma jeszcze większe znaczenie, bo szybkie wdrażanie pomaga tylko wtedy, gdy potrafisz też szybko debugować.

Logi vs metryki vs śledzenia prostym językiem

Dobry pakiet startowy obserwowalności produkcyjnej używa trzech różnych „widoków” tej samej aplikacji, bo każdy odpowiada na inne pytanie.

Logi to opowieść. Mówią, co się wydarzyło dla jednego żądania, jednego użytkownika lub jednego zadania tła. Wiersz logu może mówić „płatność nieudana dla zamówienia 123” albo „timeout DB po 2s”, plus szczegóły jak request ID, user ID i komunikat błędu. Gdy ktoś zgłasza dziwny, jednorazowy problem, logi często są najszybszym sposobem, by potwierdzić, że się zdarzył i kogo dotyczył.

Metryki to tablica wyników. To liczby, które możesz trendować i na które możesz ustawiać alerty: liczba żądań, rate błędów, percentyle latencji, CPU, głębokość kolejki. Metryki mówią, czy coś jest rzadkie czy powszechne i czy się pogarsza. Jeśli latencja skoczyła dla wszystkich o 10:05, metryki to pokażą.

Śledzenia to mapa. Trace podąża za jednym żądaniem, gdy przemieszcza się przez system (web -> API -> baza -> zewnętrzne). Pokazuje, gdzie spędzany jest czas, krok po kroku. To ważne, bo „to jest wolne” prawie nigdy nie jest jedną wielką tajemnicą. Zwykle to jedno wolne ogniwo.

Podczas incydentu praktyczny flow wygląda tak:

• Użyj metryk, by potwierdzić wpływ (ilu użytkowników, jak źle, kiedy się zaczęło).
• Użyj śledzeń, by znaleźć najwolniejszy krok (jedno wąskie gardło, na które można zadziałać).
• Użyj logów, by wyjaśnić wąskie gardło (konkretne błędy, wejścia lub przypadki brzegowe).

Prosta reguła: jeśli po kilku minutach nie potrafisz wskazać jednego wąskiego gardła, nie potrzebujesz więcej alertów. Potrzebujesz lepszych trace'ów i spójnych ID, które łączą trace'y z logami.

Konwencje na dzień pierwszy, które zapobiegają chaosowi później

Większość incydentów „nie możemy tego znaleźć” nie wynika z brakujących danych. Dzieje się tak, ponieważ ta sama rzecz jest zapisywana inaczej w różnych usługach. Kilka wspólnych konwencji na dzień pierwszy sprawia, że logi, metryki i trace'y zgadzają się, gdy potrzebujesz odpowiedzi szybko.

Zacznij od wybrania jednej nazwy usługi na jednostkę deployowalną i utrzymania jej stabilnej. Jeśli „checkout-api” staje się „checkout” na połowie dashboardów, tracisz historię i psujesz alerty. Zrób to samo dla etykiet środowiska. Wybierz mały zestaw, np. prod i staging, i używaj ich wszędzie.

Następnie spraw, by każde żądanie było łatwe do śledzenia. Generuj request ID na krawędzi (API gateway, serwer WWW lub pierwszy handler) i przekaż go przez wywołania HTTP, kolejki wiadomości i zadania tła. Jeśli ticket wsparcia mówi „było wolno o 10:42”, pojedyncze ID pozwala wyciągnąć dokładne logi i trace bez zgadywania.

Zestaw konwencji, który dobrze działa na dzień pierwszy:

• Tożsamość: nazwa usługi, środowisko, wersja (lub SHA buildu)
• Korelacja: request ID propagowany przez usługi i zadania
• Podstawowe tagi: route (lub handler), metoda, kod statusu i tenant/org ID jeśli jesteś multi-tenant
• Nazwy operacji śledzenia: nazwij operacje jak endpointy i zadania tła (nie losowe nazwy funkcji)
• Spójność: jeden styl nazewnictwa i jedna jednostka czasu dla duracji

Uzgodnij jednostki czasu wcześnie. Wybierz milisekundy dla latencji API i sekundy dla dłuższych zadań i trzymaj się tego. Mieszane jednostki tworzą wykresy, które wyglądają poprawnie, ale opowiadają błędną historię.

Konkretny przykład: jeśli każdy API loguje duration_ms, route, status i request_id, to raport „checkout jest wolny dla tenant 418” staje się szybkim filtrem, a nie debatą, od czego zacząć.

Minimalne logowanie do dodania na dzień pierwszy

Jeśli zrobisz tylko jedną rzecz w pakiecie startowym obserwowalności produkcyjnej, spraw, by logi były łatwe do przeszukania. To zaczyna się od ustrukturyzowanych logów (zwykle JSON) i tych samych pól we wszystkich usługach. Logi tekstowe są w porządku do lokalnego devu, ale przy prawdziwym ruchu, retryach i wielu instancjach zamieniają się w hałas.

Dobra zasada: loguj to, czego faktycznie użyjesz podczas incydentu. Większość zespołów musi odpowiedzieć: Jakie to było żądanie? Kto to zrobił? Gdzie to zawiodło? Co to dotknęło? Jeśli wiersz logu nie pomaga w jednej z tych rzeczy, prawdopodobnie nie powinien istnieć.

Na dzień pierwszy trzymaj mały, spójny zestaw pól, aby móc filtrować i łączyć zdarzenia między usługami:

• Timestamp, level i tożsamość usługi (service name, version, environment)
• Korelacja żądań (request_id, trace_id jeśli masz)
• Kto/gdzie (user_id lub session_id, route, method)
• Wynik (status code, duration_ms)
• Kontekst deployu (region/instance, release lub commit)

Gdy wystąpi błąd, zaloguj go raz, z kontekstem. Dołącz typ błędu (lub kod), krótki komunikat, stack trace dla błędów serwera i zależność upstream (np. postgres, payment provider, cache). Unikaj powtarzania tego samego stack trace przy każdym retry. Zamiast tego dołącz request_id, by móc śledzić łańcuch.

Przykład: użytkownik zgłasza, że nie może zapisać ustawień. Jedno wyszukanie po request_id pokazuje 500 na PATCH /settings, potem downstream timeout do Postgres z duration_ms. Nie potrzebowałeś pełnych payloadów, tylko route, user/session i nazwę zależności.

Prywatność jest częścią logowania, nie zadaniem później. Nie loguj haseł, tokenów, nagłówków auth, pełnych ciał żądań ani wrażliwych PII. Jeśli musisz identyfikować użytkownika, loguj stabilne ID (lub jego hasz) zamiast e-maili czy numerów telefonu.

Jeśli budujesz aplikacje na Koder.ai (React, Go, Flutter), warto wpleść te pola w każdą generowaną usługę od początku, żeby nie kończyć na „poprawianiu logów” podczas pierwszego incydentu.

Minimalne metryki, które wykryją większość problemów produkcyjnych

Dobry pakiet startowy zaczyna się od małego zestawu metryk, które szybko odpowiadają na pytanie: czy system jest teraz zdrowy, a jeśli nie, to gdzie boli?

Złote sygnały

Większość problemów produkcyjnych pojawia się jako jeden z czterech „golden signals”: latency (odpowiedzi są wolne), traffic (obciążenie się zmieniło), errors (coś zawodzi) i saturation (wspólny zasób jest wykorzystany do granic). Jeśli widzisz te cztery sygnały dla każdego głównego fragmentu aplikacji, możesz triage'ować większość incydentów bez zgadywania.

Latencja powinna być mierzona percentylami, nie średnimi. Śledź p50, p95 i p99, żeby zobaczyć, kiedy mała grupa użytkowników ma zły czas. Dla ruchu zacznij od requests per second (lub jobs per minute dla workerów). Dla błędów rozdziel 4xx vs 5xx: rosnące 4xx często oznaczają zmianę zachowania klienta lub walidacji; rosnące 5xx wskazują na twoją aplikację lub jej zależności. Saturacja to sygnał „kończą nam się zasoby” (CPU, pamięć, połączenia DB, backlog kolejki).

Checklist metryk według komponentu

Minimalny zestaw obejmujący większość aplikacji:

• HTTP/API: requests per second, p50/p95/p99 latency, 4xx rate, 5xx rate
• Baza danych: query latency (przynajmniej p95), użycie puli połączeń (in-use vs max), timeouts, liczba slow queries
• Workerzy/kolejki: głębokość kolejki, job runtime p95, retrysy, dead-letter count (lub failed jobs)
• Zasoby: CPU %, użycie pamięci, użycie dysku (i I/O jeśli to boli), restarty kontenerów
• Zdrowie deployu: aktualna wersja, error rate po deployu, pętle restartów (często pierwszy sygnał złego releasu)

Konkretne przyklady: jeśli użytkownicy zgłaszają „to jest wolne” i p95 API skacze przy stałym ruchu, sprawdź saturację. Jeśli użycie puli DB jest bliskie maxa i rosną timeouts, znalazłeś prawdopodobne wąskie gardło. Jeśli DB wygląda dobrze, a głębokość kolejki szybko rośnie, praca tła może zabierać współdzielone zasoby.

Jeśli używasz Koder.ai, traktuj tę checklistę jako część definicji „done” na dzień pierwszy. Łatwiej dodać te metryki, gdy aplikacja jest mała niż podczas pierwszego prawdziwego incydentu.

Minimalne śledzenie, które sprawia, że „wolne” jest debugowalne

Gdy użytkownik mówi „to jest wolne”, logi często mówią, co się wydarzyło, a metryki jak często to występuje. Trace'y mówią, gdzie poszedł czas wewnątrz jednego żądania. Ta pojedyncza oś czasu zmienia niejasne narzekanie w jasną poprawkę.

Zacznij po stronie serwera. Instrumentuj przychodzące żądania na krawędzi aplikacji (pierwszy handler, który odbiera żądanie), tak aby każde żądanie mogło wygenerować trace. Trace'y po stronie klienta mogą poczekać.

Dobry trace na dzień pierwszy ma spany, które odpowiadają częściom zwykle powodującym opóźnienia:

• Span handlera żądania dla całego żądania
• Span wywołania do bazy dla każdego zapytania/transakcji
• Span wywołania cache (get/set) kiedy używasz cache
• Span zewnętrznego wywołania HTTP dla każdej zależności
• Span zadania tła, gdy żądanie enqueuje pracę, od której zależy

Aby trace'y były wyszukiwalne i porównywalne, przechwyć kilka kluczowych atrybutów i trzymaj je spójnie między usługami.

Dla span'a przychodzącego żądania zapisz route (użyj szablonu jak /orders/:id, nie pełnego URL), metodę HTTP, kod statusu i latencję. Dla spanów DB zapisz system DB (PostgreSQL, MySQL), typ operacji (select, update) i nazwę tabeli, jeśli łatwo ją dodać. Dla zewnętrznych wywołań zapisz nazwę zależności (payments, email, maps), host docelowy i status.

Sampling ma znaczenie na dzień pierwszy, inaczej koszty i szum szybko rosną. Użyj prostej reguły head-based: śledź 100% błędów i wolnych żądań (jeśli SDK to wspiera), i próbkuj mały procent normalnego ruchu (np. 1–10%). Zaczynaj wyżej przy niskim ruchu, potem redukuj.

Co oznacza „dobrze”: jeden trace, w którym możesz przeczytać historię od góry do dołu. Przykład: GET /checkout trwał 2.4s, DB zużył 120ms, cache 10ms, a zewnętrzne wywołanie płatności zajęło 2.1s z retryem. Teraz wiesz, że problem leży po stronie zależności, nie twojego kodu. To sedno pakietu startowego obserwowalności produkcyjnej.

Prosty flow triage dla zgłoszeń „to jest wolne"

Kiedy ktoś mówi „to jest wolne”, najszybszy sukces to zamienić to niejasne odczucie w kilka konkretnych pytań. Ten flow triage działa nawet jeśli twoja aplikacja jest świeża.

5-krokowy triage

Zacznij od zawężenia problemu, potem podążaj za dowodami w kolejności. Nie skacz od razu do bazy danych.

1. Potwierdź zakres. Czy to jeden użytkownik, jedno konto klienta, jeden region, czy wszyscy? Zapytaj też: czy dzieje się to na Wi‑Fi i komórkowym, i w więcej niż jednej przeglądarce/urządzeniu?
2. Sprawdź, co zmieniło się pierwsze. Czy wolumen żądań skoczył, czy wzrósł rate błędów, czy sama latencja? Skok ruchu często powoduje kolejkowanie; wzrost błędów sugeruje zepsutą zależność.
3. Podziel spowolnienie według trasy lub operacji. Sprawdź p95 latency po endpointach (lub typach jobów) i znajdź najgorszego winowajcę. Jeśli tylko jedna trasa jest wolna, skup się na niej. Jeśli wszystkie są wolniejsze, myśl o współdzielonych zależnościach lub przepustowości.
4. Otwórz trace dla wolnej ścieżki. Weź trace z wolnego żądania i posortuj spany według czasu trwania. Cel to jedno zdanie: „Większość czasu jest w X.”
5. Zweryfikuj zależności i zdecyduj o rollbackie. Sprawdź saturację bazy, wolne zapytania, cache hit rate i czasy odpowiedzi zewnętrznych. Jeśli spowolnienie zaczęło się zaraz po wdrożeniu lub zmianie konfiguracji, rollback często jest najbezpieczniejszym pierwszym krokiem.

Po ustabilizowaniu sytuacji zrób jedną małą poprawkę: zapisz, co się stało i dodaj jeden brakujący sygnał. Na przykład, jeśli nie dało się określić, czy spowolnienie było tylko w jednym regionie, dodaj tag regionu do metryk latencji. Jeśli widziałeś długi span bazy bez wskazania, które zapytanie, dodaj etykiety zapytań ostrożnie lub pole „query name”.

Szybki przykład: jeśli p95 dla checkout skacze z 400 ms do 3 s, a trace'y pokazują span płatności trwający 2.4 s, możesz przestać debatować nad kodem aplikacji i skupić się na providerze, retryach i timeoutach.

Szybkie kontrole, które możesz zrobić w 5 minut

Gdy ktoś mówi „to jest wolne”, możesz zmarnować godzinę tylko na ustalenie, co miało na myśli. Pakiet startowy obserwowalności jest użyteczny tylko, jeśli pomaga szybko zawęzić problem.

Zacznij od trzech wyjaśniających pytań:

• Kto jest dotknięty (jeden użytkownik, segment klientów, wszyscy)?
• Jaka dokładnie akcja jest wolna (ładowanie strony, wyszukiwanie, checkout, logowanie)?
• Od kiedy to się dzieje (minuty temu, po deployu, od rana)?

Potem spójrz na kilka liczb, które zwykle mówią, gdzie iść dalej. Nie szukaj idealnego dashboardu. Chcesz tylko „gorsze niż normalnie” sygnały.

• Aktualny rate błędów (skoki często sprawiają, że użytkownicy odczuwają spowolnienie)
• p95 latency dla dotkniętego endpointu (nie średnia)
• Saturacja: CPU, pamięć, połączenia DB lub głębokość kolejki (wybierz to, co twoja aplikacja uderza pierwsze)

Jeśli p95 rośnie, a błędy są stabilne, otwórz jeden trace dla najwolniejszej trasy z ostatnich 15 minut. Pojedynczy trace często pokaże, czy czas spędzany jest w bazie, zewnętrznym API czy czekaniu na locki.

Następnie wykonaj jedno wyszukiwanie w logach. Jeśli masz konkretne zgłoszenie użytkownika, szukaj po request_id (lub trace_id jeśli go zapisujesz) i czytaj timeline. Jeśli nie, wyszukaj najczęstszy komunikat błędu w tym samym oknie czasowym i sprawdź, czy pokrywa się ze spowolnieniem.

Na końcu zdecyduj, czy od razu łagodzić sytuację, czy dalej drążyć. Jeśli użytkownicy są zablokowani i saturacja jest wysoka, szybkie działanie (scale up, rollback lub wyłączenie nieistotnej flagi funkcjonalnej) może kupić czas. Jeśli wpływ jest mały i system stabilny, kontynuuj dochodzenie z trace'ami i logami slow query.

Przykład: diagnozowanie wolnego checkoutu bez zgadywania

Kilka godzin po releasie support zaczyna otrzymywać tickety: „Checkout trwa 20–30 sekund.” Nikt nie potrafi tego odtworzyć na laptopie, więc zaczyna się zgadywanie. Tutaj pakiet startowy się opłaca.

Najpierw idź do metryk i potwierdź symptom. Wykres p95 dla żądań HTTP pokazuje wyraźny spike, ale tylko dla POST /checkout. Inne trasy wyglądają normalnie, a rate błędów jest stabilny. To zawęża problem z „cała strona jest wolna” do „jeden endpoint spowolnił po releasie”.

Następnie otwórz trace dla wolnego żądania POST /checkout. Kaskada trace'a ujawnia winowajcę. Dwa częste wyniki:

• Span „PaymentProvider.charge” trwa 18 sekund, większość czasu spędzona na oczekiwaniu.
• Span „DB: insert order” jest wolny, pokazując długie czekanie zanim zapytanie zwróci.

Teraz zweryfikuj logami, używając tego samego request ID z trace'a (lub trace ID jeśli go przechowujesz w logach). W logach dla tego żądania widzisz powtarzające się ostrzeżenia jak „payment timeout reached” lub „context deadline exceeded”, plus retrye dodane w nowym releasie. Jeśli to ścieżka DB, logi mogą pokazywać komunikaty o czekaniu na locki lub treść wolnego zapytania przekraczającego próg.

Gdy wszystkie trzy sygnały są zgodne, naprawa jest prosta:

• Cofnij release do poprzedniej wersji, żeby zatrzymać ból.
• Dodaj eksplicytne timeouty dla wywołań płatności (i ogranicz retrysy).
• Dodaj metrykę dla latencji zależności, np. p95 payment provider duration i p95 DB query duration.

Kluczowe jest to, że nie zgadywałeś. Metryki wskazały endpoint, trace'y wskazały wolny krok, a logi potwierdziły tryb awarii z dokładnym żądaniem w ręku.

Typowe błędy, które marnują czas podczas incydentów

Większość czasu incydentu jest tracona na uniknione luki: dane są, ale są hałaśliwe, ryzykowne lub brakuje jednego drobnego detalu, który łączy symptomy z przyczyną. Pakiet startowy działa tylko, jeśli pozostaje użyteczny pod stresem.

Jedną pułapką jest logowanie za dużo, zwłaszcza surowych ciał żądań. Brzmi pomocnie, dopóki nie płacisz za ogromne przechowywanie, wyszukiwanie stanie się wolne i przypadkowo nie złapiesz haseł, tokenów czy danych osobowych. Preferuj ustrukturyzowane pola (route, status code, latency, request_id) i loguj tylko małe, jawnie dozwolone fragmenty wejścia.

Innym marnotrawstwem czasu są metryki wyglądające na szczegółowe, ale nieagregowalne. Etykiety wysokiej kardynalności jak pełne user ID, e-maile czy unikalne numery zamówień mogą eksplodować liczbę serii metrycznych i uczynić dashboardy zawodnymi. Używaj etykiet ogólnych (nazwa trasy, metoda HTTP, klasa statusu, nazwa zależności), a wszystko specyficzne dla użytkownika trzymaj w logach.

Błędy, które najczęściej blokują szybką diagnozę:

• Patrzenie tylko na średnie. Średnie ukrywają prawdziwy ból; sprawdzaj p95 i p99, gdy ktoś mówi „to jest wolne”.
• Trace'y bez kontekstu. Jeśli spany nie mają nazw tras i jasnych nazw zależności, trace staje się obrazkiem bez etykiet.
• Brak znacznika wydania. Jeśli nie widać, kiedy zmieniła się wersja, zgadujesz, czy deploy to spowodował.
• Alerty bez właściciela. Gdy alerty dzwonią, a nikt nie wie, co robić, stają się hałasem, a potem ignorowane.
• Logi, które są nieprzeszukiwalne. Wolny tekst bez spójnych kluczy zamienia każdy incydent w manualne grepowanie.

Mały praktyczny przykład: jeśli p95 dla checkout rośnie z 800ms do 4s, chcesz odpowiedzieć na dwa pytania w minutach: czy zaczęło się zaraz po deployu i czy czas jest spędzany w twojej aplikacji czy w zależności (DB, payment provider, cache)? Z percentylami, tagiem wersji i trace'ami z nazwami tras i zależności jesteś tam szybko. Bez nich tracisz okno incydentu na zgadywanie.

Następne kroki: spraw, by to było powtarzalne dla każdej nowej aplikacji

Prawdziwy zysk to spójność. Pakiet startowy obserwowalności pomaga tylko wtedy, gdy każda nowa usługa shipuje z tymi samymi podstawami, nazwanymi tak samo i łatwymi do znalezienia, gdy coś psuje się.

Zamień wybory dnia pierwszego w krótki szablon, którego zespół będzie używał. Trzymaj go małego, ale konkretnego.

• Generuj request ID dla każdego przychodzącego żądania i noś go w logach i trace'ach.
• Loguj te kilka zdarzeń, których zawsze potrzebujesz: start/finish żądania, błędy (z jasnym typem) i wolne żądania powyżej progu.
• Śledź garstkę złotych metryk: ruch, rate błędów, latencję (p50 i p95) oraz jeden sygnał saturacji (CPU, pamięć, pula DB lub głębokość kolejki).
• Dodaj podstawowe trace'y dla kluczowych tras i głównych zależności (DB i jedna zewnętrzna API).
• Dołącz etykiety release/version do logów, metryk i trace'ów, by móc odpowiedzieć: „czy zaczęło się po deployu?”

Stwórz jeden widok „home”, który każdy może otworzyć podczas incydentu. Jeden ekran powinien pokazywać requests per minute, rate błędów, p95 latency i główną metrykę saturacji, z filtrem dla środowiska i wersji.

Trzymaj alertowanie minimalne na początku. Dwa alerty obejmują dużo: spike rate błędów na kluczowej trasie i spike p95 latency na tej samej trasie. Jeśli dodajesz więcej, upewnij się, że każdy ma jasną akcję.

Na koniec ustaw comiesięczny przegląd. Usuń hałaśliwe alerty, popraw nazewnictwo i dodaj jeden brakujący sygnał, który zaoszczędziłby czasu przy ostatnim incydencie.

Aby wpleść to w proces budowy, dodaj „observability gate” do checklisty wydania: brak deployu bez request ID, tagów wersji, widoku home i dwóch podstawowych alertów. Jeśli deployujesz z Koder.ai, możesz zdefiniować te sygnały dnia pierwszego w trybie planowania przed wdrożeniem, potem iterować bezpiecznie używając snapshotów i rollbacku, gdy trzeba szybko poprawić sytuację.