aboutsummaryrefslogtreecommitdiffstats

What is pw?

pw stands for Pipe Watch. Pipe-Watch is a new monitoring utility for Unix-like systems, developed starting in April 2022.

Demo Video

More Info

pw can monitor anything that produces textual output. tail -f /var/logfile, tcpdump, strace, ...

pw does not show you everything. Of course, it reads all the data, but it does that in the background. It continuously pumps lines of input through a small FIFO buffer. This buffer is sampled, and the sample is displayed. When that sampling occurs is controlled in various interactive ways. What goes into the FIFO can be filtered and the filters can be edited interactively.

With pw you can:

  • Interactively apply and remove filters on-the-fly, without interrupting the source.

  • Make recurring patterns in the stream appear to "freeze" on the screen, using triggers.

  • Prevent the overwhelming amount of output from a program to flooding the terminal, while consuming all of that output so that the program isn't blocked. pw can pause its display updates entirely.

  • Juggle multiple shell background jobs that produce output, yet execute indefinitely without blocking. When pw runs as as part of a shell background job, it continues to consume input, process filters and take snapshots, without displaying anything. When put into the foreground again, display resumes.

For instance the command tcpdump -i <ethernet-device> -l | pw turns tcpdump into an interactive network monitoring tool in which you can use the dynamic filtering in pw to select different kinds of packets, and use the trigger feature to capture certain patterns of interaction.

pw is like an oscilloscope for text streams. Digital oscilloscopes sample the signal and pass it through a fifo, which is sampled to the oscilloscope screen, and can trigger the sampling on certain conditions in the signal to make waveforms appear to stand still. pw does something like that for text streams.

Dependencies and Resource Use

  • pw has very low dependencies: it requires libraries other than the POSIX standard functions; all terminal control is via ANSI sequences. It does like to have a struct winsize and an ioctl to fill it in. There is a seven line GNU Makefile to build it. If that doesn't work for you, try it some other way. It tested it on on Solaris 10, and older Mac OS, Cygwin and a few GNU/Linuxes. It built on OpenBSD, but didn't run properly; I didn't investigate into it. Patches welcome.

  • pw is tiny: it is a little over 2000 lines of C in a single source file, compiling to an executable of around 32 kilobytes.

  • pw requires a very low amount of RAM: Given inputs with typical line lengths, and 24 line snapshots, pw it needs less than 64 kilobytes of RAM to store the data which is passing through it.

Documentation

The pw man page has all the usage details.

Video: Vertical Panes Demo

High Level State Diagram

PipeWatch State Diagram