feat: Rework Meter and MeterProvider API

metrics_api/.rubocop.yml

@@ -3,6 +3,7 @@ AllCops:
 
 Lint/UnusedMethodArgument:
   Enabled: false
+
 Metrics/AbcSize:
   Enabled: false
 Metrics/LineLength:
@@ -15,8 +16,14 @@ Metrics/CyclomaticComplexity:
   Max: 20
 Metrics/ParameterLists:
   Enabled: false
+
+Naming/VariableNumber:
+  Enabled: false
 Naming/FileName:
   Exclude:
     - "lib/opentelemetry-metrics-api.rb"
+
+Style/IfUnlessModifier:
+  Enabled: false
 Style/ModuleFunction:
   Enabled: false

metrics_api/lib/opentelemetry/metrics/instrument.rb

@@ -4,12 +4,15 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+require 'opentelemetry/metrics/instrument/synchronous_instrument'
 require 'opentelemetry/metrics/instrument/counter'
 require 'opentelemetry/metrics/instrument/histogram'
+require 'opentelemetry/metrics/instrument/up_down_counter'
+
+require 'opentelemetry/metrics/instrument/asynchronous_instrument'
 require 'opentelemetry/metrics/instrument/observable_counter'
 require 'opentelemetry/metrics/instrument/observable_gauge'
 require 'opentelemetry/metrics/instrument/observable_up_down_counter'
-require 'opentelemetry/metrics/instrument/up_down_counter'
 
 module OpenTelemetry
   module Metrics

metrics_api/lib/opentelemetry/metrics/instrument/asynchronous_instrument.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Metrics
+    module Instrument
+      # https://opentelemetry.io/docs/reference/specification/metrics/api/#asynchronous-instrument-api
+      class AsynchronousInstrument
+        attr_reader :name, :unit, :description, :callback
+
+        # @api private
+        def initialize(name, unit: nil, description: nil, callback: nil)
+          @name = name
+          @unit = unit || ''
+          @description = description || ''
+          @callback = callback ? Array(callback) : []
+        end
+
+        # @param callback [Proc, Array<Proc>]
+        #   Callback functions should:
+        #   - be reentrant safe;
+        #   - not take an indefinite amount of time;
+        #   - not make duplicate observations (more than one Measurement with the same attributes)
+        #     across all registered callbacks;
+        def register_callback(callback)
+          @callback.concat(Array(callback))
+        end
+
+        # @param callback [Proc, Array<Proc>]
+        #   Callback functions should:
+        #   - be reentrant safe;
+        #   - not take an indefinite amount of time;
+        #   - not make duplicate observations (more than one Measurement with the same attributes)
+        #     across all registered callbacks;
+        def unregister_callback(callback)
+          @callback -= Array(callback)
+        end
+      end
+    end
+  end
+end

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

@@ -8,10 +8,10 @@ module OpenTelemetry
   module Metrics
     module Instrument
       # No-op implementation of Counter.
-      class Counter
+      class Counter < SynchronousInstrument
         # Increment the Counter by a fixed amount.
         #
-        # @param [numeric] increment The increment amount, which MUST be a non-negative numeric value.
+        # @param [Numeric] increment The increment amount, which MUST be a non-negative numeric value.
         # @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

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

@@ -8,10 +8,10 @@ module OpenTelemetry
   module Metrics
     module Instrument
       # No-op implementation of Histogram.
-      class Histogram
+      class Histogram < SynchronousInstrument
         # Updates the statistics with the specified amount.
         #
-        # @param [numeric] amount The amount of the Measurement, which MUST be a non-negative numeric value.
+        # @param [Numeric] amount The amount of the Measurement, which MUST be a non-negative numeric value.
         # @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

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

@@ -8,8 +8,7 @@ module OpenTelemetry
   module Metrics
     module Instrument
       # No-op implementation of ObservableCounter.
