Logi kompilacji i środowiska uruchomieniowego: debugowanie wdrożeń Dockup

Logi kompilacji i środowiska uruchomieniowego odpowiadają na różne pytania. Logi kompilacji wyjaśniają, jak kod źródłowy został przekształcony w obraz oraz dlaczego ten proces zakończył się niepowodzeniem. Logi środowiska uruchomieniowego pokazują, co zrobiła zbudowana aplikacja po uruchomieniu kontenera lub workloadu Kubernetes.

Odczytywanie niewłaściwego strumienia powoduje stratę czasu. Brakująca zależność podczas tworzenia obrazu nigdy nie pojawi się w logach środowiska uruchomieniowego, natomiast obraz, który został poprawnie zbudowany, ale ulega awarii przy uruchamianiu, może mieć całkowicie poprawne logi kompilacji.

Czym różnią się logi kompilacji od logów środowiska uruchomieniowego?

Wybierz strumień na podstawie etapu wdrożenia:

Etap	Typowy status	Właściwe logi	Typowe awarie
Klonowanie	cloning	Kompilacja	Dostęp do repozytorium, branch
Instalowanie zależności	building	Kompilacja	Lockfile, registry, pakiet
Kompilowanie/bundlowanie	building	Kompilacja	Błędy typów, pamięć, brakujące pliki
Uruchamianie obrazu	deploying	Środowisko uruchomieniowe i health	Komenda startowa, port, uprawnienia
Działająca usługa	running	Środowisko uruchomieniowe	Wyjątki, awarie zależności
Bramka gotowości	deploying	Środowisko uruchomieniowe wraz z konfiguracją health	Nieprawidłowa ścieżka, powolny start

Odczytaj najnowsze logi kompilacji:

dockup logs production/api --build --json

Odczytaj logi środowiska uruchomieniowego działającej usługi:

dockup logs production/api --json

Pobierz więcej wierszy logów środowiska uruchomieniowego, gdy istotne zdarzenie jest starsze:

dockup logs production/api -n 500 --json

Odpowiedź JSON identyfikuje cel i typ logów, dzięki czemu agent może uniknąć łączenia niezwiązanych ze sobą strumieni.

Jak działa dockup logs --build --follow?

Tryb śledzenia przesyła nowe wiersze, odpy­tując bieżący snapshot:

dockup logs production/api --build -f --json

W trybie JSON dane wyjściowe mają format NDJSON: jeden obiekt na wiersz i na batch. Konsument może przetwarzać każdy wiersz przyrostowo.

Końcowy batch oznacza końcowy wynik kompilacji. Komenda samoczynnie kończy działanie, gdy wdrożenie zakończy się powodzeniem lub niepowodzeniem, a w przypadku niepowodzenia zwraca niezerowy kod wyjścia. Dzięki temu nadaje się do użycia przez agenta lub zadanie CI bez ręcznie napisaniej pętli sprawdzającej status.

Śledzenie logów środowiska uruchomieniowego działa podobnie:

dockup logs production/api -f --json

Każdy batch zawiera pole restarted. Gdy restarted:true, kontener został uruchomiony ponownie albo zachowany bufor został przewinięty, więc Dockup wysyła ponownie cały bieżący snapshot zamiast po cichu pomijać wiersze.

Domyślny interwał odpytywania wynosi 2 sekundy. Używaj udokumentowanego --interval tylko wtedy, gdy istnieje konkretny powód, aby zmienić częstotliwość.

Jak diagnozować nieudaną kompilację?

Zacznij od końcowego wyniku wdrożenia:

dockup deploy production/api --wait --json

Gdy komenda zakończy się statusem deploy_failed, pobierz log kompilacji i znajdź pierwszy błąd przyczynowy, a nie ostatni komunikat będący skutkiem kaskady błędów.

Przydatna kolejność działań:

