链接报告月度运行手册

为何选择月度而非每日

我们的图表大约每月刷新一次。每日运行会返回相同的数字。

更频繁地运行并不会使报告更及时，只会增加解释成本。读者看到 30 个相同的点会认为管道已损坏。

每月刻意选择一天，最好在上次刷新稳定后的一周。将日期写入文件名，以便记录调度本身。

先确定日历，让报告跟随日历。每次有人打开笔记本就重建的报告没有任何明确的日期，这在审查中很难解释。

除数字外还应存储什么

报告的一半是元数据，因此应与数字一起存储。

将拉取日期、操作名称、参数（per、sort、order）以及响应的 credits 字段写入每个快照旁边的侧边文件中。六个月后，当同事询问为何十月与九月不同时，该文件能在十秒内给出答案，而非耗费一下午。

添加脚本的 git 提交记录和 renv 中的包版本。一份无法说明哪个代码和哪个索引状态生成了图表的报告只是截图，而非分析，无论 tibble 看起来多么整洁。

最小的 targets 布局

当计划保持简单时，三个 target 就足够了。

一个 target 从 API 拉取并写入带日期的文件，一个读取文件并构建 tibble，一个渲染 Quarto 文档。因为只有第一个 target 接触网络，你可以离线尽可能多地重新运行其他 target，而图表不会意外更改。

使用 renv 锁定包版本，在报告页脚记录会话信息，并将 批量评分页面 中的阈值表保留在代码旁边的仓库中。关于费用方面，预算页面 会告诉你一个月应该花费多少。

当出现问题时，先阅读代码。HTTP 401 意味着密钥错误或缺失。HTTP 402 意味着积分耗尽。其他任何情况都值得完整记录。拆解 涵盖了这些阶段，连接示例 是一个适合计划的好工作。

在同事发现之前得知运行出错

一个静默失败的链接报告比从未运行的报告误导更多。真正的问题不是作业是否会失败，而是有人多快能得知。

让作业大声失败

当调用返回 HTTP 401 或 402 时，计划作业以非零状态退出，调度器将运行标记为失败。这是最便宜的警报，无需额外服务。

部分拉取是危险的情况。如果脚本在三十个块中的二十个之后写入文件，文件存在且看起来正常。写入临时名称，仅在成功时重命名。

每次失败发送一条消息

为失败选择一个渠道，例如发送给报告所有者的电子邮件或团队聊天中的消息。两个渠道意味着两个查看位置，且无人查看任一渠道的可能性更高。

消息应指明失败的 target、状态代码和时间。其他所有内容属于日志。

检查输出是否合理

运行可能成功但仍出错。将行数与上月进行比较，并对超出预先选择阈值的下降进行标记。

检查可以只是一个预期范围。目标是在图表到达客户之前注意到半空的快照。

为报告指定一个负责人

为报告指定一个负责人。没有负责人的警报会被所有人阅读，但无人采取行动。

负责人不必修复作业。负责人必须决定延迟的报告是否可接受，并在报告中说明。

将负责人姓名写入运行手册标题，并在负责人变更时更新。带有前任负责人的运行手册是一个安静的隐患。

选择日期并手动运行首次作业

时机和首次运行决定了调度是否有效。两者在第一个月都容易出错，但也容易做对。

两个决定，写下来一次，可以节省日后最多的争论。第一个是日期。第二个是计时器运行的位置。两者都应写入运行手册，而非任何人的脑海中。

选择一天并写下来

每月的固定一天（例如刷新稳定后的第一个工作日）比月初的猜测更容易解释。

将日期放入调度文件中，以便时间成为代码的一部分，而非某人日历中的记忆。

手动运行首次作业

首次计划运行应是手动的。亲自运行脚本，阅读日志，将文件与之前的文件进行比较，然后再将计时器移交。

首次运行还测试密钥存储库。在本地机器上有效但在 CI 中缺失的密钥是首次计划失败的常见原因。

保持侧边文件诚实

侧边文件记录运行做了什么。如果由人手动编写，它会与运行脱节。让脚本编写它，让人只读取它。

脚本从未触碰过的侧边文件只是笔记，而非记录，报告应引用记录。

每月将侧边文件与文件进行比较。如果两个文件中的数字不一致，则运行以脚本未注意到的方式失败了。

计时器的位置

托管运行器和本地 cron 条目以不同的方式失败。托管运行器可能因其自身设置而暂停，本地 cron 条目在机器休眠时停止。检查你选择了哪一个，并在真实调度之前用短调度测试一次计时器。

无论选择哪一个，都将计时器写在仓库中脚本旁边，以便下一个人知道作业的位置。