Back to Details

crontap-heartbeat-for-cron

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add a heartbeat to a recurring job

为定时任务添加心跳

A heartbeat monitors a job that already has its own clock. The job pings after successful work. Silence beyond the period and grace window becomes a missed check-in, while the 
/fail
variant reports explicit failure.
心跳用于监控一个本身已有调度时钟的任务。任务成功完成工作后会发起 ping。超过周期与宽限期之和仍无信号，即视为漏报；而 
/fail
变体用于报告显式失败。

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.
  • Know the job's real maximum interval, including expected jitter.
  • Choose a grace window long enough for ordinary delay and runtime.
  • Decide which component securely stores the returned ping URL.
在使用所需工具前，检查它们是否可用。如果缺少任何一种，请停止并向用户提供且仅提供以下两个选项：
  1. 在 
    https://mcp.crontap.com/mcp
    连接 Crontap MCP。每个 Crontap 套餐层级均支持 MCP 访问。
  2. 为原始 API 配置 
    $CRONTAP_CLIENT_ID
    和 
    $CRONTAP_API_KEY
    。原始 API 访问需要 Ultra 套餐。
不要擅自选择路径，也不要在用户选择前继续操作。
  • 了解任务的真实最大间隔，包括预期抖动。
  • 选择足以容纳普通延迟和运行时间的宽限期。
  • 确定由哪个组件安全存储返回的 ping URL。

Workflow

工作流

  1. Create the heartbeat with the expected period and grace.
  2. Capture the returned ping URL once and store it as a secret.
  3. Add a success ping only after the job completes successfully.
  4. Add a 
    /fail
    ping to the job's handled failure path.
  5. Inspect ping history after deployment and after any incident.
  6. Rotate the token only for compromise or planned credential rotation.
  1. 按预期周期和宽限期创建心跳。
  2. 仅捕获一次返回的 ping URL，并将其作为 secret 存储。
  3. 仅在任务成功完成后添加成功 ping。
  4. 在任务已处理的失败路径中添加 
    /fail
    ping。
  5. 部署后及每次故障事件后检查 ping 历史。
  6. 仅在发生凭据泄露或计划轮换凭据时轮换 token。

MCP examples

MCP 示例

Create a daily heartbeat with 30 minutes of grace:
json
{
  "tool": "create_heartbeat",
  "arguments": {
    "name": "Nightly import",
    "periodMinutes": 1440,
    "graceMinutes": 30,
    "emailCooldownMinutes": 60
  }
}
The response contains a secret ping URL. Do not echo it into source control, CI logs, support tickets, or later agent messages.
Inspect one UTC day:
json
{
  "tool": "get_heartbeat_pings",
  "arguments": {
    "heartbeatId": "<heartbeat-id>",
    "day": "2026-09-14"
  }
}
Rotate after explicit confirmation:
json
{
  "tool": "rotate_heartbeat_token",
  "arguments": {
    "heartbeatId": "<heartbeat-id>"
  }
}
Rotation invalidates both variants of the old URL immediately. Update the job with the newly returned URL before its next deadline.
创建一个宽限期为 30 分钟的每日心跳：
json
{
  "tool": "create_heartbeat",
  "arguments": {
    "name": "Nightly import",
    "periodMinutes": 1440,
    "graceMinutes": 30,
    "emailCooldownMinutes": 60
  }
}
响应中包含一个机密 ping URL。不要将其写入源代码管理、CI 日志、支持工单或后续 Agent 消息中。
查看一个 UTC 日内的记录：
json
{
  "tool": "get_heartbeat_pings",
  "arguments": {
    "heartbeatId": "<heartbeat-id>",
    "day": "2026-09-14"
  }
}
获得明确确认后进行轮换：
json
{
  "tool": "rotate_heartbeat_token",
  "arguments": {
    "heartbeatId": "<heartbeat-id>"
  }
}
轮换会立即使旧 URL 的两个变体失效。请在任务下一个截止期限之前，使用新返回的 URL 更新任务。

Job integration

任务集成

Use an environment variable such as 
CRONTAP_HEARTBEAT_URL
.
bash
run_the_job &&
  curl --fail --silent --show-error "$CRONTAP_HEARTBEAT_URL"
On a handled failure, call 
"$CRONTAP_HEARTBEAT_URL/fail?msg=bounded-error-summary"
. Keep messages free of credentials, personal data, and large stack traces.
使用 
CRONTAP_HEARTBEAT_URL
等环境变量。
bash
run_the_job &&
  curl --fail --silent --show-error "$CRONTAP_HEARTBEAT_URL"
对于已处理的失败，调用 
"$CRONTAP_HEARTBEAT_URL/fail?msg=bounded-error-summary"
。消息中不得包含凭据、个人数据或大型堆栈跟踪。

REST fallback

REST 回退方案

REST requires Ultra API access. MCP does not.
bash
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
  }'
REST 需要 Ultra API 访问权限，而 MCP 不需要。
bash
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
  }'

Verification

验证

  • Send one test success from the deployed job environment.
  • Confirm the heartbeat moves from pending after an accepted ping.
  • Exercise a safe failure path and verify a 
    fail
    event without exposing the ping URL.
  • Check that the period plus grace reflects the job's worst normal runtime.
  • 从已部署的任务环境发送一次测试用的成功 ping。
  • 确认接受 ping 后，心跳会从 pending 状态移出。
  • 触发安全的失败路径并验证 
    fail
    事件，同时不暴露 ping URL。
  • 检查周期与宽限期之和是否足以反映任务正常运行时长的最坏情况。

Safety and plan limits

安全与套餐限制

  • The ping URL is a credential. Anyone holding it can report activity.
  • A heartbeat detects silence but does not start or restart the job.
  • Starter heartbeat cadence and count limits differ from paid plans. Let the create response enforce the current account.
  • On a plan-limit response, present its four-option ladder and the smallest viable option without inventing prices.
  • ping URL 是一种凭据。任何持有它的人都可以上报活动。
  • 心跳只能检测静默，不会启动或重启任务。
  • 入门套餐的心跳频率和数量限制与付费套餐不同。当前账户适用的限制应以 create 响应为准。
  • 收到套餐限制响应时，展示响应中的四选项阶梯和最小可行选项，但不要虚构价格。

Troubleshooting

故障排查

  • No deadline starts until the first accepted ping.
  • Pings while paused record history but do not change deadlines.
  • Repeated rapid pings may be rate limited while still returning HTTP 200.
  • If the old URL stops working after rotation, that is expected. Deploy the replacement secret.
  • 在接受首个 ping 之前，截止期限不会开始计算。
  • 暂停期间的 ping 会记录历史，但不会改变截止期限。
  • 快速重复发送 ping 可能受到速率限制，但仍会返回 HTTP 200。
  • 轮换后旧 URL 停止工作属于预期行为。请部署替代 secret。

References

参考资料