tapset/*awk: document these scripts

Otherwise I will forget what they output one day and will
have to read the code again.

2 files changed, 19 insertions, 0 deletions

diff --git a/tapset/http_access_log.gawk b/tapset/http_access_log.gawk
index fe2a616..b88689c 100755
--- a/tapset/http_access_log.gawk
+++ b/tapset/http_access_log.gawk
@@ -1,6 +1,11 @@
 #!/usr/bin/gawk -f
 # using gawk for strftime
 # This takes the output of the all.stp tapset distributed with cmogstored
+# This emits output similar to Common Log Format (CLF), with two exceptions:
+#
+# The byte count for PUT requests is recorded in byte bytes transferred
+# since PUT responses are always an empty body with cmogstored.
+
 / http_accepted / {
         pid = $1
         fd = $2
diff --git a/tapset/ioq_wait.awk b/tapset/ioq_wait.awk
index ba3913e..a5caa7c 100755
--- a/tapset/ioq_wait.awk
+++ b/tapset/ioq_wait.awk
@@ -1,4 +1,18 @@
 #!/usr/bin/awk -f
+# This outputs 6 columns:
+# PID FD BLOCKED_TIME RESCHEDULE_TIME METHOD PATH
+#
+# PID - pid of cmogstored process
+# FD - descriptor of client
+# BLOCKED_TIME - total time a client spent blocked
+# RESCHEDULE_TIME - the time a client went from unblocked to dispatching
+# METHOD - HTTP or sidechannel method (e.g. GET/HEAD/PUT/DELETE/MD5)
+# PATH - path accessed (e.g. /dev666/usage)
+#
+# [PID,FD] - unique identifier on any host at that point-in-time
+# BLOCKED_TIME - RESCHEDULE_TIME = time actually spent in the queue
+# RESCHEDULE_TIME is usually very low.
+
 / ioq_blocked / {
         pid = $1
         fd = $2