Cron Monitoring

Register, save, and connect the monitor

1. Register a monitor and set the expected cadence to match the schedule your existing job already follows.
2. Save the private check-in URL when it is shown once. Store it asTELESIS_CRON_URL in the existing scheduler's secret store.
3. Add a completion check-in, run the existing job once, and confirm that the monitor reports Check-in received.

Start with completion-only success

The private base URL accepts GET, HEAD, or POST as a successful completion. Call it only after the command succeeds.

your-command && curl -fsS "$TELESIS_CRON_URL"

A failed command sends no success check-in. The monitor becomes late at the expected time and becomes missed only after the grace deadline. This shortest example deliberately does not retry automatically, so an ambiguous network outcome cannot create an unqualified retry.

HTTP/1.1 204 No Content
Cache-Control: no-store

Every accepted check-in returns 204 No Content and Cache-Control: no-store.

Add incoming lifecycle check-ins when needed

Use POST /start, POST /complete, and POST /fail when you need immediate failure reporting or maximum-runtime detection. One shared run ID correlates the three events. Each event has a distinct idempotency key because retries of start, complete, and fail are independent.

Set TELESIS_RUN_ID to a unique execution ID from your scheduler when it provides one. Otherwise, this example generates a random 128-bit run ID from /dev/urandom.

RUN_ID="${TELESIS_RUN_ID:-$(LC_ALL=C od -An -N16 -tx1 /dev/urandom | tr -d ' \n')}"
CHECK_IN_URL="$TELESIS_CRON_URL"
curl -fsS --get -X POST -H "Idempotency-Key: $RUN_ID:start" --data-urlencode "run_id=$RUN_ID" "$CHECK_IN_URL/start"
if ./your-command; then
  EXIT_CODE=0
  curl -fsS --get -X POST -H "Idempotency-Key: $RUN_ID:complete" --data-urlencode "run_id=$RUN_ID" "$CHECK_IN_URL/complete"
else
  EXIT_CODE=$?
  curl -fsS --get -X POST -H "Idempotency-Key: $RUN_ID:fail" --data-urlencode "run_id=$RUN_ID" "$CHECK_IN_URL/fail"
fi
exit "$EXIT_CODE"

Supply run_id through the query string or JSON body. If you provide it in both places, the values must match. The Idempotency-Key header identifies a retry of one event: reuse that event's stable key, but use a different key for every other event.

{
  "run_id": "$RUN_ID",
  "duration_ms": 8421,
  "exit_code": 1,
  "terminal_reason": "backup command failed",
  "diagnostic_excerpt": "bounded diagnostic context for this run"
}

The raw JSON fields are run_id, duration_ms, exit_code, terminal_reason, and the bounded diagnostic_excerpt. Keep diagnostics short, non-sensitive, and useful for the failed run.

Patch the job you already run

The optional local CLI wrapper runs only when you invoke it inside your existing scheduler. It launches the child command on your machine, reports lifecycle events, and preserves the child's exit status. The hosted service still does not execute or schedule it.

telesis cron run "$TELESIS_CRON_URL" -- ./your-command

Patch an existing Kubernetes CronJob

# Add to the container in your existing CronJob
env:
  - name: TELESIS_CRON_URL
    valueFrom:
      secretKeyRef:
        name: telesis-cron
        key: url
command: ["/bin/sh", "-c"]
args: ['your-command && curl -fsS "$TELESIS_CRON_URL"']

Patch an existing GitHub Actions workflow

# Add to a job in your existing scheduled workflow
- name: Run monitored job
  env:
    TELESIS_CRON_URL: ${{ secrets.TELESIS_CRON_URL }}
  run: |
    your-command && curl -fsS "$TELESIS_CRON_URL"

Understand late, missed, failed, and timed-out runs

Late

The expected time has passed without a success, but the grace deadline has not passed yet.

Missed

No success arrived by the grace deadline. A completion-only shell failure reaches this state after being late; it is not an immediate failure report.

Failed

An incoming /fail check-in records an immediate failed run.

Timed out

A /start without a terminal complete or fail event before the configured maximum runtime becomes timed out.

Protect the credential and scope monitor actions

• Treat the complete private URL as a secret. Keep it in a secret store and out of logs, source control, screenshots, and chat.
• Pause monitoring only disables deadline evaluation. It does not stop the existing job, and incoming check-ins remain accepted.
• Rotate the check-in URL if it is lost or exposed. The replacement is shown once; the previous credential remains valid only for the configured rotation grace window.