From 38045061c36d44bfd979b40d2dac9ad47f638b1a Mon Sep 17 00:00:00 2001
From: Oleg Zaytsev <mail@olegzaytsev.com>
Date: Tue, 21 Apr 2020 10:56:51 +0200
Subject: [PATCH] GaugeFunc: ConstLabels godoc example

Document the example usage of ConstLabels to register several GaugeFuncs
on the same metric name. Also reference it from the NewCounterFunc
documentation as it's similar.

Ref: https://github.com/prometheus/client_golang/pull/736

Signed-off-by: Oleg Zaytsev <mail@olegzaytsev.com>
---
 prometheus/counter.go       |  2 ++
 prometheus/examples_test.go | 40 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/prometheus/counter.go b/prometheus/counter.go
index df72fcf..0e1b48c 100644
--- a/prometheus/counter.go
+++ b/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),
diff --git a/prometheus/examples_test.go b/prometheus/examples_test.go
index bdb567e..903d4d9 100644
--- a/prometheus/examples_test.go
+++ b/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{