Manual Pages for UNIX Darwin command on man counter

counter(n) Counters and Histograms counter(n)

NAME

counter - Procedures for counters and histograms

SYNOPSIS

package require TTccll 88 package require ccoouunntteerr ??22..00..22?? ::::ccoouunntteerr::::iinniitt tag args ::::ccoouunntteerr::::ccoouunntt tag ?delta? ?instance? ::::ccoouunntteerr::::ssttaarrtt tag instance ::::ccoouunntteerr::::ssttoopp tag instance ::::ccoouunntteerr::::ggeett tag args ::::ccoouunntteerr::::eexxiissttss tag ::::ccoouunntteerr::::nnaammeess ::::ccoouunntteerr::::hhiissttHHttmmllDDiissppllaayy tag args ::::ccoouunntteerr::::rreesseett tag args

DESCRIPTION

The ccoouunntteerr package provides a counter facility and can compute statis-

tics and histograms over the collected data. ::::ccoouunntteerr::::iinniitt tag args

This defines a counter with the name tag. The args determines

the characteristics of the counter. The args are

-ggrroouupp name

Keep a grouped counter where the name of the histogram

bucket is passed into ::::ccoouunntteerr::::ccoouunntt.

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

-hhiisstt22xx 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 bucket represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 40 msec, 40 to 80 msec, and so on.

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

-llaassttnn N

Save the last N values of the counter to maintain a "run-

ning average" over the last N values.

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

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

::::ccoouunntteerr::::iinniitt to define the characteristics of counter before

you start to use it. If the counter type is -ggrroouupp, then the

counter identified by instance is incremented.

::::ccoouunntteerr::::ssttaarrtt tag instance Record the starting time of an interval. The tag is the name of

the counter defined as a -hhiisstt value-based histogram. The

instance is used to distinguish this interval from any other intervals that might be overlapping this one. ::::ccoouunntteerr::::ssttoopp tag instance Record the ending time of an interval. The delta time since the corresponding ::::ccoouunntteerr::::ssttaarrtt call for instance is recorded in the histogram identified by tag. ::::ccoouunntteerr::::ggeett tag args

Return statistics about a counter identified by tag. The args

determine what value to return:

-ttoottaall Return the total value of the counter. This is the

default if args is not specified.

-ttoottaallVVaarr

Return the name of the total variable. Useful for speci-

fying with -textvariable in a Tk widget.

-NN Return the number of samples accumulated into the

counter.

-aavvgg Return the average of samples accumulated into the

counter.

-aavvggnn Return the average over the last N samples taken. The N

value is set in the ::::ccoouunntteerr::::iinniitt call.

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

-hhiissttVVaarr

Return the name of the histogram array variable.

-hhiissttHHoouurr

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

-hhiissttHHoouurrVVaarr

Return the name of the hourly histogram array variable.

-hhiissttDDaayy

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

-hhiissttDDaayyVVaarr

Return the name of the daily histogram array variable.

-rreesseettDDaattee

Return the clock seconds value recorded when the counter

was last reset.

-aallll 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. ::::ccoouunntteerr::::eexxiissttss tag

Returns 1 if the counter is defined.

::::ccoouunntteerr::::nnaammeess

Returns a list of all counters defined.

::::ccoouunntteerr::::hhiissttHHttmmllDDiissppllaayy tag args

Generate HTML to display a histogram for a counter. The args

control the format of the display. They are:

-ttiittllee string

Label to display above bar chart

-uunniitt unit

Specify mmiinnuutteess, hhoouurrss, or ddaayyss for the time-base his-

tograms. For value-based histograms, the unit is used in

the title.

-iimmaaggeess url

URL of /images directory.

-ggiiff filename

Image for normal histogram bars. The filename is rela-

tive to the -iimmaaggeess directory.

-oonnggiiff filename

Image for the active histogram bar. The filename is rel-

ative to the -iimmaaggeess directory.

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

-hheeiigghhtt N

Pixel height of the highest bar.

-wwiiddtthh N

Pixel width of each bar.

-sskkiipp N

Buckets to skip when labeling value-based histograms.

-ffoorrmmaatt string

Format used to display labels of buckets.

-tteexxtt boolean

If 1, a text version of the histogram is dumped, other-

wise a graphical one is generated. ::::ccoouunntteerr::::rreesseett 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 ::::ccoouunntteerr::::iinniitt. KKEEYYWWOORRDDSS counting, histogram, statistics, tallying