opentelemetry-metrics-api 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdddbd715c197f54333fb8d8938d5342e9c6040048de12aa58e97416110f21b1
-  data.tar.gz: 8a70192047000b96d310c481e8fea2346f1af280400c49726856cb2d5df1eeb8
+  metadata.gz: '035779447efea7942cbd75c69833e5bf98e405c79feb87fee1bbc95c33b25446'
+  data.tar.gz: 5de788278de6a22c06316ea2af2c36d2ea4c7eb071dc6c7c207c31729ac77ec0
 SHA512:
-  metadata.gz: 74d6673bf1c5d7d0e84c997be486ba8d62f2082b60a60ecc5e53780ca67a29364caff82d93445ac85da0c7014e88ed77a7c477b282017ffa2ae88453265bdb30
-  data.tar.gz: 4e77afb89660407b222599ad3aade9c4427687b7e5d825da5e50f9797119bbef2a0e60dbdfc911c9481bb5a2eb75350f5fabd1fabf7c1b2fb261ca36c92759c0
+  metadata.gz: cdc4348854acf2433a651c6199232d15cd64fb705bdde5254cdf7ee535a574a35621a7aae15814d2e39abbe7b7e468ed99718c5f05350a54d28934eb59e96582
+  data.tar.gz: 12cb89591164ccedc1e6a730b0c89f8bd8f84d9851bb06d86931eb9b840973b4e7747227e08d39613b325612d44d6b5974d2e29fcc242bfb180de3513a57aee2

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History: opentelemetry-metrics-api
 
+### v0.10.0 / 2026-10-13
+
+* ADDED: Fix duplicate instrument registration warning (#2417)
+
+### 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)

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_meter.rb

@@ -19,6 +19,9 @@ module OpenTelemetry
       def initialize
         super
         @delegate = nil
+        # Every placeholder created before the delegate is set, including repeated and
+        # conflicting registrations of the same name, so that each one gets upgraded.
+        @proxy_instruments = []
       end
 
       # Set the delegate Meter. If this is called more than once, a warning will
@@ -29,7 +32,8 @@ module OpenTelemetry
         @mutex.synchronize do
           if @delegate.nil?
             @delegate = meter
-            @instrument_registry.each_value { |instrument| instrument.upgrade_with(meter) }
+            @proxy_instruments.each { |instrument| instrument.upgrade_with(meter) }
+            @proxy_instruments.clear
           else
             OpenTelemetry.logger.warn 'Attempt to reset delegate in ProxyMeter ignored.'
           end
@@ -38,9 +42,15 @@ module OpenTelemetry
 
       private
 
+      # Does not call `super`: the base registry keys instruments by name, so a repeated
+      # registration would replace an earlier placeholder that then never gets upgraded.
       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, advisory) if @delegate.nil?
+        @mutex.synchronize do
+          if @delegate.nil?
+            instrument = ProxyInstrument.new(kind, name, unit, description, callback, exemplar_filter, exemplar_reservoir, advisory)
+            @proxy_instruments << instrument
+            next instrument
+          end
 
           case kind
           when :counter then @delegate.create_counter(name, unit: unit, description: description, exemplar_filter: exemplar_filter, exemplar_reservoir: exemplar_reservoir, advisory: advisory)

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/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

@@ -304,8 +304,6 @@ module OpenTelemetry
 
       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
-
           @instrument_registry[name] = yield
         end
       end

data/lib/opentelemetry/metrics/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module Metrics
     ## Current OpenTelemetry metrics version
-    VERSION = '0.8.0'
+    VERSION = '0.10.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.8.0
+  version: 0.10.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.8.0/file/CHANGELOG.md
-  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-api/v0.8.0/metrics_api
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-metrics-api/0.10.0/file/CHANGELOG.md
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-api/v0.10.0/metrics_api
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
-  documentation_uri: https://rubydoc.info/gems/opentelemetry-metrics-api/0.8.0
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-metrics-api/0.10.0
 rdoc_options: []
 require_paths:
 - lib