DEV Community: Cronpimo

Beyond a completion signal: three useful backup metrics

Cronpimo — Wed, 11 Nov 2026 08:15:47 +0000

Originally published on Cronpimo: Beyond a completion signal: three useful backup metrics.

The overnight backup finishes without an error and its completion signal arrives. Yet the new archive contains only a fraction of the expected data. Perhaps a source directory was not mounted; perhaps someone intentionally narrowed the selection. A green completion signal cannot distinguish those cases. Three additional measurements can help you decide what to investigate.

The example below is a fictional daily full export into a compressed archive. Its numbers illustrate the checks. They are neither recommended defaults for arbitrary backups nor results from a customer incident.

Define what each measurement means

Use the same definitions for every run: files counts backed-up source files in the current manifest, bytes measures the completed compressed archive, and duration_seconds covers the backup from its start to confirmed completion at the destination. The HTTP request that delivers the completion signal is not part of that duration.

Our example job has these deliberately chosen limits:

Metric	Reported value	Allowed range
Files	120	At least 100
Archive size	50 MiB	40 to 100 MiB
Duration	180 seconds	60 to 600 seconds

1. Count: did the expected selection get backed up?

A file count helps reveal a suddenly smaller selection. If this export reports 3 files instead of 120, inspect source paths, mounted volumes and exclusion rules. Successfully creating an archive does not mean the intended selection went into it.

Do not simply count files in the destination directory: one archive remains one file regardless of how many source files it contains. Use the result or manifest from this particular backup run. A database backup might need a different meaningful count; its internal backup files may say little about completeness.

Nor does 120 matching 120 prove identical contents. The limit detects certain differences, not every form of damage. Choose it using known, checked runs and the data structure you actually expect.

2. Volume: was unusually little or much written?

A 2 MiB archive falls below the example's lower limit. That calls for investigation, but does not establish a cause. Check whether less content was backed up or whether its compressibility changed. Switching compression methods can also alter the comparison.

An upper limit can reveal unexpectedly large backups: newly included logs, for example, or old archives accidentally added to the selection. Assess full and incremental backups separately. A small amount of new data can be perfectly valid for an incremental run.

The example reports bytes: 50 MiB is 52,428,800 bytes, with limits of 41,943,040 and 104,857,600 bytes. Keep the unit consistent when collecting, sending and configuring the measurement.

3. Duration: was the process unusually short or long?

A much shorter run may fit the missing-selection hypothesis. A longer one may reflect more data, slower storage or a stalled transfer. None of these measurements identifies a cause automatically. Compare duration with the count and volume from the same run.

A lower duration limit is useful only when a faster run would genuinely be suspicious. An optimization or storage change may require revising it. Here, the upper limit of 600 seconds means a completed run reporting 601 seconds violates the metric rule.

A duration reported after completion cannot detect a process that never finishes. Monitor missing or late signals as well. The cron job monitoring guide distinguishes starting a process, completing it and checking its result.

Send measurements with the completion signal

The heartbeat guide covers setup. For a completion-only signal, the illustrative payload is:

{
  "kind": "success",
  "event_id": "backup-example-001-end",
  "metrics": {
    "files": 120,
    "bytes": 52428800,
    "duration_seconds": 180
  }
}

Replace those numbers with measurements from the run that just finished, and use a unique event identifier for each signal. If you also send a start signal, both start and completion need the same run_key, unique to that run.

Cronpimo's minimum and maximum limits are inclusive: 100 files, 40 MiB, and either 60 or 600 seconds are inside these rules. Each configured metric must be present in a success signal. If duration_seconds is missing, the heartbeat is classified as failed despite kind: success. An unavailable measurement is not the same as zero seconds. Send numbers as JSON numbers; do not replace missing measurements with invented values.

Turn an unusual result into a specific check

First inspect the affected run and its measurement source. Are the manifest and archive really from today? Was the selection changed? Adjust limits after explaining the difference. Cronpimo does not learn these limits automatically from earlier backups. If your workflow instead exposes a readable status endpoint, the result-checking guide shows how to evaluate the result and its freshness separately.

Continue to schedule restoration tests. Even specialized integrity checkers do not replace them; the PostgreSQL documentation for pg_verifybackup makes that distinction explicitly. A complete set of plausible measurements is a useful operational signal. Restoring the required data is a separate test.

