diff --git a/ctor.go b/ctor.go index a24eeb6..75d78e8 100644 --- a/ctor.go +++ b/ctor.go @@ -9,13 +9,12 @@ var ErrImplemented = errors.New("there is implemenation already injected") var ctorImpl InternalNew = nil -// name is dot spearated path -// must be uniqe, use system naming, and unit postfix, examples: +// New returns a Creator. Name is a dot separated path which must be unique. +// Examples: +// ipfs.blockstore.bloomcache.bloom.miss.total +// ipfs.routing.dht.notresuingstream.total // -// ipfs.blockstore.bloomcache.bloom.miss.total -// ipfs.routing.dht.notresuingstream.total -// -// both arguemnts are obligatory +// Both arguemnts are mandatory. func New(name, helptext string) Creator { if ctorImpl == nil { return &noop{} @@ -24,6 +23,8 @@ func New(name, helptext string) Creator { } } +// NewCtx is like New but obtains the metric scope from the given +// context. func NewCtx(ctx context.Context, name, helptext string) Creator { return New(CtxGetScope(ctx)+"."+name, helptext) } diff --git a/interface.go b/interface.go index f123759..e5f3976 100644 --- a/interface.go +++ b/interface.go @@ -1,16 +1,24 @@ +// Package metrics provides a unified interface for different metrics +// backends (prometheus etc.). package metrics import ( "time" ) -// Increment only metric +// Counter is a metric that can only be incremented. type Counter interface { Inc() Add(float64) // Only positive } -// Increse and decrese metric +// CounterVec is a counter with tags. +type CounterVec interface { + IncWithLabelValues(labels ...string) + AddWithLabelValues(n float64, labels ...string) +} + +// Gauge is a metric that can be increased and decreased. type Gauge interface { Set(float64) // Introduced discontinuity Inc() @@ -19,6 +27,7 @@ type Gauge interface { Sub(float64) } +// Histogram metric. type Histogram interface { Observe(float64) // Adds observation to Histogram } @@ -27,7 +36,7 @@ type Summary interface { Observe(float64) // Adds observation to Summary } -// Consult http://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts +// SummaryOpts allow specifying options for Summary. See: http://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts . type SummaryOpts struct { Objectives map[float64]float64 MaxAge time.Duration @@ -35,8 +44,10 @@ type SummaryOpts struct { BufCap uint32 } +// Creator can be used to create different types of metrics. type Creator interface { Counter() Counter + CounterVec() CounterVec Gauge() Gauge Histogram(buckets []float64) Histogram diff --git a/noop.go b/noop.go index 5b59aa8..09c562d 100644 --- a/noop.go +++ b/noop.go @@ -1,6 +1,6 @@ package metrics -// Also implements the Counter interface +// Also implements the Counter and CounterVec interfaces type noop struct{} func (g *noop) Set(v float64) { @@ -27,12 +27,24 @@ func (g *noop) Observe(v float64) { // Noop } +func (g *noop) IncWithLabelValues(labels ...string) { + // Noop +} + +func (g *noop) AddWithLabelValues(v float64, labels ...string) { + // Noop +} + // Creator functions func (g *noop) Counter() Counter { return g } +func (g *noop) CounterVec() CounterVec { + return g +} + func (g *noop) Gauge() Gauge { return g } diff --git a/noop_test.go b/noop_test.go index d5da27b..8384db1 100644 --- a/noop_test.go +++ b/noop_test.go @@ -1,6 +1,7 @@ package metrics var _ Counter = (*noop)(nil) +var _ CounterVec = (*noop)(nil) var _ Gauge = (*noop)(nil) var _ Histogram = (*noop)(nil) var _ Summary = (*noop)(nil)