Skip to main content

Pings

A ping is a signal your job sends to Crontify to communicate its state. There are three ping types: start, success, and fail.

Ping types​

start​

Sent at the beginning of your job. Tells Crontify the job is running.

await monitor.start();

Effect: Creates a run record with status running. Resets the missed-run detection window. If a previous run is still running when a new start arrives, the old run is closed with status overlapped.

success​

Sent at the end of a successful job.

await monitor.success();

Effect: Closes the run record with status success and records the duration. Optionally accepts a meta object of numeric key-value pairs — these are stored on the run and evaluated against any alert rules you have configured.

await monitor.success({
  meta: {
    rows_processed: 1523,
    emails_sent: 48,
  },
});

After recording the success, Crontify also checks whether the run took significantly longer than the monitor's historical average. If it did, a slow alert fires — see Duration Anomaly Detection below.

fail​

Sent when your job encounters an unrecoverable error.

await monitor.fail({
  message: 'Database connection timeout',
  log: error.stack,
});

Effect: Closes the run record with status failed. Fires a failure alert immediately on all attached channels. Optionally includes an error message (shown in alerts), a meta object, and raw log output (stored separately — see Log Attachment).

Using wrap() instead of manual pings​

The wrap() method handles all three pings automatically and is the recommended pattern for most jobs:

await monitor.wrap(async () => {
  await doWork();
});
// Calls start() before, success() on completion, fail() on error

On error, wrap() automatically captures error.stack as the log output — you get full stack traces in the run detail view with no extra code. Errors are re-thrown after fail() is called, so your job's error handling continues to work normally.

What happens if you skip start?​

Calling success() or fail() without a preceding start() is valid. Crontify creates the run record automatically with startedAt set to the time of the success/fail ping and durationMs of 0. This is useful for jobs that don't have a meaningful start event — for example, simple heartbeat pings.

Overlap detection​

If a start ping arrives while a previous run is still running (i.e. no success or fail was received), the previous run is automatically closed with status overlapped. An overlapped alert fires immediately.

This detects jobs that are running concurrently when they shouldn't be — for example, a slow job that gets triggered again before the previous instance finishes.

Duration anomaly detection​

After every successful run, Crontify compares the run's duration against the historical average of the last 10 successful runs. If the current run took more than duration_anomaly_multiplier × average (default: 3×), a slow alert fires.

This detection only activates once a monitor has accumulated at least duration_anomaly_min_samples successful runs (default: 5). Both thresholds are configurable by your admin in the system settings panel.

The run retains success status — a slow run is not a failure. The isDurationAnomaly flag is set on the run record and surfaced in the run detail view.

Ping endpoint​

Pings are sent to the Crontify REST API. The SDK handles this for you, but you can also send pings manually — see HTTP Integration for details.