Disclosure: This article and its cover illustration were created autonomously with AI for Cronpimo. Its technical claims were checked against the current implementation and the referenced documentation. The heartbeat examples and metric boundaries were validated with isolated tests against the current code.

Every morning at eight: choosing schedules and time zones

Cronpimo — Wed, 28 Oct 2026 08:16:40 +0000

Your import runs every day, but since the clocks changed, its report no longer arrives at the expected local time. The schedule might be doing exactly what it was configured to do: “every 24 hours” instead of “every morning at eight.” Those instructions coincide on many days. A change in the local UTC offset exposes the difference.

A dependable schedule starts with three decisions: Is the requirement a wall-clock time or an elapsed interval? Which time zone belongs to the task? What should happen when a local time does not exist or occurs twice?

Wall-clock time or elapsed interval?

A daily report for a team in Vienna belongs to a local time. In a five-field cron expression, 0 8 * * * means minute zero, hour eight, every day. With the time zone Europe/Vienna, the scheduled occurrence stays at 08:00 local time.

A recurring technical check often has a different requirement: scheduled occurrences should be 300 seconds apart, for example. An interval fits that requirement. Cronpimo calculates interval occurrences from a fixed starting anchor. It does not add the previous request’s runtime as an extra delay between occurrences.

86,400 seconds is exactly 24 hours, but not always one local calendar day. When Vienna moves to daylight saving time, the affected day has 23 hours; when it moves back, the day has 25. A fixed interval in seconds does not follow that change.

A concrete example from October 2026

The following comparison shows calculated occurrences in Europe/Vienna. The interval starts on 24 October at 08:00 and repeats every 86,400 seconds. The calendar schedule uses 0 8 * * *.

Date	Calendar schedule	24-hour interval
24 October	08:00 (UTC+02:00)	08:00 (UTC+02:00)
25 October	08:00 (UTC+01:00)	07:00 (UTC+01:00)
26 October	08:00 (UTC+01:00)	07:00 (UTC+01:00)

The calendar schedule has one 25-hour gap across this transition. The interval preserves its 24-hour gap and lands earlier on the local clock. A morning report usually calls for the calendar schedule; evenly spaced technical checks call for the interval. These are scheduled occurrences, not a promise that execution starts without any delay or has completed by that time.

Choose a named time zone

Europe/Vienna represents local time rules. UTC+01:00 represents only a fixed offset and contains no daylight saving rule. The IANA time zone database is updated when those rules change. Choose the zone of the business operation: Vienna for an Austrian end-of-day process, for example, or UTC for an exchange explicitly defined in UTC.

The executing agent’s location is a separate setting. A request from the United States does not turn a Vienna schedule into an American schedule. Display settings also matter: in Cronpimo, the account time zone can differ from the job’s scheduling time zone. The Suite displays occurrences in the account time zone with their UTC offset. Compare the complete timestamp and offset, rather than the hour alone.

What happens at 02:30?

In Vienna, 02:30 does not exist on 29 March 2026 because the clocks move forward. On 25 October 2026, 02:30 occurs twice. Schedulers do not all handle these cases the same way, so check the policy of the system you use.

Cronpimo’s calendar scheduler skips a nonexistent local time and considers only the first occurrence of a repeated local time. A daily 30 2 * * * schedule therefore has no occurrence on 29 March. On 25 October its occurrence is at 02:30 UTC+02:00; a second occurrence at UTC+01:00 is not scheduled.

That makes 02:30 a poor choice for a daily closing process that must not be missed. Choose a local time outside the transition window, or deliberately use a schedule defined in UTC. If every business day must be processed, the application should also identify missing work by business date. Scheduling alone does not provide that business-level check.

A short check before enabling the schedule

Write the requirement explicitly: “every day at 08:00 in Vienna” or “every 300 seconds.”
Select the matching calendar schedule and time zone, or interval and starting anchor.
Inspect the upcoming occurrences in the preview. For a later clock change, test dates on both sides of that transition; the next five occurrences do not automatically cover every edge case.
Distinguish scheduled start, actual start and successful completion. Allow for normal runtime and possible maintenance windows.

If an import must be finished by eight, eight is usually too late to start it. Allow suitable lead time and check completion separately. The cron job monitoring guide explains the different checkpoints. For work running on your own server, heartbeat completion signals can help. If an API exposes the latest result, also check its content and freshness.

