Return the symbolic string associated with the given error code, like
"ENOENT" for the number 2, or "E#3333" for an out-of-range value like 3333.
+.SS QUEUE_STATS
+.PP
+The queue_stats tapset provides functions that, given notifications of
+elementary queuing events (wait, run, done), tracks averages such as
+queue lenghth, service and wait times, utilization. The following
+three functions should be called from appropriate probes, in sequence.
+.TP
+qs_wait:unknown (qname:string)
+Record that a new request was enqueued for the given queue name.
+.TP
+qs_run:unknown (qname:string)
+Record that a previously enqueued request was removed from the given
+wait queue and is now being serviced.
+.TP
+qs_done:unknown (qname:string)
+Record that a request originally from the given queue has completed
+being serviced.
+.\" XXX: qs_time
+.PP
+Functions with the prefix
+.BR qsq_
+are for querying the statistics averaged since the first queue operation
+(or when
+.BR qsq_start
+was called). Since statistics are often fractional, a scale parameter
+is multiplies the result to a more useful scale. For some fractions,
+a scale of 100 will usefully return percentage numbers.
+.TP
+qsq_start:unknown (qname:string)
+Reset the statistics counters for the given queue, and start tracking
+anew from this moment.
+.TP
+qsq_print:unknown (qname:string)
+Print a line containing a selection of the given queue's statistics.
+.TP
+qsq_utilization:long (qname:string, scale:long)
+Return the fraction of elapsed time when the resource was utilized.
+.TP
+qsq_blocked:long (qname:string, scale:long)
+Return the fraction of elapsed time when the wait queue was used.
+.TP
+qsq_wait_queue_length:long (qname:string, scale:long)
+Return the average length of the wait queue.
+.TP
+qsq_service_time:long (qname:string, scale:long)
+Return the average time required to service a request.
+.TP
+qsq_wait_time:long (qname:string, scale:long)
+Return the average time a request took from being enqueued to completed.
+.TP
+qsq_throughput:long (qname:string, scale:long)
+Return the average rate of requests per scale units of time.
.SH FILES
.nh
--- /dev/null
+# qstats.stp: Queue statistics gathering tapset
+
+# ------------------------------------------------------------------------
+
+# The default timing function: microseconds. This function could
+# go into a separate file (say, qstats_qs_time.stp), so that a user
+# script can override it with another definition.
+
+function qs_time () { return gettimeofday_us () }
+
+# ------------------------------------------------------------------------
+
+global qs_wtime, qs_wlentime, qs_wcount
+global qs_rtime, qs_rlentime, qs_rcount
+global qs_stime, qs_utime, qs_dcount
+
+# ------------------------------------------------------------------------
+
+function _qs_update (qname) {
+ now = qs_time ()
+ then = qs_utime[qname]; if (! then) { then = now }
+ delta = now-then
+
+ qs_wtime[qname] += qs_wcount[qname] ? delta : 0
+ qs_wlentime[qname] += qs_wcount[qname] * delta
+ qs_rtime[qname] += qs_rcount[qname] ? delta : 0
+ qs_rlentime[qname] += qs_rcount[qname] * delta
+ qs_utime[qname] = now
+}
+
+function qs_wait (qname) { # enqueueing request
+ _qs_update (qname)
+ qs_wcount[qname] ++
+}
+
+function qs_run (qname) { # starting to service request
+ _qs_update (qname)
+ if (qs_wcount[qname] > 0) {
+ qs_wcount[qname] --
+ qs_rcount[qname] ++
+ }
+}
+
+function qs_done (qname) { # done servicing request
+ _qs_update (qname)
+ if (qs_rcount[qname] > 0) {
+ qs_rcount[qname] --
+ qs_dcount[qname] ++
+ }
+}
+
+# ------------------------------------------------------------------------
+
+function qsq_start (qname) { # reset statistics for new baseline
+ delete qs_rcount[qname]
+ delete qs_rtime[qname]
+ delete qs_rlentime[qname]
+ delete qs_wcount[qname]
+ delete qs_wtime[qname]
+ delete qs_wlentime[qname]
+ delete qs_dcount[qname]
+ qs_stime[qname] = qs_time ()
+}
+
+# ------------------------------------------------------------------------
+# Various query functions. Each returns the average, taken over the time
+# interval from the last qsq_start(). Most deal with fractions, and so
+# also take a scale parameter (use 100 for percent).
+
+# fraction of time that any request was being serviced
+function qsq_utilization (qname, scale) {
+ elapsed = qs_time() - qs_stime[qname]
+ return (scale * qs_rtime[qname]) / elapsed
+}
+
+# fraction of time that any request was blocked in the wait queue
+function qsq_blocked (qname, scale) {
+ elapsed = qs_time() - qs_stime[qname]
+ return (scale * qs_wtime[qname]) / elapsed
+}
+
+# length of wait queue
+function qsq_wait_queue_length (qname, scale) {
+ elapsed = qs_time() - qs_stime[qname]
+ return (scale * qs_wlentime[qname]) / elapsed
+}
+
+# service time (amount of time per request service)
+function qsq_service_time (qname, scale) {
+ return (scale * qs_rlentime[qname]) / qs_dcount[qname]
+}
+
+# wait time (amount of time in queue + service per request)
+function qsq_wait_time (qname, scale) {
+ return (scale * (qs_rlentime[qname] + qs_wlentime[qname]))
+ / qs_dcount[qname]
+}
+
+# service rate (number of requests served per unit time)
+function qsq_throughput (qname, scale) {
+ elapsed = qs_time() - qs_stime[qname]
+ return (scale * qs_dcount[qname]) / elapsed
+}
+
+
+# ------------------------------------------------------------------------
+
+function qsq_print (qname) {
+ qwl = qsq_wait_queue_length (qname, 1000)
+ printf("%s: %d ops/s, %d.%03d qlen, %d await, %d svctm, %d%% wait, %d%% util\n",
+ qname,
+ qsq_throughput (qname, 1000000), # number of qs_time() units per second
+ qwl/1000, qwl%1000,
+ qsq_wait_time (qname, 1),
+ qsq_service_time (qname, 1),
+ qsq_blocked (qname, 100),
+ qsq_utilization (qname, 100))
+}
git://sourceware.org / systemtap.git / commitdiff