Log pętli odpowiada, co robił agent. Log grafu musi odpowiedzieć, dlaczego zadziałał ten węzeł, a nie inny — i to jest zapis, którego domyślnie nikt nie prowadzi.
W pętli wiadomo, co się wydarzyło, bo istniała jedna ścieżka: obrót po obrocie, wywołanie po wywołaniu. Log pętliopisuje sekwencję, którą i tak dałoby się odtworzyć z kolejności zdarzeń.
W grafie ścieżki nie ma, dopóki się nie wydarzy. Powstała w czasie działania, na podstawie tego, co znaleziono po drodze — i jeśli nie zapisałeś, dlaczego wybrano tę krawędź, nie odtworzysz tego później. Zapis wykonań mówi, którędy poszło. Nie mówi dlaczego.
Ta różnica jest całym tematem tego artykułu.
Trzy pytania, na które log grafu musi umieć odpowiedzieć
Którędy poszło. Kolejność węzłów, czasy, wyniki. To jest część, którą narzędzia zapisują domyślnie i która wystarcza, dopóki nic się nie zepsuje.
Dlaczego tak, a nie inaczej. Router wybrał jedną z trzech krawędzi. Na jakiej podstawie? Jakie miał wejście? Jakie alternatywy odrzucił? Bez tego debugowanie polega na zgadywaniu.
Co wiedział węzeł w chwili decyzji. Nie cały stan grafu — wycinek, który dostał. Bo jeśli węzeł zdecydował źle, pierwsze pytanie brzmi, czy zdecydował źle na podstawie tego, co miał, czy dostał niewłaściwe wejście.
Trzecie pytanie jest najczęściej pomijane i najczęściej rozstrzygające. Odpowiedź na nie odróżnia dwie zupełnie różne awarie, które w logu wykonań wyglądają identycznie.
Rozstrzygnięcie krawędzi jako zdarzenie
Podstawowa zmiana wobec pętli: przejście między węzłami jest zdarzeniem, które trzeba zapisać osobno, a nie efektem ubocznym wykonania.
Minimalny zapis rozstrzygnięcia zawiera pięć rzeczy:
- z którego węzła — punkt wyjścia,
- jakie krawędzie były dozwolone — nie tylko wybrana, ale zbiór, spośród którego wybierano,
- która została wybrana,
- na jakiej podstawie — wartość warunku przy routerze deterministycznym, uzasadnienie przy routerze modelowym,
- kiedy.
Druga pozycja jest tą, którą pomija się najczęściej i której najbardziej brakuje przy debugowaniu. Zapis „poszliśmy do C” nie mówi nic. Zapis „mieliśmy B i C, poszliśmy do C” mówi, że B było rozważane. Zapis „mieliśmy tylko C” mówi coś zupełnie innego — że problem jest w konfiguracji krawędzi, nie w decyzji.
Co zapisywać przy węźle
Trzy warstwy, o różnym koszcie i różnej trwałości.
Wejście i wyjście. Wycinek stanu, który węzeł dostał, i to, co zwrócił. Zawsze, dla każdego węzła. Bez tego nie odtworzysz niczego.
Przebieg wewnętrzny. Jeśli węzeł jest agentem, ma własną pętlę z własnymi obrotami. To jest najbardziej objętościowa część logu i jednocześnie ta, której potrzebujesz najrzadziej — tylko wtedy, gdy problem jest wewnątrz węzła, a nie w jego wejściu.
Metryki. Czas, tokeny, koszt, liczba obrotów wewnętrznych. Tanie w zapisie, nieocenione przy szukaniu, który węzeł zjada budżet.
Praktyczna zasada retencji: wejścia, wyjścia i rozstrzygnięcia krawędzi trzymaj długo, bo z nich odtworzysz przebieg. Przebiegi wewnętrzne trzymaj krótko i tylko dla świeżych zadań — objętość rośnie szybciej, niż się spodziewasz, a przydają się w pierwszych dniach po awarii, nie po miesiącach.
Identyfikator, który spina wszystko
Jedna rzecz techniczna, bez której reszta jest bezużyteczna: każdy wpis musi nieść identyfikator zadania, wspólny dla całego przebiegu.
Brzmi trywialnie i bywa pomijane, bo przy jednej pętli identyfikator wynikał z kontekstu — wszystko, co działo się w tym procesie, dotyczyło tego zadania. W grafie węzły uruchamiają się osobno, czasem na różnych maszynach, czasem w odstępie godzin. Bez wspólnego identyfikatora masz zbiór niepowiązanych logów.
Warto dodać jeszcze dwa: identyfikator węzła i numer próby. Ten ostatni ratuje przy ponowieniach — bez niego trzy podejścia do tego samego węzła wyglądają w logu jak trzy różne wykonania i nie wiadomo, które było ostatnie.
Awaria zapisana jako stan
Wracam do zasady z artykułu o awariach, bo w kontekście logowania ma dodatkowe znaczenie.
Węzeł, który zawiódł, musi zostawić wpis mówiący, że zawiódł, i dlaczego. Brak wpisu jest nieodróżnialny od trzech innych sytuacji: węzeł nie wystartował, wystartował i został zabity, albo wykonał się i log nie doszedł.
W logu jednej pętli te przypadki dawało się rozróżnić po kontekście. W grafie, gdzie brak zdarzenia jest normalną sytuacją — bo węzeł mógł po prostu nie być na wybranej ścieżce — nie da się.
Zapisuj też to, co się nie wydarzyło, jeśli mogło. Krawędź nierozważona, węzeł pominięty, złączenie, które czeka. Trzy takie wpisy zajmują tyle co nic, a odróżniają „graf nie poszedł tą drogą” od „graf stoi”.
Test odtwarzalności
Sprawdzian, który rozstrzyga, czy twój log jest wystarczający, i który zajmuje kwadrans.
Weź zakończony przebieg sprzed tygodnia i odtwórz go na kartce, korzystając wyłącznie z logu. Bez zaglądania do konfiguracji, bez pytania kogokolwiek.
Trzy pytania, na które musisz umieć odpowiedzieć:
Które węzły się wykonały i w jakiej kolejności? Jeśli nie umiesz, brakuje ci podstaw.
Dlaczego po węźle A poszło do C, a nie do B? Jeśli nie umiesz, nie zapisujesz rozstrzygnięć krawędzi — i przy pierwszej niewyjaśnionej trasie będziesz zgadywać.
Co dokładnie widział węzeł C, kiedy podejmował swoją decyzję? Jeśli nie umiesz, nie odróżnisz błędu węzła od błędu jego wejścia.
Trzecie pytanie oblewa najwięcej wdrożeń, bo wymaga zapisywania wycinka stanu na wejściu, a nie tylko wyniku na wyjściu.
Ile to kosztuje
Uczciwie: log grafu jest wielokrotnie objętościowszy niż log pętli, bo węzłów jest kilka, a rozstrzygnięcia dochodzą osobno.
Trzy sposoby, żeby nie utonąć:
Poziomy szczegółowości per węzeł. Węzeł krytyczny loguje wszystko, węzeł pomocniczy tylko wejście, wyjście i metryki.
Pełny zapis warunkowo. Domyślnie skrót, pełny przebieg wewnętrzny tylko dla zadań, które zakończyły się błędem albo przekroczyły próg kosztu.
Referencje zamiast treści. W logu identyfikator dokumentu, treść w magazynie. Ta sama zasada co przy stanie między węzłami — i z tego samego powodu.
Co dalej
Graf jest opisany od środka: z czego się składa, jak decyduje, gdzie trzyma stan, co robi przy awarii, czego mu nie wolno i jak to wszystko zapisać.
Zostaje pytanie, od którego cały tor się zaczął, tylko zadane z drugiej strony. Nie „kiedy graf ma sens”, ale ile realnie kosztuje — i w jakich sytuacjach ta cena jest wyższa niż korzyść.
O tym jest artykuł dziesiąty: Kiedy graf się nie opłaca.
Stan na sierpień 2026. Zakres domyślnego logowania różni się znacznie między narzędziami orkiestrującymi — część zapisuje rozstrzygnięcia krawędzi, część wyłącznie wykonania. Warto sprawdzić, zanim uznasz, że masz komplet.
