Bring Gauges and Counters in line with client library guidelines

- 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

@@ -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
+	// positive values.
 	Inc()
 	// Add adds the given value to the counter. It panics if the value is <
 	// 0.

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.

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)
+	}
+}

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

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)
 }