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>

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