ttyplot - Man Page

• Plot the values 1, 2, and 3 (Note: cat prevents ttyplot from exiting): { echo 1 2 3; cat; } | ttyplot

• Set a specific title and unit: { echo 1 2 3; cat; } | ttyplot -t title -u unit

• Use a while loop to continuously plot random values: { while true; do echo $RANDOM; sleep 1; done } | ttyplot

• Parse the output from ping and visualize it: ping 8.8.8.8 | sed -u 's/^.*time=//g; s/ ms//g' | ttyplot -t "ping to 8.8.8.8" -u ms

tldr.sh

ttyplot takes data from standard input, most commonly some tool like ping(1), snmpget(1), netstat(8), ifconfig(8), sar(1), vmstat(8), etc., and plots in text mode on a terminal in real time.

Supports rate calculation for counters and up to two graphs on a single display, using reverse video for the second line or, experimentally, braille or block element line drawing in color.

The following options are supported:

-2

Read two values and draw two plots, the second in reverse video.

-b

(Experimental) Use braille line drawing instead of block/reverse-video bars. With -2, the two lines are distinguished by color rather than reverse video. Requires a UTF-8 locale and a capable font, otherwise falls back.

-B

(Experimental) Use block element (quadrant) line drawing, like -b.

-f

(Experimental) Fill the area under the line in braille or block mode (line 1).

-A

(Experimental) Render the plot as aalib(3) ASCII art: smooth lines in plain 7-bit ASCII, for dumb terminals that cannot display braille or block glyphs. Like braille or block mode it draws up to two lines distinguished by color, and -f fills the area under line 1. aalib emits its native 7-bit ramp in a C locale; in a UTF-8 locale it is forced to 8-bit glyphs which are folded back to ASCII, so for the smoothest output run with LC_ALL=C. Available only when compiled with aalib support (make AA=1).

-r

Calculate counter rate and divide by measured sample interval.

-c plotchar

Use plotchar for the plot line, e.g. ‘@ # % .’ etc.

-e errcharmax

Use errcharmax for plot error line when value exceeds hardmax. Default: ‘e’.

-E errcharmin

Use errcharmin for plot error symbol, displayed when plot value is less than hardmin. Default: ‘v’.

-s softmax

Use softmax as the initial maximum value but allow it to grow with input.

-S softmin

Use softmin as the initial minimum value but allow it to shrink with input.

-m hardmax

Use hardmax as a hard value limit after which an error line will be drawn (see -e). Should be greater than hardmin, if set.

-M hardmin

Use hardmin as a definite minimum limit of the plot range. If a plot value is less than this, error symbol will be drawn (see -E).

-t title

Use title as the plot title.

-u unit

Label the vertical axis unit.

-C colorspec

Set colors for plot elements. colorspec is either a predefined scheme name or a comma-separated list of color numbers (0-7): plotchar[/line2], axes, text, title, max_err, min_err. Only the first value, the plot line color, is required; the rest are optional. The optional line2 sets the second line color in braille or block mode. For example ‘-C 1,2,3,4,5,6’, ‘-C 1,2’ or ‘-C 1’. The color numbers are 0 black, 1 red, 2 green, 3 yellow, 4 blue, 5 magenta, 6 cyan and 7 white. Alternatively, colorspec may name a predefined scheme: dark1 or dark2 for dark terminals, light1 or light2 for light terminals.

-v

Print the current version and exit.

-h

Print this help message and exit.

When reading data from a pipe, ttyplot accepts the following commands typed at the terminal:

q

Quit.

r

Toggle "rate mode" on and off.

Ctrl-L

Full screen redraw.

These commands do not work when standard input is a terminal; in that case quit with ‘Ctrl-C’.

CPU usage from vmstat(8) using awk(1) to pick the right column:

vmstat -n 1 \
 | gawk '{ print 100-int($(NF-2)); fflush(); }' \
 | ttyplot

CPU usage from sar(1) with title and fixed scale to 100%:

sar 1 \
 | gawk '{ print 100-int($NF); fflush(); }' \
 | ttyplot -s 100 -t "cpu usage" -u "%"

Memory usage from sar(1), using perl(1), to pick the right column:

sar -r 1 \
 | perl -lane 'BEGIN{$|=1} print "@F[5]"' \
 | ttyplot -s 100 -t "memory used %" -u "%"

Number of processes in running and io blocked state:

vmstat -n 1 \
 | perl -lane 'BEGIN{$|=1} print "@F[0,1]"' \
 | ttyplot -2 -t "procs in R and D state"

Load average via uptime(1) and awk(1):

{ while true; do
    uptime | gawk '{ gsub(/,/, ""); print $(NF-2) }'
    sleep 1
  done } | ttyplot -t "load average" -s load

Ping plot with sed(1):

ping 8.8.8.8 \
 | sed -u 's/^.*time=//g; s/ ms//g' \
 | ttyplot -t "ping to 8.8.8.8" -u ms

The same ping plot, drawn with braille (see -b):

ping 8.8.8.8 \
 | sed -u 's/^.*time=//g; s/ ms//g' \
 | ttyplot -b -t "ping to 8.8.8.8" -u ms

The same ping plot, with custom colors for the line, axes, text and title (see -C):

ping 8.8.8.8 \
 | sed -u 's/^.*time=//g; s/ ms//g' \
 | ttyplot -t "ping to 8.8.8.8" -u ms -C 2,3,4,5

WiFi signal level in -dBM (higher is worse) using iwconfig(8):

{ while true; do
    iwconfig 2>/dev/null \
     | grep "Signal level" \
     | sed -u 's/^.*Signal level=-//g; s/dBm//g'
    sleep 1
  done } | ttyplot -t "wifi signal" -u "-dBm" -s 90

CPU temperature from proc;

{ while true; do
    awk '{ printf("%.1f0, $1/1000) }' \
         /sys/class/thermal/thermal_zone0/temp
    sleep 1
  done } | ttyplot -t "cpu temp" -u C

Fan speed from sensors(1) using grep(1), tr(1) and cut(1):

{ while true; do
    sensors | grep fan1: | tr -s " " | cut -d" " -f2
    sleep 1
  done } | ttyplot -t "fan speed" -u RPM

Bitcoin price chart using curl(1) and jq(1):

{ while true; do
    curl -sL https://api.coindesk.com/v1/bpi/currentprice.json \
     | jq .bpi.USD.rate_float
    sleep 600
  done } | ttyplot -t "bitcoin price" -u usd

Stock quote chart:

{ while true; do
    curl -sL https://api.iextrading.com/1.0/stock/googl/price
    echo
    sleep 600
  done } | ttyplot -t "google stock price" -u usd

Prometheus load average via node_exporter:

{ while true; do
    curl -s  http://10.4.7.180:9100/metrics \
     | grep "^node_load1 " \
     | cut -d" " -f2; sleep 1
  done } | ttyplot

ttyplot is written by:
Antoni Sawicki <tenox@google.com>,
Edgar Bonet <linux@edgar-bonet.org> and
Sebastian Pipping <sebastian@pipping.org>.

Its readme was converted into this manual page by
Sijmen J. Mulder <ik@sjmulder.nl>.

By default standard input and output are buffered. This can be worked around in various ways.

When there is no more data, ttyplot prints “input stream closed” and waits rather than quitting (prior to version 1.5 it quit). The screen is normally erased on exit because of the terminal's alternate screen; this can be worked around, for example:

echo 1 2 3 | TERM=vt100 ttyplot

When running interactively and non-numeric data is entered (e.g. some key) ttyplot hangs. Press ‘Ctrl^J’ to reset.