Procpath

Procpath

Procpath is a process tree analysis command-line workbench. Its goal is to provide natural interface to the tree structure of processes running on a Linux system for inspection, collection and later analysis with focus on performance.

Installation

pipx install Procpath

pipx is recommended for installing Procpath (into a dedicated virtual environment). Alternatively pip can be used to install Procpath to the Python user install directory.

pip install --user Procpath

Quickstart

Get comma-separated PIDs of the process subtree (including the parent process pid=2610).

procpath query -d , '$..children[?(@.stat.pid == 2610)]..pid'

Get JSON document of said process subtree.

procpath query -i 2 '$..children[?(@.stat.pid == 2610)]'

Get total RSS in MiB of said process subtree (this is an example that query produces JSON that can be further processed outside of procpath, and below is a much easier way to calculate aggregates).

procpath query '$..children[?(@.stat.pid == 2610)]' \
  | jq '[.. | .stat? | objects | .rss] | add / 1024 * 4'

Get total RSS in MiB of said process subtree the easy way.

procpath query '$..children[?(@.stat.pid == 2610)]' \
  'SELECT SUM(stat_rss) / 1024.0 * 4 total FROM record'

Get total RSS in MiB of a docker-compose stack.

L=$(docker ps -f status=running -f name='^project_name' -q | xargs -I{} -- \
  docker inspect -f '{{.State.Pid}}' {} | tr '\n' ,)
procpath query "$..children[?(@.stat.pid in [$L])]" \
  'SELECT SUM(stat_rss) / 1024.0 * 4 total FROM record'

Record process trees of two Docker containers once a second, re-evaluating the containers’ root process PIDs once per 30 recordings. Then visualise RSS of each process (which is also just an example, that output SQLite database can be visualised in different ways, including exporting CSV, sqlite3 -csv ..., and doing it the old way, to using proper UI described in the documentation).

procpath record \
  -e C1='docker inspect -f "{{.State.Pid}}" project_db_1' \
  -e C2='docker inspect -f "{{.State.Pid}}" project_app_1' \
  -i 1 -v 30 -d out.sqlite '$..children[?(@.stat.pid in [$C1, $C2])]'
# press Ctrl + C
sqlite3 out.sqlite \
  "SELECT stat_pid, group_concat(stat_rss / 1024.0 * 4) \
   FROM record \
   GROUP BY stat_pid" \
  | sed -z 's/\n/\n\n\n/g' | sed 's/|/\n/' | sed 's/,/\n/g' > special_fmt
gnuplot -p -e \
  "plot for [i=0:*] 'special_fmt' index i with lines title columnheader(1)"

Visualise the above recording the easy way.

procpath plot -d out.sqlite -o out.svg -q cpu -q rss

Release files for Procpath 1.15.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for Procpath 1.15.1
File	Size	Uploaded
procpath-1.15.1.tar.gz	80.6 kB	Jun 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for Procpath 1.15.1
File	Interpreter	ABI	Platform	Reset
procpath-1.15.1-py3-none-any.whl 87.8 kB Jun 14, 2026	Python 3	none	any	Details

Total release size: 168.4 kB

Release files / procpath-1.15.1.tar.gz

Download URL	procpath-1.15.1.tar.gz
Size	80.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`067e0ec7e422f59c3957858b9e47a12cd8965965016bc40bf6614d13fa453f14`
BLAKE2b-256 checksum How to use checksums	`e440c40cbfa8b6ff62d34f281999b2bd9408ef704e9edee6f2d55646b1a81abb`
Upload date	Jun 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`

Release files / procpath-1.15.1-py3-none-any.whl

Download URL	procpath-1.15.1-py3-none-any.whl
Size	87.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1d3b00b181a8937ad72b565d9f18aef9078c0361e965141271838819b5eca55a`
BLAKE2b-256 checksum How to use checksums	`eba75cc14213573d339bce72e92e16479dccd9f785aea3dd66b5ea54355f82a9`
Upload date	Jun 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`