{"id":16164609,"url":"https://github.com/johnsonjh/gfpsgo","last_synced_at":"2025-03-18T23:30:29.755Z","repository":{"id":37830226,"uuid":"342761450","full_name":"johnsonjh/gfpsgo","owner":"johnsonjh","description":"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","archived":false,"fork":false,"pushed_at":"2025-03-06T20:55:28.000Z","size":2368,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-17T00:34:18.071Z","etag":null,"topics":["aix","container","go","golang","ibm","ps","psgo"],"latest_commit_sha":null,"homepage":"https://github.com/johnsonjh/gfpsgo","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnsonjh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-27T03:29:48.000Z","updated_at":"2025-03-06T20:55:31.000Z","dependencies_parsed_at":"2023-02-03T07:16:00.041Z","dependency_job_id":"ce444366-da16-4996-a8be-52c79b46489a","html_url":"https://github.com/johnsonjh/gfpsgo","commit_stats":{"total_commits":367,"total_committers":23,"mean_commits":"15.956521739130435","dds":0.7356948228882834,"last_synced_commit":"1723da4743b480ac2327c66bdd97390611b0d5f4"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fgfpsgo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fgfpsgo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fgfpsgo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fgfpsgo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnsonjh","download_url":"https://codeload.github.com/johnsonjh/gfpsgo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244325047,"owners_count":20435029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aix","container","go","golang","ibm","ps","psgo"],"created_at":"2024-10-10T02:47:12.504Z","updated_at":"2025-03-18T23:30:29.497Z","avatar_url":"https://github.com/johnsonjh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gfpsgo for Linux\n\n[![Maintainability](https://api.codeclimate.com/v1/badges/07c320e9836d870b12d8/maintainability)](https://codeclimate.com/github/johnsonjh/gfpsgo/maintainability)\n\n---\n\n## Overview\n\n`gfpsgo` is a `ps`(`1`) (AIX-format compatible) Go library and tool, extended\nwith various descriptors useful for displaying container-related data.\n\nThe idea behind the library is to provide an easy to use way of extracting\nprocess-related data, just as `ps`(`1`) tool does. The problem with using\n`ps`(`1`) is that the `ps` output is formatted strings split into columns by\nwhitespace, which makes the output extremely impossible to automatically parse.\nIt also adds some jitter as we have to fork and execute `ps`, either in the\ncontainer, or filter the output afterwards, which further limits usability.\n\nThis tool and library is intended to make things more comfortable, especially\nfor container runtimes. An API allows joining the mount namespace of a given\nprocess, and will parse `/proc` and `/dev` filesystems automatically.\n\nThe API consists of the following functions:\n\n- `gfpsgo.ProcessInfo(descriptors []string) ([][]string, error)`\n\n  - ProcessInfo returns the process information of all processes in the\n    currently mount namespace. The input descriptors must be a slice of\n    supported AIX format descriptors in the normal form or in the code form, if\n    supported. If the input descriptor slice is empty, the\n    `gfpsgo.DefaultDescriptors` are used. The return value contain string slices\n    of process data, one per process.\n\n- `gfpsgo.ProcessInfoByPids(pids []string, descriptors []string) ([][]string, error)`\n\n  - ProcessInfoByPids is similar to `psgo.ProcessInfo`, but limits the return\n    value to a list of specified PIDs. The PIDs input must be a slice of PIDs\n    for which process information should be returned. If the input descriptor\n    slice is empty, only the format descriptor headers are returned.\n\n- `psgo.JoinNamespaceAndProcessInfo(pid string, descriptors []string) ([][]string, error)`\n\n  - JoinNamespaceAndProcessInfo has the same semantics as ProcessInfo but joins\n    the mount namespace of the specified pid before extracting data from /proc.\n    This way, we can extract the `/proc` data from a container without executing\n    any command inside the container.\n\n- `psgo.JoinNamespaceAndProcessInfoByPids(pids []string, descriptors []string) ([][]string, error)`\n\n  - JoinNamespaceAndProcessInfoByPids is similar to\n    `gfpsgo.JoinNamespaceAndProcessInfo` but takes a slice of PIDs as an\n    argument. To avoid duplicate entries, such as when two or more containers\n    share the same PID namespace, a given PID namespace will be joined only\n    once.\n\n- `psgo.ListDescriptors() []string`\n  - ListDescriptors returns a sorted string slice of all supported AIX-formatted\n    descriptors in their normal form (for example, \"args, comm, user\", etc.) It\n    can be useful in the context of shell completion, help messages, etc.\n\n---\n\n## Listing all processes\n\nWe can use the `gfpsgo` tool included with the project to test the core\ncomponents of the library. First, build `gfpsgo` via `make build`. The binary is\nnow located under `./bin/gfpsgo`. By default `gfpsgo` displays data about all\nrunning processes in the currently mount namespace, similar to the output of\n`ps -ef`.\n\n```shell\n$ ./bin/psgo | head -n 5\nUSER         PID     PPID    %CPU     ELAPSED              TTY      TIME        COMMAND\nroot         1       0       0.064    6h3m27.677997443s    ?        13.98s      systemd\nroot         2       0       0.000    6h3m27.678380128s    ?        20ms        [kthreadd]\nroot         4       2       0.000    6h3m27.678701852s    ?        0s          [kworker/0:0H]\nroot         6       2       0.000    6h3m27.678999508s    ?        0s          [mm_percpu_wq]\n```\n\n---\n\n## Listing specific processes\n\nYou can use the `--pids` flag to restrict `gfpsgo` output to a subset of\nprocesses. This option accepts a list of comma separate process IDs and returns\nexactly the same kind of information, only per process, as the default output.\n\n```shell\n$ ./bin/psgo --pids 1,$(pgrep bash | tr '\\n' ',')\nUSER   PID     PPID    %CPU    ELAPSED                TTY     TIME   COMMAND\nroot   1       0       0.009   128h52m44.193475932s   ?       40s    systemd\nroot   20830   20827   0.000   105h2m44.19579679s     pts/5   0s     bash\nroot   25843   25840   0.000   102h56m4.196072027s    pts/6   0s     bash\n```\n\n---\n\n## Listing processes within a container\n\nLet's have a look at how we can use this tool and library in the context of\ncontainers. As a simple show case, we'll start a Docker container, extract the\nprocess ID via `docker-inspect` and run the `gfpsgo` binary to extract the data\nof running processes within that container.\n\n```shell\n$ docker run -d alpine sleep 100\n473c9a05d4223b88ef7f5a9ac11e3d21e9914e012338425cc1cef853fc6c32a2\n\n$ docker inspect --format '{{.State.Pid}}' 473c9\n5572\n\n$ sudo ./bin/psgo -pids 5572 -join\nUSER   PID   PPID   %CPU    ELAPSED         TTY   TIME   COMMAND\nroot   1     0      0.000   17.249905587s   ?     0s     sleep\n```\n\n---\n\n## Format descriptors\n\nThe `gfpsgo` library is compatible with all AIX-formatted descriptors provided\nby the IBM AIX `ps`(`1`) command-line utility. (On any AIX system, execute\n`man 1 ps` for more details.) It also supports additional descriptors that can\nbe useful when seeking specific process-related information.\n\n- **capamb**\n\n  - Set of ambient capabilities. See capabilities(7) for more information.\n\n- **capbnd**\n\n  - Set of bounding capabilities. See capabilities(7) for more information.\n\n- **capeff**\n\n  - Set of effective capabilities. See capabilities(7) for more information.\n\n- **capinh**\n\n  - Set of inheritable capabilities. See capabilities(7) for more information.\n\n- **capprm**\n\n  - Set of permitted capabilities. See capabilities(7) for more information.\n\n- **hgroup**\n\n  - The corresponding effective group of a container process on the host.\n\n- **hpid**\n\n  - The corresponding host PID of a container process.\n\n- **huser**\n\n  - The corresponding effective user of a container process on the host.\n\n- **label**\n\n  - Current security attributes of the process.\n\n- **seccomp**\n\n  - Seccomp mode of the process (disabled, strict, filter).\n    - See `seccomp`(`2`) for more information.\n\n- **state**\n\n  - Process state codes (**R** for _running_, **S** for _sleeping_).\n    - See `proc`(`5`) for more information.\n\n- **stime**\n  - Process start time (such as _\"2019-12-09 10:50:36 +0100 CET\"_).\n\nWe can try out different format descriptors with the `gfpsgo` tool:\n\n```shell\n$ ./bin/gfpsgo -format \"pid, user, group, seccomp\" | head -n 5\nPID     USER         GROUP        SECCOMP\n1       root         root         disabled\n2       root         root         disabled\n4       root         root         disabled\n6       root         root         disabled\n```\n\n---\n\n## Availability\n\n- [GitHub](https://github.com/johnsonjh/gfpsgo)\n- [GitLab](https://gitlab.com/johnsonjh/gfpsgo)\n- [SourceHut](https://sr.ht/~trn/gfpsgo)\n- [NotABug](https://notabug.org/trn/gfpsgo)\n\n---\n\n## License\n\n- This software is provided under\n  [The Apache 2.0 Software License](https://gitlab.gridfinity.com/go/gfpsgo/-/blob/master/LICENSE).\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsonjh%2Fgfpsgo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnsonjh%2Fgfpsgo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsonjh%2Fgfpsgo/lists"}