Rename metric instruments to match feature-freeze API specification

CHANGELOG.md

@@ -17,6 +17,12 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
+- Metric instruments have been renamed to match the (stable) metric API speciication:
+  - ValueRecorder becomes Histogram
+  - ValueObserver becomes Gauge
+  - SumObserver becomes CounterObserver
+  - UpDownSumObserver becomes UpDownCounterObserver
+  The API is still considered experimental. (#2202)
 - Metric SDK/API implementation type `InstrumentKind` moves into `sdkapi` sub-package. (#2091)
 - The Metrics SDK export record no longer contains a Resource pointer, the SDK `"go.opentelemetry.io/otel/sdk/trace/export/metric".Exporter.Export()` function for push-based exporters now takes a single Resource argument, pull-based exporters use `"go.opentelemetry.io/otel/sdk/metric/controller/basic".Controller.Resource()`. (#2120)
 - The JSON output of the `go.opentelemetry.io/otel/exporters/stdout/stdouttrace` is harmonized now such that the output is "plain" JSON objects after each other of the form `{ ... } { ... } { ... }`. Earlier the JSON objects describing a span were wrapped in a slice for each `Exporter.ExportSpans` call, like `[ { ... } ][ { ... } { ... } ]`. Outputting JSON object directly after each other is consistent with JSON loggers, and a bit easier to parse and read. (#2196)

bridge/opencensus/exporter.go

@@ -142,16 +142,16 @@ func convertDescriptor(ocDescriptor metricdata.Descriptor) (metric.Descriptor, e
 	switch ocDescriptor.Type {
 	case metricdata.TypeGaugeInt64:
 		nkind = number.Int64Kind
-		ikind = sdkapi.ValueObserverInstrumentKind
+		ikind = sdkapi.GaugeObserverInstrumentKind
 	case metricdata.TypeGaugeFloat64:
 		nkind = number.Float64Kind
-		ikind = sdkapi.ValueObserverInstrumentKind
+		ikind = sdkapi.GaugeObserverInstrumentKind
 	case metricdata.TypeCumulativeInt64:
 		nkind = number.Int64Kind
-		ikind = sdkapi.SumObserverInstrumentKind
+		ikind = sdkapi.CounterObserverInstrumentKind
 	case metricdata.TypeCumulativeFloat64:
 		nkind = number.Float64Kind
-		ikind = sdkapi.SumObserverInstrumentKind
+		ikind = sdkapi.CounterObserverInstrumentKind
 	default:
 		// Includes TypeGaugeDistribution, TypeCumulativeDistribution, TypeSummary
 		return metric.Descriptor{}, fmt.Errorf("%w; descriptor type: %v", errConversion, ocDescriptor.Type)

bridge/opencensus/exporter_test.go

@@ -73,7 +73,7 @@ func TestExportMetrics(t *testing.T) {
 	now := time.Now()
 	basicDesc := metric.NewDescriptor(
 		"",
-		sdkapi.ValueObserverInstrumentKind,
+		sdkapi.GaugeObserverInstrumentKind,
 		number.Int64Kind,
 		metric.WithInstrumentationName("OpenCensus Bridge"),
 	)
@@ -395,7 +395,7 @@ func TestConvertDescriptor(t *testing.T) {
 			desc: "empty descriptor",
 			expected: metric.NewDescriptor(
 				"",
-				sdkapi.ValueObserverInstrumentKind,
+				sdkapi.GaugeObserverInstrumentKind,
 				number.Int64Kind,
 				metric.WithInstrumentationName("OpenCensus Bridge"),
 			),
@@ -410,7 +410,7 @@ func TestConvertDescriptor(t *testing.T) {
 			},
 			expected: metric.NewDescriptor(
 				"foo",
-				sdkapi.ValueObserverInstrumentKind,
+				sdkapi.GaugeObserverInstrumentKind,
 				number.Int64Kind,
 				metric.WithInstrumentationName("OpenCensus Bridge"),
 				metric.WithDescription("bar"),
@@ -427,7 +427,7 @@ func TestConvertDescriptor(t *testing.T) {
 			},
 			expected: metric.NewDescriptor(
 				"foo",
-				sdkapi.ValueObserverInstrumentKind,
+				sdkapi.GaugeObserverInstrumentKind,
 				number.Float64Kind,
 				metric.WithInstrumentationName("OpenCensus Bridge"),
 				metric.WithDescription("bar"),
@@ -444,7 +444,7 @@ func TestConvertDescriptor(t *testing.T) {
 			},
 			expected: metric.NewDescriptor(
 				"foo",
-				sdkapi.SumObserverInstrumentKind,
+				sdkapi.CounterObserverInstrumentKind,
 				number.Int64Kind,
 				metric.WithInstrumentationName("OpenCensus Bridge"),
 				metric.WithDescription("bar"),
@@ -461,7 +461,7 @@ func TestConvertDescriptor(t *testing.T) {
 			},
 			expected: metric.NewDescriptor(
 				"foo",
-				sdkapi.SumObserverInstrumentKind,
+				sdkapi.CounterObserverInstrumentKind,
 				number.Float64Kind,
 				metric.WithInstrumentationName("OpenCensus Bridge"),
 				metric.WithDescription("bar"),

example/prometheus/main.go

@@ -76,11 +76,11 @@ func main() {
 		(*observerLock).RUnlock()
 		result.Observe(value, labels...)
 	}
-	_ = metric.Must(meter).NewFloat64ValueObserver("ex.com.one", cb,
-		metric.WithDescription("A ValueObserver set to 1.0"),
+	_ = metric.Must(meter).NewFloat64GaugeObserver("ex.com.one", cb,
+		metric.WithDescription("A GaugeObserver set to 1.0"),
 	)
 
-	valuerecorder := metric.Must(meter).NewFloat64ValueRecorder("ex.com.two")
+	valuerecorder := metric.Must(meter).NewFloat64Histogram("ex.com.two")
 	counter := metric.Must(meter).NewFloat64Counter("ex.com.three")
 
 	commonLabels := []attribute.KeyValue{lemonsKey.Int(10), attribute.String("A", "1"), attribute.String("B", "2"), attribute.String("C", "3")}

exporters/otlp/otlpmetric/exporter_test.go

@@ -215,7 +215,7 @@ func TestNoGroupingExport(t *testing.T) {
 func TestValuerecorderMetricGroupingExport(t *testing.T) {
 	r := record{
 		"valuerecorder",
-		sdkapi.ValueRecorderInstrumentKind,
+		sdkapi.HistogramInstrumentKind,
 		number.Int64Kind,
 		nil,
 		append(baseKeyValues, cpuKey.Int(1)),
@@ -606,8 +606,8 @@ func TestStatelessExportKind(t *testing.T) {
 	for _, k := range []testcase{
 		{"counter", sdkapi.CounterInstrumentKind, metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA, true},
 		{"updowncounter", sdkapi.UpDownCounterInstrumentKind, metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_DELTA, false},
-		{"sumobserver", sdkapi.SumObserverInstrumentKind, metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE, true},
-		{"updownsumobserver", sdkapi.UpDownSumObserverInstrumentKind, metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE, false},
+		{"sumobserver", sdkapi.CounterObserverInstrumentKind, metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE, true},
+		{"updownsumobserver", sdkapi.UpDownCounterObserverInstrumentKind, metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE, false},
 	} {
 		t.Run(k.name, func(t *testing.T) {
 			runMetricExportTests(

exporters/otlp/otlpmetric/internal/metrictransform/metric_test.go

@@ -122,7 +122,7 @@ func TestMinMaxSumCountValue(t *testing.T) {
 }
 
 func TestMinMaxSumCountDatapoints(t *testing.T) {
-	desc := metric.NewDescriptor("", sdkapi.ValueRecorderInstrumentKind, number.Int64Kind)
+	desc := metric.NewDescriptor("", sdkapi.HistogramInstrumentKind, number.Int64Kind)
 	labels := attribute.NewSet(attribute.String("one", "1"))
 	mmscs := minmaxsumcount.New(2, &metric.Descriptor{})
 	mmsc, ckpt := &mmscs[0], &mmscs[1]
@@ -178,7 +178,7 @@ func TestMinMaxSumCountPropagatesErrors(t *testing.T) {
 }
 
 func TestSumIntDataPoints(t *testing.T) {
-	desc := metric.NewDescriptor("", sdkapi.ValueRecorderInstrumentKind, number.Int64Kind)
+	desc := metric.NewDescriptor("", sdkapi.HistogramInstrumentKind, number.Int64Kind)
 	labels := attribute.NewSet(attribute.String("one", "1"))
 	sums := sumAgg.New(2)
 	s, ckpt := &sums[0], &sums[1]
@@ -218,7 +218,7 @@ func TestSumIntDataPoints(t *testing.T) {
 }
 
 func TestSumFloatDataPoints(t *testing.T) {
-	desc := metric.NewDescriptor("", sdkapi.ValueRecorderInstrumentKind, number.Float64Kind)
+	desc := metric.NewDescriptor("", sdkapi.HistogramInstrumentKind, number.Float64Kind)
 	labels := attribute.NewSet(attribute.String("one", "1"))
 	sums := sumAgg.New(2)
 	s, ckpt := &sums[0], &sums[1]
@@ -256,7 +256,7 @@ func TestSumFloatDataPoints(t *testing.T) {
 }
 
 func TestLastValueIntDataPoints(t *testing.T) {
-	desc := metric.NewDescriptor("", sdkapi.ValueRecorderInstrumentKind, number.Int64Kind)
+	desc := metric.NewDescriptor("", sdkapi.HistogramInstrumentKind, number.Int64Kind)
 	labels := attribute.NewSet(attribute.String("one", "1"))
 	lvs := lvAgg.New(2)
 	lv, ckpt := &lvs[0], &lvs[1]
@@ -291,7 +291,7 @@ func TestLastValueIntDataPoints(t *testing.T) {
 }
 
 func TestExactIntDataPoints(t *testing.T) {
-	desc := metric.NewDescriptor("", sdkapi.ValueRecorderInstrumentKind, number.Int64Kind)
+	desc := metric.NewDescriptor("", sdkapi.HistogramInstrumentKind, number.Int64Kind)
 	labels := attribute.NewSet(attribute.String("one", "1"))
 	arrs := arrAgg.New(2)
 	e, ckpt := &arrs[0], &arrs[1]
@@ -326,7 +326,7 @@ func TestExactIntDataPoints(t *testing.T) {
 }
 
 func TestExactFloatDataPoints(t *testing.T) {
-	desc := metric.NewDescriptor("", sdkapi.ValueRecorderInstrumentKind, number.Float64Kind)
+	desc := metric.NewDescriptor("", sdkapi.HistogramInstrumentKind, number.Float64Kind)
 	labels := attribute.NewSet(attribute.String("one", "1"))
 	arrs := arrAgg.New(2)
 	e, ckpt := &arrs[0], &arrs[1]
@@ -360,7 +360,7 @@ func TestExactFloatDataPoints(t *testing.T) {
 }
 
 func TestSumErrUnknownValueType(t *testing.T) {
-	desc := metric.NewDescriptor("", sdkapi.ValueRecorderInstrumentKind, number.Kind(-1))
+	desc := metric.NewDescriptor("", sdkapi.HistogramInstrumentKind, number.Kind(-1))
 	labels := attribute.NewSet()
 	s := &sumAgg.New(1)[0]
 	record := export.NewRecord(&desc, &labels, s, intervalStart, intervalEnd)

exporters/otlp/otlpmetric/internal/otlpmetrictest/otlptest.go

@@ -55,10 +55,10 @@ func RunEndToEndTest(ctx context.Context, t *testing.T, exp *otlpmetric.Exporter
 	instruments := map[string]data{
 		"test-int64-counter":         {sdkapi.CounterInstrumentKind, number.Int64Kind, 1},
 		"test-float64-counter":       {sdkapi.CounterInstrumentKind, number.Float64Kind, 1},
-		"test-int64-valuerecorder":   {sdkapi.ValueRecorderInstrumentKind, number.Int64Kind, 2},
-		"test-float64-valuerecorder": {sdkapi.ValueRecorderInstrumentKind, number.Float64Kind, 2},
-		"test-int64-valueobserver":   {sdkapi.ValueObserverInstrumentKind, number.Int64Kind, 3},
-		"test-float64-valueobserver": {sdkapi.ValueObserverInstrumentKind, number.Float64Kind, 3},
+		"test-int64-valuerecorder":   {sdkapi.HistogramInstrumentKind, number.Int64Kind, 2},
+		"test-float64-valuerecorder": {sdkapi.HistogramInstrumentKind, number.Float64Kind, 2},
+		"test-int64-valueobserver":   {sdkapi.GaugeObserverInstrumentKind, number.Int64Kind, 3},
+		"test-float64-valueobserver": {sdkapi.GaugeObserverInstrumentKind, number.Float64Kind, 3},
 	}
 	for name, data := range instruments {
 		data := data
@@ -72,19 +72,19 @@ func RunEndToEndTest(ctx context.Context, t *testing.T, exp *otlpmetric.Exporter
 			default:
 				assert.Failf(t, "unsupported number testing kind", data.nKind.String())
 			}
-		case sdkapi.ValueRecorderInstrumentKind:
+		case sdkapi.HistogramInstrumentKind:
 			switch data.nKind {
 			case number.Int64Kind:
-				metric.Must(meter).NewInt64ValueRecorder(name).Record(ctx, data.val, labels...)
+				metric.Must(meter).NewInt64Histogram(name).Record(ctx, data.val, labels...)
 			case number.Float64Kind:
-				metric.Must(meter).NewFloat64ValueRecorder(name).Record(ctx, float64(data.val), labels...)
+				metric.Must(meter).NewFloat64Histogram(name).Record(ctx, float64(data.val), labels...)
 			default:
 				assert.Failf(t, "unsupported number testing kind", data.nKind.String())
 			}
-		case sdkapi.ValueObserverInstrumentKind:
+		case sdkapi.GaugeObserverInstrumentKind:
 			switch data.nKind {
 			case number.Int64Kind:
-				metric.Must(meter).NewInt64ValueObserver(name,
+				metric.Must(meter).NewInt64GaugeObserver(name,
 					func(_ context.Context, result metric.Int64ObserverResult) {
 						result.Observe(data.val, labels...)
 					},
@@ -93,7 +93,7 @@ func RunEndToEndTest(ctx context.Context, t *testing.T, exp *otlpmetric.Exporter
 				callback := func(v float64) metric.Float64ObserverFunc {
 					return metric.Float64ObserverFunc(func(_ context.Context, result metric.Float64ObserverResult) { result.Observe(v, labels...) })
 				}(float64(data.val))
-				metric.Must(meter).NewFloat64ValueObserver(name, callback)
+				metric.Must(meter).NewFloat64GaugeObserver(name, callback)
 			default:
 				assert.Failf(t, "unsupported number testing kind", data.nKind.String())
 			}
@@ -131,13 +131,13 @@ func RunEndToEndTest(ctx context.Context, t *testing.T, exp *otlpmetric.Exporter
 		seen[m.Name] = struct{}{}
 
 		switch data.iKind {
-		case sdkapi.CounterInstrumentKind, sdkapi.ValueObserverInstrumentKind:
+		case sdkapi.CounterInstrumentKind, sdkapi.GaugeObserverInstrumentKind:
 			var dp []*metricpb.NumberDataPoint
 			switch data.iKind {
 			case sdkapi.CounterInstrumentKind:
 				require.NotNil(t, m.GetSum())
 				dp = m.GetSum().GetDataPoints()
-			case sdkapi.ValueObserverInstrumentKind:
+			case sdkapi.GaugeObserverInstrumentKind:
 				require.NotNil(t, m.GetGauge())
 				dp = m.GetGauge().GetDataPoints()
 			}
@@ -151,7 +151,7 @@ func RunEndToEndTest(ctx context.Context, t *testing.T, exp *otlpmetric.Exporter
 					assert.Equal(t, v, dp[0].Value, "invalid value for %q", m.Name)
 				}
 			}
-		case sdkapi.ValueRecorderInstrumentKind:
+		case sdkapi.HistogramInstrumentKind:
 			require.NotNil(t, m.GetSummary())
 			if dp := m.GetSummary().DataPoints; assert.Len(t, dp, 1) {
 				count := dp[0].Count

exporters/prometheus/prometheus_test.go

@@ -109,7 +109,7 @@ func TestPrometheusExporter(t *testing.T) {
 	meter := exporter.MeterProvider().Meter("test")
 	upDownCounter := metric.Must(meter).NewFloat64UpDownCounter("updowncounter")
 	counter := metric.Must(meter).NewFloat64Counter("counter")
-	valuerecorder := metric.Must(meter).NewFloat64ValueRecorder("valuerecorder")
+	valuerecorder := metric.Must(meter).NewFloat64Histogram("valuerecorder")
 
 	labels := []attribute.KeyValue{
 		attribute.Key("A").String("B"),
@@ -124,7 +124,7 @@ func TestPrometheusExporter(t *testing.T) {
 
 	expected = append(expected, expectCounter("counter", `counter{A="B",C="D",R="V"} 15.3`))
 
-	_ = metric.Must(meter).NewInt64ValueObserver("intobserver", func(_ context.Context, result metric.Int64ObserverResult) {
+	_ = metric.Must(meter).NewInt64GaugeObserver("intobserver", func(_ context.Context, result metric.Int64ObserverResult) {
 		result.Observe(1, labels...)
 	})
 

exporters/stdout/stdoutmetric/example_test.go

@@ -40,7 +40,7 @@ var (
 	)
 
 	loopCounter = metric.Must(meter).NewInt64Counter("function.loops")
-	paramValue  = metric.Must(meter).NewInt64ValueRecorder("function.param")
+	paramValue  = metric.Must(meter).NewInt64Histogram("function.param")
 
 	nameKey = attribute.Key("function.name")
 )

exporters/stdout/stdoutmetric/metric_test.go

@@ -169,10 +169,10 @@ func TestStdoutMinMaxSumCount(t *testing.T) {
 	require.Equal(t, `[{"Name":"name.minmaxsumcount{R=V,instrumentation.name=test,A=B,C=D}","Min":123.456,"Max":876.543,"Sum":999.999,"Count":2}]`, fix.Output())
 }
 
-func TestStdoutValueRecorderFormat(t *testing.T) {
+func TestStdoutHistogramFormat(t *testing.T) {
 	fix := newFixture(t, stdoutmetric.WithPrettyPrint())
 
-	inst := metric.Must(fix.meter).NewFloat64ValueRecorder("name.histogram")
+	inst := metric.Must(fix.meter).NewFloat64Histogram("name.histogram")
 
 	for i := 0; i < 1000; i++ {
 		inst.Record(fix.ctx, float64(i)+0.5, attribute.String("A", "B"), attribute.String("C", "D"))

internal/metric/global/meter_test.go

@@ -48,21 +48,21 @@ func TestDirect(t *testing.T) {
 	counter.Add(ctx, 1, labels1...)
 	counter.Add(ctx, 1, labels1...)
 
-	valuerecorder := Must(meter1).NewFloat64ValueRecorder("test.valuerecorder")
+	valuerecorder := Must(meter1).NewFloat64Histogram("test.valuerecorder")
 	valuerecorder.Record(ctx, 1, labels1...)
 	valuerecorder.Record(ctx, 2, labels1...)
 
-	_ = Must(meter1).NewFloat64ValueObserver("test.valueobserver.float", func(_ context.Context, result metric.Float64ObserverResult) {
+	_ = Must(meter1).NewFloat64GaugeObserver("test.valueobserver.float", func(_ context.Context, result metric.Float64ObserverResult) {
 		result.Observe(1., labels1...)
 		result.Observe(2., labels2...)
 	})
 
-	_ = Must(meter1).NewInt64ValueObserver("test.valueobserver.int", func(_ context.Context, result metric.Int64ObserverResult) {
+	_ = Must(meter1).NewInt64GaugeObserver("test.valueobserver.int", func(_ context.Context, result metric.Int64ObserverResult) {
 		result.Observe(1, labels1...)
 		result.Observe(2, labels2...)
 	})
 
-	second := Must(meter2).NewFloat64ValueRecorder("test.second")
+	second := Must(meter2).NewFloat64Histogram("test.second")
 	second.Record(ctx, 1, labels3...)
 	second.Record(ctx, 2, labels3...)
 
@@ -146,7 +146,7 @@ func TestBound(t *testing.T) {
 	boundC.Add(ctx, 1)
 	boundC.Add(ctx, 1)
 
-	valuerecorder := Must(glob).NewInt64ValueRecorder("test.valuerecorder")
+	valuerecorder := Must(glob).NewInt64Histogram("test.valuerecorder")
 	boundM := valuerecorder.Bind(labels1...)
 	boundM.Record(ctx, 1)
 	boundM.Record(ctx, 2)
@@ -188,7 +188,7 @@ func TestUnbind(t *testing.T) {
 	counter := Must(glob).NewFloat64Counter("test.counter")
 	boundC := counter.Bind(labels1...)
 
-	valuerecorder := Must(glob).NewInt64ValueRecorder("test.valuerecorder")
+	valuerecorder := Must(glob).NewInt64Histogram("test.valuerecorder")
 	boundM := valuerecorder.Bind(labels1...)
 
 	boundC.Unbind()
@@ -268,7 +268,7 @@ func TestImplementationIndirection(t *testing.T) {
 	require.False(t, ok)
 
 	// Async: no SDK yet
-	valueobserver := Must(meter1).NewFloat64ValueObserver(
+	valueobserver := Must(meter1).NewFloat64GaugeObserver(
 		"interface.valueobserver",
 		func(_ context.Context, result metric.Float64ObserverResult) {},
 	)

internal/metric/global/registry_test.go

@@ -38,16 +38,16 @@ var (
 			return unwrap(MeterProvider().Meter(libraryName).NewFloat64Counter(name))
 		},
 		"valuerecorder.int64": func(name, libraryName string) (metric.InstrumentImpl, error) {
-			return unwrap(MeterProvider().Meter(libraryName).NewInt64ValueRecorder(name))
+			return unwrap(MeterProvider().Meter(libraryName).NewInt64Histogram(name))
 		},
 		"valuerecorder.float64": func(name, libraryName string) (metric.InstrumentImpl, error) {
-			return unwrap(MeterProvider().Meter(libraryName).NewFloat64ValueRecorder(name))
+			return unwrap(MeterProvider().Meter(libraryName).NewFloat64Histogram(name))
 		},
 		"valueobserver.int64": func(name, libraryName string) (metric.InstrumentImpl, error) {
-			return unwrap(MeterProvider().Meter(libraryName).NewInt64ValueObserver(name, func(context.Context, metric.Int64ObserverResult) {}))
+			return unwrap(MeterProvider().Meter(libraryName).NewInt64GaugeObserver(name, func(context.Context, metric.Int64ObserverResult) {}))
 		},
 		"valueobserver.float64": func(name, libraryName string) (metric.InstrumentImpl, error) {
-			return unwrap(MeterProvider().Meter(libraryName).NewFloat64ValueObserver(name, func(context.Context, metric.Float64ObserverResult) {}))
+			return unwrap(MeterProvider().Meter(libraryName).NewFloat64GaugeObserver(name, func(context.Context, metric.Float64ObserverResult) {}))
 		},
 	}
 )

metric/doc.go

@@ -41,13 +41,13 @@ The synchronous instrument names are:
 
   Counter:           additive, monotonic
   UpDownCounter:     additive
-  ValueRecorder:     grouping
+  Histogram:     grouping
 
 and the asynchronous instruments are:
 
-  SumObserver:       additive, monotonic
-  UpDownSumObserver: additive
-  ValueObserver:     grouping
+  CounterObserver:       additive, monotonic
+  UpDownCounterObserver: additive
+  GaugeObserver:     grouping
 
 All instruments are provided with support for either float64 or int64 input
 values.