Debian Codegraph @

tapset/queue_stats.stp

raw
1 # qstats.stp: Queue statistics gathering tapset
2 /* <tapsetdescription>
3 * The queue_stats tapset provides functions that,
4 * given notifications of elementary queuing events (wait, run, done),
5 * tracks averages such as queue length, service and wait times,
6 * utilization.
7 *
8 * The functions qs_wait(), qs_run(), and qs_done() should be called
9 * from appropriate probes, in sequence.
10 *
11 * Functions with the prefix qsq_ are for querying the statistics averaged
12 * since the first queue operation (or when qsq_start() was called).
13 * Since statistics are often fractional, a scale parameter is used to
14 * multiply the result to a more useful scale. For some fractions, a scale
15 * of 100 will usefully return percentage numbers.
16 * </tapsetdescription>
17 */
18
19 # ------------------------------------------------------------------------
20
21 # The default timing function: microseconds. This function could
22 # go into a separate file (say, qstats_qs_time.stp), so that a user
23 # script can override it with another definition.
24
25 /* XXX: docstring */
26 function qs_time () { return gettimeofday_us () }
27
28 # ------------------------------------------------------------------------
29
30 @__private30 global qs_wtime, qs_wlentime, qs_wcount
31 @__private30 global qs_rtime, qs_rlentime, qs_rcount
32 @__private30 global qs_stime, qs_utime, qs_dcount
33
34 # ------------------------------------------------------------------------
35
36 @__private30 function _qs_update (qname) {
37 now = qs_time ()
38 then = qs_utime[qname]; if (! then) { then = now }
39 delta = now-then
40
41 qs_wtime[qname] += qs_wcount[qname] ? delta : 0
42 qs_wlentime[qname] += qs_wcount[qname] * delta
43 qs_rtime[qname] += qs_rcount[qname] ? delta : 0
44 qs_rlentime[qname] += qs_rcount[qname] * delta
45 qs_utime[qname] = now
46 }
47
48 /**
49 * sfunction qs_wait - Function to record enqueue requests
50 * @qname: the name of the queue requesting enqueue
51 *
52 * Description: This function records that a new request
53 * was enqueued for the given queue name.
54 */
55 function qs_wait (qname:string) { # enqueueing request
56 _qs_update (qname)
57 qs_wcount[qname] ++
58 }
59
60 /**
61 * sfunction qs_run - Function to record being moved from wait queue to being serviced
62 * @qname: the name of the service being moved and started
63 *
64 * Description: This function records that the previous enqueued
65 * request was removed from the given wait queue and is now
66 * being serviced.
67 */
68 function qs_run (qname:string) { # starting to service request
69 _qs_update (qname)
70 if (qs_wcount[qname] > 0) {
71 qs_wcount[qname] --
72 qs_rcount[qname] ++
73 }
74 }
75
76 /**
77 * sfunction qs_done - Function to record finishing request
78 * @qname: the name of the service that finished
79 *
80 * Description: This function records that a request
81 * originally from the given queue has completed being
82 * serviced.
83 */
84 function qs_done (qname:string) { # done servicing request
85 _qs_update (qname)
86 if (qs_rcount[qname] > 0) {
87 qs_rcount[qname] --
88 qs_dcount[qname] ++
89 }
90 }
91
92 # ------------------------------------------------------------------------
93
94 /**
95 * sfunction qsq_start - Function to reset the stats for a queue
96 * @qname: the name of the service that finished
97 *
98 * Description: This function resets the statistics counters for the given
99 * queue, and restarts tracking from the moment the function was called.
100 * This function is also used to create intialize a queue.
101 */
102 function qsq_start (qname:string) { # reset statistics for new baseline
103 qs_rcount[qname] = 0
104 delete qs_rtime[qname]
105 delete qs_rlentime[qname]
106 qs_wcount[qname] = 0
107 delete qs_wtime[qname]
108 delete qs_wlentime[qname]
109 delete qs_dcount[qname]
110 delete qs_utime[qname]
111 qs_stime[qname] = qs_time ()
112 }
113
114 # ------------------------------------------------------------------------
115 # Various query functions. Each returns the average, taken over the time
116 # interval from the last qsq_start(). Most deal with fractions, and so
117 # also take a scale parameter (use 100 for percent).
118
119 /**
120 * sfunction qsq_utilization - Fraction of time that any request was being serviced
121 * @qname: queue name
122 * @scale: scale variable to take account for interval fraction
123 *
124 * Description: This function returns the average time in microseconds
125 * that at least one request was being serviced.
126 */
127 function qsq_utilization:long (qname:string, scale:long) {
128 _qs_update (qname)
129 elapsed = qs_time() - qs_stime[qname]
130 return (scale * qs_rtime[qname]) / elapsed
131 }
132
133 # fraction of time that any request was blocked in the wait queue
134
135 /**
136 * sfunction qsq_blocked - Returns the time reqest was on the wait queue
137 * @qname: queue name
138 * @scale: scale variable to take account for interval fraction
139 *
140 * Description: This function returns the fraction of elapsed time during
141 * which one or more requests were on the wait queue.
142 */
143 function qsq_blocked:long (qname:string, scale:long) {
144 _qs_update (qname)
145 elapsed = qs_time() - qs_stime[qname]
146 return (scale * qs_wtime[qname]) / elapsed
147 }
148
149 # length of wait queue
150 /**
151 * sfunction qsq_wait_queue_length - length of wait queue
152 * @qname: queue name
153 * @scale: scale variable to take account for interval fraction
154 *
155 * Description: This function returns the average length of the wait queue
156 */
157 function qsq_wait_queue_length:long (qname:string, scale:long) {
158 _qs_update (qname)
159 elapsed = qs_time() - qs_stime[qname]
160 return (scale * qs_wlentime[qname]) / elapsed
161 }
162
163 /**
164 * sfunction qsq_service_time - Amount of time per request service
165 * @qname: queue name
166 * @scale: scale variable to take account for interval fraction
167 *
168 * Description: This function returns the average time in microseconds
169 * required to service a request once it is removed from the wait queue.
170 */
171 function qsq_service_time:long (qname:string, scale:long) {
172 _qs_update (qname)
173 return (scale * qs_rlentime[qname]) / qs_dcount[qname]
174 }
175
176 /**
177 * sfunction qsq_wait_time - Amount of time in queue + service per request
178 * @qname: queue name
179 * @scale: scale variable to take account for interval fraction
180 *
181 * Description: This function returns the average time in microseconds
182 * that it took for a request to be serviced (qs_wait() to qa_done()).
183 */
184 function qsq_wait_time:long (qname:string, scale:long) {
185 _qs_update (qname)
186 return (scale * (qs_rlentime[qname] + qs_wlentime[qname]))
187 / qs_dcount[qname]
188 }
189
190 /**
191 * sfunction qsq_throughput - Number of requests served per unit time
192 * @qname: queue name
193 * @scale: scale variable to take account for interval fraction
194 *
195 * Description: This function returns the average number or requests
196 * served per microsecond.
197 */
198 function qsq_throughput:long (qname:string, scale:long) {
199 _qs_update (qname)
200 elapsed = qs_time() - qs_stime[qname]
201 return (scale * qs_dcount[qname]) / elapsed
202 }
203
204
205 # ------------------------------------------------------------------------
206
207 /**
208 * sfunction qsq_print - Prints a line of statistics for the given queue
209 * @qname: queue name
210 *
211 * Description: This function prints a line containing the following
212 * statistics for the given queue:
213 * the queue name,
214 * the average rate of requests per second,
215 * the average wait queue length,
216 * the average time on the wait queue,
217 * the average time to service a request,
218 * the percentage of time the wait queue was used,
219 * and the percentage of time request was being serviced.
220 */
221 function qsq_print (qname:string) {
222 qt = qsq_throughput (qname, 1000000000) # 1000 * (number of requests served per second)
223 qwl = qsq_wait_queue_length (qname, 1000)
224 printf("%s: %d.%03d ops/s, %d.%03d qlen, %d await, %d svctm, %d%% wait, %d%% util\n",
225 qname,
226 qt/1000, qt%1000,
227 qwl/1000, qwl%1000,
228 qsq_wait_time (qname, 1),
229 qsq_service_time (qname, 1),
230 qsq_blocked (qname, 100),
231 qsq_utilization (qname, 100))
232 }
233
234 /* What follows in an example form src/testsuite/systemtap.samples/queue_demo.stp
235 * It uses the randomize feature of the timer probe to simulate queuing activity.
236 *
237 * probe begin {
238 * qsq_start ("block-read")
239 * qsq_start ("block-write")
240 * }
241 *
242 * probe timer.ms(3500), end {
243 * qsq_print ("block-read")
244 * qsq_start ("block-read")
245 * qsq_print ("block-write")
246 * qsq_start ("block-write")
247 * }
248 *
249 * probe timer.ms(10000) {
250 * exit()
251 * }
252 *
253 * // synthesize queue work/service using three randomized "threads" for each queue.
254 * global tc
255 *
256 * function qs_doit (thread, name) {
257 * n = tc[thread] = (tc[thread]+1) % 3 //per-thread state counter
258 * if (n==1) qs_wait (name)
259 * else if (n==2) qs_run (name)
260 * else if (n==0) qs_done (name)
261 * }
262 *
263 * probe timer.ms(100).randomize(100) { qs_doit (0, "block-read") }
264 * probe timer.ms(100).randomize(100) { qs_doit (1, "block-read") }
265 * probe timer.ms(100).randomize(100) { qs_doit (2, "block-read") }
266 * probe timer.ms(100).randomize(100) { qs_doit (3, "block-write") }
267 * probe timer.ms(100).randomize(100) { qs_doit (4, "block-write") }
268 * probe timer.ms(100).randomize(100) { qs_doit (5, "block-write") }
269 *
270 * //This prints:
271 * block-read: 9 ops/s, 1.090 qlen, 215749 await, 96382 svctm, 69% wait, 64% util
272 * block-write: 9 ops/s, 0.992 qlen, 208485 await, 103150 svctm, 69% wait, 61% util
273 * block-read: 9 ops/s, 0.968 qlen, 197411 await, 97762 svctm, 63% wait, 63% util
274 * block-write: 8 ops/s, 0.930 qlen, 202414 await, 93870 svctm, 60% wait, 56% util
275 * block-read: 8 ops/s, 0.744 qlen, 192957 await, 99995 svctm, 58% wait, 62% util
276 * block-write: 9 ops/s, 0.861 qlen, 193857 await, 101573 svctm, 56% wait, 64% util
277 */