Ежемесячный регламент для отчета по ссылкам

Почему раз в месяц, а не ежедневно

Наш график обновляется примерно раз в месяц. Ежедневный запуск возвращает те же цифры.

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

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

Сначала выберите календарь, а отчет пусть следует за ним. Отчет, который пересобирается каждый раз, когда кто-то открывает ноутбук, вообще не имеет четкой даты, и это трудно защитить при проверке.

Что хранить помимо цифр

Половина отчета — это метаданные, поэтому храните их вместе с цифрами.

Записывайте дату загрузки, имя действия, параметры (per, sort, order) и поле credits ответа в небольшой файл-спутник рядом с каждым снимком. Спустя полгода, когда коллега спросит, почему октябрь отличается от сентября, этот файл ответит за десять секунд, а не за весь день.

Добавьте коммит git скрипта и версии пакетов из renv. Отчет, который не может сказать, какой код и какое состояние индекса создали график, — это скриншот, а не анализ, независимо от того, насколько аккуратен tibble.

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

Трех targets достаточно, когда план остается небольшим.

Один target загружает данные из API и записывает файл с датой, один читает файл и строит tibble, один рендерит документ Quarto. Поскольку только первый target обращается к сети, вы можете пересобирать остальные офлайн столько раз, сколько захотите, и график случайно не изменится.

Фиксируйте версии пакетов с помощью renv, записывайте информацию о сессии в подвале отчета и храните таблицу порогов из страницы массового скоринга в репозитории рядом с кодом. Для финансовой стороны страница с ценами подскажет, сколько должен стоить месяц.

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

Узнать о сбое до того, как это сделает коллега

Воспроизводимый отчет по ссылкам, который тихо падает, вводит в заблуждение больше, чем тот, который вообще не запускался. Реальный вопрос не в том, может ли задача упасть, а в том, как быстро об этом узнают.

Заставьте задачу падать громко

Запланированная задача завершается с ненулевым статусом, если вызов возвращает HTTP 401 или 402, и планировщик помечает запуск как неудачный. Это самое дешевое оповещение, и для него не нужен дополнительный сервис.

Частичные загрузки — опасный случай. Если скрипт записывает файл после двадцати из тридцати чанков, файл существует и выглядит нормально. Записывайте во временное имя и переименовывайте только при успехе.

Отправляйте одно сообщение об ошибке

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

Сообщение должно называть упавший target, код статуса и время. Все остальное — в логе.

Проверяйте правдоподобность вывода

Запуск может быть успешным, но результат — неверным. Сравните количество строк с прошломесячным и отметьте падение ниже выбранного заранее порога.

Проверка может быть простой: ожидаемый диапазон. Цель — заметить полупустой снимок до того, как график попадет к клиенту.

Назначьте одного владельца отчета

Назначьте одного владельца отчета. Оповещение без владельца читает каждый, но реагирует никто.

Владелец не обязан чинить задачу. Владелец должен решить, приемлемо ли опоздание с отчетом, и написать об этом в самом отчете.

Впишите имя владельца в заголовок регламента и обновляйте его при смене владельца. Регламент с бывшим владельцем — тихая угроза.

Выбор дня и ручной запуск первой задачи

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

Два решения, записанные один раз, экономят больше всего споров в будущем. Первое — день. Второе — где запускается таймер. Оба должны быть в регламенте, а не в чьей-то голове.

Выберите один день и запишите его

Фиксированный день месяца, например первый рабочий день после того, как обновится система, легче объяснить, чем догадку в начале месяца.

Поместите день в файл расписания, чтобы время было частью кода, а не памятью в чьем-то календаре.

Запустите первую задачу вручную

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

Первый запуск также тестирует хранилище секретов. Ключ, который работает на вашем компьютере, но отсутствует в CI, — частая причина первого запланированного сбоя.

Держите спутник честным

Файл-спутник записывает, что сделал запуск. Если человек пишет его вручную, он расходится с запуском. Пусть скрипт пишет его, а люди только читают.

Спутник, к которому скрипт не прикасался, — это заметка, а не запись, и отчет должен ссылаться на запись.

Сравнивайте спутник с файлом раз в месяц. Если цифры в двух расходятся, запуск упал так, что скрипт этого не заметил.

Где живет таймер

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

Что бы вы ни выбрали, запишите таймер в репозитории рядом со скриптом, чтобы следующий человек знал, где живет задача.