1counter(n)                  Counters and Histograms                 counter(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       counter - Procedures for counters and histograms
9

SYNOPSIS

11       package require Tcl  8
12
13       package require counter  ?2.0.4?
14
15       ::counter::init tag args
16
17       ::counter::count tag ?delta? ?instance?
18
19       ::counter::start tag instance
20
21       ::counter::stop tag instance
22
23       ::counter::get tag args
24
25       ::counter::exists tag
26
27       ::counter::names
28
29       ::counter::histHtmlDisplay tag args
30
31       ::counter::reset tag args
32
33______________________________________________________________________________
34

DESCRIPTION

36       The counter package provides a counter facility and can compute statis‐
37       tics and histograms over the collected data.
38
39       ::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
43              -group name
44                     Keep  a  grouped  counter where the name of the histogram
45                     bucket is passed into ::counter::count.
46
47              -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
54              -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
62              -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
70              -lastn N
71                     Save the last N values of the counter to maintain a "run‐
72                     ning average" over the last N values.
73
74              -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
87       ::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
95       ::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
101       ::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
106       ::counter::get tag args
107              Return  statistics  about a counter identified by tag.  The args
108              determine what value to return:
109
110              -total Return the total value  of  the  counter.   This  is  the
111                     default if args is not specified.
112
113              -totalVar
114                     Return the name of the total variable.  Useful for speci‐
115                     fying with -textvariable in a Tk widget.
116
117              -N     Return  the  number  of  samples  accumulated  into   the
118                     counter.
119
120              -avg   Return  the  average  of  samples  accumulated  into  the
121                     counter.
122
123              -avgn  Return the average over the last N samples taken.  The  N
124                     value is set in the ::counter::init call.
125
126              -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
131              -histVar
132                     Return the name of the histogram array variable.
133
134              -histHour
135                     Return  the complete hourly histogram in array get format
136                     sorted by bucket.
137
138              -histHourVar
139                     Return the name of the hourly histogram array variable.
140
141              -histDay
142                     Return the complete daily histogram in array  get  format
143                     sorted by bucket.
144
145              -histDayVar
146                     Return the name of the daily histogram array variable.
147
148              -resetDate
149                     Return  the clock seconds value recorded when the counter
150                     was last reset.
151
152              -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
157       ::counter::exists tag
158              Returns 1 if the counter is defined.
159
160       ::counter::names
161              Returns a list of all counters defined.
162
163       ::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
167              -title string
168                     Label to display above bar chart
169
170              -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
175              -images url
176                     URL of /images directory.
177
178              -gif filename
179                     Image for normal histogram bars.  The filename  is  rela‐
180                     tive to the -images directory.
181
182              -ongif filename
183                     Image for the active histogram bar.  The filename is rel‐
184                     ative to the -images directory.
185
186              -max N Maximum number of value-based buckets to display.
187
188              -height N
189                     Pixel height of the highest bar.
190
191              -width N
192                     Pixel width of each bar.
193
194              -skip N
195                     Buckets to skip when labeling value-based histograms.
196
197              -format string
198                     Format used to display labels of buckets.
199
200              -text boolean
201                     If 1, a text version of the histogram is  dumped,  other‐
202                     wise a graphical one is generated.
203
204       ::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

BUGS, IDEAS, FEEDBACK

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  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
213       also report any ideas for enhancements you may have for either  package
214       and/or documentation.
215
216       When proposing code changes, please provide unified diffs, i.e the out‐
217       put of diff -u.
218
219       Note further that  attachments  are  strongly  preferred  over  inlined
220       patches.  Attachments  can  be  made  by  going to the Edit form of the
221       ticket immediately after its creation, and  then  using  the  left-most
222       button in the secondary navigation bar.
223

KEYWORDS

225       counting, histogram, statistics, tallying
226

CATEGORY

228       Data structures
229
230
231
232tcllib                               2.0.4                          counter(n)
Impressum