En månadsbok för en reproducerbar backlink-rapport

Varför månatligt och inte dagligt

Vårt diagram uppdateras ungefär en gång i månaden. Ett dagligt jobb returnerar samma siffror.

Att köra det oftare gör inte en rapport mer aktuell, det gör den bara dyrare att förklara. En läsare som ser 30 identiska punkter kommer att anta att pipeline:n är trasig.

Välj en dag varje månad medvetet, helst en vecka efter att den föregående uppdateringen har lagt sig. Skriv in datumet i filnamnet, så att schemat i sig dokumenteras.

Välj kalendern först och låt rapporten följa den. En rapport som byggs om varje gång någon öppnar anteckningsboken har inget tydligt datum alls, och det är svårt att försvara vid en granskning.

Vad att lagra utöver siffrorna

En halv del av rapporten är metadata, så lagra det tillsammans med siffrorna.

Skriv hämtningsdatumet, åtgärdens namn, parametrarna (per, sort, order) och fältet för krediter från svaret i en liten sidecar-fil bredvid varje ögonblicksbild. Sex månader senare, när en kollega frågar varför oktober ser annorlunda ut jämfört med september, svarar den filen på tio sekunder istället för en eftermiddag.

Lägg till git-commit:t för skriptet och paketversionerna från renv. En rapport som inte kan säga vilken kod och vilket indextillstånd som producerade ett diagram är en skärmbild, inte en analys, oavsett hur prydlig tibble:n ser ut.

En minimal targets-layout

Tre targets räcker när planen håller sig liten.

En target hämtar från API:et och skriver den daterade filen, en läser filen och bygger tibble:n, en renderar Quarto-dokumentet. Eftersom bara den första targeten berör nätverket kan du köra om de andra offline så ofta du vill och diagrammet ändras inte av misstag.

Fäst paketversioner med renv, registrera sessioninformationen i rapportens fot och behåll tröskeltabellen från sidan för massbetygsättning i arkivet bredvid koden. För pengasidan berättar budgetsidan vad en månad bör kosta.

När något misslyckas, läs koden först. HTTP 401 betyder att nyckeln är felaktig eller saknas. HTTP 402 betyder att krediterna tog slut. Allt annat är värt att logga fullt ut. Nedmonteringen täcker dessa steg, och join-exemplet är ett bra första jobb att schemalägga.

Att lära sig att ett körning gick fel innan en kollega gör det

En reproducerbar backlink-rapport som misslyckas tyst vilseleder mer än en som aldrig kördes. Den verkliga frågan är inte om jobbet kan misslyckas, utan hur snabbt någon hör om det.

Låt jobbet misslyckas högt

Ett schemalagt jobb avslutas med en icke-noll-status när ett anrop returnerar HTTP 401 eller 402, och schemaläggaren markerar körningen som misslyckad. Det är det billigaste larmet du har, och det kräver ingen extra tjänst.

Delvisa hämtningar är det farliga fallet. Om skriptet skriver sin fil efter tjugo av trettio bitar finns filen och ser bra ut. Skriv till ett tillfälligt namn och byt namn på det endast vid framgång.

Skicka ett meddelande per misslyckande

Välj en kanal för misslyckanden, till exempel ett e-postmeddelande till rapportägaren eller ett meddelande i teamchatten. Två kanaler betyder två ställen att titta på, och en högre chans att ingen tittar på någon av dem.

Meddelandet bör namnge den target som misslyckades, statuskoden och tiden. Allt annat hör hemma i loggen.

Kontrollera att utdata är rimlig

En körning kan lyckas och ändå vara fel. Jämför radantalet med förra månadens, och flagga ett fall bortom en tröskel du valt i förväg.

Kontrollen kan vara så enkel som ett förväntat intervall. Målet är att märka en halvtom ögonblicksbild innan ett diagram når en kund.

Namnge en ägare för rapporten

Namnge en ägare för rapporten. Ett larm utan ägare läses av alla och ageras på av ingen.

Ägaren behöver inte fixa jobbet. Ägaren måste avgöra om en sen rapport är acceptabel, och säga det i rapporten i sig.

Skriv ägarens namn i körbokens rubrik, och uppdatera det när ägaren byts. En körbok med en tidigare ägare är en tyst fara.

Att välja dagen och köra det första jobbet för hand

Tidpunkt och den första körningen avgör om schemat håller. Båda är lätta att få fel i den första månaden, och båda är billiga att få rätt.

Två beslut, skrivna en gång, sparar mest argument senare. Det första är dagen. Det andra är var timern körs. Båda hör hemma i körboken, inte i någons huvud.

Välj en dag och skriv ner den

En fast dag i månaden, som den första arbetsdagen efter att uppdateringen har lagt sig, är lättare att förklara än en gissning i början av månaden.

Sätt in dagen i schemafilen i sig, så att tidpunkten är en del av koden och inte ett minne i någons kalender.

Kör det första jobbet för hand

Den första schemalagda körningen bör vara en manuell. Kör skriptet själv, läs loggen, jämför filen med den föregående, och överlåt sedan timern.

Den första körningen testar också hemlighetslagret. En nyckel som fungerar på din maskin men saknas i CI är en vanlig anledning till det första schemalagda misslyckandet.

Håll sidecar-ärlig

Sidecar-filen registrerar vad körningen gjorde. Om en person skriver den för hand, drifar den från körningen. Låt skriptet skriva den, och låt människor bara läsa den.

En sidecar som skriptet aldrig rörde vid är en anteckning, inte en registrering, och rapporten bör citera registreringen.

Jämför sidecar med filen en gång i månaden. Om siffrorna i de två inte stämmer överens, misslyckades körningen på ett sätt som skriptet inte märkte.

Var timern bor

En hostad runner och en lokal cron-post misslyckas på olika sätt. En hostad runner kan pausas av sina egna inställningar, och en lokal cron-post stannar när maskinen är i viloläge. Kontrollera vilken du valde, och testa timern en gång med en kort schema innan den riktiga.

Vilket du än väljer, skriv ner timern i arkivet bredvid skriptet, så att nästa person vet var jobbet bor.