再現可能なバックリンクレポートのための月次ランブック

なぜ日次ではなく月次なのか

当社のグラフは月1回程度更新されます。日次ジョブは同じ数値を返します。

より頻繁に実行してもレポートが最新になるわけではなく、説明のコストが増えるだけです。30個の同一ポイントを目にする読者は、パイプラインに問題があると判断します。

毎月意図的に1日を選び、理想的には前回の更新が落ち着いてから1週間後に設定する。ファイル名に日付を書き込み、スケジュール自体を文書化する。

まずカレンダーを選び、レポートに従わせる。ノートブックを開くたびに再構築されるレポートには明確な日付がなく、レビューで説明するのが難しくなる。

数値以外に何を保存するか

レポートの半分はメタデータであるため、数値と一緒に保存する。

プル日、アクション名、パラメータ（per、sort、order）、およびレスポンスのcreditsフィールドを、各スナップショットの隣にある小さなサイドカーファイルに書き込む。6ヶ月後、同僚が10月が9月と異なる理由を尋ねたとき、そのファイルが午後ではなく10秒で答えを出す。

スクリプトのgitコミットとrenvからのパッケージバージョンを追加する。どのコードとどのインデックス状態がチャートを生み出したかを示せないレポートは、tibbleがどれだけ整っていても、分析ではなくスクリーンショットに過ぎない。

最小限のtargetsレイアウト

計画が小さい場合、3つのターゲットで十分である。

1つのターゲットはAPIからプルして日付付きファイルを書き込み、1つはファイルを読み取ってtibbleを構築し、1つはQuartoドキュメントをレンダリングする。最初のターゲットのみがネットワークにアクセスするため、他のターゲットはオフラインで何度でも再実行でき、チャートが偶然変更されることはない。

renvでパッケージバージョンを固定し、レポートのフッターにセッション情報を記録し、バルクスコアリングページからの閾値テーブルをコードの隣にあるリポジトリに保持する。費用面については、予算ページが月あたりのコストを示している。

何か失敗した場合は、まずコードを読む。HTTP 401はキーが間違っているか不足していることを意味する。HTTP 402はクレジットが枯渇したことを意味する。それ以外はすべて完全にログに記録する価値がある。テardownはそれらのステージをカバーしており、結合例はスケジュールする最初のジョブとして適している。

同僚よりも先に実行の失敗を知る

静かに失敗する再現可能なバックリンクレポートは、実行されなかったレポートよりも誤解を招く。真の問題はジョブが失敗するかどうかではなく、誰がそれをどれくらい早く知るかである。

ジョブを大きく失敗させる

スケジュールされたジョブは、呼び出しがHTTP 401または402を返した場合、非ゼロのステータスで終了し、スケジューラは実行を失敗としてマークする。これが最も安価なアラートであり、追加のサービスは必要ない。

部分的なプルは危険なケースである。スクリプトが30チャンク中20チャンク後にファイルを書き込む場合、ファイルは存在し、正常に見える。一時ファイルに書き込み、成功時のみリネームする。

失敗ごとに1通のメッセージを送信

失敗用のチャンネルを1つ選ぶ（例：レポート所有者へのメールまたはチームチャットへのメッセージ）。2つのチャンネルは2つの確認場所を生み出し、どちらも見逃される可能性が高まる。

メッセージには失敗したターゲット、ステータスコード、時刻を含める。それ以外はログに記録する。

出力が妥当か確認する

実行は成功しても、結果が間違っている可能性がある。行数を前月と比較し、事前に設定した閾値を超える減少をフラグ付けする。

チェックは予想される範囲であるだけでよい。目標は、チャートがクライアントに届く前に半分空のスナップショットに気づくことである。

レポートの所有者を1人指定する

レポートの所有者を1人指定する。所有者のないアラートは全員が読み、誰も行動しない。

所有者はジョブを修正する必要はない。所有者は、遅延したレポートが許容可能かどうかを判断し、レポート自体にそれを明記する必要がある。

所有者の名前をランブックのヘッダーに書き込み、所有者が変更されたら更新する。元々の所有者がいるランブックは静かな危険である。

日の選択と手動での初回ジョブ実行

タイミングと初回実行は、スケジュールが維持されるかどうかを決定する。どちらも最初の月に間違えやすく、正しく実行するのは安価である。

2つの決定を1回書き留めることで、後の議論の大部分を回避できる。1つ目は日付、2つ目はタイマーの実行場所である。両者はランブックに書き、誰かの頭脳に留めないこと。

1日を選び、書き留める

更新が落ち着いた後の最初の営業日など、月の固定された日は、月初の推測よりも説明しやすい。

スケジュールファイル自体に日付を配置し、タイミングを誰かのカレンダーの記憶ではなくコードの一部にする。

初回ジョブを手動で実行する

最初のスケジュール実行は手動で行うべきである。スクリプトを自分で実行し、ログを読み、ファイルを前回のものと比較し、その後でタイマーを渡す。

初回実行はまた、シークレットストアもテストする。あなたのマシンでは機能するがCIでは不足しているキーは、最初のスケジュール失敗の一般的な理由である。

サイドカーを誠実に保つ

サイドカーファイルは実行の内容を記録する。人が手動で書き込むと、実行から乖離する。スクリプトに書き込ませ、人は読むだけにさせる。

スクリプトが触れたことのないサイドカーはメモであり、記録ではない。レポートは記録を引用すべきである。

サイドカーとファイルを月1回比較する。2つの数値が一致しない場合、スクリプトが気づかない方法で実行が失敗したことを意味する。

タイマーの場所

ホスト型ランナーとローカルクロンエントリは異なる方法で失敗する。ホスト型ランナーは独自の設定によって一時停止される可能性があり、ローカルクロンエントリはマシンがスリープ状態になると停止する。どちらを選択したかを確認し、実際のスケジュールの前に短いスケジュールでタイマーを1回テストする。

どちらを選択しても、タイマーをスクリプトの隣にあるリポジトリに書き留め、次の人がジョブの場所を知るようにする。