Merge pull request #321 from prometheus/beorn7/doc

Document the use of Go1.9+ for monotonic time where applicable
This commit is contained in:
Björn Rabenstein 2017-06-29 16:21:10 +02:00 committed by GitHub
commit 77934284f4
5 changed files with 17 additions and 2 deletions

View File

@ -81,6 +81,9 @@ func InstrumentRoundTripperCounter(counter *prometheus.CounterVec, next http.Rou
// //
// If the wrapped RoundTripper panics or returns a non-nil error, no values are // If the wrapped RoundTripper panics or returns a non-nil error, no values are
// reported. // reported.
//
// Note that this method is only guaranteed to never observe negative durations
// if used with Go1.9+.
func InstrumentRoundTripperDuration(obs prometheus.ObserverVec, next http.RoundTripper) RoundTripperFunc { func InstrumentRoundTripperDuration(obs prometheus.ObserverVec, next http.RoundTripper) RoundTripperFunc {
code, method := checkLabels(obs) code, method := checkLabels(obs)

View File

@ -48,8 +48,10 @@ type InstrumentTrace struct {
// RoundTripper and reports times to hook functions provided in the // RoundTripper and reports times to hook functions provided in the
// InstrumentTrace struct. Hook functions that are not present in the provided // InstrumentTrace struct. Hook functions that are not present in the provided
// InstrumentTrace struct are ignored. Times reported to the hook functions are // InstrumentTrace struct are ignored. Times reported to the hook functions are
// time since the start of the request. Note that partitioning of Histograms // time since the start of the request. Only with Go1.9+, those times are
// is expensive and should be used judiciously. // guaranteed to never be negative. (Earlier Go versions are not using a
// monotonic clock.) Note that partitioning of Histograms is expensive and
// should be used judiciously.
// //
// For hook functions that receive an error as an argument, no observations are // For hook functions that receive an error as an argument, no observations are
// made in the event of a non-nil error value. // made in the event of a non-nil error value.

View File

@ -54,6 +54,9 @@ func InstrumentHandlerInFlight(g prometheus.Gauge, next http.Handler) http.Handl
// If the wrapped Handler does not set a status code, a status code of 200 is assumed. // If the wrapped Handler does not set a status code, a status code of 200 is assumed.
// //
// If the wrapped Handler panics, no values are reported. // If the wrapped Handler panics, no values are reported.
//
// Note that this method is only guaranteed to never observe negative durations
// if used with Go1.9+.
func InstrumentHandlerDuration(obs prometheus.ObserverVec, next http.Handler) http.HandlerFunc { func InstrumentHandlerDuration(obs prometheus.ObserverVec, next http.Handler) http.HandlerFunc {
code, method := checkLabels(obs) code, method := checkLabels(obs)
@ -120,6 +123,9 @@ func InstrumentHandlerCounter(counter *prometheus.CounterVec, next http.Handler)
// If the wrapped Handler panics before calling WriteHeader, no value is // If the wrapped Handler panics before calling WriteHeader, no value is
// reported. // reported.
// //
// Note that this method is only guaranteed to never observe negative durations
// if used with Go1.9+.
//
// See the example for InstrumentHandlerDuration for example usage. // See the example for InstrumentHandlerDuration for example usage.
func InstrumentHandlerTimeToWriteHeader(obs prometheus.ObserverVec, next http.Handler) http.HandlerFunc { func InstrumentHandlerTimeToWriteHeader(obs prometheus.ObserverVec, next http.Handler) http.HandlerFunc {
code, method := checkLabels(obs) code, method := checkLabels(obs)

View File

@ -61,6 +61,7 @@ func ExampleAddFromGatherer() {
start := time.Now() start := time.Now()
n, err := performBackup() n, err := performBackup()
records.Set(float64(n)) records.Set(float64(n))
// Note that time.Since only uses a monotonic clock in Go1.9+.
duration.Set(time.Since(start).Seconds()) duration.Set(time.Since(start).Seconds())
completionTime.SetToCurrentTime() completionTime.SetToCurrentTime()
if err != nil { if err != nil {

View File

@ -41,6 +41,9 @@ func NewTimer(o Observer) *Timer {
// NewTimer. It calls the Observe method of the Observer provided during // NewTimer. It calls the Observe method of the Observer provided during
// construction with the duration in seconds as an argument. ObserveDuration is // construction with the duration in seconds as an argument. ObserveDuration is
// usually called with a defer statement. // usually called with a defer statement.
//
// Note that this method is only guaranteed to never observe negative durations
// if used with Go1.9+.
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())