Sign inRegisterCheck connection

How to Document a Stale-Upload Checker

Reference notes for documenting a weather-station stale-upload checker: expected files, timeout meaning, and false positives such as ISP outage versus station down.

Back to Cumulus weather software guides

A stale-upload checker is a quality-control instrument, not a weather instrument. It does not measure temperature. It measures whether a published file is still being rewritten on the schedule the operator claimed. If the documentation of that checker is vague—“the site is down if it looks down”—the checker becomes a rumour generator. This page is the reference card for writing that documentation: expected files, what a timeout actually clocks, and how to record false positives. The engineering of a heartbeat loop belongs on /projects/checkserver, not here.

Historical context

Cumulus and Weather Display sites of the 2000s lived on FTP. The logger PC wrote realtime.txt or ClientRaw, uploaded it, and a PHP page on the host read the file for banners, gauges, and WAP decks. When the upload stopped, the public site often kept serving the last good image. Visitors saw a sunny afternoon that had ended six hours earlier. Community “checkserver” scripts existed to notice the stall: compare the file’s age with a threshold, then publish a status.

The historical TNET URL /projects.reference.checkserver sat in the reference cluster, beside the reference hub. Its job was to tell an operator how to describe such a checker so another person could interpret the status line. This preservation page keeps that job. It does not rehost a checker, and it does not publish TNET internals.

Expected files: write the contract, not “the weather page”

A checker that “pings the homepage” is checking HTML availability, which is a different failure than a stalled observation file. Document the object under test as a file contract.

Name and path. Record the remote filename the uploader actually writes: commonly Cumulus realtime.txt (optional, off by default), a custom extra file, Weather Display clientraw.txt, or a webcam JPEG if that is the heartbeat you mean. Do not write “the live data” without a path.

Minimum completeness. A zero-byte file, a truncated line, or a field count below the version you support is not a fresh observation. The Cumulus Wiki realtime.txt map shows why field count is version-sensitive: the classic layout ends near field 58; MX later added feels-like and weekly rain. A checker documented against “58 fields” will false-alarm on a longer MX line if it treats extra tokens as corruption, or it will miss truncation if it only tests filesize > 0.

Unit tokens and clocks inside the file. For Cumulus realtime.txt, fields 1–2 are date and time from the logger PC; fields 14–17 are unit strings. A reference should say whether the checker uses filesystem modification time, packet time, or both. Those two clocks disagree whenever FTP preserves an old mtime, the PC clock is wrong, or the host is in a different timezone than the logger.

What is not a heartbeat. Dayfiles and monthly logs can be legitimately hours old. Homemade realtime logs (/projects.realtimelog) are an append-only derived archive: stale append is not the same event as a stale overwrite of realtime.txt. Write those distinctions on the card.

What a timeout measures

“Timeout = 300 seconds” is not a meaning. A timeout is a comparison between two times. The documentation must name both.

| Timeout definition | What a breach actually claims | |---|---| | now - file mtime > T | The host copy has not been replaced recently | | now - packet timestamp > T | The logger’s declared observation time is old | | HTTP request to the file exceeds T | The host or network did not answer; the file age is unknown | | No successful FTP in T (if you log transfers) | The uploader did not complete; the public file may still be the previous good copy |

Those four claims are not interchangeable. An ISP outage can trip HTTP while the logger still samples locally. Empty uploads can keep mtime fresh while packet time stalls.

Tie T to the generation interval, not to a round number. Fine Offset / EasyWeather-class stations update on the order of 48 seconds; the Cumulus Wiki warns that a faster “real-time” interval is mostly cosmetic. A 30-second timeout against a 48-second instrument is a false-positive machine. A 15-minute timeout against a 10-second upload cannot see a stall until the observation is already unusable as “current.”

Separate freshness from existence. HTTP 404, empty body, and “body older than T” are three statuses. A reference that collapses them to a red icon teaches operators to reboot the wrong box.

False positives: ISP outage versus station down

The scientific cost of a checker is not missed outages. It is mislabeled outages. Document a differential diagnosis in the same vocabulary the status page will use.

Station down (logger or sensors). The PC is off, Cumulus/MX is not running, or a Fine Offset-class “sensor contact lost” flag is set in the packet (classic realtime.txt field 51). Packet time stops advancing even if you could still fetch yesterday’s file. A webcam that still returns 200 does not refute this; it is a different instrument.

Uploader down, station up. The logger writes locally; FTP or copy to the host fails (credentials, quota, TLS, path). Local realtime.txt is fresh; the public copy is stale. A checker that only sees the host will report “station down.” The card should forbid that sentence unless the logger was observed.

Host or ISP outage. The observation PC may be fine. DNS, residential upload, or the shared host is not. HTTP timeouts and connection errors are network evidence. They are not a thermometer failure. If the operator’s own uplink is the object of interest—as it is for later connection research—the honest label is “publication path failed,” not “weather station failed.”

Clock skew. Logger in local time, host in UTC, packet date parsed with the wrong separator (Cumulus date separators follow the Windows short-date setting). A checker that treats “future” packet time as invalid, or that compares naive local strings, will flap at midnight and at DST transitions. Document the timezone assumption.

Stale cache, not stale file. A PHP banner that sends Cache-Control with a long max-age, or a CDN in front of realtime.txt, can make a checker and a visitor disagree. The checker must state whether it requests the origin with cache bypass. Cache headers themselves are specified on the avatar and banner cards; here, only record that cache can fake freshness.

Vendor interval and bandwidth pauses. Operators who slow realtime FTP to save a capped uplink will trip a tight T. That is a configuration mismatch, not a storm. Document T beside the configured interval.

A status product that cannot distinguish these cases is useful as “do not trust the public number,” not as “the instruments failed.”

What the status line should be allowed to say

  • Allowed: “Public realtime.txt is older than T,” “HTTP fetch failed,” “field count below minimum,” “packet time older than T.”
  • Forbidden as automatic conclusions: “Davis station failed,” “power outage,” “ISP is down,” “it is not raining because the file is stale.”

A human may hypothesize power or ISP after more than one signal. The checker documents one signal. Mixing them in the default string is how an archive gets a fake climate gap—or a fake storm.

Practical checklist for the card

  1. List exact filenames and the station-software flavour that writes them.
  2. State which clock is compared, and the timezone of now.
  3. State T in seconds and the generation interval it was chosen against.
  4. Split statuses: missing, empty, incomplete, stale, fetch-failed.
  5. Record known false positives in a table, including Fine Offset interval and cache.
  6. Cite the vendor field map with a last-checked date.
  7. Point operators to /projects/checkserver for the running idea; keep this page as the definitions.
  8. Do not ship a ZIP or a copy of an old PHP checker from this site.

Modern relevance

MX JSON and HTTP interfaces still go stale. A research ingest that treats “last file time” as “last observation time” without reading the packet clock repeats the FTP-era error. Documenting the checker is documenting the quality-control rule: freshness is an evidence property, not a website mood.

TNET research bridge

How TNET treats source freshness and quality control for public weather and network records is data sources, quality controls, and methodology. That brief does not list checkserver thresholds, and this card does not describe TNET scoring.

Related pages: the reference hub, the Cumulus hub, and how the service works for observed versus modelled labels when a stale page is still showing a forecast widget.

Sources