Expand description
Observation reports (“Observation reports”): what the commands of
kizz execute or kizz run touched, organized by process, for people and for
programs.
A Report is built once from CommandInputs, in the order the commands
ran, and an optional TaskProgramInput. Each command that ran brings the
ProcessTree of the tracer, the CommandOutcome and the observations of
its program lookup; a command that came from the cache brings only its outcome.
The model then:
- numbers the processes of every command from 1, across the commands, so a number is unique in the report, and maps each parent to its new number;
- puts the lookup’s observations into the first program of the command’s first process, or, when kizz started no process, into a placeholder process without a process ID or status, whose program is the name that kizz looked up;
- lists every reason that a command was traced incompletely, with its process: each reason of a program, each unknown system call, and a tracer failure;
- combines every observation and connection of the report, the task program’s
included, and counts the
Totals.
Processes keep their start order, sorted by the tracer’s numbers, programs their order, reasons are sorted, and observations and connections are sets, so the renderings do not depend on the order in which the model receives them.
Report::render writes the report as text or JSON (ReportFormat), each
hierarchical or compact (ReportMode), from the same model. JSON_FIELDS
lists every field of the JSON format by its path, with the modes that hold it.
Paths and arguments that are not valid UTF-8 appear with each invalid sequence
replaced by U+FFFD, in both formats. Text then escapes each backslash and
control character of every string that it shows (escape_text), so no string
breaks its line and two different strings never read alike; JSON keeps its
standard escaping.
Structs§
- Command
Input - One command, as the report receives it.
- Json
Field - One field of the JSON format, by its path, with the modes that hold it.
- Reason
- One reason that a command was traced incompletely.
- Report
- An observation report: its commands in the order they ran, the task program, every observation and connection combined, and the totals.
- Report
Command - One command of the report.
- Report
Process - One process of a command in the report.
- Report
Program - One program of a process in the report.
- Report
Task Program - The task program of a report.
- Task
Program Input - The task program’s own accesses, as the report of
kizz runreceives them. - Totals
- The totals of a report.
Enums§
- Command
Outcome - How a command ended, or why it did not run.
- Execution
- What happened to one command of a report.
- Reason
Kind - The kind of a reason that a command was traced incompletely, in the order the report sorts them.
- Report
Format - Whether a report is written for people or for programs.
- Report
Mode - Whether a report keeps the process hierarchy or combines it.
Constants§
- FORMAT
- The name of the JSON format, its
formatfield. - JSON_
FIELDS - Every field of the JSON format, by its path, in the order the report writes the members of each object (“Observation report fields”).
- VERSION
- The version of the JSON format, its
versionfield.
Functions§
- escape_
text textas a text report shows it: a backslash as\\, a newline as\n, a tab as\t, a carriage return as\r, every other control character, U+0000 through U+001F and U+007F through U+009F, and the separators U+2028 and U+2029 as\u{, the code in lowercase hexadecimal without leading zeros, and}, aschar::escape_unicodewrites it, and every other character as it is.