instruments: github.com/heroku/instruments Index | Examples | Files | Directories

package instruments

import "github.com/heroku/instruments"

Package instruments allows you to collects metrics over discrete time intervals.

Collected metrics will only reflect observations from last time window only, rather than including observations from prior windows, contrary to EWMA based metrics. 

timer := instruments.NewTimer(-1)

registry := reporter.NewRegistry()
registry.Register("processing-time", timer)

go reporter.Log("process", registry, time.Minute)

timer.Time(func() {
  ...
})

Instruments support two types of instruments: Discrete instruments return a single value, and Sample instruments a sorted array of values.

Theses base instruments are available:

- Counter: holds a counter that can be incremented or decremented.

- Rate: tracks the rate of values per seconds.

- Reservoir: randomly samples values.

- Derive: tracks the rate of values based on the delta with previous value.

- Gauge: tracks last value.

- Timer: tracks durations.

You can create custom instruments or compose new instruments form the built-in instruments as long as they implements the Sample or Discrete interfaces.

Registry enforce the Discrete and Sample interfaces, creating a custom Reporter should be trivial, for example: 

for k, m := range registry.Instruments() {
 	switch i := m.(type) {
 	case instruments.Discrete:
 	 	s := i.Snapshot()
 	 	report(k, s)
 	case instruments.Sample:
 	 	s := instruments.Quantile(i.Snapshot(), 0.95)
 	 	report(k, s)
 	}
}

Index

Examples

Package Files

aggregate.go instruments.go math.go

func Ceil Uses

❖
func Ceil(v float64) int64

Ceil returns the least integer value greater than or equal to x.

func Floor Uses

❖
func Floor(v float64) int64

Floor returns the greatest integer value less than or equal to x.

func Max Uses

❖
func Max(values []int64) int64

Max returns maximun value of the given sample.

func Mean Uses

❖
func Mean(values []int64) float64

Mean returns the mean of the given sample.

func Min Uses

❖
func Min(values []int64) int64

Min returns minimun value of the given sample.

func Quantile Uses

❖
func Quantile(v []int64, q float64) int64

Quantile returns the nearest value to the given quantile.

func Scale Uses

❖
func Scale(o, d time.Duration) float64

Scale returns a conversion factor from one unit to another.

func StandardDeviation Uses

❖
func StandardDeviation(v []int64) float64

StandardDeviation returns standard deviation of the given sample.

func Variance Uses

❖
func Variance(values []int64) float64

Variance returns variance if the given sample.

type Counter Uses

❖
type Counter struct {
    // contains filtered or unexported fields
}

Counter holds a counter that can be incremented or decremented.

Example

Code: 

counter := NewCounter()
counter.Update(20)
counter.Update(25)
s := counter.Snapshot()
fmt.Println(s)

func NewCounter Uses

❖
func NewCounter() *Counter

NewCounter creates a new counter instrument.

func (*Counter) Snapshot Uses

❖
func (c *Counter) Snapshot() int64

Snapshot returns the current value and reset the counter.

func (*Counter) Update Uses

❖
func (c *Counter) Update(v int64)

Update adds v to the counter.

type Derive Uses

❖
type Derive struct {
    // contains filtered or unexported fields
}

Derive tracks the rate of deltas per seconds.

Example

Code: 

derive := NewDerive(34)
derive.Update(56)
derive.Update(78)
s := derive.Snapshot()
fmt.Println(s)

func NewDerive Uses

❖
func NewDerive(v int64) *Derive

NewDerive creates a new derive instruments.

func NewDeriveScale Uses

❖
func NewDeriveScale(v int64, d time.Duration) *Derive

NewDeriveScale creates a new derive instruments with the given unit.

func (*Derive) Snapshot Uses

❖
func (d *Derive) Snapshot() int64

Snapshot returns the number of values per seconds since the last snapshot, and reset the count to zero.

func (*Derive) Update Uses

❖
func (d *Derive) Update(v int64)

Update update rate value based on the stored previous value.

type Discrete Uses

