opentelemetry-metrics-sdk 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f7970de692f93abe5d321c766ddfe2d29d85ba06a64a8e4daeac9e50a55bf42
-  data.tar.gz: 5e147f09a61be36cde37d184a0e2692b949de74c5e0cdd9dae772ed9f40b727a
+  metadata.gz: 85882c7aaf7937f0442c130f4d350cf4b94a47e69b90022010ad09a66d5b4e50
+  data.tar.gz: 04a4e258be416b2a66bbd27a1caa64bfce75cd411a1fad90ecbc757dc3a86c06
 SHA512:
-  metadata.gz: 80cb6c3b9c149bb5d2dfe4d4c3866af45121324490f9b534d63702340ed3ba4eb3bef209e6f559c73a338c11c7e4082344cf49281c3461b06dc55abc168951ee
-  data.tar.gz: 887d608e30a72332f13a8181c3fbff0444b403d8badefdea8b51797b393d1e5952a37ffcef1d4038bbd17fe6b4d433b9c1e62ae3de6626c17bb13351c3342dc1
+  metadata.gz: acd461eca177defb59f52887c77a1e2e4f65b1318da5de8f30c64e2afd7e7358d1316df4c86232e1d8178dc7f88548648e7cc9f25c2d52adadc869edc8f9feb6
+  data.tar.gz: a31db4511b453827cc0059884a0fd59b5767ed78db562e3d3b5e048960c0283164658a5054a9f398ef48cac9e245dfd9697da55d1d9155b8de60847f5e798f20

data/CHANGELOG.md

@@ -1,24 +1,33 @@
 # Release History: opentelemetry-metrics-sdk
 
+### v0.8.0 / 2025-08-14
+
+- BREAKING CHANGE: Update default aggregation temporality for counter, histogram, and up down counter to cumulative
+
+- ADDED: Support asynchronous instruments: ObservableGauge, ObservableCounter and ObservableUpDownCounter
+- FIXED: Validate scale range on exponential histograms and raise exception if out of bounds
+- FIXED: Update max instrument name length from 63 to 255 characters and allow `/` in instrument names
+- FIXED: Validate scale range and raise exception if out of bounds for exponential histograms
+
 ### v0.7.3 / 2025-07-09
 
-* FIXED: Stop exporting metrics with empty data points
+- FIXED: Stop exporting metrics with empty data points
 
 ### v0.7.2 / 2025-07-03
 
-* FIXED: Coerce aggregation temporality to be a symbol for exponential histograms
+- FIXED: Coerce aggregation temporality to be a symbol for exponential histograms
 
 ### v0.7.1 / 2025-05-28
 
-* FIXED: Recover periodic metric readers after forking
+- FIXED: Recover periodic metric readers after forking
 
 ### v0.7.0 / 2025-05-13
 
-* ADDED: Add basic exponential histogram
+- ADDED: Add basic exponential histogram
 
 ### v0.6.1 / 2025-04-09
 
-* FIXED: Use condition signal to replace sleep and remove timeout.timeout…
+- FIXED: Use condition signal to replace sleep and remove timeout.timeout…
 
 ### v0.6.0 / 2025-02-25
 

data/lib/opentelemetry/sdk/metrics/aggregation/aggregation_temporality.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Metrics
+      module Aggregation
+        # AggregationTemporality represents the temporality of
+        # data point ({NumberDataPoint} and {HistogramDataPoint}) in {Metrics}.
+        # It determine whether the data point will be cleared for each metrics pull/export.
+        class AggregationTemporality
+          class << self
+            private :new
+
+            # Returns a newly created {AggregationTemporality} with temporality == DELTA
+            #
+            # @return [AggregationTemporality]
+            def delta
+              new(DELTA)
+            end
+
+            # Returns a newly created {AggregationTemporality} with temporality == CUMULATIVE
+            #
+            # @return [AggregationTemporality]
+            def cumulative
+              new(CUMULATIVE)
+            end
+          end
+
+          attr_reader :temporality
+
+          # @api private
+          # The constructor is private and only for use internally by the class.
+          # Users should use the {delta} and {cumulative} factory methods to obtain
+          # a {AggregationTemporality} instance.
+          #
+          # @param [Integer] temporality One of the status codes below
+          def initialize(temporality)
+            @temporality = temporality
+          end
+
+          def delta?
+            @temporality == :delta
+          end
+
+          def cumulative?
+            @temporality == :cumulative
+          end
+
+          # delta: data point will be cleared after each metrics pull/export.
+          DELTA = :delta
+
+          # cumulative: data point will NOT be cleared after metrics pull/export.
+          CUMULATIVE = :cumulative
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/metrics/aggregation/drop.rb

