From bc365741ee18e2a81a231e672dec95321fc21dac Mon Sep 17 00:00:00 2001 From: beorn7 Date: Thu, 17 Nov 2016 12:56:06 +0100 Subject: [PATCH] Improve timer examples --- prometheus/example_timer_batch_test.go | 48 ------------------------ prometheus/example_timer_complex_test.go | 14 ++++--- prometheus/example_timer_gauge_test.go | 38 +++++++++++++++++++ prometheus/timer.go | 2 +- 4 files changed, 47 insertions(+), 55 deletions(-) delete mode 100644 prometheus/example_timer_batch_test.go create mode 100644 prometheus/example_timer_gauge_test.go diff --git a/prometheus/example_timer_batch_test.go b/prometheus/example_timer_batch_test.go deleted file mode 100644 index 1e86209..0000000 --- a/prometheus/example_timer_batch_test.go +++ /dev/null @@ -1,48 +0,0 @@ -// Copyright 2014 The Prometheus Authors -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package prometheus_test - -import ( - "time" - - "github.com/prometheus/client_golang/prometheus" -) - -var ( - // For periodic or batch processes that run much less frequently than - // the Prometheus scrape, it makes sense to use a Gauge to observe the - // duration. - // See https://prometheus.io/docs/practices/instrumentation/#batch-jobs - batchDuration = prometheus.NewGauge(prometheus.GaugeOpts{ - Name: "example_batch_duration_seconds", - Help: "Duration of the last batch run.", - }) -) - -func performBatch() { - // The Set method of the Gauge is used to observe the duration. - timer := prometheus.NewTimer(prometheus.ObserverFunc(batchDuration.Set)) - defer timer.ObserveDuration() - - // Actually perform the batch of work. - // ... -} - -func ExampleTimer_batch() { - // 10m is much longer than the usual scrape interval of Prometheus. - c := time.Tick(10 * time.Minute) - for _ = range c { - performBatch() - } -} diff --git a/prometheus/example_timer_complex_test.go b/prometheus/example_timer_complex_test.go index 692a7c4..7637880 100644 --- a/prometheus/example_timer_complex_test.go +++ b/prometheus/example_timer_complex_test.go @@ -29,7 +29,9 @@ var ( // even larger amount of time series. Request counters partitioned by // status code are usually OK as each counter only creates one time // series. Histograms are way more expensive, so partition with care and - // only where you really need separate latency tracking. + // only where you really need separate latency tracking. Partitioning by + // status class is only an example. In concrete cases, other partitions + // might make more sense. apiRequestDuration = prometheus.NewHistogramVec( prometheus.HistogramOpts{ Name: "api_request_duration_seconds", @@ -46,15 +48,15 @@ func handler(w http.ResponseWriter, r *http.Request) { // decides wich Histogram's Observe method is called. timer := prometheus.NewTimer(prometheus.ObserverFunc(func(v float64) { switch { - case status >= http.StatusInternalServerError: + case status >= 500: // Server error. apiRequestDuration.WithLabelValues("5xx").Observe(v) - case status >= http.StatusBadRequest: + case status >= 400: // Client error. apiRequestDuration.WithLabelValues("4xx").Observe(v) - case status >= http.StatusMultipleChoices: + case status >= 300: // Redirection. apiRequestDuration.WithLabelValues("3xx").Observe(v) - case status >= http.StatusOK: + case status >= 200: // Success. apiRequestDuration.WithLabelValues("2xx").Observe(v) - default: + default: // Informational. apiRequestDuration.WithLabelValues("1xx").Observe(v) } })) diff --git a/prometheus/example_timer_gauge_test.go b/prometheus/example_timer_gauge_test.go new file mode 100644 index 0000000..dd91066 --- /dev/null +++ b/prometheus/example_timer_gauge_test.go @@ -0,0 +1,38 @@ +// Copyright 2014 The Prometheus Authors +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package prometheus_test + +import "github.com/prometheus/client_golang/prometheus" + +var ( + // If a function is called rarely (i.e. not more often than scrapes + // happen) or ideally only once (like in a batch job), it can make sense + // to use a Gauge for timing the function call. For timing a batch job + // and pushing the result to a Pushgateway, see also the comprehensive + // example in the push package. + funcDuration = prometheus.NewGauge(prometheus.GaugeOpts{ + Name: "example_function_duration_seconds", + Help: "Duration of the last call of an example function.", + }) +) + +func ExampleTimer_gauge() error { + // The Set method of the Gauge is used to observe the duration. + timer := prometheus.NewTimer(prometheus.ObserverFunc(funcDuration.Set)) + defer timer.ObserveDuration() + + // Do something. Return errors as encountered. The use of 'defer' above + // makes sure the function is still timed properly. + return nil +} diff --git a/prometheus/timer.go b/prometheus/timer.go index 7bd9d07..f4cac5a 100644 --- a/prometheus/timer.go +++ b/prometheus/timer.go @@ -29,7 +29,7 @@ type Observer interface { // two general use cases: // // The most common one is to use a Gauge as the Observer for a Timer. -// See the "Batch" Timer example. +// See the "Gauge" Timer example. // // The more advanced use case is to create a function that dynamically decides // which Observer to use for observing the duration. See the "Complex" Timer