Cron Monitoring
Monitor scheduled jobs with heartbeat pings that report success or failure.
Cron monitoring tracks the health of your scheduled jobs. After each job execution, the SDK sends a heartbeat ping to SeeStack with the job's status, duration, and an optional message. If a job fails or misses its schedule, SeeStack triggers an alert.
The cron monitor must be created first in the SeeStack console under Cron Monitors. The SDK only sends heartbeat pings — it does not create monitors.
Basic Usage
Create a Monitor in the Console
In the SeeStack dashboard, go to Cron Monitors and create a new monitor with a slug (e.g. daily-report-generator). Set the expected schedule so SeeStack knows when to expect pings.
Instrument Your Job
Wrap your job execution with startJob and finishJob:
const handle = SeeStack.startJob('daily-report-generator');
try {
await generateReport();
SeeStack.finishJob(handle, 'success', 'Processed 1,842 records');
} catch (e) {
SeeStack.finishJob(handle, 'failed', e.message);
throw e; // Always rethrow — the SDK must not swallow job errors
}handle = seestack.start_job("daily-report-generator")
try:
generate_report()
seestack.finish_job(handle, "success", "Processed 1,842 records")
except Exception as e:
seestack.finish_job(handle, "failed", str(e))
raise # Always re-raisehandle := seestack.StartJob("daily-report-generator")
err := generateReport()
if err != nil {
seestack.FinishJob(handle, "failed", err.Error())
return err // Always return the error
}
seestack.FinishJob(handle, "success", "Processed 1,842 records")Parameters
startJob
Prop
Type
Returns a JobHandle that tracks the start time internally.
finishJob
Prop
Type
Slug Format
Monitor slugs must match the pattern ^[a-z0-9-]+$ — lowercase letters, numbers, and hyphens only.
Valid: daily-report-generator, payment-reconciliation, cleanup-job-v2
Invalid: Daily_Report, my job, CLEANUP
How It Works
startJob(slug)records the current timestamp and returns a handle- Your job executes normally
finishJob(handle, status, message?)computesdurationMsfrom the start time- A heartbeat ping is sent immediately to the backend (no batching)
Heartbeats are sent immediately after finishJob is called — they are not buffered like logs or HTTP requests.
Never swallow job errors. Always rethrow or return the error after calling finishJob. The SDK reports the failure to SeeStack, but your application's error handling must still work normally.
Status Values
| Status | Meaning | SeeStack Behavior |
|---|---|---|
success | Job completed without errors | Recorded normally |
failed | Job encountered an error | Triggers alert evaluation immediately |