Back to Details

crontap-debug-failed-runs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug failed schedule runs

调试失败的定时任务运行

Diagnose from evidence before changing cadence, retries, or credentials.
在更改调度频率、重试策略或凭据之前，先基于证据进行诊断。

Prerequisites

前置条件

Before using the required tools, check whether they are available. If any are missing, stop and offer the user exactly two choices:
  1. Connect Crontap MCP at 
    https://mcp.crontap.com/mcp
    . MCP access works on every Crontap tier.
  2. Configure 
    $CRONTAP_CLIENT_ID
    and 
    $CRONTAP_API_KEY
    for the raw API. Raw API access requires Ultra.
Do not silently choose a path or continue until the user selects one.
  • Obtain the schedule ID from the user or the schedule list.
  • Define the incident window and the expected endpoint behavior.
  • Do not ask the user to paste secret header values or full tokens.
在使用必需工具之前，检查它们是否可用。如果有任何工具缺失，请停止操作，并向用户提供恰好两个选择：
  1. 在 
    https://mcp.crontap.com/mcp
    连接 Crontap MCP。所有 Crontap 套餐均支持 MCP 访问。
  2. 为原始 API 配置 
    $CRONTAP_CLIENT_ID
    和 
    $CRONTAP_API_KEY
    。原始 API 访问需要 Ultra 套餐。
不要擅自选择访问方式，也不要在用户选择之前继续操作。
  • 从用户或定时任务列表中获取 schedule ID。
  • 确定事件发生的时间范围以及端点的预期行为。
  • 不要要求用户粘贴机密请求头值或完整的 token。

Workflow

工作流

  1. Read the current schedule configuration with 
    get_schedule
    .
  2. Read the latest history page with 
    get_schedule_history
    .
  3. Compare several runs to identify a persistent error or a one-off event.
  4. Classify the failure before proposing a bounded fix.
  5. Verify the next run or a separately authorized test after a change.
  1. 使用 
    get_schedule
    读取当前定时任务配置。
  2. 使用 
    get_schedule_history
    读取最新一页执行历史。
  3. 比较多次运行，识别持续性错误或一次性事件。
  4. 在提出范围明确的修复方案之前，先对故障进行分类。
  5. 更改后，验证下一次运行或经过单独授权的测试。

MCP examples

MCP 示例

Read the active configuration:
json
{
  "tool": "get_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
Read recent outcomes:
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}
If the response includes a cursor, pass it unchanged to inspect older runs:
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50,
    "cursor": "<opaque-cursor>"
  }
}
读取当前生效的配置：
json
{
  "tool": "get_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
读取近期执行结果：
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}
如果响应中包含 cursor，请原样传递该值以查看更早的运行记录：
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50,
    "cursor": "<opaque-cursor>"
  }
}

Failure decision tree

故障决策树

  • No history and a future next run: verify cron, timezone, pause state, and account cadence floor.
  • HTTP 401 or 403: rotate or repair the target credential in its secure store.
  • HTTP 404: confirm route, deployment environment, and trailing path.
  • HTTP 429: inspect target rate limits and retry policy before adding traffic.
  • HTTP 500 through 599: use endpoint logs and trace IDs for the same timestamp.
  • Network error: check DNS, TLS, firewall, and public reachability.
  • Timeout: reduce endpoint work, move long processing behind a queue, or return an accepted response after durable enqueue.
  • Intermittent duplicate side effects: add endpoint idempotency before enabling more retries.
  • 没有执行历史且下一次运行时间在未来：检查 cron、时区、暂停状态以及账户的调度频率下限。
  • HTTP 401 或 403：在安全存储中轮换或修复目标凭据。
  • HTTP 404：确认路由、部署环境以及路径末尾部分。
  • HTTP 429：在增加请求流量之前，检查目标服务的速率限制和重试策略。
  • HTTP 500 至 599：使用对应时间戳的端点日志和 trace ID 进行排查。
  • 网络错误：检查 DNS、TLS、防火墙以及公网可达性。
  • 超时：减少端点工作量，将耗时处理移至队列异步执行，或在可靠入队后返回已接受响应。
  • 间歇性出现重复副作用：先为端点增加幂等性，再启用更多重试。

REST fallback

REST 备用方案

REST history access requires Ultra API access:
bash
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"
Prefer MCP when connected. It is available independently of Ultra REST access.
通过 REST 访问执行历史需要 Ultra API 访问权限：
bash
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。它独立于 Ultra REST 访问权限提供。

Verification

验证

  • State the first failing timestamp, repeated signature, and last known success.
  • Tie every recommendation to current configuration or history evidence.
  • After a fix, verify both the HTTP outcome and the intended application side effect.
  • Keep the previous evidence so a transient recovery is not mistaken for a permanent fix.
  • 明确说明首次失败的时间戳、重复出现的错误特征以及最后已知成功的时间。
  • 每项建议都必须与当前配置或历史记录证据相对应。
  • 修复后，同时验证 HTTP 结果和预期的应用副作用。
  • 保留之前的证据，避免将暂时恢复误认为永久修复。

Safety and plan limits

安全与套餐限制

  • Read operations do not authorize a configuration change.
  • Never reveal hidden headers or ask Crontap to return stored secret values.
  • Do not enable broad retries for 4xx responses without an explicit reason.
  • If a proposed cadence or retry change hits an entitlement error, present its four-option ladder and smallest viable option.
  • 读取操作不代表获得修改配置的授权。
  • 绝不泄露隐藏请求头，也不要要求 Crontap 返回已存储的机密值。
  • 没有明确理由时，不要为 4xx 响应启用宽泛的重试策略。
  • 如果建议的调度频率或重试更改遇到套餐权益错误，请展示相应的四档方案及最小可行选项。

Troubleshooting

故障排查

  • A not-found result usually means a stale ID. List schedules in the connected account rather than guessing.
  • History is retained by plan and may not cover the full incident window.
  • A successful HTTP code does not prove downstream work completed. Check an application-level receipt, record, or trace.
  • 出现 not-found 结果通常意味着 ID 已失效。请列出已连接账户中的定时任务，不要进行猜测。
  • 执行历史的保留时间取决于套餐，可能无法覆盖完整的事件时间范围。
  • HTTP 状态码成功并不能证明下游工作已完成。请检查应用级回执、记录或 trace。

References

参考资料