opentelemetry-metrics-api 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea4f3c76493a7fd16c6c17457eadc82abde93f7124ec22c5697c8e6eb38fc932
-  data.tar.gz: 8fbeff160a5f21e9641fd0d4007ab1b9cd020f81fe08794f88bc3b0ce2ae4b15
+  metadata.gz: bdddbd715c197f54333fb8d8938d5342e9c6040048de12aa58e97416110f21b1
+  data.tar.gz: 8a70192047000b96d310c481e8fea2346f1af280400c49726856cb2d5df1eeb8
 SHA512:
-  metadata.gz: 1f042a80106a1445534b5f9f7e17dbbf99f773898827d3877aed6e984653cff26b5c9c61abc64db2467d2fc3752602af286ae2635ffdf39ab525558f0d6908c5
-  data.tar.gz: a0c2d36c901f160ba9f426f969a1e43127624f3d286f013252fa68cdc2c3f80abc1a483e9da40720669e1c706c3acfc34faaaaa18612bb47662fdcbe8630999f
+  metadata.gz: 74d6673bf1c5d7d0e84c997be486ba8d62f2082b60a60ecc5e53780ca67a29364caff82d93445ac85da0c7014e88ed77a7c477b282017ffa2ae88453265bdb30
+  data.tar.gz: 4e77afb89660407b222599ad3aade9c4427687b7e5d825da5e50f9797119bbef2a0e60dbdfc911c9481bb5a2eb75350f5fabd1fabf7c1b2fb261ca36c92759c0

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History: opentelemetry-metrics-api
 
+### v0.8.0 / 2026-09-29
+
+* BREAKING CHANGE: Update api for spec compliance (#2309)
+* ADDED: Update api for spec compliance (#2309)
+
 ### v0.7.1 / 2026-09-15
 
 * FIXED: Pass the callback through when upgrading a proxy instrument (#2377)

data/lib/opentelemetry/internal/proxy_instrument.rb

@@ -8,25 +8,30 @@ module OpenTelemetry
   module Internal
     # @api private
     class ProxyInstrument
-      def initialize(kind, name, unit, desc, callback, exemplar_filter, exemplar_reservoir)
+      def initialize(kind, name, unit, desc, callback, exemplar_filter, exemplar_reservoir, advisory = nil)
         @kind = kind
         @name = name
         @unit = unit
         @desc = desc
         @callback = callback
-        @exemplar_filter    = exemplar_filter
-        @exemplar_reservoir = exemplar_reservoir
+        @exemplar_filter      = exemplar_filter
+        @exemplar_reservoir   = exemplar_reservoir
+        @advisory             = advisory
+        @registered_callbacks = []
         @delegate = nil
       end
 
       # Replaces the no-op delegate with a real instrument from the given meter.
       def upgrade_with(meter)
         @delegate = case @kind
-                    when :counter, :histogram, :up_down_counter
-                      meter.send("create_#{@kind}", @name, unit: @unit, description: @desc, exemplar_filter: @exemplar_filter, exemplar_reservoir: @exemplar_reservoir)
+                    when :counter, :histogram, :up_down_counter, :gauge
+                      meter.send("create_#{@kind}", @name, unit: @unit, description: @desc, exemplar_filter: @exemplar_filter, exemplar_reservoir: @exemplar_reservoir, advisory: @advisory)
                     when :observable_counter, :observable_gauge, :observable_up_down_counter
-                      meter.send("create_#{@kind}", @name, unit: @unit, description: @desc, exemplar_filter: @exemplar_filter, exemplar_reservoir: @exemplar_reservoir, callback: @callback)
+                      meter.send("create_#{@kind}", @name, unit: @unit, description: @desc, exemplar_filter: @exemplar_filter, exemplar_reservoir: @exemplar_reservoir, callback: @callback, advisory: @advisory)
                     end
+        @registered_callbacks.each do |callback|
+          @delegate.register_callback(callback) if @delegate.respond_to?(:register_callback)
+        end
       end
 
       # Delegates to the upgraded instrument's #add, if any.
@@ -38,6 +43,34 @@ module OpenTelemetry
       def record(amount, attributes: nil)
         @delegate&.record(amount, attributes: attributes)
       end
+
+      # Delegates to the upgraded instrument's #enabled?, false (disabled) until upgraded.
+      def enabled?
+        @delegate ? @delegate.enabled? : false
+      end
+
+      # Delegates to the upgraded instrument's #bind, if any; returns self (no-op) until upgraded.
+      def bind(attributes: {})
+        @delegate ? @delegate.bind(attributes: attributes) : self
+      end
+
+      # Delegates to the underlying instrument, or queues the callback until the delegate is set.
+      def register_callback(callback)
+        if @delegate
+          @delegate.register_callback(callback)
+        else
+          @registered_callbacks << callback
+        end
+      end
+
+      # Delegates to the underlying instrument, or removes the callback from the queue.
+      def unregister(callback)
+        if @delegate
+          @delegate.unregister(callback)
+        else
+          @registered_callbacks.delete(callback)
+        end
+      end
     end
   end
 end

data/lib/opentelemetry/internal/proxy_meter.rb

@@ -38,18 +38,18 @@ module OpenTelemetry
 
       private
 
-      def create_instrument(kind, name, unit, description, callback, exemplar_filter, exemplar_reservoir)
+      def create_instrument(kind, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory)
         super do
-          next ProxyInstrument.new(kind, name, unit, description, callback, exemplar_filter, exemplar_reservoir) if @delegate.nil?
+          next ProxyInstrument.new(kind, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory) if @delegate.nil?
 
           case kind
-          when :counter then @delegate.create_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir)
-          when :histogram then @delegate.create_histogram(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir)
-          when :up_down_counter then @delegate.create_up_down_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir)
-          when :gauge then @delegate.create_gauge(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir)
-          when :observable_counter then @delegate.create_observable_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, callback: callback)
-          when :observable_gauge then @delegate.create_observable_gauge(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, callback: callback)
-          when :observable_up_down_counter then @delegate.create_observable_up_down_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, callback: callback)
+          when :counter then @delegate.create_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, advisory: advisory)
+          when :histogram then @delegate.create_histogram(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, advisory: advisory)
+          when :up_down_counter then @delegate.create_up_down_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, advisory: advisory)
+          when :gauge then @delegate.create_gauge(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, advisory: advisory)
+          when :observable_counter then @delegate.create_observable_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, callback: callback, advisory: advisory)
+          when :observable_gauge then @delegate.create_observable_gauge(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, callback: callback, advisory: advisory)
+          when :observable_up_down_counter then @delegate.create_observable_up_down_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, callback: callback, advisory: advisory)
           end
         end
       end

