Observation

An observation records what a check found, where it ran and when it ran. It is separate from a declaration of what should be true.

What it is

A structurally valid registry does not prove that a consumer can reach a declared service. An observation supplies the measured result (stado-rs/src/observations/observation.rs):

Field	Meaning
fact	The checked fact, with a shared <kind>:<subject> name so readers and writers address the same subject.
vantage	The checking host's registry name. A result from one host does not prove another host can reach the same address.
state	The observed outcome, preserved as written rather than guessed from diagnostic wording.
detail	The operation's diagnostic detail, including the operating system's or provider's cause where available.
at	The observation timestamp in RFC 3339 UTC.

Reachability distinguishes an answer (observed), a failed probe (unreachable), and a probe that could not run (unverified). A missing helper, unavailable host channel or unsupported probe does not prove that the service itself is down.

Ownership checks can additionally report misowned when the endpoint's listener is not the declared program, or standby_serving when a declared standby is answering beside the active service. Both are failures rather than proof that the intended consumer route works. Unknown outcomes from newer writers remain intact.

Freshness

A reader gets the newest observation of a fact (Seen) or Never when no observation exists; Never is neither success nor an observed outage. No window decides when an observation stops counting: every column shows how long ago the look was taken (just now, 14m ago, 12d ago, or undated for a record whose timestamp will not parse), and a judgement that needs the present either asks again or compares the observation's content with what was declared since. The lookup chooses the newest dated observation across vantages; a caller asking about one specific host must filter for that vantage. A stored result is never turned into a new probe.

Who records it

The process that actually performs the check records the observation and its vantage. Writers include:

• stado service verify records probe findings, including unverified outcomes (stado-rs/src/cli/service_verify/verdicts/record.rs).
• stado release version show --host <target> persists software reports under software:<name>@<host>, with that target as the vantage (cli).
• stado service directory connect records whether its route answered. A failure to save the observation does not change a successful connection into a failed connection (stado-rs/src/cli/directory/routes/connect.rs).

Who reads it

• stado service directory show includes endpoint freshness, so an address is not presented without the age of its supporting observation (stado-rs/src/cli/directory/report/mod.rs).
• stado service list carries an observed column per row.
• stado release status reads the recorded software reports instead of opening an SSH connection per target. A target with no report, or a report whose programs, versions or digests disagree with what is declared now, makes it exit non-zero; the report's age is printed beside it (cli). A rollout target the fleet registry does not declare fails the same way, with the finding the rollout of <product> names target <target>, which the fleet registry does not declare, so what it should run cannot be judged.

Where it lives

~/.stado/observations.json is owner-only. The store writes a temporary file in the same directory and renames it into place, so readers do not see a partial document (stado-rs/src/observations/store.rs). Recording merges into the rows already on file; a file that exists and cannot be read, or is not a JSON array, is left as it is and the recording fails with its path and cause (the recording commands print it as a warning), instead of being replaced by the new rows alone.

Commands

stado service verify
stado service directory show
stado release version show --host example-host
stado release status

Flag-by-flag detail lives in the CLI reference.

Not to be confused with

• A declaration. The registry and directory describe desired state. An observation records what a check found. Operations compares the two.
• A host beacon. A beacon is the host's own publication about its units and disks. An observation may come from a different consumer host.
• A failed probe and an unavailable probe. unreachable and unverified require different repairs and are never collapsed into one result.