valis / Reference / API reference
Node health - API reference
Exported surface for the node-health subsystem. Part of the API reference.
Package valis/src/node-health
Classes
node-health-expectations
What the node served when it reported ready. EDGE-ADAPTERS holds (name system ports) for each edge adapter a module admission owns, PORTS NIL when it had none bound. ACTIVE-PARTS holds (name system spec handle) for each started active part a module admission owns. DNS-PORTS lists the ports live :53 serve loops claimed. DNS-SYSTEM is the system of the one module holding a DNS adapter registration, or NIL when none or more than one did.
node-health-report
One assessment. PASSED-P is true when no check failed. CHECKS is a list of plists, one per check, in a fixed order: :check names its kind (:fabric, :edge-adapter, :active-module or :dns-serve), :subject what it looked at, :system the module system it belongs to or NIL, :status the result, and :detail a short reason. :passed means the registries show the subject still served; :failed means they show it no longer served; :not-assessed means the registries cannot answer for it, and it counts neither way; :not-applicable means there was nothing to check. Every check reads registries only; none opens a connection.
Functions
assess-boot
(assess-boot &key expectations fabric-serving-p (settle-seconds +boot-settle-seconds+) (check-seconds +boot-settle-check-seconds+) (sleep (function sleep)) (assess (function assess-node-health)) end-boot on-pass (stopping-p (constantly nil)))
Judge this boot by its health gate once SETTLE-SECONDS have passed, calling SLEEP to wait. ASSESS is called with EXPECTATIONS and :fabric-serving-p FABRIC-SERVING-P and returns a node-health-report.
Every CHECK-SECONDS inside the settle, ASSESS runs without counting: the module its report blames, or NIL, is recorded as the boot's suspect, so a death before the verdict is counted against that module by the next boot. The check made once the settle has passed counts. A pass logs module.boot-gate-passed, clears the module boot record, and then calls ON-PASS, a function of no arguments, when given; a condition ON-PASS signals is logged and the pass stands. A failure logs module.boot-gate-failed, counts one failed boot against the one module the report blames, or as unattributed, and calls END-BOOT with exit-transient. A condition from ASSESS in the counted check is a failure with no module to blame. STOPPING-P, a function of no arguments, answers true once an orderly stop of the node has begun; a counted check that fails then is logged and counts nothing, and END-BOOT is not called. Returns the counted report, or NIL when ASSESS signalled.
assess-node-health
(assess-node-health expectations &key fabric-serving-p)
Assess the node against EXPECTATIONS, what capture-node-health-expectations saw at readiness, and return a node-health-report. FABRIC-SERVING-P is a function of no arguments answering whether the fabric serves; without it the fabric check reads :not-assessed. Opens no connection. A check that cannot be assessed reads :not-assessed and never counts as passed or failed.
capture-node-health-expectations
(capture-node-health-expectations)
Return a node-health-expectations naming what the node serves now: the edge adapters module admissions own and the ports each has bound, the started active parts module admissions own, the ports live :53 serve loops claim, and the one module holding a DNS adapter registration. Call it when the node reports ready.
node-health-blamed-system
(node-health-blamed-system report)
The module system every failed check of REPORT names, or NIL when none failed, when one names no module, or when two name different modules.
node-health-report-checks
(node-health-report-checks instance)
Undocumented: this exported symbol needs a docstring.
node-health-report-passed-p
(node-health-report-passed-p instance)
Undocumented: this exported symbol needs a docstring.
Constants
+boot-settle-check-seconds+
Seconds between the uncounted checks inside the boot settle. Well inside the unit's 30 second watchdog. A check that runs and names one module records it as the suspect; a hang no check saw before the watchdog ends the process stays unattributed.
+boot-settle-seconds+
Seconds a boot runs after it reports ready before its health gate counts. The default boot settle: only a check made once it has passed counts.