monitor.heartbeat-check
A heartbeat's state as a check status for a status page: up, late as degraded, down as down, new as nothing yet.
1.0.0 · published 2026-10-03 by charlie · Anterra
Pinned by 8 tests, run in TypeScript, Python and Rust.
What it does
A heartbeat (a cron job that pings the monitor on a schedule, judged by `monitor.heartbeat`) as one check behind a status page component, so the job can sit on the same page as the HTTP targets and feed `monitor.component-state`, `monitor.incidents` and `monitor.uptime`.
| heartbeat state | check status | why | | --- | --- | --- | | `up` | `up` | pinged within its period | | `late` | `degraded` | past due but inside the grace time: something is slow, nothing has failed yet | | `down` | `down` | past the grace time: the job has stopped | | `new` | null | it has never pinged, so there is nothing to report |
For example
heartbeat_check(up)→ up a heartbeat pinging on time is upheartbeat_check(late)→ degraded a late heartbeat is degraded, not down: it is still inside its grace timeheartbeat_check(down)→ down a heartbeat past its grace time is down
The function
The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.
def heartbeat_check(state: HeartbeatState) -> Optional[CheckStatus]| state | HeartbeatState | where the heartbeat stands, from monitor.heartbeat |
| returns | CheckStatus? | null for a heartbeat that has never pinged: there is nothing to report yet |
Your code names it in one line, in the file that uses it
from fune.monitor.heartbeat_check import heartbeat_check # monitor.heartbeat-check@^1Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.
from typing import Optional
from .monitor_check_status import CheckStatus ← from monitor.check-status ^1.0.0 · built alongside by fune
from .monitor_heartbeat import HeartbeatState ← from monitor.heartbeat ^1.0.0 · built alongside by fune
_STATUS = {"up": "up", "late": "degraded", "down": "down"}
def heartbeat_check(state: HeartbeatState) -> Optional[CheckStatus]:
"""A heartbeat as one check behind a status page component. Late is
degraded, not down: the job may still ping within its grace time, which is
what the grace time is for. A new heartbeat has proved nothing either way,
so it is null rather than a guess."""
if state == "new":
return None
if state not in _STATUS:
raise ValueError("unknown heartbeat state: %s" % (state,))
return _STATUS[state] # type: ignore[return-value]Install
fune buildWith that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:
fune add monitor.heartbeat-checkThe manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./monitor.heartbeat-check-1.0.0-python.fune, or fetch it from a terminal with fune pull monitor.heartbeat-check@1.0.0:python.
The whole function, every language, is one file too: monitor.heartbeat-check-1.0.0.fune, 6,589 bytes, sha256 ba92e30f23d19bb08606233144125bb805f847790f3973b11d15a465ee2381f9. It installs into a project of any language.
Customise it in your app
The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.
before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.
# fune: before monitor.heartbeat-checkafter — your function gets the result and the arguments, and returns the final result.
# fune: after monitor.heartbeat-checkreplace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.
# fune: replace monitor.check-status in monitor.heartbeat-check
# fune: replace monitor.heartbeat in monitor.heartbeat-checkstep — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show monitor.heartbeat-check --steps.
# fune: step monitor.heartbeat-check after <n|label>Tests
A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.
| Case | Arguments | Expected | |
|---|---|---|---|
| a heartbeat pinging on time is up | up | → | up |
| a late heartbeat is degraded, not down: it is still inside its grace time | late | → | degraded |
| a heartbeat past its grace time is down | down | → | down |
| a heartbeat that has never pinged has nothing to report | new | → | — |
| an unknown state is an error | missing | → | error: unknown heartbeat state: missing |
| states are case-sensitive | Up | → | error: unknown heartbeat state: Up |
| an empty state is an error | → | error: unknown heartbeat state: | |
| a check status is not a heartbeat state: degraded is refused | degraded | → | error: unknown heartbeat state: degraded |
More from the author
## Why this shape
- **Late is not down.** The grace time exists because jobs run long; calling a late job down would page for exactly the case the grace time was set to absorb. healthchecks.io, which named these states, only alerts on down. - **New is null, not up.** A heartbeat that has never pinged has proved nothing. Calling it up would show a never-deployed job as healthy on the status page; calling it down would page for a job that is not due yet. The caller leaves it out of the component's checks (and shows "awaiting first ping") until the first ping arrives.
## Errors
- `unknown heartbeat state: X`, for anything but `new`, `up`, `late` and `down` (case-sensitive; a `CheckStatus` such as `degraded` is refused).
## Sources
- healthchecks.io, "Configuring checks: period and grace time" (new, up, late, down; notifications only when a check goes down): https://healthchecks.io/docs/configuring_checks/
Files
| Path | Bytes |
|---|---|
| README.md | 1,600 |
| impl/python.py | 719 |
| impl/rust.rs | 845 |
| impl/typescript.ts | 820 |
| vectors.json | 877 |