README
¶
go-metrics
Go port of Coda Hale's Metrics library: https://github.com/codahale/metrics.
Documentation: http://godoc.org/github.com/rcrowley/go-metrics.
Usage
Create and update metrics:
c := metrics.NewCounter()
metrics.Register("foo", c)
c.Inc(47)
g := metrics.NewGauge()
metrics.Register("bar", g)
g.Update(47)
s := metrics.NewExpDecaySample(1028, 0.015) // or metrics.NewUniformSample(1028)
h := metrics.NewHistogram(s)
metrics.Register("baz", h)
h.Update(47)
m := metrics.NewMeter()
metrics.Register("quux", m)
m.Mark(47)
t := metrics.NewTimer()
metrics.Register("bang", t)
t.Time(func() {})
t.Update(47)
Periodically log every metric in human-readable form to standard error:
go metrics.Log(metrics.DefaultRegistry, 60e9, log.New(os.Stderr, "metrics: ", log.Lmicroseconds))
Periodically log every metric in slightly-more-parseable form to syslog:
w, _ := syslog.Dial("unixgram", "/dev/log", syslog.LOG_INFO, "metrics")
go metrics.Syslog(metrics.DefaultRegistry, 60e9, w)
Periodically emit every metric to Graphite:
addr, _ := net.ResolveTCPAddr("tcp", "127.0.0.1:2003")
go metrics.Graphite(metrics.DefaultRegistry, 10e9, "metrics", addr)
Periodically emit every metric to StatHat:
import "github.com/rcrowley/go-metrics/stathat"
stathat.Stathat(metrics.DefaultRegistry, 10e9, "example@example.com")
Installation
go get github.com/rcrowley/go-metrics
StatHat support additionally requires their Go client:
go get github.com/stathat/go
Documentation
¶
Overview ¶
Go port of Coda Hale's Metrics library
<https://github.com/rcrowley/go-metrics>
Coda Hale's original work: <https://github.com/codahale/metrics>
Index ¶
- Variables
- func CaptureDebugGCStats(r Registry, d time.Duration)
- func CaptureDebugGCStatsOnce(r Registry)
- func CaptureRuntimeMemStats(r Registry, d time.Duration)
- func CaptureRuntimeMemStatsOnce(r Registry)
- func Each(f func(string, interface{}))
- func Get(name string) interface{}
- func Graphite(r Registry, d time.Duration, prefix string, addr *net.TCPAddr)
- func Log(r Registry, d time.Duration, l *log.Logger)
- func Register(name string, i interface{})
- func RegisterDebugGCStats(r Registry)
- func RegisterRuntimeMemStats(r Registry)
- func RunHealthchecks()
- func Syslog(r Registry, d time.Duration, w *syslog.Writer)
- func Unregister(name string)
- func Write(r Registry, d time.Duration, w io.Writer)
- type Counter
- type EWMA
- type ExpDecaySample
- type Gauge
- type Healthcheck
- type Histogram
- type Meter
- type NilCounter
- type NilEWMA
- type NilGauge
- type NilHealthcheck
- type NilHistogram
- func (h NilHistogram) Clear()
- func (h NilHistogram) Count() int64
- func (h NilHistogram) Max() int64
- func (h NilHistogram) Mean() float64
- func (h NilHistogram) Min() int64
- func (h NilHistogram) Percentile(p float64) float64
- func (h NilHistogram) Percentiles(ps []float64) []float64
- func (h NilHistogram) StdDev() float64
- func (h NilHistogram) Update(v int64)
- func (h NilHistogram) Variance() float64
- type NilMeter
- type NilSample
- type NilTimer
- func (t NilTimer) Count() int64
- func (t NilTimer) Max() int64
- func (t NilTimer) Mean() float64
- func (t NilTimer) Min() int64
- func (t NilTimer) Percentile(p float64) float64
- func (t NilTimer) Percentiles(ps []float64) []float64
- func (t NilTimer) Rate1() float64
- func (t NilTimer) Rate15() float64
- func (t NilTimer) Rate5() float64
- func (t NilTimer) RateMean() float64
- func (t NilTimer) StdDev() float64
- func (t NilTimer) Time(f func())
- func (t NilTimer) Update(d time.Duration)
- func (t NilTimer) UpdateSince(ts time.Time)
- type Registry
- type Sample
- type StandardCounter
- type StandardEWMA
- type StandardGauge
- type StandardHealthcheck
- type StandardHistogram
- func (h *StandardHistogram) Clear()
- func (h *StandardHistogram) Count() int64
- func (h *StandardHistogram) Max() int64
- func (h *StandardHistogram) Mean() float64
- func (h *StandardHistogram) Min() int64
- func (h *StandardHistogram) Percentile(p float64) float64
- func (h *StandardHistogram) Percentiles(ps []float64) []float64
- func (h *StandardHistogram) StdDev() float64
- func (h *StandardHistogram) Update(v int64)
- func (h *StandardHistogram) Variance() float64
- type StandardMeter
- type StandardRegistry
- func (r *StandardRegistry) Each(f func(string, interface{}))
- func (r *StandardRegistry) Get(name string) interface{}
- func (r StandardRegistry) MarshalJSON() ([]byte, error)
- func (r *StandardRegistry) Register(name string, i interface{})
- func (r *StandardRegistry) RunHealthchecks()
- func (r *StandardRegistry) Unregister(name string)
- type StandardTimer
- func (t *StandardTimer) Count() int64
- func (t *StandardTimer) Max() int64
- func (t *StandardTimer) Mean() float64
- func (t *StandardTimer) Min() int64
- func (t *StandardTimer) Percentile(p float64) float64
- func (t *StandardTimer) Percentiles(ps []float64) []float64
- func (t *StandardTimer) Rate1() float64
- func (t *StandardTimer) Rate15() float64
- func (t *StandardTimer) Rate5() float64
- func (t *StandardTimer) RateMean() float64
- func (t *StandardTimer) StdDev() float64
- func (t *StandardTimer) Time(f func())
- func (t *StandardTimer) Update(d time.Duration)
- func (t *StandardTimer) UpdateSince(ts time.Time)
- type Timer
- type UniformSample
Constants ¶
This section is empty.
Variables ¶
var UseNilMetrics bool = false
UseNilMetrics is checked by the constructor functions for all of the standard metrics. If it is true, the metric returned is a stub.
This global kill-switch helps quantify the observer effect and makes for less cluttered pprof profiles.
Functions ¶
func CaptureDebugGCStats ¶
Capture new values for the Go garbage collector statistics exported in debug.GCStats. This is designed to be called as a goroutine.
func CaptureDebugGCStatsOnce ¶
func CaptureDebugGCStatsOnce(r Registry)
Capture new values for the Go garbage collector statistics exported in debug.GCStats. This is designed to be called in a background goroutine. Giving a registry which has not been given to RegisterDebugGCStats will panic.
func CaptureRuntimeMemStats ¶
Capture new values for the Go runtime statistics exported in runtime.MemStats. This is designed to be called as a goroutine.
func CaptureRuntimeMemStatsOnce ¶
func CaptureRuntimeMemStatsOnce(r Registry)
Capture new values for the Go runtime statistics exported in runtime.MemStats. This is designed to be called in a background goroutine. Giving a registry which has not been given to RegisterRuntimeMemStats will panic.
func Each ¶
func Each(f func(string, interface{}))
Call the given function for each registered metric.
func Get ¶
func Get(name string) interface{}
Get the metric by the given name or nil if none is registered.
func Register ¶
func Register(name string, i interface{})
Register the given metric under the given name.
func RegisterDebugGCStats ¶
func RegisterDebugGCStats(r Registry)
Register metrics for the Go garbage collector statistics exported in debug.GCStats. The metrics are named by their fully-qualified Go symbols, i.e. debug.GCStats.PauseTotal.
func RegisterRuntimeMemStats ¶
func RegisterRuntimeMemStats(r Registry)
Register runtimeMetrics for the Go runtime statistics exported in runtime and specifically runtime.MemStats. The runtimeMetrics are named by their fully-qualified Go symbols, i.e. runtime.MemStats.Alloc.
Types ¶
type Counter ¶
Counters hold an int64 value that can be incremented and decremented.
This is an interface so as to encourage other structs to implement the Counter API as appropriate.
type EWMA ¶
EWMAs continuously calculate an exponentially-weighted moving average based on an outside source of clock ticks.
This is an interface so as to encourage other structs to implement the EWMA API as appropriate.
func NewEWMA1 ¶
func NewEWMA1() EWMA
Create a new EWMA with alpha set for a one-minute moving average.
type ExpDecaySample ¶
type ExpDecaySample struct {
// contains filtered or unexported fields
}
An exponentially-decaying sample using a forward-decaying priority reservoir. See Cormode et al's "Forward Decay: A Practical Time Decay Model for Streaming Systems".
func (*ExpDecaySample) Size ¶
func (s *ExpDecaySample) Size() int
Return the size of the sample, which is at most the reservoir size.
func (*ExpDecaySample) Update ¶
func (s *ExpDecaySample) Update(v int64)
Update the sample with a new value.
func (*ExpDecaySample) Values ¶
func (s *ExpDecaySample) Values() []int64
Return all the values in the sample.
type Gauge ¶
Gauges hold an int64 value that can be set arbitrarily.
This is an interface so as to encourage other structs to implement the Gauge API as appropriate.
type Healthcheck ¶
Healthchecks hold an os.Error value describing an arbitrary up/down status.
This is an interface so as to encourage other structs to implement the Healthcheck API as appropriate.
func NewHealthcheck ¶
func NewHealthcheck(f func(Healthcheck)) Healthcheck
Create a new Healthcheck, which will use the given function to update its status.
type Histogram ¶
type Histogram interface {
Clear()
Count() int64
Max() int64
Mean() float64
Min() int64
Percentile(float64) float64
Percentiles([]float64) []float64
StdDev() float64
Update(int64)
Variance() float64
}
Histograms calculate distribution statistics from an int64 value.
This is an interface so as to encourage other structs to implement the Histogram API as appropriate.
func NewHistogram ¶
Create a new Histogram with the given Sample. The initial values compare so that the first value will be both min and max and the variance is flagged for special treatment on its first iteration.
type Meter ¶
type Meter interface {
Count() int64
Mark(int64)
Rate1() float64
Rate5() float64
Rate15() float64
RateMean() float64
}
Meters count events to produce exponentially-weighted moving average rates at one-, five-, and fifteen-minutes and a mean rate.
This is an interface so as to encourage other structs to implement the Meter API as appropriate.
type Registry ¶
type Registry interface {
// Call the given function for each registered metric.
Each(func(string, interface{}))
// Get the metric by the given name or nil if none is registered.
Get(string) interface{}
// Register the given metric under the given name.
Register(string, interface{})
// Run all registered healthchecks.
RunHealthchecks()
// Unregister the metric with the given name.
Unregister(string)
}
A Registry holds references to a set of metrics by name and can iterate over them, calling callback functions provided by the user.
This is an interface so as to encourage other structs to implement the Registry API as appropriate.
var DefaultRegistry Registry = NewRegistry()
type Sample ¶
Samples maintain a statistically-significant selection of values from a stream.
This is an interface so as to encourage other structs to implement the Sample API as appropriate.
func NewExpDecaySample ¶
Create a new exponentially-decaying sample with the given reservoir size and alpha.
func NewUniformSample ¶
Create a new uniform sample with the given reservoir size.
type StandardCounter ¶
type StandardCounter struct {
// contains filtered or unexported fields
}
The standard implementation of a Counter uses the sync/atomic package to manage a single int64 value.
func (*StandardCounter) Clear ¶
func (c *StandardCounter) Clear()
Clear the counter: set it to zero.
func (*StandardCounter) Dec ¶
func (c *StandardCounter) Dec(i int64)
Decrement the counter by the given amount.
func (*StandardCounter) Inc ¶
func (c *StandardCounter) Inc(i int64)
Increment the counter by the given amount.
type StandardEWMA ¶
type StandardEWMA struct {
// contains filtered or unexported fields
}
The standard implementation of an EWMA tracks the number of uncounted events and processes them on each tick. It uses the sync/atomic package to manage uncounted events.
func (*StandardEWMA) Rate ¶
func (a *StandardEWMA) Rate() float64
Return the moving average rate of events per second.
func (*StandardEWMA) Tick ¶
func (a *StandardEWMA) Tick()
Tick the clock to update the moving average.
type StandardGauge ¶
type StandardGauge struct {
// contains filtered or unexported fields
}
The standard implementation of a Gauge uses the sync/atomic package to manage a single int64 value.
func (*StandardGauge) Value ¶
func (g *StandardGauge) Value() int64
Return the gauge's current value.
type StandardHealthcheck ¶
type StandardHealthcheck struct {
// contains filtered or unexported fields
}
The standard implementation of a Healthcheck stores the status and a function to call to update the status.
func (*StandardHealthcheck) Check ¶
func (h *StandardHealthcheck) Check()
Update the healthcheck's status.
func (*StandardHealthcheck) Error ¶
func (h *StandardHealthcheck) Error() error
Return the healthcheck's status, which will be nil if it is healthy.
func (*StandardHealthcheck) Healthy ¶
func (h *StandardHealthcheck) Healthy()
Mark the healthcheck as healthy.
func (*StandardHealthcheck) Unhealthy ¶
func (h *StandardHealthcheck) Unhealthy(err error)
Mark the healthcheck as unhealthy. The error should provide details.
type StandardHistogram ¶
type StandardHistogram struct {
// contains filtered or unexported fields
}
The standard implementation of a Histogram uses a Sample and a goroutine to synchronize its calculations.
func (*StandardHistogram) Count ¶
func (h *StandardHistogram) Count() int64
Return the count of inputs since the histogram was last cleared.
func (*StandardHistogram) Max ¶
func (h *StandardHistogram) Max() int64
Return the maximal value seen since the histogram was last cleared.
func (*StandardHistogram) Mean ¶
func (h *StandardHistogram) Mean() float64
Return the mean of all values seen since the histogram was last cleared.
func (*StandardHistogram) Min ¶
func (h *StandardHistogram) Min() int64
Return the minimal value seen since the histogram was last cleared.
func (*StandardHistogram) Percentile ¶
func (h *StandardHistogram) Percentile(p float64) float64
Return an arbitrary percentile of all values seen since the histogram was last cleared.
func (*StandardHistogram) Percentiles ¶
func (h *StandardHistogram) Percentiles(ps []float64) []float64
Return a slice of arbitrary percentiles of all values seen since the histogram was last cleared.
func (*StandardHistogram) StdDev ¶
func (h *StandardHistogram) StdDev() float64
Return the standard deviation of all values seen since the histogram was last cleared.
func (*StandardHistogram) Update ¶
func (h *StandardHistogram) Update(v int64)
Update the histogram with a new value.
func (*StandardHistogram) Variance ¶
func (h *StandardHistogram) Variance() float64
Return the variance of all values seen since the histogram was last cleared.
type StandardMeter ¶
type StandardMeter struct {
// contains filtered or unexported fields
}
The standard implementation of a Meter uses a goroutine to synchronize its calculations and another goroutine (via time.Ticker) to produce clock ticks.
func (*StandardMeter) Count ¶
func (m *StandardMeter) Count() int64
Return the count of events seen.
func (*StandardMeter) Rate1 ¶
func (m *StandardMeter) Rate1() float64
Return the meter's one-minute moving average rate of events.
func (*StandardMeter) Rate15 ¶
func (m *StandardMeter) Rate15() float64
Return the meter's fifteen-minute moving average rate of events.
func (*StandardMeter) Rate5 ¶
func (m *StandardMeter) Rate5() float64
Return the meter's five-minute moving average rate of events.
func (*StandardMeter) RateMean ¶
func (m *StandardMeter) RateMean() float64
Return the meter's mean rate of events.
type StandardRegistry ¶
type StandardRegistry struct {
// contains filtered or unexported fields
}
The standard implementation of a Registry is a mutex-protected map of names to metrics.
func (*StandardRegistry) Each ¶
func (r *StandardRegistry) Each(f func(string, interface{}))
Call the given function for each registered metric.
func (*StandardRegistry) Get ¶
func (r *StandardRegistry) Get(name string) interface{}
Get the metric by the given name or nil if none is registered.
func (StandardRegistry) MarshalJSON ¶
func (r StandardRegistry) MarshalJSON() ([]byte, error)
MarshalJSON returns a byte slice containing a JSON representation of all the metrics in the Registry.
func (*StandardRegistry) Register ¶
func (r *StandardRegistry) Register(name string, i interface{})
Register the given metric under the given name.
func (*StandardRegistry) RunHealthchecks ¶
func (r *StandardRegistry) RunHealthchecks()
Run all registered healthchecks.
func (*StandardRegistry) Unregister ¶
func (r *StandardRegistry) Unregister(name string)
Unregister the metric with the given name.
type StandardTimer ¶
type StandardTimer struct {
// contains filtered or unexported fields
}
The standard implementation of a Timer uses a Histogram and Meter directly.
func (*StandardTimer) Mean ¶
func (t *StandardTimer) Mean() float64
Return the mean of all values seen.
func (*StandardTimer) Percentile ¶
func (t *StandardTimer) Percentile(p float64) float64
Return an arbitrary percentile of all values seen.
func (*StandardTimer) Percentiles ¶
func (t *StandardTimer) Percentiles(ps []float64) []float64
Return a slice of arbitrary percentiles of all values seen.
func (*StandardTimer) Rate1 ¶
func (t *StandardTimer) Rate1() float64
Return the meter's one-minute moving average rate of events.
func (*StandardTimer) Rate15 ¶
func (t *StandardTimer) Rate15() float64
Return the meter's fifteen-minute moving average rate of events.
func (*StandardTimer) Rate5 ¶
func (t *StandardTimer) Rate5() float64
Return the meter's five-minute moving average rate of events.
func (*StandardTimer) RateMean ¶
func (t *StandardTimer) RateMean() float64
Return the meter's mean rate of events.
func (*StandardTimer) StdDev ¶
func (t *StandardTimer) StdDev() float64
Return the standard deviation of all values seen.
func (*StandardTimer) Time ¶
func (t *StandardTimer) Time(f func())
Record the duration of the execution of the given function.
func (*StandardTimer) Update ¶
func (t *StandardTimer) Update(d time.Duration)
Record the duration of an event.
func (*StandardTimer) UpdateSince ¶
func (t *StandardTimer) UpdateSince(ts time.Time)
Record the duration of an event that started at a time and ends now.
type Timer ¶
type Timer interface {
Count() int64
Max() int64
Mean() float64
Min() int64
Percentile(float64) float64
Percentiles([]float64) []float64
Rate1() float64
Rate5() float64
Rate15() float64
RateMean() float64
StdDev() float64
Time(func())
Update(time.Duration)
UpdateSince(time.Time)
}
Timers capture the duration and rate of events.
This is an interface so as to encourage other structs to implement the Timer API as appropriate.
func NewCustomTimer ¶
Create a new timer with the given Histogram and Meter.
type UniformSample ¶
type UniformSample struct {
// contains filtered or unexported fields
}
A uniform sample using Vitter's Algorithm R.
<http://www.cs.umd.edu/~samir/498/vitter.pdf>
func (*UniformSample) Size ¶
func (s *UniformSample) Size() int
Return the size of the sample, which is at most the reservoir size.
func (*UniformSample) Update ¶
func (s *UniformSample) Update(v int64)
Update the sample with a new value.
func (*UniformSample) Values ¶
func (s *UniformSample) Values() []int64
Return all the values in the sample.
Source Files
Directories