README

Instruments

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.

Installation

Download and install:

$ go get github.com/heroku/instruments

Add it to your code:

import "github.com/heroku/instruments"

Usage

timer := instruments.NewTimer(-1)

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

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

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

Instruments

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

These base instruments are available:

  • Counter: a simple counter.
  • 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.

Reporters

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)
  }
}

See also

Expand ▾ Collapse ▴

Documentation

Overview

    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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Ceil

    func Ceil(v float64) int64

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

      func Floor

      func Floor(v float64) int64

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

        func Max

        func Max(values []int64) int64

          Max returns maximun value of the given sample.

          func Mean

          func Mean(values []int64) float64

            Mean returns the mean of the given sample.

            func Min

            func Min(values []int64) int64

              Min returns minimun value of the given sample.

              func Quantile

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

                Quantile returns the nearest value to the given quantile.

                func Scale

                func Scale(o, d time.Duration) float64

                  Scale returns a conversion factor from one unit to another.

                  func StandardDeviation

                  func StandardDeviation(v []int64) float64

                    StandardDeviation returns standard deviation of the given sample.

                    func Variance

                    func Variance(values []int64) float64

                      Variance returns variance if the given sample.

                      Types

                      type Counter

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

                        Counter holds a counter that can be incremented or decremented.

                        Example
                        Output:
                        
                        

                        func NewCounter

                        func NewCounter() *Counter

                          NewCounter creates a new counter instrument.

                          func (*Counter) Snapshot

                          func (c *Counter) Snapshot() int64

                            Snapshot returns the current value and reset the counter.

                            func (*Counter) Update

                            func (c *Counter) Update(v int64)

                              Update adds v to the counter.

                              type Derive

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

                                Derive tracks the rate of deltas per seconds.

                                Example
                                Output:
                                
                                

                                func NewDerive

                                func NewDerive(v int64) *Derive

                                  NewDerive creates a new derive instruments.

                                  func NewDeriveScale

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

                                    NewDeriveScale creates a new derive instruments with the given unit.

                                    func (*Derive) Snapshot

                                    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

                                      func (d *Derive) Update(v int64)

                                        Update update rate value based on the stored previous value.

                                        type Discrete

                                        type Discrete interface {
                                        	Snapshot() int64
                                        }

                                          Discrete represents a single value instrument.

                                          type Gauge

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

                                            Gauge tracks a value.

                                            Example
                                            Output:
                                            
                                            

                                            func NewGauge

                                            func NewGauge(v int64) *Gauge

                                              NewGauge creates a new Gauge with the given value.

                                              func (*Gauge) Snapshot

                                              func (g *Gauge) Snapshot() int64

                                                Snapshot returns the current value.

                                                func (*Gauge) Update

                                                func (g *Gauge) Update(v int64)

                                                  Update updates the current stored value.

                                                  type Rate

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

                                                    Rate tracks the rate of values per second.

                                                    Example
                                                    Output:
                                                    
                                                    

                                                    func NewRate

                                                    func NewRate() *Rate

                                                      NewRate creates a new rate instrument.

                                                      func NewRateScale

                                                      func NewRateScale(d time.Duration) *Rate

                                                        NewRateScale creates a new rate instruments with the given unit.

                                                        func (*Rate) Snapshot

                                                        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

                                                          func (r *Rate) Update(v int64)

                                                            Update updates rate value.

                                                            type Reservoir

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

                                                              Reservoir tracks a sample of values.

                                                              Example
                                                              Output:
                                                              
                                                              

                                                              func NewReservoir

                                                              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

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

                                                                  Snapshot returns sample as a sorted array.

                                                                  func (*Reservoir) Update

                                                                  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

                                                                    type Sample interface {
                                                                    	Snapshot() []int64
                                                                    }

                                                                      Sample represents a sample instrument.

                                                                      type Timer

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

                                                                        Timer tracks durations.

                                                                        Example
                                                                        Output:
                                                                        
                                                                        

                                                                        func NewTimer

                                                                        func NewTimer(size int64) *Timer

                                                                          NewTimer creates a new Timer with the given sample size.

                                                                          func (*Timer) Since

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

                                                                            Since records duration since the given start time.

                                                                            func (*Timer) Snapshot

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

                                                                              Snapshot returns durations sample as a sorted array.

                                                                              func (*Timer) Time

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

                                                                                Time records given function execution time.

                                                                                Example
                                                                                Output:
                                                                                
                                                                                

                                                                                func (*Timer) Update

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

                                                                                  Update adds duration to the sample in ms.

                                                                                  Directories

                                                                                  Path Synopsis
                                                                                  Package reporter provides default reporting functionnality.
                                                                                  Package reporter provides default reporting functionnality.
                                                                                  Package runtime provides runtime instrumentations around memory usage, goroutine and cgo calls.
                                                                                  Package runtime provides runtime instrumentations around memory usage, goroutine and cgo calls.