--db PATH and --json options. --json changes the output format, not the evidence selection.
Start with the session
sessions lists sessions newest first, with status, scope, time, event count, and duration. inspect adds:
- Session ID, command, arguments as recorded, scope, status, and termination state.
- Kernel and collector provenance.
- Event counts by type.
- Collection and loss counters.
- Observed process summaries.
- The database path in use.
Find a session
List more than the default 50:Reconstruct process relationships
processes lists process instances derived from recorded events. Depending on the evidence, each row may include:
- Canonical process-instance ID.
- Canonical PID.
- Recorded executable and command line.
- Parent PID and parent instance when linkage is unambiguous.
- First and last observed times.
- Event count and whether an exit was observed.
- Unresolved identity or ancestry flags.
tree renders the hierarchy. It uses process-instance identity, not PID alone. Ambiguous PID-reuse matches are left unresolved, missing parents are marked, and cycles are reported rather than followed forever.
Read the event stream
events is the raw chronological event listing:
timeline is the investigation-oriented view. It supports more filters and a stable, paged order:
Accepted time forms:
- Integer nanoseconds since the Unix epoch.
- RFC3339 UTC such as
2026-11-10T12:34:56Zor with fractional seconds.
timestamp_ns ASC, monotonic_ns ASC, id ASC.
Follow filesystem attempts
dirfd, raw result, success or errno, and notes for relative or truncated paths.
Important interpretation:
- The path is the string passed to
openat, not a resolved absolute path. dirfd == -100meansAT_FDCWD; other values identify a directory descriptor.- Relative paths are preserved as recorded and cannot be resolved without the process working directory and descriptor state.
- Truncated paths are marked.
- An open attempt does not prove that file contents were read or written.
open,openat2, and other file syscalls are not captured.
Follow network attempts
- A
connectevent is an attempt, not an established session. - The tracepoint cannot distinguish TCP from UDP.
- Source metadata is often unavailable and is stored as
null. - A successful local connection still does not prove application-level establishment or data transfer.
Summarize evidence accounting
stats reports duration, process-instance count, event counts by type, collection counters, kernel ring-buffer loss, userspace drops, unresolved identity counts when available, and session termination state.
--verify adds a read-only verification assessment. Verification is never required to inspect counters.
Interpret the result
Absence of a row is never proof that activity did not occur.
Machine-readable output
Every inspection command supports--json. JSON output is valid UTF-8 and preserves nulls for unavailable values rather than inventing placeholders.