-      class ObservableCounter
-        # TODO
+      class ObservableCounter < AsynchronousInstrument
       end
     end
   end

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

@@ -8,8 +8,7 @@ module OpenTelemetry
   module Metrics
     module Instrument
       # No-op implementation of ObservableGauge.
-      class ObservableGauge
-        # TODO
+      class ObservableGauge < AsynchronousInstrument
       end
     end
   end

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

@@ -8,8 +8,7 @@ module OpenTelemetry
   module Metrics
     module Instrument
       # No-op implementation of ObservableUpDownCounter.
-      class ObservableUpDownCounter
-        # TODO
+      class ObservableUpDownCounter < AsynchronousInstrument
       end
     end
   end

metrics_api/lib/opentelemetry/metrics/instrument/synchronous_instrument.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Metrics
+    module Instrument
+      # https://opentelemetry.io/docs/reference/specification/metrics/api/#synchronous-instrument-api
+      class SynchronousInstrument
+        attr_reader :name, :unit, :description
+
+        # @api private
+        def initialize(name, unit: nil, description: nil)
+          @name = name
+          @unit = unit || ''
+          @description = description || ''
+        end
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module OpenTelemetry
   module Metrics
     module Instrument
       # No-op implementation of UpDownCounter.
-      class UpDownCounter
+      class UpDownCounter < SynchronousInstrument
         # Increment or decrement the UpDownCounter by a fixed amount.
         #
         # @param [Numeric] amount The amount to be added, can be positive, negative or zero.

metrics_api/lib/opentelemetry/metrics/meter.rb

@@ -8,71 +8,156 @@ module OpenTelemetry
   module Metrics
     # No-op implementation of Meter.
     class Meter
-      COUNTER = Instrument::Counter.new
-      OBSERVABLE_COUNTER = Instrument::ObservableCounter.new
-      HISTOGRAM = Instrument::Histogram.new
-      OBSERVABLE_GAUGE = Instrument::ObservableGauge.new
-      UP_DOWN_COUNTER = Instrument::UpDownCounter.new
-      OBSERVABLE_UP_DOWN_COUNTER = Instrument::ObservableUpDownCounter.new
+      NOOP_COUNTER                    = Instrument::Counter.new('np-op')
+      NOOP_HISTOGRAM                  = Instrument::Histogram.new('np-op')
+      NOOP_UP_DOWN_COUNTER            = Instrument::UpDownCounter.new('np-op')
+      NOOP_OBSERVABLE_COUNTER         = Instrument::ObservableCounter.new('np-op')
+      NOOP_OBSERVABLE_GAUGE           = Instrument::ObservableGauge.new('np-op')
+      NOOP_OBSERVABLE_UP_DOWN_COUNTER = Instrument::ObservableUpDownCounter.new('np-op')
+
+      private_constant(
+        :NOOP_COUNTER,
+        :NOOP_HISTOGRAM,
+        :NOOP_UP_DOWN_COUNTER,
+        :NOOP_OBSERVABLE_COUNTER,
+        :NOOP_OBSERVABLE_GAUGE,
+        :NOOP_OBSERVABLE_UP_DOWN_COUNTER
+      )
+
+      attr_reader :name, :version, :schema_url, :attributes
+
+      # @api private
+      def initialize(name, version: nil, schema_url: nil, attributes: nil)
+        @name = name
+        @version = version || ''
+        @schema_url = schema_url || ''
+        @attributes = attributes || {}
 
-      NAME_REGEX = /^[a-zA-Z][-.\w]{0,62}$/.freeze
-
-      private_constant(:COUNTER, :OBSERVABLE_COUNTER, :HISTOGRAM, :OBSERVABLE_GAUGE, :UP_DOWN_COUNTER, :OBSERVABLE_UP_DOWN_COUNTER)
-
-      DuplicateInstrumentError = Class.new(OpenTelemetry::Error)
-      InstrumentNameError = Class.new(OpenTelemetry::Error)
-      InstrumentUnitError = Class.new(OpenTelemetry::Error)
-      InstrumentDescriptionError = Class.new(OpenTelemetry::Error)
-
-      def initialize
         @mutex = Mutex.new
         @instrument_registry = {}
       end
 
