From 2a99f48ff1f873f537784d6f70d7641ada1ed7bd Mon Sep 17 00:00:00 2001 From: fche Date: Tue, 14 Feb 2006 22:12:07 +0000 Subject: 2006-02-14 Frank Ch. Eigler * stapfuncs.5.in: Document new queue_stats tapset. * elaborate.cxx (*): Put "while:" clarification messages before a thrown semantic error. * staptree.cxx (print_format::string_to_components): Correct parse of "%%" formatting element. * queue_stats.stp: New tapset. * systemtap.samples/queue_demo.*: New test. --- stapfuncs.5.in | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) (limited to 'stapfuncs.5.in') diff --git a/stapfuncs.5.in b/stapfuncs.5.in index 3ad19642..b6b663f3 100644 --- a/stapfuncs.5.in +++ b/stapfuncs.5.in @@ -164,6 +164,58 @@ errno_str:string (e:long) 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 -- cgit