opentelemetry-metrics-api 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea4f3c76493a7fd16c6c17457eadc82abde93f7124ec22c5697c8e6eb38fc932
-  data.tar.gz: 8fbeff160a5f21e9641fd0d4007ab1b9cd020f81fe08794f88bc3b0ce2ae4b15
+  metadata.gz: '01447149549ce311507e50a73b1c25962ea229f9d30fee3878ca09b519e278ba'
+  data.tar.gz: c7cf8d92fd0a56ee620a0c465f10178dde5773652482ca02b607fd3db06d4884
 SHA512:
-  metadata.gz: 1f042a80106a1445534b5f9f7e17dbbf99f773898827d3877aed6e984653cff26b5c9c61abc64db2467d2fc3752602af286ae2635ffdf39ab525558f0d6908c5
-  data.tar.gz: a0c2d36c901f160ba9f426f969a1e43127624f3d286f013252fa68cdc2c3f80abc1a483e9da40720669e1c706c3acfc34faaaaa18612bb47662fdcbe8630999f
+  metadata.gz: fb53b43bcbce42330ba77fc382e398f6972cbe7b643d346bd6afe63fc7e354fac8f0874bb56858fea667e5015e21a5c8ac2dcb15cb67a34b0da847b2f7b5d9e0
+  data.tar.gz: 6ffc9da9c4603ded64ba39f805bc73f4bd37dea3044e306e97f6a217e2efca1823801331c07083b146b2dd1807f42a95142ef8966811df6aba7d8b6443064bae

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History: opentelemetry-metrics-api
 
