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.

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.

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.

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.

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.

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.

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.

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.