data/lib/opentelemetry/metrics/instrument/counter.rb

@@ -17,6 +17,32 @@ module OpenTelemetry
         #   Array values must not contain nil elements and all elements must be of
         #   the same basic type (string, numeric, boolean).
         def add(increment, attributes: {}); end
+
+        # Returns whether this Counter is enabled for recording measurements.
+        #
+        # Instrumentation authors need to call this API each time
+        #  they record a measurement to ensure they have the most
+        #  up-to-date value.
+        #
+        # @return [Boolean] default to true in noop implementation
+        def enabled?
+          true
+        end
+
+        # (Development) Binds a fixed set of attributes to this Counter, returning an instrument
+        # whose #add calls associate every measurement with those attributes. Attributes are resolved
+        # once at bind time rather than on every recording, avoiding repeated attribute processing and
+        # lookup. Passing attributes to #add on the returned bound instrument negates this benefit.
+        #
+        # @param [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
+        #   Values must be non-nil and (array of) string, boolean or numeric type.
+        #   Array values must not contain nil elements and all elements must be of
+        #   the same basic type (string, numeric, boolean).
+        #
+        # @return [Counter] a bound instrument supporting #add; the no-op implementation returns self.
+        def bind(attributes: {})
+          self
+        end
       end
     end
   end

data/lib/opentelemetry/metrics/instrument/gauge.rb

@@ -17,6 +17,33 @@ module OpenTelemetry
         #   Array values must not contain nil elements and all elements must be of
         #   the same basic type (string, numeric, boolean).
         def record(amount, attributes: {}); end
+
+        # Returns whether this Gauge is enabled for recording measurements.
+        #
+        # Instrumentation authors need to call this API each time
+        #  they record a measurement to ensure they have the most
+        #  up-to-date value.
+        #
+        # @return [Boolean] default to true in noop implementation
+        def enabled?
+          true
+        end
+
+        # (Development) Binds a fixed set of attributes to this Gauge, returning an instrument
+        # whose #record calls associate every measurement with those attributes. Attributes are
+        # resolved once at bind time rather than on every recording, avoiding repeated attribute
+        # processing and lookup. Passing attributes to #record on the returned bound instrument
+        # negates this benefit.
+        #
+        # @param [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
+        #   Values must be non-nil and (array of) string, boolean or numeric type.
+        #   Array values must not contain nil elements and all elements must be of
+        #   the same basic type (string, numeric, boolean).
+        #
+        # @return [Gauge] a bound instrument supporting #record; the no-op implementation returns self.
+        def bind(attributes: {})
+          self
+        end
       end
     end
   end

data/lib/opentelemetry/metrics/instrument/histogram.rb

@@ -17,6 +17,33 @@ module OpenTelemetry
         #   Array values must not contain nil elements and all elements must be of
         #   the same basic type (string, numeric, boolean).
         def record(amount, attributes: {}); end
+
+        # Returns whether this Histogram is enabled for recording measurements.
+        #
+        # Instrumentation authors need to call this API each time
+        #  they record a measurement to ensure they have the most
+        #  up-to-date value.
+        #
+        # @return [Boolean] default to true in noop implementation
+        def enabled?
+          true
+        end
+
+        # (Development) Binds a fixed set of attributes to this Histogram, returning an instrument
+        # whose #record calls associate every measurement with those attributes. Attributes are
+        # resolved once at bind time rather than on every recording, avoiding repeated attribute
+        # processing and lookup. Passing attributes to #record on the returned bound instrument
+        # negates this benefit.
+        #
+        # @param [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
+        #   Values must be non-nil and (array of) string, boolean or numeric type.
+        #   Array values must not contain nil elements and all elements must be of
+        #   the same basic type (string, numeric, boolean).
+        #
+        # @return [Histogram] a bound instrument supporting #record; the no-op implementation returns self.
+        def bind(attributes: {})
+          self
+        end
       end
     end
   end

data/lib/opentelemetry/metrics/instrument/observable_counter.rb

@@ -17,6 +17,16 @@ module OpenTelemetry
         #   Array values must not contain nil elements and all elements must be of
         #   the same basic type (string, numeric, boolean).
         def observe(timeout: nil, attributes: {}); end
+
+        # Registers a callback function to report Measurements for this instrument.
+        #
+        # @param [Proc] callback the callback function
+        def register_callback(callback); end
+
+        # Unregisters a callback function previously registered via {#register_callback}.
+        #
+        # @param [Proc] callback the callback function
+        def unregister(callback); end
       end
     end
   end

data/lib/opentelemetry/metrics/instrument/observable_gauge.rb

@@ -17,6 +17,16 @@ module OpenTelemetry
         #   Array values must not contain nil elements and all elements must be of
         #   the same basic type (string, numeric, boolean).
         def observe(timeout: nil, attributes: {}); end
+
+        # Registers a callback function to report Measurements for this instrument.
+        #
+        # @param [Proc] callback the callback function
+        def register_callback(callback); end
+
+        # Unregisters a callback function previously registered via {#register_callback}.
+        #
+        # @param [Proc] callback the callback function
+        def unregister(callback); end
       end
     end
   end

data/lib/opentelemetry/metrics/instrument/observable_up_down_counter.rb

@@ -17,6 +17,16 @@ module OpenTelemetry
         #   Array values must not contain nil elements and all elements must be of
         #   the same basic type (string, numeric, boolean).
         def observe(timeout: nil, attributes: {}); end
+
+        # Registers a callback function to report Measurements for this instrument.
+        #
+        # @param [Proc] callback the callback function
+        def register_callback(callback); end
+
+        # Unregisters a callback function previously registered via {#register_callback}.
+        #
+        # @param [Proc] callback the callback function
+        def unregister(callback); end
       end
     end
   end

data/lib/opentelemetry/metrics/instrument/up_down_counter.rb

@@ -17,6 +17,33 @@ module OpenTelemetry
         #   Array values must not contain nil elements and all elements must be of
         #   the same basic type (string, numeric, boolean).
         def add(amount, attributes: {}); end
+
+        # Returns whether this UpDownCounter is enabled for recording
+        #  measurements.
+        #
+        # Instrumentation authors need to call this API each time
+        #  they record a measurement to ensure they have the most
+        #  up-to-date value.
+        #
+        # @return [Boolean] default to true in noop implementation
+        def enabled?
+          true
+        end
+
+        # (Development) Binds a fixed set of attributes to this UpDownCounter, returning an instrument
+        # whose #add calls associate every measurement with those attributes. Attributes are resolved
+        # once at bind time rather than on every recording, avoiding repeated attribute processing and
+        # lookup. Passing attributes to #add on the returned bound instrument negates this benefit.
+        #
+        # @param [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
+        #   Values must be non-nil and (array of) string, boolean or numeric type.
+        #   Array values must not contain nil elements and all elements must be of
+        #   the same basic type (string, numeric, boolean).
+        #
+        # @return [UpDownCounter] a bound instrument supporting #add; the no-op implementation returns self.
+        def bind(attributes: {})
+          self
+        end
       end
     end
   end

data/lib/opentelemetry/metrics/meter.rb

@@ -55,10 +55,14 @@ module OpenTelemetry
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir` - uniformly-weighted sampling
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir` - one exemplar per histogram bucket (recommended for histograms)
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir` - no-op, disables exemplar collection
+      # @param advisory [optional Hash] optional advisory parameters: recommendations from the
+      #   instrument author that implementations MAY ignore. The API does not validate them.
+      #   @option advisory [Array<String>] :attributes Recommended set of attribute keys for the resulting metrics.
+      #   @option advisory [Array<Numeric>] :explicit_bucket_boundaries Applies to histograms only and has no effect here.
       #
       # @return [nil] after creation of counter, it will be stored in instrument_registry
-      def create_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil)
-        create_instrument(:counter, name, unit, description, nil, exemplar_filter, exemplar_reservoir) { COUNTER }
+      def create_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
+        create_instrument(:counter, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { COUNTER }
       end
 
       # Histogram is a synchronous Instrument which can be used to report arbitrary values that are likely
@@ -86,10 +90,15 @@ module OpenTelemetry
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir` - uniformly-weighted sampling
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir` - one exemplar per histogram bucket (recommended for histograms)
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir` - no-op, disables exemplar collection
+      # @param advisory [optional Hash] optional advisory parameters: recommendations from the
+      #   instrument author that implementations MAY ignore. The API does not validate them.
+      #   @option advisory [Array<Numeric>] :explicit_bucket_boundaries Recommended bucket boundaries when
+      #     this instrument is aggregated to an explicit bucket histogram.
+      #   @option advisory [Array<String>] :attributes Recommended set of attribute keys for the resulting metrics.
       #
       # @return [nil] after creation of histogram, it will be stored in instrument_registry
-      def create_histogram(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil)
-        create_instrument(:histogram, name, unit, description, nil, exemplar_filter, exemplar_reservoir) { HISTOGRAM }
+      def create_histogram(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
+        create_instrument(:histogram, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { HISTOGRAM }
       end
 
       # Gauge is an synchronous Instrument which reports non-additive value(s)
@@ -115,10 +124,14 @@ module OpenTelemetry
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir` - uniformly-weighted sampling
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir` - one exemplar per histogram bucket (recommended for histograms)
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir` - no-op, disables exemplar collection
+      # @param advisory [optional Hash] optional advisory parameters: recommendations from the
+      #   instrument author that implementations MAY ignore. The API does not validate them.
+      #   @option advisory [Array<String>] :attributes Recommended set of attribute keys for the resulting metrics.
+      #   @option advisory [Array<Numeric>] :explicit_bucket_boundaries Applies to histograms only and has no effect here.
       #
       # @return [nil] after creation of gauge, it will be stored in instrument_registry
-      def create_gauge(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil)
-        create_instrument(:gauge, name, unit, description, nil, exemplar_filter, exemplar_reservoir) { GAUGE }
+      def create_gauge(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
+        create_instrument(:gauge, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { GAUGE }
       end
 
       # UpDownCounter is a synchronous Instrument which supports increments and decrements.
@@ -144,10 +157,14 @@ module OpenTelemetry
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir` - uniformly-weighted sampling
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir` - one exemplar per histogram bucket (recommended for histograms)
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir` - no-op, disables exemplar collection
+      # @param advisory [optional Hash] optional advisory parameters: recommendations from the
+      #   instrument author that implementations MAY ignore. The API does not validate them.
+      #   @option advisory [Array<String>] :attributes Recommended set of attribute keys for the resulting metrics.
+      #   @option advisory [Array<Numeric>] :explicit_bucket_boundaries Applies to histograms only and has no effect here.
       #
       # @return [nil] after creation of up_down_counter, it will be stored in instrument_registry
-      def create_up_down_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil)
-        create_instrument(:up_down_counter, name, unit, description, nil, exemplar_filter, exemplar_reservoir) { UP_DOWN_COUNTER }
+      def create_up_down_counter(name, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
+        create_instrument(:up_down_counter, name, unit, description, nil, exemplar_filter, exemplar_reservoir, advisory) { UP_DOWN_COUNTER }
       end
 
       # ObservableCounter is an asynchronous Instrument which reports monotonically
@@ -164,7 +181,7 @@ module OpenTelemetry
       #                                    exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)
       #
       # @param name [String] the name of the observable_counter
-      # @param callback [Proc] the callback function that used to collect metrics
+      # @param callback [optional Proc, Array<Proc>] zero or more callback functions used to collect metrics
       # @param unit [optional String] an optional string provided by user.
       # @param description [optional String] an optional free-form text provided by user.
       # @param exemplar_filter [optional Object] an optional filter to control which measurements are
@@ -177,10 +194,14 @@ module OpenTelemetry
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir` - uniformly-weighted sampling
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir` - one exemplar per histogram bucket (recommended for histograms)
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir` - no-op, disables exemplar collection
+      # @param advisory [optional Hash] optional advisory parameters: recommendations from the
+      #   instrument author that implementations MAY ignore. The API does not validate them.
+      #   @option advisory [Array<String>] :attributes Recommended set of attribute keys for the resulting metrics.
+      #   @option advisory [Array<Numeric>] :explicit_bucket_boundaries Applies to histograms only and has no effect here.
       #
       # @return [nil] after creation of observable_counter, it will be stored in instrument_registry
-      def create_observable_counter(name, callback:, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil)
-        create_instrument(:observable_counter, name, unit, description, callback, exemplar_filter, exemplar_reservoir) { OBSERVABLE_COUNTER }
+      def create_observable_counter(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
+        create_instrument(:observable_counter, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory) { OBSERVABLE_COUNTER }
       end
 
       # ObservableGauge is an asynchronous Instrument which reports non-additive value(s)
@@ -198,7 +219,7 @@ module OpenTelemetry
       #                                  exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)
       #
       # @param name [String] the name of the observable_gauge
-      # @param callback [Proc] the callback function that used to collect metrics
+      # @param callback [optional Proc, Array<Proc>] zero or more callback functions used to collect metrics
       # @param unit [optional String] an optional string provided by user.
       # @param description [optional String] an optional free-form text provided by user.
       # @param exemplar_filter [optional Object] an optional filter to control which measurements are
@@ -211,10 +232,14 @@ module OpenTelemetry
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir` - uniformly-weighted sampling
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir` - one exemplar per histogram bucket (recommended for histograms)
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir` - no-op, disables exemplar collection
+      # @param advisory [optional Hash] optional advisory parameters: recommendations from the
+      #   instrument author that implementations MAY ignore. The API does not validate them.
+      #   @option advisory [Array<String>] :attributes Recommended set of attribute keys for the resulting metrics.
+      #   @option advisory [Array<Numeric>] :explicit_bucket_boundaries Applies to histograms only and has no effect here.
       #
       # @return [nil] after creation of observable_gauge, it will be stored in instrument_registry
-      def create_observable_gauge(name, callback:, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil)
-        create_instrument(:observable_gauge, name, unit, description, callback, exemplar_filter, exemplar_reservoir) { OBSERVABLE_GAUGE }
+      def create_observable_gauge(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
+        create_instrument(:observable_gauge, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory) { OBSERVABLE_GAUGE }
       end
 
       # ObservableUpDownCounter is an asynchronous Instrument which reports additive value(s)
@@ -232,7 +257,7 @@ module OpenTelemetry
       #                                            exemplar_reservoir: OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new)
       #
       # @param name [String] the name of the observable_up_down_counter
-      # @param callback [Proc] the callback function that used to collect metrics
+      # @param callback [optional Proc, Array<Proc>] zero or more callback functions used to collect metrics
       # @param unit [optional String] an optional string provided by user.
       # @param description [optional String] an optional free-form text provided by user.
       # @param exemplar_filter [optional Object] an optional filter to control which measurements are
@@ -245,15 +270,39 @@ module OpenTelemetry
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::SimpleFixedSizeExemplarReservoir` - uniformly-weighted sampling
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir` - one exemplar per histogram bucket (recommended for histograms)
       #   - `OpenTelemetry::SDK::Metrics::Exemplar::NoopExemplarReservoir` - no-op, disables exemplar collection
+      # @param advisory [optional Hash] optional advisory parameters: recommendations from the
+      #   instrument author that implementations MAY ignore. The API does not validate them.
+      #   @option advisory [Array<String>] :attributes Recommended set of attribute keys for the resulting metrics.
+      #   @option advisory [Array<Numeric>] :explicit_bucket_boundaries Applies to histograms only and has no effect here.
       #
       # @return [nil] after creation of observable_up_down_counter, it will be stored in instrument_registry
-      def create_observable_up_down_counter(name, callback:, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil)
-        create_instrument(:observable_up_down_counter, name, unit, description, callback, exemplar_filter, exemplar_reservoir) { OBSERVABLE_UP_DOWN_COUNTER }
+      def create_observable_up_down_counter(name, callback: nil, unit: nil, description: nil, exemplar_filter: nil, exemplar_reservoir: nil, advisory: nil)
+        create_instrument(:observable_up_down_counter, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory) { OBSERVABLE_UP_DOWN_COUNTER }
+      end
+
+      # Registers a callback function against a declared set of asynchronous instruments from this Meter.
+      #
+      # @param [Array] instruments the asynchronous instruments the callback function reports Measurements for
+      # @param [Proc] callback the callback function
+      #
+      # @return [nil]
+      def register_callback(instruments, callback)
+        instruments.each { |instrument| instrument.register_callback(callback) }
+      end
+
+      # Unregisters a callback function previously registered via {#register_callback}.
+      #
+      # @param [Array] instruments the asynchronous instruments the callback function was registered against
+      # @param [Proc] callback the callback function
+      #
+      # @return [nil]
+      def unregister(instruments, callback)
+        instruments.each { |instrument| instrument.unregister(callback) }
       end
 
       private
 
-      def create_instrument(kind, name, unit, description, callback, exemplar_filter, exemplar_reservoir)
+      def create_instrument(kind, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory)
         @mutex.synchronize do
           OpenTelemetry.logger.warn("duplicate instrument registration occurred for instrument #{name}") if @instrument_registry.include? name
 

data/lib/opentelemetry/metrics/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module Metrics
     ## Current OpenTelemetry metrics version
-    VERSION = '0.7.1'
+    VERSION = '0.8.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-metrics-api
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
@@ -54,10 +54,10 @@ homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://rubydoc.info/gems/opentelemetry-metrics-api/0.7.1/file/CHANGELOG.md
-  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-api/v0.7.1/metrics_api
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-metrics-api/0.8.0/file/CHANGELOG.md
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-api/v0.8.0/metrics_api
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
-  documentation_uri: https://rubydoc.info/gems/opentelemetry-metrics-api/0.7.1
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-metrics-api/0.8.0
 rdoc_options: []
 require_paths:
 - lib
@@ -72,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A stats collection and distributed tracing framework
 test_files: []