README
¶
Instruments
Instruments allows you to collects metrics over discrete time intervals. This a fork of the (original library)[https://github.com/heroku/instruments] which comes with several new additions - consider it a v2!
Collected metrics will only reflect observations from last time window only, rather than including observations from prior windows, contrary to EWMA based metrics.
The new features include:
- Slighly faster
- More convenient API
- Support for tags
Installation
Download and install:
$ go get github.com/bsm/instruments
Add it to your code:
import "github.com/bsm/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:
report(k, i.Snapshot())
case instruments.Sample:
report(k, i.Snapshot().Quantile(0.95))
}
}
See also
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.
// Create new registry instance, flushing at minutely intervals
registry := instruments.New(time.Minute)
defer registry.Close()
// Watch errors that may happen during flush cycles
go func() {
for err := registry.Errors() {
log.Println("ERROR", err)
}
}()
// Subscribe a reporter
registry.Subscribe(logreporter.New("myapp."))
// Fetch a timer and measure something
timer := registry.Timer("processing-time")
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.
Index ¶
- func Ceil(v float64) int64
- func Floor(v float64) int64
- func MetricID(name string, tags []string) string
- func Scale(o, d time.Duration) float64
- func SplitMetricID(metricID string) (name string, tags []string)
- type Counter
- type Derive
- type Discrete
- type Gauge
- type Logger
- type Rate
- type Registry
- func (r *Registry) AddTags(tags ...string)
- func (r *Registry) Close() error
- func (r *Registry) Counter(name string, tags []string) *Counter
- func (r *Registry) Derive(name string, tags []string, v int64) *Derive
- func (r *Registry) DeriveScale(name string, tags []string, v int64, d time.Duration) *Derive
- func (r *Registry) Fetch(name string, tags []string, factory func() interface{}) interface{}
- func (r *Registry) Flush() error
- func (r *Registry) Gauge(name string, tags []string) *Gauge
- func (r *Registry) Get(name string, tags []string) interface{}
- func (r *Registry) Rate(name string, tags []string) *Rate
- func (r *Registry) RateScale(name string, tags []string, d time.Duration) *Rate
- func (r *Registry) Register(name string, tags []string, v interface{})
- func (r *Registry) Reservoir(name string, tags []string, size int) *Reservoir
- func (r *Registry) SetTags(tags ...string)
- func (r *Registry) Size() int
- func (r *Registry) Subscribe(rep Reporter)
- func (r *Registry) Tags() []string
- func (r *Registry) Timer(name string, tags []string, size int) *Timer
- func (r *Registry) Unregister(name string, tags []string)
- type Reporter
- type Reservoir
- type Sample
- type SampleSlice
- func (s SampleSlice) IsSorted() bool
- func (s SampleSlice) Len() int
- func (s SampleSlice) Less(i, j int) bool
- func (s SampleSlice) Max() int64
- func (s SampleSlice) Mean() float64
- func (s SampleSlice) Min() int64
- func (s SampleSlice) Quantile(q float64) int64
- func (s SampleSlice) Release()
- func (s SampleSlice) Sort()
- func (s SampleSlice) StandardDeviation() float64
- func (s SampleSlice) Swap(i, j int)
- func (s SampleSlice) Variance() float64
- type Timer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SplitMetricID ¶
SplitMetricID takes a metric ID ans splits it into name and tags
Types ¶
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
Counter holds a counter that can be incremented or decremented.
Example ¶
package main
import (
"fmt"
"github.com/bsm/instruments"
)
func main() {
counter := instruments.NewCounter()
counter.Update(20)
counter.Update(25)
fmt.Println(counter.Snapshot())
}
Output: 45
type Derive ¶
type Derive struct {
// contains filtered or unexported fields
}
Derive tracks the rate of deltas per seconds.
Example ¶
package main
import (
"fmt"
"github.com/bsm/instruments"
)
func main() {
derive := instruments.NewDerive(34)
derive.Update(56)
derive.Update(78)
fmt.Println(derive.Snapshot())
}
Output:
func NewDeriveScale ¶
NewDeriveScale creates a new derive instruments with the given unit.
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 ¶
package main
import (
"fmt"
"github.com/bsm/instruments"
)
func main() {
gauge := instruments.NewGauge()
gauge.Update(35)
fmt.Println(gauge.Snapshot())
}
Output: 35
type Rate ¶
type Rate struct {
// contains filtered or unexported fields
}
Rate tracks the rate of values per second.
Example ¶
package main
import (
"fmt"
"github.com/bsm/instruments"
)
func main() {
rate := instruments.NewRate()
rate.Update(20)
rate.Update(25)
fmt.Println(rate.Snapshot())
}
Output:
func NewRateScale ¶
NewRateScale creates a new rate instruments with the given unit.
type Registry ¶
type Registry struct {
Logger Logger
// contains filtered or unexported fields
}
Registry is a registry of all instruments.
func New ¶
New creates a new Registry with a flushInterval at which metrics are reported to the subscribed Reporter instances, a custom prefix which is prepended to every metric name and default tags. Default: 60s
You should call/defer Close() on exit to flush all accummulated data and release all resources.
func NewUnstarted ¶
New creates a new Registry without a background flush thread.
func (*Registry) Counter ¶
Counter fetches an instrument from the registry or creates a new one.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) Derive ¶
Derive fetches an instrument from the registry or creates a new one.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) DeriveScale ¶
DeriveScale fetches an instrument from the registry or creates a new one with a custom scale.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) Fetch ¶
Fetch returns an instrument from the Registry or creates a new one using the provided factory.
func (*Registry) Flush ¶
Flush performs a manual flush to all subscribed reporters. This method is usually called by a background thread every flushInterval, specified in New()
func (*Registry) Gauge ¶
Gauge fetches an instrument from the registry or creates a new one.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) Rate ¶
Rate fetches an instrument from the registry or creates a new one.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) RateScale ¶
RateScale fetches an instrument from the registry or creates a new one with a custom scale.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) Reservoir ¶
Reservoir fetches an instrument from the registry or creates a new one.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) Timer ¶
Timer fetches an instrument from the registry or creates a new one.
If another instrument type is already registered with the same name/tags, a blank one will be returned and an error will be logged to the Errors() channel.
func (*Registry) Unregister ¶
Unregister remove from the registry the instrument matching the given name/tags
type Reporter ¶
type Reporter interface {
// Prep is called at the beginning of each reporting cycle, which
// allows reporters to prepare for next data snapshot.
Prep() error
// Discrete accepts a numeric value with name and (sorted) tags
Discrete(name string, tags []string, value int64) error
// Sample accepts a sampled value with name and (sorted) tags
Sample(name string, tags []string, value SampleSlice) error
// Flush is called at the end of each reporting cycle, which
// allows reporters to safely buffer data and emit it to
// backend as a bulk.
Flush() error
}
Reporter describes the interface every reporter must follow. See logreporter package as an example.
type Reservoir ¶
type Reservoir struct {
// contains filtered or unexported fields
}
Reservoir tracks a sample of values.
Example ¶
package main
import (
"fmt"
"github.com/bsm/instruments"
)
func main() {
reservoir := instruments.NewReservoir(-1)
reservoir.Update(12)
reservoir.Update(54)
reservoir.Update(34)
fmt.Println(reservoir.Snapshot().Quantile(0.99))
}
Output: 54
func NewReservoir ¶
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() SampleSlice
Snapshot returns sample as a sorted array.
func (*Reservoir) Update ¶
Update fills the sample randomly with given value, for reference, see: http://en.wikipedia.org/wiki/Reservoir_sampling
type Sample ¶
type Sample interface {
Snapshot() SampleSlice
}
Sample represents a sample instrument.
type SampleSlice ¶
type SampleSlice []int64
SampleSlice are returned by Sample.Snapshot. These are simple int64 slices which extensions for simpler calculations:
func (SampleSlice) IsSorted ¶
func (s SampleSlice) IsSorted() bool
func (SampleSlice) Len ¶
func (s SampleSlice) Len() int
func (SampleSlice) Less ¶
func (s SampleSlice) Less(i, j int) bool
func (SampleSlice) Max ¶
func (s SampleSlice) Max() int64
Max returns maximum value of the given sample.
func (SampleSlice) Mean ¶
func (s SampleSlice) Mean() float64
Mean returns the mean of the given sample.
func (SampleSlice) Min ¶
func (s SampleSlice) Min() int64
Min returns minimun value of the given sample.
func (SampleSlice) Quantile ¶
func (s SampleSlice) Quantile(q float64) int64
Quantile returns the nearest value to the given quantile.
func (SampleSlice) Release ¶ added in v1.1.0
func (s SampleSlice) Release()
Release releases the SampleSlice to a pool where it can be recycled. Use this with caution! Once released the object must not be accessed by your code again.
func (SampleSlice) Sort ¶
func (s SampleSlice) Sort()
func (SampleSlice) StandardDeviation ¶
func (s SampleSlice) StandardDeviation() float64
StandardDeviation returns standard deviation of the given sample.
func (SampleSlice) Swap ¶
func (s SampleSlice) Swap(i, j int)
func (SampleSlice) Variance ¶
func (s SampleSlice) Variance() float64
Variance returns variance if the given sample.
type Timer ¶
type Timer struct {
// contains filtered or unexported fields
}
Timer tracks durations.
Example ¶
package main
import (
"fmt"
"time"
"github.com/bsm/instruments"
)
func main() {
timer := instruments.NewTimer(-1)
ts := time.Now()
time.Sleep(10 * time.Millisecond)
timer.Since(ts)
fmt.Println(timer.Snapshot().Quantile(0.99))
}
Output:
func (*Timer) Snapshot ¶
func (t *Timer) Snapshot() SampleSlice
Snapshot returns durations sample as a sorted array.
func (*Timer) Time ¶
func (t *Timer) Time(f func())
Time records given function execution time.
Example ¶
package main
import (
"fmt"
"time"
"github.com/bsm/instruments"
)
func main() {
timer := instruments.NewTimer(-1)
timer.Time(func() {
time.Sleep(10 * time.Millisecond)
})
fmt.Println(timer.Snapshot().Quantile(0.99))
}
Output:
Source Files
Directories