Merge pull request #260 from prometheus/beorn7/doc

Extend the example for pushing to pushgateway

prometheus/push/example_add_from_gatherer_test.go

@@ -0,0 +1,83 @@
+// Copyright 2016 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.
+
+// Copyright (c) 2013, The Prometheus Authors
+// All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found
+// in the LICENSE file.
+
+package push_test
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/push"
+)
+
+var (
+	completionTime = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "db_backup_last_completion_timestamp_seconds",
+		Help: "The timestamp of the last completion of a DB backup, successful or not.",
+	})
+	successTime = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "db_backup_last_success_timestamp_seconds",
+		Help: "The timestamp of the last successful completion of a DB backup.",
+	})
+	duration = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "db_backup_duration_seconds",
+		Help: "The duration of the last DB backup in seconds.",
+	})
+	records = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "db_backup_records_processed",
+		Help: "The number of records processed in the last DB backup.",
+	})
+)
+
+func performBackup() (int, error) {
+	// Perform the backup and return the number of backed up records and any
+	// applicable error.
+	// ...
+	return 42, nil
+}
+
+func ExampleAddFromGatherer() {
+	registry := prometheus.NewRegistry()
+	registry.MustRegister(completionTime, duration, records)
+	// Note that successTime is not registered at this time.
+
+	start := time.Now()
+	n, err := performBackup()
+	records.Set(float64(n))
+	duration.Set(time.Since(start).Seconds())
+	completionTime.SetToCurrentTime()
+	if err != nil {
+		fmt.Println("DB backup failed:", err)
+	} else {
+		// Only now register successTime.
+		registry.MustRegister(successTime)
+		successTime.SetToCurrentTime()
+	}
+	// AddFromGatherer is used here rather than FromGatherer to not delete a
+	// previously pushed success timestamp in case of a failure of this
+	// backup.
+	if err := push.AddFromGatherer(
+		"db_backup", nil,
+		"http://pushgateway:9091",
+		registry,
+	); err != nil {
+		fmt.Println("Could not push to Pushgateway:", err)
+	}
+}

prometheus/push/examples_test.go

@@ -15,7 +15,6 @@ package push_test
 
 import (
 	"fmt"
-	"time"
 
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/prometheus/client_golang/prometheus/push"
@@ -26,7 +25,7 @@ func ExampleCollectors() {
 		Name: "db_backup_last_completion_timestamp_seconds",
 		Help: "The timestamp of the last successful completion of a DB backup.",
 	})
-	completionTime.Set(float64(time.Now().Unix()))
+	completionTime.SetToCurrentTime()
 	if err := push.Collectors(
 		"db_backup", push.HostnameGroupingKey(),
 		"http://pushgateway:9091",
@@ -35,22 +34,3 @@ func ExampleCollectors() {
 		fmt.Println("Could not push completion time to Pushgateway:", err)
 	}
 }
-
-func ExampleFromGatherer() {
-	registry := prometheus.NewRegistry()
-
-	completionTime := prometheus.NewGauge(prometheus.GaugeOpts{
-		Name: "db_backup_last_completion_timestamp_seconds",
-		Help: "The timestamp of the last successful completion of a DB backup.",
-	})
-	registry.MustRegister(completionTime)
-
-	completionTime.Set(float64(time.Now().Unix()))
-	if err := push.FromGatherer(
-		"db_backup", push.HostnameGroupingKey(),
-		"http://pushgateway:9091",
-		registry,
-	); err != nil {
-		fmt.Println("Could not push completion time to Pushgateway:", err)
-	}
-}