Add the UpDownCounter instrument (#745)

* Add UpDownCounter to the API

* Add an SDK test

* Comment fix

api/metric/api_test.go

@@ -93,57 +93,90 @@ func TestOptions(t *testing.T) {
 }
 
 func TestCounter(t *testing.T) {
-	{
+	// N.B. the API does not check for negative
+	// values, that's the SDK's responsibility.
+	t.Run("float64 counter", func(t *testing.T) {
 		mockSDK, meter := mockTest.NewMeter()
 		c := Must(meter).NewFloat64Counter("test.counter.float")
 		ctx := context.Background()
 		labels := []kv.KeyValue{kv.String("A", "B")}
-		c.Add(ctx, 42, labels...)
+		c.Add(ctx, 1994.1, labels...)
 		boundInstrument := c.Bind(labels...)
-		boundInstrument.Add(ctx, 42)
+		boundInstrument.Add(ctx, -742)
 		meter.RecordBatch(ctx, labels, c.Measurement(42))
-		t.Log("Testing float counter")
-		checkBatches(t, ctx, labels, mockSDK, metric.Float64NumberKind, c.SyncImpl())
-	}
-	{
+		checkSyncBatches(t, ctx, labels, mockSDK, metric.Float64NumberKind, metric.CounterKind, c.SyncImpl(),
+			1994.1, -742, 42,
+		)
+	})
+	t.Run("int64 counter", func(t *testing.T) {
 		mockSDK, meter := mockTest.NewMeter()
 		c := Must(meter).NewInt64Counter("test.counter.int")
 		ctx := context.Background()
 		labels := []kv.KeyValue{kv.String("A", "B"), kv.String("C", "D")}
 		c.Add(ctx, 42, labels...)
 		boundInstrument := c.Bind(labels...)
-		boundInstrument.Add(ctx, 42)
+		boundInstrument.Add(ctx, 4200)
+		meter.RecordBatch(ctx, labels, c.Measurement(420000))
+		checkSyncBatches(t, ctx, labels, mockSDK, metric.Int64NumberKind, metric.CounterKind, c.SyncImpl(),
+			42, 4200, 420000,
+		)
+
+	})
+	t.Run("int64 updowncounter", func(t *testing.T) {
+		mockSDK, meter := mockTest.NewMeter()
+		c := Must(meter).NewInt64UpDownCounter("test.updowncounter.int")
+		ctx := context.Background()
+		labels := []kv.KeyValue{kv.String("A", "B"), kv.String("C", "D")}
+		c.Add(ctx, 100, labels...)
+		boundInstrument := c.Bind(labels...)
+		boundInstrument.Add(ctx, -100)
 		meter.RecordBatch(ctx, labels, c.Measurement(42))
-		t.Log("Testing int counter")
-		checkBatches(t, ctx, labels, mockSDK, metric.Int64NumberKind, c.SyncImpl())
-	}
+		checkSyncBatches(t, ctx, labels, mockSDK, metric.Int64NumberKind, metric.UpDownCounterKind, c.SyncImpl(),
+			100, -100, 42,
+		)
+	})
+	t.Run("float64 updowncounter", func(t *testing.T) {
+		mockSDK, meter := mockTest.NewMeter()
+		c := Must(meter).NewFloat64UpDownCounter("test.updowncounter.float")
+		ctx := context.Background()
+		labels := []kv.KeyValue{kv.String("A", "B"), kv.String("C", "D")}
+		c.Add(ctx, 100.1, labels...)
+		boundInstrument := c.Bind(labels...)
+		boundInstrument.Add(ctx, -76)
+		meter.RecordBatch(ctx, labels, c.Measurement(-100.1))
+		checkSyncBatches(t, ctx, labels, mockSDK, metric.Float64NumberKind, metric.UpDownCounterKind, c.SyncImpl(),
+			100.1, -76, -100.1,
+		)
+	})
 }
 
 func TestValueRecorder(t *testing.T) {
-	{
+	t.Run("float64 valuerecorder", func(t *testing.T) {
 		mockSDK, meter := mockTest.NewMeter()
 		m := Must(meter).NewFloat64ValueRecorder("test.valuerecorder.float")
 		ctx := context.Background()
 		labels := []kv.KeyValue{}
 		m.Record(ctx, 42, labels...)
 		boundInstrument := m.Bind(labels...)
-		boundInstrument.Record(ctx, 42)
-		meter.RecordBatch(ctx, labels, m.Measurement(42))
-		t.Log("Testing float valuerecorder")
-		checkBatches(t, ctx, labels, mockSDK, metric.Float64NumberKind, m.SyncImpl())
-	}
-	{
+		boundInstrument.Record(ctx, 0)
+		meter.RecordBatch(ctx, labels, m.Measurement(-100.5))
+		checkSyncBatches(t, ctx, labels, mockSDK, metric.Float64NumberKind, metric.ValueRecorderKind, m.SyncImpl(),
+			42, 0, -100.5,
+		)
+	})
+	t.Run("int64 valuerecorder", func(t *testing.T) {
 		mockSDK, meter := mockTest.NewMeter()
 		m := Must(meter).NewInt64ValueRecorder("test.valuerecorder.int")
 		ctx := context.Background()
 		labels := []kv.KeyValue{kv.Int("I", 1)}
-		m.Record(ctx, 42, labels...)
+		m.Record(ctx, 173, labels...)
 		boundInstrument := m.Bind(labels...)
-		boundInstrument.Record(ctx, 42)
-		meter.RecordBatch(ctx, labels, m.Measurement(42))
-		t.Log("Testing int valuerecorder")
-		checkBatches(t, ctx, labels, mockSDK, metric.Int64NumberKind, m.SyncImpl())
-	}
+		boundInstrument.Record(ctx, 80)
+		meter.RecordBatch(ctx, labels, m.Measurement(0))
+		checkSyncBatches(t, ctx, labels, mockSDK, metric.Int64NumberKind, metric.ValueRecorderKind, m.SyncImpl(),
+			173, 80, 0,
+		)
+	})
 }
 
 func TestObserverInstruments(t *testing.T) {
@@ -170,7 +203,7 @@ func TestObserverInstruments(t *testing.T) {
 	}
 }
 
-func checkBatches(t *testing.T, ctx context.Context, labels []kv.KeyValue, mock *mockTest.MeterImpl, kind metric.NumberKind, instrument metric.InstrumentImpl) {
+func checkSyncBatches(t *testing.T, ctx context.Context, labels []kv.KeyValue, mock *mockTest.MeterImpl, nkind metric.NumberKind, mkind metric.Kind, instrument metric.InstrumentImpl, expected ...float64) {
 	t.Helper()
 	if len(mock.MeasurementBatches) != 3 {
 		t.Errorf("Expected 3 recorded measurement batches, got %d", len(mock.MeasurementBatches))
@@ -195,6 +228,8 @@ func checkBatches(t *testing.T, ctx context.Context, labels []kv.KeyValue, mock
 		}
 		for j := 0; j < minMLen; j++ {
 			measurement := got.Measurements[j]
+			require.Equal(t, mkind, measurement.Instrument.Descriptor().MetricKind())
+
 			if measurement.Instrument.Implementation() != ourInstrument {
 				d := func(iface interface{}) string {
 					i := iface.(*mockTest.Instrument)
@@ -202,9 +237,9 @@ func checkBatches(t *testing.T, ctx context.Context, labels []kv.KeyValue, mock
 				}
 				t.Errorf("Wrong recorded instrument in measurement %d in batch %d, expected %s, got %s", j, i, d(ourInstrument), d(measurement.Instrument.Implementation()))
 			}
-			ft := fortyTwo(t, kind)
-			if measurement.Number.CompareNumber(kind, ft) != 0 {
-				t.Errorf("Wrong recorded value in measurement %d in batch %d, expected %s, got %s", j, i, ft.Emit(kind), measurement.Number.Emit(kind))
+			expect := number(t, nkind, expected[i])
+			if measurement.Number.CompareNumber(nkind, expect) != 0 {
+				t.Errorf("Wrong recorded value in measurement %d in batch %d, expected %s, got %s", j, i, expect.Emit(nkind), measurement.Number.Emit(nkind))
 			}
 		}
 	}
@@ -248,11 +283,11 @@ func TestBatchObserverInstruments(t *testing.T) {
 
 	m1 := got.Measurements[0]
 	require.Equal(t, impl1, m1.Instrument.Implementation().(*mockTest.Async))
-	require.Equal(t, 0, m1.Number.CompareNumber(metric.Int64NumberKind, fortyTwo(t, metric.Int64NumberKind)))
+	require.Equal(t, 0, m1.Number.CompareNumber(metric.Int64NumberKind, number(t, metric.Int64NumberKind, 42)))
 
 	m2 := got.Measurements[1]
 	require.Equal(t, impl2, m2.Instrument.Implementation().(*mockTest.Async))
-	require.Equal(t, 0, m2.Number.CompareNumber(metric.Float64NumberKind, fortyTwo(t, metric.Float64NumberKind)))
+	require.Equal(t, 0, m2.Number.CompareNumber(metric.Float64NumberKind, number(t, metric.Float64NumberKind, 42)))
 }
 
 func checkObserverBatch(t *testing.T, labels []kv.KeyValue, mock *mockTest.MeterImpl, kind metric.NumberKind, observer metric.AsyncImpl) {
@@ -273,20 +308,19 @@ func checkObserverBatch(t *testing.T, labels []kv.KeyValue, mock *mockTest.Meter
 	}
 	measurement := got.Measurements[0]
 	assert.Equal(t, o, measurement.Instrument.Implementation().(*mockTest.Async))
-	ft := fortyTwo(t, kind)
+	ft := number(t, kind, 42)
 	assert.Equal(t, 0, measurement.Number.CompareNumber(kind, ft))
 }
 
-func fortyTwo(t *testing.T, kind metric.NumberKind) metric.Number {
+func number(t *testing.T, kind metric.NumberKind, value float64) metric.Number {
 	t.Helper()
 	switch kind {
 	case metric.Int64NumberKind:
-		return metric.NewInt64Number(42)
+		return metric.NewInt64Number(int64(value))
 	case metric.Float64NumberKind:
-		return metric.NewFloat64Number(42)
+		return metric.NewFloat64Number(value)
 	}
-	t.Errorf("Invalid value kind %q", kind)
-	return metric.NewInt64Number(0)
+	panic("invalid number kind")
 }
 
 type testWrappedMeter struct {

api/metric/kind.go

@@ -24,6 +24,9 @@ const (
 	ValueRecorderKind Kind = iota
 	// ValueObserverKind indicates an ValueObserver instrument.
 	ValueObserverKind
+
 	// CounterKind indicates a Counter instrument.
 	CounterKind
+	// UpDownCounterKind indicates a UpDownCounter instrument.
+	UpDownCounterKind
 )

api/metric/kind_string.go

@@ -11,11 +11,12 @@ func _() {
 	_ = x[ValueRecorderKind-0]
 	_ = x[ValueObserverKind-1]
 	_ = x[CounterKind-2]
+	_ = x[UpDownCounterKind-3]
 }
 
-const _Kind_name = "ValueRecorderKindValueObserverKindCounterKind"
+const _Kind_name = "ValueRecorderKindValueObserverKindCounterKindUpDownCounterKind"
 
-var _Kind_index = [...]uint8{0, 17, 34, 45}
+var _Kind_index = [...]uint8{0, 17, 34, 45, 62}
 
 func (i Kind) String() string {
 	if i < 0 || i >= Kind(len(_Kind_index)-1) {

api/metric/meter.go

@@ -82,6 +82,24 @@ func (m Meter) NewFloat64Counter(name string, options ...Option) (Float64Counter
 		m.newSync(name, CounterKind, Float64NumberKind, options))
 }
 
+// NewInt64UpDownCounter creates a new integer UpDownCounter instrument with the
+// given name, customized with options.  May return an error if the
+// name is invalid (e.g., empty) or improperly registered (e.g.,
+// duplicate registration).
+func (m Meter) NewInt64UpDownCounter(name string, options ...Option) (Int64UpDownCounter, error) {
+	return wrapInt64UpDownCounterInstrument(
+		m.newSync(name, UpDownCounterKind, Int64NumberKind, options))
+}
+
+// NewFloat64UpDownCounter creates a new floating point UpDownCounter with the
+// given name, customized with options.  May return an error if the
+// name is invalid (e.g., empty) or improperly registered (e.g.,
+// duplicate registration).
+func (m Meter) NewFloat64UpDownCounter(name string, options ...Option) (Float64UpDownCounter, error) {
+	return wrapFloat64UpDownCounterInstrument(
+		m.newSync(name, UpDownCounterKind, Float64NumberKind, options))
+}
+
 // NewInt64ValueRecorder creates a new integer ValueRecorder instrument with the
 // given name, customized with options.  May return an error if the
 // name is invalid (e.g., empty) or improperly registered (e.g.,

api/metric/must.go

@@ -53,6 +53,26 @@ func (mm MeterMust) NewFloat64Counter(name string, cos ...Option) Float64Counter
 	}
 }
 
+// NewInt64UpDownCounter calls `Meter.NewInt64UpDownCounter` and returns the
+// instrument, panicking if it encounters an error.
+func (mm MeterMust) NewInt64UpDownCounter(name string, cos ...Option) Int64UpDownCounter {
+	if inst, err := mm.meter.NewInt64UpDownCounter(name, cos...); err != nil {
+		panic(err)
+	} else {
+		return inst
+	}
+}
+
+// NewFloat64UpDownCounter calls `Meter.NewFloat64UpDownCounter` and returns the
+// instrument, panicking if it encounters an error.
+func (mm MeterMust) NewFloat64UpDownCounter(name string, cos ...Option) Float64UpDownCounter {
+	if inst, err := mm.meter.NewFloat64UpDownCounter(name, cos...); err != nil {
+		panic(err)
+	} else {
+		return inst
+	}
+}
+
 // NewInt64ValueRecorder calls `Meter.NewInt64ValueRecorder` and returns the
 // instrument, panicking if it encounters an error.
 func (mm MeterMust) NewInt64ValueRecorder(name string, mos ...Option) Int64ValueRecorder {

api/metric/sync.go

@@ -156,37 +156,37 @@ func newMeasurement(instrument SyncImpl, number Number) Measurement {
 	}
 }
 
-// wrapInt64CounterInstrument returns an `Int64Counter` from a
-// `SyncImpl`.  An error will be generated if the
-// `SyncImpl` is nil (in which case a No-op is substituted),
-// otherwise the error passes through.
+// wrapInt64CounterInstrument converts a SyncImpl into Int64Counter.
 func wrapInt64CounterInstrument(syncInst SyncImpl, err error) (Int64Counter, error) {
 	common, err := checkNewSync(syncInst, err)
 	return Int64Counter{syncInstrument: common}, err
 }
 
-// wrapFloat64CounterInstrument returns an `Float64Counter` from a
-// `SyncImpl`.  An error will be generated if the
-// `SyncImpl` is nil (in which case a No-op is substituted),
-// otherwise the error passes through.
+// wrapFloat64CounterInstrument converts a SyncImpl into Float64Counter.
 func wrapFloat64CounterInstrument(syncInst SyncImpl, err error) (Float64Counter, error) {
 	common, err := checkNewSync(syncInst, err)
 	return Float64Counter{syncInstrument: common}, err
 }
 
-// wrapInt64ValueRecorderInstrument returns an `Int64ValueRecorder` from a
-// `SyncImpl`.  An error will be generated if the
-// `SyncImpl` is nil (in which case a No-op is substituted),
-// otherwise the error passes through.
+// wrapInt64UpDownCounterInstrument converts a SyncImpl into Int64UpDownCounter.
+func wrapInt64UpDownCounterInstrument(syncInst SyncImpl, err error) (Int64UpDownCounter, error) {
+	common, err := checkNewSync(syncInst, err)
+	return Int64UpDownCounter{syncInstrument: common}, err
+}
+
+// wrapFloat64UpDownCounterInstrument converts a SyncImpl into Float64UpDownCounter.
+func wrapFloat64UpDownCounterInstrument(syncInst SyncImpl, err error) (Float64UpDownCounter, error) {
+	common, err := checkNewSync(syncInst, err)
+	return Float64UpDownCounter{syncInstrument: common}, err
+}
+
+// wrapInt64ValueRecorderInstrument converts a SyncImpl into Int64ValueRecorder.
 func wrapInt64ValueRecorderInstrument(syncInst SyncImpl, err error) (Int64ValueRecorder, error) {
 	common, err := checkNewSync(syncInst, err)
 	return Int64ValueRecorder{syncInstrument: common}, err
 }
 
-// wrapFloat64ValueRecorderInstrument returns an `Float64ValueRecorder` from a
-// `SyncImpl`.  An error will be generated if the
-// `SyncImpl` is nil (in which case a No-op is substituted),
-// otherwise the error passes through.
+// wrapFloat64ValueRecorderInstrument converts a SyncImpl into Float64ValueRecorder.
 func wrapFloat64ValueRecorderInstrument(syncInst SyncImpl, err error) (Float64ValueRecorder, error) {
 	common, err := checkNewSync(syncInst, err)
 	return Float64ValueRecorder{syncInstrument: common}, err

api/metric/updowncounter.go

@@ -0,0 +1,96 @@
+// Copyright The OpenTelemetry 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.
+
+package metric
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/api/kv"
+)
+
+// Float64UpDownCounter is a metric instrument that sums floating
+// point values.
+type Float64UpDownCounter struct {
+	syncInstrument
+}
+
+// Int64UpDownCounter is a metric instrument that sums integer values.
+type Int64UpDownCounter struct {
+	syncInstrument
+}
+
+// BoundFloat64UpDownCounter is a bound instrument for Float64UpDownCounter.
+//
+// It inherits the Unbind function from syncBoundInstrument.
+type BoundFloat64UpDownCounter struct {
+	syncBoundInstrument
+}
+
+// BoundInt64UpDownCounter is a boundInstrument for Int64UpDownCounter.
+//
+// It inherits the Unbind function from syncBoundInstrument.
+type BoundInt64UpDownCounter struct {
+	syncBoundInstrument
+}
+
+// Bind creates a bound instrument for this counter. The labels are
+// associated with values recorded via subsequent calls to Record.
+func (c Float64UpDownCounter) Bind(labels ...kv.KeyValue) (h BoundFloat64UpDownCounter) {
+	h.syncBoundInstrument = c.bind(labels)
+	return
+}
+
+// Bind creates a bound instrument for this counter. The labels are
+// associated with values recorded via subsequent calls to Record.
+func (c Int64UpDownCounter) Bind(labels ...kv.KeyValue) (h BoundInt64UpDownCounter) {
+	h.syncBoundInstrument = c.bind(labels)
+	return
+}
+
+// Measurement creates a Measurement object to use with batch
+// recording.
+func (c Float64UpDownCounter) Measurement(value float64) Measurement {
+	return c.float64Measurement(value)
+}
+
+// Measurement creates a Measurement object to use with batch
+// recording.
+func (c Int64UpDownCounter) Measurement(value int64) Measurement {
+	return c.int64Measurement(value)
+}
+
+// Add adds the value to the counter's sum. The labels should contain
+// the keys and values to be associated with this value.
+func (c Float64UpDownCounter) Add(ctx context.Context, value float64, labels ...kv.KeyValue) {
+	c.directRecord(ctx, NewFloat64Number(value), labels)
+}
+
+// Add adds the value to the counter's sum. The labels should contain
+// the keys and values to be associated with this value.
+func (c Int64UpDownCounter) Add(ctx context.Context, value int64, labels ...kv.KeyValue) {
+	c.directRecord(ctx, NewInt64Number(value), labels)
+}
+
+// Add adds the value to the counter's sum using the labels
+// previously bound to this counter via Bind()
+func (b BoundFloat64UpDownCounter) Add(ctx context.Context, value float64) {
+	b.directRecord(ctx, NewFloat64Number(value))
+}
+
+// Add adds the value to the counter's sum using the labels
+// previously bound to this counter via Bind()
+func (b BoundInt64UpDownCounter) Add(ctx context.Context, value int64) {
+	b.directRecord(ctx, NewInt64Number(value))
+}

sdk/metric/correct_test.go

@@ -86,7 +86,7 @@ func (cb *correctnessIntegrator) Process(_ context.Context, record export.Record
 	return nil
 }
 
-func TestInputRangeTestCounter(t *testing.T) {
+func TestInputRangeCounter(t *testing.T) {
 	ctx := context.Background()
 	meter, sdk, integrator := newSDK(t)
 
@@ -114,7 +114,31 @@ func TestInputRangeTestCounter(t *testing.T) {
 	require.Nil(t, sdkErr)
 }
 
-func TestInputRangeTestValueRecorder(t *testing.T) {
+func TestInputRangeUpDownCounter(t *testing.T) {
+	ctx := context.Background()
+	meter, sdk, integrator := newSDK(t)
+
+	var sdkErr error
+	sdk.SetErrorHandler(func(handleErr error) {
+		sdkErr = handleErr
+	})
+
+	counter := Must(meter).NewInt64UpDownCounter("name.updowncounter")
+
+	counter.Add(ctx, -1)
+	counter.Add(ctx, -1)
+	counter.Add(ctx, 2)
+	counter.Add(ctx, 1)
+
+	checkpointed := sdk.Collect(ctx)
+	sum, err := integrator.records[0].Aggregator().(aggregator.Sum).Sum()
+	require.Equal(t, int64(1), sum.AsInt64())
+	require.Equal(t, 1, checkpointed)
+	require.Nil(t, err)
+	require.Nil(t, sdkErr)
+}
+
+func TestInputRangeValueRecorder(t *testing.T) {
 	ctx := context.Background()
 	meter, sdk, integrator := newSDK(t)