Rename Kind from the api/metric package (#1240)

* Update metric Kind to InstrumentKind

* Update all the other modules with Kind rename

* Update metric Descriptor with instrument Kind rename

* Update other modules with Descriptor method rename

* Update OTLP exporter test field name

* Rename kind filenames

* Add changes to CHANGELOG

* Fix documentation for Grouping and PrecomputedSum

CHANGELOG.md

@@ -18,6 +18,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Move the `go.opentelemetry.io/otel/api/trace/tracetest` package into `go.opentelemetry.io/otel/oteltest`. (#1229)
 - OTLP Exporter supports OTLP v0.5.0. (#1230)
 - The Sampler is now called on local child spans. (#1233)
+- The `Kind` type from the `go.opentelemetry.io/otel/api/metric` package was renamed to `InstrumentKind` to more specifically describe what it is and avoid semantic ambiguity. (#1240)
+- The `MetricKind` method of the `Descriptor` type in the `go.opentelemetry.io/otel/api/metric` package was renamed to `Descriptor.InstrumentKind`.
+   This matches the returned type and fixes misuse of the term metric. (#1240)
 - Move test harness from the `go.opentelemetry.io/otel/api/apitest` package into `go.opentelemetry.io/otel/oteltest`. (#1241)
 - Rename `MergeItererator` to `MergeIterator` in the `go.opentelemetry.io/otel/label` package. (#1244)
 

api/metric/api_test.go

@@ -32,7 +32,7 @@ import (
 
 var Must = metric.Must
 
-func checkSyncBatches(ctx context.Context, t *testing.T, labels []label.KeyValue, mock *mockTest.MeterImpl, nkind metric.NumberKind, mkind metric.Kind, instrument metric.InstrumentImpl, expected ...float64) {
+func checkSyncBatches(ctx context.Context, t *testing.T, labels []label.KeyValue, mock *mockTest.MeterImpl, nkind metric.NumberKind, mkind metric.InstrumentKind, instrument metric.InstrumentImpl, expected ...float64) {
 	t.Helper()
 
 	batchesCount := len(mock.MeasurementBatches)
@@ -131,7 +131,7 @@ func TestCounter(t *testing.T) {
 		boundInstrument := c.Bind(labels...)
 		boundInstrument.Add(ctx, -742)
 		meter.RecordBatch(ctx, labels, c.Measurement(42))
-		checkSyncBatches(ctx, t, labels, mockSDK, metric.Float64NumberKind, metric.CounterKind, c.SyncImpl(),
+		checkSyncBatches(ctx, t, labels, mockSDK, metric.Float64NumberKind, metric.CounterInstrumentKind, c.SyncImpl(),
 			1994.1, -742, 42,
 		)
 	})
@@ -144,7 +144,7 @@ func TestCounter(t *testing.T) {
 		boundInstrument := c.Bind(labels...)
 		boundInstrument.Add(ctx, 4200)
 		meter.RecordBatch(ctx, labels, c.Measurement(420000))
-		checkSyncBatches(ctx, t, labels, mockSDK, metric.Int64NumberKind, metric.CounterKind, c.SyncImpl(),
+		checkSyncBatches(ctx, t, labels, mockSDK, metric.Int64NumberKind, metric.CounterInstrumentKind, c.SyncImpl(),
 			42, 4200, 420000,
 		)
 
@@ -158,7 +158,7 @@ func TestCounter(t *testing.T) {
 		boundInstrument := c.Bind(labels...)
 		boundInstrument.Add(ctx, -100)
 		meter.RecordBatch(ctx, labels, c.Measurement(42))
-		checkSyncBatches(ctx, t, labels, mockSDK, metric.Int64NumberKind, metric.UpDownCounterKind, c.SyncImpl(),
+		checkSyncBatches(ctx, t, labels, mockSDK, metric.Int64NumberKind, metric.UpDownCounterInstrumentKind, c.SyncImpl(),
 			100, -100, 42,
 		)
 	})
@@ -171,7 +171,7 @@ func TestCounter(t *testing.T) {
 		boundInstrument := c.Bind(labels...)
 		boundInstrument.Add(ctx, -76)
 		meter.RecordBatch(ctx, labels, c.Measurement(-100.1))
-		checkSyncBatches(ctx, t, labels, mockSDK, metric.Float64NumberKind, metric.UpDownCounterKind, c.SyncImpl(),
+		checkSyncBatches(ctx, t, labels, mockSDK, metric.Float64NumberKind, metric.UpDownCounterInstrumentKind, c.SyncImpl(),
 			100.1, -76, -100.1,
 		)
 	})
@@ -187,7 +187,7 @@ func TestValueRecorder(t *testing.T) {
 		boundInstrument := m.Bind(labels...)
 		boundInstrument.Record(ctx, 0)
 		meter.RecordBatch(ctx, labels, m.Measurement(-100.5))
-		checkSyncBatches(ctx, t, labels, mockSDK, metric.Float64NumberKind, metric.ValueRecorderKind, m.SyncImpl(),
+		checkSyncBatches(ctx, t, labels, mockSDK, metric.Float64NumberKind, metric.ValueRecorderInstrumentKind, m.SyncImpl(),
 			42, 0, -100.5,
 		)
 	})
@@ -200,7 +200,7 @@ func TestValueRecorder(t *testing.T) {
 		boundInstrument := m.Bind(labels...)
 		boundInstrument.Record(ctx, 80)
 		meter.RecordBatch(ctx, labels, m.Measurement(0))
-		checkSyncBatches(ctx, t, labels, mockSDK, metric.Int64NumberKind, metric.ValueRecorderKind, m.SyncImpl(),
+		checkSyncBatches(ctx, t, labels, mockSDK, metric.Int64NumberKind, metric.ValueRecorderInstrumentKind, m.SyncImpl(),
 			173, 80, 0,
 		)
 	})
@@ -214,7 +214,7 @@ func TestObserverInstruments(t *testing.T) {
 			result.Observe(42.1, labels...)
 		})
 		mockSDK.RunAsyncInstruments()
-		checkObserverBatch(t, labels, mockSDK, metric.Float64NumberKind, metric.ValueObserverKind, o.AsyncImpl(),
+		checkObserverBatch(t, labels, mockSDK, metric.Float64NumberKind, metric.ValueObserverInstrumentKind, o.AsyncImpl(),
 			42.1,
 		)
 	})
@@ -225,7 +225,7 @@ func TestObserverInstruments(t *testing.T) {
 			result.Observe(-142, labels...)
 		})
 		mockSDK.RunAsyncInstruments()
-		checkObserverBatch(t, labels, mockSDK, metric.Int64NumberKind, metric.ValueObserverKind, o.AsyncImpl(),
+		checkObserverBatch(t, labels, mockSDK, metric.Int64NumberKind, metric.ValueObserverInstrumentKind, o.AsyncImpl(),
 			-142,
 		)
 	})
@@ -236,7 +236,7 @@ func TestObserverInstruments(t *testing.T) {
 			result.Observe(42.1, labels...)
 		})
 		mockSDK.RunAsyncInstruments()
-		checkObserverBatch(t, labels, mockSDK, metric.Float64NumberKind, metric.SumObserverKind, o.AsyncImpl(),
+		checkObserverBatch(t, labels, mockSDK, metric.Float64NumberKind, metric.SumObserverInstrumentKind, o.AsyncImpl(),
 			42.1,
 		)
 	})
@@ -247,7 +247,7 @@ func TestObserverInstruments(t *testing.T) {
 			result.Observe(-142, labels...)
 		})
 		mockSDK.RunAsyncInstruments()
-		checkObserverBatch(t, labels, mockSDK, metric.Int64NumberKind, metric.SumObserverKind, o.AsyncImpl(),
+		checkObserverBatch(t, labels, mockSDK, metric.Int64NumberKind, metric.SumObserverInstrumentKind, o.AsyncImpl(),
 			-142,
 		)
 	})
@@ -258,7 +258,7 @@ func TestObserverInstruments(t *testing.T) {
 			result.Observe(42.1, labels...)
 		})
 		mockSDK.RunAsyncInstruments()
-		checkObserverBatch(t, labels, mockSDK, metric.Float64NumberKind, metric.UpDownSumObserverKind, o.AsyncImpl(),
+		checkObserverBatch(t, labels, mockSDK, metric.Float64NumberKind, metric.UpDownSumObserverInstrumentKind, o.AsyncImpl(),
 			42.1,
 		)
 	})
@@ -269,7 +269,7 @@ func TestObserverInstruments(t *testing.T) {
 			result.Observe(-142, labels...)
 		})
 		mockSDK.RunAsyncInstruments()
-		checkObserverBatch(t, labels, mockSDK, metric.Int64NumberKind, metric.UpDownSumObserverKind, o.AsyncImpl(),
+		checkObserverBatch(t, labels, mockSDK, metric.Int64NumberKind, metric.UpDownSumObserverInstrumentKind, o.AsyncImpl(),
 			-142,
 		)
 	})
@@ -320,7 +320,7 @@ func TestBatchObserverInstruments(t *testing.T) {
 	require.Equal(t, 0, m2.Number.CompareNumber(metric.Float64NumberKind, mockTest.ResolveNumberByKind(t, metric.Float64NumberKind, 42)))
 }
 
-func checkObserverBatch(t *testing.T, labels []label.KeyValue, mock *mockTest.MeterImpl, nkind metric.NumberKind, mkind metric.Kind, observer metric.AsyncImpl, expected float64) {
+func checkObserverBatch(t *testing.T, labels []label.KeyValue, mock *mockTest.MeterImpl, nkind metric.NumberKind, mkind metric.InstrumentKind, observer metric.AsyncImpl, expected float64) {
 	t.Helper()
 	assert.Len(t, mock.MeasurementBatches, 1)
 	if len(mock.MeasurementBatches) < 1 {
@@ -337,7 +337,7 @@ func checkObserverBatch(t *testing.T, labels []label.KeyValue, mock *mockTest.Me
 		return
 	}
 	measurement := got.Measurements[0]
-	require.Equal(t, mkind, measurement.Instrument.Descriptor().MetricKind())
+	require.Equal(t, mkind, measurement.Instrument.Descriptor().InstrumentKind())
 	assert.Equal(t, o, measurement.Instrument.Implementation().(*mockTest.Async))
 	ft := mockTest.ResolveNumberByKind(t, nkind, expected)
 	assert.Equal(t, 0, measurement.Number.CompareNumber(nkind, ft))

api/metric/descriptor.go

@@ -20,19 +20,19 @@ import "go.opentelemetry.io/otel/unit"
 // including its name, metric kind, number kind, and the configurable
 // options.
 type Descriptor struct {
-	name       string
-	kind       Kind
-	numberKind NumberKind
-	config     InstrumentConfig
+	name           string
+	instrumentKind InstrumentKind
+	numberKind     NumberKind
+	config         InstrumentConfig
 }
 
 // NewDescriptor returns a Descriptor with the given contents.
-func NewDescriptor(name string, mkind Kind, nkind NumberKind, opts ...InstrumentOption) Descriptor {
+func NewDescriptor(name string, ikind InstrumentKind, nkind NumberKind, opts ...InstrumentOption) Descriptor {
 	return Descriptor{
-		name:       name,
-		kind:       mkind,
-		numberKind: nkind,
-		config:     NewInstrumentConfig(opts...),
+		name:           name,
+		instrumentKind: ikind,
+		numberKind:     nkind,
+		config:         NewInstrumentConfig(opts...),
 	}
 }
 
@@ -41,9 +41,9 @@ func (d Descriptor) Name() string {
 	return d.name
 }
 
-// MetricKind returns the specific kind of instrument.
-func (d Descriptor) MetricKind() Kind {
-	return d.kind
+// InstrumentKind returns the specific kind of instrument.
+func (d Descriptor) InstrumentKind() InstrumentKind {
+	return d.instrumentKind
 }
 
 // Description provides a human-readable description of the metric

api/metric/instrumentkind.go

@@ -0,0 +1,80 @@
+// 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.
+
+//go:generate stringer -type=InstrumentKind
+
+package metric
+
+// InstrumentKind describes the kind of instrument.
+type InstrumentKind int8
+
+const (
+	// ValueRecorderInstrumentKind indicates a ValueRecorder instrument.
+	ValueRecorderInstrumentKind InstrumentKind = iota
+	// ValueObserverInstrumentKind indicates an ValueObserver instrument.
+	ValueObserverInstrumentKind
+
+	// CounterInstrumentKind indicates a Counter instrument.
+	CounterInstrumentKind
+	// UpDownCounterInstrumentKind indicates a UpDownCounter instrument.
+	UpDownCounterInstrumentKind
+
+	// SumObserverInstrumentKind indicates a SumObserver instrument.
+	SumObserverInstrumentKind
+	// UpDownSumObserverInstrumentKind indicates a UpDownSumObserver
+	// instrument.
+	UpDownSumObserverInstrumentKind
+)
+
+// Synchronous returns whether this is a synchronous kind of instrument.
+func (k InstrumentKind) Synchronous() bool {
+	switch k {
+	case CounterInstrumentKind, UpDownCounterInstrumentKind, ValueRecorderInstrumentKind:
+		return true
+	}
+	return false
+}
+
+// Asynchronous returns whether this is an asynchronous kind of instrument.
+func (k InstrumentKind) Asynchronous() bool {
+	return !k.Synchronous()
+}
+
+// Adding returns whether this kind of instrument adds its inputs (as opposed to Grouping).
+func (k InstrumentKind) Adding() bool {
+	switch k {
+	case CounterInstrumentKind, UpDownCounterInstrumentKind, SumObserverInstrumentKind, UpDownSumObserverInstrumentKind:
+		return true
+	}
+	return false
+}
+
+// Grouping returns whether this kind of instrument groups its inputs (as opposed to Adding).
+func (k InstrumentKind) Grouping() bool {
+	return !k.Adding()
+}
+
+// Monotonic returns whether this kind of instrument exposes a non-decreasing sum.
+func (k InstrumentKind) Monotonic() bool {
+	switch k {
+	case CounterInstrumentKind, SumObserverInstrumentKind:
+		return true
+	}
+	return false
+}
+
+// PrecomputedSum returns whether this kind of instrument receives precomputed sums.
+func (k InstrumentKind) PrecomputedSum() bool {
+	return k.Adding() && k.Asynchronous()
+}

api/metric/kind_test.go → api/metric/instrumentkind_test.go

@@ -23,49 +23,49 @@ import (
 )
 
 var (
-	syncKinds = []metric.Kind{
-		metric.ValueRecorderKind,
-		metric.CounterKind,
-		metric.UpDownCounterKind,
-	}
-	asyncKinds = []metric.Kind{
-		metric.ValueObserverKind,
-		metric.SumObserverKind,
-		metric.UpDownSumObserverKind,
-	}
-	addingKinds = []metric.Kind{
-		metric.CounterKind,
-		metric.UpDownCounterKind,
-		metric.SumObserverKind,
-		metric.UpDownSumObserverKind,
-	}
-	groupingKinds = []metric.Kind{
-		metric.ValueRecorderKind,
-		metric.ValueObserverKind,
+	syncKinds = []metric.InstrumentKind{
+		metric.ValueRecorderInstrumentKind,
+		metric.CounterInstrumentKind,
+		metric.UpDownCounterInstrumentKind,
+	}
+	asyncKinds = []metric.InstrumentKind{
+		metric.ValueObserverInstrumentKind,
+		metric.SumObserverInstrumentKind,
+		metric.UpDownSumObserverInstrumentKind,
+	}
+	addingKinds = []metric.InstrumentKind{
+		metric.CounterInstrumentKind,
+		metric.UpDownCounterInstrumentKind,
+		metric.SumObserverInstrumentKind,
+		metric.UpDownSumObserverInstrumentKind,
+	}
+	groupingKinds = []metric.InstrumentKind{
+		metric.ValueRecorderInstrumentKind,
+		metric.ValueObserverInstrumentKind,
 	}
 
-	monotonicKinds = []metric.Kind{
-		metric.CounterKind,
-		metric.SumObserverKind,
+	monotonicKinds = []metric.InstrumentKind{
+		metric.CounterInstrumentKind,
+		metric.SumObserverInstrumentKind,
 	}
 
-	nonMonotonicKinds = []metric.Kind{
-		metric.UpDownCounterKind,
-		metric.UpDownSumObserverKind,
-		metric.ValueRecorderKind,
-		metric.ValueObserverKind,
+	nonMonotonicKinds = []metric.InstrumentKind{
+		metric.UpDownCounterInstrumentKind,
+		metric.UpDownSumObserverInstrumentKind,
+		metric.ValueRecorderInstrumentKind,
+		metric.ValueObserverInstrumentKind,
 	}
 
-	precomputedSumKinds = []metric.Kind{
-		metric.SumObserverKind,
-		metric.UpDownSumObserverKind,
+	precomputedSumKinds = []metric.InstrumentKind{
+		metric.SumObserverInstrumentKind,
+		metric.UpDownSumObserverInstrumentKind,
 	}
 
-	nonPrecomputedSumKinds = []metric.Kind{
-		metric.CounterKind,
-		metric.UpDownCounterKind,
-		metric.ValueRecorderKind,
-		metric.ValueObserverKind,
+	nonPrecomputedSumKinds = []metric.InstrumentKind{
+		metric.CounterInstrumentKind,
+		metric.UpDownCounterInstrumentKind,
+		metric.ValueRecorderInstrumentKind,
+		metric.ValueObserverInstrumentKind,
 	}
 )