Observing a command

This page explains kizz execute, which runs any command under the tracer and reports what it touched.

Overview

kizz execute runs one program, traces its whole process tree, and writes an observation report to a file. It needs no kizz.md, no repository and no cache, and it never caches anything, so every run executes the program. The report says, for each path the program and its children used, how they used it and with what outcome. By default it is hierarchical, and lists each process with the programs it ran and the paths each program used; with --compact, it combines every process's observations into one set and lists no process. It is text unless --json is given.

kizz execute --output=report.txt -- make
kizz execute --compact --json --output=deps.json -- cargo build

What it is for

Running a command

kizz execute --output=<file> [--compact] [--json] -- <program> [arguments...]

Reading a hierarchical report

This report comes from a pipeline that sh runs, with PATH set to /usr/bin to keep it short:

PATH=/usr/bin kizz execute --output=report.txt -- sh -c 'cat notes.txt | wc -w'
kizz observation report, version 1, hierarchical
trace: complete
totals: commands 1, cached 0, processes 3, programs 3, paths 9, connections 0
paths by access: read 3, probe 5, list 0, write 0, exec 4, xattr 0

command 1: sh -c 'cat notes.txt | wc -w'
  program: /usr/bin/sh
  directory: /tmp/demo/hello
  outcome: exited with 0
  trace: complete
  process 1, pid 392913, exited with 0
    program /usr/bin/sh: sh -c 'cat notes.txt | wc -w'
      read:
        /etc/ld.so.cache: ok
        /lib/x86_64-linux-gnu/libc.so.6: ok
      probe:
        /etc/ld.so.preload: ENOENT
        /tmp/demo/hello: ok
        /usr/bin/cat: ok
        /usr/bin/sh: ok
        /usr/bin/wc: ok
      exec:
        /lib64/ld-linux-x86-64.so.2: ok
        /usr/bin/sh: ok
    process 2, pid 392915, child of process 1, exited with 0
      program /usr/bin/cat: cat notes.txt
        read:
          /etc/ld.so.cache: ok
          /lib/x86_64-linux-gnu/libc.so.6: ok
          /tmp/demo/hello/notes.txt: ok
        probe:
          /etc/ld.so.preload: ENOENT
        exec:
          /lib64/ld-linux-x86-64.so.2: ok
          /usr/bin/cat: ok
    process 3, pid 392916, child of process 1, exited with 0
      program /usr/bin/wc: wc -w
        read:
          /etc/ld.so.cache: ok
          /lib/x86_64-linux-gnu/libc.so.6: ok
        probe:
          /etc/ld.so.preload: ENOENT
        exec:
          /lib64/ld-linux-x86-64.so.2: ok
          /usr/bin/wc: ok

Here sh looked up cat and wc in PATH, and kizz itself looked up sh before starting it, which is attributed to sh's program. Each program's loader is an exec of the program that it started, and each program looked for /etc/ld.so.preload, which does not exist. A successful exec belongs to the program that it starts, and a failed one to the program that made the call.

Every observation is reported, /proc and /sys included; the ignore patterns and other rules of builds do not apply. A text report escapes each backslash and control character of its strings, such as a newline in a path, which reads \n. Paths and arguments that are not valid UTF-8 appear with each invalid sequence replaced by U+FFFD.

Reading a compact report

--compact combines the observations of every process into one set, after the commands, with each path once:

PATH=/usr/bin kizz execute --compact --output=compact.txt -- sh -c 'cat notes.txt | wc -w'
kizz observation report, version 1, compact
trace: complete
totals: commands 1, cached 0, processes 3, programs 3, paths 9, connections 0
paths by access: read 3, probe 5, list 0, write 0, exec 4, xattr 0

command 1: sh -c 'cat notes.txt | wc -w'
  program: /usr/bin/sh
  directory: /tmp/demo/hello
  outcome: exited with 0
  trace: complete

