1counter(n) Counters and Histograms counter(n)
2______________________________________________________________________________
6
8 counter - Procedures for counters and histograms
9
11 package require Tcl 8
12 package require counter ?2.0.4?
14 ::counter::init tag args
16 ::counter::count tag ?delta? ?instance?
18 ::counter::start tag instance
20 ::counter::stop tag instance
22 ::counter::get tag args
24 ::counter::exists tag
26 ::counter::names
28 ::counter::histHtmlDisplay tag args
30 ::counter::reset tag args
32_________________________________________________________________
34
36 The counter package provides a counter facility and can compute statis‐
37 tics and histograms over the collected data.
38 ::counter::init tag args
40 This defines a counter with the name tag. The args determines
41 the characteristics of the counter. The args are
42 -group name
44 Keep a grouped counter where the name of the histogram
45 bucket is passed into ::counter::count.
46 -hist bucketsize
48 Accumulate the counter into histogram buckets of size
49 bucketsize. For example, if the samples are millisecond
50 time values and bucketsize is 10, then each histogram
51 bucket represents time values of 0 to 10 msec, 10 to 20
52 msec, 20 to 30 msec, and so on.
53 -hist2x bucketsize
55 Accumulate the statistic into histogram buckets. The
56 size of the first bucket is bucketsize, each other bucket
57 holds values 2 times the size of the previous bucket.
58 For example, if bucketsize is 10, then each histogram
59 bucket represents time values of 0 to 10 msec, 10 to 20
60 msec, 20 to 40 msec, 40 to 80 msec, and so on.
61 -hist10x bucketsize
63 Accumulate the statistic into histogram buckets. The
64 size of the first bucket is bucketsize, each other bucket
65 holds values 10 times the size of the previous bucket.
66 For example, if bucketsize is 10, then each histogram
67 bucket represents time values of 0 to 10 msec, 10 to 100
68 msec, 100 to 1000 msec, and so on.
69 -lastn N
71 Save the last N values of the counter to maintain a "run‐
72 ning average" over the last N values.
73 -timehist secsPerMinute
75 Keep a time-based histogram. The counter is summed into
76 a histogram bucket based on the current time. There are
77 60 per-minute buckets that have a size determined by sec‐
78 sPerMinute, which is normally 60, but for testing pur‐
79 poses can be less. Every "hour" (i.e., 60 "minutes") the
80 contents of the per-minute buckets are summed into the
81 next hourly bucket. Every 24 "hours" the contents of the
82 per-hour buckets are summed into the next daily bucket.
83 The counter package keeps all time-based histograms in
84 sync, so the first secsPerMinute value seen by the pack‐
85 age is used for all subsequent time-based histograms.
86 ::counter::count tag ?delta? ?instance?
88 Increment the counter identified by tag. The default increment
89 is 1, although you can increment by any value, integer or real,
90 by specifying delta. You must declare each counter with
91 ::counter::init to define the characteristics of counter before
92 you start to use it. If the counter type is -group, then the
93 counter identified by instance is incremented.
94 ::counter::start tag instance
96 Record the starting time of an interval. The tag is the name of
97 the counter defined as a -hist value-based histogram. The
98 instance is used to distinguish this interval from any other
99 intervals that might be overlapping this one.
100 ::counter::stop tag instance
102 Record the ending time of an interval. The delta time since the
103 corresponding ::counter::start call for instance is recorded in
104 the histogram identified by tag.
105 ::counter::get tag args
107 Return statistics about a counter identified by tag. The args
108 determine what value to return:
109 -total Return the total value of the counter. This is the
111 default if args is not specified.
112 -totalVar
114 Return the name of the total variable. Useful for speci‐
115 fying with -textvariable in a Tk widget.
116 -N Return the number of samples accumulated into the
118 counter.
119 -avg Return the average of samples accumulated into the
121 counter.
122 -avgn Return the average over the last N samples taken. The N
124 value is set in the ::counter::init call.
125 -hist bucket
127 If bucket is specified, then the value in that bucket of
128 the histogram is returned. Otherwise the complete his‐
129 togram is returned in array get format sorted by bucket.
130 -histVar
132 Return the name of the histogram array variable.
133 -histHour
135 Return the complete hourly histogram in array get format
136 sorted by bucket.
137 -histHourVar
139 Return the name of the hourly histogram array variable.
140 -histDay
142 Return the complete daily histogram in array get format
143 sorted by bucket.
144 -histDayVar
146 Return the name of the daily histogram array variable.
147 -resetDate
149 Return the clock seconds value recorded when the counter
150 was last reset.
151 -all Return an array get of the array used to store the
153 counter. This includes the total, the number of samples
154 (N), and any type-specific information. This does not
155 include the histogram array.
156 ::counter::exists tag
158 Returns 1 if the counter is defined.
159 ::counter::names
161 Returns a list of all counters defined.
162 ::counter::histHtmlDisplay tag args
164 Generate HTML to display a histogram for a counter. The args
165 control the format of the display. They are:
166 -title string
168 Label to display above bar chart
169 -unit unit
171 Specify minutes, hours, or days for the time-base his‐
172 tograms. For value-based histograms, the unit is used in
173 the title.
174 -images url
176 URL of /images directory.
177 -gif filename
179 Image for normal histogram bars. The filename is rela‐
180 tive to the -images directory.
181 -ongif filename
183 Image for the active histogram bar. The filename is rel‐
184 ative to the -images directory.
185 -max N Maximum number of value-based buckets to display.
187 -height N
189 Pixel height of the highest bar.
190 -width N
192 Pixel width of each bar.
193 -skip N
195 Buckets to skip when labeling value-based histograms.
196 -format string
198 Format used to display labels of buckets.
199 -text boolean
201 If 1, a text version of the histogram is dumped, other‐
202 wise a graphical one is generated.
203 ::counter::reset tag args
205 Resets the counter with the name tag to an initial state. The
206 args determine the new characteristics of the counter. They have
207 the same meaning as described for ::counter::init.
208
210 This document, and the package it describes, will undoubtedly contain
211 bugs and other problems. Please report such in the category counter of
212 the Tcllib SF Trackers [http://source‐
213 forge.net/tracker/?group_id=12883]. Please also report any ideas for
214 enhancements you may have for either package and/or documentation.
215
217 counting, histogram, statistics, tallying
218counter 2.0.4 counter(n)