1. Potwierdź cel i identyfikator wdrożenia.
2. Ustal, czy problem wystąpił na etapie klonowania, instalowania, kompilowania czy tworzenia obrazu.
3. Znajdź pierwszy błąd, którego nie można naprawić przez ponowienie próby.
4. Porównaj metodę kompilacji z założeniami repozytorium.
5. Jeśli to możliwe, odtwórz problem na czystym klonie.
6. Wprowadź jedną, ukierunkowaną zmianę.
7. Wdróż ponownie z opcją --wait.

Typowe problemy Nixpacks obejmują nierozpoznany katalog główny projektu, brakujący lockfile, brak standardowego skryptu startowego lub wymaganie pakietu natywnego. Typowe problemy z Dockerfile obejmują nieprawidłowy kontekst kompilacji, brakujący skopiowany artefakt, niedostępny obraz bazowy lub nieudaną instrukcję RUN.

Przewodnik Nixpacks a Dockerfile przedstawia mapę decyzji dotyczących systemu kompilacji.

Nie próbuj naprawiać deterministycznego błędu kompilacji przez zwiększenie limitu czasu z 900 sekund. Zmiana limitu pomaga w przypadku uzasadnionej, długiej kompilacji, ale nie naprawia komendy, która zakończyła się błędem.

Jak diagnozować awarię środowiska uruchomieniowego lub nieudaną kontrolę health?

Poprawnie zbudowany obraz może nadal zakończyć się niepowodzeniem przed przełączeniem ruchu. Sprawdź stan usługi i logi środowiska uruchomieniowego:

dockup status production/api --json
dockup logs production/api --json
dockup health production/api --json

Zwróć uwagę na:

• Proces kończy się natychmiast po uruchomieniu.
• Aplikacja nasłuchuje na nieprawidłowym porcie.
• Aplikacja nasłuchuje na 127.0.0.1 zamiast na wszystkich interfejsach.
• Brakuje wymaganego klucza środowiskowego.
• Połączenie z bazą danych lub Redis kończy się niepowodzeniem.
• Uprawnienia do plików blokują uruchomienie.
• Ścieżka health zwraca status oznaczający niepowodzenie.
• Uruchamianie trwa dłużej, niż pozwala na to skonfigurowana liczba ponowień.
• Migracja kończy się niepowodzeniem lub jest uruchamiana równolegle.

Konfigurację health można sprawdzić lub zaktualizować:

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

Nie osłabiaj bramki health tylko po to, aby przepuścić wadliwe wydanie. Jeśli uruchomienie rzeczywiście wymaga więcej czasu, zmień politykę na podstawie dowodów i zachowaj endpoint, który nadal potwierdza gotowość.

Zmiany środowiska wymagają ponownego wdrożenia. Jeśli naprawiono brakujący sekret, wdróż ponownie i zaczekaj; ponowne uruchomienie starego kontenera nie zastosuje nowego oczekiwanego środowiska.

Jak agenci powinni analizować NDJSON bez utraty kodu wyjścia?

Agent lub skrypt powinien odczytywać każdy wiersz JSON, zachowując jednocześnie status procesu. Unikaj przekierowywania danych do komendy, która ukrywa oryginalny kod wyjścia, jeśli nie używasz pipefail.

set -o pipefail
dockup logs production/api --build -f --json \
  | tee build-stream.ndjson

Dzięki pipefail nieudana komenda Dockup sprawia, że cały potok zwraca wartość różną od zera, nawet jeśli tee zakończyło się pomyślnie.

Konsument może analizować każdy obiekt niezależnie:

while IFS= read -r line; do
  printf '%s\n' "$line" | jq -r '.lines[]?'
done < build-stream.ndjson

Zachowaj surowy artefakt NDJSON. Czytelny dla człowieka fragment jest przydatny w pull requeście lub podczas obsługi incydentu, ale oryginalne pola zachowują znaczniki ponownego uruchomienia, status i sygnały zakończenia.

Ogólne zasady projektowania interfejsów maszynowych opisano w artykule Projektowanie CLI dla agentów AI.

Jak przygotować powtarzalny runbook do debugowania wdrożeń?

Skorzystaj z następującej ścieżki decyzyjnej:

dockup status production/api --json
dockup deployments production/api -n 5 --json
dockup logs production/api --build --json
dockup logs production/api --json

