opentelemetry-metrics-sdk 0.13.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7334096b386c7cfbef752c28e4f0e21f10dad2fd6c7d200a6b2ac005199c1aa4
-  data.tar.gz: a885b64ee8021d1c53fcd647c114ae919197d4596aec37c72743f75b20e4e255
+  metadata.gz: fee8234836c749267c8ef70c3a6e1edd1e7f07f2f684be31be5bbb692783bbe5
+  data.tar.gz: d95498e59164701c62e415db1d99d20f201f77a7a9d621667603bdb7485c668c
 SHA512:
-  metadata.gz: 1ec27c0c72f390a2d48c533ba021d714987f5183983e2aa968f0f03e8b07dadc2b63dce78c3b9379d9abfd22737f859745c9c3ce17d38520dfaee1a4dd652d89
-  data.tar.gz: 0c706c3757af11cd8cc65bdc07aea5498f88aabcf1d683f9178502f440cd5dc46a3b86e29a80ca0e21429ad5f4ae5d5412dce3f453b803b9733b51091ea19c4c
+  metadata.gz: 13fc13a8866034bbd502032c7b6aef1fe485591d065cd01d533eec77ed9aa3fc8c3e11def8317b891bda9347317558ea0322bc211c00d46c3ee0cbc3a57c2bce
+  data.tar.gz: 123a2e82d19c865243d45d0e2e29dce12e2c3166813ccdc8ad5e10ea45fb6e31d6d9c54b9558f36c380e8ece670146c9ba1b2450286b03a6ab6c70ec28db0839

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History: opentelemetry-metrics-sdk
 
