From 2ee6e843736612b2777c2ecc23970afb7c5a70c7 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Mon, 2 May 2022 18:01:13 -0700 Subject: Improve README. --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 52 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 40644a7..af45fe8 100644 --- a/README.md +++ b/README.md @@ -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 + +
-`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. -
+* 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 -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. -- cgit v1.2.3