Health File¶

When the COSALETTE_HEALTH_FILE environment variable names a path, the app writes its heartbeat to that file and the health probes check it (ADR-083). This page is the contract between the writer and the probes. The native cosalette-health binary and the Python probes implement the same rules and share one set of test fixtures (ADR-087).

Format¶

The file is one JSON object, written atomically:

{
  "health_file_version": 1,
  "written_at": 1791100800.25,
  "interval": 60.0,
  "status": "online",
  "uptime_s": 3600.0,
  "devices": {
    "sensor": {"status": "ok"},
    "relay": {"status": "stale"}
  }
}

The probes ignore every other key, including the rest of the heartbeat payload. The file must be strict JSON: NaN, Infinity and numbers that overflow to infinity make it unreadable. Integers outside the signed/unsigned 64-bit range are represented as finite floating point values when possible, matching serde_json; values too large for a finite float make the file unreadable.

Checks¶

A probe reports the file unhealthy at the first of these that applies:

1. The file does not exist, cannot be read, or is not valid JSON.
2. The top-level value is not an object.
3. health_file_version is not an integer, or is a version the probe does not know. A newer writer therefore never passes an older probe.
4. written_at is missing or not a finite number.
5. The file is older than --max-age, which defaults to three times interval.
6. A device's status is listed in --fail-on (default: stale).

Otherwise the file is healthy.

Versioning¶

The current version is 1. Adding optional keys does not change the version, because probes ignore keys they do not know. A change that an older probe would misread, such as renaming written_at or changing its unit, needs a new major version and probes that accept it.

Probes¶

All of them exit 0 when healthy and 1 otherwise, including on usage errors. See Health Probe for the options and Health Checks for when to run a probe at all.