Practical guide
Review Cron Heartbeats From a Local File
A backup ended at 2:17 a.m. Or maybe it only started.
The event file in front of you contains a job name and a few timestamps. Someone wants one answer: does this job need attention now?
That file can answer a narrow question. It cannot tell you that every event arrived, watch the next run, or explain why a failure occurred. The useful move is to classify only what the supplied events support.
A heartbeat row is not a completed job
A heartbeat row proves that a particular signal appears in the file. Its meaning depends on the event type.
Cronitor documents three lifecycle events for scheduled jobs: run when work starts, complete when it ends successfully, and fail when it ends with an error. Cronitor receives those events through its Telemetry API. It can also evaluate expected schedules and apply grace or tolerance settings.
A local file begins farther downstream. The events have already been supplied. Reviewing them does not prove where they came from or whether another event went missing before the file was made.
That distinction changes the decision:
- A
runevent says the job started. It does not establish completion. - A
completeevent supports a successful result for that execution. - A
failevent supports an explicit failure result. It does not identify the cause. - No event supports a missed-signal classification only when the expected interval, grace period, and review time are also known.
Give the review enough facts to answer one question
The review needs four kinds of input: the job identity, its timing rule, the ordered events, and the time being evaluated.
For a nightly backup, that means naming the backup, stating when its next signal was expected, allowing the chosen grace period, and supplying every event under review in timestamp order. The operator can then compare the event sequence with the timing rule.
This file review applies supplied success and failure observations plus a supplied evaluation time. It can return healthy, late, down, or recovered from those inputs. Repeating the same input produces the same ordered result.
For this review, a start-only row remains outside the success and failure classification. If the source contains run without complete or fail, keep completion unknown. Do not squeeze an incomplete lifecycle into a success label.
Four fictional cases expose the boundary
The examples below are fictional. They show what each supplied sequence can establish.
Case 1: the file contains only run
The job reports that it started at 2:00 a.m. No completion or failure follows.
The immediate answer is started, final outcome unknown. The operator may need logs or another source before deciding what happened next.
Case 2: complete follows the start
The job starts at 2:00 a.m. and reports completion at 2:17 a.m.
The completion event can be treated as a supplied success. If the earlier state was late or down, a later success can support a recovered state. The file still does not prove that an outside collector received every event.
Case 3: the job reports fail
The job starts at 2:00 a.m. and reports failure at 2:04 a.m.
The supplied failure supports a down classification. It does not support a claim about bad credentials, a full disk, a network problem, or any other cause unless the file contains separate source evidence for that cause.
Case 4: the expected signal is absent
The backup is expected at 2:00 a.m. with a 15-minute grace period. The supplied review time is after that grace period, but the file contains no success event for the expected run.
The timing rule supports a missed-signal result for this review. Nothing checked the clock on its own. Change the expected interval, grace period, or review time, and the answer may change.
Know when the event file is enough
The file is enough when a site operator needs to inspect a known event set, reproduce a classification, and decide what to check next.
It fits a post-incident review, a test of event wording, or a manual check before changing a scheduled task. The input remains visible, so another person can compare the status with the source events.
The file is a poor fit when the job needs independent event intake, continuous schedule evaluation, alert delivery, shared access, or long-term hosted history. Those are service functions. Cronitor’s official documentation describes telemetry intake, schedule settings, grace controls, and notification options for that wider job.
The file is also a poor fit for root-cause analysis. A failure event answers what status was supplied. It does not answer why the process failed.
For the wider category boundary, read Monitoring starts with the state you can prove.
Takeaway
An event file answers the immediate review question only when it separates successful completion, explicit failure, and silence under a supplied timing rule. A start event alone leaves the final outcome open.
Check one recent job without changing it
Make a copy of one recent job’s event file. Add its expected interval, grace period, and review time. Then test four versions: run only, complete, fail, and no later event. If the result changes for reasons you cannot point to in the copied input, the file is not yet a safe basis for action.