@@ -10,10 +10,8 @@ module OpenTelemetry
       module Aggregation
         # Contains the implementation of the Drop aggregation
         class Drop
-          attr_reader :aggregation_temporality
-
-          def initialize(aggregation_temporality: :delta)
-            @aggregation_temporality = aggregation_temporality
+          def initialize
+            @aggregation_temporality = nil
           end
 
           def collect(start_time, end_time, data_points)
@@ -30,6 +28,10 @@ module OpenTelemetry
             )
             nil
           end
+
+          def aggregation_temporality
+            nil
+          end
         end
       end
     end

data/lib/opentelemetry/sdk/metrics/aggregation/explicit_bucket_histogram.rb

@@ -14,24 +14,22 @@ module OpenTelemetry
           DEFAULT_BOUNDARIES = [0, 5, 10, 25, 50, 75, 100, 250, 500, 1000].freeze
           private_constant :DEFAULT_BOUNDARIES
 
-          attr_reader :aggregation_temporality
-
           # The default value for boundaries represents the following buckets:
           # (-inf, 0], (0, 5.0], (5.0, 10.0], (10.0, 25.0], (25.0, 50.0],
           # (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0],
           # (500.0, 1000.0], (1000.0, +inf)
           def initialize(
-            aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :delta), # TODO: the default should be :cumulative, see issue #1555
+            aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :cumulative),
             boundaries: DEFAULT_BOUNDARIES,
             record_min_max: true
           )
-            @aggregation_temporality = aggregation_temporality.to_sym
+            @aggregation_temporality = aggregation_temporality.to_sym == :delta ? AggregationTemporality.delta : AggregationTemporality.cumulative
             @boundaries = boundaries && !boundaries.empty? ? boundaries.sort : nil
             @record_min_max = record_min_max
           end
 
           def collect(start_time, end_time, data_points)
-            if @aggregation_temporality == :delta
+            if @aggregation_temporality.delta?
               # Set timestamps and 'move' data point values to result.
               hdps = data_points.values.map! do |hdp|
                 hdp.start_time_unix_nano = start_time
@@ -87,6 +85,10 @@ module OpenTelemetry
             nil
           end
 
+          def aggregation_temporality
+            @aggregation_temporality.temporality
+          end
+
           private
 
           def empty_bucket_counts

data/lib/opentelemetry/sdk/metrics/aggregation/exponential_bucket_histogram.rb

@@ -19,15 +19,18 @@ module OpenTelemetry
           attr_reader :aggregation_temporality
 
           # relate to min max scale: https://opentelemetry.io/docs/specs/otel/metrics/sdk/#support-a-minimum-and-maximum-scale
+          DEFAULT_SIZE  = 160
+          DEFAULT_SCALE = 20
           MAX_SCALE = 20
           MIN_SCALE = -10
-          MAX_SIZE  = 160
+          MIN_MAX_SIZE = 2
+          MAX_MAX_SIZE = 16_384
 
           # The default boundaries are calculated based on default max_size and max_scale values
           def initialize(
             aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :delta),
-            max_size: MAX_SIZE,
-            max_scale: MAX_SCALE,
+            max_size: DEFAULT_SIZE,
+            max_scale: DEFAULT_SCALE,
             record_min_max: true,
             zero_threshold: 0
           )
@@ -175,6 +178,7 @@ module OpenTelemetry
           end
 
           def new_mapping(scale)
+            scale = validate_scale(scale)
             scale <= 0 ? ExponentialHistogram::ExponentMapping.new(scale) : ExponentialHistogram::LogarithmMapping.new(scale)
           end
 
@@ -203,17 +207,17 @@ module OpenTelemetry
           end
 
           def validate_scale(scale)
-            return scale unless scale > MAX_SCALE || scale < MIN_SCALE
+            raise ArgumentError, "Scale #{scale} is larger than maximum scale #{MAX_SCALE}" if scale > MAX_SCALE
+            raise ArgumentError, "Scale #{scale} is smaller than minimum scale #{MIN_SCALE}" if scale < MIN_SCALE
 
-            OpenTelemetry.logger.warn "Scale #{scale} is invalid, using default max scale #{MAX_SCALE}"
-            MAX_SCALE
+            scale
           end
 
           def validate_size(size)
