Ein monatliches Runbook für einen reproduzierbaren Backlink-Bericht

Warum monatlich und nicht täglich?

Unser Graph aktualisiert sich etwa einmal im Monat. Ein täglicher Job liefert dieselben Zahlen.

Häufigeres Ausführen macht einen Bericht nicht aktueller, sondern nur teurer zu erklären. Ein Leser, der 30 identische Punkte sieht, geht davon aus, dass die Pipeline defekt ist.

Wählen Sie einen Tag im Monat bewusst aus, idealerweise eine Woche nach dem sich der vorherige Refresh settled. Schreiben Sie das Datum in den Dateinamen, damit der Zeitplan selbst dokumentiert ist.

Wählen Sie zuerst den Kalender und lassen Sie den Bericht ihm folgen. Ein Bericht, der jedes Mal neu erstellt wird, wenn jemand das Notebook öffnet, hat kein klares Datum, was in einer Prüfung schwer zu vertreten ist.

Was neben den Zahlen gespeichert werden soll

Die Hälfte des Berichts besteht aus Metadaten, also speichern Sie diese zusammen mit den Zahlen.

Schreiben Sie das Abrufdatum, den Aktion-Namen, die Parameter (per, sort, order) und das Credits-Feld der Antwort in eine kleine Sidecar-Datei neben jedem Snapshot. Sechs Monate später, wenn ein Kollege fragt, warum Oktober anders aussieht als September, beantwortet diese Datei die Frage in zehn Sekunden statt einen ganzen Nachmittag.

Fügen Sie den Git-Commit des Skripts und die Paketversionen aus renv hinzu. Ein Bericht, der nicht sagen kann, welcher Code und welcher Index-Stand ein Diagramm erzeugt hat, ist ein Screenshot, keine Analyse, egal wie ordentlich der tibble aussieht.

Ein minimales targets-Layout

Drei Targets reichen aus, wenn der Plan klein bleibt.

Ein Target ruft von der API ab und schreibt die datierte Datei, eines liest die Datei und erstellt den tibble, eines rendert das Quarto-Dokument. Da nur das erste Target das Netzwerk berührt, können Sie die anderen so oft offline neu ausführen, wie Sie möchten, und das Diagramm ändert sich nicht versehentlich.

Sperren Sie Paketversionen mit renv, notieren Sie die Session-Info in der Fußzeile des Berichts und halten Sie die Threshold-Tabelle von der Bulk-Scoring-Seite im Repository neben dem Code. Für die Kosten-Seite sagt Ihnen die Budget-Seite, was ein Monat kosten sollte.

Wenn etwas fehlschlägt, lesen Sie zuerst den Code. HTTP 401 bedeutet, dass der Schlüssel falsch oder fehlend ist. HTTP 402 bedeutet, dass die Credits aufgebraucht sind. Alles andere lohnt sich, vollständig zu protokollieren. Der Teardown behandelt diese Stufen, und das Join-Beispiel ist ein guter erster Job zum Planen.

Zu lernen, dass ein Lauf falsch gelaufen ist, bevor es ein Kollege tut

Ein reproduzierbarer Backlink-Bericht, der still fehlschlägt, irreführt mehr als einer, der nie ausgeführt wurde. Die eigentliche Frage ist nicht, ob der Job fehlschlagen kann, sondern wie schnell jemand davon erfährt.

Den Job laut fehlschlagen lassen

Ein geplanter Job endet mit einem Nicht-Null-Status, wenn eine Antwort HTTP 401 oder 402 zurückgibt, und der Scheduler markiert den Lauf als fehlgeschlagen. Das ist die günstigste Warnung, die Sie haben, und sie benötigt keinen zusätzlichen Dienst.

Partielle Abrufe sind der gefährliche Fall. Wenn das Skript seine Datei schreibt, nachdem zwanzig von dreißig Chunks abgeschlossen sind, existiert die Datei und sieht in Ordnung aus. Schreiben Sie in einen temporären Namen und benennen Sie ihn nur bei Erfolg um.

Eine Nachricht pro Fehler senden

