Merge pull request #738 from colega/colega/gauge-func-const-labels-godoc

GaugeFunc: ConstLabels godoc example

prometheus/counter.go

@@ -309,6 +309,8 @@ type CounterFunc interface {
 // provided function must be concurrency-safe. The function should also honor
 // the contract for a Counter (values only go up, not down), but compliance will
 // not be checked.
+//
+// Check out the ExampleGaugeFunc examples for the similar GaugeFunc.
 func NewCounterFunc(opts CounterOpts, function func() float64) CounterFunc {
 	return newValueFunc(NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),

prometheus/examples_test.go

@@ -72,7 +72,7 @@ func ExampleGaugeVec() {
 	opsQueued.With(prometheus.Labels{"type": "delete", "user": "alice"}).Inc()
 }
 
-func ExampleGaugeFunc() {
+func ExampleGaugeFunc_simple() {
 	if err := prometheus.Register(prometheus.NewGaugeFunc(
 		prometheus.GaugeOpts{
 			Subsystem: "runtime",
@@ -90,6 +90,44 @@ func ExampleGaugeFunc() {
 	// GaugeFunc 'goroutines_count' registered.
 }
 
+func ExampleGaugeFunc_constLabels() {
+	// primaryDB and secondaryDB represent two example *sql.DB connections we want to instrument.
+	var primaryDB, secondaryDB interface {
+		Stats() struct{ OpenConnections int }
+	}
+
+	if err := prometheus.Register(prometheus.NewGaugeFunc(
+		prometheus.GaugeOpts{
+			Namespace:   "mysql",
+			Name:        "connections_open",
+			Help:        "Number of mysql connections open.",
+			ConstLabels: prometheus.Labels{"destination": "primary"},
+		},
+		func() float64 { return float64(primaryDB.Stats().OpenConnections) },
+	)); err == nil {
+		fmt.Println(`GaugeFunc 'connections_open' for primary DB connection registered with labels {destination="primary"}`)
+	}
+
+	if err := prometheus.Register(prometheus.NewGaugeFunc(
+		prometheus.GaugeOpts{
+			Namespace:   "mysql",
+			Name:        "connections_open",
+			Help:        "Number of mysql connections open.",
+			ConstLabels: prometheus.Labels{"destination": "secondary"},
+		},
+		func() float64 { return float64(secondaryDB.Stats().OpenConnections) },
+	)); err == nil {
+		fmt.Println(`GaugeFunc 'connections_open' for secondary DB connection registered with labels {destination="secondary"}`)
+	}
+
+	// Note that we can register more than once GaugeFunc with same metric name
+	// as long as their const labels are consistent.
+
+	// Output:
+	// GaugeFunc 'connections_open' for primary DB connection registered with labels {destination="primary"}
+	// GaugeFunc 'connections_open' for secondary DB connection registered with labels {destination="secondary"}
+}
+
 func ExampleCounterVec() {
 	httpReqs := prometheus.NewCounterVec(
 		prometheus.CounterOpts{