impatient/README.md

# impatient

A general purpose utility for estimating when a task will complete

## Overview

`impatient` is sort of like `pv` for tasks where you can't insert
extra commands into a pipeline, and sort of like `progress` for tasks
that aren't reading/writing a specific file on the local system.  If
you give it any shell command that outputs a number (possibly with a
K/M/G/T suffix), it will repeatedly run the command and show you how
fast that number is changing.  If you give it the expected final value
of the number, it'll also estimate how much longer you have to wait.
It also has a specific option for tracking the total size of a
file or directory as given by `du`.

For example, here's `impatient` tracking an in-progress `zfs send` to
a remote machine:

```
$ impatient -f "$(zfs list -pH -o used pool/home)" -c 'ssh remote-server zfs list -pH -o used remote-pool/backups/pool/home' -i 60
109.8G - 2.8M/s - 263.7G total - 41.6% complete - 15h03m remaining - ETA 2021-11-23 11:34
```

Note that `-f` is given the value output by `zfs list`; we could
give it a number directly, this just simplifies things in this
particular scenario.  The `-p` flag for `zfs list` isn't strictly
necessary, `impatient` can parse values like `50.7G`, but
using the exact byte value provides more precision.

`-c`, on the other hand, is given a quoted string containing a
command, which will output the current progress value each time it's
run. The command given to `-c` can be an arbitrary shell one-liner,
use responsibly.

## Usage

```
usage: impatient [-h] [-f FINAL] [-i INTERVAL] [-w WINDOW] [-d DECAY]
                 [-V FRACTION] [-I COUNT] [-l PATH] (-p PATH | -c COMMAND)

Display progress and time estimates for arbitrary tasks

optional arguments:
  -h, --help            show this help message and exit
  -f FINAL, --final FINAL
                        Expected final size/value at completion, optionally
                        with a K/M/G/T suffix
  -i INTERVAL, --interval INTERVAL
                        Interval in seconds between samples (default 10)
  -w WINDOW, --window WINDOW
                        Number of samples to keep for the sliding window
                        (default 100)
  -d DECAY, --decay DECAY
                        Decay coefficient for older samples (default 1). Must
                        be between 0 and 1 inclusive. The lower this is, the
                        more responsive/swingy the estimate will be.
  -V FRACTION, --termination-value-threshold FRACTION
                        Fraction of the expected final value that must be
                        reached in order to terminate (default 0.95). Reaching
                        this threshold is necessary but not sufficient, see
                        also -I
  -I COUNT, --termination-inactivity-threshold COUNT
                        Number of consecutive unchanged samples that must be
                        observed in order to terminate (default 10). Reaching
                        this threshold is necessary but not sufficient, see
                        also -V
  -l PATH, --log-file PATH
                        File to log the time series to. Will be saved as a
                        csv, with columns for timestamp and for value. Will
                        append data if the file already exists.
  -p PATH, --path PATH  Track total disk usage of a given path
  -c COMMAND, --command COMMAND
                        Track value returned by a shell command; this should
                        return a single number, optionally with a K/M/G/T
                        suffix
```