Wählen Sie einen Kanal für Fehler, z. B. eine E-Mail an den Berichtseigentümer oder eine Nachricht im Team-Chat. Zwei Kanäle bedeuten zwei Orte zum Suchen und eine höhere Wahrscheinlichkeit, dass niemand an beiden schaut.

Die Nachricht sollte das Target benennen, das fehlgeschlagen ist, den Statuscode und die Zeit. Alles andere gehört ins Log.

Prüfen, ob die Ausgabe plausibel ist

Ein Lauf kann erfolgreich sein und dennoch falsch. Vergleichen Sie die Zeilenanzahl mit der des letzten Monats und markieren Sie einen Rückgang jenseits eines im Voraus gewählten Thresholds.

Die Prüfung kann so einfach sein wie eine erwartete Spanne. Das Ziel ist es, einen halb leeren Snapshot zu bemerken, bevor ein Diagramm einen Kunden erreicht.

Einen Eigentümer für den Bericht benennen

Benennen Sie einen Eigentümer für den Bericht. Eine Warnung ohne Eigentümer wird von allen gelesen, aber von niemandem bearbeitet.

Der Eigentümer muss den Job nicht beheben. Der Eigentümer muss entscheiden, ob ein später Bericht akzeptabel ist, und dies im Bericht selbst mitteilen.

Schreiben Sie den Namen des Eigentümers in den Runbook-Header und aktualisieren Sie ihn, wenn sich der Eigentümer ändert. Ein Runbook mit einem ehemaligen Eigentümer ist eine stille Gefahr.

Den Tag wählen und den ersten Job manuell ausführen

Timing und der erste Lauf entscheiden darüber, ob der Zeitplan hält. Beide sind im ersten Monat leicht falsch zu machen und leicht richtig zu machen.

Zwei Entscheidungen, einmal aufgeschrieben, sparen die meisten Argumente später. Die erste ist der Tag. Die zweite ist, wo der Timer läuft. Beide gehören ins Runbook, nicht in den Kopf eines Menschen.

Wählen Sie einen Tag und schreiben Sie ihn auf

Ein fester Tag im Monat, wie der erste Arbeitstag nach dem sich der Refresh settled, ist leichter zu erklären als eine Vermutung Anfang des Monats.

Legen Sie den Tag in die Schedule-Datei selbst, damit das Timing Teil des Codes und kein Gedächtnis im Kalender eines Menschen ist.

Führen Sie den ersten Job manuell aus

Der erste geplante Lauf sollte ein manueller sein. Führen Sie das Skript selbst aus, lesen Sie das Log, vergleichen Sie die Datei mit der vorherigen und übergeben Sie erst dann den Timer.

Der erste Lauf testet auch den Secret-Store. Ein Schlüssel, der auf Ihrer Maschine funktioniert, aber in CI fehlt, ist ein häufiger Grund für den ersten geplanten Fehler.

Die Sidecar ehrlich halten

Die Sidecar-Datei zeichnet auf, was der Lauf getan hat. Wenn eine Person sie von Hand schreibt, weicht sie vom Lauf ab. Lassen Sie das Skript sie schreiben und die Menschen nur lesen.

Eine Sidecar, die das Skript nie berührt hat, ist eine Notiz, kein Rekord, und der Bericht sollte den Rekord zitieren.

Vergleichen Sie die Sidecar einmal im Monat mit der Datei. Wenn die Zahlen in beiden nicht übereinstimmen, ist der Lauf auf eine Weise fehlgeschlagen, die das Skript nicht bemerkt hat.

Wo der Timer lebt

Ein gehosteter Runner und ein lokaler cron-Eintrag schlagen auf unterschiedliche Weise fehl. Ein gehosteter Runner kann durch seine eigenen Einstellungen pausiert werden, und ein lokaler cron-Eintrag stoppt, wenn die Maschine im Ruhezustand ist. Prüfen Sie, was Sie gewählt haben, und testen Sie den Timer einmal mit einem kurzen Zeitplan vor dem echten.

Egal was Sie wählen, schreiben Sie den Timer im Repository neben das Skript, damit die nächste Person weiß, wo der Job lebt.