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
- Built-in reporters
- Accurate histograms
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.
Documentation
Please see the API documentation for package and API descriptions and examples.
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.
Instruments support two types of instruments: Discrete instruments return a single value, and Sample instruments a value distribution.
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 MetricID(name string, tags []string) string
- func SplitMetricID(metricID string) (name string, tags []string)
- type Counter
- type Derive
- type Discrete
- type Distribution
- 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 float64) *Derive
- func (r *Registry) DeriveScale(name string, tags []string, v float64, 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) *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) *Timer
- func (r *Registry) Unregister(name string, tags []string)
- type Reporter
- type Reservoir
- type Sample
- type Timer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SplitMetricID ¶
SplitMetricID takes a metric ID and 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() float64
}
Discrete represents a single value instrument.
type Distribution ¶ added in v1.3.0
type Distribution interface {
// Count returns the number of observations
Count() int
// Min returns the minimum observed value
Min() float64
// Max returns the maximum observed value
Max() float64
// Sum returns the sum
Sum() float64
// Mean returns the mean
Mean() float64
// Quantile returns the quantile for a given q (0..1)
Quantile(q float64) float64
// Variance returns the variance
Variance() float64
// NumBins number of bins/buckets.
NumBins() int
// Bin returns the bin/bucket value and weight at index.
Bin(index int) (value, weight float64)
}
Distribution is returned by Sample snapshots
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.6)
fmt.Println(gauge.Snapshot())
}
Output: 35.6
type Logger ¶ added in v1.2.0
type Logger interface {
Printf(string, ...interface{})
}
Logger allows to plug in a logger.
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.
Example ¶
package main
import (
"log"
"os"
"time"
"github.com/bsm/instruments"
"github.com/bsm/instruments/logreporter"
)
func main() {
// Create new registry instance, flushing at minutely intervals
registry := instruments.New(time.Minute, "myapp.")
defer registry.Close()
// Subscribe a reporter
logger := log.New(os.Stdout, "", log.LstdFlags)
registry.Subscribe(logreporter.New(logger))
// Fetch a timer
timer := registry.Timer("processing-time", []string{"tag1", "tag2"})
// Measure something
start := time.Now()
time.Sleep(20 * time.Millisecond)
timer.Since(start)
}
Output:
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 ¶
NewUnstarted 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 float64) error
// Sample accepts a sampled distribution with name and (sorted) tags
Sample(name string, tags []string, dist Distribution) 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()
reservoir.Update(12)
reservoir.Update(54)
reservoir.Update(34)
fmt.Println(reservoir.Snapshot().Quantile(0.99))
}
Output: 54
func (*Reservoir) Snapshot ¶
func (r *Reservoir) Snapshot() Distribution
Snapshot returns a Distribution
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() Distribution
}
Sample represents a sample instrument.
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()
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() Distribution
Snapshot returns durations distribution
Source Files
Directories