+      # @param name [String]
+      #   Must conform to the instrument name syntax:
+      #   not nil or empty, case-insensitive ASCII string that matches `/\A[a-z][a-z0-9_.-]{0,62}\z/i`
+      # @param unit [optional String]
+      #   Must conform to the instrument unit rule:
+      #   case-sensitive ASCII string with maximum length of 63 characters
+      # @param description [optional String]
+      #   Must conform to the instrument description rule:
+      #   UTF-8 string but up to 3 bytes per charater with maximum length of 1023 characters
+      #
+      # @return [Instrument::Counter]
       def create_counter(name, unit: nil, description: nil)
-        create_instrument(:counter, name, unit, description, nil) { COUNTER }
+        create_instrument(:counter, name, unit, description, nil) { NOOP_COUNTER }
       end
 
+      # @param name [String]
+      #   Must conform to the instrument name syntax:
+      #   not nil or empty, case-insensitive ASCII string that matches `/\A[a-z][a-z0-9_.-]{0,62}\z/i`
+      # @param unit [optional String]
+      #   Must conform to the instrument unit rule:
+      #   case-sensitive ASCII string with maximum length of 63 characters
+      # @param description [optional String]
+      #   Must conform to the instrument description rule:
+      #   UTF-8 string but up to 3 bytes per charater with maximum length of 1023 characters
+      #
+      # @return [Instrument::Histogram]
       def create_histogram(name, unit: nil, description: nil)
-        create_instrument(:histogram, name, unit, description, nil) { HISTOGRAM }
+        create_instrument(:histogram, name, unit, description, nil) { NOOP_HISTOGRAM }
       end
 
+      # @param name [String]
+      #   Must conform to the instrument name syntax:
+      #   not nil or empty, case-insensitive ASCII string that matches `/\A[a-z][a-z0-9_.-]{0,62}\z/i`
+      # @param unit [optional String]
+      #   Must conform to the instrument unit rule:
+      #   case-sensitive ASCII string with maximum length of 63 characters
+      # @param description [optional String]
+      #   Must conform to the instrument description rule:
+      #   UTF-8 string but up to 3 bytes per charater with maximum length of 1023 characters
+      #
+      # @return [Instrument::UpDownCounter]
       def create_up_down_counter(name, unit: nil, description: nil)
-        create_instrument(:up_down_counter, name, unit, description, nil) { UP_DOWN_COUNTER }
+        create_instrument(:up_down_counter, name, unit, description, nil) { NOOP_UP_DOWN_COUNTER }
       end
 
-      def create_observable_counter(name, unit: nil, description: nil, callback:)
-        create_instrument(:observable_counter, name, unit, description, callback) { OBSERVABLE_COUNTER }
+      # @param name [String]
+      #   Must conform to the instrument name syntax:
+      #   not nil or empty, case-insensitive ASCII string that matches `/\A[a-z][a-z0-9_.-]{0,62}\z/i`
+      # @param unit [optional String]
+      #   Must conform to the instrument unit rule:
+      #   case-sensitive ASCII string with maximum length of 63 characters
+      # @param description [optional String]
+      #   Must conform to the instrument description rule:
+      #   UTF-8 string but up to 3 bytes per charater with maximum length of 1023 characters
+      # @param callback [optional Proc, Array<Proc>]
+      #   Callback functions should:
+      #   - be reentrant safe;
+      #   - not take an indefinite amount of time;
+      #   - not make duplicate observations (more than one Measurement with the same attributes)
+      #     across all registered callbacks;
+      #
+      # @return [Instrument::ObservableCounter]
+      def create_observable_counter(name, unit: nil, description: nil, callback: nil)
+        create_instrument(:observable_counter, name, unit, description, callback) { NOOP_OBSERVABLE_COUNTER }
       end
 
