diff options
| -rw-r--r-- | README.md | 72 |
1 files changed, 52 insertions, 20 deletions
@@ -3,31 +3,63 @@ `pw` stands for Pipe Watch. Pipe-Watch is a new monitoring utility for Unix-like systems, developed starting in April 2022. -Scroll down for a demo video. +## Demo Video + +<div style="padding:75% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/705257869?h=7e8d85a3c2&badge=0&autopause=0&player_id=0&app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen style="position:absolute;top:0;left:0;width:100%;height:100%;" title="pipewatch-gnome-strace.mp4"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script> -`pw` can monitor anything that produces output. `tail -f /var/logfile`, -`tcpdump`, you name it. In particular, it's suitable when the output -is spewing at a fast rate. +## More Info + +`pw` can monitor anything that produces textual output. `tail -f /var/logfile`, +`tcpdump`, you name it. `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 displayed. When the sampling -occurs is controlled in various ways. - -`pw` is a little over 1200 lines of code, all in one source file, compiling to -a tiny executable. It depends on no 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. Since it only retains the last -portion of the real-time input, it doesn't need a lot of memory. 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. +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. -## Documentation +With `pw` you can do things like: -The [`pw` man page](../tree/pw.1) has all the usage details. +* Look for certain pieces of known information in live textual data. -## Demo Video +* Explore the data to discover information and patterns. -<div style="padding:75% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/705257869?h=7e8d85a3c2&badge=0&autopause=0&player_id=0&app_id=58479" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen style="position:absolute;top:0;left:0;width:100%;height:100%;" title="pipewatch-gnome-strace.mp4"></iframe></div><script src="https://player.vimeo.com/api/player.js"></script> +* Make recurring patterns in the stream appear to "freeze" with +on the screen triggered snapshots. + +* 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. + +* Gain visibility into the diagnostic stream produced by a program, +and analytic ability, without having to capture and store any large +subset (or all) of that data anywhere. + +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. Modern 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. + +All of the above is achieved with low resources. `pw` is a little over 1200 +lines of code, all in one source file, compiling to a tiny executable. It only +retains a small number of snapshots of small windows the real-time input, +storage for which requires requiring less than 64 kilobytes of memory. + +## Dependencies + +`pw` depends on no 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. + +## Documentation + +The [`pw` man page](../tree/pw.1) has all the usage details. |