opentelemetry-metrics-sdk 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b9f9ff1d02193fd4d346d99c5f581e1e83eba6018315705e1e31355e1fe75fc
-  data.tar.gz: cb95d4e5aba02bb9d257d5a0298cce4c014a2cd7297450e6c4d25437a59c6b0d
+  metadata.gz: ab86f13e4c2f144a3c7e0016427f84cd3b441e73ea7a1763b87ce0d65cdfe09a
+  data.tar.gz: 0a6108e36f68f835015d2788dfda936fe32dd9dece37c89f9544cc2954598a89
 SHA512:
-  metadata.gz: be225d34da7104c077cad530fcec9360feb31c9d930e393ac5c3e1509809b9511c2d39cbd5ebb35ff2e2d16569935c7b41d974fac8acb5b2bac1acbe2e12d8c7
-  data.tar.gz: 9590ecc610905a827b266e50f014ff653abc72bc7dee204351259218dda3144ce8d5519c9372d12ee876f82a484cf34aa71510ab096ddeacb5b44322c7896511
+  metadata.gz: 63c87d0216721b418f168d92e419006c3b552a0eb1dd2de9b804f773a7928c14505eac77691ef92782ab69a7d457c916cb162a89098eee9fa382f8ac3e27526d
+  data.tar.gz: fe4b4ad19c93bdb896d66d54c65a3500eb7e1237af6d1c992b64129ad050fe93351bb7a6e1812035db123fc81795ccb29be479c48593c0f2f45402cbac60d490

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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

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,11 @@ 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
             @previous_positive = {} # nil
             @previous_negative = {} # nil
@@ -67,6 +79,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
@@ -146,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,
@@ -157,7 +172,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
@@ -172,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,
@@ -183,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
@@ -206,7 +222,7 @@ module OpenTelemetry
 
           # 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)
+          def update(amount, attributes, data_points, exemplar_offer: false)
             # fetch or initialize the ExponentialHistogramDataPoint
             hdp = data_points.fetch(attributes) do
               if @record_min_max
@@ -233,6 +249,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
+
             # Start to populate the data point (esp. the buckets)
             if @record_min_max
               hdp.max = amount if amount > hdp.max
@@ -336,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,

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

@@ -11,9 +11,20 @@ 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
-          def initialize(aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :cumulative), monotonic: false, instrument_kind: nil)
+          attr_reader :exemplar_reservoir
+
+          # if no reservior pass from instrument, then use this empty reservior to avoid no method found error
+          DEFAULT_RESERVOIR = Metrics::Exemplar::SimpleFixedSizeExemplarReservoir.new
+          private_constant :DEFAULT_RESERVOIR
+
+          def initialize(aggregation_temporality: ENV.fetch('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE', :cumulative),
+                         monotonic: false,
+                         instrument_kind: nil,
+                         exemplar_reservoir: nil)
             @aggregation_temporality = AggregationTemporality.determine_temporality(aggregation_temporality: aggregation_temporality, instrument_kind: instrument_kind, default: :cumulative)
             @monotonic = monotonic
+            @exemplar_reservoir = exemplar_reservoir || DEFAULT_RESERVOIR
+            @exemplar_reservoir_storage = {}
           end
 
           def collect(start_time, end_time, data_points)
@@ -22,6 +33,8 @@ module OpenTelemetry
               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: @aggregation_temporality)
                 ndp
               end
               data_points.clear
@@ -31,6 +44,8 @@ module OpenTelemetry
               data_points.values.map! do |ndp|
                 ndp.start_time_unix_nano ||= start_time # Start time of a data point is from the first observation.
                 ndp.time_unix_nano = end_time
+                reservoir = @exemplar_reservoir_storage[ndp.attributes]
+                ndp.exemplars = reservoir&.collect(attributes: ndp.attributes, aggregation_temporality: @aggregation_temporality)
                 ndp.dup
               end
             end
@@ -40,7 +55,7 @@ module OpenTelemetry
             @monotonic
           end
 
-          def update(increment, attributes, data_points)
+          def update(increment, attributes, data_points, exemplar_offer: false)
             return if @monotonic && increment < 0
 
             ndp = data_points[attributes] || data_points[attributes] = NumberDataPoint.new(
@@ -51,6 +66,20 @@ module OpenTelemetry
               nil
             )
 
+            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
+
             ndp.value += increment
             nil
           end