quark-mon.8

.Dd $Mdocdate$
.Dt QUARK-MON 8
.Os
.Sh NAME
.Nm quark-mon
.Nd monitor and print quark events
.Sh SYNOPSIS
.Nm quark-mon
.Op Fl bDekSstv
.Op Fl C Ar filename
.Op Fl l Ar maxlength
.Op Fl m Ar maxnodes
.Op Fl P Ar ppid
.Nm quark-mon
.Fl h
.Nm quark-mon Fl V
.Sh DESCRIPTION
The
.Nm
program listens to all incoming
.Xr quark 7
events and prints them to stdout, the output format used is the one in
.Xr quark_event_dump 3 .
.Pp
The main utility is for testing and debugging quark, it's also a good
introduction to the code base.
.Nm
runs until a SIGINT is received.
.Pp
The options are as follows:
.Bl -tag -width Dtb
.It Fl b
Attempt EBPF as the backend.
.It Fl C Ar filename
Dumps the contents of the internal cache into
.Ar filename
after exit.
Format is a
.Em dot
file that can be compiled to a
.Em svg
with:
.Bd -literal -offset indent
dot -Tsvg filename -o filename.svg
.Ed
.It Fl D
Drop priviledges to nobody and chroot to /var/empty, useful to show how quark
can run without priviledges.
.It Fl e
Include
.Em proc_entry_leader
and
.Em proc_entry_type
in
.Em quark_events .
Entry leader is how the process entered the system, it is disabled by default as
it is Elastic/ECS specific.
.It Fl g
Use minimal aggregation, fork, exec and exit will
.Em not
be aggregated.
.It Fl h
Display this manpage.
.It Fl k
Attempt kprobe as the backend.
.It Fl l Ar maxlength
Maximum lenght of the quark queue, essentially how much quark is willing to
buffer, refer to
.Xr quark_queue_open 3
for further details.
.It Fl S
Enable socket events (experimental).
.It Fl s
Don't send the initial snapshot of existing processes.
.It Fl t
Don't supress thread events, this is only useful for debugging and will likely
be zapped in the future.
.It Fl v
Increase verbosity, can be specified multiple times for more verbosity.
.It Fl m Ar maxnodes
Don't really process events, just collect
.Ar maxnodes
in the sorting tree
and output
.Pa quark_by_time.dot
and
.Pa quark_by_pidtime.dot .
The first is events sorted by time, and the second by pid plus time.
Exits after
.Ar maxnodes
has been reached.
This is used purely for internal debugging.
.It Fl P Ar ppid
Display only events where parent pid is
.Ar ppid .
.It Fl V
Print version and exit.
.El
.Sh BACKEND SELECTION
If no backend option is specified,
.Nm
will attempt EBPF, and then kprobe if EBPF failed.
If only one of
.Fl b
or
.Fl k
is passed, then
.Nm
will be restricted to that option only.
.Sh EXIT STATUS
.Nm
exits with 0 in if a SIGINT was sent, or 1 in case of error.
.Sh EXAMPLES
Running:
.Dl $ quark-mon
.Pp
outputs:
.Bd -literal
->1607007 (FORK+EXEC+EXIT)
  COMM  comm=locale
  CMDL  cmdline=[ locale, charmap ]
  PROC  ppid=1607003
  PROC  uid=1000 gid=1000 suid=1000 sgid=1000 euid=1000 egid=1000
  PROC  cap_inheritable=0x0 cap_permitted=0x0 cap_effective=0x0
  PROC  cap_bset=0x1ffffffffff cap_ambient=0x0
  PROC  time_boot=1713340073284870415
  CWD   cwd=/d/e/quark
  FILE  filename=/usr/bin/locale
  EXIT  exit_code=0 exit_time=434523672438062
->1607008 (FORK+EXEC+EXIT)
  COMM  comm=groff
  CMDL  cmdline=[ groff, -mtty-char, -Tutf8, -mandoc, -rLL=109n, -rLT=109n, -P-c ]
  PROC  ppid=1607003
  PROC  uid=1000 gid=1000 suid=1000 sgid=1000 euid=1000 egid=1000
  PROC  cap_inheritable=0x0 cap_permitted=0x0 cap_effective=0x0
  PROC  cap_bset=0x1ffffffffff cap_ambient=0x0
  PROC  time_boot=1713340073288110375
  CWD   cwd=/d/e/quark
  FILE  filename=/usr/bin/groff
  EXIT  exit_code=0 exit_time=434523688177774
  ...
.Ed
.Pp
Refer to
.Xr quark_event_dump 3
for the output format description.
.Sh SEE ALSO
.Xr quark_event_dump 3 ,
.Xr quark_process_lookup 3 ,
.Xr quark_queue_block 3 ,
.Xr quark_queue_close 3 ,
.Xr quark_queue_get_epollfd 3 ,
.Xr quark_queue_get_event 3 ,
.Xr quark_queue_get_stats 3 ,
.Xr quark_queue_open 3 ,
.Xr quark-btf 8 ,
.Xr quark-test 8