Unify metric API into the one otel/metric package

[MrAlias]

Resolves: #3995

Changes:

• Flatten metric/instrument into metric
• Deprecates all previously released types from metric/instrument and the package itself

These changes are proposed as they resolve the following:

• The metric/instrument package only provides types and functionality called from the metric package
• The metric API is fractured across two packages currently
  • Users need to import two packages for the single task of instrumenting code with metrics
  • Users need to reference documentation from metric/instrument to understand the full purpose and functionality of metric

This proposal has been discussed before¹², why change it now?

Prior considerations were made before the Meter API was updated to be specification compliant. That update and the following cleanup removed the non-compliant instrument provider and the number scoped instrument packages. With those changes the instruments themselves are never meant to be created or used outside of the functionality provided by metric. It is a relic to keep the partition of the metric/instrument package when all of its use is now in metric.

Footnotes

1. https://github.com/open-telemetry/opentelemetry-go/issues/2653 ↩

2. https://github.com/open-telemetry/opentelemetry-go/issues/2526 ↩

[codecov]

Codecov Report

Merging #4018 (4302d01) into main (94f6c4f) will decrease coverage by 0.1%.
The diff coverage is 100.0%.

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #4018     +/-   ##
=======================================
- Coverage   82.2%   82.2%   -0.1%     
=======================================
  Files        175     175             
  Lines      13065   13065             
=======================================
- Hits       10742   10740      -2     
- Misses      2102    2104      +2     
  Partials     221     221             

Impacted Files	Coverage Δ
metric/asyncfloat64.go	100.0% <ø> (ø)
metric/asyncint64.go	100.0% <ø> (ø)
metric/syncfloat64.go	100.0% <ø> (ø)
metric/syncint64.go	100.0% <ø> (ø)
metric/instrument.go	100.0% <100.0%> (ø)
metric/internal/global/instruments.go	60.8% <100.0%> (ø)
metric/internal/global/meter.go	93.8% <100.0%> (ø)
metric/noop/noop.go	100.0% <100.0%> (ø)
sdk/metric/instrument.go	93.0% <100.0%> (ø)
sdk/metric/meter.go	90.2% <100.0%> (ø)

... and 1 file with indirect coverage changes

[pellared]

I am aware that my comments are mostly concerns about the OTel Metrics API Spec. However, I do not think that the package users need to know/check exactly what is in the spec.

[pellared]

@seh PTAL 😉

[seh]

Do the types and functions that had lived in the sdk/metric/instrument package need to be exported? It's hard to tell from the PR how the files outside this package were relying on it. In some cases it was the options that we discussed during last week's SIG meeting, and continuing to export those is still necessary.

For example, does the specification mandate that we expose types like metric.Float64Observable? Can we shrink the exported surface of this Go module?

[MrAlias]

Do the types and functions that had lived in the sdk/metric/instrument package need to be exported? It's hard to tell from the PR how the files outside this package were relying on it. In some cases it was the options that we discussed during last week's SIG meeting, and continuing to export those is still necessary.

For example, does the specification mandate that we expose types like metric.Float64Observable? Can we shrink the exported surface of this Go module?

All of the instruments need to be exported as they are returned from their respective creation method of the Meter.

The Float64Observable itself is needed to generally reference all the observable instruments that can be passed to a Float64Callback.

[seh]

All of the instruments need to be exported as they are returned from their respective creation method of the Meter.

Got it. This is not the opportunity I was hoping to find.

[MrAlias]

@Aneurysm9 thoughts?