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]
                      [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.

record

$ procpath record --help
     ___   ___   ___   __    ___    __   _____  _   
    | |_) | |_) / / \ / /`  | |_)  / /\   | |  | |_|
    |_|   |_| \ \_\_/ \_\_, |_|   /_/--\  |_|  |_| |

                   a process tree analysis workbench

usage: procpath record [-h] [-f PROCFILE-LIST] [-e ENVIRONMENT] -d DATABASE-FILE
                       [-p PID-LIST] [-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.

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] [-s STOP-SIGNAL] [-f PROCFILE-LIST]
                      [--no-restart]

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.

named 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 to repetitions instead of infinite watch.
  -s STOP-SIGNAL, --stop-signal STOP-SIGNAL
                        Signal to send to the spawned processes on watch stop.
                        By default: SIGINT.
  -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.
  --no-restart          Do not restart watched processes when they stop, and
                        stop watching once no watched process is running.

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.