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§
- Absolute
Path - An absolute path, normalized as the tracer reports touched paths.
- Access
Kinds - 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.
- File
Metadata - The metadata of a regular file at one moment, as a tracer notes it when a command first reads or runs the file.
- File
System - The file system that holds a working directory.
- First
Reads - 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
FileMetadataat that moment, in sorted path order. - Kernel
- The kernel that runs a command, as
unamereports it. - Machine
State - 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.
- NotAbsolute
Error - 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.
- Process
Tree - 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.
- Resource
Limit - One resource limit of a process, soft and hard.
- RunRequest
- One command for a
Tracerto run. - RunResult
- The result of a request that started.
- Stdio
Echo - Echoes live output to the terminal: standard error to standard error, and everything else to standard output.
Enums§
- Access
Kind - One way a command touched a path.
- Capture
Mode - How a command’s standard output and standard error are captured.
- Captured
Output - 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.
- Incomplete
Reason - Why a run was traced incompletely.
- Outcome
- How the calls that touched a path in one way ended.
- Output
Stream - 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.
- Trace
Error - A request that did not produce a
RunResult.
Traits§
- Echo
Sink - 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_namefor an error number that has no name, and its default answer for every number:errnoand the number, such aserrno 200.
Type Aliases§
- Extended
Attributes - The extended attributes of one path: each name with its value, as bytes, sorted by name.
- Kind
Outcomes - 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.