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.