Skip to main content

Crate kizz_trace

Crate kizz_trace 

Source
Expand description

The kizz tracer interface.

The engine never starts a process itself and knows nothing about system calls. It describes one command in a RunRequest: the exact program, the argument vector, the exact environment, the absolute working directory, the stdin content, the capture mode, and whether output is echoed live. A Tracer runs the command and returns a RunResult: how the command ended, its raw captured output, every path its process tree touched with the combined AccessKinds for each path, the FirstReads of the run, the system calls of the run that the tracer does not know, the Connections of the run, and a report when the trace is incomplete.

The first reads hold, for each path whose first read or run of a regular file came before any write of that path in the run, the file’s FileMetadata at that moment. The engine compares them with the final state of each path, so a file that changed after the command read it, whether the command rewrote it or something else changed it while the command ran, keeps the result out of the cache.

A system call that the tracer does not know is not a reason for an incomplete trace: the tracer reports its number in RunResult::unknown_system_calls, and the engine decides whether such a run is cached.

A connection to an IPv4 or IPv6 address, or to a Unix socket by path or abstract name, is an input that the tracer cannot see: the tracer reports it in RunResult::connections, and the engine records it, warns about it and still caches the result.

A request can also ask, with RunRequest::tree, for the ProcessTree of the run, which the result then holds besides the combined accesses: each traced process, a thread group whose threads fold into it, with its number, its process ID, the number of the process that created it, the programs it ran and the status it ended with. Each Program holds what the tracer attributes to it: its Observations, each path with its access kinds and each kind with its Outcomes, ok, the name of an error such as ENOENT, or unknown, and its connections, unknown system calls and every reason that the trace is incomplete. The kinds of each path in the tree, combined over every program, are exactly that path’s kinds in the combined accesses. The request flag is off by default, and builds never set it, so a build’s tracer does no more work than before, and a failed start carries the tree in its TraceError only when it is set.

A request runs in one of two ways. A command of a build runs in a process group of its own, with pipes or /dev/null as its standard streams, so its output is captured and a terminal’s Ctrl-C reaches only kizz, which interrupts the command exactly once through Cancellation. A command that keeps the terminal, which a request asks for with RunRequest::terminal, as kizz execute does, uses the standard input, output and error of the process that runs the tracer, and stays in that process’s process group and session, so a terminal’s input and signals reach it as they would without kizz; nothing of its output is captured. In both ways the command starts with an empty signal mask and the default action for SIGPIPE, and every other disposition is inherited, so a signal that kizz ignores stays ignored in the command.

The caller can forward a termination Signal to a running request with Cancellation::forward, which the tracer delivers once: to the command’s first process while it lives, and afterwards to each live process of the tree. A signal sent to the whole process group of a command that keeps the terminal reaches it directly, and once more if the caller forwards it, since the caller cannot tell it from a signal sent to the caller alone.

A tracer may not keep a traced process stopped: the Linux tracer resumes a process that a stop signal stopped, because with PTRACE_TRACEME it cannot learn when SIGCONT would end the stop. A terminal’s Ctrl-Z therefore stops kizz itself, which keeps the default action of SIGTSTP, SIGTTIN and SIGTTOU, and each traced process then waits at its next traced system call or signal until kizz goes on; a stop signal sent to one traced process alone does not keep it stopped.

Through the same interface, the engine reads what the standard library cannot: the extended attributes of a path, with Tracer::extended_attributes, the MachineState that a command starts with, with Tracer::machine_state, and the name of an error number, with Tracer::error_name, whose default answer is errno and the number, unnamed_error.

Version 1 has one tracer, for Linux, in kizz_trace_linux; tests of the engine implement Tracer with a fake, which notes first reads with FirstReads::note_at as it reads or runs files, as the Linux tracer does, answers the attribute query from attributes that the test sets and the machine query with a state that the test scripts, and builds the tree of one process that a request asks for with ProcessTree::of_request. A fake whose run a test builds an observation report from builds the tree of each of its results with ProcessTree::of_run instead, which also puts the run’s reason, unknown system calls and connections on the one program, as the Linux tracer puts them on the program that made them, so the report says what the run reported. Nothing in the engine changes when the tracer does.

Structs§

AbsolutePath
An absolute path, normalized as the tracer reports touched paths.
AccessKinds
The combined access kinds of one path.
Accesses
Every path a command’s process tree touched, each with its combined access kinds, in sorted path order.
Cancellation
A shared handle that cancels a running request, or forwards signals to it.
Disk
The size and free space of the file system that holds a working directory, in bytes.
FileMetadata
The metadata of a regular file at one moment, as a tracer notes it when a command first reads or runs the file.
FileSystem
The file system that holds a working directory.
FirstReads
The first reads of a run: for each path whose first read or run of a regular file came before any write of that path in the run, the file’s FileMetadata at that moment, in sorted path order.
Kernel
The kernel that runs a command, as uname reports it.
MachineState
The machine and process state that a command inherits when it starts, in six parts. A part that could not be read is None.
Memory
The memory of the machine, in bytes.
NotAbsoluteError
The error for a path that must be absolute but is not.
Observations
The paths that a program touched, each with its access kinds and each kind with its outcomes, in sorted path order.
Process
One traced process: a thread group, whose threads fold into it.
ProcessTree
The processes of a run, in the order the tracer saw them start, each with its programs and their observations.
Program
One program that a traced process ran, with everything the tracer attributes to it.
ResourceLimit
One resource limit of a process, soft and hard.
RunRequest
One command for a Tracer to run.
RunResult
The result of a request that started.
StdioEcho
Echoes live output to the terminal: standard error to standard error, and everything else to standard output.

Enums§

AccessKind
One way a command touched a path.
CaptureMode
How a command’s standard output and standard error are captured.
CapturedOutput
A command’s raw captured output, exactly as the process wrote it.
Connection
A connection that a process of the run made to a service outside the trace, whose answer is an input that the tracer cannot see.
IncompleteReason
Why a run was traced incompletely.
Outcome
How the calls that touched a path in one way ended.
OutputStream
The stream a chunk of live output came from.
Signal
A termination signal that the caller can forward to a running request, with Cancellation::forward.
Termination
How a command ended.
TraceError
A request that did not produce a RunResult.

Traits§

EchoSink
Where live output goes when a request asks for echo.
Tracer
Runs and traces commands, and answers the platform queries of the core.

Functions§

unnamed_error
The answer of Tracer::error_name for an error number that has no name, and its default answer for every number: errno and the number, such as errno 200.

Type Aliases§

ExtendedAttributes
The extended attributes of one path: each name with its value, as bytes, sorted by name.
KindOutcomes
The access kinds of one observed path, each with its outcomes, in the order of AccessKind::ALL.
Outcomes
The outcomes of one access kind of one path, in the order of Outcome.