gfpsgo: Fork of psgo, an IBM AIX-compatible ps(1) utility (and Go library) extended with various descriptors useful for displaying container-related data on Linux. https://github.com/johnsonjh/gfpsgo/
Jeffrey H. Johnson f2dae108d8 Merge pull request #83 from johnsonjh/renovate/golang.org-x-sys-digest | %!s(int64=2) %!d(string=hai) anos | |
---|---|---|
.github | %!s(int64=2) %!d(string=hai) anos | |
cmd | %!s(int64=3) %!d(string=hai) anos | |
internal | %!s(int64=3) %!d(string=hai) anos | |
test | %!s(int64=4) %!d(string=hai) anos | |
.deepsource.toml | %!s(int64=3) %!d(string=hai) anos | |
.gitignore | %!s(int64=4) %!d(string=hai) anos | |
.gitlab-ci.yml | %!s(int64=4) %!d(string=hai) anos | |
.whitesource | %!s(int64=3) %!d(string=hai) anos | |
LICENSE | %!s(int64=3) %!d(string=hai) anos | |
Makefile | %!s(int64=3) %!d(string=hai) anos | |
README.md | %!s(int64=3) %!d(string=hai) anos | |
SECURITY.md | %!s(int64=3) %!d(string=hai) anos | |
go.mod | %!s(int64=2) %!d(string=hai) anos | |
go.sum | %!s(int64=2) %!d(string=hai) anos | |
psgo.go | %!s(int64=3) %!d(string=hai) anos | |
psgo_test.go | %!s(int64=3) %!d(string=hai) anos | |
renovate.json | %!s(int64=3) %!d(string=hai) anos |
gfpsgo
is a ps
(1
) (AIX-format compatible) Go library and tool, extended
with various descriptors useful for displaying container-related data.
The idea behind the library is to provide an easy to use way of extracting
process-related data, just as ps
(1
) tool does. The problem with using
ps
(1
) is that the ps
output is formatted strings split into columns by
whitespace, which makes the output extremely impossible to automatically parse.
It also adds some jitter as we have to fork and execute ps
, either in the
container, or filter the output afterwards, which further limits usability.
This tool and library is intended to make things more comfortable, especially
for container runtimes. An API allows joining the mount namespace of a given
process, and will parse /proc
and /dev
filesystems automatically.
The API consists of the following functions:
gfpsgo.ProcessInfo(descriptors []string) ([][]string, error)
gfpsgo.DefaultDescriptors
are used. The return value contain string slices
of process data, one per process.gfpsgo.ProcessInfoByPids(pids []string, descriptors []string) ([][]string, error)
psgo.ProcessInfo
, but limits the return
value to a list of specified PIDs. The PIDs input must be a slice of PIDs
for which process information should be returned. If the input descriptor
slice is empty, only the format descriptor headers are returned.psgo.JoinNamespaceAndProcessInfo(pid string, descriptors []string) ([][]string, error)
/proc
data from a container without executing
any command inside the container.psgo.JoinNamespaceAndProcessInfoByPids(pids []string, descriptors []string) ([][]string, error)
gfpsgo.JoinNamespaceAndProcessInfo
but takes a slice of PIDs as an
argument. To avoid duplicate entries, such as when two or more containers
share the same PID namespace, a given PID namespace will be joined only
once.psgo.ListDescriptors() []string
We can use the gfpsgo
tool included with the project to test the core
components of the library. First, build gfpsgo
via make build
. The binary is
now located under ./bin/gfpsgo
. By default gfpsgo
displays data about all
running processes in the currently mount namespace, similar to the output of
ps -ef
.
$ ./bin/psgo | head -n 5
USER PID PPID %CPU ELAPSED TTY TIME COMMAND
root 1 0 0.064 6h3m27.677997443s ? 13.98s systemd
root 2 0 0.000 6h3m27.678380128s ? 20ms [kthreadd]
root 4 2 0.000 6h3m27.678701852s ? 0s [kworker/0:0H]
root 6 2 0.000 6h3m27.678999508s ? 0s [mm_percpu_wq]
You can use the --pids
flag to restrict gfpsgo
output to a subset of
processes. This option accepts a list of comma separate process IDs and returns
exactly the same kind of information, only per process, as the default output.
$ ./bin/psgo --pids 1,$(pgrep bash | tr '\n' ',')
USER PID PPID %CPU ELAPSED TTY TIME COMMAND
root 1 0 0.009 128h52m44.193475932s ? 40s systemd
root 20830 20827 0.000 105h2m44.19579679s pts/5 0s bash
root 25843 25840 0.000 102h56m4.196072027s pts/6 0s bash
Let's have a look at how we can use this tool and library in the context of
containers. As a simple show case, we'll start a Docker container, extract the
process ID via docker-inspect
and run the gfpsgo
binary to extract the data
of running processes within that container.
$ docker run -d alpine sleep 100
473c9a05d4223b88ef7f5a9ac11e3d21e9914e012338425cc1cef853fc6c32a2
$ docker inspect --format '{{.State.Pid}}' 473c9
5572
$ sudo ./bin/psgo -pids 5572 -join
USER PID PPID %CPU ELAPSED TTY TIME COMMAND
root 1 0 0.000 17.249905587s ? 0s sleep
The gfpsgo
library is compatible with all AIX-formatted descriptors provided
by the IBM AIX ps
(1
) command-line utility. (On any AIX system, execute
man 1 ps
for more details.) It also supports additional descriptors that can
be useful when seeking specific process-related information.
capamb
capbnd
capeff
capinh
capprm
hgroup
hpid
huser
label
seccomp
seccomp
(2
) for more information.state
proc
(5
) for more information.stime
We can try out different format descriptors with the gfpsgo
tool:
$ ./bin/gfpsgo -format "pid, user, group, seccomp" | head -n 5
PID USER GROUP SECCOMP
1 root root disabled
2 root root disabled
4 root root disabled
6 root root disabled