crontap-debug-failed-runs

スケジュール実行の失敗をデバッグする

頻度、リトライ、認証情報を変更する前に、証拠に基づいて診断してください。

前提条件

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

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

ユーザーがいずれかを選択するまでは、どちらかの方法を勝手に選んだり、処理を続けたりしないでください。

• ユーザーまたはスケジュール一覧からスケジュール ID を取得します。
• インシデントの時間範囲と、エンドポイントに期待される動作を定義します。
• 秘密のヘッダー値やトークン全体をユーザーに貼り付けるよう求めないでください。

ワークフロー

1. get_schedule で現在のスケジュール設定を読み取ります。
2. get_schedule_history で最新の履歴ページを読み取ります。
3. 複数回の実行を比較し、継続的なエラーか単発の事象かを特定します。
4. 範囲を限定した修正を提案する前に、失敗の種類を分類します。
5. 変更後、次回の実行、または別途許可を得たテストを検証します。

MCP の例

有効な設定を読み取ります。

{
  "tool": "get_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}

直近の結果を読み取ります。

{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}

応答にカーソルが含まれる場合は、そのまま渡して古い実行を確認します。

{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50,
    "cursor": "<opaque-cursor>"
  }
}

失敗の判断ツリー

• 履歴がなく、次回実行が未来に設定されている場合：cron、タイムゾーン、一時停止状態、アカウントの実行頻度の下限を確認します。
• HTTP 401 または 403：セキュアストアにある接続先の認証情報をローテーションするか、修正します。
• HTTP 404：ルート、デプロイ環境、末尾のパスを確認します。
• HTTP 429：トラフィックを増やす前に、接続先のレート制限とリトライポリシーを確認します。
• HTTP 500 から 599：同じタイムスタンプのエンドポイントログとトレース ID を確認します。
• ネットワークエラー：DNS、TLS、ファイアウォール、パブリックアクセスの可否を確認します。
• タイムアウト：エンドポイントの処理を減らす、時間のかかる処理をキューの後ろに移す、または永続化されたキューへの登録後に受け付け済みの応答を返す方法を検討します。
• 副作用の重複が断続的に発生する場合：リトライを増やす前に、エンドポイントに冪等性を追加します。

REST の代替手段

REST で履歴にアクセスするには、Ultra API の利用権限が必要です。

curl --fail-with-body \
  "https://api.crontap.com/v1/schedule/<schedule-id>/history?limit=50" \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY"

接続されている場合は MCP を優先してください。MCP は Ultra の REST アクセスとは独立して利用できます。

検証

• 最初に失敗したタイムスタンプ、繰り返し発生している特徴、最後に成功した時点を示します。
• すべての推奨事項を、現在の設定または履歴に基づく証拠と関連付けます。
• 修正後は、HTTP の結果と、意図したアプリケーション側の副作用の両方を検証します。
• 一時的な復旧を恒久的な修正と誤認しないよう、以前の証拠を保管します。

安全性とプランの制限

• 読み取り操作は、設定変更を許可するものではありません。
• 非表示のヘッダーを開示したり、Crontap に保存済みの秘密値を返すよう求めたりしないでください。
• 明確な理由がない限り、4xx 応答に対する広範なリトライを有効にしないでください。
• 提案した実行頻度またはリトライの変更で利用権限エラーが発生した場合は、4つの選択肢からなる段階的な案と、実行可能な最小の選択肢を提示します。

トラブルシューティング

• 見つからないという結果は、多くの場合、ID が古いことを示します。推測するのではなく、接続中のアカウントでスケジュール一覧を取得してください。
• 履歴の保存期間はプランによって異なるため、インシデントの全期間がカバーされない場合があります。
• HTTP コードが成功を示していても、後続処理が完了したとは限りません。アプリケーションレベルの受領記録、レコード、またはトレースを確認してください。

参考資料

• Crontap エージェントスキルカタログ
• Cron のトラブルシューティングガイド
• 自動リトライ
• Cron ジョブの監視
• 最新の REST API リファレンス