crontap-heartbeat-for-cron

定期ジョブにハートビートを追加する

ハートビートは、独自のスケジュールですでに実行されているジョブを監視します。ジョブが正常に完了した後に ping を送信します。期間と猶予時間を超えて応答がない場合はチェックイン漏れとなり、/fail バリアントを使うと明示的な失敗を報告できます。

前提条件

必須のツールを使用する前に、利用可能かどうかを確認してください。いずれかが利用できない場合はそこで停止し、ユーザーに次の2つの選択肢だけを提示してください。

1. Crontap MCP（https://mcp.crontap.com/mcp）に接続する。MCP はすべての Crontap プランで利用できます。
2. $CRONTAP_CLIENT_ID と $CRONTAP_API_KEY を設定して、Raw API を使用する。Raw API の利用には Ultra が必要です。

ユーザーが選択するまで、黙って方法を選んだり、処理を続けたりしないでください。

• 想定される揺らぎも含め、ジョブの実際の最大実行間隔を把握します。
• 通常の遅延と実行時間を十分に考慮した猶予時間を設定します。
• 返された ping URL をどのコンポーネントで安全に保管するか決めます。

ワークフロー

1. 想定される期間と猶予時間を指定して、ハートビートを作成します。
2. 返された ping URL を一度だけ取得し、シークレットとして保管します。
3. ジョブが正常に完了した後にのみ、成功 ping を追加します。
4. ジョブの処理対象となる失敗パスに /fail ping を追加します。
5. デプロイ後、およびインシデント発生後に ping 履歴を確認します。
6. トークンのローテーションは、漏えいまたは計画的な認証情報のローテーションが必要な場合にのみ行います。

MCP の例

猶予時間を30分に設定して、毎日のハートビートを作成します。

{
  "tool": "create_heartbeat",
  "arguments": {
    "name": "Nightly import",
    "periodMinutes": 1440,
    "graceMinutes": 30,
    "emailCooldownMinutes": 60
  }
}

レスポンスにはシークレットの ping URL が含まれます。ソース管理、CI ログ、サポートチケット、後続のエージェントとのメッセージに出力しないでください。

UTC の1日分を確認します。

{
  "tool": "get_heartbeat_pings",
  "arguments": {
    "heartbeatId": "<heartbeat-id>",
    "day": "2026-09-14"
  }
}

明示的な確認後にローテーションします。

{
  "tool": "rotate_heartbeat_token",
  "arguments": {
    "heartbeatId": "<heartbeat-id>"
  }
}

ローテーションすると、古い URL の両方のバリアントが直ちに無効になります。次の期限までに、ジョブを新しく返された URL に更新してください。

ジョブへの組み込み

CRONTAP_HEARTBEAT_URL などの環境変数を使用します。

run_the_job &&
  curl --fail --silent --show-error "$CRONTAP_HEARTBEAT_URL"

処理対象となる失敗が発生した場合は、 "$CRONTAP_HEARTBEAT_URL/fail?msg=bounded-error-summary" を呼び出します。メッセージには認証情報、個人データ、大量のスタックトレースを含めないでください。

REST の代替手段

REST の利用には Ultra API アクセスが必要です。MCP は必要ありません。

curl --fail-with-body https://api.crontap.com/v1/heartbeat \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Nightly import",
    "periodMinutes": 1440,
    "graceMinutes": 30
  }'

検証

• デプロイ済みのジョブ環境からテスト用の成功 ping を1回送信します。
• ping が受理された後、ハートビートが pending から移行することを確認します。
• 安全な失敗パスを実行し、ping URL を漏らさずに fail イベントが記録されることを確認します。
• 期間と猶予時間の合計が、ジョブの通常時の最長実行時間を考慮していることを確認します。

安全性とプランの制限

• ping URL は認証情報です。これを持つ人は誰でもアクティビティを報告できます。
• ハートビートは無応答を検知しますが、ジョブを開始または再起動するものではありません。
• Starter プランのハートビート頻度と件数の上限は、有料プランとは異なります。現在のアカウントに適用される上限は作成レスポンスで確認してください。
• プラン上限に関するレスポンスが返された場合は、4つの選択肢からなる段階的な選択肢と、実現可能な最小の選択肢を提示します。価格をでっち上げないでください。

トラブルシューティング

• 最初の ping が受理されるまで、期限は開始されません。
• 一時停止中の ping は履歴に記録されますが、期限は変わりません。
• 短時間に繰り返し送信された ping は、HTTP 200 が返されてもレート制限される場合があります。
• ローテーション後に古い URL が動作しなくなるのは想定どおりです。新しいシークレットをデプロイしてください。

参考資料

• Crontap Agent Skills カタログ
• Crontap のハートビート
• スケジュールされた AI ジョブ
• Cron ジョブの監視
• ライブ REST API リファレンス