read:
  /etc/ld.so.cache: ok
  /lib/x86_64-linux-gnu/libc.so.6: ok
  /tmp/demo/hello/notes.txt: ok
probe:
  /etc/ld.so.preload: ENOENT
  /tmp/demo/hello: ok
  /usr/bin/cat: ok
  /usr/bin/sh: ok
  /usr/bin/wc: ok
exec:
  /lib64/ld-linux-x86-64.so.2: ok
  /usr/bin/cat: ok
  /usr/bin/sh: ok
  /usr/bin/wc: ok

A compact report lists no process, and its observations are exactly the combined observations of the hierarchical report. It suits dependency inventories and other tools that need to know only what the whole command touched.

Reading a JSON report

--json writes the same report as JSON, for scripts, analysis tools and AI agents. It names its format, kizz-execute, and its version, 1. A hierarchical report has each command's processes, and a compact one has the top-level observations and connections.

PATH=/usr/bin kizz execute --compact --json --output=report.json -- wc -w notes.txt
{
  "format": "kizz-execute",
  "version": 1,
  "mode": "compact",
  "complete": true,
  "totals": {
    "commands": 1,
    "cached": 0,
    "processes": 1,
    "programs": 1,
    "paths": 6,
    "connections": 0,
    "kinds": {
      "read": 3,
      "probe": 2,
      "list": 0,
      "write": 0,
      "exec": 2,
      "xattr": 0
    }
  },
  "commands": [
    {
      "argv": [
        "wc",
        "-w",
        "notes.txt"
      ],
      "program": "/usr/bin/wc",
      "cwd": "/tmp/demo/hello",
      "cached": false,
      "outcome": {
        "kind": "exited",
        "code": 0
      },
      "complete": true,
      "incomplete": []
    }
  ],
  "task_program": null,
  "observations": [
    {
      "path": "/etc/ld.so.cache",
      "access": {
        "read": [
          "ok"
        ]
      }
    },
    {
      "path": "/etc/ld.so.preload",
      "access": {
        "probe": [
          "ENOENT"
        ]
      }
    },
    {
      "path": "/lib/x86_64-linux-gnu/libc.so.6",
      "access": {
        "read": [
          "ok"
        ]
      }
    },
    {
      "path": "/lib64/ld-linux-x86-64.so.2",
      "access": {
        "exec": [
          "ok"
        ]
      }
    },
    {
      "path": "/tmp/demo/hello/notes.txt",
      "access": {
        "read": [
          "ok"
        ]
      }
    },
    {
      "path": "/usr/bin/wc",
      "access": {
        "probe": [
          "ok"
        ],
        "exec": [
          "ok"
        ]
      }
    }
  ],
  "connections": []
}

A new field may appear without a new version, but a field that changes its meaning or disappears raises the version. The report reference describes every field.

Outcomes and completeness

A command's outcome is one of these:

When kizz started no process, the command's tree holds one process without a process ID, and its program is the name that kizz looked up, with every location the lookup checked:

command 1: no-such-program
  program: not found
  directory: /tmp/demo/hello
  outcome: not found: program `no-such-program` was not found in PATH
  trace: complete
  process 1, not started
    program no-such-program: no-such-program
      probe:
        /usr/bin/no-such-program: ENOENT

A report says whether each command was traced completely, and lists every reason that one was not: a system call through a non-native interface, a call that kizz cannot follow, such as a mount, a system call that the tracer does not know, a tracer failure, or another reason the tracer gives. A report never claims a complete trace when the tracer said otherwise.

What kizz changes for the program

Kizz never restricts which paths the program may use, but it starts every command that it traces, in builds and kizz run as well, with these changes:

Terminals, signals and job control

The program keeps your terminal, and its signals and job control differ from a run without kizz in these ways:

The last limit comes from how the tracer attaches to the processes it starts, which the builds of kizz rely on too.

Exit statuses

What it does not do

kizz execute deliberately does not: