From 988a625a10e2d7f0807c1e17f3dee9de13c485ee Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 26 Feb 2026 13:15:08 -0500 Subject: [PATCH] Document metric api interfaces that methods need to be safe to be called concurrently (#7952) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes https://github.com/open-telemetry/opentelemetry-go/issues/7864 Follows this spec change: https://github.com/open-telemetry/opentelemetry-specification/pull/4868 --------- Co-authored-by: Robert Pająk --- metric/asyncfloat64.go | 3 +++ metric/asyncint64.go | 3 +++ metric/meter.go | 54 +++++++++++++++++++++++++++++++++++++++++- metric/syncfloat64.go | 24 +++++++++++++++++++ metric/syncint64.go | 24 +++++++++++++++++++ 5 files changed, 107 insertions(+), 1 deletion(-) diff --git a/metric/asyncfloat64.go b/metric/asyncfloat64.go index eb4f5961f..466812d34 100644 --- a/metric/asyncfloat64.go +++ b/metric/asyncfloat64.go @@ -211,6 +211,9 @@ type Float64Observer interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Observe(value float64, options ...ObserveOption) } diff --git a/metric/asyncint64.go b/metric/asyncint64.go index 1dfc4b0f2..66c971bd8 100644 --- a/metric/asyncint64.go +++ b/metric/asyncint64.go @@ -210,6 +210,9 @@ type Int64Observer interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Observe(value int64, options ...ObserveOption) } diff --git a/metric/meter.go b/metric/meter.go index a16c4c0a1..5606ec4bd 100644 --- a/metric/meter.go +++ b/metric/meter.go @@ -30,6 +30,9 @@ type MeterProvider interface { // // If the name is empty, then an implementation defined default name will // be used instead. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Meter(name string, opts ...MeterOption) Meter } @@ -51,6 +54,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error) // Int64UpDownCounter returns a new Int64UpDownCounter instrument @@ -61,6 +67,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error) // Int64Histogram returns a new Int64Histogram instrument identified by @@ -71,6 +80,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error) // Int64Gauge returns a new Int64Gauge instrument identified by name and @@ -80,6 +92,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Int64Gauge(name string, options ...Int64GaugeOption) (Int64Gauge, error) // Int64ObservableCounter returns a new Int64ObservableCounter identified @@ -95,6 +110,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error) // Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter @@ -110,6 +128,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Int64ObservableUpDownCounter( name string, options ...Int64ObservableUpDownCounterOption, @@ -128,6 +149,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error) // Float64Counter returns a new Float64Counter instrument identified by @@ -148,6 +172,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error) // Float64Histogram returns a new Float64Histogram instrument identified by @@ -158,6 +185,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error) // Float64Gauge returns a new Float64Gauge instrument identified by name and @@ -167,6 +197,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Float64Gauge(name string, options ...Float64GaugeOption) (Float64Gauge, error) // Float64ObservableCounter returns a new Float64ObservableCounter @@ -182,6 +215,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error) // Float64ObservableUpDownCounter returns a new @@ -197,6 +233,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Float64ObservableUpDownCounter( name string, options ...Float64ObservableUpDownCounterOption, @@ -215,6 +254,9 @@ type Meter interface { // The name needs to conform to the OpenTelemetry instrument name syntax. // See the Instrument Name section of the package documentation for more // information. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error) // RegisterCallback registers f to be called during the collection of a @@ -229,6 +271,9 @@ type Meter interface { // If no instruments are passed, f should not be registered nor called // during collection. // + // Implementations of this method need to be safe for a user to call + // concurrently. + // // The function f needs to be concurrent safe. RegisterCallback(f Callback, instruments ...Observable) (Registration, error) } @@ -263,9 +308,15 @@ type Observer interface { embedded.Observer // ObserveFloat64 records the float64 value for obsrv. + // + // Implementations of this method need to be safe for a user to call + // concurrently. ObserveFloat64(obsrv Float64Observable, value float64, opts ...ObserveOption) // ObserveInt64 records the int64 value for obsrv. + // + // Implementations of this method need to be safe for a user to call + // concurrently. ObserveInt64(obsrv Int64Observable, value int64, opts ...ObserveOption) } @@ -283,6 +334,7 @@ type Registration interface { // Unregister removes the callback registration from a Meter. // - // This method needs to be idempotent and concurrent safe. + // Implementations of this method need to be idempotent and safe for a user + // to call concurrently. Unregister() error } diff --git a/metric/syncfloat64.go b/metric/syncfloat64.go index 57a74c5e6..abb3051d7 100644 --- a/metric/syncfloat64.go +++ b/metric/syncfloat64.go @@ -24,12 +24,18 @@ type Float64Counter interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Add(ctx context.Context, incr float64, options ...AddOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool } @@ -83,12 +89,18 @@ type Float64UpDownCounter interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Add(ctx context.Context, incr float64, options ...AddOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool } @@ -142,12 +154,18 @@ type Float64Histogram interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Record(ctx context.Context, incr float64, options ...RecordOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool } @@ -206,12 +224,18 @@ type Float64Gauge interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Record(ctx context.Context, value float64, options ...RecordOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool } diff --git a/metric/syncint64.go b/metric/syncint64.go index ac2d033ea..5bbfaf039 100644 --- a/metric/syncint64.go +++ b/metric/syncint64.go @@ -24,12 +24,18 @@ type Int64Counter interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Add(ctx context.Context, incr int64, options ...AddOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool } @@ -83,12 +89,18 @@ type Int64UpDownCounter interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Add(ctx context.Context, incr int64, options ...AddOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool } @@ -142,12 +154,18 @@ type Int64Histogram interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Record(ctx context.Context, incr int64, options ...RecordOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool } @@ -206,12 +224,18 @@ type Int64Gauge interface { // // Use the WithAttributeSet (or, if performance is not a concern, // the WithAttributes) option to include measurement attributes. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Record(ctx context.Context, value int64, options ...RecordOption) // Enabled reports whether the instrument will process measurements for the given context. // // This function can be used in places where measuring an instrument // would result in computationally expensive operations. + // + // Implementations of this method need to be safe for a user to call + // concurrently. Enabled(context.Context) bool }