TTYPLOT(1)

NAME
ttyplot - realtime terminal plotting utility

SYNOPSIS
ttyplot [-2bBfr] [-c plotchar] [-e errcharmax] [-E errcharmin] [-s softmax] [-S softmin] [-m hardmax] [-M hardmin] [-t title] [-u unit] [-C colorspec]
ttyplot -v
ttyplot -h

DESCRIPTION
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.

KEY BINDINGS
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’.

EXAMPLES
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("%.1f, $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

  Network/disk throughput examples
ttyplot supports two-line plots for in/out or read/write.

Local network throughput for all interfaces combined from sar(1):

    sar -n DEV 1 | gawk '{
      if($6 ~ /rxkB/) {
         print iin/1000;
         print out/1000;
         iin=0;
         out=0;
         fflush();
      }
      iin=iin+$6;
      out=out+$7;
    }' | ttyplot -2 -u "MB/s"

SNMP network throughput for an interface using ‘ttg’:

    ttg -i 10 -u Mb 10.23.73.254 public 9 \
     | gawk '{ print $5,$8; fflush(); }' \
     | ttyplot -2 -u Mb/s

SNMP network throughput for an interface using snmpdelta(1):

    snmpdelta -v 2c -c public -Cp 10 \
              10.23.73.254 1.3.6.1.2.1.2.2.1.{10,16}.9 \
     | gawk '{ print $NF/1000/1000/10; fflush(); }' \
     | ttyplot -2 -t "interface 9 throughput" -u Mb/s

Disk throughput from iostat(1):

    iostat -xmy 1 nvme0n1 \
     | stdbuf -o0 tr -s " " \
     | stdbuf -o0 cut -d " " -f 4,5 \
     | ttyplot -2 -t "nvme0n1 throughput" -u MB/s

  Rate calculator for counters
ttyplot also supports counter style metrics, calculating a rate by measuring time difference between samples.

SNMP network throughput for an interface using snmpget(1):

    { while true; do
        snmpget  -v 2c -c public \
                 10.23.73.254 1.3.6.1.2.1.2.2.1.{10,16}.9 \
         | awk '{ print $NF/1000/1000; }'
        sleep 10
      done } | ttyplot -2 -r -u "MB/s"

Local interface throughput using ip(8) and jq(1):

    { while true; do
        ip -s -j link show enp0s31f6 \
         | jq '.[].stats64.rx.bytes/1024/1024, \
               .[].stats64.tx.bytes/1024/1024'
        sleep 1
      done } | ttyplot -r -2 -u "MB/s"

Prometheus node exporter disk throughput for /dev/sda:

    { while true; do
        curl -s http://10.11.0.173:9100/metrics \
         | awk '/^node_disk_.+_bytes_total{device="sda"}/ {
             printf("%f, $2/1024/1024);
           }'
        sleep 1
      done } | ttyplot -r -2 -u MB/s -t "10.11.0.173 sda writes"

AUTHORS
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>.

BUGS
By default standard input and output are buffered. This can be worked around in various ways: http://www.perkin.org.uk/posts/how-to-fix-stdio-buffering.html.

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: https://invisible-island.net/xterm/xterm.faq.html#xterm_tite; 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.