Logi i diagnostyka problemów po wdrożeniu
Zdiagnozujesz nieudane wdrożenie warstwa po warstwie: od procesu i portu aplikacji przez Nginx i TLS aż po DNS oraz zasoby systemu.
1. Krótka teoria
Skuteczna diagnostyka nie polega na wielokrotnym restartowaniu usługi, lecz na ustaleniu, w której warstwie znika poprawna odpowiedź. Najpierw systemctl status example-app pokazuje, czy proces został uruchomiony, a journalctl -u example-app ujawnia błędy importu, brak konfiguracji, problemy z uprawnieniami lub bazą. Opcja -n 100 pobiera ostatnie wpisy, --since ogranicza czas, -f śledzi nowe zdarzenia, a -b może ograniczyć logi do bieżącego uruchomienia systemu. Kolejny krok to bezpośredni test Uvicorna na 127.0.0.1:8000 i kontrola nasłuchu przez ss -tlnp. Jeśli aplikacja lokalnie odpowiada, sprawdza się nginx -t, status Nginxa oraz /var/log/nginx/error.log i access.log. Dopiero potem bada się publiczną domenę, TLS oraz DNS przez curl i dig. Warstwy mają różne objawy: błędny DNS prowadzi pod niewłaściwy adres; problem TLS zatrzymuje zestawienie bezpiecznego połączenia; Nginx może zwrócić 502, gdy nie połączy się z Uvicornem; aplikacja może zwrócić 500 przy błędzie kodu lub bazy. Kod 404 oznacza brak wskazanego zasobu lub niedopasowaną trasę, 502 Bad Gateway zwykle problem z upstreamem, 503 Service Unavailable niedostępność usługi, a 500 Internal Server Error błąd obsługi żądania. Kody są wskazówką, nie pełną diagnozą. Trzeba też sprawdzić procesy i zasoby: pełny dysk może uniemożliwić zapis bazy lub logów, brak pamięci może zakończyć proces, a wysokie obciążenie może powodować timeouty. df -h, free -h i uptime szybko pokazują podstawowy stan. Rozsądna kolejność to: status i logi aplikacji, lokalny port, lokalna odpowiedź, Nginx, publiczny HTTPS, DNS i zasoby. Restart wykonuje się dopiero wtedy, gdy wynika z diagnozy; bez rozpoznania przyczyny może chwilowo ukryć problem i zatrzeć część kontekstu.
2. Przykłady komend
systemctl status example-app --no-pager -l
Pokazuje stan usługi aplikacji i pełne ostatnie komunikaty.
$ systemctl status example-app --no-pager -l
journalctl -u example-app -n 100 --no-pager
Wyświetla sto ostatnich wpisów dziennika jednostki.
$ journalctl -u example-app -n 100 --no-pager
journalctl -u example-app --since "10 minutes ago"
Ogranicza logi do okresu obejmującego ostatnie wdrożenie.
$ journalctl -u example-app --since "10 minutes ago"
journalctl -u example-app -f
Śledzi nowe logi podczas kontrolowanego testu żądania.
$ journalctl -u example-app -f
sudo nginx -t && systemctl status nginx --no-pager -l
Sprawdza konfigurację i stan warstwy reverse proxy.
$ sudo nginx -t
$ systemctl status nginx --no-pager -l
sudo tail -n 100 /var/log/nginx/error.log
Pokazuje ostatnie błędy połączeń, konfiguracji i upstreamu Nginxa.
$ sudo tail -n 100 /var/log/nginx/error.log
curl -v http://127.0.0.1:8000/ && curl -I https://app.example.com/
Porównuje bezpośrednią odpowiedź Uvicorna z publicznym adresem HTTPS.
$ curl -v http://127.0.0.1:8000/
$ curl -I https://app.example.com/
ss -tlnp && ps aux
Pokazuje nasłuchujące porty i uruchomione procesy.
$ ss -tlnp
$ ps aux
df -h && free -h && uptime && dig app.example.com
Sprawdza dysk, pamięć, obciążenie oraz rozwiązanie domeny.
$ df -h
$ free -h
$ uptime
$ dig app.example.com3. Zadanie praktyczne
https://app.example.com zwraca 502. Sprawdź kolejno status i logi example-app z ostatnich 10 minut, nasłuch portu przez ss -tlnp, odpowiedź curl -v http://127.0.0.1:8000/, test i log błędów Nginxa, publiczny HTTPS oraz rekord DNS. Na końcu sprawdź df -h, free -h i uptime. Dla każdego kroku zapisz obserwację i wniosek. Nie restartuj usługi, dopóki nie wskażesz hipotezy, którą restart ma sprawdzić lub naprawić.
4. Typowe błędy
- Restartowanie usługi bez wcześniejszego zapisania stanu i odczytania logów.
- Diagnozowanie publicznej domeny bez bezpośredniego testu 127.0.0.1:8000.
- Traktowanie każdego 502 jako błędu DNS.
- Sprawdzanie tylko logów aplikacji i pomijanie error.log Nginxa.
- Ignorowanie pełnego dysku, braku pamięci i wysokiego obciążenia.
- Wyciąganie wniosków z samego kodu HTTP bez korelacji z logami.
- Używanie journalctl -f bez ograniczenia wcześniejszych wpisów do czasu wdrożenia.
5. Podsumowanie
Problemy po wdrożeniu należy rozdzielać na DNS, TLS, Nginx, Uvicorn, aplikację i bazę danych. Status oraz journalctl pokazują stan procesu, lokalny curl i ss weryfikują upstream, a test i logi Nginxa wyjaśniają błędy reverse proxy. Publiczny test, DNS i zasoby systemu uzupełniają obraz. Restart ma wynikać z diagnozy, ponieważ wykonany bez przyczyny może tylko ukryć problem.