1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin counter n 2.0.4]
[keywords counting]
[keywords histogram]
[keywords statistics]
[keywords tallying]
[moddesc {Counters and Histograms}]
[titledesc {Procedures for counters and histograms}]
[category {Data structures}]
[require Tcl 8]
[require counter [opt 2.0.4]]
[description]
[para]
The [package counter] package provides a counter facility and can
compute statistics and histograms over the collected data.
[list_begin definitions]
[call [cmd ::counter::init] [arg {tag args}]]
This defines a counter with the name [arg tag]. The [arg args]
determines the characteristics of the counter. The [arg args] are
[list_begin definitions]
[def "[option -group] [arg name]"]
Keep a grouped counter where the name of the histogram bucket is
passed into [cmd ::counter::count].
[def "[option -hist] [arg bucketsize]"]
Accumulate the counter into histogram buckets of size
[arg bucketsize]. For example, if the samples are millisecond time
values and [arg bucketsize] is 10, then each histogram bucket
represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 30 msec,
and so on.
[def "[option -hist2x] [arg bucketsize]"]
Accumulate the statistic into histogram buckets. The size of the
first bucket is [arg bucketsize], each other bucket holds values 2
times the size of the previous bucket. For example, if
[arg bucketsize] is 10, then each histogram bucket represents time
values of 0 to 10 msec, 10 to 20 msec, 20 to 40 msec, 40 to 80 msec,
and so on.
[def "[option -hist10x] [arg bucketsize]"]
Accumulate the statistic into histogram buckets. The size of the
first bucket is [arg bucketsize], each other bucket holds values 10
times the size of the previous bucket. For example, if
[arg bucketsize] is 10, then each histogram bucket represents time
values of 0 to 10 msec, 10 to 100 msec, 100 to 1000 msec, and so on.
[def "[option -lastn] [arg N]"]
Save the last [arg N] values of the counter to maintain a "running
average" over the last [arg N] values.
[def "[option -timehist] [arg secsPerMinute]"]
Keep a time-based histogram. The counter is summed into a histogram
bucket based on the current time. There are 60 per-minute buckets
that have a size determined by [arg secsPerMinute], which is normally
60, but for testing purposes can be less. Every "hour" (i.e., 60
"minutes") the contents of the per-minute buckets are summed into the
next hourly bucket. Every 24 "hours" the contents of the per-hour
buckets are summed into the next daily bucket. The counter package
keeps all time-based histograms in sync, so the first
[arg secsPerMinute] value seen by the package is used for all
subsequent time-based histograms.
[list_end]
[call [cmd ::counter::count] [arg tag] [opt [arg delta]] [opt [arg instance]]]
Increment the counter identified by [arg tag]. The default increment
is 1, although you can increment by any value, integer or real, by
specifying [arg delta]. You must declare each counter with
[cmd ::counter::init] to define the characteristics of counter before
you start to use it. If the counter type is [option -group], then the
counter identified by [arg instance] is incremented.
[call [cmd ::counter::start] [arg {tag instance}]]
Record the starting time of an interval. The [arg tag] is the name of
the counter defined as a [option -hist] value-based histogram. The
[arg instance] is used to distinguish this interval from any other
intervals that might be overlapping this one.
[call [cmd ::counter::stop] [arg {tag instance}]]
Record the ending time of an interval. The delta time since the
corresponding [cmd ::counter::start] call for [arg instance] is
recorded in the histogram identified by [arg tag].
[call [cmd ::counter::get] [arg {tag args}]]
Return statistics about a counter identified by [arg tag]. The
[arg args] determine what value to return:
[list_begin definitions]
[def [option -total]]
Return the total value of the counter. This is the default if
[arg args] is not specified.
[def [option -totalVar]]
Return the name of the total variable. Useful for specifying with
-textvariable in a Tk widget.
[def [option -N]]
Return the number of samples accumulated into the counter.
[def [option -avg]]
Return the average of samples accumulated into the counter.
[def [option -avgn]]
Return the average over the last [arg N] samples taken. The [arg N]
value is set in the [cmd ::counter::init] call.
[def "[option -hist] [arg bucket]"]
If [arg bucket] is specified, then the value in that bucket of the
histogram is returned. Otherwise the complete histogram is returned
in array get format sorted by bucket.
[def [option -histVar]]
Return the name of the histogram array variable.
[def [option -histHour]]
Return the complete hourly histogram in array get format sorted by
bucket.
[def [option -histHourVar]]
Return the name of the hourly histogram array variable.
[def [option -histDay]]
Return the complete daily histogram in array get format sorted by
bucket.
[def [option -histDayVar]]
Return the name of the daily histogram array variable.
[def [option -resetDate]]
Return the clock seconds value recorded when the
counter was last reset.
[def [option -all]]
Return an array get of the array used to store the counter. This
includes the total, the number of samples (N), and any type-specific
information. This does not include the histogram array.
[list_end]
[call [cmd ::counter::exists] [arg tag]]
Returns 1 if the counter is defined.
[call [cmd ::counter::names]]
Returns a list of all counters defined.
[call [cmd ::counter::histHtmlDisplay] [arg {tag args}]]
Generate HTML to display a histogram for a counter. The [arg args]
control the format of the display. They are:
[list_begin definitions]
[def "[option -title] [arg string]"]
Label to display above bar chart
[def "[option -unit] [arg unit]"]
Specify [const minutes], [const hours], or [const days] for the
time-base histograms. For value-based histograms, the [arg unit] is
used in the title.
[def "[option -images] [arg url]"]
URL of /images directory.
[def "[option -gif] [arg filename]"]
Image for normal histogram bars. The [arg filename] is relative to
the [option -images] directory.
[def "[option -ongif] [arg filename]"]
Image for the active histogram bar. The [arg filename] is relative to
the [option -images] directory.
[def "[option -max] [arg N]"]
Maximum number of value-based buckets to display.
[def "[option -height] [arg N]"]
Pixel height of the highest bar.
[def "[option -width] [arg N]"]
Pixel width of each bar.
[def "[option -skip] [arg N]"]
Buckets to skip when labeling value-based histograms.
[def "[option -format] [arg string]"]
Format used to display labels of buckets.
[def "[option -text] [arg boolean]"]
If 1, a text version of the histogram is dumped, otherwise a graphical
one is generated.
[list_end]
[call [cmd ::counter::reset] [arg {tag args}]]
Resets the counter with the name [arg tag] to an initial state. The
[arg args] determine the new characteristics of the counter. They have
the same meaning as described for [cmd ::counter::init].
[list_end]
[vset CATEGORY counter]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
|
