Runbook bulanan untuk laporan backlink yang dapat direproduksi

Mengapa bulanan dan bukan harian

Graf kami diperbarui kira-kira sekali sebulan. Pekerjaan harian mengembalikan angka yang sama.

Menjalankannya lebih sering tidak membuat laporan lebih terkini, hanya membuatnya lebih mahal untuk dijelaskan. Pembaca yang melihat 30 titik identik akan mengasumsikan pipa bermasalah.

Pilih satu hari setiap bulan secara sengaja, idealnya seminggu setelah pembaruan sebelumnya stabil. Tulis tanggalnya ke dalam nama file, sehingga jadwalnya sendiri terdokumentasi.

Pilih kalender terlebih dahulu dan biarkan laporan mengikutinya. Laporan yang dibangun ulang setiap kali seseorang membuka notebook tidak memiliki tanggal yang jelas sama sekali, dan itu sulit dipertahankan saat tinjauan.

Apa yang harus disimpan selain angka

Setengah dari laporan adalah metadata, jadi simpanlah bersama angka-angkanya.

Tulis tanggal penarikan, nama tindakan, parameter (per, sort, order) dan bidang kredit dari respons ke dalam file sidecar kecil di samping setiap snapshot. Enam bulan kemudian, ketika seorang rekan bertanya mengapa Oktober terlihat berbeda dari September, file itu menjawab dalam sepuluh detik, bukan sepanjang sore.

Tambahkan commit git dari skrip dan versi paket dari renv. Laporan yang tidak dapat mengatakan kode dan keadaan indeks mana yang menghasilkan grafik hanyalah screenshot, bukan analisis, tidak peduli seberapa rapi tibble-nya.

Tata letak targets minimal

Tiga target sudah cukup ketika rencananya tetap kecil.

Satu target menarik dari API dan menulis file bertanggal, satu membaca file dan membangun tibble, satu merender dokumen Quarto. Karena hanya target pertama yang menyentuh jaringan, Anda dapat menjalankan ulang yang lainnya secara offline sebanyak yang Anda inginkan dan grafik tidak berubah secara tidak sengaja.

Kunci versi paket dengan renv, catat info sesi di footer laporan, dan pertahankan tabel ambang batas dari halaman penilaian massal di repositori di sebelah kode. Untuk sisi anggaran, halaman anggaran memberi tahu Anda berapa biaya yang seharusnya untuk satu bulan.

Ketika sesuatu gagal, baca kode terlebih dahulu. HTTP 401 berarti kunci salah atau hilang. HTTP 402 berarti kredit habis. Apa pun yang lain layak dicatat secara lengkap. Runtutan mencakup tahap-tahap tersebut, dan contoh penggabungan adalah pekerjaan pertama yang baik untuk dijadwalkan.

Belajar bahwa sebuah run berjalan salah sebelum rekan Anda melakukannya

Laporan backlink yang dapat direproduksi yang gagal secara diam-diam menyesatkan lebih daripada yang tidak pernah berjalan. Pertanyaan sebenarnya bukan apakah pekerjaan dapat gagal, tetapi seberapa cepat seseorang mendengarnya.

Buat pekerjaan gagal dengan keras

Pekerjaan terjadwal keluar dengan status non-nol ketika panggilan mengembalikan HTTP 401 atau 402, dan scheduler menandai run sebagai gagal. Itu adalah peringatan termurah yang Anda miliki, dan tidak memerlukan layanan tambahan.

Penarikan parsial adalah kasus berbahaya. Jika skrip menulis file setelah dua puluh dari tiga puluh chunk, file ada dan terlihat baik. Tulis ke nama sementara dan ganti nama hanya jika berhasil.

Kirim satu pesan per kegagalan

Pilih satu saluran untuk kegagalan, seperti email ke pemilik laporan atau pesan di obrolan tim. Dua saluran berarti dua tempat untuk dilihat, dan peluang lebih tinggi bahwa tidak ada yang melihat keduanya.

Pesan harus menyebutkan target yang gagal, kode status, dan waktu. Yang lain masuk ke dalam log.

Periksa apakah outputnya masuk akal

Sebuah run dapat berhasil dan masih salah. Bandingkan jumlah baris dengan bulan lalu, dan tandai penurunan di luar ambang batas yang Anda pilih sebelumnya.

Pemeriksaan bisa sesederjang kisaran yang diharapkan. Tujuannya adalah untuk menyadari snapshot setengah kosong sebelum grafik mencapai klien.

Tentukan satu pemilik untuk laporan

Tentukan satu pemilik untuk laporan. Peringatan tanpa pemilik dibaca oleh semua orang dan tidak ditindaklanjuti oleh siapa pun.

Pemilik tidak harus memperbaiki pekerjaan. Pemilik harus memutuskan apakah laporan yang terlambat dapat diterima, dan mengatakannya dalam laporan itu sendiri.

Tulis nama pemilik ke dalam header runbook, dan perbarui ketika pemilik berubah. Runbook dengan pemilik lama adalah bahaya yang diam-diam.

Memilih hari dan menjalankan pekerjaan pertama secara manual

Waktu dan run pertama menentukan apakah jadwal bertahan. Keduanya mudah salah pada bulan pertama, dan keduanya murah untuk dilakukan dengan benar.

Dua keputusan, ditulis sekali, menghemat paling banyak argumen nanti. Yang pertama adalah hari. Yang kedua adalah di mana timer berjalan. Keduanya milik runbook, bukan di kepala siapa pun.

Pilih satu hari dan tulis

Hari tetap dalam sebulan, seperti hari kerja pertama setelah pembaruan stabil, lebih mudah dijelaskan daripada tebakan awal bulan.

Masukkan hari ke dalam file jadwal itu sendiri, sehingga waktu menjadi bagian dari kode dan bukan memori di kalender seseorang.

Jalankan pekerjaan pertama secara manual

Run terjadwal pertama harus manual. Jalankan skrip sendiri, baca log, bandingkan file dengan yang sebelumnya, dan baru kemudian serahkan timer.

Run pertama juga menguji penyimpanan rahasia. Kunci yang berfungsi di mesin Anda tetapi hilang di CI adalah alasan umum untuk kegagalan terjadwal pertama.

Jaga sidecar tetap jujur

File sidecar mencatat apa yang dilakukan run. Jika seseorang menuliskannya secara manual, ia menyimpang dari run. Biarkan skrip yang menulisnya, dan biarkan orang hanya membacanya.

Sidecar yang tidak disentuh skrip adalah catatan, bukan catatan, dan laporan harus mengutip catatan tersebut.

Bandingkan sidecar dengan file sekali sebulan. Jika angka-angka dalam keduanya tidak cocok, run gagal dengan cara yang tidak diperhatikan skrip.

Di mana timer berada

Runner yang dihosting dan entri cron lokal gagal dengan cara yang berbeda. Runner yang dihosting dapat dijeda oleh pengaturannya sendiri, dan entri cron lokal berhenti ketika mesin tidur. Periksa mana yang Anda pilih, dan uji timer sekali dengan jadwal pendek sebelum yang sebenarnya.

Apapun yang Anda pilih, tulis timer di repositori di sebelah skrip, sehingga orang berikutnya tahu di mana pekerjaan berada.