Skip to main content

Module observe

Module observe 

Source
Expand description

The state of every path a step touched, recorded when the step finishes.

observe turns the accesses a tracer reported into observations, recording the paths concurrently. Paths that an ignore pattern matches are left out and counted. Each other path gets the PathState that “Path states” specifies:

  • absent paths: PathState::Absent;
  • regular files: size, modification and change times in nanoseconds, inode, device, mode, and owner, plus a BLAKE3 hash of the content only when the file was read or run, hashed with several threads for large files, through the build’s FileStates, so a file is hashed once per build;
  • directories: mode, owner, and modification and change times, and when they were listed, also a hash of the entry names and types in the order the file system returned them, a hash of the same entries sorted, and the entries in that order when there are at most MAX_LISTED_NAMES; entry inode numbers are not recorded;
  • symbolic links: the target, plus the state of what the link points to;
  • devices, FIFOs, and sockets: type only.

A path whose extended attributes the step read or listed, the xattr kind, also records them with its state (see record_attributes): each name with a BLAKE3 hash of its value, sorted by name, for the path itself and, for a symbolic link, for what it points to. Kizz reads them only through the attribute query of the tracer interface, Tracer::extended_attributes, because the standard library cannot read them.

Paths under /proc and /sys are recorded as PathState::Untracked unless a track pattern matches them; a tracked one gets its state, with the content of a regular file read and hashed again whatever the access, never from the cache. A path that symbolic links lead into /proc or /sys, such as /dev/fd/3 or /dev/stdin, leaves only that final object untracked (see kernel_links): the links on the way stay ordinary dependencies, each recorded with its target, so retargeting, removing, or replacing one of them changes the step. A final link is recorded as PathState::Symlink with an untracked pointee, and every other link on the way is recorded as such a link too, as a probe.

changed_after_read compares the first-read metadata that the tracer noted with the recorded states, to find the files that changed during the run after the command first read them or ran them.

Structs§

HashCounter
Counts the files whose content was hashed, so tests can observe hashing.
Observed
The observations of one step.

Functions§

access_bits
The access kinds kinds as the store records them.
changed_after_read
The files that changed during a run after the command first read them or ran them, sorted by path: each path in first_reads whose recorded state in observations, following a final symbolic link, is not a regular file with the noted device, inode, size, modification and change times, mode, and owner. No file, another type, and an inaccessible path are changes too. Each says whether the command wrote the path, as its access kinds show.
is_kernel_path
Whether path is under /proc or /sys, or is one of them.
kernel_links
The symbolic links outside /proc and /sys, each with its target, that lead path into /proc or /sys, in the order a path lookup follows them; None when path does not reach /proc or /sys, and no links when it is under one of them already.
listing
The listing of entries, in the order given: the hash of their names and types in that order, the hash of the same entries sorted by name and type, and the entries in that order when there are at most MAX_LISTED_NAMES.
observe
Record the state of every path in accesses, concurrently on the worker pool of states, leaving out and counting the paths that ignore matches, and hashing the /proc and /sys paths that track matches. Hashes go through states, and the extended attributes of the paths whose attributes were read or listed come from the attribute query of tracer.
path_state
The state of path, which a step touched with kinds, without following a final symbolic link. A regular file is hashed when it was read or run, through the cache states, or when force_hash is set, read again without the cache.
reaches_kernel
Whether path is under /proc or /sys, or the symbolic links on the way to it lead there, as /dev/fd leads to /proc/self/fd and /dev/stdin to /proc/self/fd/0 (see kernel_links).
record_attributes
The extended attributes of path now, as a path whose attributes were read or listed records them, read through the attribute query of tracer: those of the path itself, without following a final symbolic link, and, when the path is a symbolic link, those of what it points to. Each list holds every name with a BLAKE3 hash of its value, sorted by name, or is None when the query fails, as it does when nothing is at the path; a file system without attributes has none.