❖
type Discrete interface {
    Snapshot() int64
}

Discrete represents a single value instrument.

type Gauge Uses

❖
type Gauge struct {
    // contains filtered or unexported fields
}

Gauge tracks a value.

Example

Code: 

gauge := NewGauge(34)
gauge.Update(35)
s := gauge.Snapshot()
fmt.Println(s)

func NewGauge Uses

❖
func NewGauge(v int64) *Gauge

NewGauge creates a new Gauge with the given value.

func (*Gauge) Snapshot Uses

❖
func (g *Gauge) Snapshot() int64

Snapshot returns the current value.

func (*Gauge) Update Uses

❖
func (g *Gauge) Update(v int64)

Update updates the current stored value.

type Rate Uses

❖
type Rate struct {
    // contains filtered or unexported fields
}

Rate tracks the rate of values per second.

Example

Code: 

rate := NewRate()
rate.Update(20)
rate.Update(25)
s := rate.Snapshot()
fmt.Println(s)

func NewRate Uses

❖
func NewRate() *Rate

NewRate creates a new rate instrument.

func NewRateScale Uses

❖
func NewRateScale(d time.Duration) *Rate

NewRateScale creates a new rate instruments with the given unit.

func (*Rate) Snapshot Uses

❖
func (r *Rate) Snapshot() int64

Snapshot returns the number of values per second since the last snapshot, and reset the count to zero.

func (*Rate) Update Uses

❖
func (r *Rate) Update(v int64)

Update updates rate value.

type Reservoir Uses

❖
type Reservoir struct {
    // contains filtered or unexported fields
}

Reservoir tracks a sample of values.

Example

Code: 

reservoir := NewReservoir(-1)
reservoir.Update(12)
reservoir.Update(54)
reservoir.Update(34)
s := reservoir.Snapshot()
fmt.Println(Quantile(s, 0.99))

func NewReservoir Uses

❖
func NewReservoir(size int64) *Reservoir

NewReservoir creates a new reservoir of the given size. If size is negative, it will create a sample of DefaultReservoirSize size.

func (*Reservoir) Snapshot Uses

❖
func (r *Reservoir) Snapshot() []int64

Snapshot returns sample as a sorted array.

func (*Reservoir) Update Uses

❖
func (r *Reservoir) Update(v int64)

Update fills the sample randomly with given value, for reference, see: http://en.wikipedia.org/wiki/Reservoir_sampling

type Sample Uses

❖
type Sample interface {
    Snapshot() []int64
}

Sample represents a sample instrument.

type Timer Uses

❖
type Timer struct {
    // contains filtered or unexported fields
}

Timer tracks durations.

Example

Code: 

timer := NewTimer(-1)
ts := time.Now()
time.Sleep(10 * time.Second)
timer.Since(ts)
s := timer.Snapshot()
fmt.Println(Quantile(s, 0.99))

func NewTimer Uses

❖
func NewTimer(size int64) *Timer

NewTimer creates a new Timer with the given sample size.

func (*Timer) Since Uses

❖
func (t *Timer) Since(start time.Time)

Since records duration since the given start time.

func (*Timer) Snapshot Uses

❖
func (t *Timer) Snapshot() []int64

Snapshot returns durations sample as a sorted array.

func (*Timer) Time Uses

❖
func (t *Timer) Time(f func())

Time records given function execution time.

Example

Code: 

timer := NewTimer(-1)
timer.Time(func() {
    time.Sleep(10 * time.Second)
})
s := timer.Snapshot()
fmt.Println(Quantile(s, 0.99))

func (*Timer) Update Uses

❖
func (t *Timer) Update(d time.Duration)

Update adds duration to the sample in ms.

Directories

PathSynopsis
reporterPackage reporter provides default reporting functionnality.
runtimePackage runtime provides runtime instrumentations around memory usage, goroutine and cgo calls.

Package instruments imports 6 packages (graph) and is imported by 2 packages. Updated 2017-10-07. Refresh now. Tools for package owners.