Rename metric instruments to match feature-freeze API specification (#2202)

* s/ValueRecorder/Histogram/g

* s/ValueObserver/GaugeObserver/g

* s/UpDownSumObserver/UpDownCounterObserver/g

* s/SumObserver/CounterObserver/g

* changelog

* pr num

* unstable->experimental

* Apply suggestions from code review

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

* Apply suggestions from code review

* apply feedback from @evantorrie by hand

* Apply suggestions from code review

Thanks

Co-authored-by: ET <evantorrie@users.noreply.github.com>

* Update sdk/export/metric/metric.go

* Apply suggestions from code review

Thank you @evantorrie !

Co-authored-by: ET <evantorrie@users.noreply.github.com>

* revert getting-started fix let tyler's update remove this text

* more variable name fixes

* test repair

Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
Co-authored-by: ET <evantorrie@users.noreply.github.com>
Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>

Author: 4 people

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 (feature-frozen) metric API specification:
+  - ValueRecorder becomes Histogram
+  - ValueObserver becomes Gauge
+  - SumObserver becomes CounterObserver
+  - UpDownSumObserver becomes UpDownCounterObserver
+  The API exported from this project 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")
+	histogram := 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")}
@@ -95,7 +95,7 @@ func main() {
 	meter.RecordBatch(
 		ctx,
 		commonLabels,
-		valuerecorder.Measurement(2.0),
+		histogram.Measurement(2.0),
 		counter.Measurement(12.0),
 	)
 
@@ -108,7 +108,7 @@ func main() {
 	meter.RecordBatch(
 		ctx,
 		notSoCommonLabels,
-		valuerecorder.Measurement(2.0),
+		histogram.Measurement(2.0),
 		counter.Measurement(22.0),
 	)
 
@@ -121,7 +121,7 @@ func main() {
 	meter.RecordBatch(
 		ctx,
 		commonLabels,
-		valuerecorder.Measurement(12.0),
+		histogram.Measurement(12.0),
 		counter.Measurement(13.0),
 	)
 

exporters/otlp/otlpmetric/exporter_test.go

@@ -212,10 +212,10 @@ func TestNoGroupingExport(t *testing.T) {
 	)
 }
 
-func TestValuerecorderMetricGroupingExport(t *testing.T) {
+func TestHistogramMetricGroupingExport(t *testing.T) {
 	r := record{
-		"valuerecorder",
-		sdkapi.ValueRecorderInstrumentKind,
+		"histogram",
+		sdkapi.HistogramInstrumentKind,
 		number.Int64Kind,
 		nil,
 		append(baseKeyValues, cpuKey.Int(1)),
@@ -227,7 +227,7 @@ func TestValuerecorderMetricGroupingExport(t *testing.T) {
 				{
 					Metrics: []*metricpb.Metric{
 						{
-							Name: "valuerecorder",
+							Name: "histogram",
 							Data: &metricpb.Metric_Histogram{
 								Histogram: &metricpb.Histogram{
 									AggregationTemporality: metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE,
@@ -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},
+		{"counterobserver", sdkapi.CounterObserverInstrumentKind, metricpb.AggregationTemporality_AGGREGATION_TEMPORALITY_CUMULATIVE, true},
+		{"updowncounterobserver", 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-histogram":       {sdkapi.HistogramInstrumentKind, number.Int64Kind, 2},
+		"test-float64-histogram":     {sdkapi.HistogramInstrumentKind, number.Float64Kind, 2},
+		"test-int64-gaugeobserver":   {sdkapi.GaugeObserverInstrumentKind, number.Int64Kind, 3},
+		"test-float64-gaugeobserver": {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")
+	histogram := metric.Must(meter).NewFloat64Histogram("histogram")
 
 	labels := []attribute.KeyValue{
 		attribute.Key("A").String("B"),
@@ -124,23 +124,23 @@ 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...)
 	})
 
 	expected = append(expected, expectGauge("intobserver", `intobserver{A="B",C="D",R="V"} 1`))
 
-	valuerecorder.Record(ctx, -0.6, labels...)
-	valuerecorder.Record(ctx, -0.4, labels...)
-	valuerecorder.Record(ctx, 0.6, labels...)
-	valuerecorder.Record(ctx, 20, labels...)
-
-	expected = append(expected, expectHistogram("valuerecorder",
-		`valuerecorder_bucket{A="B",C="D",R="V",le="-0.5"} 1`,
-		`valuerecorder_bucket{A="B",C="D",R="V",le="1"} 3`,
-		`valuerecorder_bucket{A="B",C="D",R="V",le="+Inf"} 4`,
-		`valuerecorder_sum{A="B",C="D",R="V"} 19.6`,
-		`valuerecorder_count{A="B",C="D",R="V"} 4`,
+	histogram.Record(ctx, -0.6, labels...)
+	histogram.Record(ctx, -0.4, labels...)
+	histogram.Record(ctx, 0.6, labels...)
+	histogram.Record(ctx, 20, labels...)
+
+	expected = append(expected, expectHistogram("histogram",
+		`histogram_bucket{A="B",C="D",R="V",le="-0.5"} 1`,
+		`histogram_bucket{A="B",C="D",R="V",le="1"} 3`,
+		`histogram_bucket{A="B",C="D",R="V",le="+Inf"} 4`,
+		`histogram_sum{A="B",C="D",R="V"} 19.6`,
+		`histogram_count{A="B",C="D",R="V"} 4`,
 	))
 
 	upDownCounter.Add(ctx, 10, 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"))