opentelemetry-metrics-sdk 0.11.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f62ae36ad71651af824a64c15bd3ffff2e32c08cd161655a013955736f97a95
-  data.tar.gz: 7c1a32329e65f2a96e5ee4c6715067cb488e2b5c88e2642d3668d2eddfbe9ce3
+  metadata.gz: ab86f13e4c2f144a3c7e0016427f84cd3b441e73ea7a1763b87ce0d65cdfe09a
+  data.tar.gz: 0a6108e36f68f835015d2788dfda936fe32dd9dece37c89f9544cc2954598a89
 SHA512:
-  metadata.gz: 8286d7d68a62f7629e05fbfc7718743b583268a24882f390e60fdcdf584a27dc7aef7d487d209caafd179966c713969334c06fb2ad230f3865686627b62a88ef
-  data.tar.gz: e43fca566da12585f81251e896175a4b627af4403aa9d146d733ebce117cadf08836d1687d01acfe024c7f9ef06a395f3122ba080201249677eb9b154b9bedd9
+  metadata.gz: 63c87d0216721b418f168d92e419006c3b552a0eb1dd2de9b804f773a7928c14505eac77691ef92782ab69a7d457c916cb162a89098eee9fa382f8ac3e27526d
+  data.tar.gz: fe4b4ad19c93bdb896d66d54c65a3500eb7e1237af6d1c992b64129ad050fe93351bb7a6e1812035db123fc81795ccb29be479c48593c0f2f45402cbac60d490

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release History: opentelemetry-metrics-sdk
 