-      def create_observable_gauge(name, unit: nil, description: nil, callback:)
-        create_instrument(:observable_gauge, name, unit, description, callback) { OBSERVABLE_GAUGE }
+      # @param name [String]
+      #   Must conform to the instrument name syntax:
+      #   not nil or empty, case-insensitive ASCII string that matches `/\A[a-z][a-z0-9_.-]{0,62}\z/i`
+      # @param unit [optional String]
+      #   Must conform to the instrument unit rule:
+      #   case-sensitive ASCII string with maximum length of 63 characters
+      # @param description [optional String]
+      #   Must conform to the instrument description rule:
+      #   UTF-8 string but up to 3 bytes per charater with maximum length of 1023 characters
+      # @param callback [optional Proc, Array<Proc>]
+      #   Callback functions should:
+      #   - be reentrant safe;
+      #   - not take an indefinite amount of time;
+      #   - not make duplicate observations (more than one Measurement with the same attributes)
+      #     across all registered callbacks;
+      #
+      # @return [Instrument::ObservableGauge]
+      def create_observable_gauge(name, unit: nil, description: nil, callback: nil)
+        create_instrument(:observable_gauge, name, unit, description, callback) { NOOP_OBSERVABLE_GAUGE }
       end
 
-      def create_observable_up_down_counter(name, unit: nil, description: nil, callback:)
-        create_instrument(:observable_up_down_counter, name, unit, description, callback) { OBSERVABLE_UP_DOWN_COUNTER }
+      # @param name [String]
+      #   Must conform to the instrument name syntax:
+      #   not nil or empty, case-insensitive ASCII string that matches `/\A[a-z][a-z0-9_.-]{0,62}\z/i`
+      # @param unit [optional String]
+      #   Must conform to the instrument unit rule:
+      #   case-sensitive ASCII string with maximum length of 63 characters
+      # @param description [optional String]
+      #   Must conform to the instrument description rule:
+      #   UTF-8 string but up to 3 bytes per charater with maximum length of 1023 characters
+      # @param callback [optional Proc, Array<Proc>]
+      #   Callback functions should:
+      #   - be reentrant safe;
+      #   - not take an indefinite amount of time;
+      #   - not make duplicate observations (more than one Measurement with the same attributes)
+      #     across all registered callbacks;
+      #
+      # @return [Instrument::ObservableUpDownCounter]
+      def create_observable_up_down_counter(name, unit: nil, description: nil, callback: nil)
+        create_instrument(:observable_up_down_counter, name, unit, description, callback) { NOOP_OBSERVABLE_UP_DOWN_COUNTER }
       end
 
       private
 
       def create_instrument(kind, name, unit, description, callback)
-        raise InstrumentNameError if name.nil?
-        raise InstrumentNameError if name.empty?
-        raise InstrumentNameError unless NAME_REGEX.match?(name)
-        raise InstrumentUnitError if unit && (!unit.ascii_only? || unit.size > 63)
-        raise InstrumentDescriptionError if description && (description.size > 1023 || !utf8mb3_encoding?(description.dup))
+        name = name.downcase
 
         @mutex.synchronize do
-          OpenTelemetry.logger.warn("duplicate instrument registration occurred for instrument #{name}") if @instrument_registry.include? name
+          if @instrument_registry.include?(name)
+            OpenTelemetry.logger.warn("duplicate instrument registration occurred for #{name}")
+          end
 
           @instrument_registry[name] = yield
         end
       end
-
-      def utf8mb3_encoding?(string)
-        string.force_encoding('UTF-8').valid_encoding? &&
-          string.each_char { |c| return false if c.bytesize >= 4 }
-      end
     end
   end
 end