Command-line UI¶
This page provides the help listing of all Procpath command-line interface’s commands.
$ procpath --help
___ ___ ___ __ ___ __ _____ _
| |_) | |_) / / \ / /` | |_) / /\ | | | |_|
|_| |_| \ \_\_/ \_\_, |_| /_/--\ |_| |_| |
a process tree analysis workbench
usage: procpath [-h] [--version] [--logging-level LOGGING-LEVEL]
{query,record,plot,explore,watch,play} ...
positional arguments:
{query,record,plot,explore,watch,play}
options:
-h, --help show this help message and exit
--version show program's version number and exit
--logging-level LOGGING-LEVEL
Logging level. By default: INFO.
query¶
$ procpath query --help
___ ___ ___ __ ___ __ _____ _
| |_) | |_) / / \ / /` | |_) / /\ | | | |_|
|_| |_| \ \_\_/ \_\_, |_| /_/--\ |_| |_| |
a process tree analysis workbench
usage: procpath query [-h] [-f PROCFILE-LIST] [-d DELIMITER] [-i INDENT]
[-e ENVIRONMENT] [--procfs PROCFS]
[--procfs-target PROCFS-TARGET]
[query] [sql_query]
Execute given JSONPath and/or SQL query against process tree producing JSON or
separator-delimited values.
positional arguments:
query JSONPath expression, for example this query returns PIDs
for process subtree including the given root's:
$..children[?(@.stat.pid == 2610)]..pid
sql_query SQL query to further filter and/or aggregate collected
process nodes. Note that if JSONPath query is present it
must return full nodes, e.g. $..children[?(@.stat.pid ==
2610)]. For example this query returns total RSS of the
processes: SELECT SUM(stat_rss) / 1024.0 * 4 total FROM
record
options:
-h, --help show this help message and exit
named arguments:
-f PROCFILE-LIST, --procfile-list PROCFILE-LIST
Procfs files to read per PID. Comma-separated list. By
default: stat, cmdline. Available: stat, cmdline, io,
status, fd, smaps_rollup.
-d DELIMITER, --delimiter DELIMITER
Join query result using given delimiter
-i INDENT, --indent INDENT
Format result JSON using given indent number
-e ENVIRONMENT, --environment ENVIRONMENT
Commands to evaluate in the shell and template the
queries, like VAR=date. Multiple occurrence is possible.
--procfs PROCFS Procfs mount path. By default: /proc.
--procfs-target PROCFS-TARGET
Procfs target object. By default: process. Available:
process, thread.
record¶
$ procpath record --help
___ ___ ___ __ ___ __ _____ _
| |_) | |_) / / \ / /` | |_) / /\ | | | |_|
|_| |_| \ \_\_/ \_\_, |_| /_/--\ |_| |_| |
a process tree analysis workbench
usage: procpath record [-h] [-f PROCFILE-LIST] [-e ENVIRONMENT] -d DATABASE-FILE
[-p PID-LIST] [--procfs PROCFS]
[--procfs-target PROCFS-TARGET] [-i INTERVAL] [-r RECNUM]
[-v REEVALNUM] [--stop-without-result]
[query]
Record the nodes of process tree matching given JSONPath query into a SQLite
database in given intervals.
positional arguments:
query JSONPath expression, for example this query returns a
node including its subtree for given PID:
$..children[?(@.stat.pid == 2610)]
options:
-h, --help show this help message and exit
named arguments:
-f PROCFILE-LIST, --procfile-list PROCFILE-LIST
Procfs files to read per PID. Comma-separated list. By
default: stat, cmdline. Available: stat, cmdline, io,
status, fd, smaps_rollup.
-e ENVIRONMENT, --environment ENVIRONMENT
Commands to evaluate in the shell and template the
query, like VAR=date. Multiple occurrence is possible.
-d DATABASE-FILE, --database-file DATABASE-FILE
Path to the recording database file
-p PID-LIST, --pid-list PID-LIST
Keep only branches with given PIDs in the tree before
running query against it. Comma-separated list. It can
include environment variables.
--procfs PROCFS Procfs mount path. By default: /proc.
--procfs-target PROCFS-TARGET
Procfs target object. By default: process. Available:
process, thread.
loop control arguments:
-i INTERVAL, --interval INTERVAL
Interval in second between each recording, 10 by
default.
-r RECNUM, --recnum RECNUM
Number of recordings to take at --interval seconds
apart. If not specified, recordings will be taken
indefinitely.
-v REEVALNUM, --reevalnum REEVALNUM
Number of recordings after which environment must be re-
evaluate. It's useful when you expect it to change while
recordings are taken.
--stop-without-result
Prematurely stop recording when target processes can no
longer be found, or otherwise when the query and/or PID
filter don't yield a result.
plot¶
$ procpath plot --help
___ ___ ___ __ ___ __ _____ _
| |_) | |_) / / \ / /` | |_) / /\ | | | |_|
|_| |_| \ \_\_/ \_\_, |_| /_/--\ |_| |_| |
a process tree analysis workbench
usage: procpath plot [-h] -d DATABASE-FILE [-f PLOT-FILE] [-q QUERY-NAME]
[--custom-query-file CUSTOM-QUERY-FILE]
[--custom-value-expr CUSTOM-VALUE-EXPR] [-a AFTER]
[-b BEFORE] [-p PID-LIST] [-s] [-l] [--style STYLE]
[--formatter FORMATTER] [--title TITLE] [--no-dots]
[--relative-time] [-e EPSILON] [-w MOVING-AVERAGE-WINDOW]
Plot previously recorded SQLite database using predefined or custom SQL
expression or query.
options:
-h, --help show this help message and exit
named arguments:
-d DATABASE-FILE, --database-file DATABASE-FILE
Path to the database file to read from.
-f PLOT-FILE, --plot-file PLOT-FILE
Path to the output SVG file, plot.svg by default.
query control arguments:
-q QUERY-NAME, --query-name QUERY-NAME
Built-in query name. Available: cpu, rss, pss, uss,
swap, fd, rbs, wbs, wait. Without --share-y-axis it can
occur once or twice (including other query-contributing
options). In the latter case, the plot has two Y axes.
--custom-query-file CUSTOM-QUERY-FILE
Use custom SQL query in given file. The result-set must
have 3 columns: ts, pid, value. See procpath.procret.
Without --share-y-axis it can occur once or twice
(including other query-contributing options). In the
latter case, the plot has two Y axes.
--custom-value-expr CUSTOM-VALUE-EXPR
Use custom SELECT expression to plot as the value.
Without --share-y-axis it can occur once or twice
(including other query-contributing options). In the
latter case, the plot has two Y axes.
filter control arguments:
-a AFTER, --after AFTER
Include only points after given UTC date, like
2000-01-01T00:00:00.
-b BEFORE, --before BEFORE
Include only points before given UTC date, like
2000-01-01T00:00:00.
-p PID-LIST, --pid-list PID-LIST
Include only given PIDs. Comma-separated list.
plot control arguments:
-s, --share-y-axis Use the same Y axis for two or more queries.
-l, --logarithmic Plot using logarithmic scale.
--style STYLE Plot using given pygal.style, like LightGreenStyle.
--formatter FORMATTER
Force given pygal.formatter, like integer.
--title TITLE Override plot title.
--no-dots Do not add hover dots to the lines.
--relative-time Display X axis as time deltas since the first
measurement.
post-processing control arguments:
-e EPSILON, --epsilon EPSILON
Reduce points using Ramer-Douglas-Peucker algorithm and
given ε.
-w MOVING-AVERAGE-WINDOW, --moving-average-window MOVING-AVERAGE-WINDOW
Smooth the lines using moving average.
watch¶
$ procpath watch --help
___ ___ ___ __ ___ __ _____ _
| |_) | |_) / / \ / /` | |_) / /\ | | | |_|
|_| |_| \ \_\_/ \_\_, |_| /_/--\ |_| |_| |
a process tree analysis workbench
usage: procpath watch [-h] [-e ENVIRONMENT] [-q QUERY] -c COMMAND -i INTERVAL
[-r REPEAT] [--no-restart] [-s STOP-SIGNAL]
[--kill-after KILL-AFTER] [-f PROCFILE-LIST]
[--procfs PROCFS] [--procfs-target PROCFS-TARGET]
Execute given commands in given intervals. It has similar purpose to procps
watch, but allows JSONPath queries to the process tree to choose processes of
interest. In each next process' environment exist variables WSP1, WSP2 and so on
containing PIDs of previous shells that run watched processes.
options:
-h, --help show this help message and exit
command control arguments:
-e ENVIRONMENT, --environment ENVIRONMENT
Commands to evaluate in the shell, like C1='docker
inspect -f "{{.State.Pid}}" nginx' or D='date +%s'.
Multiple occurrence is possible.
-q QUERY, --query QUERY
JSONPath expressions that typically evaluate into a list
of PIDs. The environment defined with -e can be used
like L1='$..children[?(@.stat.pid == $C1)]..pid'.
Multiple occurrence is possible.
-c COMMAND, --command COMMAND
Target command to "watch" in the shell. The environment
and query results can be used like 'smemstat -o
smemstat-$D.json -p $L1'. Query result lists are joined
with comma. Multiple occurrence is possible.
loop control arguments:
-i INTERVAL, --interval INTERVAL
Interval in second after which to re-evaluate the
environment and the queries, and re-run each command if
one has finished.
-r REPEAT, --repeat REPEAT
Fixed number of iterations instead of infinite watch.
--no-restart Do not restart watched processes when they stop, and
stop watching once no watched process is running.
-s STOP-SIGNAL, --stop-signal STOP-SIGNAL
Signal to send to the spawned processes on watch stop.
By default: SIGINT.
--kill-after KILL-AFTER
Kill all remaining descendant processes after this many
seconds after the stop signal has been sent. By default:
10.',
named arguments:
-f PROCFILE-LIST, --procfile-list PROCFILE-LIST
Procfs files to read per PID. Comma-separated list. By
default: stat, cmdline. Available: stat, cmdline, io,
status, fd, smaps_rollup.
--procfs PROCFS Procfs mount path. By default: /proc.
--procfs-target PROCFS-TARGET
Procfs target object. By default: process. Available:
process, thread.
play¶
$ procpath play --help
___ ___ ___ __ ___ __ _____ _
| |_) | |_) / / \ / /` | |_) / /\ | | | |_|
|_| |_| \ \_\_/ \_\_, |_| /_/--\ |_| |_| |
a process tree analysis workbench
usage: procpath play [-h] -f PLAYBOOK-FILE [-l] [-n] [-o OPTION]
target [target ...]
Play one or more sections from given playbook.
positional arguments:
target Name or glob-expression of the section from the
playbook.
options:
-h, --help show this help message and exit
named arguments:
-f PLAYBOOK-FILE, --playbook-file PLAYBOOK-FILE
Path to the playbook to play.
-l, --list-sections List matching sections in the playbook.
-n, --dry-run Collect and print target sections.
-o OPTION, --option OPTION
A key-value pair to override the option in the playbook,
like database_file=db.sqlite. Multiple occurrence is
possible.
explore¶
$ procpath explore --help
___ ___ ___ __ ___ __ _____ _
| |_) | |_) / / \ / /` | |_) / /\ | | | |_|
|_| |_| \ \_\_/ \_\_, |_| /_/--\ |_| |_| |
a process tree analysis workbench
usage: procpath explore [-h] [--reinstall] [--build-url BUILD-URL] [-b ADDRESS]
[-p PORT] [--no-browser] [-d DATABASE-FILE]
Serve a Sqliteviz build from a local web-server for exploratory or ad-hoc
visualisation. On first invocation Sqliteviz is downloaded and saved locally for
later offline use. Procpath exports pre-defined queries into Sqliteviz.
options:
-h, --help show this help message and exit
named arguments:
--reinstall Remove local copy and fetch Sqliteviz build again.
--build-url BUILD-URL
Sqliteviz build URL. By default: https://github.com/lana
-k/sqliteviz/releases/latest/download/dist.zip.
-b ADDRESS, --bind ADDRESS
Specify alternate bind address. By default: all
interfaces.
-p PORT, --port PORT Specify alternate port. By default: 8000.
--no-browser Do not open a browser after startup.
-d DATABASE-FILE, --database-file DATABASE-FILE
Database file to pre-load into Sqliteviz.