+### v0.15.0 / 2026-06-16
+
+* BREAKING CHANGE: Metrics cardinality limit (#1909)
+* ADDED: Metrics cardinality limit (#1909)
+
+### v0.14.0 / 2026-05-12
+
+* BREAKING CHANGE: Use trace_based exemplar filter by default (#2112)
+* ADDED: Use trace_based exemplar filter by default (#2112)
+* ADDED: Add git tag to source URI in gemspec (#2101)
+* FIXED: Return false if it is noop_exemplar_reservoir (#2104)
+
 ### v0.13.1 / 2026-04-15
 
 * FIXED: Move the metrics-sdk requires to support "require 'opentelemetry/sdk/metrics'" (#1956)

data/README.md

@@ -39,8 +39,8 @@ At this time, you should be able to:
 * Export metrics on a schedule using `PeriodicMetricReader` with any compatible push exporter (e.g. OTLP via `opentelemetry-exporter-otlp-metrics`)
 * Attach exemplars to metric data points for trace correlation:
   * `AlwaysOnExemplarFilter` — every measurement is eligible
-  * `AlwaysOffExemplarFilter` — no exemplars collected (default)
-  * `TraceBasedExemplarFilter` — only measurements inside a sampled trace
+  * `AlwaysOffExemplarFilter` — no exemplars collected
+  * `TraceBasedExemplarFilter` — only measurements inside a sampled trace (default)
 
 We do not yet have support for:
 
@@ -278,7 +278,7 @@ OpenTelemetry.meter_provider.shutdown
 
 Exemplars attach individual raw measurements — along with the trace context active at the time of the measurement — to an exported metric data point. This lets you jump from a metric spike directly to the trace that caused it.
 
-By default exemplars are **disabled** (`AlwaysOffExemplarFilter`). Enable them via an environment variable or programmatically.
+By default, exemplars use `TraceBasedExemplarFilter`, which records measurements only when they occur inside a sampled trace.
 
 #### Enable via environment variable
 
@@ -289,7 +289,7 @@ export OTEL_METRICS_EXEMPLAR_FILTER=trace_based
 # Eligible for every measurement regardless of trace context
 export OTEL_METRICS_EXEMPLAR_FILTER=always_on
 
-# Disabled (default)
+# Disabled
 export OTEL_METRICS_EXEMPLAR_FILTER=always_off
 ```
 

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

@@ -22,7 +22,7 @@ module OpenTelemetry
             data_points.values.map!(&:dup)
           end
 
-          def update(increment, attributes, data_points, exemplar_offer: false)
+          def update(increment, attributes, data_points, cardinality_limit, exemplar_offer: false)
             data_points[attributes] = NumberDataPoint.new(
               {},
               0,

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

@@ -11,6 +11,7 @@ module OpenTelemetry
         # Contains the implementation of the ExplicitBucketHistogram aggregation
         # https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#explicit-bucket-histogram-aggregation
         class ExplicitBucketHistogram
+          OVERFLOW_ATTRIBUTE_SET = { 'otel.metric.overflow' => true }.freeze
           attr_reader :exemplar_reservoir
 
           DEFAULT_BOUNDARIES = [0, 5, 10, 25, 50, 75, 100, 250, 500, 1000].freeze
@@ -59,41 +60,48 @@ module OpenTelemetry
             end
           end
 
-          def update(amount, attributes, data_points, exemplar_offer: false)
-            hdp = data_points.fetch(attributes) do
-              if @record_min_max
-                min = Float::INFINITY
-                max = -Float::INFINITY
-              end
+          def update(amount, attributes, data_points, cardinality_limit, exemplar_offer: false)
+            hdp = if data_points.key?(attributes)
+                    data_points[attributes]
+                  elsif data_points.size >= cardinality_limit - 1
+                    data_points[OVERFLOW_ATTRIBUTE_SET] || create_new_data_point(OVERFLOW_ATTRIBUTE_SET, data_points)
+                  else
+                    create_new_data_point(attributes, data_points)
+                  end
 
-              data_points[attributes] = HistogramDataPoint.new(
-                attributes,
-                nil,                 # :start_time_unix_nano
-                nil,                 # :time_unix_nano
-                0,                   # :count
-                0,                   # :sum
-                empty_bucket_counts, # :bucket_counts
-                @boundaries,         # :explicit_bounds
-                nil,                 # :exemplars
-                min,                 # :min
-                max                  # :max
-              )
-            end
+            update_histogram_data_point(hdp, amount, exemplar_offer: exemplar_offer)
+            nil
+          end
 
-            reservoir = @exemplar_reservoir_storage[attributes]
-            unless reservoir
-              reservoir = @exemplar_reservoir.dup
-              reservoir.reset
-              @exemplar_reservoir_storage[attributes] = reservoir
-            end
+          def aggregation_temporality
+            @aggregation_temporality.temporality
+          end
 
-            if exemplar_offer
-              reservoir.offer(value: amount,
-                              timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
-                              attributes: attributes,
-                              context: OpenTelemetry::Context.current)
+          private
+
+          def create_new_data_point(attributes, data_points)
+            if @record_min_max
+              min = Float::INFINITY
+              max = -Float::INFINITY
             end
 
+            data_points[attributes] = HistogramDataPoint.new(
+              attributes,
+              nil,                 # :start_time_unix_nano
+              nil,                 # :time_unix_nano
+              0,                   # :count
+              0,                   # :sum
+              empty_bucket_counts, # :bucket_counts
+              @boundaries,         # :explicit_bounds
+              nil,                 # :exemplars
+              min,                 # :min
+              max                  # :max
+            )
+          end
+
+          def update_histogram_data_point(hdp, amount, exemplar_offer: false)
+            reservior_update(hdp.attributes, amount, exemplar_offer)
+
             if @record_min_max
               hdp.max = amount if amount > hdp.max
               hdp.min = amount if amount < hdp.min
@@ -101,18 +109,27 @@ module OpenTelemetry
 
             hdp.sum += amount
             hdp.count += 1
-            if @boundaries
-              bucket_index = @boundaries.bsearch_index { |i| i >= amount } || @boundaries.size
-              hdp.bucket_counts[bucket_index] += 1
-            end
-            nil
-          end
+            return unless @boundaries
 
-          def aggregation_temporality
-            @aggregation_temporality.temporality
+            bucket_index = @boundaries.bsearch_index { |i| i >= amount } || @boundaries.size
+            hdp.bucket_counts[bucket_index] += 1
           end
 
-          private
+          def reservior_update(attributes, amount, exemplar_offer)
+            reservoir = @exemplar_reservoir_storage[attributes]
+            unless reservoir
+              reservoir = @exemplar_reservoir.dup
+              reservoir.reset
+              @exemplar_reservoir_storage[attributes] = reservoir
+            end
+
+            return unless exemplar_offer
+
+            reservoir.offer(value: amount,
+                            timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
+                            attributes: attributes,
+                            context: OpenTelemetry::Context.current)
+          end
 
           def empty_bucket_counts
             @boundaries ? Array.new(@boundaries.size + 1, 0) : nil

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

@@ -17,6 +17,8 @@ module OpenTelemetry
       module Aggregation
         # Contains the implementation of the {https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exponentialhistogram ExponentialBucketHistogram} aggregation
         class ExponentialBucketHistogram # rubocop:disable Metrics/ClassLength
+          OVERFLOW_ATTRIBUTE_SET = { 'otel.metric.overflow' => true }.freeze
+
           # 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
@@ -94,7 +96,6 @@ module OpenTelemetry
 
               # this will slow down the operation especially if large amount of data_points present
               # but it should be fine since with cumulative, the data_points are merged into previous_* and not kept in data_points
-              # rubocop:disable Metrics/BlockLength
               data_points.each do |attributes, hdp|
                 # Store current values
                 current_positive = hdp.positive
@@ -181,7 +182,6 @@ module OpenTelemetry
                 merged_data_points[attributes] = merged_hdp
                 @previous_mappings[attributes] = @mappings[attributes] if @mappings[attributes] # Preserve mapping for next collection
               end
-              # rubocop:enable Metrics/BlockLength
 
               # when you have no local_data_points, the loop from cumulative aggregation will not run
               # so return last merged data points if exists
@@ -221,49 +221,53 @@ module OpenTelemetry
           # rubocop:enable Metrics/MethodLength
 
           # this is aggregate in python; there is no merge in aggregate; but rescale happened
-          # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
-          def update(amount, attributes, data_points, exemplar_offer: false)
-            # fetch or initialize the ExponentialHistogramDataPoint
-            hdp = data_points.fetch(attributes) do
-              if @record_min_max
-                min = Float::INFINITY
-                max = -Float::INFINITY
-              end
+          def update(amount, attributes, data_points, cardinality_limit, exemplar_offer: false)
+            hdp = if data_points.key?(attributes)
+                    data_points[attributes]
+                  elsif data_points.size >= cardinality_limit - 1
+                    data_points[OVERFLOW_ATTRIBUTE_SET] || create_new_data_point(OVERFLOW_ATTRIBUTE_SET, data_points)
+                  else
+                    create_new_data_point(attributes, data_points)
+                  end
+
+            update_histogram_data_point(hdp, attributes, amount, exemplar_offer: exemplar_offer)
+            nil
+          end
 
-              # this code block will only be executed if no data_points was found with the attributes
-              data_points[attributes] = ExponentialHistogramDataPoint.new(
-                attributes,
-                nil,                                                               # :start_time_unix_nano
-                0,                                                                 # :time_unix_nano
-                0,                                                                 # :count
-                0,                                                                 # :sum
-                @scale,                                                            # :scale
-                @zero_count,                                                       # :zero_count
-                ExponentialHistogram::Buckets.new,                                 # :positive
-                ExponentialHistogram::Buckets.new,                                 # :negative
-                0,                                                                 # :flags
-                nil,                                                               # :exemplars
-                min,                                                               # :min
-                max,                                                               # :max
-                @zero_threshold                                                    # :zero_threshold
-              )
-            end
+          def aggregation_temporality
+            @aggregation_temporality.temporality
+          end
 
-            reservoir = @exemplar_reservoir_storage[attributes]
-            unless reservoir
-              reservoir = @exemplar_reservoir.dup
-              reservoir.reset
-              @exemplar_reservoir_storage[attributes] = reservoir
-            end
+          private
 
-            if exemplar_offer
-              reservoir.offer(value: amount,
-                              timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
-                              attributes: attributes,
-                              context: OpenTelemetry::Context.current)
+          def create_new_data_point(attributes, data_points)
+            if @record_min_max
+              min = Float::INFINITY
+              max = -Float::INFINITY
             end
 
-            # Start to populate the data point (esp. the buckets)
+            data_points[attributes] = ExponentialHistogramDataPoint.new(
+              attributes,
+              nil,                                                               # :start_time_unix_nano
+              0,                                                                 # :time_unix_nano
+              0,                                                                 # :count
+              0,                                                                 # :sum
+              @scale,                                                            # :scale
+              @zero_count,                                                       # :zero_count
+              ExponentialHistogram::Buckets.new,                                 # :positive
+              ExponentialHistogram::Buckets.new,                                 # :negative
+              0,                                                                 # :flags
+              nil,                                                               # :exemplars
+              min,                                                               # :min
+              max,                                                               # :max
+              @zero_threshold                                                    # :zero_threshold
+            )
+          end
+
+          # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+          def update_histogram_data_point(hdp, attributes, amount, exemplar_offer: false)
+            reservior_update(attributes, amount, exemplar_offer)
+
             if @record_min_max
               hdp.max = amount if amount > hdp.max
               hdp.min = amount if amount < hdp.min
@@ -339,15 +343,8 @@ module OpenTelemetry
             bucket_index += buckets.counts.size if bucket_index.negative?
 
             buckets.increment_bucket(bucket_index)
-            nil
           end
-          # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
-
-          def aggregation_temporality
-            @aggregation_temporality.temporality
-          end
-
-          private
+          # rubocop:enable Metrics/CyclomaticComplexity,Metrics/MethodLength
 
           def grow_buckets(span, buckets)
             return if span < buckets.counts.size
@@ -356,6 +353,22 @@ module OpenTelemetry
             buckets.grow(span + 1, @size)
           end
 
+          def reservior_update(attributes, amount, exemplar_offer)
+            reservoir = @exemplar_reservoir_storage[attributes]
+            unless reservoir
+              reservoir = @exemplar_reservoir.dup
+              reservoir.reset
+              @exemplar_reservoir_storage[attributes] = reservoir
+            end
+
+            return unless exemplar_offer
+
+            reservoir.offer(value: amount,
+                            timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
+                            attributes: attributes,
+                            context: OpenTelemetry::Context.current)
+          end
+
           def new_mapping(scale)
             scale = validate_scale(scale)
             scale <= 0 ? ExponentialHistogram::ExponentMapping.new(scale) : ExponentialHistogram::LogarithmMapping.new(scale)

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

@@ -10,6 +10,7 @@ module OpenTelemetry
       module Aggregation
         # Contains the implementation of the LastValue aggregation
         class LastValue
+          OVERFLOW_ATTRIBUTE_SET = { 'otel.metric.overflow' => true }.freeze
           attr_reader :exemplar_reservoir
 
           # if no reservoir pass from instrument, then use this empty reservoir to avoid no method found error
@@ -33,29 +34,51 @@ module OpenTelemetry
             ndps
           end
 
-          def update(increment, attributes, data_points, exemplar_offer: false)
-            reservoir = @exemplar_reservoir_storage[attributes]
-            unless reservoir
-              reservoir = @exemplar_reservoir.dup
-              reservoir.reset
-              @exemplar_reservoir_storage[attributes] = reservoir
-            end
+          def update(increment, attributes, data_points, cardinality_limit, exemplar_offer: false)
+            # Check if we already have this attribute set
+            ndp = if data_points.key?(attributes)
+                    data_points[attributes]
+                  elsif data_points.size >= cardinality_limit - 1
+                    data_points[OVERFLOW_ATTRIBUTE_SET] || create_new_data_point(OVERFLOW_ATTRIBUTE_SET, data_points)
+                  else
+                    create_new_data_point(attributes, data_points)
+                  end
 
-            if exemplar_offer
-              reservoir.offer(value: increment,
-                              timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
-                              attributes: attributes,
-                              context: OpenTelemetry::Context.current)
-            end
+            update_number_data_point(ndp, increment, exemplar_offer: exemplar_offer)
+            nil
+          end
 
+          private
+
+          def create_new_data_point(attributes, data_points)
             data_points[attributes] = NumberDataPoint.new(
               attributes,
               nil,
               nil,
-              increment,
+              0,
               nil
             )
-            nil
+          end
+
+          def update_number_data_point(ndp, increment, exemplar_offer: false)
+            ndp.value = increment
+            reservior_update(ndp.attributes, increment, exemplar_offer)
+          end
+
+          def reservior_update(attributes, increment, exemplar_offer)
+            reservoir = @exemplar_reservoir_storage[attributes]
+            unless reservoir
+              reservoir = @exemplar_reservoir.dup
+              reservoir.reset
+              @exemplar_reservoir_storage[attributes] = reservoir
+            end
+
+            return unless exemplar_offer
+
+            reservoir.offer(value: increment,
+                            timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
+                            attributes: attributes,
+                            context: OpenTelemetry::Context.current)
           end
         end
       end

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

@@ -9,8 +9,8 @@ module OpenTelemetry
     module Metrics
       module Aggregation
         # Contains the implementation of the Sum aggregation
-        # https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#sum-aggregation
         class Sum
+          OVERFLOW_ATTRIBUTE_SET = { 'otel.metric.overflow' => true }.freeze
           attr_reader :exemplar_reservoir
 
           # if no reservior pass from instrument, then use this empty reservior to avoid no method found error
@@ -51,21 +51,48 @@ module OpenTelemetry
             end
           end
 
+          def update(increment, attributes, data_points, cardinality_limit, exemplar_offer: false)
+            return if @monotonic && increment < 0
+
+            # Check if we already have this attribute set
+            ndp = if data_points.key?(attributes)
+                    data_points[attributes]
+                  elsif data_points.size >= cardinality_limit - 1
+                    data_points[OVERFLOW_ATTRIBUTE_SET] || create_new_data_point(OVERFLOW_ATTRIBUTE_SET, data_points)
+                  else
+                    create_new_data_point(attributes, data_points)
+                  end
+
+            update_number_data_point(ndp, increment, exemplar_offer: exemplar_offer)
+            nil
+          end
+
           def monotonic?
             @monotonic
           end
 
-          def update(increment, attributes, data_points, exemplar_offer: false)
-            return if @monotonic && increment < 0
+          def aggregation_temporality
+            @aggregation_temporality.temporality
+          end
+
+          private
 
-            ndp = data_points[attributes] || data_points[attributes] = NumberDataPoint.new(
+          def create_new_data_point(attributes, data_points)
+            data_points[attributes] = NumberDataPoint.new(
               attributes,
               nil,
               nil,
               0,
               nil
             )
+          end
+
+          def update_number_data_point(ndp, increment, exemplar_offer: false)
+            reservior_update(ndp.attributes, increment, exemplar_offer)
+            ndp.value += increment
+          end
 
+          def reservior_update(attributes, increment, exemplar_offer)
             reservoir = @exemplar_reservoir_storage[attributes]
             unless reservoir
               reservoir = @exemplar_reservoir.dup
@@ -73,19 +100,12 @@ module OpenTelemetry
               @exemplar_reservoir_storage[attributes] = reservoir
             end
 
-            if exemplar_offer
-              reservoir.offer(value: increment,
-                              timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
-                              attributes: attributes,
-                              context: OpenTelemetry::Context.current)
-            end
+            return unless exemplar_offer
 
-            ndp.value += increment
-            nil
-          end
-
-          def aggregation_temporality
-            @aggregation_temporality.temporality
+            reservoir.offer(value: increment,
+                            timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
+                            attributes: attributes,
+                            context: OpenTelemetry::Context.current)
           end
         end
       end

data/lib/opentelemetry/sdk/metrics/exemplar/exemplar_reservoir.rb

@@ -32,6 +32,18 @@ module OpenTelemetry
           def collect(attributes: nil, aggregation_temporality: :delta)
             raise NotImplementedError, "#{self.class} must implement #collect"
           end
+
+          # Called after dup to reset internal state before reuse for a new attribute set.
+          # Subclasses that hold mutable per-attribute state must override this.
+          def reset; end
+
+          # Returns true if this reservoir never stores exemplars.
+          # Used to skip the exemplar filter and timestamp lookups entirely.
+          #
+          # @return [Boolean]
+          def noop?
+            false
+          end
         end
       end
     end

data/lib/opentelemetry/sdk/metrics/exemplar/noop_exemplar_reservoir.rb

@@ -15,6 +15,10 @@ module OpenTelemetry
           def collect(attributes: nil, aggregation_temporality: :delta)
             []
           end
+
+          def noop?
+            true
+          end
         end
       end
     end

data/lib/opentelemetry/sdk/metrics/export/console_metric_pull_exporter.rb

@@ -12,8 +12,8 @@ module OpenTelemetry
         #
         # Potentially useful for exploratory purposes.
         class ConsoleMetricPullExporter < MetricReader
-          def initialize
-            super
+          def initialize(aggregation_cardinality_limit: nil)
+            super(aggregation_cardinality_limit: aggregation_cardinality_limit)
             @stopped = false
           end
 

data/lib/opentelemetry/sdk/metrics/export/in_memory_metric_pull_exporter.rb

@@ -13,8 +13,8 @@ module OpenTelemetry
         class InMemoryMetricPullExporter < MetricReader
           attr_reader :metric_snapshots
 
-          def initialize
-            super
+          def initialize(aggregation_cardinality_limit: nil)
+            super(aggregation_cardinality_limit: aggregation_cardinality_limit)
             @metric_snapshots = []
             @mutex = Mutex.new
           end

data/lib/opentelemetry/sdk/metrics/export/metric_reader.rb

@@ -14,8 +14,8 @@ module OpenTelemetry
         class MetricReader
           attr_reader :metric_store
 
-          def initialize
-            @metric_store = OpenTelemetry::SDK::Metrics::State::MetricStore.new
+          def initialize(aggregation_cardinality_limit: nil)
+            @metric_store = OpenTelemetry::SDK::Metrics::State::MetricStore.new(cardinality_limit: aggregation_cardinality_limit)
           end
 
           def collect

data/lib/opentelemetry/sdk/metrics/export/periodic_metric_reader.rb

@@ -24,8 +24,9 @@ module OpenTelemetry
           # @return a new instance of the {PeriodicMetricReader}.
           def initialize(export_interval_millis: Float(ENV.fetch('OTEL_METRIC_EXPORT_INTERVAL', 60_000)),
                          export_timeout_millis: Float(ENV.fetch('OTEL_METRIC_EXPORT_TIMEOUT', 30_000)),
-                         exporter: nil)
-            super()
+                         exporter: nil,
+                         aggregation_cardinality_limit: nil)
+            super(aggregation_cardinality_limit: aggregation_cardinality_limit)
 
             @export_interval = export_interval_millis / 1000.0
             @export_timeout = export_timeout_millis / 1000.0

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

@@ -130,19 +130,17 @@ module OpenTelemetry
         end
         alias register_asynchronous_instrument register_synchronous_instrument
 
-        # spec: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#exemplar
-        # this is one way to turn on the exemplar (exemplar should be turned off by default)
         def exemplar_filter_setup
           case ENV['OTEL_METRICS_EXEMPLAR_FILTER']
           when 'always_on'
             @exemplar_filter = Exemplar::AlwaysOnExemplarFilter
-          when 'trace_based'
+          when nil, '', 'trace_based'
             @exemplar_filter = Exemplar::TraceBasedExemplarFilter
           when 'always_off'
             @exemplar_filter = Exemplar::AlwaysOffExemplarFilter
           else
-            OpenTelemetry.logger.warn("OTEL_METRICS_EXEMPLAR_FILTER #{ENV['OTEL_METRICS_EXEMPLAR_FILTER']} is not part of the provided exemplar filters. Exemplar is off.")
-            @exemplar_filter = Exemplar::AlwaysOffExemplarFilter
+            OpenTelemetry.logger.warn("OTEL_METRICS_EXEMPLAR_FILTER #{ENV['OTEL_METRICS_EXEMPLAR_FILTER']} is not part of the provided exemplar filters. Using trace_based.")
+            @exemplar_filter = Exemplar::TraceBasedExemplarFilter
           end
         end
 

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

@@ -51,17 +51,22 @@ module OpenTelemetry
 
           def invoke_callback(timeout, attributes)
             if @registered_views.empty?
+
+              resolved_cardinality_limit = @cardinality_limit || DEFAULT_CARDINALITY_LIMIT
               @mutex.synchronize do
                 @callback.each do |cb|
                   value = safe_guard_callback(cb, timeout: timeout)
+
                   if value.is_a?(Numeric)
                     exemplar_offer = should_offer_exemplar?(value, attributes)
-                    @default_aggregation.update(value, attributes, @data_points, exemplar_offer: exemplar_offer)
+                    @default_aggregation.update(value, attributes, @data_points, resolved_cardinality_limit, exemplar_offer: exemplar_offer)
                   end
                 end
               end
             else
               @registered_views.each do |view, data_points|
+                resolved_cardinality_limit = resolve_cardinality_limit(view)
+
                 @mutex.synchronize do
                   @callback.each do |cb|
                     value = safe_guard_callback(cb, timeout: timeout)
@@ -69,9 +74,10 @@ module OpenTelemetry
 
                     merged_attributes = attributes || {}
                     merged_attributes.merge!(view.attribute_keys)
+
                     if view.valid_aggregation?
                       exemplar_offer = should_offer_exemplar?(value, merged_attributes)
-                      view.aggregation.update(value, attributes, data_points, exemplar_offer: exemplar_offer)
+                      view.aggregation.update(value, attributes, data_points, resolved_cardinality_limit, exemplar_offer: exemplar_offer)
                     end
                   end
                 end

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

@@ -13,11 +13,12 @@ module OpenTelemetry
         # The MetricStore module provides SDK internal functionality that is not a part of the
         # public API.
         class MetricStore
-          def initialize
+          def initialize(cardinality_limit: nil)
             @mutex = Mutex.new
             @epoch_start_time = OpenTelemetry::Common::Utilities.time_in_nanoseconds
             @epoch_end_time = nil
             @metric_streams = []
+            @cardinality_limit = cardinality_limit
           end
 
           def collect
@@ -32,6 +33,7 @@ module OpenTelemetry
 
           def add_metric_stream(metric_stream)
             @mutex.synchronize do
+              metric_stream.cardinality_limit = @cardinality_limit
               @metric_streams = @metric_streams.dup.push(metric_stream)
               nil
             end

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

@@ -12,9 +12,13 @@ module OpenTelemetry
         #
         # The MetricStream class provides SDK internal functionality that is not a part of the
         # public API.
+        #
         # rubocop:disable Metrics/ClassLength
         class MetricStream
           attr_reader :name, :description, :unit, :instrument_kind, :instrumentation_scope, :data_points
+          attr_writer :cardinality_limit
+
+          DEFAULT_CARDINALITY_LIMIT = 2000
 
           def initialize(
             name,
@@ -51,10 +55,14 @@ module OpenTelemetry
               return metric_data if empty_data_point?
 
               if @registered_views.empty?
-                metric_data << aggregate_metric_data(start_time, end_time)
+                metric_data << aggregate_metric_data(start_time,
+                                                     end_time)
               else
                 @registered_views.each do |view, data_points|
-                  metric_data << aggregate_metric_data(start_time, end_time, aggregation: view.aggregation, data_points: data_points)
+                  metric_data << aggregate_metric_data(start_time,
+                                                       end_time,
+                                                       aggregation: view.aggregation,
+                                                       data_points: data_points)
                 end
               end
 
@@ -62,20 +70,29 @@ module OpenTelemetry
             end
           end
 
+          # view has the cardinality, pass to aggregation update
+          # to determine if aggregation have the cardinality
+          # if the aggregation does not have the cardinality, then it will be default 2000
+          # it better to move overflowed data_points during update because if do it in collect,
+          # then we need to sort the entire data_points (~ 2000) based on time, which is time-consuming
+          # view will modify the data_point that is not suitable when there are multiple views
           def update(value, attributes)
             if @registered_views.empty?
+              resolved_cardinality_limit = resolve_cardinality_limit(nil)
               @mutex.synchronize do
                 exemplar_offer = should_offer_exemplar?(value, attributes)
-                @default_aggregation.update(value, attributes, @data_points, exemplar_offer: exemplar_offer)
+                @default_aggregation.update(value, attributes, @data_points, resolved_cardinality_limit, exemplar_offer: exemplar_offer)
               end
             else
               @registered_views.each do |view, data_points|
+                resolved_cardinality_limit = resolve_cardinality_limit(view)
                 @mutex.synchronize do
                   attributes ||= {}
                   attributes.merge!(view.attribute_keys)
+
                   if view.valid_aggregation?
                     exemplar_offer = should_offer_exemplar?(value, attributes)
-                    view.aggregation.update(value, attributes, data_points, exemplar_offer: exemplar_offer)
+                    view.aggregation.update(value, attributes, data_points, resolved_cardinality_limit, exemplar_offer: exemplar_offer)
                   end
                 end
               end
@@ -119,7 +136,14 @@ module OpenTelemetry
             end
           end
 
+          def resolve_cardinality_limit(view)
+            cardinality_limit = view&.aggregation_cardinality_limit || @cardinality_limit || DEFAULT_CARDINALITY_LIMIT
+            [cardinality_limit, 0].max # if cardinality_limit is negative, then give it 0
+          end
+
           def should_offer_exemplar?(value, attributes)
+            return false if @exemplar_reservoir&.noop?
+
             context = OpenTelemetry::Context.current
             time = OpenTelemetry::Common::Utilities.time_in_nanoseconds
             @exemplar_filter&.should_sample?(value, time, attributes, context)

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

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

data/lib/opentelemetry/sdk/metrics/view/registered_view.rb

@@ -10,13 +10,14 @@ module OpenTelemetry
       module View
         # RegisteredView is an internal class used to match Views with a given {MetricStream}
         class RegisteredView
-          attr_reader :name, :aggregation, :attribute_keys, :regex
+          attr_reader :name, :aggregation, :attribute_keys, :regex, :aggregation_cardinality_limit
 
           def initialize(name, **options)
             @name = name
             @options = options
             @aggregation = options[:aggregation]
             @attribute_keys = options[:attribute_keys] || {}
+            @aggregation_cardinality_limit = options[:aggregation_cardinality_limit]
 
             generate_regex_pattern(name)
           end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-metrics-sdk
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.15.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
@@ -51,118 +51,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-- !ruby/object:Gem::Dependency
-  name: benchmark-ipsa
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: opentelemetry-test-helpers
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.3'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.65'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.65'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.17'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.17'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-- !ruby/object:Gem::Dependency
-  name: yard-doctest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.6
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.6
 description: A stats collection and distributed tracing framework
 email:
 - cncf-opentelemetry-contributors@lists.cncf.io
@@ -233,10 +121,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.13.1/file.CHANGELOG.html
-  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/metrics_sdk
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-metrics-sdk/0.15.0/file/CHANGELOG.md
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-sdk/v0.15.0/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.13.1
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-metrics-sdk/0.15.0
 rdoc_options: []
 require_paths:
 - lib
@@ -251,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A stats collection and distributed tracing framework
 test_files: []