bucketstats

package
v0.0.0-...-4017c26 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2021 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package bucketstats implements easy to use statistics collection and reporting, including bucketized statistics. Statistics start at zero and grow as they are added to.

The statistics provided include totaler (with the Totaler interface), average (with the Averager interface), and distributions (with the Bucketer interface).

Each statistic must have a unique name, "Name". One or more statistics is placed in a structure and registered, with a name, via a call to Register() before being used. The set of the statistics registered can be queried using the registered name or individually.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Register 

func Register(pkgName string, statsGroupName string, statsStruct interface{})

Register and initialize a set of statistics.

statsStruct is a pointer to a structure which has one or more fields holding statistics. It may also contain other fields that are not bucketstats types.

The combination of pkgName and statsGroupName must be unique. pkgName is typically the name of a pacakge and statsGroupName is the name for the group of stats. One or the other, but not both, can be the empty string. Whitespace characters, '"' (double quote), '*' (asterik), and ':' (colon) are not allowed in either name.

func SprintStats 

func SprintStats(stringFmt StatStringFormat, pkgName string, statsGroupName string) (values string)

Print one or more groups of statistics.

The value of all statistics associated with pkgName and statsGroupName are returned as a string, with one statistic per line, according to the specified format.

Use "*" to select all package names with a given group name, all groups with a given package name, or all groups.

func UnRegister 

func UnRegister(pkgName string, statsGroupName string)

UnRegister a set of statistics.

Once unregistered, the same or a different set of statistics can be registered using the same name.

Types

type Average 

type Average struct {
	Name string
	// contains filtered or unexported fields
}

Average counts a number of items and their average size. It supports the Averager interface.

Name must be unique within statistics in the structure. If it is "" then Register() will assign a name based on the name of the field.

func (*Average) Add 

func (this *Average) Add(value uint64)

Add a value to the mean statistics.

func (*Average) AverageGet 

func (this *Average) AverageGet() uint64

func (*Average) CountGet 

func (this *Average) CountGet() uint64

func (*Average) Increment 

func (this *Average) Increment()

Add a value of 1 to the mean statistics.

func (*Average) Sprint 

func (this *Average) Sprint(stringFmt StatStringFormat, pkgName string, statsGroupName string) string

Return a string with the statistic's value in the specified format.

func (*Average) TotalGet 

func (this *Average) TotalGet() uint64

type Averager 

type Averager interface {
	Totaler
	CountGet() (count uint64)
	AverageGet() (avg uint64)
}

An Averager is a Totaler with a average (mean) function added.

This adds a CountGet() function that returns the number of values added as well as an AverageGet() method that returns the average.

type BucketInfo 

type BucketInfo struct {
	Count      uint64
	NominalVal uint64
	MeanVal    uint64
	RangeLow   uint64
	RangeHigh  uint64
}

Holds information for an individual statistics bucket, consisting of:

Count the number of values added to the bucket RangeLow the smallest value mapped to the bucket RangeHigh the largest value mapped to the bucket NominalVal the nominal value of the bucket (sqrt(2)^n or 2^n) MeanVal the mean value of values added to the bucket, assuming 

a uniform distribution

When performing math on these statistics be careful of overflowing a uint64. It may be a good idea to use the "math/big" package.

type BucketLog2Round 

type BucketLog2Round struct {
	Name    string
	NBucket uint
	// contains filtered or unexported fields
}

BucketLog2Round holds bucketized statistics where the stats value is placed in bucket N, determined by round(log2(value) + 1), where round() rounds to the nearest integar and value 0 goes in bucket 0 instead of negative infinity.

NBucket determines the number of buckets and has a maximum value of 65 and a minimum value that is implementation defined (currently 9). If it is less then the minimum it will be changed to the minimum. If NBucket is not set it defaults to 65. It must be set before the statistic is registered and cannot be changed afterward.

Name must be unique within statistics in the structure. If it is "" then Register() will assign a name based on the name of the field.

Example mappings of values to buckets: 

Values  Bucket
     0       0
     1       1
     2       2
 3 - 5       3
6 - 11       4

12 - 22 5 

etc.

Note that value 2^n increments the count in bucket n + 1, but the average of values in bucket n is very slightly larger than 2^n.

func (*BucketLog2Round) Add 

func (this *BucketLog2Round) Add(value uint64)

