Document instrument name requirements (#5435)

Fix #5377

---------

Co-authored-by: Sam Xie <sam@samxie.me>

CHANGELOG.md

@@ -19,6 +19,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Identify the `Tracer` returned from the global `TracerProvider` in `go.opentelemetry.io/otel/global` with its schema URL. (#5426)
 - Identify the `Meter` returned from the global `MeterProvider` in `go.opentelemetry.io/otel/global` with its schema URL. (#5426)
 - Log a warning to the OpenTelemetry internal logger when a `Span` in `go.opentelemetry.io/otel/sdk/trace` drops an attribute, event, or link due to a limit being reached. (#5434)
+- Document instrument name requirements in `go.opentelemetry.io/otel/metric`. (#5435)
 
 ## [1.27.0/0.49.0/0.3.0] 2024-05-21
 

metric/doc.go

@@ -57,6 +57,23 @@ asynchronous measurement, a Gauge ([Int64ObservableGauge] and
 See the [OpenTelemetry documentation] for more information about instruments
 and their intended use.
 
+# Instrument Name
+
+OpenTelemetry defines an [instrument name syntax] that restricts what
+instrument names are allowed.
+
+Instrument names should ...
+
+  - Not be empty.
+  - Have an alphabetic character as their first letter.
+  - Have any letter after the first be an alphanumeric character, ‘_’, ‘.’,
+    ‘-’, or ‘/’.
+  - Have a maximum length of 255 letters.
+
+To ensure compatibility with observability platforms, all instruments created
+need to conform to this syntax. Not all implementations of the API will validate
+these names, it is the callers responsibility to ensure compliance.
+
 # Measurements
 
 Measurements are made by recording values and information about the values with
@@ -153,6 +170,7 @@ It is strongly recommended that authors only embed
 That implementation is the only one OpenTelemetry authors can guarantee will
 fully implement all the API interfaces when a user updates their API.
 
+[instrument name syntax]: https://opentelemetry.io/docs/specs/otel/metrics/api/#instrument-name-syntax
 [OpenTelemetry documentation]: https://opentelemetry.io/docs/concepts/signals/metrics/
 [GetMeterProvider]: https://pkg.go.dev/go.opentelemetry.io/otel#GetMeterProvider
 */

metric/meter.go

@@ -47,20 +47,36 @@ type Meter interface {
 	// Int64Counter returns a new Int64Counter instrument identified by name
 	// and configured with options. The instrument is used to synchronously
 	// record increasing int64 measurements during a computational operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error)
 	// Int64UpDownCounter returns a new Int64UpDownCounter instrument
 	// identified by name and configured with options. The instrument is used
 	// to synchronously record int64 measurements during a computational
 	// operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error)
 	// Int64Histogram returns a new Int64Histogram instrument identified by
 	// name and configured with options. The instrument is used to
 	// synchronously record the distribution of int64 measurements during a
 	// computational operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error)
 	// Int64Gauge returns a new Int64Gauge instrument identified by name and
 	// configured with options. The instrument is used to synchronously record
 	// instantaneous int64 measurements during a computational operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Int64Gauge(name string, options ...Int64GaugeOption) (Int64Gauge, error)
 	// Int64ObservableCounter returns a new Int64ObservableCounter identified
 	// by name and configured with options. The instrument is used to
@@ -71,6 +87,10 @@ type Meter interface {
 	// the WithInt64Callback option to register the callback here, or use the
 	// RegisterCallback method of this Meter to register one later. See the
 	// Measurements section of the package documentation for more information.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error)
 	// Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter
 	// instrument identified by name and configured with options. The
@@ -81,6 +101,10 @@ type Meter interface {
 	// the WithInt64Callback option to register the callback here, or use the
 	// RegisterCallback method of this Meter to register one later. See the
 	// Measurements section of the package documentation for more information.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Int64ObservableUpDownCounter(name string, options ...Int64ObservableUpDownCounterOption) (Int64ObservableUpDownCounter, error)
 	// Int64ObservableGauge returns a new Int64ObservableGauge instrument
 	// identified by name and configured with options. The instrument is used
@@ -91,26 +115,46 @@ type Meter interface {
 	// the WithInt64Callback option to register the callback here, or use the
 	// RegisterCallback method of this Meter to register one later. See the
 	// Measurements section of the package documentation for more information.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error)
 
 	// Float64Counter returns a new Float64Counter instrument identified by
 	// name and configured with options. The instrument is used to
 	// synchronously record increasing float64 measurements during a
 	// computational operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error)
 	// Float64UpDownCounter returns a new Float64UpDownCounter instrument
 	// identified by name and configured with options. The instrument is used
 	// to synchronously record float64 measurements during a computational
 	// operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error)
 	// Float64Histogram returns a new Float64Histogram instrument identified by
 	// name and configured with options. The instrument is used to
 	// synchronously record the distribution of float64 measurements during a
 	// computational operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error)
 	// Float64Gauge returns a new Float64Gauge instrument identified by name and
 	// configured with options. The instrument is used to synchronously record
 	// instantaneous float64 measurements during a computational operation.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Float64Gauge(name string, options ...Float64GaugeOption) (Float64Gauge, error)
 	// Float64ObservableCounter returns a new Float64ObservableCounter
 	// instrument identified by name and configured with options. The
@@ -121,6 +165,10 @@ type Meter interface {
 	// the WithFloat64Callback option to register the callback here, or use the
 	// RegisterCallback method of this Meter to register one later. See the
 	// Measurements section of the package documentation for more information.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error)
 	// Float64ObservableUpDownCounter returns a new
 	// Float64ObservableUpDownCounter instrument identified by name and
@@ -131,6 +179,10 @@ type Meter interface {
 	// the WithFloat64Callback option to register the callback here, or use the
 	// RegisterCallback method of this Meter to register one later. See the
 	// Measurements section of the package documentation for more information.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Float64ObservableUpDownCounter(name string, options ...Float64ObservableUpDownCounterOption) (Float64ObservableUpDownCounter, error)
 	// Float64ObservableGauge returns a new Float64ObservableGauge instrument
 	// identified by name and configured with options. The instrument is used
@@ -141,6 +193,10 @@ type Meter interface {
 	// the WithFloat64Callback option to register the callback here, or use the
 	// RegisterCallback method of this Meter to register one later. See the
 	// Measurements section of the package documentation for more information.
+	//
+	// The name needs to conform to the OpenTelemetry instrument name syntax.
+	// See the Instrument Name section of the package documentation for more
+	// information.
 	Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error)
 
 	// RegisterCallback registers f to be called during the collection of a