From 606b8f85e51a39f527623efe2599804c28f5bce0 Mon Sep 17 00:00:00 2001
From: beorn7 <beorn@soundcloud.com>
Date: Fri, 18 Nov 2016 16:29:59 +0100
Subject: [PATCH] - Point from Inc and Dec to Add and Sub in doc comments.

- Deprecate Untyped for direct instrumentation.

- Add a SetToCurrentTime method to Gauge

Note that adding the SetToCurrentTime method is not really following
Go's principle of lean interfaces. However, the Gauge interface is
already quite fat. (The only methods really required are Set and
Add. Everything else could be expressed in terms of those two.) So we
have already quite a few "convenience" methods traditionally, so I
think we should stay consistent here.

The alternatives would be:

- Not support SetToCurrentTime at all (it's only a SHOULD in the
  guidelines).

- A top level function `SetToCurrentTime(Gauge)`.

- Just a helper `CurrentTime()` that returns the curent unix time in
  seconds as a float (which is pretty verbose using the standard
  library, see code in this commit). This would allow
  `myGauge.Set(CurrentTime)`.

Weighing all circumstances, I believe the way in this commit is the
least evil. Issue #223 could be used to rework interfaces more
fundamentally in a breaking change if feasible.
---
 prometheus/counter.go    |  3 ++-
 prometheus/gauge.go      | 13 +++++++++----
 prometheus/gauge_test.go | 20 ++++++++++++++++++++
 prometheus/untyped.go    |  5 +++++
 prometheus/value.go      |  5 +++++
 5 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/prometheus/counter.go b/prometheus/counter.go
index d0fdd5d..72d5256 100644
--- a/prometheus/counter.go
+++ b/prometheus/counter.go
@@ -30,7 +30,8 @@ type Counter interface {
 	Metric
 	Collector
 
-	// Inc increments the counter by 1.
+	// Inc increments the counter by 1. Use Add to increment it by arbitrary
+	// non-negative values.
 	Inc()
 	// Add adds the given value to the counter. It panics if the value is <
 	// 0.
diff --git a/prometheus/gauge.go b/prometheus/gauge.go
index 8b70e51..9ab5a3d 100644
--- a/prometheus/gauge.go
+++ b/prometheus/gauge.go
@@ -27,16 +27,21 @@ type Gauge interface {
 
 	// Set sets the Gauge to an arbitrary value.
 	Set(float64)
-	// Inc increments the Gauge by 1.
+	// Inc increments the Gauge by 1. Use Add to increment it by arbitrary
+	// values.
 	Inc()
-	// Dec decrements the Gauge by 1.
+	// Dec decrements the Gauge by 1. Use Sub to decrement it by arbitrary
+	// values.
 	Dec()
-	// Add adds the given value to the Gauge. (The value can be
-	// negative, resulting in a decrease of the Gauge.)
+	// Add adds the given value to the Gauge. (The value can be negative,
+	// resulting in a decrease of the Gauge.)
 	Add(float64)
 	// Sub subtracts the given value from the Gauge. (The value can be
 	// negative, resulting in an increase of the Gauge.)
 	Sub(float64)
+
+	// SetToCurrentTime sets the Gauge to the current Unix time in seconds.
+	SetToCurrentTime()
 }
 
 // GaugeOpts is an alias for Opts. See there for doc comments.
diff --git a/prometheus/gauge_test.go b/prometheus/gauge_test.go
index 48cab46..8e5f002 100644
--- a/prometheus/gauge_test.go
+++ b/prometheus/gauge_test.go
@@ -19,6 +19,7 @@ import (
 	"sync"
 	"testing"
 	"testing/quick"
+	"time"
 
 	dto "github.com/prometheus/client_model/go"
 )
@@ -180,3 +181,22 @@ func TestGaugeFunc(t *testing.T) {
 		t.Errorf("expected %q, got %q", expected, got)
 	}
 }
+
+func TestGaugeSetCurrentTime(t *testing.T) {
+	g := NewGauge(GaugeOpts{
+		Name: "test_name",
+		Help: "test help",
+	})
+	g.SetToCurrentTime()
+	unixTime := float64(time.Now().Unix())
+
+	m := &dto.Metric{}
+	g.Write(m)
+
+	delta := unixTime - m.GetGauge().GetValue()
+	// This is just a smoke test to make sure SetToCurrentTime is not
+	// totally off. Tests with current time involved are hard...
+	if math.Abs(delta) > 5 {
+		t.Errorf("Gauge set to current time deviates from current time by more than 5s, delta is %f seconds", delta)
+	}
+}
diff --git a/prometheus/untyped.go b/prometheus/untyped.go
index 5faf7e6..065501d 100644
--- a/prometheus/untyped.go
+++ b/prometheus/untyped.go
@@ -20,6 +20,11 @@ package prometheus
 // no type information is implied.
 //
 // To create Untyped instances, use NewUntyped.
+//
+// Deprecated: The Untyped type is deprecated because it doesn't make sense in
+// direct instrumentation. If you need to mirror an external metric of unknown
+// type (usually while writing exporters), Use MustNewConstMetric to create an
+// untyped metric instance on the fly.
 type Untyped interface {
 	Metric
 	Collector
diff --git a/prometheus/value.go b/prometheus/value.go
index a944c37..7d3e810 100644
--- a/prometheus/value.go
+++ b/prometheus/value.go
@@ -19,6 +19,7 @@ import (
 	"math"
 	"sort"
 	"sync/atomic"
+	"time"
 
 	dto "github.com/prometheus/client_model/go"
 
@@ -80,6 +81,10 @@ func (v *value) Set(val float64) {
 	atomic.StoreUint64(&v.valBits, math.Float64bits(val))
 }
 
+func (v *value) SetToCurrentTime() {
+	v.Set(float64(time.Now().UnixNano()) / 1e9)
+}
+
 func (v *value) Inc() {
 	v.Add(1)
 }