Skip to main content

Module report

Module report 

Source
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§

CommandInput
One command, as the report receives it.
JsonField
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.
ReportCommand
One command of the report.
ReportProcess
One process of a command in the report.
ReportProgram
One program of a process in the report.
ReportTaskProgram
The task program of a report.
TaskProgramInput
The task program’s own accesses, as the report of kizz run receives them.
Totals
The totals of a report.

Enums§

CommandOutcome
How a command ended, or why it did not run.
Execution
What happened to one command of a report.
ReasonKind
The kind of a reason that a command was traced incompletely, in the order the report sorts them.
ReportFormat
Whether a report is written for people or for programs.
ReportMode
Whether a report keeps the process hierarchy or combines it.

Constants§

FORMAT
The name of the JSON format, its format field.
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 version field.

Functions§

escape_text
text as 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 }, as char::escape_unicode writes it, and every other character as it is.