NAME

       ::counter - Procedures for counters and histograms.


SYNOPSIS

_________________________________________________________________

       counter::init tag args

       counter::count tag {delta 1} args

       counter::reset tag

       counter::get tag args

       counter::start tag

       counter::stop tag

       counter::exists tag

       counter::names tag

       counter::histHtmlDisplay tag args
_________________________________________________________________


DESCRIPTION

       The  ::counter package provides a counter facility and can
       compute statistics 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 his­
              togram 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.

              other  bucket  holds values 2 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 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
              "running 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 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 buck­
              ets 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
              package  is used for all subsequent time-based his­
              tograms.

       counter::count tag {delta 1} {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  incre­
              mented.

       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

              that might be overlapping this one.

       counter::stop tag instance
              Record  the  ending time of an interval.  The delta
              time since the corresponding  countStart  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.

       -totalVar
              Return the name of the total variable.  Useful  for
              specifying 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 histogram 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 vari­
              able.

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

       -histDayVar
              Return  the  name  of  the  daily  histogram  array


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

       -title string
              Label to display above bar chart

       -unit unit
              Specify  minutes,  hours, or days for the time-base
              histograms.  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
              relative to the -images directory.

       -ongif filename
              Image for the active histogram bar.   The  filename
              is relative 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.

              Buckets  to  skip  when  labeling  value-based his­
              tograms.

       -format string
              Format used to display labels of buckets.

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


Man(1) output converted with man2html