valis / Reference / API reference
Logging - API reference
Exported surface for the logging subsystem. Part of the API reference.
Package valis/src/logging
Classes
substrate-json-appender
A log4cl appender that emits the current substrate event as a single jzon object per line, never the free-form log message.
Conditions
unknown-substrate-event
Signalled when log-event is handed an event name not in the taxonomy. Fail closed rather than emit an event at an unknown level.
Functions
log-event
(log-event event subsystem &rest fields)
Log a substrate lifecycle EVENT for SUBSYSTEM, with optional scalar event-specific FIELDS as a keyword plist (e.g. :days-to-expiry 3). The level is resolved from substrate-event-catalog; an unknown event signals unknown-substrate-event. Emits exactly one jzon object per line to substrate-log-stream. Returns the event object (for inspection/testing).
There is no message parameter: substrate facts only, never content.
log-event-at
(log-event-at level event subsystem &rest fields)
Log EVENT for SUBSYSTEM with FIELDS as log-event does, at LEVEL (:info, :warn, or :error) in place of the catalog's level. LEVEL may raise the catalog's level and never lower it: a level below it signals an error, as does a LEVEL outside those three. An unknown EVENT signals unknown-substrate-event. Returns the event object.
Variables
*substrate-event-catalog*
The substrate event vocabulary: each lifecycle event name mapped to the level it is logged at. This is the shared taxonomy downstream lifecycle wiring consumes rather than re-deriving. Later modules extend it by adding entries here.
*substrate-log-stream*
The stream substrate event lines are written to. Defaults to error-output so a systemd-supervised resident's lines land in journald. Tests bind it to a captured string stream to stay hermetic.
Constants
+event-acme-renewal-failed+
Undocumented: this exported symbol needs a docstring.
+event-backup-kdf-cost-overridden+
backup.kdf-cost-overridden, logged at WARN whenever a backup is sealed at a key-derivation cost other than mercer's production cost, lower or higher. Names the argon2id block count and pass count used, so a backup sealed at anything but the production cost never passes unnoticed.
+event-backup-written+
Undocumented: this exported symbol needs a docstring.
+event-boot-composition+
Undocumented: this exported symbol needs a docstring.
+event-boot-fault-recorded+
boot.fault-recorded, logged at INFO when a supervised run that is ending on a condition no handler took has written its boot fault record to the data root. Names the condition's type (condition) and the bring-up step running when it was signalled (rung). Never the condition's report.
+event-cert-custody-held-inconsistent+
cert.custody-held-inconsistent, logged at WARN once while custody holds a chain and key for a name that do not belong together, as between the two writes of a renewal; the leg keeps presenting the leaf in force for that name. Names the leg, the name and the fingerprint kept. Logged again only after the pair has read consistent or the name has left custody.
+event-cert-custody-unreadable+
Undocumented: this exported symbol needs a docstring.
+event-cert-custody-watch-failed+
cert.custody-watch-failed, logged at ERROR when the custody watch cannot be started, so a certificate changed in custody is no longer picked up without a restart or an explicit reload. Names the condition type.
+event-cert-custody-watch-reset+
cert.custody-watch-reset, logged at INFO when the custody watch is established or re-established and all of custody re-read. Names the cause: start when the watch starts; overflow for an event queue overflow; unmount when the store's file system is unmounted; ignored when the watch on the store root or domains/ is dropped; moved when the store root or domains/ is moved away; or the cause passed to note-custody-watch-doubt.
+event-cert-edge-dark+
cert.edge-dark, logged at WARN once when the :443 base certificate (edge.domain) is removed from custody or expires, so every :443 handshake is refused until custody holds a usable one again. Names the base domain and the reason (removed or expired).
+event-cert-expiry-imminent+
Undocumented: this exported symbol needs a docstring.
+event-cert-issued+
Undocumented: this exported symbol needs a docstring.
+event-cert-load-failed-dark+
Undocumented: this exported symbol needs a docstring.
+event-cert-presented-changed+
cert.presented-changed, logged at INFO once for each name whose certificate a leg presents changed after a re-read of custody. Names the leg (443 or 25), the name, the old and new leaf fingerprints, and the reason (replaced, removed, expired or added). Never key or certificate bytes.
+event-cert-renewed+
Undocumented: this exported symbol needs a docstring.
+event-config-allowance-refused+
config.allowance-refused, logged at WARN once for each distinct address-range allowance the node reads and refuses, whether from the store or the environment, so the allowance reads as none. Names the key and why it was refused. Never a value.
+event-config-environment-superseded+
config.environment-superseded, logged at WARN. Names, by key path and never by value, every key whose environment value the configuration store overrides.
+event-config-held-in-environment+
config.held-in-environment, logged at INFO on every boot whose environment value for a key carries a secret, which therefore stays out of the store. Names the key.
+event-config-rebind-failed+
config.rebind-failed, logged at WARN. Names a key and the type of the condition its rebinding signalled, after the key's new value was stored; the value takes effect at the next restart. Never a value.
+event-config-seed-refused+
config.seed-refused, logged at WARN. Names a key and its type when the environment value offered for it is not of that type and was not stored.
+event-delivery-applied+
Undocumented: this exported symbol needs a docstring.
+event-development-listener-closed+
development-listener.closed, logged at WARN each time the development listener closes. Names the route that closed it (route: shutdown, host, owner, config, recovery), who asked (actor), the socket path it was bound at (socket), and how many seconds it was open (openseconds).
+event-development-listener-notice-delivered+
development-listener.notice-delivered, logged at INFO when the notice that the development listener opened has been delivered into the owner's Maildir by one pass of local delivery, run because no standing delivery loop was running. Names the Maildir entry (entry: inbox/<owner DID>/new/<name>).
+event-development-listener-notice-failed+
development-listener.notice-failed, logged at WARN when landing or delivering the notice that the development listener opened failed. The listener stays open. Names the reason (reason: the class of the condition signalled, or not-delivered when local delivery left the notice queued).
+event-development-listener-notice-landed+
development-listener.notice-landed, logged at INFO when the notice that the development listener opened has been landed on the node's mail queue for the owner. Names the queue entry (entry) and the local recipient (recipient).
+event-development-listener-notice-skipped+
development-listener.notice-skipped, logged at WARN when the development listener opened but no notice could be landed for the owner. The listener is unaffected. Names the reason (reason: no-mail-store when the node has no durable mail store up, no-local-domain when mail.local-domains names no domain).
+event-development-listener-opened+
development-listener.opened, logged at WARN each time the development listener opens. Names the route that opened it (route: boot, host, owner, config, recovery), who asked (actor), and the socket path it is bound at (socket).
+event-development-listener-persist-failed+
development-listener.persist-failed, logged at WARN when an open or close of the development listener stands but development.listener could not be written, so the switch will not survive a restart as it is. Names the route (route), the switch being written (switch: on, off), and the class of the store condition (reason).
+event-development-listener-refused+
Undocumented: this exported symbol needs a docstring.
+event-development-listener-request-refused+
development-listener.request-refused, logged at WARN when the resident finds a development request in the runtime root that it will not read: not a regular file, owned by an account other than its own or root, linked more than once, or not openable. The file is left in place and logged once for each inode and modification time. Names the file (file) and the reason class (reason: not-regular-file, owner, links, unopenable), never the file's content.
+event-development-listener-retired-port-stored+
development-listener.retired-port-stored, logged at WARN once per boot when the node's store holds a value for the retired development.listener-port. The value opens nothing. Names the stored port (port) and its origin (origin: operator or seeded).
+event-development-listener-stale-socket-removed+
development-listener.stale-socket-removed, logged at WARN when the development listener, opening, finds a socket owned by the run account at its path, left by a process that never closed it, and removes it before binding. Names the socket path (socket).
+event-development-listener-started+
Undocumented: this exported symbol needs a docstring.
+event-development-listener-still-open+
development-listener.still-open, logged at WARN once every reminder interval while the development listener is open, and never while it is closed. Names the route that opened it (route), who asked (actor), the socket path (socket), when it opened (since, UTC), and how many seconds it has been open (openseconds).
+event-edge-443-dark+
Undocumented: this exported symbol needs a docstring.
+event-edge-443-up+
Undocumented: this exported symbol needs a docstring.
+event-fence-seeded+
Undocumented: this exported symbol needs a docstring.
+event-identity-key-enrolled+
identity.key.enrolled, logged at INFO once for each device key enrolled on the owner keyring. Names the key's Ed25519 did:key, its label, and the DID that enrolled it. Never key octets.
+event-identity-key-retired+
identity.key.retired, logged at INFO once for each device key retired from the owner keyring. Names the key's Ed25519 did:key and the DID that retired it. Never key octets.
+event-mail-delivered+
mail.delivered, logged at INFO once for each message written into an owner's Maildir, by the delivery loop or, on a node without the queue, by the direct write. Names the file written (entry), as inbox/<did>/new/<entry name>. Never the recipient, the sender, the subject or any byte of the message.
+event-mail-delivery-held+
mail.delivery-held, logged at WARN when a local delivery signals, or a whole delivery cycle does, and again only when the condition's type changes. Names the queue entry, or cycle for a whole cycle (entry), and the condition's type (conditiontype). Never the condition's report text, the recipient, the subject or any byte of the message.
+event-mail-delivery-loop+
mail.delivery-loop, logged at INFO when the standing delivery loop starts or stops, or when the node does not start it. Names the state (started, stopped or skipped) and, when skipped, the reason: no-mail-store, no-operator-state or loop-still-running.
+event-mail-relay-bounced+
mail.relay-bounced, logged at WARN once for each message you sent that the node records as bounced, since no notice goes back to you by mail. Names the queue entry, the recipient's domain, and the reason: exchangers-refused (every exchanger is at an address the node refuses to dial), null-mx (the domain accepts no mail), domain-unresolvable (the domain does not exist or names no exchanger), or exchanger-rejected (an exchanger refused the message permanently). Never the recipient's address and never the message.
+event-module-binary-generation-skipped+
module.binary-generation-skipped, logged at WARN when a release trial passes its boot health gate while the image runs a tentative generation of the module set, so no generation with cause binary is recorded. The release promotion stands and the stamp keeps reading differs until a later passed trial. Names the running tentative generation (running).
+event-module-binary-stamp-mismatch+
module.binary-stamp-mismatch, logged at WARN when a boot stands up a generation of the module set stamped by a binary other than the running one. The boot stands every module up as it would otherwise and selects no other generation. Names the generation's number, its version and commit (generationversion, generationcommit), and the running binary's (imageversion, imagecommit).
+event-module-boot-died-in+
module.boot-died-in, logged at ERROR when a boot finds that the boot before it died while standing up one recorded module. Names the system, the phase (load or start), the number of boots running that died in it, and its module designation when known.
+event-module-boot-floor+
module.boot-floor, logged at ERROR when a boot stands up only the resident set because boots running failed with no module to blame. Names the count of those boots and how many recorded modules are not running.
+event-module-boot-gate-failed+
module.boot-gate-failed, logged at ERROR when a boot's health gate fails once the boot has settled after reporting ready, or cannot be assessed, so the failure is counted and the node exits for a retry. Names the module system blamed, when one module is, the number of failed checks, and the condition type when the assessment signalled. Never a path.
+event-module-boot-gate-passed+
module.boot-gate-passed, logged at INFO when a boot's health gate passes once the boot has settled after reporting ready, so the boot counts as stood up and every count in the module boot record is cleared. Names the number of checks made. Never a path.
+event-module-boot-left-out+
module.boot-left-out, logged at ERROR when a boot leaves a recorded module out without loading any of it, because boots running died while standing it up. Names the system, the count, the phase, and its module designation when known.
+event-module-boot-record-unreadable+
module.boot-record-unreadable, logged at ERROR when the module boot record does not parse or does not match its digest, so the boot stands up only the resident set and starts a fresh record. Names why, and may quote the line or token that did not parse; never the path.
+event-module-boot-record-unwritable+
module.boot-record-unwritable, logged at ERROR when a write of the module boot record fails. The boot goes on and the disk keeps the last record written, so when an :end write fails after its :begin write succeeded, a later death is blamed on that module. Names the condition type, never the path.
+event-module-boot-stopped-before-verdict+
module.boot-stopped-before-verdict, logged at INFO when a boot finds that the boot before it was stopped in order, by SIGTERM or SIGINT, after reporting ready and before its health gate's verdict, so nothing is counted for it. Names nothing else.
+event-module-degraded+
module.degraded, logged at ERROR once when two consecutive passes of the health loop fail a health check, meaning the node no longer serves something it served. Names each failed check as its kind and subject, and how many checks failed. Logged again only after a pass that finds every check passing has ended the episode. Never a path.
+event-module-disable-refused+
module.disable-refused, logged at WARN when the owner's disable of a module is refused. Names the kind: not-a-designation, tentative, rejected, not-carried, retire-incomplete, change-in-progress, or fenced. Never the request's text and never a path.
+event-module-disabled+
module.disabled, logged at INFO when the owner disables a running module: every part the node can still attribute to one of its admissions is out of service, and its code stays in the image until the next restart. Names the system, its module designation, how many admissions were retired (retired), which is 0 when the node could attribute nothing to the module, whether its record is still in the durable module manifest (recorded yes or no), and how many of its threads were left running. Never a path.
+event-module-generation-blessed+
module.generation-blessed, logged at INFO when a tentative generation of the module set is made permanent by a bless, moving the boot default to it. Names the generation's number.
+event-module-generation-promoted+
module.generation-promoted, logged at INFO when the running tentative generation of the module set has passed every health check for a whole health window and is made permanent, moving the boot default to it. Names the generation's number and the window in seconds.
+event-module-generation-recorded+
module.generation-recorded, logged at INFO when a change to the module set is recorded as a generation in the store's lifetime record. Names the generation's number, its cause (install, supersede, disable, jailed, or rollback), and its status (tentative or permanent). Never a path.
+event-module-generation-rejected+
module.generation-rejected, logged at INFO when the owner rejects a tentative generation of the module set, so it is never made permanent. Names the generation's number and whether the image runs it (running yes or no); when it does, a restart stands up the boot default.
+event-module-jailed+
module.jailed, logged at ERROR when module bytes are moved to the module jail under the module source root. Names the kind (refused-landing, backed-out or failed-boots), the module designation when known, and the system when known. Never a path.
+event-module-parole-refused+
module.parole-refused, logged at WARN when the owner's parole of a jailed module is refused and nothing moved. Names the kind: not-a-designation, no-source-root, fenced, change-in-progress, jail-unreadable, not-jailed, bytes-gone, already-present, still-recorded, manifest-unreadable, not-the-identity, or move-failed. Never the request's text and never a path.
+event-module-paroled+
module.paroled, logged at WARN when the owner paroles a jailed module: its bytes are back in their identity directory under the module source root, and nothing of it is loaded or recorded. Names the kind of jailing it was paroled from (refused-landing, backed-out, or failed-boots) and the module designation. Never a path.
+event-module-recovered+
module.recovered, logged at INFO when a pass of the health loop passes every check after the node was reported degraded, ending the episode. Names how many consecutive passes had failed.
+event-module-repair-requested+
module.repair-requested, logged at WARN when a repair is requested: whatever it rejected or cleared is on disk, and the node is about to be asked to restart into its boot default. A repair with nothing to reject or clear writes nothing and is logged the same way. Names who asked (requestedby: owner, or health-loop when module.restart-when-degraded is on), the running generation the repair rejected (rejected), when it was tentative, and the next-boot trial it cleared (trialcleared), when one was pending.
+event-module-retention-failed+
module.retention-failed, logged at ERROR when retention could not finish, for one of four causes. The lifetime record was not reduced, and nothing was published. The module source root was refused, so nothing was deleted. The manifests of the dropped or retained generations, or the module jail, could not be read, so nothing was deleted. An identity directory a dropped generation alone named was not deleted; the other directories are still tried. Names the module designation concerned (designation), when there is one, and the reason. Never a path.
+event-module-retention-pruned+
module.retention-pruned, logged at INFO when retention drops generations from the lifetime record: five generations and sixty days, whichever keeps more, besides the boot default, the running generation, the next-boot trial, and the most recent permanent generation. Names how many generations were dropped (dropped), how many identity directories were deleted (deleted), and the module designation of each one deleted (designations). Never a path.
+event-module-rollback-committed+
module.rollback-committed, logged at INFO when the owner's rollback is recorded: a new generation, cause rollback, standing up an earlier generation's module set, is the next-boot trial, and a restart is asked for when a restart function is set. Names the new generation's number, the generation it returns to (target), and the trial it replaced (replaced), when one was pending and not yet attempted.
+event-module-rollback-override+
module.rollback-override, logged at WARN once for each override a committed rollback used. Names the rollback generation's number and the override: withdrawn, naming each withdrawn version's module designation (designations), or downgrade, naming each module system whose newer data the older version does not declare it reads (systems). Never a path.
+event-module-settings-declared+
module.settings-declared, logged at INFO when a module that states settings in its define-module form registers them. Names the system its settings are kept under and how many keys it declares.
+event-module-settings-kept-aside+
module.settings-kept-aside, logged at WARN when the node keeps aside, in a module's settings file, values its owner set that the version of the module now loaded could not carry: no key takes them, the module's migration signalled, or a key's own check refused the value. Names the system, each key path set aside, and the condition type when the migration or a check signalled. Never a value.
+event-module-trial-failed+
module.trial-failed, logged at ERROR when a next-boot trial is ended as failed and the node stands up its boot default instead: its one boot died, was stopped in order before its health gate's verdict, failed its health gate, passed it without the trial being kept, met the resident-only floor, or could not read its module boot record. Names the trial's generation number, the boot default's, and the reason: died-in-module (with the module's system), stopped-before-verdict, died-unattributed, gate-failed, passed-unrecorded, boot-floor, boot-record-unreadable, or no-cause-recorded. Never a path.
+event-module-trial-passed+
module.trial-passed, logged at INFO when a boot that stood up a next-boot trial passes its health gate, so the trial is made permanent and the boot default and is no longer pending. Names the trial's generation number.
+event-operator-state-engage-failed+
Undocumented: this exported symbol needs a docstring.
+event-recovery-rung+
recovery.rung, logged once for each step of a recovery start's bring-up ladder: at INFO when the step came up, at WARN when a piece of it could not be started and recovery went on without it, and at ERROR when the step failed and the run ends. Names the step (rung: configuration, analysis, development-socket, control-session, mail, notice, readiness, stop), what came of it (outcome: started, degraded, failed, stopped), and the piece that could not be started (piece), or none.
+event-release-launch-refused+
release.launch-refused, logged at WARN when the launch facts on the resident's argv cannot be read, so the boot is taken as a default launch. Names the flag (flag) and the reason. Never a path.
+event-release-retention-pruned+
release.retention-pruned, logged at INFO when placed releases outside the kept set are removed. Names how many were removed (removed) and their identity hexes (releases). Never a path. The kept set:
- the default
- the previous default
- a pending trial
- the running release
- two further predecessors
+event-release-rollback-committed+
release.rollback-committed, logged at INFO when the owner's rollback has named a release this node ran, or base, the next boot's trial in the selection record, before any restart is asked for. Names the trial (release), the default left in place (default), and the trial it replaced (replaced), when one was pending. Never a path.
+event-release-rollback-override+
release.rollback-override, logged at WARN when a rollback is committed past the downgrade refusal because the owner overrode it. Names the trial (release), the refusal overridden (override, downgrade), the trial's store format or unknown (store-format), and the highest store format this node has run with (high-water). Never a path.
+event-release-trial-failed+
release.trial-failed, logged at ERROR at a boot whose host agent reports that a release trial ended before the boot health gate passed, and that it launched another binary. Names the failed trial (release), how its one boot ended as the host agent records it (end), and what this boot runs (launched). The end is exit:<n>, signal:<n>, or unconfirmed; a refusal that exits 78 counts as a failed end like any other exit. Never a path.
+event-release-trial-passed+
release.trial-passed, logged at INFO when a boot of a release trial passes its health gate and the selection record makes the release the default with no trial. Names the release (release) and the default it replaced (previous). Never a path.
+event-release-trial-recorded+
release.trial-recorded, logged at INFO when the owner's apply has placed a release and the selection record names it the next boot's trial, before any restart is asked for. Names the release's identity hex (release), the default left in place (default), and the trial it replaced (replaced), when one was pending. Never a path.
+event-resident-ready+
Undocumented: this exported symbol needs a docstring.
+event-restore-completed+
Undocumented: this exported symbol needs a docstring.
+event-transfer-refused+
Undocumented: this exported symbol needs a docstring.
+event-watchdog-degraded+
Undocumented: this exported symbol needs a docstring.