+### v0.9.0 / 2026-10-05
+
+* BREAKING CHANGE: Move the global meter provider behind an opt-in require (#2416)
+* ADDED: Move the global meter provider behind an opt-in require (#2416)
+
+### 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/README.md

@@ -22,18 +22,24 @@ This code is still under development and is not a complete implementation of the
 
 ## How do I get started?
 
-Install the gem using:
+Install the gems using:
 
 ```sh
-gem install opentelemetry-metrics-api
+gem install opentelemetry-sdk
+gem install opentelemetry-metrics-sdk
 ```
 
-Or, if you use [bundler][bundler-home], include `opentelemetry-metrics-api` in your `Gemfile`.
+Or, if you use [bundler][bundler-home], include `opentelemetry-sdk` and `opentelemetry-metrics-sdk` in your `Gemfile`. The SDK depends on `opentelemetry-metrics-api`.
 
-Then, use the OpenTelemetry interfaces to produces traces and other telemetry data. Following is a basic example.
+Requiring `opentelemetry-metrics-sdk` defines the global `OpenTelemetry.meter_provider` accessor. Requiring `opentelemetry-metrics-api` on its own does not. See [Upgrading to 0.9.0](#upgrading-to-090).
+
+Then, use the OpenTelemetry interfaces to produce metrics and other telemetry data. Following is a basic example.
 
 ```ruby
-require 'opentelemetry-metrics-api'
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+
+OpenTelemetry::SDK.configure
 
 # Obtain the current default meter provider
 provider = OpenTelemetry.meter_provider
@@ -50,6 +56,20 @@ histogram.record(123, attributes: {'foo' => 'bar'})
 
 For additional examples, see the [examples on github][examples-github].
 
+## Upgrading to 0.9.0
+
+The Metrics API is experimental. To keep it off the public `OpenTelemetry` module until it stabilizes, `opentelemetry-metrics-api` 0.9.0 no longer defines `OpenTelemetry.meter_provider` or `OpenTelemetry.meter_provider=`. `opentelemetry-metrics-sdk` 0.20.0 and later define both when required.
+
+- **Applications using `opentelemetry-metrics-sdk`:** Upgrade the SDK to 0.20.0 or later. No code changes are needed.
+- **Code that requires only `opentelemetry-metrics-api`:** Calling `OpenTelemetry.meter_provider` raises `NoMethodError`. Require `opentelemetry-metrics-sdk`, or `opentelemetry/metrics/global` to define the accessors without the SDK.
+- **Applications on `opentelemetry-metrics-sdk` 0.19.0 or earlier:** These versions allow `opentelemetry-metrics-api` 0.9.0, so bundler can pair them. A compatibility shim in the API keeps them working and logs this warning:
+
+  ```text
+  opentelemetry-metrics-sdk 0.19.0 and earlier register the global meter provider through a compatibility shim in opentelemetry-metrics-api. Upgrade to opentelemetry-metrics-sdk 0.20.0 or later.
+  ```
+
+  The shim will be removed in a future release ([#2414][2414]). Upgrade the SDK to clear the warning.
+
 ## How can I get involved?
 
 The `opentelemetry-metrics-api` gem source is [on github][repo-github], along with related gems including `opentelemetry-metrics-sdk`.
@@ -76,3 +96,4 @@ The `opentelemetry-api` gem is distributed under the Apache 2.0 license. See [LI
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
 [1662]: https://github.com/open-telemetry/opentelemetry-ruby/issues/1662
+[2414]: https://github.com/open-telemetry/opentelemetry-ruby/issues/2414

data/lib/opentelemetry/internal/global_meter_provider.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # @api private
+  module Internal
+    @meter_provider = ProxyMeterProvider.new
+    @meter_provider_mutex = Mutex.new
+
+    class << self
+      # Registers the process-wide meter provider that instrumentation reads
+      # from. The public +OpenTelemetry.meter_provider+ accessor, defined in
+      # +opentelemetry/metrics/global+, delegates here.
+      #
+      # @param [MeterProvider] provider A meter provider to register as the
+      #   global instance.
+      def meter_provider=(provider)
+        @meter_provider_mutex.synchronize do
+          if @meter_provider.instance_of?(ProxyMeterProvider)
+            OpenTelemetry.logger.debug("Upgrading default proxy meter provider to #{provider.class}")
+            @meter_provider.delegate = provider
+          end
+          @meter_provider = provider
+        end
+      end
+
+      # @return [Object, Metrics::MeterProvider] registered meter provider or a
+      #   default no-op implementation of the meter provider.
+      def meter_provider
+        @meter_provider_mutex.synchronize { @meter_provider }
+      end
+    end
+  end
+end

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/global.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry-metrics-api'
+
+# Defines the top-level accessors for the global meter provider. The Metrics
+# API is unstable, so requiring +opentelemetry-metrics-api+ does not define
+# these. Requiring +opentelemetry-metrics-sdk+ does.
+#
+# These are delegators. The provider itself lives in
+# {OpenTelemetry::Internal}, so this file can be required at any point,
+# before or after the SDK is configured.
+module OpenTelemetry
+  # Register the global meter provider.
+  #
+  # @param [MeterProvider] provider A meter provider to register as the
+  #   global instance.
+  def meter_provider=(provider)
+    Internal.meter_provider = provider
+  end
+
+  # @return [Object, Metrics::MeterProvider] registered meter provider or a
+  #   default no-op implementation of the meter provider.
+  def meter_provider
+    Internal.meter_provider
+  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/legacy_global_compat.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Installs the top-level meter provider accessors on behalf of metrics SDKs
+# released before those accessors moved out of this gem. Those versions assign
+# and read +OpenTelemetry.meter_provider+ while configuring and after forking,
+# and have no way to require +opentelemetry/metrics/global+ themselves.
+#
+# Such an SDK is always loaded by the time it reaches for the accessor, so the
+# check cannot happen at require time. It happens on the miss instead.
+#
+# Removal is tracked in #2414.
+module OpenTelemetry
+  module Metrics
+    # Detects a metrics SDK that predates {OpenTelemetry::Metrics::Global} and
+    # installs the accessors it expects. With no SDK loaded, +super+ raises
+    # NoMethodError, which is what a caller holding only the API is meant to
+    # get.
+    #
+    # @api private
+    module LegacyGlobalCompat
+      ACCESSORS = %i[meter_provider meter_provider=].freeze
+
+      WARNING = 'opentelemetry-metrics-sdk 0.19.0 and earlier register the global meter ' \
+                'provider through a compatibility shim in opentelemetry-metrics-api. ' \
+                'Upgrade to opentelemetry-metrics-sdk 0.20.0 or later.'
+
+      # Keyed on MeterProvider rather than the SDK's Metrics namespace, which
+      # another gem could plausibly define without the SDK being present.
+      def self.handles?(name)
+        ACCESSORS.include?(name) && defined?(OpenTelemetry::SDK::Metrics::MeterProvider)
+      end
+
+      private
+
+      def method_missing(name, *, &)
+        return super unless LegacyGlobalCompat.handles?(name)
+
+        require 'opentelemetry/metrics/global'
+        return super unless singleton_class.method_defined?(name)
+
+        OpenTelemetry.logger.warn(WARNING)
+        public_send(name, *, &)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        LegacyGlobalCompat.handles?(name) || super
+      end
+    end
+  end
+
+  singleton_class.prepend(Metrics::LegacyGlobalCompat)
+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.9.0'
   end
 end

data/lib/opentelemetry-metrics-api.rb

@@ -10,32 +10,12 @@ require 'opentelemetry/metrics/version'
 require 'opentelemetry/internal/proxy_instrument'
 require 'opentelemetry/internal/proxy_meter_provider'
 require 'opentelemetry/internal/proxy_meter'
+require 'opentelemetry/internal/global_meter_provider'
+require 'opentelemetry/metrics/legacy_global_compat'
 
 # OpenTelemetry is an open source observability framework, providing a
 # general-purpose API, SDK, and related tools required for the instrumentation
 # of cloud-native software, frameworks, and libraries.
 #
-# The OpenTelemetry module provides global accessors for telemetry objects.
-module OpenTelemetry
-  @meter_provider = Internal::ProxyMeterProvider.new
-
-  # Register the global meter provider.
-  #
-  # @param [MeterProvider] provider A meter provider to register as the
-  #   global instance.
-  def meter_provider=(provider)
-    @mutex.synchronize do
-      if @meter_provider.instance_of? Internal::ProxyMeterProvider
-        logger.debug("Upgrading default proxy meter provider to #{provider.class}")
-        @meter_provider.delegate = provider
-      end
-      @meter_provider = provider
-    end
-  end
-
-  # @return [Object, Metrics::MeterProvider] registered meter provider or a
-  #   default no-op implementation of the meter provider.
-  def meter_provider
-    @mutex.synchronize { @meter_provider }
-  end
-end
+# Requiring this gem makes the Metrics API available to instrumentation through
+# {OpenTelemetry::Internal.meter_provider}.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-metrics-api
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.9.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
@@ -34,10 +34,12 @@ files:
 - LICENSE
 - README.md
 - lib/opentelemetry-metrics-api.rb
+- lib/opentelemetry/internal/global_meter_provider.rb
 - lib/opentelemetry/internal/proxy_instrument.rb
 - lib/opentelemetry/internal/proxy_meter.rb
 - lib/opentelemetry/internal/proxy_meter_provider.rb
 - lib/opentelemetry/metrics.rb
+- lib/opentelemetry/metrics/global.rb
 - lib/opentelemetry/metrics/instrument.rb
 - lib/opentelemetry/metrics/instrument/counter.rb
 - lib/opentelemetry/metrics/instrument/gauge.rb
@@ -46,6 +48,7 @@ files:
 - lib/opentelemetry/metrics/instrument/observable_gauge.rb
 - lib/opentelemetry/metrics/instrument/observable_up_down_counter.rb
 - lib/opentelemetry/metrics/instrument/up_down_counter.rb
+- lib/opentelemetry/metrics/legacy_global_compat.rb
 - lib/opentelemetry/metrics/measurement.rb
 - lib/opentelemetry/metrics/meter.rb
 - lib/opentelemetry/metrics/meter_provider.rb
@@ -54,10 +57,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.9.0/file/CHANGELOG.md
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-api/v0.9.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.9.0
 rdoc_options: []
 require_paths:
 - lib
@@ -72,7 +75,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: []