Een maandelijkse runbook voor een reproduceerbaar backlink-rapport

Waarom maandelijks en niet dagelijks

Onze grafiek vernieuwt zich ongeveer één keer per maand. Een dagelijkse taak levert dezelfde cijfers op.

Het vaker uitvoeren maakt een rapport niet actueler, het maakt het alleen duurder om uit te leggen. Een lezer die 30 identieke punten ziet, gaat ervan uit dat de pipeline kapot is.

Kies één dag per maand bewust, bij voorkeur een week nadat de vorige vernieuwing is ingezet. Schrijf de datum in de bestandsnaam, zodat de planning zelf gedocumenteerd is.

Kies eerst de kalender en laat het rapport daarop volgen. Een rapport dat herbouwt wanneer iemand het notebook opent, heeft helemaal geen duidelijke datum, en dat is moeilijk te verdedigen in een review.

Wat opslaan naast de cijfers

De helft van het rapport is metadata, dus sla het op naast de cijfers.

Schrijf de ophaaldatum, de actienaam, de parameters (per, sort, order) en het veld credits van de response in een klein sidecar-bestand naast elke snapshot. Over zes maanden, als een collega vraagt waarom oktober er anders uitziet dan september, beantwoordt dat bestand de vraag in tien seconden in plaats van een hele middag.

Voeg de git-commit van het script en de pakketversies van renv toe. Een rapport dat niet kan zeggen welke code en welke indexstatus een grafiek hebben geproduceerd, is een screenshot, geen analyse, hoe netjes de tibble er ook uitziet.

Een minimale targets-layout

Drie targets zijn genoeg als het plan klein blijft.

Eén target haalt op van de API en schrijft het gedateerde bestand, één leest het bestand en bouwt de tibble, één rendert het Quarto-document. Omdat alleen de eerste target het netwerk raakt, kun je de anderen zo vaak offline heruitvoeren als je wilt en verandert de grafiek niet per ongeluk.

Pakketversies vastzetten met renv, de sessie-informatie vastleggen in de footer van het rapport, en de drempeltafel van de bulk scoring pagina in de repository naast de code houden. Voor de financiële kant vertelt de budgetpagina je wat een maand zou moeten kosten.

Als er iets misgaat, lees dan eerst de code. HTTP 401 betekent dat de sleutel fout of ontbreekt. HTTP 402 betekent dat de credits op zijn. Alles anders is het waard om volledig te loggen. De teardown behandelt die fasen, en het join-voorbeeld is een goede eerste taak om te plannen.

Leren dat een run fout ging voordat een collega dat doet

Een reproduceerbaar backlink-rapport dat stil faalt, misleidt meer dan een rapport dat nooit is uitgevoerd. De echte vraag is niet of de taak kan falen, maar hoe snel iemand er iets van merkt.

Laat de taak luid falen

Een geplande taak stopt met een niet-nul statuscode wanneer een call HTTP 401 of 402 retourneert, en de planner markeert de run als mislukt. Dat is de goedkoopste alert die je hebt, en het vereist geen extra service.

Gedeeltelijke ophalingen zijn het gevaarlijke geval. Als het script zijn bestand schrijft na twintig van de dertig chunks, bestaat het bestand en ziet het er goed uit. Schrijf naar een tijdelijke naam en hernoem het alleen bij succes.

Stuur één bericht per fout

Kies één kanaal voor fouten, zoals een e-mail naar de rapporteigenaar of een bericht in de teamchat. Twee kanalen betekenen twee plekken om naar te kijken, en een grotere kans dat niemand naar beide kijkt.

Het bericht moet de target noemen die is mislukt, de statuscode en de tijd. Alles anders hoort in de log.

Controleer of de output aannemelijk is

Een run kan slagen en toch fout zijn. Vergelijk het aantal rijen met dat van vorige maand, en markeer een daling die verder gaat dan een drempel die je van tevoren hebt gekozen.

De check kan zo simpel zijn als een verwacht bereik. Het doel is om een halflege snapshot op te merken voordat een grafiek een klant bereikt.

Noem één eigenaar voor het rapport

Noem één eigenaar voor het rapport. Een alert zonder eigenaar wordt door iedereen gelezen en door niemand opgevolgd.

De eigenaar hoeft de taak niet op te lossen. De eigenaar moet beslissen of een laat rapport acceptabel is, en dat in het rapport zelf zeggen.

Schrijf de naam van de eigenaar in de runbook-header, en update deze wanneer de eigenaar verandert. Een runbook met een voormalige eigenaar is een stille gevarenbron.

De dag kiezen en de eerste taak handmatig uitvoeren

Timing en de eerste run bepalen of de planning standhoudt. Beide zijn in de eerste maand makkelijk fout te doen, en beide zijn goedkoop om goed te doen.

Twee beslissingen, één keer opgeschreven, besparen de meeste discussies later. De eerste is de dag. De tweede is waar de timer draait. Beide behoren in de runbook, niet in iemands hoofd.

Kies één dag en schrijf het op

Een vaste dag in de maand, zoals de eerste werkdag nadat de vernieuwing is ingezet, is makkelijker uit te leggen dan een gok aan het begin van de maand.

Zet de dag in het schedule-bestand zelf, zodat de timing onderdeel is van de code en geen geheugen in iemands agenda.

Voer de eerste taak handmatig uit

De eerste geplande run moet een handmatige zijn. Voer het script zelf uit, lees de log, vergelijk het bestand met het vorige, en geef de timer pas over.

De eerste run test ook de secret store. Een sleutel die op jouw machine werkt, maar ontbreekt in CI, is een veelvoorkomende reden voor de eerste geplande fout.

Houd het sidecar eerlijk

Het sidecar-bestand registreert wat de run heeft gedaan. Als een persoon het met de hand schrijft, wijkt het af van de run. Laat het script het schrijven, en laat mensen het alleen lezen.

Een sidecar waar het script nooit bij heeft gepakt, is een notitie, geen record, en het rapport moet het record citeren.

Vergelijk het sidecar met het bestand één keer per maand. Als de cijfers in de twee niet overeenkomen, is de run op een manier mislukt die het script niet heeft opgemerkt.

Waar de timer leeft

Een gehoste runner en een lokale cron-entry falen op verschillende manieren. Een gehoste runner kan worden gepauzeerd door zijn eigen instellingen, en een lokale cron-entry stopt wanneer de machine in slaapstand staat. Controleer welke je hebt gekozen, en test de timer één keer met een korte planning voordat de echte start.

Wat je ook kiest, schrijf de timer op in de repository naast het script, zodat de volgende persoon weet waar de taak leeft.