A good schedule makes the expectation explicit. The result then tells you whether the expected work was actually completed.

Originally published on Cronpimo: Every morning at eight: choosing schedules and time zones.

Disclosure: This article and its cover were created with AI for Cronpimo. The scheduling examples were checked against Cronpimo’s current implementation and isolated tests.

HTTP 200, empty import: monitor a PHP job's actual result

Cronpimo — Wed, 21 Oct 2026 06:34:22 +0000

Your scheduled import returns HTTP 200, but the new records are missing from the shop. The request succeeded; the business outcome still needs checking.

A small status endpoint can answer three more useful questions: did the import finish, did it commit enough records, and is the result recent? This tutorial separates the importer from the endpoint that observes it. It requires PHP 8.1 or later and works independently of the service or script you use to monitor that endpoint.

Disclosure: This article was prepared with AI assistance. The author represents Cronpimo, where the original guide is published.

Define success beyond the status code

For a frequently refreshed product feed, success might mean the import completed, at least one record was committed, and completion happened no more than 15 minutes ago:

{"status":"completed","imported_count":142,"updated_at":1792458000}

Here, updated_at is a Unix timestamp in seconds: 20 October 2026 at 01:00 UTC. It records the import's completion. Do not replace it with the current time whenever someone reads the status endpoint: that would make old data appear permanently fresh.

The count and timestamp are JSON numbers, not strings containing digits. The required minimum count is a business decision: an incremental feed with no changes may legitimately produce zero records.

Expose a protected status endpoint

Configure these environment variables for the PHP web process:

MONITOR_TOKEN: a random secret of at least 32 characters.
IMPORT_STATUS_FILE: an absolute path outside the public web directory.

For example, configure them in the relevant PHP-FPM pool. Exporting them in an interactive shell does not automatically configure the web process. Also configure HTTPS and forwarding of the Authorization header from your web server to PHP.

The endpoint accepts only GET, checks a Bearer token, limits the stored JSON it reads and returns only the three intended fields.

<?php
declare(strict_types=1);

function respond(int $code, array $data): never {
    http_response_code($code);
    header('Content-Type: application/json; charset=utf-8');
    header('Cache-Control: no-store');
    header('X-Content-Type-Options: nosniff');
    echo json_encode($data, JSON_THROW_ON_ERROR);
    exit;
}

if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'GET') {
    header('Allow: GET');
    respond(405, ['error' => 'method_not_allowed']);
}
$secret = getenv('MONITOR_TOKEN') ?: '';
$path = getenv('IMPORT_STATUS_FILE') ?: '';
if (strlen($secret) < 32 || $path === '') {
    respond(503, ['error' => 'status_unavailable']);
}
$auth = $_SERVER['HTTP_AUTHORIZATION']
    ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION'] ?? '';
if (!hash_equals('Bearer ' . $secret, $auth)) {
    header('WWW-Authenticate: Bearer');
    respond(401, ['error' => 'unauthorized']);
}
$raw = @file_get_contents($path, false, null, 0, 8193);
try {
    $s = is_string($raw) && strlen($raw) <= 8192
        ? json_decode($raw, true, 8, JSON_THROW_ON_ERROR) : null;
} catch (JsonException) {
    $s = null;
}
if (!is_array($s)
    || !in_array($s['status'] ?? null, ['completed', 'failed'], true)
    || !is_int($s['imported_count'] ?? null) || $s['imported_count'] < 0
    || !is_int($s['updated_at'] ?? null) || $s['updated_at'] < 0) {
    respond(503, ['error' => 'status_unavailable']);
}
respond(200, [
    'status' => $s['status'],
    'imported_count' => $s['imported_count'],
    'updated_at' => $s['updated_at'],
]);

A missing secret, unreadable file or malformed JSON produces HTTP 503. An incorrect Bearer token produces 401. A stored import status of failed can still be read with HTTP 200: the status request works, while the content check detects the failed import.

Keep customer data, internal file paths and import exception messages out of this response. Store operational error details in your own protected logs.

Publish a result only after the actual outcome

In this example, the importer and endpoint run under the same operating-system user. Include the following function in the importer. It writes a temporary file in the destination directory, then replaces the published file after writing completes. This avoids exposing a partially written JSON document to the monitor.

<?php
declare(strict_types=1);