func (*BucketLog2Round) AverageGet 

func (this *BucketLog2Round) AverageGet() uint64

func (*BucketLog2Round) CountGet 

func (this *BucketLog2Round) CountGet() uint64

func (*BucketLog2Round) DistGet 

func (this *BucketLog2Round) DistGet() []BucketInfo

Return BucketInfo information for all the buckets.

func (*BucketLog2Round) Increment 

func (this *BucketLog2Round) Increment()

Add a value of 1 to the bucketized statistics.

func (*BucketLog2Round) Sprint 

func (this *BucketLog2Round) Sprint(stringFmt StatStringFormat, pkgName string, statsGroupName string) string

Return a string with the statistic's value in the specified format.

func (*BucketLog2Round) TotalGet 

func (this *BucketLog2Round) TotalGet() uint64

type BucketLogRoot2Round 

type BucketLogRoot2Round struct {
	Name    string
	NBucket uint
	// contains filtered or unexported fields
}

BucketLogRoot2Round holds bucketized statistics where the stats value is placed bucket N determined by round(logRoot(2)(value), except that:

value 0 goes in bucket 0 (instead of negative infinity) value 1 goes in bucket 1 (instead of 0) value 2 goes in bucket 2 (instead of 1)

NBucket determines the number of buckets and has a maximum value of 128 and a minimum value that is implementation defined (currently 9). If it is less then the minimum it will be changed to the minimum. If NBucket is not set it defaults to 128. It must be set before the statistic is registered and cannot be changed afterward.

Name must be unique within statistics in the structure. If it is "" then Register() will assign a name based on the name of the field.

Example mappings of values to buckets: 

Values  Bucket
     0       0
     1       1
     2       2
     3       3
     4       4
 5 - 6       5
 7 - 9       6

10 - 13 7 

etc.

Note that a value sqrt(2)^n increments the count in bucket 2 * n, but the average of values in bucket n is slightly larger than sqrt(2)^n.

func (*BucketLogRoot2Round) Add 

func (this *BucketLogRoot2Round) Add(value uint64)

func (*BucketLogRoot2Round) AverageGet 

func (this *BucketLogRoot2Round) AverageGet() uint64

func (*BucketLogRoot2Round) CountGet 

func (this *BucketLogRoot2Round) CountGet() uint64

func (*BucketLogRoot2Round) DistGet 

func (this *BucketLogRoot2Round) DistGet() []BucketInfo

Return BucketInfo information for all the buckets.

func (*BucketLogRoot2Round) Increment 

func (this *BucketLogRoot2Round) Increment()

Add a value of 1 to the bucketized statistics.

func (*BucketLogRoot2Round) Sprint 

func (this *BucketLogRoot2Round) Sprint(stringFmt StatStringFormat, pkgName string, statsGroupName string) string

Return a string with the statistic's value in the specified format.

func (*BucketLogRoot2Round) TotalGet 

func (this *BucketLogRoot2Round) TotalGet() uint64

type Bucketer 

type Bucketer interface {
	Averager
	DistGet() []BucketInfo
}

A Bucketer is a Averager which also tracks the distribution of values.

The number of buckets and the range of values mapped to a bucket depends on the bucket type used.

DistGet() returns the distribution of values across the buckets as an array of BucketInfo.

type StatStringFormat 

type StatStringFormat int
const (
	StatFormatParsable1 StatStringFormat = iota
)

type Total 

type Total struct {
	Name string
	// contains filtered or unexported fields
}

Total is a simple totaler. It supports the Totaler interface.

Name must be unique within statistics in the structure. If it is "" then Register() will assign a name based on the name of the field.

func (*Total) Add 

func (this *Total) Add(value uint64)

func (*Total) Increment 

func (this *Total) Increment()

func (*Total) Sprint 

func (this *Total) Sprint(stringFmt StatStringFormat, pkgName string, statsGroupName string) string

Return a string with the statistic's value in the specified format.

func (*Total) TotalGet 

func (this *Total) TotalGet() uint64

type Totaler 

type Totaler interface {
	Increment()
	Add(value uint64)
	TotalGet() (total uint64)
	Sprint(stringFmt StatStringFormat, pkgName string, statsGroupName string) (values string)
}

A Totaler can be incremented, or added to, and tracks the total value of all values added.

Adding a negative value is not supported.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.