[SDK] refactor: exemplar filters

CHANGELOG.md

@@ -185,6 +185,10 @@ Increment the:
   `trace_based` to match the specification.
   [#4328](https://github.com/open-telemetry/opentelemetry-cpp/pull/4328)
 
+* [SDK] Complete exemplar filtering: the exemplar filter(`AlwaysOn`/
+  `AlwaysOff`/`TraceBased`)
+  [#4267](https://github.com/open-telemetry/opentelemetry-cpp/pull/4267)
+
 Breaking changes:
 
 * [CONFIGURATION] SDK default component builder libraries and example
@@ -231,6 +235,18 @@ Breaking changes:
   rebuilt.
   [#4328](https://github.com/open-telemetry/opentelemetry-cpp/pull/4328)
 
+* [METRICS SDK] Remove the `SystemTimestamp` parameter from the preview
+  `ExemplarReservoir::OfferMeasurement()` overloads
+  [#4267](https://github.com/open-telemetry/opentelemetry-cpp/pull/4267)
+  * This is an incompatible API and ABI change for custom exemplar reservoirs.
+    Implementations and callers must remove the timestamp parameter.
+
+* [METRICS SDK] Breaking change to the preview metrics exemplar surface: the
+  `SyncMetricStorage`/`AsyncMetricStorage` constructors now take an
+  `ExemplarFilterType`, and `ExemplarData::Create` takes the `SpanContext`
+  by value.
+  [#4267](https://github.com/open-telemetry/opentelemetry-cpp/pull/4267)
+
 ## [1.28.0] 2026-07-16
 
 * [RELEASE] Bump main branch to 1.28.0-dev

ci/do_ci.sh

@@ -633,7 +633,7 @@ elif [[ "$1" == "bazel.tsan" ]]; then
   exit 0
 elif [[ "$1" == "bazel.valgrind" ]]; then
   bazel $BAZEL_STARTUP_OPTIONS build $BAZEL_OPTIONS_ASYNC //...
-  bazel $BAZEL_STARTUP_OPTIONS test --test_timeout=600 --run_under="/usr/bin/valgrind --leak-check=full --error-exitcode=1 --errors-for-leak-kinds=definite --suppressions=\"${SRC_DIR}/ci/valgrind-suppressions\"" $BAZEL_TEST_OPTIONS_ASYNC //...
+  bazel $BAZEL_STARTUP_OPTIONS test --test_timeout=900 --run_under="/usr/bin/valgrind --leak-check=full --error-exitcode=1 --errors-for-leak-kinds=definite --suppressions=\"${SRC_DIR}/ci/valgrind-suppressions\"" $BAZEL_TEST_OPTIONS_ASYNC //...
   exit 0
 elif [[ "$1" == "benchmark" ]]; then
   [ -z "${BENCHMARK_DIR}" ] && export BENCHMARK_DIR=$HOME/benchmark

sdk/include/opentelemetry/sdk/metrics/data/exemplar_data.h

@@ -3,8 +3,6 @@
 
 #pragma once
 
-#include <memory>
-
 #include "opentelemetry/common/timestamp.h"
 #include "opentelemetry/sdk/metrics/data/metric_data.h"
 #include "opentelemetry/sdk/metrics/state/filtered_ordered_attribute_map.h"
@@ -26,7 +24,7 @@ using MetricAttributes = opentelemetry::sdk::metrics::FilteredOrderedAttributeMa
 class ExemplarData
 {
 public:
-  static ExemplarData Create(const std::shared_ptr<opentelemetry::trace::SpanContext> &context,
+  static ExemplarData Create(const opentelemetry::trace::SpanContext &context,
                              const opentelemetry::common::SystemTimestamp &timestamp,
                              const PointDataAttributes &point_data_attr)
   {
@@ -68,10 +66,10 @@ class ExemplarData
   static PointType CreateDropPointData() { return DropPointData{}; }
 
 private:
-  ExemplarData(const std::shared_ptr<opentelemetry::trace::SpanContext> &context,
+  ExemplarData(const opentelemetry::trace::SpanContext &context,
                opentelemetry::common::SystemTimestamp timestamp,
                const PointDataAttributes &point_data_attr)
-      : context_(*context.get()), timestamp_(timestamp), point_data_attr_(point_data_attr)
+      : context_(context), timestamp_(timestamp), point_data_attr_(point_data_attr)
   {}
 
   opentelemetry::trace::SpanContext context_;

sdk/include/opentelemetry/sdk/metrics/exemplar/filter_predicate.h

@@ -0,0 +1,47 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
+
+#  include "opentelemetry/context/context.h"
+#  include "opentelemetry/sdk/metrics/exemplar/filter_type.h"
+#  include "opentelemetry/trace/context.h"
+#  include "opentelemetry/trace/span_context.h"
+#  include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace metrics
+{
+
+/**
+ * Decides whether a measurement is eligible to be offered to the exemplar reservoir.
+ *
+ *   - kAlwaysOff  : no measurement is eligible (exemplar sampling disabled).
+ *   - kAlwaysOn   : every measurement is eligible.
+ *   - kTraceBased : eligible only when recorded inside a valid, sampled span.
+ */
+inline bool ExemplarFilterEnabled(ExemplarFilterType filter_type,
+                                  const opentelemetry::context::Context &context) noexcept
+{
+  switch (filter_type)
+  {
+    case ExemplarFilterType::kAlwaysOn:
+      return true;
+    case ExemplarFilterType::kAlwaysOff:
+      return false;
+    default:  // TraceBased.
+      const opentelemetry::trace::SpanContext span_context =
+          opentelemetry::trace::GetSpanContext(context);
+      return span_context.IsValid() && span_context.IsSampled();
+  }
+}
+
+}  // namespace metrics
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE
+
+#endif  // ENABLE_METRICS_EXEMPLAR_PREVIEW

sdk/include/opentelemetry/sdk/metrics/exemplar/fixed_size_exemplar_reservoir.h

@@ -36,11 +36,9 @@ class FixedSizeExemplarReservoir : public ExemplarReservoir
 
   using ExemplarReservoir::OfferMeasurement;
 
-  void OfferMeasurement(
-      int64_t value,
-      const MetricAttributes &attributes,
-      const opentelemetry::context::Context &context,
-      const opentelemetry::common::SystemTimestamp & /* timestamp */) noexcept override
+  void OfferMeasurement(int64_t value,
+                        const MetricAttributes &attributes,
+                        const opentelemetry::context::Context &context) noexcept override
   {
     if (!reservoir_cell_selector_)
     {
@@ -54,11 +52,9 @@ class FixedSizeExemplarReservoir : public ExemplarReservoir
     }
   }
 
-  void OfferMeasurement(
-      double value,
-      const MetricAttributes &attributes,
-      const opentelemetry::context::Context &context,
-      const opentelemetry::common::SystemTimestamp & /* timestamp */) noexcept override
+  void OfferMeasurement(double value,
+                        const MetricAttributes &attributes,
+                        const opentelemetry::context::Context &context) noexcept override
   {
     if (!reservoir_cell_selector_)
     {

sdk/include/opentelemetry/sdk/metrics/exemplar/no_exemplar_reservoir.h

@@ -26,20 +26,16 @@ class NoExemplarReservoir final : public ExemplarReservoir
 {
 
 public:
-  void OfferMeasurement(
-      int64_t /* value */,
-      const MetricAttributes & /* attributes */,
-      const opentelemetry::context::Context & /* context */,
-      const opentelemetry::common::SystemTimestamp & /* timestamp */) noexcept override
+  void OfferMeasurement(int64_t /* value */,
+                        const MetricAttributes & /* attributes */,
+                        const opentelemetry::context::Context & /* context */) noexcept override
   {
     // Stores nothing
   }
 
-  void OfferMeasurement(
-      double /* value */,
-      const MetricAttributes & /* attributes */,
-      const opentelemetry::context::Context & /* context */,
-      const opentelemetry::common::SystemTimestamp & /* timestamp */) noexcept override
+  void OfferMeasurement(double /* value */,
+                        const MetricAttributes & /* attributes */,
+                        const opentelemetry::context::Context & /* context */) noexcept override
   {
     // Stores nothing.
   }

sdk/include/opentelemetry/sdk/metrics/exemplar/reservoir.h

@@ -8,7 +8,6 @@
 #  include <memory>
 #  include <vector>
 
-#  include "opentelemetry/sdk/metrics/exemplar/filter_type.h"
 #  include "opentelemetry/sdk/metrics/exemplar/reservoir_cell_selector.h"
 #  include "opentelemetry/version.h"
 
@@ -47,18 +46,14 @@ class ExemplarReservoir
   virtual ~ExemplarReservoir() = default;
 
   /** Offers a long measurement to be sampled. */
-  virtual void OfferMeasurement(
-      int64_t value,
-      const MetricAttributes &attributes,
-      const opentelemetry::context::Context &context,
-      const opentelemetry::common::SystemTimestamp &timestamp) noexcept = 0;
+  virtual void OfferMeasurement(int64_t value,
+                                const MetricAttributes &attributes,
+                                const opentelemetry::context::Context &context) noexcept = 0;
 
   /** Offers a double measurement to be sampled. */
-  virtual void OfferMeasurement(
-      double value,
-      const MetricAttributes &attributes,
-      const opentelemetry::context::Context &context,
-      const opentelemetry::common::SystemTimestamp &timestamp) noexcept = 0;
+  virtual void OfferMeasurement(double value,
+                                const MetricAttributes &attributes,
+                                const opentelemetry::context::Context &context) noexcept = 0;
 
   /**
    * Builds vector of Exemplars for exporting from the current reservoir.
@@ -73,10 +68,6 @@ class ExemplarReservoir
   virtual std::vector<std::shared_ptr<ExemplarData>> CollectAndReset(
       const MetricAttributes &pointAttributes) noexcept = 0;
 
-  static nostd::shared_ptr<ExemplarReservoir> GetSimpleFilteredExemplarReservoir(
-      ExemplarFilterType filter_type,
-      std::shared_ptr<ExemplarReservoir> reservoir);
-
   static nostd::shared_ptr<ExemplarReservoir> GetSimpleFixedSizeExemplarReservoir(
       size_t size,
       const std::shared_ptr<ReservoirCellSelector> &reservoir_cell_selector,

sdk/include/opentelemetry/sdk/metrics/exemplar/reservoir_cell.h

@@ -63,7 +63,7 @@ class ReservoirCell
    */
   std::shared_ptr<ExemplarData> GetAndResetLong(const MetricAttributes &point_attributes)
   {
-    if (!context_)
+    if (!populated_)
     {
       return nullptr;
     }
@@ -88,7 +88,7 @@ class ReservoirCell
    */
   std::shared_ptr<ExemplarData> GetAndResetDouble(const MetricAttributes &point_attributes)
   {
-    if (!context_)
+    if (!populated_)
     {
       return nullptr;
     }
@@ -109,6 +109,7 @@ class ReservoirCell
   {
     value_       = 0.0;
     record_time_ = opentelemetry::common::SystemTimestamp{};
+    populated_   = false;
   }
 
 private:
@@ -134,15 +135,13 @@ class ReservoirCell
   {
     attributes_  = attributes;
     record_time_ = opentelemetry::common::SystemTimestamp(std::chrono::system_clock::now());
-    const auto current_ctx = opentelemetry::trace::GetSpanContext(context);
-    if (current_ctx.IsValid())
-    {
-      context_.reset(new opentelemetry::trace::SpanContext{current_ctx});
-    }
+    context_     = opentelemetry::trace::GetSpanContext(context);
+    populated_   = true;
   }
 
   // Cell stores either long or double values, but must not store both
-  std::shared_ptr<opentelemetry::trace::SpanContext> context_;
+  bool populated_                            = false;
+  opentelemetry::trace::SpanContext context_ = opentelemetry::trace::SpanContext::GetInvalid();
   nostd::variant<int64_t, double> value_;
   opentelemetry::common::SystemTimestamp record_time_;
   MetricAttributes attributes_;

sdk/include/opentelemetry/sdk/metrics/exemplar/reservoir_utils.h

@@ -10,6 +10,8 @@
 #  include "opentelemetry/common/macros.h"
 #  include "opentelemetry/sdk/metrics/aggregation/aggregation_config.h"
 #  include "opentelemetry/sdk/metrics/exemplar/aligned_histogram_bucket_exemplar_reservoir.h"
+#  include "opentelemetry/sdk/metrics/exemplar/filter_type.h"
+#  include "opentelemetry/sdk/metrics/exemplar/reservoir.h"
 #  include "opentelemetry/sdk/metrics/exemplar/simple_fixed_size_exemplar_reservoir.h"
 #  include "opentelemetry/version.h"
 
@@ -48,8 +50,14 @@ static inline size_t GetSimpleFixedReservoirDefaultSize(const AggregationType ag
 static inline nostd::shared_ptr<ExemplarReservoir> GetExemplarReservoir(
     const AggregationType agg_type,
     const AggregationConfig *agg_config,
-    const InstrumentDescriptor &instrument_descriptor)
+    const InstrumentDescriptor &instrument_descriptor,
+    ExemplarFilterType filter_type)
 {
+  if (filter_type == ExemplarFilterType::kAlwaysOff)
+  {
+    return ExemplarReservoir::GetNoExemplarReservoir();
+  }
+
   if (agg_type == AggregationType::kHistogram)
   {
     const auto *histogram_agg_config = static_cast<const HistogramAggregationConfig *>(agg_config);
@@ -61,18 +69,18 @@ static inline nostd::shared_ptr<ExemplarReservoir> GetExemplarReservoir(
     //
     if (histogram_agg_config != nullptr && histogram_agg_config->boundaries_.size() > 1)
     {
-      return nostd::shared_ptr<ExemplarReservoir>(new AlignedHistogramBucketExemplarReservoir(
+      return ExemplarReservoir::GetAlignedHistogramBucketExemplarReservoir(
           histogram_agg_config->boundaries_.size(),
           AlignedHistogramBucketExemplarReservoir::GetHistogramCellSelector(
               histogram_agg_config->boundaries_),
-          GetMapAndResetCellMethod(instrument_descriptor)));
+          GetMapAndResetCellMethod(instrument_descriptor));
     }
   }
 
-  return nostd::shared_ptr<ExemplarReservoir>(new SimpleFixedSizeExemplarReservoir(
+  return ExemplarReservoir::GetSimpleFixedSizeExemplarReservoir(
       GetSimpleFixedReservoirDefaultSize(agg_type, agg_config),
       SimpleFixedSizeExemplarReservoir::GetSimpleFixedSizeCellSelector(),
-      GetMapAndResetCellMethod(instrument_descriptor)));
+      GetMapAndResetCellMethod(instrument_descriptor));
 }
 }  // namespace metrics
 }  // namespace sdk

sdk/include/opentelemetry/sdk/metrics/state/async_metric_storage.h

@@ -13,6 +13,7 @@
 #include "opentelemetry/sdk/metrics/aggregation/default_aggregation.h"
 
 #ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
+#  include "opentelemetry/sdk/metrics/exemplar/filter_predicate.h"
 #  include "opentelemetry/sdk/metrics/exemplar/filter_type.h"
 #  include "opentelemetry/sdk/metrics/exemplar/reservoir.h"
 #endif
@@ -37,7 +38,7 @@ class AsyncMetricStorage : public MetricStorage, public AsyncWritableMetricStora
   AsyncMetricStorage(const InstrumentDescriptor &instrument_descriptor,
                      const AggregationType aggregation_type,
 #ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
-                     ExemplarFilterType exempler_filter_type,
+                     ExemplarFilterType exemplar_filter_type,
                      nostd::shared_ptr<ExemplarReservoir> &&exemplar_reservoir,
 #endif
                      const AggregationConfig *aggregation_config)
@@ -49,7 +50,7 @@ class AsyncMetricStorage : public MetricStorage, public AsyncWritableMetricStora
         delta_hash_map_(
             std::make_unique<AttributesHashMap>(aggregation_config_->cardinality_limit_)),
 #ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
-        exemplar_filter_type_(exempler_filter_type),
+        exemplar_filter_type_(exemplar_filter_type),
         exemplar_reservoir_(std::move(exemplar_reservoir)),
 #endif
         temporal_metric_storage_(instrument_descriptor, aggregation_type, aggregation_config)
@@ -63,13 +64,16 @@ class AsyncMetricStorage : public MetricStorage, public AsyncWritableMetricStora
     // exporter/reader can request either for delta or cumulative value.
     // So we convert the async counter value to delta before passing it to temporal storage.
     std::lock_guard<opentelemetry::common::SpinLockMutex> guard(hashmap_lock_);
+#ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
+    const bool offer_exemplars =
+        ExemplarFilterEnabled(exemplar_filter_type_, opentelemetry::context::Context{});
+#endif
     for (auto &measurement : measurements)
     {
 #ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
-      if (exemplar_filter_type_ == ExemplarFilterType::kAlwaysOn)
+      if (offer_exemplars)
       {
-        exemplar_reservoir_->OfferMeasurement(measurement.second, {}, {},
-                                              std::chrono::system_clock::now());
+        exemplar_reservoir_->OfferMeasurement(measurement.second, measurement.first, {});
       }
 #endif