// Include in the importer; call only after its final outcome is known.
function publishImportStatus(string $status, int $count): void {
    $path = getenv('IMPORT_STATUS_FILE') ?: '';
    if ($path === '' || !in_array($status, ['completed', 'failed'], true)
        || $count < 0 || !is_dir(dirname($path))) {
        throw new RuntimeException('Invalid status configuration');
    }
    $json = json_encode([
        'status' => $status,
        'imported_count' => $count,
        'updated_at' => time(),
    ], JSON_THROW_ON_ERROR);
    $tmp = tempnam(dirname($path), '.import-status-');
    if ($tmp === false) {
        throw new RuntimeException('Cannot create status file');
    }
    try {
        // Importer and status endpoint run as the same OS user here.
        if (!chmod($tmp, 0600)
            || file_put_contents($tmp, $json, LOCK_EX) !== strlen($json)
            || !rename($tmp, $path)) {
            throw new RuntimeException('Cannot publish import status');
        }
    } finally {
        if (is_file($tmp)) {
            unlink($tmp);
        }
    }
}

After a successful import and database commit, call:

publishImportStatus('completed', $importedCount);

$importedCount must be the number of records actually committed by your importer. This tutorial deliberately does not invent an import algorithm or fill that number with a constant.

On a caught import failure, publish publishImportStatus('failed', 0) and preserve the import process's failure exit status. A failure to write the status file also belongs in the local error log.

If the importer and endpoint use different operating-system accounts, configure narrowly scoped file permissions instead of making the file publicly readable. This example's 0600 permission assumes the same account reads and writes the file.

Check completion, quantity and freshness together

Make a GET request to the endpoint with the private header Authorization: Bearer YOUR_TOKEN. Keep that token out of URLs, repositories and screenshots. Require HTTP 200, then validate all three values:

JSON Pointer	Required condition	Value
`/status`	Equals the JSON string	`"completed"`
`/imported_count`	Is a number at least	`1`
`/updated_at`	Is a Unix timestamp no older than	`900` seconds

These paths use JSON Pointer, not JavaScript expressions. A missing field must not pass. The string "142" is not the JSON number 142; reject wrong types rather than silently coercing them.

For a Unix timestamp, age is evaluation_time - updated_at. Check that the value is not unreasonably in the future as well; keep the application and monitoring clocks synchronized and choose an explicit small clock-skew tolerance. Send seconds, not milliseconds. If your checker also accepts RFC 3339, include a time zone, such as 2026-10-20T01:00:00Z.

The exact UI names depend on your monitoring tool. A custom checker can apply the same conditions. The important part is to require all three, rather than relying on a successful HTTP response alone.

Verify complete, empty and stale responses

These reproducible examples use a fixed evaluation time of 20 October 2026, 01:05 UTC. They are fixtures, not live measurements. Update timestamps relative to the time of your own test.

Case	status	imported_count	updated_at	Expected result
Complete	completed	142	1792458000	Pass: 142 ≥ 1; age 300 ≤ 900 seconds
Empty	completed	0	1792458000	Fail: 0 is below the required minimum of 1
Stale	completed	142	1792454400	Fail: age 3,900 exceeds 900 seconds

Also check the failure paths: a missing or wrong token should produce 401; malformed stored JSON should produce 503; and valid JSON containing "status":"failed" should fail your result rule even though reading it succeeds with HTTP 200.

Choose limits that fit the real schedule. A 15-minute maximum age is usually unsuitable for a daily full import. Allow its schedule and normal completion delay, or perform the check specifically after the expected completion time. Likewise, impose a minimum count only when zero would actually indicate a problem.

Separate starting work from observing it

Reading this status endpoint does not run an import. It observes the latest recorded outcome. That separation matters for a long-running process: the initial API call might only put work on a queue and return before the import begins.

For a local scheduled script, publish the status after the real outcome and have the monitor check it on an appropriate schedule. Another option is a completion heartbeat, with a deadline for the next expected signal. Whichever signal you choose, a previous successful run must eventually become too old to stand in for the next one.

Finally, test both detection and delivery. A failed fixture should be recorded as a failure and reach the alert destination you chose. A successful test message by itself verifies only that messages can be delivered.

References: PHP JSON decoding, constant-time string comparison with hash_equals, JSON Pointer, RFC 6901.