-            return size unless size > MAX_SIZE || size < 0
+            raise ArgumentError, "Max size #{size} is smaller than minimum size #{MIN_MAX_SIZE}" if size < MIN_MAX_SIZE
+            raise ArgumentError, "Max size #{size} is larger than maximum size #{MAX_MAX_SIZE}" if size > MAX_MAX_SIZE
 
-            OpenTelemetry.logger.warn "Size #{size} is invalid, using default max size #{MAX_SIZE}"
-            MAX_SIZE
+            size
           end
         end
       end

data/lib/opentelemetry/sdk/metrics/aggregation/last_value.rb

@@ -10,14 +10,12 @@ module OpenTelemetry
       module Aggregation
         # Contains the implementation of the LastValue aggregation
         class LastValue
-          attr_reader :aggregation_temporality
-
           def initialize(aggregation_temporality: :delta)
-            @aggregation_temporality = aggregation_temporality
+            @aggregation_temporality = aggregation_temporality == :cumulative ? AggregationTemporality.cumulative : AggregationTemporality.delta
           end
 
           def collect(start_time, end_time, data_points)
-            if @aggregation_temporality == :delta
+            if @aggregation_temporality.delta?
               # Set timestamps and 'move' data point values to result.
               ndps = data_points.values.map! do |ndp|
                 ndp.start_time_unix_nano = start_time
@@ -46,6 +44,10 @@ module OpenTelemetry
             )
             nil
           end
+
+          def aggregation_temporality
+            @aggregation_temporality.temporality
+          end
         end
       end
     end

data/lib/opentelemetry/sdk/metrics/aggregation/sum.rb

@@ -11,16 +11,13 @@ module OpenTelemetry
         # Contains the implementation of the Sum aggregation
         # https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#sum-aggregation
         class Sum
-          attr_reader :aggregation_temporality
-
-          def initialize(aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :delta), monotonic: false)
-            # TODO: the default should be :cumulative, see issue #1555
-            @aggregation_temporality = aggregation_temporality.to_sym
+          def initialize(aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :cumulative), monotonic: false)
+            @aggregation_temporality = aggregation_temporality.to_sym == :delta ? AggregationTemporality.delta : AggregationTemporality.cumulative
             @monotonic = monotonic
           end
 
           def collect(start_time, end_time, data_points)
-            if @aggregation_temporality == :delta
+            if @aggregation_temporality.delta?
               # Set timestamps and 'move' data point values to result.
               ndps = data_points.values.map! do |ndp|
                 ndp.start_time_unix_nano = start_time
@@ -57,6 +54,10 @@ module OpenTelemetry
             ndp.value += increment
             nil
           end
+
+          def aggregation_temporality
+            @aggregation_temporality.temporality
+          end
         end
       end
     end

data/lib/opentelemetry/sdk/metrics/aggregation.rb

@@ -15,6 +15,7 @@ module OpenTelemetry
   end
 end
 
+require 'opentelemetry/sdk/metrics/aggregation/aggregation_temporality'
 require 'opentelemetry/sdk/metrics/aggregation/number_data_point'
 require 'opentelemetry/sdk/metrics/aggregation/histogram_data_point'
 require 'opentelemetry/sdk/metrics/aggregation/explicit_bucket_histogram'

