stats

README

Emitter Stats

This golang package is used for monitoring emitter.io cluster. This provides a tight binary compression and a single histogram/counter abstraction in order to deal with various kinds of system monitoring. This package is compatible with GopherJS (snapshot-only) and hence can also be compiled to javascript. Documentation is available on go doc.

Installation

go get -u github.com/emitter-io/stats

Quick Start

The package itself provides a general-purpose monitoring capabilities, with tight encoding using our binary codec. While it's primarily have been built for emitter, it can be used anywhere.

Typical usage consists of creating a metric container, measuring various metrics and sending snapshots over the wire.

rand.Seed(time.Now().UnixNano())

// Create a container
m := stats.New()

// Measure few metrics
m.Measure("my.metric.1", rand.Int31n(1000))
m.Measure("my.metric.2", rand.Int31n(1000))

// Create a snapshot which can be transferred over the wire
bytes := m.Snapshot()

// Restore a snapshot from binary
v, err := stats.Restore(bytes)

// Get the values back
percentiles := v[0].Quantile(50, 90, 95, 99)
average := v[0].Mean()
count := v[0].Count()

Documentation

Index

• type Bin
• type Measurer
• type Metric
  • func NewMetric(name string) *Metric
  • func (m *Metric) Count() int
  • func (m *Metric) Histogram(bins ...int) []Bin
  • func (m *Metric) Max() int
  • func (m *Metric) Mean() float64
  • func (m *Metric) Min() int
  • func (m *Metric) Name() string
  • func (m *Metric) Quantile(quantiles ...float64) []float64
  • func (m *Metric) Rate() float64
  • func (m *Metric) Reset()
  • func (m *Metric) Snapshot() *Snapshot
  • func (m *Metric) StdDev() float64
  • func (m *Metric) Tag() string
  • func (m *Metric) Update(v int32)
  • func (m *Metric) UpdateTag(tag string)
  • func (m *Metric) Variance() float64
  • func (m *Metric) Window() (time.Time, time.Time)
• type Monitor
  • func New() *Monitor
  • func (m *Monitor) Get(name string) *Metric
  • func (m *Monitor) Measure(name string, value int32)
  • func (m *Monitor) MeasureElapsed(name string, start time.Time)
  • func (m *Monitor) MeasureRuntime()
  • func (m *Monitor) Range(f func(*Metric) bool)
  • func (m *Monitor) Snapshot() (out []byte)
  • func (m *Monitor) Tag(name, tag string)
• type Noop
  • func NewNoop() *Noop
  • func (m *Noop) Measure(name string, value int32)
  • func (m *Noop) MeasureElapsed(name string, start time.Time)
  • func (m *Noop) MeasureRuntime()
  • func (m *Noop) Snapshot() []byte
  • func (m *Noop) Tag(name, tag string)
• type Snapshot
  • func (s *Snapshot) Count() int
  • func (s *Snapshot) Max() int
  • func (s *Snapshot) Mean() float64
  • func (s *Snapshot) Merge(other Snapshot)
  • func (s *Snapshot) Min() int
  • func (s *Snapshot) Name() string
  • func (s *Snapshot) Quantile(quantiles ...float64) []float64
  • func (s *Snapshot) Rate() float64
  • func (s *Snapshot) StdDev() float64
  • func (s *Snapshot) Sum() int
  • func (s *Snapshot) Tag() string
  • func (s *Snapshot) Variance() float64
  • func (s *Snapshot) Window() (int64, int64)
• type Snapshots
  • func Restore(encoded []byte) (snapshots Snapshots, err error)
  • func (snapshots *Snapshots) Merge(others Snapshots)
  • func (snapshots Snapshots) ToMap() map[string]Snapshot
• type Snapshotter

Types

type Bin

type Bin struct {
	Lower int32 // The lower bound of the bin
	//Center int32 // The center of the bin
	Upper int32 // The upper bound of the bin
	Count int   // The number of elements in the bin
}

Bin represents a bin of a histogram

type Measurer

type Measurer interface {
	Snapshotter
	Measure(name string, value int32)
	MeasureElapsed(name string, start time.Time)
	MeasureRuntime()
	Tag(name, tag string)
}

Measurer represents a monitoring contract.

type Metric

type Metric struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Metric maintains a combination of a gauge and a statistically-significant selection of the values from a stream. This is essentially a combination of a histogram, gauge and a counter.

func NewMetric

func NewMetric(name string) *Metric

NewMetric creates a new metric.

func (*Metric) Count

func (m *Metric) Count() int

Count returns the number of samples recorded, which may exceed the reservoir size.

func (*Metric) Histogram

func (m *Metric) Histogram(bins ...int) []Bin

Histogram creates a histogram with the bins provided.

func (*Metric) Max

func (m *Metric) Max() int

Max returns the maximum value in the sample, which may not be the maximum value ever to be part of the sample.

func (*Metric) Mean

func (m *Metric) Mean() float64

Mean returns the mean of the values in the sample.

func (*Metric) Min

func (m *Metric) Min() int

Min returns the minimum value in the sample, which may not be the minimum value ever to be part of the sample.

func (*Metric) Name

func (m *Metric) Name() string

Name returns the name of the histogram.

func (*Metric) Quantile

func (m *Metric) Quantile(quantiles ...float64) []float64

Quantile returns a slice of arbitrary quantiles of the sample.

func (*Metric) Rate

func (m *Metric) Rate() float64

Rate returns a operation per second rate since the creation of the metric.

func (*Metric) Reset

func (m *Metric) Reset()

Reset clears all samples and resets the metric.

func (*Metric) Snapshot

func (m *Metric) Snapshot() *Snapshot

Snapshot returns a read-only copy of the sample.

func (*Metric) StdDev

func (m *Metric) StdDev() float64

StdDev returns the standard deviation of the values in the sample.

func (*Metric) Tag

func (m *Metric) Tag() string

Tag returns the associated tag of the metric.

func (*Metric) Update

func (m *Metric) Update(v int32)

Update samples a new value into the metric.

func (*Metric) UpdateTag

func (m *Metric) UpdateTag(tag string)

UpdateTag updates the associated metric tag.

func (*Metric) Variance

func (m *Metric) Variance() float64

Variance returns the variance of the values in the sample.

func (*Metric) Window

func (m *Metric) Window() (time.Time, time.Time)

Window returns start and end time of the histogram.

type Monitor

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

Monitor represents a monitoring registry

func New

func New() *Monitor

New creates a new monitor.

func (*Monitor) Get

func (m *Monitor) Get(name string) *Metric

Get retrieves a metric by its name. If the metric does not exist yet, it will create and register the metric.

func (*Monitor) Measure

func (m *Monitor) Measure(name string, value int32)

Measure retrieves the metric and updates it.

func (*Monitor) MeasureElapsed

func (m *Monitor) MeasureElapsed(name string, start time.Time)

MeasureElapsed measures elapsed time since the start

func (*Monitor) MeasureRuntime

func (m *Monitor) MeasureRuntime()

MeasureRuntime captures the runtime metrics, this is a relatively slow process and code is largely inspired by go-metrics.

func (*Monitor) Range

func (m *Monitor) Range(f func(*Metric) bool)

Range ranges over all the metrics in the monitor. The iteration stops if the function returns false, similar to sync.Map

func (*Monitor) Snapshot

func (m *Monitor) Snapshot() (out []byte)

Snapshot encodes the metrics into a binary representation

func (*Monitor) Tag

func (m *Monitor) Tag(name, tag string)

Tag updates a tag of a particular metric.

type Noop

type Noop struct{}

Noop represents a no-op monitor

func NewNoop

func NewNoop() *Noop

NewNoop creates a new no-op monitor.

func (*Noop) Measure

func (m *Noop) Measure(name string, value int32)

Measure records a value in the queue

func (*Noop) MeasureElapsed

func (m *Noop) MeasureElapsed(name string, start time.Time)

MeasureElapsed measures elapsed time since the start

func (*Noop) MeasureRuntime

func (m *Noop) MeasureRuntime()

MeasureRuntime measures the runtime information

func (*Noop) Snapshot

func (m *Noop) Snapshot() []byte

Snapshot creates a snapshot

func (*Noop) Tag

func (m *Noop) Tag(name, tag string)

Tag updates a tag.

type Snapshot

type Snapshot struct {
	Metric string
	Label  string
	Sample sample
	Amount int32
	T0     int64
	T1     int64
}

Snapshot is a read-only copy of another Sample.

func (*Snapshot) Count

func (s *Snapshot) Count() int

Count returns the count of inputs at the time the snapshot was taken.

func (*Snapshot) Max

func (s *Snapshot) Max() int

Max returns the maximal value at the time the snapshot was taken.

func (*Snapshot) Mean

func (s *Snapshot) Mean() float64

Mean returns the mean value at the time the snapshot was taken.

func (*Snapshot) Merge

func (s *Snapshot) Merge(other Snapshot)

Merge merges two snapshots together.

func (*Snapshot) Min

func (s *Snapshot) Min() int

Min returns the minimal value at the time the snapshot was taken.

func (*Snapshot) Name

func (s *Snapshot) Name() string

Name returns the name of the metric.

func (*Snapshot) Quantile

func (s *Snapshot) Quantile(quantiles ...float64) []float64

Quantile returns a slice of arbitrary quantiles of the sample.

func (*Snapshot) Rate

func (s *Snapshot) Rate() float64

Rate returns a operation per second rate over the time window.

func (*Snapshot) StdDev

func (s *Snapshot) StdDev() float64

StdDev returns the standard deviation of values at the time the snapshot was taken.

func (*Snapshot) Sum

func (s *Snapshot) Sum() int

Sum returns the arithmetic sum of all of the values in the snapshot.

func (*Snapshot) Tag

func (s *Snapshot) Tag() string

Tag returns the associated tag of the metric.

func (*Snapshot) Variance

func (s *Snapshot) Variance() float64

Variance returns the variance of values at the time the snapshot was taken.

func (*Snapshot) Window

func (s *Snapshot) Window() (int64, int64)

Window returns start and end time of the metric.

type Snapshots

type Snapshots []Snapshot

Snapshots represents a set of snapshots.

func Restore

func Restore(encoded []byte) (snapshots Snapshots, err error)

Restore restores a snapshot into a read-only histogram format.

func (*Snapshots) Merge

func (snapshots *Snapshots) Merge(others Snapshots)

Merge merges two sets of snapshots together.

func (Snapshots) ToMap

func (snapshots Snapshots) ToMap() map[string]Snapshot

ToMap converts the set of snapshots to a map.

type Snapshotter

type Snapshotter interface {
	Snapshot() []byte
}

Snapshotter represents a snapshotting contract.