Miesięczny scenariusz wykonania dla raportu z backlinków

Dlaczego raz w miesiącu, a nie codziennie

Nasz wykres odświeża się mniej więcej raz w miesiącu. Codzienne zadanie zwraca te same liczby.

Uruchamianie częściej nie czyni raportu bardziej aktualnym, tylko droższym w wyjaśnieniu. Czytnik, który zobaczy 30 identycznych punktów, założy, że pipeline jest uszkodzony.

Wybierz jeden dzień w miesiącu świadomie, najlepiej tydzień po ustabilizowaniu się poprzedniego odświeżenia. Zapisz datę w nazwie pliku, aby sam harmonogram był udokumentowany.

Najpierw wybierz kalendarz, a raport niech mu podąża. Raport, który odtwarza się za każdym razem, gdy ktoś otworzy notatnik, nie ma jasnej daty, a to trudno bronić podczas przeglądu.

Co przechowywać oprócz liczb

Połowa raportu to metadane, więc przechowuj je obok liczb.

Zapisz datę pobrania, nazwę akcji, parametry (per, sort, order) oraz pole kredytów z odpowiedzi do małego pliku sidecar obok każdej migawki. Za sześć miesięcy, gdy kolega zapyta, dlaczego październik wygląda inaczej niż wrzesień, ten plik odpowie w dziesięć sekund, a nie po południu.

Dodaj commit git skryptu oraz wersje pakietów z renv. Raport, który nie może powiedzieć, który kod i który stan indeksu wygenerował wykres, to screenshot, a nie analiza, niezależnie od tego, jak schludnie wygląda tibble.

Minimalny układ targets

Trzy cele wystarczają, gdy plan jest mały.

Jeden cel pobiera dane z API i zapisuje datowany plik, drugi czyta plik i buduje tibble, trzeci renderuje dokument Quarto. Ponieważ tylko pierwszy cel dotyka sieci, możesz wielokrotnie uruchamiać pozostałe offline, a wykres nie zmieni się przypadkowo.

Zablokuj wersje pakietów za pomocą renv, zapisuj informacje o sesji w stopce raportu i utrzymuj tabelę progową ze strony masowego oceniania w repozytorium obok kodu. Jeśli chodzi o koszty, strona z cenami mówi, ile powinien kosztować miesiąc.

Kiedy coś się nie powiedzie, najpierw przeczytaj kod. HTTP 401 oznacza, że klucz jest błędny lub brakuje go. HTTP 402 oznacza wyczerpanie kredytów. Wszystko inne warto zalogować w całości. Analiza obejmuje te etapy, a przykład joina to dobry pierwszy cel do zaplanowania.

Dowiedzenie się, że uruchomienie poszło nie tak, zanim zrobi to kolega

Odtwarzalny raport z backlinków, który cicho się nie powiedzie, wprowadza w błąd bardziej niż taki, który w ogóle nie został uruchomiony. Rzeczywiste pytanie nie brzmi, czy zadanie może się nie powieść, ale jak szybko ktoś o tym się dowie.

Zakończ zadanie głośnym błędem

Zaplanowane zadanie kończy się statusem innym niż zero, gdy wywołanie zwraca HTTP 401 lub 402, a harmonogram oznacza uruchomienie jako nieudane. To najtańsze powiadomienie, którego nie wymaga dodatkowa usługa.

Częściowe pobrania to niebezpieczny przypadek. Jeśli skrypt zapisze plik po dwudziestu z trzydziestu chunków, plik istnieje i wygląda na poprawny. Zapisuj do tymczasowej nazwy i zmień ją tylko po sukcesie.

Wysyłaj jedną wiadomość na każde niepowodzenie

Wybierz jeden kanał dla powiadomień o błędach, np. e-mail do właściciela raportu lub wiadomość na czacie zespołowym. Dwa kanały oznaczają dwa miejsca do sprawdzenia i większe prawdopodobieństwo, że nikt nie sprawdzi żadnego.

Wiadomość powinna zawierać nazwę celu, który się nie powiódł, kod statusu i godzinę. Wszystko inne należy w logu.

Sprawdź, czy wynik jest prawdopodobny

Uruchomienie może się udać, a wynik i tak być błędny. Porównaj liczbę wierszy z poprzednim miesiącem i oznacz spadek przekraczający wcześniej przyjęty próg.

Sprawdzenie może być tak proste jak oczekiwany zakres. Celem jest zauważenie półpuste migawki zanim wykres trafi do klienta.

Wyznacz jednego właściciela raportu

Wyznacz jednego właściciela raportu. Powiadomienie bez właściciela jest czytane przez wszystkich, a przez nikogo realizowane.

Właściciel nie musi naprawiać zadania. Właściciel musi zdecydować, czy spóźniony raport jest akceptowalny, i napisać to w samym raporcie.

Zapisz imię i nazwisko właściciela w nagłówku scenariusza wykonania i aktualizuj go przy zmianie właściciela. Scenariusz z byłym właścicielem to cicha pułapka.

Wybór dnia i ręczne uruchomienie pierwszego zadania

Harmonogram i pierwsze uruchomienie decydują o tym, czy harmonogram się utrzyma. Oba są łatwe do popełnienia błędu w pierwszym miesiącu, a oba są tanie do poprawienia.

Dwie decyzje zapisane raz oszczędzą najwięcej sporów później. Pierwsza to dzień. Druga to miejsce, gdzie działa timer. Obie należą do scenariusza wykonania, a nie do czyjejś głowy.

Wybierz jeden dzień i zapisz go

Stały dzień w miesiącu, np. pierwszy dzień roboczy po ustabilizowaniu się odświeżenia, jest łatwiejszy do wyjaśnienia niż zgadywanie na początku miesiąca.

Umieść dzień w pliku harmonogramu, aby czas był częścią kodu, a nie pamięcią w kalendarzu kogoś.

Uruchom pierwsze zadanie ręcznie

Pierwsze zaplanowane uruchomienie powinno być ręczne. Uruchom skrypt sam, przeczytaj log, porównaj plik z poprzednim, a dopiero potem przekaż timer.

Pierwsze uruchomienie testuje też sklep sekretów. Klucz, który działa na Twojej maszynie, ale brakuje go w CI, to częsty powód pierwszego niepowodzenia zaplanowanego.

Utrzymuj sidecar w zgodzie

Plik sidecar zapisuje, co zrobiło uruchomienie. Jeśli osoba zapisuje go ręcznie, odbiega od uruchomienia. Niech skrypt go zapisze, a ludzie tylko go czytają.

Sidecar, którego skrypt nie dotknął, to notatka, a nie rekord, a raport powinien cytować rekord.

Porównuj sidecar z plikiem raz w miesiącu. Jeśli liczby w obu się nie zgadzają, uruchomienie nie powiodło się w sposób, którego skrypt nie zauważył.

Gdzie mieszka timer

Zdalny runner i lokalny wpis cron kończą się różnymi błędami. Zdalny runner może zostać wstrzymany przez własne ustawienia, a lokalny wpis cron zatrzymuje się, gdy komputer jest uśpiony. Sprawdź, co wybrałeś, i przetestuj timer raz krótkim harmonogramem przed właściwym.

Bez względu na wybór, zapisz timer w repozytorium obok skryptu, aby następna osoba wiedziała, gdzie mieszka zadanie.