opentelemetry-metrics-sdk 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab86f13e4c2f144a3c7e0016427f84cd3b441e73ea7a1763b87ce0d65cdfe09a
-  data.tar.gz: 0a6108e36f68f835015d2788dfda936fe32dd9dece37c89f9544cc2954598a89
+  metadata.gz: 35222d1da9eadba8252b7110b20a504a5e5b339c7ecc50403b3d6056f6b2c282
+  data.tar.gz: 23732ae05bea5b79aa6678f636e429d5958a35b96cf7dbd54846212db33d6727
 SHA512:
-  metadata.gz: 63c87d0216721b418f168d92e419006c3b552a0eb1dd2de9b804f773a7928c14505eac77691ef92782ab69a7d457c916cb162a89098eee9fa382f8ac3e27526d
-  data.tar.gz: fe4b4ad19c93bdb896d66d54c65a3500eb7e1237af6d1c992b64129ad050fe93351bb7a6e1812035db123fc81795ccb29be479c48593c0f2f45402cbac60d490
+  metadata.gz: 81abb739ad7ee5191f98d3577a2a7f65323dbb567ba137def5a0f35cf3937caf61f442e6ef3b8320d5cc2c0e6083c02a1f32e58d955d09461df1742f5df0e967
+  data.tar.gz: 83031636bdddd8317ca29fc8cf21f7bd17ca2f37cc06e16faba61b82d5286ea8e1c218de32461beb647ce8fd6a49928a0f73f26f26e0e219f19276214a744a5b

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release History: opentelemetry-metrics-sdk
 
+### 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)
+
 ### v0.13.0 / 2026-04-07
 
 * ADDED: Min Ruby Version 3.3 (#2070)

data/README.md

@@ -37,10 +37,13 @@ At this time, you should be able to:
   * `ConsoleMetricPullExporter`
   * `InMemoryMetricPullExporter` (for testing)
 * 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
+  * `TraceBasedExemplarFilter` — only measurements inside a sampled trace (default)
 
 We do not yet have support for:
 
-* Metrics Exemplars
 * `schema_url` in view configuration
 
 These lists are incomplete and are intended to give a broad description of what's available.
@@ -271,6 +274,67 @@ counter.add(1, attributes: { 'service' => 'web' })
 OpenTelemetry.meter_provider.shutdown
 ```
 
+### Exemplars
+
+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 use `TraceBasedExemplarFilter`, which records measurements only when they occur inside a sampled trace.
+
+#### Enable via environment variable
+
+```bash
+# Eligible only when the measurement occurs inside a sampled trace (recommended)
+export OTEL_METRICS_EXEMPLAR_FILTER=trace_based
+
+# Eligible for every measurement regardless of trace context
+export OTEL_METRICS_EXEMPLAR_FILTER=always_on
+
+# Disabled
+export OTEL_METRICS_EXEMPLAR_FILTER=always_off
+```
+
+#### Enable programmatically
+
+```ruby
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-sdk'
+
+ENV['OTEL_METRICS_EXPORTER'] = 'none'
+OpenTelemetry::SDK.configure
+
+exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
+OpenTelemetry.meter_provider.add_metric_reader(exporter)
+
+# Enable exemplar, by default using trace_based
+OpenTelemetry.meter_provider.enable_exemplar_filter
+```
+
+#### AlwaysOn Exemplars and Customized Exemplars
+
+```ruby
+# Use AlwaysOn Exemplars
+OpenTelemetry.meter_provider.enable_exemplar_filter(
+  exemplar_filter: OpenTelemetry::SDK::Metrics::Exemplar::AlwaysOnExemplarFilter
+)
+
+# Customized Exemplars
+class CustomExemplarFilter < OpenTelemetry::SDK::Metrics::Exemplar::ExemplarFilter
+  def self.should_sample?(value, timestamp, attributes, context)
+    # customized logic to determine should sample
+  end
+end
+
+OpenTelemetry.meter_provider.enable_exemplar_filter(
+  exemplar_filter: CustomExemplarFilter
+)
+```
+
+#### Disabling exemplars
+
+```ruby
+OpenTelemetry.meter_provider.disable_exemplar_filter
+```
+
 ### Using InMemoryMetricPullExporter for testing
 
 ```ruby

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/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/metric_stream.rb

@@ -120,6 +120,8 @@ module OpenTelemetry
           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.0'
+      VERSION = '0.14.0'
     end
   end
 end

data/lib/opentelemetry/sdk/metrics.rb

@@ -4,6 +4,9 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+require 'opentelemetry/sdk'
+require 'opentelemetry-metrics-api'
+
 module OpenTelemetry
   module SDK
     # The Metrics module contains the OpenTelemetry metrics reference
@@ -13,6 +16,7 @@ module OpenTelemetry
   end
 end
 
+require 'opentelemetry/sdk/metrics/version'
 require 'opentelemetry/sdk/metrics/exemplar'
 require 'opentelemetry/sdk/metrics/aggregation'
 require 'opentelemetry/sdk/metrics/configurator_patch'

data/lib/opentelemetry-metrics-sdk.rb

@@ -4,6 +4,4 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry/sdk'
-require 'opentelemetry-metrics-api'
 require 'opentelemetry/sdk/metrics'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-metrics-sdk
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
@@ -51,20 +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
@@ -233,10 +219,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.0/file.CHANGELOG.html
-  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/metrics_sdk
+  changelog_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-sdk/v0.14.0/file.CHANGELOG.html
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-metrics-sdk/v0.14.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.0
+  documentation_uri: https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-metrics-sdk/v0.14.0
 rdoc_options: []
 require_paths:
 - lib