Added doc comments

This commit is contained in:
beorn7 2016-11-14 20:53:36 +01:00
parent 8aba21aba3
commit 18c13ef63d
1 changed files with 46 additions and 0 deletions

View File

@ -21,31 +21,77 @@ type Observer interface {
Observe(float64) Observe(float64)
} }
// observerFunc is a function that implements Observer.
type observerFunc func(float64) type observerFunc func(float64)
func (o observerFunc) Observe(value float64) { func (o observerFunc) Observe(value float64) {
o(value) o(value)
} }
// Timer is a helper type to time functions. Use NewTimer to create new
// instances. The most common usage pattern is to time a function with a
// Histogram in the following way:
// func timeMe() {
// t := NewTimer().With(myHistogram)
// defer t.ObserveDuration()
// // Do something.
// }
// See the documentation of the methods for special cases.
type Timer struct { type Timer struct {
begin time.Time begin time.Time
observer Observer observer Observer
} }
// NewTimer creates a new Timer. To time anything, an Observer (i.e. a Histogram
// or a Summary) or a Gague has to be bound to it, the former with the With
// method, the latter with the WithGauge method.
func NewTimer() *Timer { func NewTimer() *Timer {
return &Timer{begin: time.Now()} return &Timer{begin: time.Now()}
} }
// With binds an Observer (i.e. a Histogram or a Summary) to the Timer and
// returns the Timer for convenience. In most cases, the Observer to be used is
// already known at construction time, so it can be set immediately:
// t := NewTimer().With(myObserver)
//
// With can also be called later, to bind an Observer for the first time or to
// change the bound Observer. It can be called with nil to unbind a previously
// bound Observer. Both is useful for recording with different Observers (or
// none) depending on the outcome of the timed function. Note that timing
// depending on the outcome can be confusing and should only be used after
// careful consideration.
//
// The ObserveDuration method of the Timer records the duration by calling the
// Observe method of the bound Observer with the time elapsed since NewTimer was
// called (in seconds).
//
// Note that a Gauge bound with WithGauge overrides the Observer bound with With
// and vice versa.
func (t *Timer) With(o Observer) *Timer { func (t *Timer) With(o Observer) *Timer {
t.observer = o t.observer = o
return t return t
} }
// WithGauge binds a Gauge to the Timer and returns the Timer for
// convenience. This works in the same way as With works for Observers. To
// record the time, the Set method of the Gauge is called (with the recorded
// duration in seconds). Note that timing with Gauges is only useful for events
// that happen less frequently than the scrape interval or for one-shot batch
// jobs (where the recorded duration is pushed to a Pushgateway).
//
// Note that a Gauge bound with WithGauge overrides the Observer bound with With
// and vice versa.
func (t *Timer) WithGauge(g Gauge) *Timer { func (t *Timer) WithGauge(g Gauge) *Timer {
t.observer = observerFunc(g.Set) t.observer = observerFunc(g.Set)
return t return t
} }
// ObserveDuration records the duration passed since NewTimer was called. If an
// Observer has been bound with the With method, ObserveDuration calls its
// Observe method with the duration in seconds as an argument. If a Gauge has
// been bound with the WithGauge method, ObserveDuration calls its Set method
// with the duration in seconds as an argument. ObserveDuration is usually
// called with a defer statement.
func (t *Timer) ObserveDuration() { func (t *Timer) ObserveDuration() {
if t.observer != nil { if t.observer != nil {
t.observer.Observe(time.Since(t.begin).Seconds()) t.observer.Observe(time.Since(t.begin).Seconds())