Щомісячний регламент для звіту про беклінки

Чому щомісяця, а не щодня

Наш графік оновлюється приблизно раз на місяць. Щоденний запуск повертає ті самі числа.

Запуск частіше не робить звіт актуальнішим, він лише робить його дорожчим для пояснення. Читач, який бачить 30 однакових точок, припустить, що конвеер зламаний.

Вибір одного дня на місяць свідомо, ідеально через тиждень після того, як попереднє оновлення вщухне. Запишіть дату в назву файла, щоб сам графік був задокументований.

Спочатку виберіть календар, а звіт нехай слідує за ним. Звіт, який перебудовується щоразу, коли хтось відкриває блокнот, взагалі не має чіткої дати, і це важко захищати на ревізії.

Що зберігати окрім чисел

Половину звіту становить метадані, тому зберігайте їх поруч із числами.

Запишіть дату витяжки, назву дії, параметри (per, sort, order) та поле credits відповіді в невеликий супутній файл поруч із кожним знімком. Через пів року, коли колега запитає, чому жовтень виглядає інакше, ніж вересень, цей файл дасть відповідь за десять секунд замість цілого дня.

Додайте хеш коміта скрипта та версії пакетів з renv. Звіт, який не може сказати, який код і який стан індексу створили графік, — це скріншот, а не аналіз, незалежно від того, наскільки акуратним виглядає tibble.

Мінімальна структура targets

Трьох цілей достатньо, коли план залишається невеликим.

Одна ціль витягує дані з API і записує файл з датою, одна читає файл і будує tibble, одна рендерить документ Quarto. Оскільки лише перша ціль звертається до мережі, ви можете перебудовувати інші офлайн стільки завгодно, і графік випадково не зміниться.

Фіксуйте версії пакетів за допомогою renv, записуйте інформацію про сесію у підвалі звіту та зберігайте таблицю порогів зі сторінки масового оцінювання в репозиторії поруч із кодом. Щодо бюджету, сторінка з цінами покаже, скільки має коштувати місяць.

Коли щось ламається, спочатку читайте код. HTTP 401 означає, що ключ неправильний або відсутній. HTTP 402 означає, що закінчилися кредити. Все інше варто логувати повністю. Розбір охоплює ці етапи, а приклад об'єднання — гарна перша задача для планування.

Дізнатися, що запуск пройшов неправильно, перш ніж колега

Відтворюваний звіт про беклінки, який тихо падає, вводить в оману більше, ніж той, що взагалі не запустився. Справжнє питання не в тому, чи може задача впасти, а в тому, як швидко хтось про це дізнається.

Зробіть так, щоб задача падала гучно

Запланована задача завершується з ненульовим статусом, коли запит повертає HTTP 401 або 402, і планувальник позначає запуск як невдалий. Це найдешевший спосіб сповіщення, якому не потрібні додаткові сервіси.

Часткові витяжки — небезпечний випадок. Якщо скрипт записує свій файл після двадцяти з тридцяти чанків, файл існує і виглядає нормально. Записуйте у тимчасове ім'я і перейменовуйте лише при успіху.

Надсилайте одне повідомлення про одну помилку

Оберіть один канал для повідомлень про помилки, наприклад, email власнику звіту або повідомлення в командному чаті. Два канали означають два місця для пошуку і вищу ймовірність того, що ніхто не подивиться ні в одне.

Повідомлення має містити назву цілі, яка впала, код статусу та час. Все інше належить логу.

Перевірте, чи є вивід правдоподібним

Запуск може бути успішним, але дані будуть неправильними. Порівняйте кількість рядків із минулим місяцем і позначте падіння вище порогу, який ви обрали заздалегідь.

Перевірка може бути простою, як очікуваний діапазон. Мета — помітити напівпорожній знімок, перш ніж графік потрапить до клієнта.

Призначте одного власника звіту

Призначте одного власника звіту. Сповіщення без власника читають усі, але реагує ніхто.

Власник не зобов'язаний виправляти задачу. Власник має вирішити, чи прийнятно запізнення звіту, і написати про це в самому звіті.

Запишіть ім'я власника в заголовок регламенту і оновлюйте його при зміні власника. Регламент із колишнім власником — тиха загроза.

Вибір дня та запуск першої задачі вручну

Часування та перший запуск вирішують, чи тримається графік. Обидва легко зробити неправильно в перший місяць, і обидва легко виправити.

Два рішення, записані один раз, економлять найбільше суперечок пізніше. Перше — день. Друге — місце, де працює таймер. Обидва мають бути в регламенті, а не в чиїйсь голові.

Оберіть один день і запишіть його

Фіксований день місяця, наприклад, перший робочий день після того, як оновлення вщухне, легше пояснити, ніж вгадування на початку місяця.

Покладіть день у файл розкладу, щоб час був частиною коду, а не пам'яттю в чиїсь календарі.

Запустіть першу задачу вручну

Перший запланований запуск має бути ручним. Запустіть скрипт самі, прочитайте лог, порівняйте файл із попереднім і лише потім передайте таймер.

Перший запуск також перевіряє сховище секретів. Ключ, який працює на вашому комп'ютері, але відсутній в CI, — поширена причина першої запланованої невдачі.

Зберігайте супутній файл чесним

Супутній файл фіксує, що зробив запуск. Якщо людина записує його вручну, він відхиляється від реального запуску. Нехай скрипт записує його, а люди лише читають.

Супутній файл, до якого скрипт не торкався, — це нотатка, а не запис, і звіт має посилатися на запис.

Порівнюйте супутній файл з файлом раз на місяць. Якщо числа в двох не збігаються, запуск провалився так, що скрипт цього не помітив.

Де живе таймер

Хостований раннер і локальний cron-запис падають по-різному. Хостований раннер можна призупинити власними налаштуваннями, а локальний cron-запис зупиняється, коли комп'ютер засинає. Перевірте, що ви обрали, і протестуйте таймер раз коротким графіком перед справжнім.

Якщо ви обрали будь-який варіант, запишіть таймер в репозиторії поруч із скриптом, щоб наступна людина знала, де живе задача.