+### v0.13.0 / 2026-04-07
+
+* ADDED: Min Ruby Version 3.3 (#2070)
+* ADDED: Add basic support for metrics exemplar (#1609)
+
+### v0.12.0 / 2026-02-11
+
+* BREAKING CHANGE: Fix the issue of mixed scale with multiple attributes
+
+* FIXED: Fix the issue of mixed scale with multiple attributes
+
 ### v0.11.2 / 2025-12-02
 
 * FIXED: Add merge logic for exponential histogram when the temporality cumulative

data/README.md

@@ -12,28 +12,36 @@ OpenTelemetry provides a single set of APIs, libraries, agents, and collector se
 
 Metrics is one of the core signals in OpenTelemetry. This package allows you to emit OpenTelemetry metrics using Ruby. It leverages an alpha implementation of the OpenTelemetry Metrics API. At the current stage, things may break and APIs may change. Use this tool with caution.
 
-This gem does not have a full implementation of the Metrics SDK specification. The work is in progress.
+This gem does not yet have a full implementation of the Metrics SDK specification. Work is in progress.
 
 At this time, you should be able to:
 
-* Create synchronous:
-  * counters
-  * up down counters
-  * histograms
-  * observable counters
-  * observable gauges
-  * observable up down counters
-* Export using a pull exporter
-* Use delta aggregation temporality
-* Periodic Exporting Metric Reader
+* Create all synchronous instruments:
+  * `Counter`
+  * `UpDownCounter`
+  * `Histogram`
+  * `Gauge`
+* Create all asynchronous (observable) instruments:
+  * `ObservableCounter`
+  * `ObservableGauge`
+  * `ObservableUpDownCounter`
+* Use all aggregation types:
+  * `ExplicitBucketHistogram` (default for histograms)
+  * `ExponentialBucketHistogram`
+  * `Sum` (default for counters and up-down counters)
+  * `LastValue` (default for gauges)
+  * `Drop`
+* Configure aggregation temporality: delta, cumulative, or low-memory
+* Customize metric collection with Views (filter by name, type, unit, aggregation, attribute keys)
+* Export metrics using pull-based exporters:
+  * `ConsoleMetricPullExporter`
+  * `InMemoryMetricPullExporter` (for testing)
+* Export metrics on a schedule using `PeriodicMetricReader` with any compatible push exporter (e.g. OTLP via `opentelemetry-exporter-otlp-metrics`)
 
 We do not yet have support for:
 
-* Asynchronous instruments
-* Cumulative aggregation temporality
-* Metrics Views
 * Metrics Exemplars
-* Push metric exporting
+* `schema_url` in view configuration
 
 These lists are incomplete and are intended to give a broad description of what's available.
 
@@ -56,31 +64,232 @@ Then, configure the SDK according to your desired handling of telemetry data, an
 require 'opentelemetry/sdk'
 require 'opentelemetry-metrics-sdk'
 
-# Configure the sdk with default export and context propagation formats.
+# Disable automatic exporter configuration so we can set one manually.
+ENV['OTEL_METRICS_EXPORTER'] = 'none'
+
+OpenTelemetry::SDK.configure
+
+# Create an exporter and register it with the meter provider.
+console_exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
+OpenTelemetry.meter_provider.add_metric_reader(console_exporter)
+
+# Create a meter and instrument.
+meter = OpenTelemetry.meter_provider.meter('my_app')
+histogram = meter.create_histogram('http.request.duration', unit: 'ms', description: 'HTTP request duration')
+
+# Record a measurement.
+histogram.record(200, attributes: { 'http.method' => 'GET', 'http.status_code' => '200' })
+
+# Flush metrics to the exporter.
+OpenTelemetry.meter_provider.metric_readers.each(&:pull)
+
+OpenTelemetry.meter_provider.shutdown
+```
+
+### All synchronous instruments
+
+```ruby
+meter = OpenTelemetry.meter_provider.meter('my_app')
+
+# Counter — monotonically increasing value
+counter = meter.create_counter('requests.total', unit: '1', description: 'Total requests')
+counter.add(1, attributes: { 'service' => 'web' })
+
+# UpDownCounter — value that can increase or decrease
+queue_depth = meter.create_up_down_counter('queue.depth', unit: '1', description: 'Items in queue')
+queue_depth.add(5)
+queue_depth.add(-3)
+
+# Histogram — distribution of measurements
+duration = meter.create_histogram('db.query.duration', unit: 'ms', description: 'Database query duration')
+duration.record(42, attributes: { 'db.operation' => 'SELECT' })
+
+# Gauge — current value at observation time
+temperature = meter.create_gauge('system.temperature', unit: 'cel', description: 'Current temperature')
+temperature.record(23.5, attributes: { 'sensor' => 'cpu' })
+```
+
+### Asynchronous (observable) instruments
+
+Asynchronous instruments collect measurements via a callback that is invoked when the metric reader collects data.
+
+```ruby
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+
+ENV['OTEL_METRICS_EXPORTER'] = 'none'
 OpenTelemetry::SDK.configure
 
-# Create an exporter. This example exports metrics to the console.
-console_metric_exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
+console_exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
+OpenTelemetry.meter_provider.add_metric_reader(console_exporter)
 
-# Add the exporter to the meter provider as a new metric reader.
-OpenTelemetry.meter_provider.add_metric_reader(console_metric_exporter)
+meter = OpenTelemetry.meter_provider.meter('my_app')
 
-# Create a meter to generate instruments.
-meter = OpenTelemetry.meter_provider.meter("SAMPLE_METER_NAME")
+# ObservableCounter — monotonically increasing, measured on demand
+cpu_callback = proc { `ps -p #{Process.pid} -o %cpu=`.strip.to_f }
+cpu_counter = meter.create_observable_counter('process.cpu.usage', callback: cpu_callback, unit: 'ms')
 
-# Create an instrument.
-histogram = meter.create_histogram('histogram', unit: 'smidgen', description: 'desscription')
+# ObservableGauge — current value, measured on demand
+mem_callback = proc { `ps -p #{Process.pid} -o %mem=`.strip.to_f }
+mem_gauge = meter.create_observable_gauge('process.memory.usage', callback: mem_callback, unit: 'percent')
 
-# Record a metric.
-histogram.record(123, attributes: {'foo' => 'bar'})
+# ObservableUpDownCounter — can increase or decrease, measured on demand
+queue_callback = proc { JobQueue.current_depth }
+queue_counter = meter.create_observable_up_down_counter('jobs.queue.depth', callback: queue_callback, unit: '1')
+
+# Trigger callbacks and export
+cpu_counter.observe
+mem_gauge.observe
+queue_counter.observe
 
-# Send the recorded metrics to the metric readers.
 OpenTelemetry.meter_provider.metric_readers.each(&:pull)
+OpenTelemetry.meter_provider.shutdown
+```
+
+### Views
+
+Views let you customize how metrics are collected and exported — changing the aggregation, filtering attribute keys, or dropping instruments entirely.
 
-# Shut down the meter provider.
+#### Change aggregation for a specific instrument
+
+```ruby
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+
+ENV['OTEL_METRICS_EXPORTER'] = 'none'
+OpenTelemetry::SDK.configure
+
+console_exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
+OpenTelemetry.meter_provider.add_metric_reader(console_exporter)
+
+# Use exponential histogram aggregation for any histogram whose name contains "exponential".
+# The view name supports * (match any characters) and ? (match one character) wildcards.
+OpenTelemetry.meter_provider.add_view(
+  '*exponential*',
+  aggregation: OpenTelemetry::SDK::Metrics::Aggregation::ExponentialBucketHistogram.new(
+    aggregation_temporality: :cumulative,
+    max_scale: 20
+  ),
+  type: :histogram,
+  unit: 'ms'
+)
+
+meter = OpenTelemetry.meter_provider.meter('my_app')
+hist = meter.create_histogram('http.exponential.latency', unit: 'ms', description: 'Latency distribution')
+(1..10).each { |i| hist.record(i ** 2, attributes: { 'env' => 'prod' }) }
+
+OpenTelemetry.meter_provider.metric_readers.each(&:pull)
 OpenTelemetry.meter_provider.shutdown
 ```
 
+#### Drop an instrument
+
+```ruby
+# Drop all metrics from a specific meter — useful for suppressing noisy or low-value instrumentation.
+OpenTelemetry.meter_provider.add_view(
+  '*',
+  aggregation: OpenTelemetry::SDK::Metrics::Aggregation::Drop.new,
+  meter_name: 'noisy_library'
+)
+```
+
+#### Restrict which attribute keys are retained
+
+```ruby
+# Only keep the 'http.method' and 'http.status_code' attributes; all others are dropped.
+OpenTelemetry.meter_provider.add_view(
+  'http.request.duration',
+  attribute_keys: { 'http.method' => nil, 'http.status_code' => nil }
+)
+```
+
+#### Full view options reference
+
+```ruby
+OpenTelemetry.meter_provider.add_view(
+  'instrument_name_pattern',   # supports * and ? wildcards; matches against instrument name
+  aggregation:   OpenTelemetry::SDK::Metrics::Aggregation::ExplicitBucketHistogram.new,
+  type:          :histogram,   # instrument kind: :counter, :up_down_counter, :histogram,
+                               #   :gauge, :observable_counter, :observable_gauge,
+                               #   :observable_up_down_counter
+  unit:          'ms',         # matches instruments with this unit
+  meter_name:    'my_meter',   # matches instruments from this meter
+  meter_version: '1.0',        # matches instruments from this meter version
+  attribute_keys: { 'env' => nil, 'region' => nil }  # allowlist of attribute keys to retain
+)
+```
+
+### Aggregation temporality
+
+Aggregation temporality controls whether exported values represent measurements since the last export (delta) or since the process started (cumulative). Configure it globally via the environment variable or per-aggregation:
+
+```ruby
+# Via environment variable (applies to all OTLP exports):
+# OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative  (or delta, or lowmemory)
+
+# Per-aggregation:
+sum_agg = OpenTelemetry::SDK::Metrics::Aggregation::Sum.new(aggregation_temporality: :delta)
+hist_agg = OpenTelemetry::SDK::Metrics::Aggregation::ExplicitBucketHistogram.new(
+  aggregation_temporality: :cumulative,
+  boundaries: [0, 10, 50, 100, 500, 1000]
+)
+
+OpenTelemetry.meter_provider.add_view('my_counter', aggregation: sum_agg, type: :counter)
+OpenTelemetry.meter_provider.add_view('my_histogram', aggregation: hist_agg, type: :histogram)
+```
+
+| Temporality preference | Counter | Observable Counter | Histogram | UpDownCounter | Observable UpDownCounter |
+| --- | --- | --- | --- | --- | --- |
+| `cumulative` | Cumulative | Cumulative | Cumulative | Cumulative | Cumulative |
+| `delta` | Delta | Delta | Delta | Cumulative | Cumulative |
+| `lowmemory` | Delta | Cumulative | Delta | Cumulative | Cumulative |
+
+### Periodic exporting with PeriodicMetricReader
+
+Use `PeriodicMetricReader` to wrap any push exporter (such as the OTLP exporter) and automatically export on a schedule:
+
+```ruby
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+require 'opentelemetry-exporter-otlp-metrics'
+
+ENV['OTEL_METRICS_EXPORTER'] = 'none'
+OpenTelemetry::SDK.configure
+
+otlp_exporter = OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new
+periodic_reader = OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(
+  export_interval_millis: 5_000,   # default: OTEL_METRIC_EXPORT_INTERVAL (60_000 ms)
+  export_timeout_millis:  1_000,   # default: OTEL_METRIC_EXPORT_TIMEOUT  (30_000 ms)
+  exporter: otlp_exporter
+)
+OpenTelemetry.meter_provider.add_metric_reader(periodic_reader)
+
+meter  = OpenTelemetry.meter_provider.meter('my_app')
+counter = meter.create_counter('requests.total', unit: '1')
+counter.add(1, attributes: { 'service' => 'web' })
+
+OpenTelemetry.meter_provider.shutdown
+```
+
+### Using InMemoryMetricPullExporter for testing
+
+```ruby
+require 'opentelemetry-metrics-sdk'
+
+exporter = OpenTelemetry::SDK::Metrics::Export::InMemoryMetricPullExporter.new
+OpenTelemetry.meter_provider.add_metric_reader(exporter)
+
+meter   = OpenTelemetry.meter_provider.meter('test_meter')
+counter = meter.create_counter('test.counter', unit: '1')
+counter.add(5, attributes: { 'env' => 'test' })
+
+exporter.pull
+snapshots = exporter.metric_snapshots  # Array of MetricData structs
+# => [#<struct name="test.counter", data_points=[...]>]
+
+exporter.reset  # clear accumulated snapshots between test cases
+```
+
 For additional examples, see the [examples on github][examples-github].
 
 ## How can I get involved?

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

@@ -10,17 +10,25 @@ module OpenTelemetry
       module Aggregation
         # Contains the implementation of the Drop aggregation
         class Drop
+          # Use noop reservoir since this is a no-op aggregation
+          DEFAULT_RESERVOIR = Metrics::Exemplar::NoopExemplarReservoir.new
+          private_constant :DEFAULT_RESERVOIR
+
+          def initialize(exemplar_reservoir: nil)
+            @exemplar_reservoir = DEFAULT_RESERVOIR
+          end
+
           def collect(start_time, end_time, data_points)
             data_points.values.map!(&:dup)
           end
 
-          def update(increment, attributes, data_points)
+          def update(increment, attributes, data_points, exemplar_offer: false)
             data_points[attributes] = NumberDataPoint.new(
               {},
               0,
               0,
               0,
-              0
+              []
             )
             nil
           end

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

@@ -11,6 +11,8 @@ 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
+          attr_reader :exemplar_reservoir
+
           DEFAULT_BOUNDARIES = [0, 5, 10, 25, 50, 75, 100, 250, 500, 1000].freeze
           private_constant :DEFAULT_BOUNDARIES
 
@@ -21,11 +23,14 @@ module OpenTelemetry
           def initialize(
             aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :cumulative),
             boundaries: DEFAULT_BOUNDARIES,
-            record_min_max: true
+            record_min_max: true,
+            exemplar_reservoir: nil
           )
             @aggregation_temporality = AggregationTemporality.determine_temporality(aggregation_temporality: aggregation_temporality, default: :cumulative)
             @boundaries = boundaries && !boundaries.empty? ? boundaries.sort : nil
             @record_min_max = record_min_max
+            @exemplar_reservoir = exemplar_reservoir || Metrics::Exemplar::AlignedHistogramBucketExemplarReservoir.new(boundaries: @boundaries)
+            @exemplar_reservoir_storage = {}
           end
 
           def collect(start_time, end_time, data_points)
@@ -34,6 +39,8 @@ module OpenTelemetry
               hdps = data_points.values.map! do |hdp|
                 hdp.start_time_unix_nano = start_time
                 hdp.time_unix_nano = end_time
+                reservoir = @exemplar_reservoir_storage[hdp.attributes]
+                hdp.exemplars = reservoir&.collect(attributes: hdp.attributes, aggregation_temporality: @aggregation_temporality)
                 hdp
               end
               data_points.clear
@@ -43,6 +50,8 @@ module OpenTelemetry
               data_points.values.map! do |hdp|
                 hdp.start_time_unix_nano ||= start_time # Start time of a data point is from the first observation.
                 hdp.time_unix_nano = end_time
+                reservoir = @exemplar_reservoir_storage[hdp.attributes]
+                hdp.exemplars = reservoir&.collect(attributes: hdp.attributes, aggregation_temporality: @aggregation_temporality)
                 hdp = hdp.dup
                 hdp.bucket_counts = hdp.bucket_counts.dup
                 hdp
@@ -50,7 +59,7 @@ module OpenTelemetry
             end
           end
 
-          def update(amount, attributes, data_points)
+          def update(amount, attributes, data_points, exemplar_offer: false)
             hdp = data_points.fetch(attributes) do
               if @record_min_max
                 min = Float::INFINITY
@@ -71,6 +80,20 @@ module OpenTelemetry
               )
             end
 
+            reservoir = @exemplar_reservoir_storage[attributes]
+            unless reservoir
+              reservoir = @exemplar_reservoir.dup
+              reservoir.reset
+              @exemplar_reservoir_storage[attributes] = reservoir
+            end
+
+            if exemplar_offer
+              reservoir.offer(value: amount,
+                              timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
+                              attributes: attributes,
+                              context: OpenTelemetry::Context.current)
+            end
+
             if @record_min_max
               hdp.max = amount if amount > hdp.max
               hdp.min = amount if amount < hdp.min

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

@@ -25,13 +25,20 @@ module OpenTelemetry
           MIN_MAX_SIZE = 2
           MAX_MAX_SIZE = 16_384
 
+          attr_reader :exemplar_reservoir
+
+          # if no reservoir pass from instrument, then use this empty reservoir to avoid no method found error
+          DEFAULT_RESERVOIR = Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new
+          private_constant :DEFAULT_RESERVOIR
+
           # 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: DEFAULT_SIZE,
             max_scale: DEFAULT_SCALE,
             record_min_max: true,
-            zero_threshold: 0
+            zero_threshold: 0,
+            exemplar_reservoir: nil
           )
             @aggregation_temporality = AggregationTemporality.determine_temporality(aggregation_temporality: aggregation_temporality, default: :delta)
             @record_min_max = record_min_max
@@ -44,6 +51,9 @@ module OpenTelemetry
             @size           = validate_size(max_size)
             @scale          = validate_scale(max_scale)
 
+            @exemplar_reservoir = exemplar_reservoir || DEFAULT_RESERVOIR
+            @exemplar_reservoir_storage = {}
+
             @mapping = new_mapping(@scale)
 
             # Previous state for cumulative aggregation
@@ -55,6 +65,10 @@ module OpenTelemetry
             @previous_count = {} # 0
             @previous_zero_count = {} # 0
             @previous_scale = {} # nil
+
+            # Cache mappings per attribute set
+            @mappings = {}
+            @previous_mappings = {}
           end
 
           # when aggregation temporality is cumulative, merge and downscale will happen.
@@ -65,9 +79,12 @@ module OpenTelemetry
               hdps = data_points.values.map! do |hdp|
                 hdp.start_time_unix_nano = start_time
                 hdp.time_unix_nano = end_time
+                reservoir = @exemplar_reservoir_storage[hdp.attributes]
+                hdp.exemplars = reservoir&.collect(attributes: hdp.attributes, aggregation_temporality: @aggregation_temporality)
                 hdp
               end
               data_points.clear
+              @mappings.clear
               hdps
             else
               # CUMULATIVE temporality - merge current data_points to previous data_points
@@ -143,6 +160,7 @@ module OpenTelemetry
                 @previous_scale[attributes] = min_scale
 
                 # Create merged data point
+                reservoir = @exemplar_reservoir_storage[attributes]
                 merged_hdp = ExponentialHistogramDataPoint.new(
                   attributes,
                   start_time,
@@ -154,13 +172,14 @@ module OpenTelemetry
                   @previous_positive[attributes].dup,
                   @previous_negative[attributes].dup,
                   0, # flags
-                  nil, # exemplars
+                  reservoir&.collect(attributes: attributes, aggregation_temporality: @aggregation_temporality), # exemplars
                   @previous_min[attributes],
                   @previous_max[attributes],
                   @zero_threshold
                 )
 
                 merged_data_points[attributes] = merged_hdp
+                @previous_mappings[attributes] = @mappings[attributes] if @mappings[attributes] # Preserve mapping for next collection
               end
               # rubocop:enable Metrics/BlockLength
 
@@ -168,6 +187,7 @@ module OpenTelemetry
               # so return last merged data points if exists
               if data_points.empty? && !@previous_positive.empty?
                 @previous_positive.each_key do |attributes|
+                  reservoir = @exemplar_reservoir_storage[attributes]
                   merged_hdp = ExponentialHistogramDataPoint.new(
                     attributes,
                     start_time,
@@ -179,7 +199,7 @@ module OpenTelemetry
                     @previous_positive[attributes].dup,
                     @previous_negative[attributes].dup,
                     0, # flags
-                    nil, # exemplars
+                    reservoir&.collect(attributes: attributes, aggregation_temporality: @aggregation_temporality), # exemplars
                     @previous_min[attributes],
                     @previous_max[attributes],
                     @zero_threshold
@@ -188,6 +208,10 @@ module OpenTelemetry
                 end
               end
 
+              # Swap current with previous mappings for next cycle
+              @mappings = @previous_mappings
+              @previous_mappings = {}
+
               # clear data_points since the data is merged into previous_* already;
               # otherwise we will have duplicated data_points in the next collect
               data_points.clear
@@ -197,8 +221,8 @@ module OpenTelemetry
           # rubocop:enable Metrics/MethodLength
 
           # this is aggregate in python; there is no merge in aggregate; but rescale happened
-          # rubocop:disable Metrics/MethodLength
-          def update(amount, attributes, data_points)
+          # 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
@@ -215,16 +239,30 @@ module OpenTelemetry
                 0,                                                                 # :sum
                 @scale,                                                            # :scale
                 @zero_count,                                                       # :zero_count
-                ExponentialHistogram::Buckets.new,  # :positive
-                ExponentialHistogram::Buckets.new,  # :negative
+                ExponentialHistogram::Buckets.new,                                 # :positive
+                ExponentialHistogram::Buckets.new,                                 # :negative
                 0,                                                                 # :flags
                 nil,                                                               # :exemplars
                 min,                                                               # :min
                 max,                                                               # :max
-                @zero_threshold # :zero_threshold)
+                @zero_threshold                                                    # :zero_threshold
               )
             end
 
+            reservoir = @exemplar_reservoir_storage[attributes]
+            unless reservoir
+              reservoir = @exemplar_reservoir.dup
+              reservoir.reset
+              @exemplar_reservoir_storage[attributes] = reservoir
+            end
+
+            if exemplar_offer
+              reservoir.offer(value: amount,
+                              timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
+                              attributes: attributes,
+                              context: OpenTelemetry::Context.current)
+            end
+
             # Start to populate the data point (esp. the buckets)
             if @record_min_max
               hdp.max = amount if amount > hdp.max
@@ -244,7 +282,15 @@ module OpenTelemetry
             buckets = amount.positive? ? hdp.positive : hdp.negative
             amount = -amount if amount.negative?
 
-            bucket_index = @mapping.map_to_index(amount)
+            # Reset scale to max_scale if transitioning from all-zeros to first non-zero value
+            if buckets.counts == [0] && hdp.scale == 0 && hdp.count > hdp.zero_count
+              hdp.scale = @scale
+              @mappings.delete(attributes) # Clear any cached mapping
+            end
+
+            # Get or create mapping for this attribute set
+            mapping = @mappings[attributes] ||= new_mapping(hdp.scale)
+            bucket_index = mapping.map_to_index(amount)
 
             rescaling_needed = false
             low = high = 0
@@ -268,14 +314,15 @@ module OpenTelemetry
             if rescaling_needed
               scale_change = get_scale_change(low, high)
               downscale(scale_change, hdp.positive, hdp.negative)
-              new_scale = @mapping.scale - scale_change
-              @mapping = new_mapping(new_scale)
-              bucket_index = @mapping.map_to_index(amount)
+              new_scale = mapping.scale - scale_change
+              mapping = new_mapping(new_scale)
+              @mappings[attributes] = mapping # Update cache
+              bucket_index = mapping.map_to_index(amount)
 
               OpenTelemetry.logger.debug "Rescaled with new scale #{new_scale} from #{low} and #{high}; bucket_index is updated to #{bucket_index}"
             end
 
-            hdp.scale = @mapping.scale
+            hdp.scale = mapping.scale
 
             # adjust buckets based on the bucket_index
             if bucket_index < buckets.index_start
@@ -294,7 +341,7 @@ module OpenTelemetry
             buckets.increment_bucket(bucket_index)
             nil
           end
-          # rubocop:enable Metrics/MethodLength
+          # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
 
           def aggregation_temporality
             @aggregation_temporality.temporality
@@ -319,9 +366,6 @@ module OpenTelemetry
           end
 
           def get_scale_change(low, high)
-            # puts "get_scale_change: low: #{low}, high: #{high}, @size: #{@size}"
-            # python code also produce 18 with 0,1048575, the high is little bit off
-            # just checked, the mapping is also ok, produce the 1048575
             change = 0
             while high - low >= @size
               high >>= 1

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

@@ -10,17 +10,44 @@ module OpenTelemetry
       module Aggregation
         # Contains the implementation of the LastValue aggregation
         class LastValue
+          attr_reader :exemplar_reservoir
+
+          # if no reservoir pass from instrument, then use this empty reservoir to avoid no method found error
+          DEFAULT_RESERVOIR = Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new
+          private_constant :DEFAULT_RESERVOIR
+
+          def initialize(exemplar_reservoir: nil)
+            @exemplar_reservoir = exemplar_reservoir || DEFAULT_RESERVOIR
+            @exemplar_reservoir_storage = {}
+          end
+
           def collect(start_time, end_time, data_points)
             ndps = data_points.values.map! do |ndp|
               ndp.start_time_unix_nano = start_time
               ndp.time_unix_nano = end_time
+              reservoir = @exemplar_reservoir_storage[ndp.attributes]
+              ndp.exemplars = reservoir&.collect(attributes: ndp.attributes, aggregation_temporality: :delta)
               ndp
             end
             data_points.clear
             ndps
           end
 
-          def update(increment, attributes, data_points)
+          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
+
+            if exemplar_offer
+              reservoir.offer(value: increment,
+                              timestamp: OpenTelemetry::Common::Utilities.time_in_nanoseconds,
+                              attributes: attributes,
+                              context: OpenTelemetry::Context.current)
+            end
+
             data_points[attributes] = NumberDataPoint.new(
               attributes,
               nil,