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 a4bc04e274 Update dependencies 22 hours ago
.github b78959ba7e Update codacy/codacy-analysis-cli-action action to v3.0.3 1 month ago
cmd 8537b241a1 Update dependenices, fixup order and module path. 3 months ago
internal 45fe74403e Update dependencies 1 month ago
test 94652f5e1c Overhaul Make deps, BATS testing, etc. 5 months ago
.deepsource.toml 8d936c0c95 Update dependencies, fix deepsource scanning 2 months ago
.gitignore f844c3ad5d Update .gitignore 5 months ago
.gitlab-ci.yml 898b10272b CI/CD: Simplify build 5 months ago
.whitesource 8dbb6f8ad5 Add .whitesource configuration file 3 months ago
LICENSE 7025b7c66b Update licensing, documentation, reporting info. 4 months ago
Makefile e95c59ec5f multi: use github for imports, etc. 3 months ago
README.md 71a7bc4dc1 Update README.md 1 month ago
SECURITY.md 17e8ac9f0c Format code with black, gofmt, yapf, autopep8, isort, standardrb, standardjs, prettier and rubocop 2 months ago
go.mod a4bc04e274 Update dependencies 22 hours ago
go.sum a4bc04e274 Update dependencies 22 hours ago
psgo.go 8537b241a1 Update dependenices, fixup order and module path. 3 months ago
psgo_test.go 8537b241a1 Update dependenices, fixup order and module path. 3 months ago
renovate.json 2611bb75da Restyled by prettier-json 2 months ago

README.md

gfpsgo for Linux

Maintainability


Overview

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)

    • ProcessInfo returns the process information of all processes in the currently mount namespace. The input descriptors must be a slice of supported AIX format descriptors in the normal form or in the code form, if supported. If the input descriptor slice is empty, the gfpsgo.DefaultDescriptors are used. The return value contain string slices of process data, one per process.
  • gfpsgo.ProcessInfoByPids(pids []string, descriptors []string) ([][]string, error)

    • ProcessInfoByPids is similar to 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)

    • JoinNamespaceAndProcessInfo has the same semantics as ProcessInfo but joins the mount namespace of the specified pid before extracting data from /proc. This way, we can extract the /proc data from a container without executing any command inside the container.
  • psgo.JoinNamespaceAndProcessInfoByPids(pids []string, descriptors []string) ([][]string, error)

    • JoinNamespaceAndProcessInfoByPids is similar to 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

    • ListDescriptors returns a sorted string slice of all supported AIX-formatted descriptors in their normal form (for example, "args, comm, user", etc.) It can be useful in the context of shell completion, help messages, etc.

Listing all processes

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]

Listing specific processes

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

Listing processes within a container

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

Format descriptors

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

    • Set of ambient capabilities. See capabilities(7) for more information.
  • capbnd

    • Set of bounding capabilities. See capabilities(7) for more information.
  • capeff

    • Set of effective capabilities. See capabilities(7) for more information.
  • capinh

    • Set of inheritable capabilities. See capabilities(7) for more information.
  • capprm

    • Set of permitted capabilities. See capabilities(7) for more information.
  • hgroup

    • The corresponding effective group of a container process on the host.
  • hpid

    • The corresponding host PID of a container process.
  • huser

    • The corresponding effective user of a container process on the host.
  • label

    • Current security attributes of the process.
  • seccomp

    • Seccomp mode of the process (disabled, strict, filter).
    • See seccomp(2) for more information.
  • state

    • Process state codes (R for running, S for sleeping).
    • See proc(5) for more information.
  • stime

    • Process start time (such as "2019-12-09 10:50:36 +0100 CET").

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

Availability


License