data/lib/opentelemetry/sdk/metrics/instrument/asynchronous_instrument.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Metrics
+      module Instrument
+        # {AsynchronousInstrument} contains the common functionality shared across
+        # the asynchronous instruments SDK instruments.
+        class AsynchronousInstrument
+          def initialize(name, unit, description, callback, instrumentation_scope, meter_provider)
+            @name = name
+            @unit = unit
+            @description = description
+            @instrumentation_scope = instrumentation_scope
+            @meter_provider = meter_provider
+            @metric_streams = []
+            @callbacks = []
+            @timeout   = nil
+            @attributes = {}
+
+            init_callback(callback)
+            meter_provider.register_asynchronous_instrument(self)
+          end
+
+          # @api private
+          def register_with_new_metric_store(metric_store, aggregation: default_aggregation)
+            ms = OpenTelemetry::SDK::Metrics::State::AsynchronousMetricStream.new(
+              @name,
+              @description,
+              @unit,
+              instrument_kind,
+              @meter_provider,
+              @instrumentation_scope,
+              aggregation,
+              @callbacks,
+              @timeout,
+              @attributes
+            )
+            @metric_streams << ms
+            metric_store.add_metric_stream(ms)
+          end
+
+          # The API MUST support creation of asynchronous instruments by passing zero or more callback functions
+          # to be permanently registered to the newly created instrument.
+          def init_callback(callback)
+            if callback.instance_of?(Proc)
+              @callbacks << callback
+            elsif callback.instance_of?(Array)
+              callback.each { |cb| @callbacks << cb if cb.instance_of?(Proc) }
+            else
+              OpenTelemetry.logger.warn "Only accept single Proc or Array of Proc for initialization with callback (given callback #{callback.class}"
+            end
+          end
+
+          # Where the API supports registration of callback functions after asynchronous instrumentation creation,
+          # the user MUST be able to undo registration of the specific callback after its registration by some means.
+          def register_callback(callback)
+            if callback.instance_of?(Proc)
+              @callbacks << callback
+              callback
+            else
+              OpenTelemetry.logger.warn "Only accept single Proc for registering callback (given callback #{callback.class}"
+            end
+          end
+
+          def unregister(callback)
+            @callbacks.delete(callback)
+          end
+
+          def timeout(timeout)
+            @timeout = timeout
+          end
+
+          def add_attributes(attributes)
+            @attributes.merge!(attributes) if attributes.instance_of?(Hash)
+          end
+
+          private
+
+          # update the observed value (after calling observe)
+          # invoke callback will execute callback and export metric_data that is observed
+          def update(timeout, attributes)
+            @metric_streams.each { |ms| ms.invoke_callback(timeout, attributes) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,16 +8,31 @@ module OpenTelemetry
   module SDK
     module Metrics
       module Instrument
-        # {ObservableCounter} is the SDK implementation of {OpenTelemetry::Metrics::ObservableCounter}.
-        class ObservableCounter < OpenTelemetry::Metrics::Instrument::ObservableCounter
-          attr_reader :name, :unit, :description
+        # {ObservableCounter} is the SDK implementation of {OpenTelemetry::SDK::Metrics::Instrument::AsynchronousInstrument}.
+        # Asynchronous Counter is an asynchronous Instrument which reports monotonically increasing value(s) when the instrument is being observed.
+        class ObservableCounter < OpenTelemetry::SDK::Metrics::Instrument::AsynchronousInstrument
+          # Returns the instrument kind as a Symbol
+          #
+          # @return [Symbol]
+          def instrument_kind
+            :observable_counter
+          end
+
+          # Observe the ObservableCounter with fixed timeout duration.
+          #
+          # @param [int] timeout The timeout duration for callback to run, 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
+          #   the same basic type (string, numeric, boolean).
+          def observe(timeout: nil, attributes: {})
+            update(timeout, attributes)
+          end
+
+          private
 
-          def initialize(name, unit, description, callback, meter)
-            @name = name
-            @unit = unit
-            @description = description
-            @callback = callback
-            @meter = meter
+          def default_aggregation
+            OpenTelemetry::SDK::Metrics::Aggregation::Sum.new(monotonic: true)
           end
         end
       end

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

@@ -8,16 +8,31 @@ module OpenTelemetry
   module SDK
     module Metrics
       module Instrument
-        # {ObservableGauge} is the SDK implementation of {OpenTelemetry::Metrics::ObservableGauge}.
-        class ObservableGauge < OpenTelemetry::Metrics::Instrument::ObservableGauge
-          attr_reader :name, :unit, :description
+        # {ObservableGauge} is the SDK implementation of {OpenTelemetry::SDK::Metrics::Instrument::AsynchronousInstrument}.
+        # Asynchronous Gauge is an asynchronous Instrument which reports non-additive value(s) (e.g. the room temperature)
+        class ObservableGauge < OpenTelemetry::SDK::Metrics::Instrument::AsynchronousInstrument
+          # Returns the instrument kind as a Symbol
+          #
+          # @return [Symbol]
+          def instrument_kind
+            :observable_gauge
+          end
+
+          # Observe the Gauge with fixed timeout duration.
+          #
+          # @param [int] timeout The timeout duration for callback to run, 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
+          #   the same basic type (string, numeric, boolean).
+          def observe(timeout: nil, attributes: {})
+            update(timeout, attributes)
+          end
+
+          private
 
-          def initialize(name, unit, description, callback, meter)
-            @name = name
-            @unit = unit
-            @description = description
-            @callback = callback
-            @meter = meter
+          def default_aggregation
+            OpenTelemetry::SDK::Metrics::Aggregation::LastValue.new
           end
         end
       end

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

@@ -8,16 +8,31 @@ module OpenTelemetry
   module SDK
     module Metrics
       module Instrument
-        # {ObservableUpDownCounter} is the SDK implementation of {OpenTelemetry::Metrics::ObservableUpDownCounter}.
-        class ObservableUpDownCounter < OpenTelemetry::Metrics::Instrument::ObservableUpDownCounter
-          attr_reader :name, :unit, :description
+        # {ObservableUpDownCounter} is the SDK implementation of {OpenTelemetry::SDK::Metrics::Instrument::AsynchronousInstrument}.
+        # Asynchronous UpDownCounter is an asynchronous Instrument which reports additive value(s) (e.g. the process heap size)
+        class ObservableUpDownCounter < OpenTelemetry::SDK::Metrics::Instrument::AsynchronousInstrument
+          # Returns the instrument kind as a Symbol
+          #
+          # @return [Symbol]
+          def instrument_kind
+            :observable_up_down_counter
+          end
+
+          # Observe the UpDownCounter with fixed timeout duration.
+          #
+          # @param [int] timeout The timeout duration for callback to run, 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
+          #   the same basic type (string, numeric, boolean).
+          def observe(timeout: nil, attributes: {})
+            update(timeout, attributes)
+          end
+
+          private
 
-          def initialize(name, unit, description, callback, meter)
-            @name = name
-            @unit = unit
-            @description = description
-            @callback = callback
-            @meter = meter
+          def default_aggregation
+            OpenTelemetry::SDK::Metrics::Aggregation::Sum.new(aggregation_temporality: :delta, monotonic: false)
           end
         end
       end

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

@@ -14,6 +14,7 @@ module OpenTelemetry
 end
 
 require 'opentelemetry/sdk/metrics/instrument/synchronous_instrument'
+require 'opentelemetry/sdk/metrics/instrument/asynchronous_instrument'
 require 'opentelemetry/sdk/metrics/instrument/counter'
 require 'opentelemetry/sdk/metrics/instrument/histogram'
 require 'opentelemetry/sdk/metrics/instrument/observable_counter'

data/lib/opentelemetry/sdk/metrics/meter.rb

@@ -11,7 +11,7 @@ module OpenTelemetry
     module Metrics
       # {Meter} is the SDK implementation of {OpenTelemetry::Metrics::Meter}.
       class Meter < OpenTelemetry::Metrics::Meter
-        NAME_REGEX = /\A[a-zA-Z][-.\w]{0,62}\z/
+        NAME_REGEX = %r{\A[a-zA-Z][-./\w]{0,254}\z}
 
         # @api private
         #
@@ -28,6 +28,30 @@ module OpenTelemetry
           @meter_provider = meter_provider
         end
 
+        # Multiple-instrument callbacks
+        # Callbacks registered after the time of instrument creation MAY be associated with multiple instruments.
+        # Related spec: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#multiple-instrument-callbacks
+        # Related spec: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#synchronous-instrument-api
+        #
+        # @param [Array] instruments A list (or tuple, etc.) of Instruments used in the callback function.
+        # @param [Proc] callback A callback function
+        #
+        # It is RECOMMENDED that the API authors use one of the following forms for the callback function:
+        # The list (or tuple, etc.) returned by the callback function contains (Instrument, Measurement) pairs.
+        # the Observable Result parameter receives an additional (Instrument, Measurement) pairs
+        # Here it chose the second form
+        def register_callback(instruments, callback)
+          instruments.each do |instrument|
+            instrument.register_callback(callback)
+          end
+        end
+
+        def unregister(instruments, callback)
+          instruments.each do |instrument|
+            instrument.unregister(callback)
+          end
+        end
+
         # @api private
         def add_metric_reader(metric_reader)
           @instrument_registry.each_value do |instrument|

data/lib/opentelemetry/sdk/metrics/meter_provider.rb

@@ -126,6 +126,7 @@ module OpenTelemetry
             end
           end
         end
+        alias register_asynchronous_instrument register_synchronous_instrument
 
         # A View provides SDK users with the flexibility to customize the metrics that are output by the SDK.
         #

data/lib/opentelemetry/sdk/metrics/state/asynchronous_metric_stream.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Metrics
+      module State
+        # @api private
+        #
+        # The AsynchronousMetricStream class provides SDK internal functionality that is not a part of the
+        # public API. It extends MetricStream to support asynchronous instruments.
+        class AsynchronousMetricStream < MetricStream
+          def initialize(
+            name,
+            description,
+            unit,
+            instrument_kind,
+            meter_provider,
+            instrumentation_scope,
+            aggregation,
+            callback,
+            timeout,
+            attributes
+          )
+            # Call parent constructor with common parameters
+            super(name, description, unit, instrument_kind, meter_provider, instrumentation_scope, aggregation)
+
+            # Initialize asynchronous-specific attributes
+            @callback = callback
+            @start_time = now_in_nano
+            @timeout = timeout
+            @attributes = attributes
+          end
+
+          # When collect, if there are asynchronous SDK Instruments involved, their callback functions will be triggered.
+          # Related spec: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#collect
+          # invoke_callback will update the data_points in aggregation
+          def collect(start_time, end_time)
+            invoke_callback(@timeout, @attributes)
+
+            # Call parent collect method for the core collection logic
+            super(start_time, end_time)
+          end
+
+          def invoke_callback(timeout, attributes)
+            if @registered_views.empty?
+              @mutex.synchronize do
+                Timeout.timeout(timeout || 30) do
+                  @callback.each do |cb|
+                    value = cb.call
+                    @default_aggregation.update(value, attributes, @data_points)
+                  end
+                end
+              end
+            else
+              @registered_views.each do |view|
+                @mutex.synchronize do
+                  Timeout.timeout(timeout || 30) do
+                    @callback.each do |cb|
+                      value = cb.call
+                      merged_attributes = attributes || {}
+                      merged_attributes.merge!(view.attribute_keys)
+                      view.aggregation.update(value, merged_attributes, @data_points) if view.valid_aggregation?
+                    end
+                  end
+                end
+              end
+            end
+          end
+
+          def now_in_nano
+            (Time.now.to_r * 1_000_000_000).to_i
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/metrics/state.rb

@@ -20,3 +20,4 @@ end
 require 'opentelemetry/sdk/metrics/state/metric_data'
 require 'opentelemetry/sdk/metrics/state/metric_store'
 require 'opentelemetry/sdk/metrics/state/metric_stream'
+require 'opentelemetry/sdk/metrics/state/asynchronous_metric_stream'

data/lib/opentelemetry/sdk/metrics/version.rb

@@ -8,7 +8,7 @@ module OpenTelemetry
   module SDK
     module Metrics
       # Current OpenTelemetry metrics sdk version
-      VERSION = '0.7.3'
+      VERSION = '0.8.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-metrics-sdk
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-09 00:00:00.000000000 Z
+date: 2025-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -206,6 +206,7 @@ files:
 - lib/opentelemetry-metrics-sdk.rb
 - lib/opentelemetry/sdk/metrics.rb
 - lib/opentelemetry/sdk/metrics/aggregation.rb
+- lib/opentelemetry/sdk/metrics/aggregation/aggregation_temporality.rb
 - lib/opentelemetry/sdk/metrics/aggregation/drop.rb
 - lib/opentelemetry/sdk/metrics/aggregation/explicit_bucket_histogram.rb
 - lib/opentelemetry/sdk/metrics/aggregation/exponential_bucket_histogram.rb
@@ -227,6 +228,7 @@ files:
 - lib/opentelemetry/sdk/metrics/export/periodic_metric_reader.rb
 - lib/opentelemetry/sdk/metrics/fork_hooks.rb
 - lib/opentelemetry/sdk/metrics/instrument.rb
+- lib/opentelemetry/sdk/metrics/instrument/asynchronous_instrument.rb
 - lib/opentelemetry/sdk/metrics/instrument/counter.rb
 - lib/opentelemetry/sdk/metrics/instrument/gauge.rb
 - lib/opentelemetry/sdk/metrics/instrument/histogram.rb
@@ -238,6 +240,7 @@ files:
 - lib/opentelemetry/sdk/metrics/meter.rb
 - lib/opentelemetry/sdk/metrics/meter_provider.rb
 - lib/opentelemetry/sdk/metrics/state.rb
+- lib/opentelemetry/sdk/metrics/state/asynchronous_metric_stream.rb
 - lib/opentelemetry/sdk/metrics/state/metric_data.rb
 - lib/opentelemetry/sdk/metrics/state/metric_store.rb
 - lib/opentelemetry/sdk/metrics/state/metric_stream.rb
@@ -248,10 +251,10 @@ homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-sdk/v0.7.3/file.CHANGELOG.html
+  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-sdk/v0.8.0/file.CHANGELOG.html
   source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/metrics_sdk
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
-  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-sdk/v0.7.3
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-sdk/v0.8.0
 post_install_message:
 rdoc_options: []
 require_paths: