Update metric API documentation (#3896)

* Update metric API documentation

Remove the warning on otel/metric not being GA.

Document the otel/metric and otel/metric/instrument package for
instrumenters.

* Remove unrendered links in MeterProvider.Meter doc

* Clarify synchronous and asynchronous

* Fix misspelling

* Update metric/instrument/doc.go

Co-authored-by: Robert Pająk <pellared@hotmail.com>

* Update metric/instrument/doc.go

Co-authored-by: Robert Pająk <pellared@hotmail.com>

* Update metric/instrument/doc.go

Co-authored-by: Robert Pająk <pellared@hotmail.com>

* Update metric/instrument/doc.go

Co-authored-by: Robert Pająk <pellared@hotmail.com>

* Apply feedback

* Apply suggestions from code review

Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>

---------

Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>

metric/doc.go

@@ -13,11 +13,23 @@
 // limitations under the License.
 
 /*
-Package metric provides an implementation of the metrics part of the
-OpenTelemetry API.
+Package metric provides the OpenTelemetry API used to measure metrics about
+source code operation.
 
-This package is currently in a pre-GA phase. Backwards incompatible changes
-may be introduced in subsequent minor version releases as we work to track the
-evolving OpenTelemetry specification and user feedback.
+This API is separate from its implementation so the instrumentation built from
+it is reusable. See [go.opentelemetry.io/otel/sdk/metric] for the official
+OpenTelemetry implementation of this API.
+
+All measurements made with this package are made via instruments. These
+instruments are created by a [Meter] which itself is created by a
+[MeterProvider]. Applications need to accept a [MeterProvider] implementation
+as a starting point when instrumenting. This can be done directly, or by using
+the OpenTelemetry global MeterProvider via [GetMeterProvider]. Using an
+appropriately named [Meter] from the accepted [MeterProvider], instrumentation
+can then be built from the [Meter]'s instruments. See
+[go.opentelemetry.io/otel/metric/instrument] for documentation on each
+instrument and its intended use.
+
+[GetMeterProvider]: https://pkg.go.dev/go.opentelemetry.io/otel#GetMeterProvider
 */
 package metric // import "go.opentelemetry.io/otel/metric"

metric/instrument/doc.go

@@ -0,0 +1,59 @@
+// 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.
+
+/*
+Package instrument provides the OpenTelemetry API instruments used to make
+measurements.
+
+Each instrument is designed to make measurements of a particular type. Broadly,
+all instruments fall into two overlapping logical categories: asynchronous or
+synchronous, and int64 or float64.
+
+All synchronous instruments ([Int64Counter], [Int64UpDownCounter],
+[Int64Histogram], [Float64Counter], [Float64UpDownCounter], [Float64Histogram])
+are used to measure the operation and performance of source code during the
+source code execution. These instruments only make measurements when the source
+code they instrument is run.
+
+All asynchronous instruments ([Int64ObservableCounter],
+[Int64ObservableUpDownCounter], [Int64ObservableGauge],
+[Float64ObservableCounter], [Float64ObservableUpDownCounter],
+[Float64ObservableGauge]) are used to measure metrics outside of the execution
+of source code. They are said to make "observations" via a callback function
+called once every measurement collection cycle.
+
+Each instrument is also grouped by the value type it measures. Either int64 or
+float64. The value being measured will dictate which instrument in these
+categories to use.
+
+Outside of these two broad categories, instruments are described by the
+function they are designed to serve. All Counters ([Int64Counter],
+[Float64Counter], [Int64ObservableCounter], [Float64ObservableCounter]) are
+designed to measure values that never decrease in value, but instead only
+incrementally increase in value. UpDownCounters ([Int64UpDownCounter],
+[Float64UpDownCounter], [Int64ObservableUpDownCounter],
+[Float64ObservableUpDownCounter]) on the other hand, are designed to measure
+values that can increase and decrease. When more information
+needs to be conveyed about all the synchronous measurements made during a
+collection cycle, a Histogram ([Int64Histogram], [Float64Histogram]) should be
+used. Finally, when just the most recent measurement needs to be conveyed about an
+asynchronous measurement, a Gauge ([Int64ObservableGauge],
+[Float64ObservableGauge]) should be used.
+
+See the [OpenTelemetry documentation] for more information about instruments
+and their intended use.
+
+[OpenTelemetry documentation]: https://opentelemetry.io/docs/concepts/signals/metrics/
+*/
+package instrument // import "go.opentelemetry.io/otel/metric/instrument"

metric/meter.go

@@ -22,15 +22,19 @@ import (
 )
 
 // MeterProvider provides access to named Meter instances, for instrumenting
-// an application or library.
+// an application or package.
 //
 // Warning: methods may be added to this interface in minor releases.
 type MeterProvider interface {
-	// Meter creates an instance of a `Meter` interface. The name must be the
-	// name of the library providing instrumentation. This name may be the same
-	// as the instrumented code only if that code provides built-in
-	// instrumentation. If the name is empty, then a implementation defined
-	// default name will be used instead.
+	// Meter returns a new Meter with the provided name and configuration.
+	//
+	// A Meter should be scoped at most to a single package. The name needs to
+	// be unique so it does not collide with other names used by
+	// an application, nor other applications. To achieve this, the import path
+	// of the instrumentation package is recommended to be used as name.
+	//
+	// If the name is empty, then an implementation defined default name will
+	// be used instead.
 	Meter(name string, opts ...MeterOption) Meter
 }