Added doc comments
This commit is contained in:
parent
8aba21aba3
commit
18c13ef63d
|
@ -21,31 +21,77 @@ type Observer interface {
|
|||
Observe(float64)
|
||||
}
|
||||
|
||||
// observerFunc is a function that implements Observer.
|
||||
type observerFunc func(float64)
|
||||
|
||||
func (o observerFunc) Observe(value float64) {
|
||||
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 {
|
||||
begin time.Time
|
||||
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 {
|
||||
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 {
|
||||
t.observer = o
|
||||
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 {
|
||||
t.observer = observerFunc(g.Set)
|
||||
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() {
|
||||
if t.observer != nil {
|
||||
t.observer.Observe(time.Since(t.begin).Seconds())
|
||||
|
|
Loading…
Reference in New Issue