README
¶
go-metrics
This library provides a metrics package which can be used to instrument code,
expose application metrics, and profile runtime performance in a flexible manner.
Current API: 
Sinks
The metrics package makes use of a MetricSink interface to support delivery
to any type of backend. Currently the following sinks are provided:
- StatsiteSink : Sinks to a statsite instance (TCP)
- StatsdSink: Sinks to a StatsD / statsite instance (UDP)
- PrometheusSink: Sinks to a Prometheus metrics endpoint (exposed via HTTP for scrapes)
- InmemSink : Provides in-memory aggregation, can be used to export stats
- FanoutSink : Sinks to multiple sinks. Enables writing to multiple statsite instances for example.
- BlackholeSink : Sinks to nowhere
In addition to the sinks, the InmemSignal can be used to catch a signal,
and dump a formatted output of recent metrics. For example, when a process gets
a SIGUSR1, it can dump to stderr recent performance metrics for debugging.
Examples
Here is an example of using the package:
func SlowMethod() {
// Profiling the runtime of a method
defer metrics.MeasureSince([]string{"SlowMethod"}, time.Now())
}
// Configure a statsite sink as the global metrics sink
sink, _ := metrics.NewStatsiteSink("statsite:8125")
metrics.NewGlobal(metrics.DefaultConfig("service-name"), sink)
// Emit a Key/Value pair
metrics.EmitKey([]string{"questions", "meaning of life"}, 42)
Here is an example of setting up an signal handler:
// Setup the inmem sink and signal handler
inm := metrics.NewInmemSink(10*time.Second, time.Minute)
sig := metrics.DefaultInmemSignal(inm)
metrics.NewGlobal(metrics.DefaultConfig("service-name"), inm)
// Run some code
inm.SetGauge([]string{"foo"}, 42)
inm.EmitKey([]string{"bar"}, 30)
inm.IncrCounter([]string{"baz"}, 42)
inm.IncrCounter([]string{"baz"}, 1)
inm.IncrCounter([]string{"baz"}, 80)
inm.AddSample([]string{"method", "wow"}, 42)
inm.AddSample([]string{"method", "wow"}, 100)
inm.AddSample([]string{"method", "wow"}, 22)
....
When a signal comes in, output like the following will be dumped to stderr:
[2014-01-28 14:57:33.04 -0800 PST][G] 'foo': 42.000
[2014-01-28 14:57:33.04 -0800 PST][P] 'bar': 30.000
[2014-01-28 14:57:33.04 -0800 PST][C] 'baz': Count: 3 Min: 1.000 Mean: 41.000 Max: 80.000 Stddev: 39.509
[2014-01-28 14:57:33.04 -0800 PST][S] 'method.wow': Count: 3 Min: 22.000 Mean: 54.667 Max: 100.000 Stddev: 40.513
Documentation
¶
Index ¶
- Constants
- func AddSample(key []string, val float32)
- func EmitKey(key []string, val float32)
- func IncrCounter(key []string, val float32)
- func MeasureSince(key []string, start time.Time)
- func SetGauge(key []string, val float32)
- type AggregateSample
- type BlackholeSink
- type Config
- type FanoutSink
- type InmemSignal
- type InmemSink
- type IntervalMetrics
- type MetricSink
- type Metrics
- type StatsdSink
- type StatsiteSink
Constants ¶
const ( // DefaultSignal is used with DefaultInmemSignal DefaultSignal = syscall.SIGUSR1 )
Variables ¶
This section is empty.
Functions ¶
func IncrCounter ¶
func MeasureSince ¶
Types ¶
type AggregateSample ¶
type AggregateSample struct {
Count int // The count of emitted pairs
Sum float64 // The sum of values
SumSq float64 // The sum of squared values
Min float64 // Minimum value
Max float64 // Maximum value
LastUpdated time.Time // When value was last updated
}
AggregateSample is used to hold aggregate metrics about a sample
func (*AggregateSample) Ingest ¶
func (a *AggregateSample) Ingest(v float64)
Ingest is used to update a sample
func (*AggregateSample) Mean ¶
func (a *AggregateSample) Mean() float64
Computes a mean of the values
func (*AggregateSample) Stddev ¶
func (a *AggregateSample) Stddev() float64
Computes a Stddev of the values
func (*AggregateSample) String ¶
func (a *AggregateSample) String() string
type BlackholeSink ¶
type BlackholeSink struct{}
BlackholeSink is used to just blackhole messages
func (*BlackholeSink) AddSample ¶
func (*BlackholeSink) AddSample(key []string, val float32)
func (*BlackholeSink) EmitKey ¶
func (*BlackholeSink) EmitKey(key []string, val float32)
func (*BlackholeSink) IncrCounter ¶
func (*BlackholeSink) IncrCounter(key []string, val float32)
func (*BlackholeSink) SetGauge ¶
func (*BlackholeSink) SetGauge(key []string, val float32)
type Config ¶
type Config struct {
ServiceName string // Prefixed with keys to seperate services
HostName string // Hostname to use. If not provided and EnableHostname, it will be os.Hostname
EnableHostname bool // Enable prefixing gauge values with hostname
EnableRuntimeMetrics bool // Enables profiling of runtime metrics (GC, Goroutines, Memory)
EnableTypePrefix bool // Prefixes key with a type ("counter", "gauge", "timer")
TimerGranularity time.Duration // Granularity of timers.
ProfileInterval time.Duration // Interval to profile runtime metrics
}
Config is used to configure metrics settings
func DefaultConfig ¶
DefaultConfig provides a sane default configuration
type FanoutSink ¶
type FanoutSink []MetricSink
FanoutSink is used to sink to fanout values to multiple sinks
func (FanoutSink) AddSample ¶
func (fh FanoutSink) AddSample(key []string, val float32)
func (FanoutSink) EmitKey ¶
func (fh FanoutSink) EmitKey(key []string, val float32)
func (FanoutSink) IncrCounter ¶
func (fh FanoutSink) IncrCounter(key []string, val float32)
func (FanoutSink) SetGauge ¶
func (fh FanoutSink) SetGauge(key []string, val float32)
type InmemSignal ¶
type InmemSignal struct {
// contains filtered or unexported fields
}
InmemSignal is used to listen for a given signal, and when received, to dump the current metrics from the InmemSink to an io.Writer
func DefaultInmemSignal ¶
func DefaultInmemSignal(inmem *InmemSink) *InmemSignal
DefaultInmemSignal returns a new InmemSignal that responds to SIGUSR1 and writes output to stderr. Windows uses SIGBREAK
func NewInmemSignal ¶
NewInmemSignal creates a new InmemSignal which listens for a given signal, and dumps the current metrics out to a writer
func (*InmemSignal) Stop ¶
func (i *InmemSignal) Stop()
Stop is used to stop the InmemSignal from listening
type InmemSink ¶
type InmemSink struct {
// contains filtered or unexported fields
}
InmemSink provides a MetricSink that does in-memory aggregation without sending metrics over a network. It can be embedded within an application to provide profiling information.
func NewInmemSink ¶
NewInmemSink is used to construct a new in-memory sink. Uses an aggregation interval and maximum retention period.
func (*InmemSink) Data ¶
func (i *InmemSink) Data() []*IntervalMetrics
Data is used to retrieve all the aggregated metrics Intervals may be in use, and a read lock should be acquired
func (*InmemSink) IncrCounter ¶
type IntervalMetrics ¶
type IntervalMetrics struct {
sync.RWMutex
// The start time of the interval
Interval time.Time
// Gauges maps the key to the last set value
Gauges map[string]float32
// Points maps the string to the list of emitted values
// from EmitKey
Points map[string][]float32
// Counters maps the string key to a sum of the counter
// values
Counters map[string]*AggregateSample
// Samples maps the key to an AggregateSample,
// which has the rolled up view of a sample
Samples map[string]*AggregateSample
}
IntervalMetrics stores the aggregated metrics for a specific interval
func NewIntervalMetrics ¶
func NewIntervalMetrics(intv time.Time) *IntervalMetrics
NewIntervalMetrics creates a new IntervalMetrics for a given interval
type MetricSink ¶
type MetricSink interface {
// A Gauge should retain the last value it is set to
SetGauge(key []string, val float32)
// Should emit a Key/Value pair for each call
EmitKey(key []string, val float32)
// Counters should accumulate values
IncrCounter(key []string, val float32)
// Samples are for timing information, where quantiles are used
AddSample(key []string, val float32)
}
The MetricSink interface is used to transmit metrics information to an external system
type Metrics ¶
type Metrics struct {
Config
// contains filtered or unexported fields
}
Metrics represents an instance of a metrics sink that can be used to emit
func New ¶
func New(conf *Config, sink MetricSink) (*Metrics, error)
New is used to create a new instance of Metrics
func NewGlobal ¶
func NewGlobal(conf *Config, sink MetricSink) (*Metrics, error)
NewGlobal is the same as New, but it assigns the metrics object to be used globally as well as returning it.
func (*Metrics) IncrCounter ¶
type StatsdSink ¶
type StatsdSink struct {
// contains filtered or unexported fields
}
StatsdSink provides a MetricSink that can be used with a statsite or statsd metrics server. It uses only UDP packets, while StatsiteSink uses TCP.
func NewStatsdSink ¶
func NewStatsdSink(addr string) (*StatsdSink, error)
NewStatsdSink is used to create a new StatsdSink
func (*StatsdSink) AddSample ¶
func (s *StatsdSink) AddSample(key []string, val float32)
func (*StatsdSink) EmitKey ¶
func (s *StatsdSink) EmitKey(key []string, val float32)
func (*StatsdSink) IncrCounter ¶
func (s *StatsdSink) IncrCounter(key []string, val float32)
func (*StatsdSink) SetGauge ¶
func (s *StatsdSink) SetGauge(key []string, val float32)
func (*StatsdSink) Shutdown ¶
func (s *StatsdSink) Shutdown()
Close is used to stop flushing to statsd
type StatsiteSink ¶
type StatsiteSink struct {
// contains filtered or unexported fields
}
StatsiteSink provides a MetricSink that can be used with a statsite metrics server
func NewStatsiteSink ¶
func NewStatsiteSink(addr string) (*StatsiteSink, error)
NewStatsiteSink is used to create a new StatsiteSink
func (*StatsiteSink) AddSample ¶
func (s *StatsiteSink) AddSample(key []string, val float32)
func (*StatsiteSink) EmitKey ¶
func (s *StatsiteSink) EmitKey(key []string, val float32)
func (*StatsiteSink) IncrCounter ¶
func (s *StatsiteSink) IncrCounter(key []string, val float32)
func (*StatsiteSink) SetGauge ¶
func (s *StatsiteSink) SetGauge(key []string, val float32)
func (*StatsiteSink) Shutdown ¶
func (s *StatsiteSink) Shutdown()
Close is used to stop flushing to statsite
Source Files
Directories