Następnie sklasyfikuj incydent:

Klasyfikacja	Dowody	Następne działanie
Kod źródłowy/kompilacja	Błąd w logu kompilacji	Napraw repozytorium lub definicję kompilacji
Konfiguracja	Brakujące/nieprawidłowe środowisko lub port	Popraw konfigurację i wdróż ponownie
Gotowość	Aplikacja działa, ale health kończy się niepowodzeniem	Napraw endpoint lub uzasadnij zmianę czasu
Zależność środowiska uruchomieniowego	Wyjątek połączenia	Sprawdź bazę danych/sieć/poświadczenia
Regresja	Poprzednia wersja działała	Rozważ rollback po znanym identyfikatorze
Niepewność platformy	Timeout, brak stanu końcowego	Przed ponowieniem sprawdź status

Wykonuj rollback dopiero po zidentyfikowaniu znanego poprzedniego wdrożenia:

dockup rollback <deploymentId> production/api --json

Najpierw zachowaj identyfikator nieudanego wdrożenia i logi. Rollback przywraca dostępność usługi, ale nie wyjaśnia głównej przyczyny.

Artykuł wdrożenia bez przestoju wyjaśnia, dlaczego nieudana bramka gotowości może chronić działający ruch.

Jak sprawić, aby logi produkcyjne były użyteczne?

Dockup może pobierać dane wyjściowe, ale za jakość logów odpowiada aplikacja. Preferuj ustrukturyzowane rekordy pojedynczych zdarzeń zawierające znaczniki czasu, poziom ważności, identyfikatory żądań lub trace, nazwę komponentu i bezpieczny opis błędu.

Nigdy nie rejestruj tokenów dostępu, adresów URL baz danych, haseł, pełnych nagłówków autoryzacji ani danych osobowych, które nie są niezbędne do działania systemu. Maskowanie sekretów w konfiguracji Dockup nie redaguje dowolnych danych wyjściowych aplikacji.

Rejestruj bezpieczne i przydatne diagnostycznie informacje o uruchomieniu:

• Wersję aplikacji lub commit.
• Nazwę środowiska.
• Port nasłuchiwania.
• Nazwy włączonych funkcji bez wartości sekretów.
• Klasę hosta bazy danych, ale nie hasło.
• Wersję migracji.
• Gotowość endpointu health.

Szablon osi czasu incydentu

Zapisz:

1. Identyfikator wdrożenia i commit źródłowy.
2. Znaczniki czasu rozpoczęcia wdrożenia i jego zakończenia.
3. Pierwszy przyczynowy błąd kompilacji lub środowiska uruchomieniowego.
4. Wynik bramki health.
5. Komendę odzyskiwania i identyfikator wdrożenia.
6. Okres wpływu na użytkowników.
7. Osobę odpowiedzialną za dalsze działania.

Dane uptime dodają dostępność i czas odpowiedzi z dokładnością do minuty:

dockup uptime production/api --hours 24 --json

Wynik zawiera średni czas odpowiedzi oraz p95. Połącz go z logami kompilacji i środowiska uruchomieniowego, aby odróżnić incydent wdrożeniowy od dłuższej regresji wydajności.

Skorzystaj z dokumentacji CLI Dockup, aby sprawdzić aktualne flagi logów, oraz z artykułu najlepsze praktyki bezpieczeństwa, aby bezpiecznie rejestrować logi aplikacji.

Koreluj logi z historią wdrożeń

Wiersz logu jest użyteczny tylko wtedy, gdy można go powiązać z właściwym wydaniem. Przechowuj identyfikator wdrożenia, hash commit oraz czas rozpoczęcia obok artefaktu logów. Gdy dwa wydania następują w krótkim odstępie, same znaczniki czasu mogą wprowadzać w błąd.

dockup deployments production/api -n 20 --json

Historia wdrożeń pokazuje, które źródło było aktywne i które wydanie osiągnęło stan końcowy. Agent nie powinien przypisywać wyjątku środowiska uruchomieniowego najnowszemu commitowi, dopóki stan usługi nie potwierdzi, że ten commit został faktycznie wdrożony.

