


counter(n)           Counters and Histograms           counter(n)


______________________________________________________________________________

NAME
       counter - Procedures for counters and histograms

SYNOPSIS
       package require Tcl  8

       package require counter  ?2.0.4?

       ::counter::init tag args

       ::counter::count tag ?delta? ?instance?

       ::counter::start tag instance

       ::counter::stop tag instance

       ::counter::get tag args

       ::counter::exists tag

       ::counter::names

       ::counter::histHtmlDisplay tag args

       ::counter::reset tag args

_________________________________________________________________

DESCRIPTION
       The counter package provides a counter facility and can compute statis-
       tics and histograms over the collected data.

       ::counter::init tag args
              This defines a counter with the name tag.  The  args  determines
              the characteristics of the counter.  The args are

              -group name
                     Keep  a  grouped  counter where the name of the histogram
                     bucket is passed into ::counter::count.

              -hist bucketsize
                     Accumulate the counter into  histogram  buckets  of  size
                     bucketsize.   For example, if the samples are millisecond
                     time values and 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.

              -hist2x bucketsize
                     Accumulate the statistic  into  histogram  buckets.   The
                     size of the first bucket is bucketsize, each other bucket
                     holds values 2 times the size  of  the  previous  bucket.
                     For  example,  if  bucketsize  is 10, then each histogram



counter                       2.0.4                             1





counter(n)           Counters and Histograms           counter(n)


                     bucket represents time values of 0 to 10 msec, 10  to  20
                     msec, 20 to 40 msec, 40 to 80 msec, and so on.

              -hist10x bucketsize
                     Accumulate  the  statistic  into  histogram buckets.  The
                     size of the first bucket is bucketsize, each other bucket
                     holds  values  10  times the size of the previous bucket.
                     For example, if 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.

              -lastn N
                     Save the last N values of the counter to maintain a "run-
                     ning average" over the last N values.

              -timehist 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 sec-
                     sPerMinute, which is normally 60, but  for  testing  pur-
                     poses 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 secsPerMinute value seen by the  pack-
                     age is used for all subsequent time-based histograms.

       ::counter::count tag ?delta? ?instance?
              Increment  the counter identified by tag.  The default increment
              is 1, although you can increment by any value, integer or  real,
              by  specifying  delta.   You  must  declare  each  counter  with
              ::counter::init to define the characteristics of counter  before
              you  start  to  use it.  If the counter type is -group, then the
              counter identified by instance is incremented.

       ::counter::start tag instance
              Record the starting time of an interval.  The tag is the name of
              the  counter  defined  as  a  -hist  value-based histogram.  The
              instance is used to distinguish this  interval  from  any  other
              intervals that might be overlapping this one.

       ::counter::stop tag instance
              Record the ending time of an interval.  The delta time since the
              corresponding ::counter::start call for instance is recorded  in
              the histogram identified by tag.

       ::counter::get tag args
              Return  statistics  about a counter identified by tag.  The args
              determine what value to return:

              -total Return the total value  of  the  counter.   This  is  the
                     default if args is not specified.




counter                       2.0.4                             2





counter(n)           Counters and Histograms           counter(n)


              -totalVar
                     Return the name of the total variable.  Useful for speci-
                     fying with -textvariable in a Tk widget.

              -N     Return  the  number  of  samples  accumulated  into   the
                     counter.

              -avg   Return  the  average  of  samples  accumulated  into  the
                     counter.

              -avgn  Return the average over the last N samples taken.  The  N
                     value is set in the ::counter::init call.

              -hist bucket
                     If  bucket is specified, then the value in that bucket of
                     the histogram is returned.  Otherwise the  complete  his-
                     togram  is returned in array get format sorted by bucket.

              -histVar
                     Return the name of the histogram array variable.

              -histHour
                     Return the complete hourly histogram in array get  format
                     sorted by bucket.

              -histHourVar
                     Return the name of the hourly histogram array variable.

              -histDay
                     Return  the  complete daily histogram in array get format
                     sorted by bucket.

              -histDayVar
                     Return the name of the daily histogram array variable.

              -resetDate
                     Return the clock seconds value recorded when the  counter
                     was last reset.

              -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.

       ::counter::exists tag
              Returns 1 if the counter is defined.

       ::counter::names
              Returns a list of all counters defined.

       ::counter::histHtmlDisplay tag args
              Generate HTML to display a histogram for a  counter.   The  args
              control the format of the display.  They are:




counter                       2.0.4                             3





counter(n)           Counters and Histograms           counter(n)


              -title string
                     Label to display above bar chart

              -unit unit
                     Specify  minutes,  hours,  or days for the time-base his-
                     tograms.  For value-based histograms, the unit is used in
                     the title.

              -images url
                     URL of /images directory.

              -gif filename
                     Image  for  normal histogram bars.  The filename is rela-
                     tive to the -images directory.

              -ongif filename
                     Image for the active histogram bar.  The filename is rel-
                     ative to the -images directory.

              -max N Maximum number of value-based buckets to display.

              -height N
                     Pixel height of the highest bar.

              -width N
                     Pixel width of each bar.

              -skip N
                     Buckets to skip when labeling value-based histograms.

              -format string
                     Format used to display labels of buckets.

              -text boolean
                     If  1,  a text version of the histogram is dumped, other-
                     wise a graphical one is generated.

       ::counter::reset tag args
              Resets the counter with the name tag to an  initial  state.  The
              args determine the new characteristics of the counter. They have
              the same meaning as described for ::counter::init.


BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs and other problems.  Please report such in the category counter of
       the         Tcllib         SF         Trackers          [http://source-
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       counting, histogram, statistics, tallying





counter                       2.0.4                             4





counter(n)           Counters and Histograms           counter(n)


CATEGORY
       Data structures























































counter                       2.0.4                             5