Unikaj ujawniania sekretów w logach

Nieudane połączenie często kusi, aby wypisać pełny adres URL. Zamiast tego rejestruj protokół, zamaskowanego hosta, nazwę bazy danych i kategorię błędu. W przypadku tokenów rejestruj wyłącznie bezpieczny fingerprint wygenerowany przed zapisaniem, jeśli organizacja ma odpowiednią politykę.

Przejrzyj artefakty nieudanej kompilacji przed udostępnieniem ich poza zespołem. Dane wyjściowe menedżera pakietów i Dockera mogą zawierać prywatne adresy URL repozytoriów, nazwy użytkowników registry lub argumenty komend, nawet jeśli Dockup prawidłowo maskuje przechowywane sekrety środowiskowe.

Dzięki temu logi kompilacji i środowiska uruchomieniowego są wystarczająco bezpieczne do wspólnego diagnozowania problemów.

Zachowaj minimalny pakiet dowodowy

Dla każdego nieudanego wydania zapisz JSON z wynikiem wdrożenia, log kompilacji, odpowiedni fragment logów środowiska uruchomieniowego, status usługi oraz wybrany identyfikator wdrożenia przywracającego działanie. Taki pakiet jest wystarczająco mały do rutynowego użycia i wystarczająco kompletny, aby drugi operator mógł kontynuować pracę bez ponownego wykonywania niepewnych mutacji.

Potwierdź poprawkę, a nie tylko nową kompilację

Po pomyślnym wdrożeniu poprawionej wersji ponów żądanie lub warunek uruchomieniowy, który powodował problem, i obserwuj logi środowiska uruchomieniowego pod kątem jego ponownego wystąpienia. Zamknij incydent dopiero wtedy, gdy pierwotny objaw nie występuje, bramka health przechodzi pomyślnie, a oczekiwane działanie produkcyjne zostało zaobserwowane.

Zamknij pętlę

Udokumentuj zweryfikowaną poprawkę.

Zacznij od weryfikowalnego wdrożenia

Wymuś niepowodzenie jednej testowej kompilacji, zapisz jej strumień NDJSON i kod wyjścia, a następnie sprawdź, czy runbook wybiera log kompilacji zamiast logu środowiska uruchomieniowego.

Zacznij bezpłatnie w app.dockup.ai. Plan Free kosztuje 0 USD miesięcznie, obejmuje środki początkowe w wysokości 10 USD oraz obsługuje jeden workspace, trzy bazy danych i trzy wdrożenia.

FAQ

Czym różnią się logi kompilacji Dockup od logów środowiska uruchomieniowego?

Logi kompilacji obejmują klonowanie, instalowanie zależności, kompilowanie i tworzenie obrazu. Logi środowiska uruchomieniowego obejmują uruchomiony kontener aplikacji lub pody.

Jak śledzić logi kompilacji Dockup na żywo?

Użyj dockup logs z --build i --follow albo -f. Z opcją --json komenda emituje batche NDJSON i kończy działanie po osiągnięciu przez wdrożenie stanu końcowego.

Dlaczego śledzenie kompilacji kończy się niezerowym kodem?

Zachowuje wynik wdrożenia. Nieudana kompilacja musi spowodować niepowodzenie wywołującej powłoki, zadania CI lub zadania agenta, zamiast wyglądać jak pomyślny strumień logów.

Co oznacza restarted:true w danych wyjściowych śledzenia środowiska uruchomieniowego?

Oznacza, że kontener został uruchomiony ponownie albo zachowany bufor został przewinięty, więc Dockup ponownie wysłał bieżący snapshot zamiast po cichu utracić wiersze.

Czy logi aplikacji powinny zawierać sekrety środowiskowe?

Nie. Dockup maskuje odczyty przechowywanej konfiguracji, ale nie może zabezpieczyć dowolnych sekretów wypisanych przez aplikację. Poświadczenia należy redagować na poziomie logowania aplikacji.